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

يمكنك استخدام Firebase Remote Config لتحديد المَعلمات في تطبيقك وتعديل قيمها في السحابة الإلكترونية، ما يتيح لك تعديل مظهر تطبيقك وسلوكه بدون توزيع تحديث له.

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

يرشدك هذا الدليل إلى خطوات البدء ويقدّم بعض النماذج البرمجية، ويمكن نسخها أو تنزيلها كلها من مستودع GitHub الخاص بـ firebase/quickstart-unity.

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

لاستخدام Remote Config، عليك إجراء ما يلي:

• سجِّل مشروع Unity وأعدّه لاستخدام Firebase.

  • إذا كان مشروعك في Unity يستخدم Firebase في الوقت الحالي، يعني ذلك أنّه تم تسجيله وإعداده من أجل Firebase.

  • إذا لم يكن لديك مشروع Unity، يمكنك تنزيل نموذج تطبيق.

• أضِف حزمة تطوير البرامج (SDK) Unity لبرامج Firebase (خاصةً FirebaseRemoteConfig.unitypackage) إلى مشروعك على Unity.

تجدر الإشارة إلى أنّ إضافة Firebase إلى مشروع Unity تتضمّن مهام في وحدة التحكّم Firebase وفي مشروع Unity المفتوح (على سبيل المثال، يمكنك تنزيل ملفات إعدادات Firebase من وحدة التحكّم، ثم نقلها إلى مشروع Unity).

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

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

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

(سيتم تحويل السمات غير النصية إلى نوع السمة عند استدعاء SetDefaultsAsync()).

System.Collections.Generic.Dictionary<string, object> defaults =
  new System.Collections.Generic.Dictionary<string, object>();

// These are the values that are used if we haven't fetched data from the
// server
// yet, or if we ask for values that the server doesn't have:
defaults.Add("config_test_string", "default local string");
defaults.Add("config_test_int", 1);
defaults.Add("config_test_float", 1.0);
defaults.Add("config_test_bool", false);

Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.SetDefaultsAsync(defaults)
  .ContinueWithOnMainThread(task => {

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

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

للحصول على هذه القيم، استخدِم GetValue()، مع تقديم مفتاح المَعلمة كوسيطة. يعرِض هذا الإجراء ConfigValue، التي تحتوي على سمات لتحويل القيمة إلى أنواع أساسية مختلفة.

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

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

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

لجلب قيم المَعلمات من الخلفية في Remote Config، يمكنك استدعاء الأسلوب FetchAsync(). يتم جلب أي قيم تحدّدها في الخلفية و تخزينها في كائن Remote Config.

// Start a fetch request.
// FetchAsync only fetches new data if the current data is older than the provided
// timespan.  Otherwise it assumes the data is "recent enough", and does nothing.
// By default the timespan is 12 hours, and for production apps, this is a good
// number. For this example though, it's set to a timespan of zero, so that
// changes in the console will always show up immediately.
public Task FetchDataAsync() {
  DebugLog("Fetching data...");
  System.Threading.Tasks.Task fetchTask =
  Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.FetchAsync(
      TimeSpan.Zero);
  return fetchTask.ContinueWithOnMainThread(FetchComplete);
}

في الرمز أعلاه، FetchComplete هي طريقة يتطابق توقيعها مع مَعلمات إحدى عمليات التحميل الزائد لـ ContinueWithOnMainThread().

في الرمز البرمجي النموذجي أدناه، يتم تمرير المهمة السابقة (fetchTask) إلى الطريقة FetchComplete، ما يسمح لـ FetchComplete بتحديد ما إذا كانت قد اكتملت. يستخدم الرمز Info.LastFetchStatus لتحديد ما إذا كان الانتهاء أيضًا ناجحًا. إذا كان الأمر كذلك، يتم بعد ذلك تفعيل قيم مَعلمة Remote Config باستخدام ActivateAsync().

private void FetchComplete(Task fetchTask) {
  if (!fetchTask.IsCompleted) {
    Debug.LogError("Retrieval hasn't finished.");
    return;
  }

  var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
  var info = remoteConfig.Info;
  if(info.LastFetchStatus != LastFetchStatus.Success) {
    Debug.LogError($"{nameof(FetchComplete)} was unsuccessful\n{nameof(info.LastFetchStatus)}: {info.LastFetchStatus}");
    return;
  }

  // Fetch successful. Parameter values must be activated to use.
  remoteConfig.ActivateAsync()
    .ContinueWithOnMainThread(
      task => {
        Debug.Log($"Remote data loaded and ready for use. Last fetch time {info.FetchTime}.");
    });
}

يتم تخزين القيم التي تم استرجاعها باستخدام FetchAsync() مؤقتًا محليًا عند اكتمال عملية الجلب، ولكن لا تصبح متاحة حتى استدعاء ActivateAsync(). يتيح لك هذا التأكد من عدم تطبيق القيم الجديدة في منتصف الحساب، أو في أوقات أخرى قد تسبب مشكلات أو سلوكًا غريبًا.

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

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

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

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

// Invoke the listener.
void Start()
{
  Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.OnConfigUpdateListener
    += ConfigUpdateListenerEventHandler;
}

// Handle real-time Remote Config events.
void ConfigUpdateListenerEventHandler(
   object sender, Firebase.RemoteConfig.ConfigUpdateEventArgs args) {
  if (args.Error != Firebase.RemoteConfig.RemoteConfigError.None) {
    Debug.Log(String.Format("Error occurred while listening: {0}", args.Error));
    return;
  }

  Debug.Log("Updated keys: " + string.Join(", ", args.UpdatedKeys));
  // Activate all fetched values and then display a welcome message.
  remoteConfig.ActivateAsync().ContinueWithOnMainThread(
    task => {
        DisplayWelcomeMessage();
    });
}

// Stop the listener.
void OnDestroy() {
    Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.OnConfigUpdateListener
      -= ConfigUpdateListenerEventHandler;
}

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

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

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

• إدارة نُسخ نموذج Remote Config
• استراتيجيات تحميل الإعدادات