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


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

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

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

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

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

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

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

  1. في وحدة تحكّم Firebase، انتقِل إلى DevOps & Engagement > الإعداد عن بُعد.

  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، ثم انقر على إضافة حزمة (Add package).

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

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

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

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

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

    هنا، ستُدرج Remote Config وRemote Config real-time listener كعمليات استيراد ليتمكّن التطبيق من جلب القيم الجديدة في الوقت الفعلي، وستضيف الحد الأدنى للفاصل الزمني للجلب:

    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:35.1.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:35.1.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;
    

Dart

  1. من دليل مشروع Flutter، ثبِّت Remote Config وأضِفها باستخدام الأمر التالي:

    flutter pub add firebase_remote_config
    
  2. افتح ./lib/main.dart وأضِف عملية الاستيراد بعد عمليات الاستيراد الأخرى التي أضفتها لإتاحة Firebase AI Logic:

    import 'package:firebase_ai/firebase_ai.dart';
    import 'package:firebase_core/firebase_core.dart';
    import 'package:firebase_remote_config/firebase_remote_config.dart';
    
  3. أضِف المتغيّر _modelName إلى تطبيقك لتتمكّن من استخدامه لاحقًا:

    late final String _modelName;
    late final String _systemInstructions;
    late final String _prompt;
    
  4. احصل على النسخة الافتراضية لعنصر Remote Config وحدِّد أقل فترة زمنية للاسترجاع من أجل السماح بإعادة التحميل بشكل متكرّر. يُرجى التأكّد من إضافة هذا الرمز بعد إعداد Firebase.

      final remoteConfig = FirebaseRemoteConfig.instance;
      await remoteConfig.setConfigSettings(RemoteConfigSettings(
        fetchTimeout: const Duration(seconds: 3600),
        minimumFetchInterval: const Duration(seconds: 3600),
      ));
    

Unity

  1. أضِف Remote Config إلى مشروعك على Unity باتّباع هذه التعليمات.

  2. احصل على النسخة الافتراضية لعنصر Remote Config وحدِّد أقل فترة زمنية للاسترجاع من أجل السماح بإعادة التحميل بشكل متكرّر. يُرجى التأكّد من إضافة هذا الرمز بعد إعداد Firebase.

    var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
    const int MillisecondsPerSecond = 1000;
    await remoteConfig.SetConfigSettingsAsync(new ConfigSettings() {
      FetchTimeoutInMilliseconds = 3600 * MillisecondsPerSecond,
      MinimumFetchIntervalInMilliseconds = 3600 * MillisecondsPerSecond
    });
    

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

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

Swift

  1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

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

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

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

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

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

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

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

Kotlin

  1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

  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، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

  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',
};

Dart

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

// Set default values for Remote Config parameters.
remoteConfig.setDefaults(const {
  "template_id": "my-first-template-v1-0-0"
});

Unity

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

// Set default values for Remote Config parameters.
await remoteConfig.SetDefaultsAsync(
  new System.Collections.Generic.Dictionary<string, object>() {
    { "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();
    

Dart

// Fetch and activate Remote Config.
remoteConfig.fetchAndActivate();

// Assign Remote Config values.
String? _templateID = remoteConfig.getString("template_id");

Unity

// Fetch and activate Remote Config values.
await remoteConfig.FetchAndActivateAsync();

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

 // Add a real-time Remote Config listener
 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.");
   }
});

Dart

// Add a real-time Remote Config listener
remoteConfig.onConfigUpdated.listen((event) async {
  await remoteConfig.activate();
});

Unity

// Add a real-time Remote Config listener to automatically update whenever
// a new template is published.
// Note: the parameters can be anonymous as they are unused.

remoteConfig.OnConfigUpdateListener += (_, _) => {
  remoteConfig.ActivateAsync();
};

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

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

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

Swift

import FirebaseAILogic

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(backend = GenerativeBackend.googleAI()).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: templateID,
  // Provide the values for any input variables required by your template
  templateVariables: {
    customerName: customerName,
  },
});

// ...

Dart

// ...

final model = FirebaseAI.googleAI().templateGenerativeModel();

final templateID = remoteConfig.getString("template_id");
final customerName = 'Jane';

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

// ...

Unity

// ...

var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

var templateID = remoteConfig.GetValue("template_id").StringValue;
var model = ai.GetTemplateGenerativeModel();
var customerName = "Jane";

try
{
    // When making the `generateContent` call, source the template ID value from Remote Config
    var response = await model.GenerateContentAsync(
        templateID,
        // Provide the values for any input variables required by your template
        new Dictionary<string, object>
        {
            { "customerName", customerName },
        }
    );
    Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e)
{
    Debug.LogError($"An error occurred: {e.Message}");
}

// ...

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

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

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