بدء استخدام ميزة "الإعداد عن بُعد" على أجهزة iOS

يمكنك استخدام ميزة Firebase Remote Config لتحديد المَعلمات في تطبيقك وتعديل قيمها في السحابة الإلكترونية، ما يتيح لك تعديل مظهر تطبيقك وطريقة عمله بدون توزيع تحديث للتطبيق. يقدّم لك هذا الدليل الخطوات اللازمة للبدء وبعض الرموز النموذجية، وكلها متاحة للاستنساخ أو التنزيل من مستودع firebase/quickstart-ios على GitHub.

الخطوة 1: إضافة Remote Config إلى تطبيقك

1. أضِف Firebase إلى مشروع Apple الخاص بك، في حال لم يسبق لك إجراء ذلك.

2. بالنسبة إلى Remote Config، يجب استخدام Google Analytics من أجل استهداف نسخ التطبيق الافتراضية لخصائص المستخدمين وشرائح الجمهور وفقًا للشروط. تأكَّد من تفعيل Google Analytics في مشروعك.

3. أنشئ كائن Remote Config الفردي، كما هو موضّح في المثال التالي:

   Swift

   let remoteConfig = RemoteConfig.remoteConfig()
   let settings = RemoteConfigSettings()
   settings.minimumFetchInterval = 0
   RemoteConfig.remoteConfig().configSettings = settings
   MigratedSnippets.swift

   Objective-C

   FIRRemoteConfig *remoteConfig = [FIRRemoteConfig remoteConfig];
   FIRRemoteConfigSettings *remoteConfigSettings = [[FIRRemoteConfigSettings alloc] init];
   remoteConfigSettings.minimumFetchInterval = 0;
   remoteConfig.configSettings = remoteConfigSettings;
   ObjCMigratedSnippets.m

يُستخدَم هذا العنصر لتخزين قيم المَعلمات التلقائية داخل التطبيق، واسترجاع قيم المَعلمات المعدَّلة من الخلفية في Remote Config، والتحكّم في وقت إتاحة القيم التي تم استرجاعها لتطبيقك.

أثناء عملية التطوير، ننصحك بضبط حد أدنى منخفض نسبيًا للفاصل الزمني بين عمليات الجلب. يمكنك الاطّلاع على التقييد لمزيد من المعلومات.

الخطوة 2: ضبط قيم المَعلمات التلقائية داخل التطبيق

يمكنك ضبط قيم المَعلمات التلقائية داخل التطبيق في كائن Remote Config، لكي يعمل تطبيقك على النحو المطلوب قبل اتصاله بالخلفية Remote Config، ولكي تتوفّر القيم التلقائية في حال عدم ضبط أي قيم في الخلفية.

1. حدِّد مجموعة من أسماء المَعلمات وقيم المَعلمات التلقائية باستخدام عنصر NSDictionary أو ملف plist.

   إذا سبق لك ضبط قيم مَعلمات الخلفية في Remote Config، يمكنك تنزيل ملف plist الذي تم إنشاؤه والذي يتضمّن جميع القيم التلقائية وحفظه في مشروع Xcode.

   REST

   curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=PLIST -o RemoteConfigDefaults.plist
   

   يمكنك إنشاء رمز حامل مميز من خلال تنفيذ الأمر التالي باستخدام Google Cloud CLI أو Cloud Shell:

   gcloud auth print-access-token
   

   هذا الرمز المميّز قصير الأجل، لذا قد تحتاج إلى إعادة إنشائه إذا ظهر لك خطأ في المصادقة.

   وحدة تحكّم Firebase

   1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

   2. افتح more_vert القائمة ، واختَر تنزيل القيم التلقائية.

   3. عندما يُطلب منك ذلك، فعِّل ملف plist.لنظام التشغيل iOS، ثم انقر على تنزيل الملف.

