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

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

مرحله ۱: افزودن و مقداردهی اولیه کیت توسعه نرم‌افزار Remote Config

1. اگر قبلاً این کار را نکرده‌اید، کیت توسعه نرم‌افزار Firebase JS را نصب کنید و 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، و کنترل زمان دردسترس قرار گرفتن مقادیر واکشی‌شده برای برنامه شما استفاده می‌شود.

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

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

// 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، طبق انتظار رفتار کند و اگر هیچ مقداری در باطن تنظیم نشده باشد، مقادیر پیش‌فرض دردسترس باشند.

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

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

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

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

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

3. اگر از شرایط سیگنال سفارشی استفاده می‌کنید، مشخصه‌ها و مقادیر آن‌ها را تعریف کنید. مثال زیر نشان می‌دهد که چگونه شرط سیگنال سفارشی را تعریف کنید.

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

مرحله ۶: واکشی و فعال کردن مقادیر

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

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

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

محدودسازی

اگر برنامه‌ای در مدت زمان کوتاهی بیش‌ازحد واکشی کند، ممکن است تماس‌های واکشی محدود شود. در این موارد، کیت توسعه نرم‌افزار خطای FETCH_THROTTLE را نشان می‌دهد. توصیه می‌شود این خطا را بگیرید و در حالت عقب‌گرد نمایی دوباره امتحان کنید و بین درخواست‌های واکشی بعدی فواصل طولانی‌تری منتظر بمانید.

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

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

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