با Firebase Remote Config شروع کنید

شما می‌توانید از Firebase Remote Config برای تعریف پارامترها در برنامه خود و به‌روزرسانی مقادیر آنها در فضای ابری استفاده کنید، که به شما امکان می‌دهد ظاهر و رفتار برنامه خود را بدون توزیع به‌روزرسانی برنامه تغییر دهید. این راهنما مراحل شروع کار را برای شما شرح می‌دهد و چند نمونه کد ارائه می‌دهد که همه آنها برای کپی کردن یا دانلود از مخزن گیت‌هاب firebase/quickstart-js در دسترس هستند.

مرحله ۱: اضافه کردن و مقداردهی اولیه Remote Config SDK

1. اگر هنوز این کار را نکرده‌اید، Firebase JS SDK را نصب کنید و Firebase را مقداردهی اولیه کنید .

2. کیت توسعه نرم‌افزاری Remote Config JS را اضافه کنید و Remote Config را مقداردهی اولیه کنید:

import { initializeApp } from "firebase/app";
import { getRemoteConfig } from "firebase/remote-config";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);


// Initialize Remote Config and get a reference to the service
const remoteConfig = getRemoteConfig(app);

import firebase from "firebase/compat/app";
import "firebase/compat/remote-config";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);


// Initialize Remote Config and get a reference to the service
const remoteConfig = firebase.remoteConfig();

این شیء برای ذخیره مقادیر پیش‌فرض پارامترها در برنامه، دریافت مقادیر به‌روزرسانی‌شده پارامترها از Remote Config backend و کنترل زمان در دسترس قرار گرفتن مقادیر دریافتی برای برنامه شما استفاده می‌شود.

مرحله ۲: حداقل فاصله زمانی دریافت را تنظیم کنید

در طول توسعه، توصیه می‌شود حداقل فاصله زمانی واکشی نسبتاً کمی تنظیم شود. برای اطلاعات بیشتر به بخش تنظیم فشار (Throttling) مراجعه کنید.

// The default and recommended production fetch interval for Remote Config is 12 hours
remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
rc_set_minimum_fetch_time.js

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
index.js

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

شما می‌توانید مقادیر پیش‌فرض پارامترهای درون‌برنامه‌ای را در شیء Remote Config تنظیم کنید، به طوری که برنامه شما قبل از اتصال به Remote Config backend طبق انتظار رفتار کند، و اگر هیچ مقداری در backend تنظیم نشده باشد، مقادیر پیش‌فرض در دسترس باشند.

remoteConfig.defaultConfig = {
  "welcome_message": "Welcome"
};
rc_set_default_values.js

remoteConfig.defaultConfig = {
  "welcome_message": "Welcome"
};
index.js

اگر قبلاً مقادیر پارامترهای backend مربوط به Remote Config را پیکربندی کرده‌اید، می‌توانید یک فایل JSON تولید شده که شامل تمام مقادیر پیش‌فرض است را دانلود کرده و آن را در بسته برنامه خود قرار دهید:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=JSON -o remote_config_defaults.json

gcloud auth print-access-token

مثال‌های زیر دو روش مختلف برای وارد کردن و تنظیم مقادیر پیش‌فرض در برنامه شما را نشان می‌دهند. مثال اول از fetch استفاده می‌کند که یک درخواست HTTP به فایل پیش‌فرض موجود در بسته برنامه شما ارسال می‌کند:

  const rcDefaultsFile = await fetch('remote_config_defaults.json');
  const rcDefaultsJson = await rcDefaultsFile.json();
  remoteConfig.defaultConfig = rcDefaultsJson;
  

مثال بعدی از require استفاده می‌کند که مقادیر را در زمان ساخت در برنامه شما کامپایل می‌کند:

  let rcDefaults = require('./remote_config_defaults.json');
  remoteConfig.defaultConfig = rcDefaults;

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

اکنون می‌توانید مقادیر پارامترها را از شیء Remote Config دریافت کنید. اگر بعداً مقادیر را در backend تنظیم کنید، آنها را دریافت کنید و سپس فعال کنید، آن مقادیر در برنامه شما در دسترس خواهند بود. برای دریافت این مقادیر، متد getValue() را فراخوانی کنید و کلید پارامتر را به عنوان آرگومان ارائه دهید.

import { getValue } from "firebase/remote-config";

const val = getValue(remoteConfig, "welcome_messsage");
rc_get_values.js

const val = remoteConfig.getValue("welcome_messsage");
index.js

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

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

1. در کنسول Firebase ، پروژه خود را باز کنید.
2. برای مشاهده داشبورد Remote Config ، از منو Remote Config را انتخاب کنید.
3. پارامترهایی را با همان نام پارامترهایی که در برنامه خود تعریف کرده‌اید، تعریف کنید. برای هر پارامتر، می‌توانید یک مقدار پیش‌فرض تنظیم کنید (که در نهایت مقدار پیش‌فرض درون برنامه را لغو می‌کند) و همچنین می‌توانید مقادیر شرطی تنظیم کنید. برای کسب اطلاعات بیشتر، به بخش پارامترها و شرایط Remote Config مراجعه کنید.

