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

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

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

1. إذا لم يسبق لك إجراء ذلك، ثبِّت حزمة تطوير البرامج (SDK) لمنصة Firebase JavaScript وأعِد إعداد 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

gcloud auth print-access-token

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

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

الخطوة 7: الاستماع إلى التحديثات في الوقت الفعلي

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

1. في تطبيقك، استخدِم onConfigUpdate لبدء الاستماع إلى التعديلات واسترجاع أي قيم جديدة للمَعلمات تلقائيًا. نفِّذ وظيفة رد الاتصال next لتفعيل الإعدادات المعدَّلة.

     onConfigUpdate(remoteConfig, {
        next: (configUpdate) => {
           console.log("Updated keys:", configUpdate.getUpdatedKeys());
           if (configUpdate.getUpdatedKeys().has("welcome_message")) {
              activate(remoteConfig).then(() => {
              showWelcomeMessage();
              });
           }
        },
        error: (error) => {
           console.log("Config update error:", error);
        },
        complete: () => {
           console.log("Listening stopped.");
        }
     });

2. في المرة القادمة التي تنشر فيها إصدارًا جديدًا من Remote Config، ستطلب الأجهزة التي تشغّل تطبيقك وتستمع إلى التغييرات من معالج الإكمال تنفيذ عملية التحديث.

التقييد

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

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

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

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