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


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

الخطوة 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

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

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

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

تقييد

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

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

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

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

الخطوات التالية

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