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


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

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

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

  2. إضافة حزمة تطوير برامج JavaScript لميزة "الإعداد عن بُعد" وإعداد ميزة "الإعداد عن بُعد":

واجهة برمجة التطبيقات Web modular API 

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

يُستخدم هذا العنصر لتخزين قيم المَعلمات التلقائية داخل التطبيق واسترجاع قيم المَعلمات المعدّلة من خلفية "الإعداد عن بُعد" والتحكّم في وقت توفُّر القيم التي تم جلبها لتطبيقك.

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

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

واجهة برمجة التطبيقات Web modular API

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
rc_set_minimum_fetch_time.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
index.js

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

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

واجهة برمجة التطبيقات Web modular API

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

واجهة برمجة التطبيقات لمساحة الاسم على الويب

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

إذا سبق لك ضبط قيم مَعلمات الواجهة الخلفية لميزة "الإعداد عن بُعد"، يمكنك تنزيل ملف 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: الحصول على قيم المَعلمات لاستخدامها في تطبيقك

يمكنك الآن الحصول على قيم المَعلمات من كائن "الإعداد عن بُعد". إذا ضبطت القيم لاحقًا في الخلفية، وأحضرتها، ثم فعّلتها، ستكون هذه القيم متاحة لتطبيقك.للحصول على هذه القيم، يمكنك طلب إجراء getValue() مع تقديم مفتاح المَعلمة كوسيطة.

واجهة برمجة التطبيقات Web modular API

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 أو واجهات برمجة تطبيقات الخلفية للإعداد عن بُعد، يمكنك إنشاء قيم تلقائية جديدة من جهة الخادم تلغي القيم داخل التطبيق وفقًا للمنطق الشرطي أو استهداف المستخدم المطلوب. يرشدك هذا القسم خلال خطوات وحدة تحكم Firebase لإنشاء هذه القيم.

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

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

  1. لاسترجاع قيم المَعلمات من الواجهة الخلفية لميزة "الإعداد عن بُعد"، عليك استدعاء الطريقة fetchConfig(). يتم استرجاع أي قيم ضبطتها في الخلفية وتخزينها مؤقتًا في كائن "الإعداد عن بُعد".
  2. لإتاحة قيم المَعلمات التي تم استرجاعها لتطبيقك، استدعِ الطريقة activate().

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

واجهة برمجة التطبيقات Web modular API

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

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

واجهة برمجة التطبيقات لمساحة الاسم على الويب

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

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

تقييد

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

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

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

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

الخطوات اللاحقة

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