4. اگر از شرایط سیگنال سفارشی استفاده می‌کنید، ویژگی‌ها و مقادیر آنها را تعریف کنید. مثال زیر نحوه تعریف یک شرایط سیگنال سفارشی را نشان می‌دهد.

     let customSignals = {
        "city": "Tokyo",
        "preferred_event_category": "sports"
     }
   
     setCustomSignals(config, customSignals);

مرحله ۶: دریافت و فعال‌سازی مقادیر

1. برای دریافت مقادیر پارامترها از Remote Config backend، متد fetchConfig() را فراخوانی کنید. هر مقداری که در backend تنظیم کنید، در شیء Remote Config دریافت و ذخیره می‌شود.
2. برای اینکه مقادیر پارامترهای واکشی شده در دسترس برنامه شما قرار گیرند، متد activate() فراخوانی کنید.

برای مواردی که می‌خواهید مقادیر را در یک فراخوانی دریافت و فعال کنید، از fetchAndActivate() همانطور که در این مثال نشان داده شده است استفاده کنید:

import { fetchAndActivate } from "firebase/remote-config";

fetchAndActivate(remoteConfig)
  .then(() => {
    // ...
  })
  .catch((err) => {
    // ...
  });
rc_fetch_config_callback.js

remoteConfig.fetchAndActivate()
  .then(() => {
    // ...
  })
  .catch((err) => {
    // ...
  });
index.js

از آنجا که این مقادیر پارامتر به‌روزرسانی‌شده بر رفتار و ظاهر برنامه شما تأثیر می‌گذارند، باید مقادیر واکشی‌شده را در زمانی فعال کنید که تجربه‌ای روان را برای کاربر شما تضمین کند، مانند دفعه بعدی که کاربر برنامه شما را باز می‌کند. برای اطلاعات و مثال‌های بیشتر، به استراتژی‌های بارگذاری Remote Config مراجعه کنید.

مرحله ۷: به روزرسانی‌ها را به صورت آنی دریافت کنید

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

1. در برنامه خود، از onConfigUpdate برای شروع گوش دادن به به‌روزرسانی‌ها و دریافت خودکار مقادیر پارامتر جدید استفاده کنید. فراخوانی next را برای فعال کردن پیکربندی به‌روزرسانی‌شده پیاده‌سازی کنید.

     onConfigUpdate(remoteConfig, {
        next: (configUpdate) => {
           console.log("Updated keys:", configUpdate.getUpdatedKeys());
           if (configUpdate.getUpdatedKeys().has("welcome_message")) {
              activate(remoteConfig).then(() => {
              showWelcomeMessage();
              });
           }
        },
        error: (error) => {
           console.log("Config update error:", error);
        },
        complete: () => {
           console.log("Listening stopped.");
        }
     });

2. دفعه‌ی بعدی که نسخه‌ی جدیدی از Remote Config خود را منتشر می‌کنید، دستگاه‌هایی که برنامه‌ی شما را اجرا می‌کنند و منتظر تغییرات هستند، completion handler را فراخوانی می‌کنند.

تنظیم سرعت

اگر یک برنامه در یک بازه زمانی کوتاه، تعداد زیادی داده را دریافت کند، ممکن است فراخوانی‌های دریافت داده با مشکل مواجه شوند. در چنین مواردی، SDK خطای FETCH_THROTTLE را نمایش می‌دهد. توصیه می‌شود این خطا را دریافت کرده و در حالت بازگشت نمایی (exponential backoff mode) دوباره امتحان کنید و بین درخواست‌های دریافت داده بعدی، فواصل زمانی طولانی‌تری را منتظر بمانید.

در طول توسعه برنامه، ممکن است بخواهید حافظه پنهان را مرتباً (چندین بار در ساعت) به‌روزرسانی کنید تا بتوانید هنگام توسعه و آزمایش برنامه خود، به سرعت آن را تکرار کنید. برای تطبیق با تکرار سریع در پروژه‌ای با توسعه‌دهندگان متعدد، می‌توانید به طور موقت یک ویژگی با حداقل فاصله واکشی کم ( Settings.minimumFetchIntervalMillis ) در برنامه خود اضافه کنید.

فاصله زمانی پیش‌فرض و توصیه‌شده برای واکشی Remote Config عملیاتی، ۱۲ ساعت است، به این معنی که پیکربندی‌ها بیش از یک بار در یک بازه زمانی ۱۲ ساعته از بک‌اند واکشی نمی‌شوند، صرف نظر از اینکه در واقع چند فراخوانی واکشی انجام شده است. به طور خاص، حداقل فاصله زمانی واکشی به ترتیب زیر تعیین می‌شود:

1. پارامتر موجود در Settings.minimumFetchIntervalMillis .
2. مقدار پیش‌فرض ۱۲ ساعت.

مراحل بعدی

If you haven't already, explore the Remote Config use cases , and take a look at some of the key concepts and advanced strategies documentation, including:

• Manage Remote Config template versions
• Config loading strategies