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

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

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

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

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

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

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

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

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

• أضِف حزمة SDK لنظام التشغيل Firebase Unity (على وجه التحديد، FirebaseRemoteConfig.unitypackage) إلى مشروعك على Unity.

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

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

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

للقيام بذلك، قم بإنشاء قاموس سلسلة، وتعبئته بأزواج المفتاح/القيمة وتمثل الإعدادات الافتراضية التي تريد إضافتها. إذا قمت بالفعل بتهيئة لـ 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.

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