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

انتخاب پلاتفرم: iOS+ Android وب Flutter Unity C++


می‌توانید از 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 تنظیم کنید تا برنامه‌تان قبل‌از اتصال به باطن 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 استفاده کنید. وقتی به‌روزرسانی‌ها دردسترس باشند، Real-time Remote Config به دستگاه‌های متصل سیگنال می‌دهد و پس‌از انتشار نسخه جدید Remote Config، تغییرات را به‌طور خودکار واکشی می‌کند.

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