Remote Config را با برنامه تغییر دهید

پیکربندی قالب‌ها با استفاده از Admin SDK، REST API و Firebase CLI. page_type: guide

این سند توضیح می‌دهد که چگونه می‌توانید مجموعه‌ای از پارامترها و شرایط با فرمت JSON را که به عنوان الگوی Remote Config شناخته می‌شوند، از طریق برنامه‌نویسی بخوانید و تغییر دهید. این به شما امکان می‌دهد تغییرات الگو را در backend ایجاد کنید که برنامه کلاینت می‌تواند با استفاده از کتابخانه کلاینت آن را دریافت کند.

با استفاده از Remote Config REST API ، Admin SDK ها یا Firebase CLI که در این راهنما توضیح داده شده است، می‌توانید مدیریت قالب در کنسول Firebase را کنار بگذارید تا تغییرات Remote Config را مستقیماً در فرآیندهای خود ادغام کنید. به عنوان مثال، با APIهای backend Remote Config ، می‌توانید:

• به‌روزرسانی‌های Remote Config را زمان‌بندی کنید . با استفاده از فراخوانی‌های API همراه با یک cron job، می‌توانید مقادیر Remote Config در یک برنامه منظم تغییر دهید.
• مقادیر پیکربندی را به صورت دسته‌ای وارد کنید تا به طور موثر از سیستم اختصاصی خود به Firebase Remote Config منتقل شوید.
• از Remote Config با Cloud Functions for Firebase استفاده کنید و مقادیر برنامه خود را بر اساس رویدادهایی که در سمت سرور اتفاق می‌افتند تغییر دهید. به عنوان مثال، می‌توانید از Remote Config برای تبلیغ یک ویژگی جدید در برنامه خود استفاده کنید و سپس پس از تشخیص تعامل کافی افراد با ویژگی جدید، آن تبلیغ را به طور خودکار خاموش کنید.

بخش‌های بعدی این راهنما، عملیاتی را که می‌توانید با استفاده از APIهای بک‌اند Remote Config انجام دهید، شرح می‌دهد.

تغییر Remote Config با استفاده از Firebase Admin SDK

Admin SDK مجموعه‌ای از کتابخانه‌های سرور است که به شما امکان می‌دهد از محیط‌های دارای امتیاز با Firebase تعامل داشته باشید. Admin SDK علاوه بر انجام به‌روزرسانی‌ها در Remote Config ، امکان تولید و تأیید توکن‌های احراز هویت Firebase و خواندن و نوشتن از Realtime Database فراهم می‌کند. برای کسب اطلاعات بیشتر در مورد پیش‌نیازها و تنظیمات Admin SDK ، به بخش «افزودن Firebase Admin SDK به سرور خود» مراجعه کنید.

برای بررسی نمونه کدی که این وظایف را با استفاده از Admin SDK انجام می‌دهد، به یکی از برنامه‌های شروع سریع زیر مراجعه کنید:

• شروع سریع Firebase Remote Config برای جاوا
• Firebase Remote Config Node.js
• شروع سریع Firebase Remote Config پایتون

در یک جریان معمول Remote Config ، ممکن است الگوی فعلی را دریافت کنید، برخی از پارامترها یا گروه‌های پارامتر و شرایط را تغییر دهید، الگو را اعتبارسنجی کنید و سپس آن را منتشر کنید. قبل از انجام این فراخوانی‌های API، باید درخواست‌ها را از SDK تأیید کنید.

مقداردهی اولیه SDK و تأیید درخواست‌های API

