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


عند استخدام نماذج الطلبات من الخادم، يمكنك تعديل القيم داخل نموذج معيّن بدون طرح إصدار جديد من تطبيقك. ومع ذلك، بما أنّ أي تغييرات في النموذج ستُستخدم على الفور تقريبًا في الطلبات الواردة من تطبيقك، عليك توخّي الحذر بشأن إجراء تغييرات قد تؤدي إلى تعطيل تطبيقك أو حدوث تغييرات غير متوقّعة في السلوك.

لذا، إذا كنت تريد إجراء تغييرات أكثر أهمية أو طرح التغييرات تدريجيًا، لن تحتاج إلى تغيير النموذج المستخدَم في رمز الإنتاج.

بدلاً من ذلك، ننصحك باستخدام Firebase Remote Config للتحكّم في قيمة معرّف النموذج المستخدَم في الطلب المُرسَل إلى النموذج.

تتيح لك ميزة Firebase Remote Config تعديل قيم المَعلمات في تطبيقك (مثل رقم تعريف النموذج) بشكل ديناميكي وعن بُعد من خلال وحدة تحكّم Firebase، بدون الحاجة إلى طرح إصدار جديد من تطبيقك. وتتضمّن الميزة أيضًا إمكانات وعمليات تكامل مبسطة لطرح التغييرات وإجراء اختبارات A/B.

يوضّح هذا الدليل كيفية تنفيذ Remote Config في تطبيقك، وتحديدًا كيفية التحكّم في معرّف النموذج المستخدَم في تطبيقك.

الخطوة 1: ضبط قيمة المَعلمة في وحدة تحكّم Firebase

أنشئ نموذج Remote Config للعميل واضبط template_id مَعلمة وقيمتها لاسترجاعها واستخدامها في التطبيق.

  1. افتح مشروعك على Firebase في Firebase. بعد ذلك، من قائمة التنقّل، وسِّع تنفيذ (Run) وانقر على Remote Config.

  2. تأكَّد من اختيار العميل من أداة اختيار العميل/الخادم في أعلى الصفحة.

  3. ابدأ نموذج عميل بالنقر على إنشاء إعداد (أو إضافة مَعلمة إذا سبق لك استخدام نماذج العملاء).

  4. حدِّد المَعلمة template_id:

    اسم المَعلمة الوصف النوع القيمة التلقائية
    template_id رقم تعريف النموذج سلسلة my-first-template-v1-0-0

  5. بعد إضافة هذه المَعلمة، انقر على نشر التغييرات. إذا لم يكن هذا Remote Config نموذجًا جديدًا، راجِع التغييرات وانقر على نشر التغييرات مرة أخرى.

الخطوة 2: إضافة Remote Config وتهيئة إعداداته في تطبيقك

أضِف مكتبة Remote Config واضبط إعداداتها في تطبيقك.Remote Config

Swift

كجزء من عملية Firebase AI Logic الإعداد، سبق لك إضافة حزمة تطوير البرامج (SDK) لمنصة Firebase إلى تطبيقك، ولكن عليك أيضًا إضافة Remote Config.

  1. في Xcode، بعد فتح المشروع، انتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة (File > Add Package Dependencies).

  2. اختَر firebase-ios-sdk، ثم انقر على إضافة حزمة.

  3. من "مستكشف المشروع" (Project navigator)، اختَر تطبيقك > الأهداف (Targets) > تطبيقك.

  4. من علامة التبويب الإعدادات العامة، انتقِل إلى الأطر والمكتبات والمحتوى المضمّن.

  5. انقر على + واختَر FirebaseRemoteConfig، ثم انقر على إضافة.

  6. أضِف عملية استيراد FirebaseRemoteConfig إلى الرمز:

    import FirebaseRemoteConfig

  7. داخل الفئة المناسبة لتطبيقك، عليك إعداد Firebase وإضافة Remote Config إلى منطق التطبيق الرئيسي.

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

    let remoteConfig = RemoteConfig.remoteConfig()
let settings = RemoteConfigSettings()
settings.minimumFetchInterval = 3600
remoteConfig.configSettings = settings

Kotlin

  1. أضِف الاعتمادية Remote Config إلى ملف Gradle الخاص بالوحدة (على مستوى التطبيق) (عادةً app/build.gradle.kts أو app/build.gradle):

    dependencies {
    implementation(platform("com.google.firebase:firebase-bom:34.5.0"))
    implementation("com.google.firebase:firebase-ai")
    implementation("com.google.firebase:firebase-config")
    // ... other dependencies
}

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

    val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)

Java

  1. أضِف الاعتمادية Remote Config إلى ملف Gradle الخاص بالوحدة (على مستوى التطبيق) (عادةً app/build.gradle.kts أو app/build.gradle):

    dependencies {
    implementation(platform("com.google.firebase:firebase-bom:34.5.0"))
    implementation("com.google.firebase:firebase-ai")
    implementation("com.google.firebase:firebase-config")
    // ... other dependencies
}

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

    FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
    .setMinimumFetchIntervalInSeconds(3600)
    .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);

