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

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

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

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

2. أضِف حزمة تطوير البرامج (SDK) لـ JavaScript في Remote Config وابدأ إعداد 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، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

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

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

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