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

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

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

1. ثبِّت حزمة تطوير البرامج (SDK) لمنصّة Firebase JS واحرِص على إعداد Firebase إذا لم يسبق لك ذلك.

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

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

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

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
rc_set_minimum_fetch_time.js

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
index.js

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

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

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

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

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

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

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() كما هو موضّح في المثال التالي:

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 ساعة.

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

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

• إدارة إصدارات نماذج "الإعداد عن بُعد"
• استراتيجيات تحميل الإعدادات