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

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

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

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

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

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

• تسجيل مشروع Unity الخاص بك وإعداده لاستخدام Firebase

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

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

• إضافة حزمة Firebase Unity SDK (وتحديدًا FirebaseRemoteConfig.unitypackage) إلى مشروع Unity

يُرجى العِلم أنّ إضافة Firebase إلى مشروع Unity تتضمّن مهامًا في كلّ من الـ Firebase console ومشروع 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، انتقِل إلى DevOps & Engagement > الإعداد عن بُعد.

2. حدِّد مَعلمات بالأسماء نفسها التي حدّدتها في تطبيقك. لكل مَعلمة، يمكنك ضبط قيمة تلقائية (ستلغي في النهاية القيمة التلقائية داخل التطبيق) وقيم مشروطة. لمعرفة المزيد، يُرجى الاطّلاع على مقالة 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 ConfigRemote Config تُرسِل إشارات في الوقت الفعلي Remote Config إلى الأجهزة المتصلة عند توفّر التحديثات، وتسترجع التغييرات تلقائيًا بعد نشر إصدار جديد Remote Config.

تتوافق التحديثات في الوقت الفعلي مع الإصدار 11.0.0 من Firebase Unity SDK والإصدارات الأحدث لمنصتَي 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، ستستدعي الأجهزة التي تشغّل تطبيقك وتستمع إلى التغييرات معالج الإكمال.