وقتی Admin SDK بدون هیچ پارامتری مقداردهی اولیه می‌کنید، SDK از اعتبارنامه‌های پیش‌فرض برنامه گوگل استفاده می‌کند و گزینه‌ها را از متغیر محیطی FIREBASE_CONFIG می‌خواند. اگر محتوای متغیر FIREBASE_CONFIG با یک { شروع شود، به عنوان یک شیء JSON تجزیه می‌شود. در غیر این صورت، SDK فرض می‌کند که رشته، نام یک فایل JSON حاوی گزینه‌ها است.

برای مثال:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

الگوی فعلی Remote Config را دریافت کنید

هنگام کار با قالب‌های Remote Config ، به خاطر داشته باشید که آنها نسخه‌بندی شده‌اند و هر نسخه از زمان ایجاد تا زمانی که آن را با یک به‌روزرسانی جایگزین می‌کنید، طول عمر محدودی دارد: ۹۰ روز، با محدودیت کلی ۳۰۰ نسخه ذخیره شده. برای اطلاعات بیشتر به Templates and Versioning مراجعه کنید.

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

پارامترها و مقادیر پارامتری که به طور خاص به عنوان گونه‌های مختلف در یک آزمایش A/B Testing ایجاد شده‌اند، در قالب‌های صادر شده لحاظ نمی‌شوند.

برای دریافت الگو:

function getTemplate() {
  var config = admin.remoteConfig();
  config.getTemplate()
      .then(function (template) {
        console.log('ETag from server: ' + template.etag);
        var templateStr = JSON.stringify(template);
        fs.writeFileSync('config.json', templateStr);
      })
      .catch(function (err) {
        console.error('Unable to get template');
        console.error(err);
      });
}

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

پارامترهای Remote Config را تغییر دهید

شما می‌توانید پارامترها و گروه‌های پارامتر Remote Config از طریق برنامه‌نویسی تغییر داده و اضافه کنید. برای مثال، به یک گروه پارامتر موجود با نام "new_menu" می‌توانید پارامتری برای کنترل نمایش اطلاعات فصلی اضافه کنید:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

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

تغییر شرایط Remote Config

شما می‌توانید شرایط و مقادیر شرطی Remote Config به صورت برنامه‌نویسی تغییر داده و اضافه کنید. برای مثال، برای اضافه کردن یک شرط جدید:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

در همه موارد، شما باید پس از انجام تغییرات، الگو را صریحاً منتشر کنید.

APIهای بک‌اند Remote Config چندین شرط و عملگر مقایسه‌ای ارائه می‌دهند که می‌توانید از آنها برای تغییر رفتار و ظاهر برنامه خود استفاده کنید. برای کسب اطلاعات بیشتر در مورد شرط‌ها و عملگرهای پشتیبانی شده برای این شرط‌ها، به مرجع عبارت شرطی مراجعه کنید.

اعتبارسنجی الگوی Remote Config

به صورت اختیاری، می‌توانید قبل از انتشار به‌روزرسانی‌های خود، آنها را اعتبارسنجی کنید، همانطور که نشان داده شده است:

function validateTemplate(template) {
  admin.remoteConfig().validateTemplate(template)
      .then(function (validatedTemplate) {
        // The template is valid and safe to use.
        console.log('Template was valid and safe to use');
      })
      .catch(function (err) {
        console.error('Template is invalid and cannot be published');
        console.error(err);
      });
}

try {
  Template validatedTemplate = FirebaseRemoteConfig.getInstance()
          .validateTemplateAsync(template).get();
  System.out.println("Template was valid and safe to use");
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Template is invalid and cannot be published");
    System.out.println(rcError.getMessage());
  }
}

این فرآیند اعتبارسنجی، خطاهایی مانند کلیدهای تکراری برای پارامترها و شرایط، نام‌های نامعتبر شرایط یا شرایط ناموجود، یا برچسب‌های با قالب نادرست را بررسی می‌کند. برای مثال، درخواستی که حاوی بیش از تعداد مجاز کلیدها - ۲۰۰۰ - باشد، پیام خطای Param count too large را برمی‌گرداند.

الگوی Remote Config را منتشر کنید

پس از بازیابی یک الگو و اصلاح آن با به‌روزرسانی‌هایتان، می‌توانید آن را منتشر کنید. انتشار یک الگو به روشی که در این بخش توضیح داده شده است، کل الگوی پیکربندی موجود را با فایل به‌روزرسانی‌شده جایگزین می‌کند و به الگوی فعال جدید، شماره نسخه یک بزرگتر از الگویی که جایگزین آن شده است، اختصاص داده می‌شود.

در صورت لزوم، می‌توانید از REST API برای بازگشت به نسخه قبلی استفاده کنید. برای کاهش خطر خطا در به‌روزرسانی، می‌توانید قبل از انتشار، اعتبارسنجی کنید .

شخصی‌سازی‌ها و شرایط Remote Config در قالب‌های دانلود شده گنجانده شده‌اند، بنابراین مهم است که هنگام تلاش برای انتشار در یک پروژه دیگر، از محدودیت‌های زیر آگاه باشید:

• شخصی‌سازی‌ها را نمی‌توان از پروژه‌ای به پروژه دیگر وارد کرد.

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