2. أضِف هذه القيم إلى العنصر Remote Config باستخدام setDefaults:. يضبط المثال التالي القيم التلقائية داخل التطبيق من ملف plist:

   Swift

   RemoteConfig.remoteConfig().setDefaults(fromPlist: "RemoteConfigDefaults")
   MigratedSnippets.swift

   Objective-C

   [remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
   ObjCMigratedSnippets.m

الخطوة 3: الحصول على قيم المَعلمات لاستخدامها في تطبيقك

يمكنك الآن الحصول على قيم المَعلمات من الكائن Remote Config. إذا ضبطت لاحقًا قيمًا في الخلفية Remote Config، وجلبتها، ثم فعّلتها، ستكون هذه القيم متاحة لتطبيقك. وإلا، ستحصل على قيم المَعلمات داخل التطبيق التي تم ضبطها باستخدام setDefaults:. للحصول على هذه القيم، يمكنك استدعاء الطريقة configValueForKey: مع تقديم مفتاح المَعلمة كوسيطة.

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a parameter value using configValueForKey
let welcomeMessageValue = remoteConfig.configValue(forKey: "welcome_message")
let welcomeMessage = welcomeMessageValue.stringValue

let featureFlagValue = remoteConfig.configValue(forKey: "new_feature_flag")
let isFeatureEnabled = featureFlagValue.boolValue

يمكن الوصول إلى هذه القيم بطريقة أكثر سهولة ووضوحًا في Swift من خلال تدوين الرمز المنخفض في Swift:

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a string parameter value
let welcomeMessage = remoteConfig["welcome_message"].stringValue

// Retrieve a boolean parameter value
let isFeatureEnabled = remoteConfig["new_feature_flag"].boolValue

// Retrieve a number parameter value
let maxItemCount = remoteConfig["max_items"].numberValue.intValue

استخدام Codable لضبط الإعدادات بطريقة تمنع أخطاء الكتابة

بالنسبة إلى الإعدادات الأكثر تعقيدًا، يمكنك استخدام بروتوكول Codable في Swift لفك ترميز البيانات المنظَّمة من Remote Config. يوفّر ذلك إدارة عملية الإعداد مع منع أخطاء الكتابة، كما يسهّل التعامل مع العناصر المعقّدة.

// Define a Codable struct for your configuration
struct AppFeatureConfig: Codable {
  let isNewFeatureEnabled: Bool
  let maxUploadSize: Int
  let themeColors: [String: String]
}

// Fetch and decode the configuration
func configureAppFeatures() {
  let remoteConfig = RemoteConfig.remoteConfig()
  remoteConfig.fetchAndActivate { status, error in
    guard error == nil else { return }

    do {
      let featureConfig = try remoteConfig["app_feature_config"].decoded(asType: AppFeatureConfig.self)
      configureApp(with: featureConfig)
    } catch {
      // Handle decoding errors
      print("Failed to decode configuration: \(error)")
    }
  }
}

تتيح لك هذه الطريقة ما يلي:

• تحديد هياكل الإعدادات المعقّدة
• تحليل إعدادات JSON تلقائيًا
• تأكَّد من منع أخطاء الكتابة عند الوصول إلى قيم Remote Config.
• يجب تقديم رمز برمجي واضح وسهل القراءة للتعامل مع نماذج Remote Config المنظَّمة.

استخدام "مغلِّفات السمات" (Property Wrappers) لضبط الإعدادات التعريفية في SwiftUI

تُعدّ "أغلفة الخصائص" ميزة فعّالة في Swift تتيح لك إضافة سلوك مخصّص إلى تعريفات الخصائص. في SwiftUI، تُستخدم برامج تضمين الخصائص لإدارة الحالة والارتباطات وسلوكيات الخصائص الأخرى. لمزيد من المعلومات، يُرجى الاطّلاع على دليل لغة Swift.

struct ContentView: View {
  @RemoteConfigProperty(key: "cardColor", fallback: "#f05138")
  var cardColor

  var body: some View {
    VStack {
      Text("Dynamic Configuration")
        .background(Color(hex: cardColor))
    }
    .onAppear {
      RemoteConfig.remoteConfig().fetchAndActivate()
    }
  }
}

استخدِم برنامج تضمين السمة @RemoteConfigProperty عندما تريد طريقة تعريفية للوصول إلى قيم Remote Config في SwiftUI، مع دعم مدمج للقيم التلقائية وإدارة عملية الإعداد المبسّطة.

الخطوة 4: ضبط قيم المَعلمات

باستخدام وحدة تحكّم Firebase أو واجهات برمجة التطبيقات الخلفية لميزة Remote Config، يمكنك إنشاء قيم تلقائية جديدة في الخلفية تلغي القيم داخل التطبيق وفقًا للمنطق الشرطي أو استهداف المستخدمين المطلوب. يستعرض هذا القسم خطوات وحدة تحكم Firebase لإنشاء هذه القيم.

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

2. حدِّد مَعلمات بالأسماء نفسها التي حدّدتها في تطبيقك. ويمكنك ضبط قيمة تلقائية لكل مَعلمة (والتي ستلغي في النهاية القيمة التلقائية داخل التطبيق)، كما يمكنك ضبط قيم شرطية. لمزيد من المعلومات، يُرجى الاطّلاع على مَعلمات وشروط "Remote Config".

3. في حال استخدام شروط الإشارات المخصّصة، حدِّد السمات وقيمها. توضّح الأمثلة التالية كيفية تحديد شرط إشارة مخصّص.

   Swift

       Task {
           let customSignals: [String: CustomSignalValue?] = [
           "city": .string("Tokyo"),
           "preferred_event_category": .string("sports")
         ]
   
         do {
           try await remoteConfig.setCustomSignals(customSignals)
           print("Custom signals set successfully!")
           } catch {
               print("Error setting custom signals: \(error)")
           }
     }

   Objective-C

       dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         NSDictionary *customSignals = @{
           @"city": @"Tokyo",
           @"preferred_event_category": @"sports"
         };
   
         [self.remoteConfig setCustomSignals:customSignals withCompletion:^(NSError * _Nullable error) {
             if (error) {
                 NSLog(@"Error setting custom signals: %@", error);
             } else {
                 NSLog(@"Custom signals set successfully!");
             }
       }];
   });