Web

  1. افتح الرمز في محرِّر نصوص واستورِد Remote Config:

    import { getRemoteConfig } from 'firebase/remote-config';

  2. داخل وظيفتك الأساسية وبعد تهيئة تطبيق Firebase لحزمة تطوير البرامج (SDK) Firebase AI Logic، يمكنك تهيئة Remote Config:

      // Initialize Remote Config and get a reference to the service
  const remoteConfig = getRemoteConfig(app);

  3. ضبط الحدّ الأدنى للفاصل الزمني بين عمليات الجلب:

    remoteConfig.settings.minimumFetchIntervalMillis = 3600000;

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

عليك ضبط قيم المَعلمات التلقائية داخل التطبيق في العنصر Remote Config. يضمن ذلك أن يتصرف تطبيقك على النحو المتوقّع حتى إذا لم يتمكّن من جلب القيم من خدمة Remote Config.

Swift

  1. في وحدة تحكّم Firebase، افتح Remote Config.

  2. في علامة التبويب المَعلمات، افتح القائمة، ثم انقر على تنزيل القيم التلقائية.

  3. عندما يُطلب منك ذلك، فعِّل ملف ‎.plist لنظام التشغيل iOS، ثم انقر على تنزيل الملف.

  4. احفظ الملف في دليل التطبيق.

  5. في Xcode، انقر بزر الماوس الأيمن على تطبيقك واختَر إضافة ملفات

  6. اختَر remote_config_defaults.plist، ثمّ انقر على إضافة.

  7. عدِّل رمز تطبيقك للإشارة إلى ملف الإعدادات التلقائية:

    // Set default values for Remote Config parameters.
remoteConfig.setDefaults(fromPlist: "remote_config_defaults")

Kotlin

  1. من وحدة تحكّم Firebase، افتح Remote Config.

  2. في علامة التبويب المَعلمات، افتح القائمة، ثم اختَر تنزيل القيم التلقائية.

  3. عندما يُطلب منك ذلك، فعِّل ملف ‎.xml لنظام التشغيل Android، ثم انقر على تنزيل الملف.

  4. احفظ الملف في دليل موارد XML الخاص بتطبيقك.

  5. عدِّل ملف النشاط الرئيسي لإضافة القيم التلقائية بعد configSettings التي أضفتها سابقًا:

    // Set default values for Remote Config parameters.
remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

Java

  1. في وحدة تحكّم Firebase، افتح Remote Config.

  2. في علامة التبويب المَعلمات، افتح القائمة، ثم اختَر تنزيل القيم التلقائية.

  3. عندما يُطلب منك ذلك، فعِّل ملف ‎.xml لنظام التشغيل Android، ثم انقر على تنزيل الملف.

  4. احفظ الملف في دليل موارد XML الخاص بتطبيقك.

  5. عدِّل ملف النشاط الرئيسي لإضافة القيم التلقائية بعد configSettings التي أضفتها سابقًا:

    // Set default values for Remote Config parameters.
mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

Web

يمكنك ضبط القيمة التلقائية لاسم النموذج مباشرةً في الرمز:

// Set default values for Remote Config parameters.
remoteConfig.defaultConfig = {
  template_id: 'my-first-template-v1-0-0',
};

الخطوة 4: استرجاع القيمة وتفعيلها

بعد ضبط القيمة التلقائية لاسم الطراز، أضِف ما يلي لجلب القيم وتفعيلها.

Swift 

// Fetch and activate Remote Config values
remoteConfig.fetchAndActivate { status, error in
  if let error = error {
    print("Error fetching Remote Config: \(error.localizedDescription)")
  }
}

يجب أن يؤدي ذلك إلى تعديل الكائن Remote Config كلما تم نشر نموذج Remote Config جديد.

Kotlin 

// Fetch and activate Remote Config values
remoteConfig.fetchAndActivate()
      .addOnCompleteListener(this) { task ->
          if (task.isSuccessful) {
              val updated = task.result
              Log.d(TAG, "Remote Config values fetched and activated: $updated")
          } else {
              Log.e(TAG, "Error fetching Remote Config", task.exception)
          }
      }

Java 

  // Fetch and activate Remote Config values
  mFirebaseRemoteConfig.fetchAndActivate()
    .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
        @Override
        public void onComplete(@NonNull Task<Boolean> task) {
            if (task.isSuccessful()) {
                boolean updated = task.getResult();
                Log.d(TAG, "Config params updated: " + updated);
            } else {
                Log.e(TAG, "Error fetching Remote Config", task.exception)
            }
          }
    });

Web

  1. أضِف getValue وfetchAndActivate إلى عمليات الاستيراد:

    import { getValue, fetchAndActivate } from 'firebase/remote-config';

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

    // Fetch and activate Remote Config.
