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


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

الخطوة 1: إضافة حزمة تطوير البرامج (SDK) لمنصّة Remote Config وإعدادها

  1. ثبِّت حزمة تطوير البرامج (SDK) لـ Firebase JS وفعِّل Firebase، إذا لم يسبق لك إجراء ذلك.

  2. أضِف حزمة تطوير البرامج (SDK) لـ Remote Config JS وفعِّل Remote Config:

Web 

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);

Web 

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: ضبط الحد الأدنى للفاصل الزمني بين عمليات الجلب

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

Web

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
rc_set_minimum_fetch_time.js

Web

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
index.js

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

يمكنك ضبط قيم المَعلمات التلقائية داخل التطبيق في Remote Config العنصر، لكي يعمل تطبيقك على النحو المطلوب قبل الاتصال بواجهة Remote Config الخلفية، ولكي تتوفّر القيم التلقائية في حال عدم تحديد أي منها في الخلفية.

Web

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

Web

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

إذا سبق لك ضبط Remote Config قيم مَعلمات الخلفية، يمكنك تنزيل ملف JSON تم إنشاؤه يتضمّن جميع القيم التلقائية وإدراجه في حِزمة تطبيقك:

REST

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

وحدة تحكّم Firebase

  1. في علامة التبويب المَعلمات، افتح القائمة، ثم انقر على تنزيل القيم التلقائية.
  2. فعِّل ‎.json للويب عندما يُطلب منك ذلك، ثم انقر على تنزيل الملف.

توضِّح الأمثلة التالية طريقتَين مختلفتَين لاستيراد قيم تلقائية وضبطها في تطبيقك. يستخدم المثال الأول 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()، مع تقديم مفتاح المَعلمة كوسيطة.

Web

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

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

Web

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

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

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

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

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

  1. لجلب قيم المَعلمات من الخلفية في Remote Config، يمكنك استدعاء الأسلوب fetchConfig(). يتم جلب أي قيم تحدّدها في الخلفية و تخزينها في كائن Remote Config.
  2. لجعل قيم المَعلمات التي تم جلبها متاحة لتطبيقك، استخدِم الأسلوب activate().

في الحالات التي تريد فيها استرجاع القيم وتفعيلها في طلب واحد، استخدِم fetchAndActivate() كما هو موضّح في هذا المثال:

Web

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

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

Web

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

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

التقييد

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

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

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

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

الخطوات التالية

يمكنك استكشاف Remote Config حالات الاستخدام، والاطّلاع على بعض مستندات المفاهيم الرئيسية والاستراتيجيات المتقدّمة، بما في ذلك: