شروع به کار با «پیکربندی از راه دور» در Unity

می‌توانید از Firebase Remote Config برای تعریف پارامترها در برنامه‌تان و به‌روزرسانی مقادیر آن‌ها در فضای ابری استفاده کنید، که به شما امکان می‌دهد ظاهر و رفتار برنامه‌تان را بدون توزیع به‌روزرسانی برنامه تغییر دهید.

از کتابخانه Remote Config برای ذخیره مقادیر پیش‌فرض پارامتر درون‌برنامه‌ای، واکشی مقادیر پارامتر به‌روزشده از زیرینه Remote Config، و کنترل زمان دردسترس قرار گرفتن مقادیر واکشی‌شده برای برنامه استفاده می‌شود. برای کسب اطلاعات بیشتر، استراتژی‌های بار کردن «پیکربندی از دور» را ببینید.

این راهنما شما را در مراحل شروع به کار راهنمایی می‌کند و مقداری کد نمونه ارائه می‌دهد که همه آن‌ها برای شبیه‌سازی یا بارگیری از مخزن GitHub firebase/quickstart-unity دردسترس است.

مرحله ۱: Remote Config را به برنامه‌تان اضافه کنید

پیش‌از اینکه بتوانید از Remote Config استفاده کنید، باید:

• پروژه Unity خود را ثبت کنید و آن را برای استفاده از Firebase پیکربندی کنید.

  • اگر پروژه Unity شما ازقبل از Firebase استفاده می‌کند، پس ازقبل برای Firebase ثبت و پیکربندی شده است.

  • اگر پروژه Unity ندارید، می‌توانید برنامه نمونه‌ای را بارگیری کنید.

• Firebase Unity SDK (به‌طور دقیق، FirebaseRemoteConfig.unitypackage) را به پروژه Unity خود اضافه کنید.

توجه داشته باشید که افزودن Firebase به پروژه Unity شما شامل وظایفی در هر دو Firebase کنسول و پروژه Unity باز شما است (برای مثال، فایل‌های پیکربندی Firebase را از کنسول بارگیری می‌کنید، سپس آن‌ها را به پروژه Unity خود منتقل می‌کنید).

مرحله ۲: تنظیم مقادیر پارامتر پیش‌فرض درون‌برنامه‌ای

می‌توانید مقادیر پارامتر پیش‌فرض درون‌برنامه‌ای را در Remote Config object تنظیم کنید تا برنامه‌تان قبل‌از اتصال به زیرینه 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 => {

مرحله ۳: دریافت مقادیر پارامتر برای استفاده در برنامه

اکنون می‌توانید مقادیر پارامتر را از شیء Remote Config دریافت کنید. اگر مقادیر را در زیرینه Remote Config تنظیم کنید، آن‌ها را واکشی کنید، و سپس آن‌ها را فعال کنید، آن مقادیر برای برنامه شما دردسترس هستند. درغیراین‌صورت، مقادیر پارامتر درون‌برنامه‌ای را که بااستفاده از SetDefaultsAsync() پیکربندی شده است دریافت می‌کنید.

برای دریافت این مقادیر، از GetValue(), استفاده کنید و کلید پارامتر را به‌عنوان آرگومان ارائه دهید. این تابع ConfigValue را برمی‌گرداند که خصوصیاتی برای تبدیل مقدار به انواع پایه دارد.

مرحله ۴: تنظیم مقادیر پارامتر

1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از دور بروید.

2. پارامترهایی با همان نام پارامترهایی که در برنامه‌تان تعریف کرده‌اید تعریف کنید. برای هر پارامتر، می‌توانید مقدار پیش‌فرضی (که درنهایت مقدار پیش‌فرض درون برنامه را ملغی می‌کند) و مقادیر شرطی تنظیم کنید. برای کسب اطلاعات بیشتر، Remote Config پارامترها و شرایط را ببینید.

مرحله ۵: واکشی و فعال کردن مقادیر (درصورت نیاز)

برای واکشی مقادیر پارامتر از زیرینه 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() فراخوانی نشود دردسترس قرار نمی‌گیرند. این کار به شما امکان می‌دهد مطمئن شوید که مقادیر جدید در حین محاسبه یا در زمان‌های دیگری که ممکن است باعث بروز مشکل یا رفتار عجیب شود، اعمال نمی‌شوند.

مرحله ۶: به‌روزرسانی‌ها را به‌طور هم‌زمان بشنوید

پس‌از واکشی مقادیر پارامتر، می‌توانید از Remote Config هم‌زمان برای شنیدن به‌روزرسانی‌های Remote Config زیرینه استفاده کنید. وقتی به‌روزرسانی دردسترس باشد، Remote Config سیگنال‌های هم‌زمان به دستگاه‌های متصل ارسال می‌شود و پس‌از انتشار نسخه جدید Remote Config، تغییرات به‌طور خودکار واکشی می‌شود.

به‌روزرسانی‌های هم‌زمان توسط Firebase Unity SDK v11.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 منتشر می‌کنید، دستگاه‌هایی که برنامه شما را اجرا می‌کنند و منتظر تغییرات هستند، کنترل‌کننده تکمیل را فراخوانی خواهند کرد.