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

يمكنك استخدام Firebase Remote Config لتحديد مَعلمات في تطبيقك و تعديل قيمها في السحابة الإلكترونية، ما يتيح لك تغيير مظهر تطبيقك و سلوكه بدون توزيع تحديث للتطبيق. يرشدك هذا الدليل خلال خطوات البدء ويقدّم بعض نماذج الرموز البرمجية، وكلّها متاحة لاستنساخها أو تنزيلها من مستودع firebase/quickstart-js على GitHub.

الخطوة 1: إضافة حزمة تطوير البرامج (SDK) لـ Remote Config وتهيئتها

1. إذا لم يسبق لك إجراء ذلك، ثبِّت حزمة Firebase JS SDK و هيِّئ Firebase.

2. أضِف حزمة Remote Config JS SDK وهيِّئ ميزة 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، والتحكّم في وقت إتاحة القيم المسترجَعة لتطبيقك.

الخطوة 2: ضبط الحدّ الأدنى لفترة الاسترجاع

أثناء التطوير، يُنصح بضبط حدّ أدنى منخفض نسبيًا لفترة الاسترجاع. يمكنك الاطّلاع على التقييد لمزيد من المعلومات.

// 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

الخطوة 3: ضبط القيم التلقائية للمَعلمات داخل التطبيق

يمكنك ضبط القيم التلقائية للمَعلمات داخل التطبيق في الكائن 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;

الخطوة 4: الحصول على قيم المَعلمات لاستخدامها في تطبيقك

يمكنك الآن الحصول على قيم المَعلمات من كائن 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

الخطوة 5: ضبط قيم المَعلمات

باستخدام وحدة تحكّم Firebase أو واجهات برمجة التطبيقات الخلفية Remote Config ، يمكنك إنشاء قيم تلقائية جديدة من جهة الخادم تلغي القيم داخل التطبيق وفقًا للمنطق الشرطي أو استهداف المستخدم الذي تريده. يرشدك هذا القسم خلال خطوات وحدة تحكّم Firebase لإنشاء هذه القيم.

1. في وحدة تحكّم Firebase، انتقِل إلى DevOps & Engagement > الإعداد عن بُعد > صفحة المَعلمات.

2. حدِّد مَعلمات بالأسماء نفسها التي حدّدتها في تطبيقك. لكل مَعلمة، يمكنك ضبط قيمة تلقائية (ستلغي في النهاية القيمة التلقائية داخل التطبيق)، ويمكنك أيضًا ضبط قيم مشروطة. لمزيد من المعلومات، يمكنك الاطّلاع على Remote Config مَعلمات و الشروط.

3. في حال استخدام شروط الإشارات المخصّصة، حدِّد السمات وقيمها. يوضّح المثال التالي كيفية تحديد شرط إشارة مخصّصة.

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

الخطوة 6: استرجاع القيم وتنشيطها

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

بما أنّ قيم المَعلمات المعدَّلة هذه تؤثر في سلوك تطبيقك ومظهره، عليك تفعيل القيم المسترجَعة في وقت يضمن تجربة سلسة للمستخدم، مثل المرة التالية التي يفتح فيها المستخدم تطبيقك. يمكنك الاطّلاع على استراتيجيات تحميل "الإعداد عن بُعد" لمزيد من المعلومات والأمثلة.

الخطوة 7: الاستماع إلى التعديلات في الوقت الفعلي

بعد استرجاع قيم المَعلمات، يمكنك استخدام ميزة "الإعداد عن بُعد" في الوقت الفعلي للاستماع إلى التعديلات من واجهة برمجة التطبيقات الخلفية لميزة "الإعداد عن بُعد".Remote ConfigRemote 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، ستستدعي الأجهزة التي تشغّل تطبيقك وتستمع إلى التغييرات معالج الإكمال.

التقييد

إذا استرجَع أحد التطبيقات البيانات عدة مرات في فترة قصيرة، قد يتم تقييد طلبات الاسترجاع. في مثل هذه الحالات، تعرض حزمة تطوير البرامج (SDK) الخطأ FETCH_THROTTLE. يُنصح برصد هذا الخطأ وإعادة المحاولة في وضع الرقود الأسي الثنائي، مع الانتظار لفترات أطول بين طلبات الاسترجاع اللاحقة.

أثناء تطوير التطبيق، قد تحتاج إلى إعادة تحميل ذاكرة التخزين المؤقت بشكل متكرر جدًا (عدة مرات في الساعة) للسماح لك بالتكرار السريع أثناء تطوير تطبيقك واختباره. لاستيعاب التكرار السريع في مشروع يضم عددًا كبيرًا من المطوّرين، يمكنك إضافة سمة مؤقتًا بحدّ أدنى منخفض لفترة الاسترجاع (Settings.minimumFetchIntervalMillis) في تطبيقك.

إنّ فترة الاسترجاع التلقائية والمقترَحة للإنتاج في Remote Config هي 12 ساعة، ما يعني أنّه لن يتم استرجاع الإعدادات من واجهة برمجة التطبيقات الخلفية أكثر من مرة خلال فترة 12 ساعة، بغض النظر عن عدد طلبات الاسترجاع التي يتم إجراؤها فعليًا. يتم تحديد الحدّ الأدنى لفترة الاسترجاع بالترتيب التالي:

1. المَعلمة في Settings.minimumFetchIntervalMillis
2. القيمة التلقائية البالغة 12 ساعة