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


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

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

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

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

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

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

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

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

  • أضِف حزمة تطوير برامج Unity من Firebase (خصوصًا 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) لمنصة 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;
}

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

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

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