الخطوة 5: استرجاع القيم وتفعيلها

لجلب قيم المَعلمات من Remote Config، يمكنك استدعاء الطريقة fetchWithCompletionHandler: أو fetchWithExpirationDuration:completionHandler:. يتم جلب أي قيم تضبطها في الخلفية وتخزينها مؤقتًا في الكائن Remote Config.

في الحالات التي تريد فيها جلب القيم وتفعيلها في طلب واحد، استخدِم fetchAndActivateWithCompletionHandler:.

يجلب هذا المثال القيم من الخلفية Remote Config (وليس القيم المخزّنة مؤقتًا) ويستدعي activateWithCompletionHandler: لإتاحتها للتطبيق:

remoteConfig.fetch { (status, error) -> Void in
  if status == .success {
    print("Config fetched!")
    remoteConfig.activate { changed, error in
      // ...
    }
  } else {
    print("Config not fetched")
    print("Error: \(error?.localizedDescription ?? "No error available.")")
  }
}
MigratedSnippets.swift

[remoteConfig fetchWithCompletionHandler:^(FIRRemoteConfigFetchStatus status, NSError *error) {
  if (status == FIRRemoteConfigFetchStatusSuccess) {
    NSLog(@"Config fetched!");
    [remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Activate error: %@", error.localizedDescription);
      } else {
        dispatch_async(dispatch_get_main_queue(), ^{
          // update UI
        });
      }
    }];
  } else {
    NSLog(@"Config not fetched");
    NSLog(@"Error %@", error.localizedDescription);
  }
}];
ObjCMigratedSnippets.m

بما أنّ قيم المَعلمات المعدَّلة هذه تؤثر في سلوك تطبيقك ومظهره، عليك تفعيل القيم التي تم جلبها في وقت يضمن تجربة سلسة للمستخدم، مثل المرة التالية التي يفتح فيها المستخدم تطبيقك. لمزيد من المعلومات والأمثلة، يُرجى الاطّلاع على استراتيجيات تحميل ميزة "الإعداد عن بُعد".

الخطوة 6: الاستماع إلى التعديلات في الوقت الفعلي

بعد جلب قيم المَعلمات، يمكنك استخدام ميزة Remote Config في الوقت الفعلي للاستماع إلى التعديلات من الخلفية في Remote Config. يرسل Remote Config إشارات في الوقت الفعلي إلى الأجهزة المتصلة عند توفّر تحديثات، ويجلب التغييرات تلقائيًا بعد نشر إصدار جديد من Remote Config.

