الگوهای نسخه بااستفاده از «پیکربندی از راه دور»


وقتی از الگوهای پیام‌واره سرور استفاده می‌کنید، می‌توانید مقادیر را درون الگوی داده‌شده بدون انتشار نسخه جدیدی از برنامه‌تان به‌روز کنید. بااین‌حال، ازآنجایی‌که هرگونه تغییر در الگو تقریباً بلافاصله توسط درخواست‌های برنامه شما استفاده خواهد شد، باید در ایجاد تغییراتی که می‌تواند برنامه شما را خراب کند یا باعث تغییرات غیرمنتظره در رفتار شود، احتیاط کنید.

بنابراین، اگر می‌خواهید تغییرات اساسی‌تری ایجاد کنید یا تغییرات را به‌تدریج عرضه کنید، نمی‌خواهید الگویی را که در کد تولید استفاده می‌شود تغییر دهید.

درعوض، توصیه می‌کنیم از Firebase Remote Config برای کنترل مقدار شناسه الگو استفاده‌شده در درخواست به مدل استفاده کنید.

‫Firebase Remote Config به شما امکان می‌دهد مقادیر پارامتر را در برنامه‌تان (مثل شناسه الگو) به‌صورت پویا و از راه دور از کنسول Firebase به‌روز کنید، بدون اینکه نیاز باشد نسخه جدیدی از برنامه‌تان منتشر کنید. این کنسول همچنین قابلیت‌ها و یکپارچه‌سازی‌های ساده‌ای برای عرضه تغییرات و همچنین آزمایش A/B دارد.

این راهنما نحوه پیاده‌سازی Remote Config در برنامه‌تان را توضیح می‌دهد، به‌ویژه برای کنترل شناسه الگوی استفاده‌شده در برنامه‌تان.

مرحله ۱: مقدار پارامتر را در کنسول Firebase تنظیم کنید

الگوی کارخواه Remote Config را ایجاد کنید و پارامتر template_id و مقدار آن را برای واکشی و استفاده در برنامه پیکربندی کنید.

  1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از دور بروید.

  2. از انتخابگر کارخواه/کارساز در بالای صفحه، کارخواه را انتخاب کنید.

  3. با کلیک کردن روی ایجاد پیکربندی (یا افزودن پارامتر اگر قبلاً از الگوهای کارخواه استفاده کرده‌اید) الگوی کارخواه را شروع کنید.

  4. پارامتر template_id را تعریف کنید:

    نام پارامتر شرح نوع مقدار پیش‌فرض
    template_id شناسه الگو. تار my-first-template-v1-0-0
  5. پس‌از افزودن این پارامتر، روی انتشار تغییرات کلیک کنید. اگر این الگوی Remote Config جدید نیست، تغییرات را مرور کنید و دوباره روی انتشار تغییرات کلیک کنید.

مرحله ۲: افزودن و مقداردهی اولیه Remote Config در برنامه

کتابخانه Remote Config را اضافه کنید و Remote Config را در برنامه‌تان راه‌اندازی کنید.

Swift

به‌عنوان بخشی از راه‌اندازی Firebase AI Logic، قبلاً «کیت توسعه نرم‌افزار Firebase» را به برنامه‌تان اضافه کرده‌اید، اما باید Remote Config را نیز اضافه کنید.

  1. در Xcode، با باز بودن پروژه، به File > Add Package Dependencies پیمایش کنید.

  2. firebase-ios-sdk را انتخاب کنید و سپس روی افزودن بسته کلیک کنید.

  3. از «پیمایشگر پروژه»، برنامه > هدف‌ها > برنامه را انتخاب کنید.

  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:35.0.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.0.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 برای کیت توسعه نرم‌افزار 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
    });
    

مرحله ۳: مقدار پارامتر درون‌برنامه‌ای را تنظیم کنید

باید مقادیر پارامتر پیش‌فرض درون‌برنامه‌ای را در Remote Config شیء تنظیم کنید. این کار تضمین می‌کند که برنامه شما حتی اگر نتواند مقادیر را از سرویس Remote Config واکشی کند، طبق انتظار عمل کند.

Swift

  1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از دور > صفحه پارامترها بروید.

  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، به DevOps و تعامل > پیکربندی از دور > صفحه پارامترها بروید.

  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 و تعامل > پیکربندی از دور > صفحه پارامترها بروید.

  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" }
  }
);

مرحله ۴: واکشی و فعال کردن مقدار

پس‌از تنظیم مقدار پیش‌فرض برای نام مدل، موارد زیر را برای واکشی و فعال کردن مقادیر اضافه کنید.

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();
قرار دهید.

مرحله ۵: افزودن شنونده 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();
};

مرحله ۶: به‌روزرسانی درخواست‌های 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,
  // Provide the values for any input variables required by your template
  {
    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}");
}

// ...

مرحله ۷: اجرای برنامه

برنامه را بسازید و اجرا کنید و مطمئن شوید که کار می‌کند. از صفحه Remote Config در کنسول Firebase، تغییراتی در پیکربندی‌تان ایجاد کنید، تغییرات را منتشر کنید، و نتیجه را درستی‌سنجی کنید.

مراحل بعدی