• شرایط را می‌توان از پروژه‌ای به پروژه دیگر وارد کرد، اما توجه داشته باشید که هرگونه مقدار شرطی خاص (مانند شناسه برنامه یا مخاطبان) باید قبل از انتشار در پروژه هدف وجود داشته باشد.

  برای مثال، اگر یک پارامتر Remote Config دارید که از شرطی استفاده می‌کند که مقدار پلتفرم iOS را مشخص می‌کند، می‌توان این الگو را در پروژه دیگری منتشر کرد، زیرا مقادیر پلتفرم برای هر پروژه‌ای یکسان است. با این حال، اگر حاوی شرطی باشد که به یک شناسه برنامه یا مخاطب کاربر خاص متکی باشد که در پروژه هدف وجود ندارد، اعتبارسنجی با شکست مواجه خواهد شد.

• اگر قالبی که قصد انتشار آن را دارید حاوی شرایطی است که به Google Analytics متکی است، Analytics باید در پروژه هدف فعال باشد.

function publishTemplate() {
  var config = admin.remoteConfig();
  var template = config.createTemplateFromJSON(
      fs.readFileSync('config.json', 'UTF8'));
  config.publishTemplate(template)
      .then(function (updatedTemplate) {
        console.log('Template has been published');
        console.log('ETag from server: ' + updatedTemplate.etag);
      })
      .catch(function (err) {
        console.error('Unable to publish template.');
        console.error(err);
      });
}

try {
  Template publishedTemplate = FirebaseRemoteConfig.getInstance()
          .publishTemplateAsync(template).get();
  System.out.println("Template has been published");
  // See the ETag of the published template.
  System.out.println("ETag from server: " + publishedTemplate.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Unable to publish template.");
    System.out.println(rcError.getMessage());
  }
}

تغییر Remote Config با استفاده از REST API

این بخش قابلیت‌های اصلی Remote Config REST API را در https://firebaseremoteconfig.googleapis.com شرح می‌دهد. برای جزئیات کامل، به مرجع API مراجعه کنید.

دریافت توکن دسترسی برای احراز هویت و مجوزدهی درخواست‌های API

پروژه‌های فایربیس از حساب‌های سرویس گوگل پشتیبانی می‌کنند که می‌توانید از آن‌ها برای فراخوانی APIهای سرور فایربیس از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی هستید یا برنامه خود را در محل مستقر می‌کنید، می‌توانید از اعتبارنامه‌های به دست آمده با استفاده از این حساب سرویس برای تأیید درخواست‌های سرور استفاده کنید.

شما می‌توانید تمام حساب‌های سرویس مربوط به پروژه Firebase خود را در ... مشاهده کنید. settings > برگه حساب‌های سرویس .

برای تأیید اعتبار یک حساب کاربری سرویس و اجازه دسترسی آن به سرویس‌های Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.

برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:

1. در کنسول Firebase ، به مسیر زیر بروید: settings > برگه حساب‌های سرویس .

2. روی «ایجاد کلید خصوصی جدید» کلیک کنید، سپس با کلیک روی «ایجاد کلید» تأیید کنید.

3. فایل JSON حاوی کلید را به طور ایمن ذخیره کنید.

هنگام تأیید اعتبار از طریق یک حساب کاربری سرویس، دو گزینه برای ارائه اعتبارنامه به برنامه خود دارید. می‌توانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید، یا می‌توانید مسیر کلید حساب کاربری سرویس را به صورت کد به صراحت ارسال کنید. گزینه اول امن‌تر است و اکیداً توصیه می‌شود.

برای تنظیم متغیر محیطی:

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

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

پس از تکمیل مراحل فوق، اعتبارنامه‌های پیش‌فرض برنامه (ADC) قادر است به‌طور ضمنی اعتبارنامه‌های شما را تعیین کند و به شما امکان می‌دهد هنگام آزمایش یا اجرا در محیط‌های غیر گوگلی، از اعتبارنامه‌های حساب سرویس استفاده کنید.

از اعتبارنامه‌های Firebase خود به همراه کتابخانه Google Auth برای زبان مورد نظر خود استفاده کنید تا یک توکن دسترسی OAuth 2.0 کوتاه مدت دریافت کنید:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
FirebaseRemoteConfigSnippets.java

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

برای تأیید دسترسی به Remote Config ، دامنه https://www.googleapis.com/auth/firebase.remoteconfig را درخواست کنید.

الگوی Remote Config را تغییر دهید

هنگام کار با قالب‌های Remote Config ، به خاطر داشته باشید که آنها نسخه‌بندی شده‌اند و هر نسخه از زمان ایجاد تا زمانی که آن را با یک به‌روزرسانی جایگزین می‌کنید، طول عمر محدودی دارد: ۹۰ روز، با محدودیت کلی ۳۰۰ نسخه ذخیره شده. برای اطلاعات بیشتر به Templates and Versioning مراجعه کنید.