تتوفّر التعديلات في الوقت الفعلي من خلال حزمة تطوير البرامج (SDK) لـ "Firebase" على منصات "Apple" بالإصدار 10.7.0 والإصدارات الأحدث.

1. في تطبيقك، يمكنك استدعاء addOnConfigUpdateListener لبدء الاستماع إلى التعديلات وجلب أي قيم مَعلمات جديدة أو معدَّلة تلقائيًا. يستمع المثال التالي إلى التحديثات، وعند استدعاء activateWithCompletionHandler، يستخدم القيم التي تم جلبها حديثًا لعرض رسالة ترحيب محدّثة.

   Swift

   remoteConfig.addOnConfigUpdateListener { configUpdate, error in
       guard let configUpdate, error == nil else {
         print("Error listening for config updates: \(error)")
       }
   
       print("Updated keys: \(configUpdate.updatedKeys)")
   
       self.remoteConfig.activate { changed, error in
         guard error == nil else { return self.displayError(error) }
         DispatchQueue.main.async {
           self.displayWelcome()
         }
       }
     }
     

   Objective-C

   __weak __typeof__(self) weakSelf = self;
     [self.remoteConfig addOnConfigUpdateListener:^(FIRRemoteConfigUpdate * _Nonnull configUpdate, NSError * _Nullable error) {
       if (error != nil) {
         NSLog(@"Error listening for config updates %@", error.localizedDescription);
       } else {
         NSLog(@"Updated keys: %@", configUpdate.updatedKeys);
   
         __typeof__(self) strongSelf = weakSelf;
         [strongSelf.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
           if (error != nil) {
             NSLog(@"Activate error %@", error.localizedDescription);
           }
   
           dispatch_async(dispatch_get_main_queue(), ^{
             [strongSelf displayWelcome];
           });
         }];
       }
     }];
     

2. في المرة التالية التي تنشر فيها إصدارًا جديدًا من Remote Config، ستستدعي الأجهزة التي تشغّل تطبيقك وتستمع إلى التغييرات معالج الإكمال.

التقييد

إذا جلب أحد التطبيقات عددًا كبيرًا جدًا من المرات في فترة زمنية قصيرة، يتم تقييد طلبات الجلب وتعرض حزمة تطوير البرامج (SDK) FIRRemoteConfigFetchStatusThrottled. قبل الإصدار 6.3.0 من حزمة تطوير البرامج (SDK)، كان الحدّ الأقصى هو 5 طلبات جلب في فترة زمنية مدتها 60 دقيقة (تتضمّن الإصدارات الأحدث حدودًا أكثر تساهلاً).

أثناء تطوير التطبيق، قد تحتاج إلى جلب البيانات بشكل متكرر لتحديث ذاكرة التخزين المؤقت بشكل متكرر جدًا (عدة مرات في الساعة) للسماح لك بالتكرار السريع أثناء تطوير وتجربة تطبيقك. تتجاوز تحديثات الإعداد عن بُعد في الوقت الفعلي تلقائيًا ذاكرة التخزين المؤقت عند تحديث الإعداد على الخادم. لاستيعاب التكرار السريع في مشروع يضم العديد من المطوّرين، يمكنك إضافة السمة FIRRemoteConfigSettings مؤقتًا مع فاصل زمني منخفض للحد الأدنى للجلب (MinimumFetchInterval) في تطبيقك.

إنّ الفاصل الزمني التلقائي والمقترَح لجلب الإعدادات في مرحلة الإنتاج في Remote Config هو 12 ساعة، ما يعني أنّه لن يتم جلب الإعدادات من الخلفية أكثر من مرة واحدة خلال فترة 12 ساعة، بغض النظر عن عدد طلبات الجلب التي يتم إجراؤها فعليًا. على وجه التحديد، يتم تحديد الحد الأدنى للفاصل الزمني للجلب بالترتيب التالي:

1. المَعلمة في fetch(long)
2. المَعلمة في FIRRemoteConfigSettings.MinimumFetchInterval
3. القيمة التلقائية هي 12 ساعة