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

يمكنك استخدام ميزة 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، انتقِل إلى 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().

في الرمز النموذجي التالي، يتم تمرير الطريقة FetchComplete إلى المهمة السابقة (fetchTask)، ما يسمح للطريقة 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، ستستدعي الأجهزة التي تُشغّل تطبيقك وتستمع إلى التغييرات معالج الإكمال.