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

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

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

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

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

قبل أن تتمكّن من استخدام الإعداد عن بُعد، عليك إجراء ما يلي:

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

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

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

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

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

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

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

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

(سيتم تحويل المواقع الإلكترونية التي لا تتضمّن سلسلة إلى نوع الموقع عند استدعاء السمة 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: الحصول على قيم المَعلمات لاستخدامها في تطبيقك

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

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

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

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

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

لاسترجاع قيم المَعلمات من الواجهة الخلفية لميزة "الإعداد عن بُعد"، عليك طلب الإجراء FetchAsync(). ويتم استرجاع أي قيم تضبطها في الخلفية وتخزينها مؤقتًا في كائن "الإعداد عن بُعد".

// 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().

في نموذج الرمز أدناه، اجتازت الطريقة FetchComplete المهمة السابقة (fetchTask)، ما يتيح لـ FetchComplete تحديد ما إذا كانت المهمة قد اكتملت أم لا. يستخدم الرمز Info.LastFetchStatus لتحديد ما إذا كانت النهاية أيضًا ناجحة. إذا كان الأمر كذلك، سيتم تفعيل قيم مَعلمات "الإعداد عن بُعد" باستخدام 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: الاستماع إلى آخر الأخبار في الوقت الفعلي

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

تتوفّر التحديثات في الوقت الفعلي من خلال الإصدار 11.0.0 أو الإصدارات الأحدث من حزمة تطوير البرامج (SDK) Unity SDK لـ Firebase لنظامي التشغيل 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;
}

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

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

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

• إدارة إصدارات نماذج "الإعداد عن بُعد"
• استراتيجيات تحميل الإعدادات