try {
  await fetchAndActivate(remoteConfig);
} catch(err) {
  console.error('Remote Config fetch failed', err);
}

console.log('Remote Config fetched.');

// Assign Remote Config values.
const templateID = getValue(remoteConfig, 'template_id').asString();

الخطوة 5: إضافة أداة معالجة Remote Config في الوقت الفعلي

أضِف برنامج معالجة Remote Config في الوقت الفعلي إلى تطبيقك لضمان نقل التغييرات التي تجريها على نموذج Remote Config إلى العميل فور تعديلها.

يعدّل الرمز التالي الكائن Remote Config كلما تغيّرت قيمة إحدى المَعلمات.

Swift 

// Add real-time Remote Config
remoteConfig.addOnConfigUpdateListener { configUpdate, error in
  guard let configUpdate = configUpdate, error == nil else {
    print("Error listening for config updates: \(error?.localizedDescription ?? "No error available")")
    return
  }

  print("Updated keys: \(configUpdate.updatedKeys)")
  remoteConfig.activate { changed, error in
    guard error == nil else {
      print("Error activating config: \(error?.localizedDescription ?? "No error available")")
      return
    }
    print("Activated config successfully")
  }
}

Kotlin

يمكنك أيضًا ضبط إجراء داخل عملية التفعيل addOnCompleteListener، وذلك بشكل اختياري:

      // Add a real-time Remote Config listener
      remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener {
          override fun onUpdate(configUpdate : ConfigUpdate) {
              Log.d(ContentValues.TAG, "Updated keys: " + configUpdate.updatedKeys);
              remoteConfig.activate().addOnCompleteListener {
                  // Optionally, add an action to perform on update here.
              }
          }

          override fun onError(error : FirebaseRemoteConfigException) {
              Log.w(ContentValues.TAG, "Config update error with code: " + error.code, error)
          }
      }

Java

يمكنك أيضًا ضبط إجراء داخل عملية التفعيل addOnCompleteListener، وذلك بشكل اختياري:

  // Add a real-time Remote Config listener
  remoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() {
      @Override
      public void onUpdate(ConfigUpdate configUpdate) {
          Log.d(ContentValues.TAG, "Updated keys: " + configUpdate.getUpdatedKeys());
                remoteConfig.activate().addOnCompleteListener(new OnCompleteListener<Boolean>() {
                  @Override
                  public void onComplete(@NonNull Task<Boolean> task) {
                      // Optionally, add an action to perform on update here.
                  }
              });
          }

      @Override
      public void onError(FirebaseRemoteConfigException error) {
          Log.w(ContentValues.TAG, "Config update error with code: " + error.getCode(), error);
      }
  });

Web

لا تتوافق أدوات معالجة Remote Config في الوقت الفعلي مع تطبيقات الويب.

الخطوة 6: تعديل طلبات Gemini API لاستخدام قيمة Remote Config

انقر على موفّر Gemini API لعرض المحتوى والرمز الخاصين بموفّر الخدمة على هذه الصفحة.

بعد إعداد Remote Config بالكامل، عدِّل الرمز البرمجي لاستبدال القيم المضمّنة بقيم مصدرها Remote Config.

Swift 

import FirebaseAI

let templateID = remoteConfig.configValue(forKey: "template_id").stringValue
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()
let customerName = "Jane"

// When making the `generateContent` call, source the template ID value from Remote Config
let response = try await model.generateContent(
  templateID: templateID,
  // Provide the values for any input variables required by your template.
  inputs: [
    "customerName": customerName
  ]
)

// ...

Kotlin 

// ...

val model = Firebase.ai().templateGenerativeModel()
val customerName = "Jane"

// When making the `generateContent` call, source the template ID value from Remote Config
val response = model.generateContent(
  remoteConfig.getString("template_id"),
  // Provide the values for any input variables required by your template.
  mapOf(
    "customerName" to customerName
  )
)

val text = response.text
println(text)

Java 

// ...

TemplateGenerativeModel ai = FirebaseAI.getInstance()
    .templateGenerativeModel(null /* Request Options */);

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(ai);
String customerName = "Jane";

// When making the `generateContent` call, source the template ID value from Remote Config
Future<GenerateContentResponse> response = model.generateContent(
    remoteConfig.getString("template_id"),
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)

);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

// ...

Web 

// ...

const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

const model = getTemplateGenerativeModel(ai);
const templateID = getValue(remoteConfig, 'template_id').asString();
const customerName = 'Jane';

// When making the `generateContent` call, source the template ID value from Remote Config
const result = await model.generateContent(
  templateID,
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

// ...

الخطوة 7: تشغيل التطبيق

أنشئ التطبيق وشغِّله وتأكَّد من أنّه يعمل. أجرِ تغييرات على إعداداتك من صفحة Remote Config في وحدة تحكّم Firebase، وانشر التغييرات، وتأكَّد من النتيجة.

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