الگوی فعلی Remote Config را دریافت کنید

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

پارامترها و مقادیر پارامتری که به طور خاص به عنوان گونه‌های مختلف در یک آزمایش A/B Testing ایجاد شده‌اند، در قالب‌های صادر شده لحاظ نمی‌شوند.

از دستورات زیر استفاده کنید:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

اعتبارسنجی الگوی Remote Config

به صورت اختیاری، می‌توانید قبل از انتشار، به‌روزرسانی‌های خود را اعتبارسنجی کنید. با افزودن پارامتر ?validate_only=true به درخواست انتشار، به‌روزرسانی‌های قالب را اعتبارسنجی کنید. در پاسخ، کد وضعیت ۲۰۰ و یک etag به‌روزرسانی‌شده با پسوند -0 به این معنی است که به‌روزرسانی شما با موفقیت اعتبارسنجی شده است. هر پاسخی غیر از ۲۰۰ نشان می‌دهد که داده‌های JSON حاوی خطاهایی هستند که باید قبل از انتشار آنها را اصلاح کنید.

الگوی Remote Config را به‌روزرسانی کنید

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

در صورت لزوم، می‌توانید از REST API برای بازگشت به نسخه قبلی استفاده کنید. برای کاهش خطر خطا در به‌روزرسانی، می‌توانید قبل از انتشار، اعتبارسنجی کنید .

شخصی‌سازی‌ها و شرایط Remote Config در قالب‌های دانلود شده گنجانده شده‌اند، بنابراین مهم است که هنگام تلاش برای انتشار در یک پروژه دیگر، از محدودیت‌های زیر آگاه باشید:

• شخصی‌سازی‌ها را نمی‌توان از پروژه‌ای به پروژه دیگر وارد کرد.

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

• شرایط را می‌توان از پروژه‌ای به پروژه دیگر وارد کرد، اما توجه داشته باشید که هرگونه مقدار شرطی خاص (مانند شناسه برنامه یا مخاطبان) باید قبل از انتشار در پروژه هدف وجود داشته باشد.

  برای مثال، اگر یک پارامتر Remote Config دارید که از شرطی استفاده می‌کند که مقدار پلتفرم iOS را مشخص می‌کند، می‌توان این الگو را در پروژه دیگری منتشر کرد، زیرا مقادیر پلتفرم برای هر پروژه‌ای یکسان است. با این حال، اگر حاوی شرطی باشد که به یک شناسه برنامه یا مخاطب کاربر خاص متکی باشد که در پروژه هدف وجود ندارد، اعتبارسنجی با شکست مواجه خواهد شد.

• اگر قالبی که قصد انتشار آن را دارید حاوی شرایطی است که به Google Analytics متکی است، Analytics باید در پروژه هدف فعال باشد.

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

تغییر شرایط Remote Config

شما می‌توانید شرایط و مقادیر شرطی Remote Config از طریق برنامه‌نویسی تغییر دهید. با REST API، قبل از انتشار الگو، باید مستقیماً الگو را ویرایش کنید تا شرایط را تغییر دهید.

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all
      capital letters."
    }
  }
}

firebase remoteconfig:versions:list [--limit NUMBER_OF_VERSIONS]

firebase remoteconfig:get [-v, --version_number VERSION_NUMBER] [-o, --output FILENAME]

firebase remoteconfig:rollback [-v, --version_number VERSION_NUMBER] [--force]

firebase remoteconfig:experiments:list [--filter EXPRESSION] [--pageSize NUMBER] [--pageToken TOKEN]

firebase remoteconfig:experiments:list

firebase remoteconfig:experiments:get EXPERIMENT_ID

firebase remoteconfig:experiments:get exp_promo_discount_2026

firebase remoteconfig:experiments:delete EXPERIMENT_ID

firebase remoteconfig:experiments:delete exp_promo_discount_2026

firebase remoteconfig:rollouts:list [--filter EXPRESSION] [--pageSize NUMBER] [--pageToken TOKEN]

firebase remoteconfig:rollouts:list

firebase remoteconfig:rollouts:get ROLLOUT_ID

firebase remoteconfig:rollouts:get rollout_new_checkout_flow

firebase remoteconfig:rollouts:delete ROLLOUT_ID

firebase remoteconfig:rollouts:delete rollout_new_checkout_flow