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


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

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

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

  2. أضِف حزمة تطوير البرامج (SDK) الخاصة بلغة JavaScript ‏(Remote Config) وأعِد ضبطها على الوضع الأوّلي (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

// The default and recommended production fetch interval for Remote Config is 12 hours
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.

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

      let customSignals = {
     "city": "Tokyo",
     "preferred_event_category": "sports"
  }

  setCustomSignals(config, customSignals);

الخطوة 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

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

التقييد

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

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

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

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

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

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