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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

2. أضِف حزمة تطوير البرامج (SDK) لـ Remote Config JS وفعِّل 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

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

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) في تطبيقك.

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

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

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

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

• إدارة نُسخ نموذج Remote Config
• استراتيجيات تحميل الإعدادات