بدء استخدام ميزة "الإعداد عن بُعد في Firebase"


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

الخطوة 1: إضافة ميزة "الإعداد عن بُعد" إلى تطبيقك

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

  2. بالنسبة إلى ميزة "الإعداد عن بُعد"، يجب استخدام "إحصاءات Google" من أجل الاستهداف المشروط لمثيلات التطبيق لخصائص المستخدمين وشرائح الجمهور. تأكّد من تفعيل "إحصاءات Google" في مشروعك.

  3. أنشئ عنصر ميزة "الإعداد عن بُعد" في نمط "سينغلتون"، كما هو موضّح في المثال التالي:

    Swift

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

    Objective-C

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

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

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

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

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

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

    إذا سبق لك ضبط قيم مَعلمات الواجهة الخلفية لميزة "الإعداد عن بُعد"، يمكنك تنزيل ملف 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

    وحدة تحكُّم Firebase

    1. في علامة التبويب المَعلمات، افتح القائمة، واختَر تنزيل القيم التلقائية.

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

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

    Swift

    remoteConfig.setDefaults(fromPlist: "RemoteConfigDefaults")
    ViewController.swift

    Objective-C

    [self.remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
    ViewController.m

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

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

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

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

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

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

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

بالنسبة إلى الحالات التي تريد فيها استرجاع القيم وتفعيلها في مكالمة واحدة، استخدِم fetchAndActivateWithCompletionHandler:.

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

Swift

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

Objective-C

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

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

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

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

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

  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. في المرة التالية التي تنشر فيها إصدارًا جديدًا من ميزة "الإعداد عن بُعد"، إنّ الأجهزة التي تشغّل تطبيقك وتستمع إلى التغييرات ستدعي معالج الإكمال.

تقييد

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

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

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

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

الخطوات اللاحقة

يمكنك استكشاف حالات استخدام ميزة "الإعداد عن بُعد" والاطّلاع على بعض المفاهيم الرئيسية والاستراتيجيات المتقدّمة، بما في ذلك: