Ikuti semua informasi yang diumumkan di Firebase Summit, dan pelajari bagaimana Firebase dapat membantu Anda mempercepat pengembangan aplikasi dan menjalankan aplikasi dengan percaya diri. Pelajari Lebih Lanjut

Ubah Remote Config secara terprogram

Dokumen ini menjelaskan cara membaca dan memodifikasi kumpulan parameter dan kondisi berformat JSON yang dikenal sebagai template Remote Config secara terprogram. Ini memungkinkan Anda membuat perubahan template di backend yang dapat diambil oleh aplikasi klien menggunakan pustaka klien.

Dengan menggunakan REST API Remote Config atau SDK Admin yang dijelaskan dalam panduan ini, Anda dapat mengabaikan pengelolaan template di konsol Firebase untuk langsung mengintegrasikan perubahan Remote Config ke dalam proses Anda sendiri. Misalnya, dengan API backend Remote Config, Anda dapat:

  • Menjadwalkan pembaruan Remote Config . Dengan menggunakan panggilan API bersamaan dengan tugas cron, Anda dapat mengubah nilai Remote Config pada jadwal reguler.
  • Nilai konfigurasi impor batch untuk melakukan transisi secara efisien dari sistem milik Anda sendiri ke Firebase Remote Config.
  • Gunakan Remote Config dengan Cloud Functions for Firebase , mengubah nilai di aplikasi Anda berdasarkan peristiwa yang terjadi di sisi server. Misalnya, Anda dapat menggunakan Remote Config untuk mempromosikan fitur baru di aplikasi Anda, lalu menonaktifkan promosi tersebut secara otomatis setelah Anda mendeteksi cukup banyak orang yang telah berinteraksi dengan fitur baru tersebut.

    Diagram yang menampilkan backend Remote Config yang berinteraksi dengan alat dan server kustom

Bagian berikut dari panduan ini menjelaskan operasi yang dapat Anda lakukan dengan API backend Remote Config. Untuk meninjau beberapa kode yang menjalankan tugas ini melalui REST API, lihat salah satu contoh aplikasi berikut:

Modifikasi Remote Config menggunakan Firebase Admin SDK

Admin SDK adalah sekumpulan pustaka server yang memungkinkan Anda berinteraksi dengan Firebase dari lingkungan istimewa. Selain melakukan update pada Remote Config, Admin SDK memungkinkan pembuatan dan verifikasi token autentikasi Firebase, pembacaan dan penulisan dari Realtime Database, dan seterusnya. Untuk mempelajari lebih lanjut prasyarat dan penyiapan Admin SDK, lihat Menambahkan Firebase Admin SDK ke server Anda .

Dalam alur Remote Config tipikal, Anda mungkin mendapatkan template saat ini, memodifikasi beberapa parameter atau grup parameter dan ketentuan, memvalidasi template, lalu memublikasikannya. Sebelum melakukan panggilan API tersebut, Anda harus mengotorisasi permintaan dari SDK.

Inisialisasi SDK dan otorisasi permintaan API

Saat Anda menginisialisasi Admin SDK tanpa parameter, SDK menggunakan Kredensial Default Aplikasi Google dan membaca opsi dari variabel lingkungan FIREBASE_CONFIG . Jika konten variabel FIREBASE_CONFIG dimulai dengan { maka akan diuraikan sebagai objek JSON. Kalau tidak, SDK menganggap bahwa string adalah nama file JSON yang berisi opsi.

Sebagai contoh:

Node.js

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

Jawa

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

Dapatkan Template Remote Config saat ini

Saat bekerja dengan template Remote Config, perlu diingat bahwa template tersebut berversi, dan setiap versi memiliki masa pakai terbatas sejak pembuatannya hingga Anda menggantinya dengan pembaruan: 90 hari, dengan batas total 300 versi yang disimpan. Lihat Templat dan Pembuatan Versi untuk informasi lebih lanjut.

Anda dapat menggunakan API backend untuk mendapatkan versi template Remote Config yang aktif saat ini dalam format JSON.

Parameter dan nilai parameter yang dibuat khusus sebagai varian dalam eksperimen Pengujian A/B tidak disertakan dalam template yang diekspor.

Untuk mendapatkan templatnya:

Node.js

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

Jawa

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

Modifikasi parameter Remote Config

Anda dapat memodifikasi dan menambahkan parameter Remote Config dan grup parameter secara terprogram. Misalnya, ke grup parameter yang ada bernama "menu_baru", Anda dapat menambahkan parameter untuk mengontrol tampilan informasi musiman:

Node.js

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

Jawa

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

API memungkinkan Anda membuat parameter dan grup parameter baru, atau mengubah nilai default, nilai bersyarat, dan deskripsi. Dalam semua kasus, Anda harus menerbitkan template secara eksplisit setelah melakukan modifikasi.

Modifikasi kondisi Remote Config

Anda dapat memodifikasi dan menambahkan kondisi Remote Config dan nilai kondisional secara terprogram. Misalnya, untuk menambahkan kondisi baru:

Node.js

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

Jawa

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

Dalam semua kasus, Anda harus menerbitkan template secara eksplisit setelah melakukan modifikasi.

API backend Remote Config menyediakan beberapa kondisi dan operator perbandingan yang dapat Anda gunakan untuk mengubah perilaku dan tampilan aplikasi Anda. Untuk mempelajari lebih lanjut tentang ketentuan dan operator yang didukung untuk ketentuan ini, lihat referensi ekspresi bersyarat .

Validasi template Remote Config

Secara opsional, Anda dapat memvalidasi pembaruan Anda sebelum memublikasikannya, seperti yang ditunjukkan:

Node.js

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

Jawa

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

Proses validasi ini memeriksa kesalahan seperti kunci duplikat untuk parameter dan kondisi, nama kondisi yang tidak valid atau kondisi yang tidak ada, atau etag yang salah format. Misalnya, permintaan yang berisi lebih dari jumlah kunci yang diizinkan—2000—akan mengembalikan pesan kesalahan, Param count too large .

Publikasikan template Remote Config

Setelah mengambil template dan merevisinya dengan pembaruan yang diinginkan, Anda kemudian dapat menerbitkannya. Menerbitkan template seperti yang dijelaskan di bagian ini akan mengganti seluruh template konfigurasi yang ada dengan file yang diperbarui, dan template aktif baru diberi nomor versi satu nomor lebih besar dari template yang digantikannya.

Jika perlu, Anda dapat menggunakan REST API untuk kembali ke versi sebelumnya . Untuk mengurangi risiko kesalahan dalam pembaruan, Anda dapat melakukan validasi sebelum memublikasikan .

Personalisasi dan ketentuan Remote Config disertakan dalam template yang diunduh, jadi penting untuk mengetahui batasan berikut saat mencoba memublikasikan ke project lain:

  • Personalisasi tidak dapat diimpor dari proyek ke proyek.

    Misalnya, jika Anda mengaktifkan personalisasi di proyek dan mengunduh serta mengedit template, Anda dapat menerbitkannya ke proyek yang sama, tetapi Anda tidak dapat memublikasikannya ke proyek lain kecuali Anda menghapus personalisasi dari template.

  • Ketentuan dapat diimpor dari proyek ke proyek, tetapi perhatikan bahwa nilai bersyarat tertentu (seperti ID aplikasi atau audiens), harus ada di proyek target sebelum dipublikasikan.

    Misalnya, jika Anda memiliki parameter Remote Config yang menggunakan kondisi yang menentukan nilai platform iOS , template dapat dipublikasikan ke proyek lain, karena nilai platform sama untuk semua proyek. Namun, jika berisi kondisi yang bergantung pada ID aplikasi tertentu atau audiens pengguna yang tidak ada di project target, validasi akan gagal.

  • Jika template yang Anda rencanakan untuk dipublikasikan berisi ketentuan yang bergantung pada Google Analytics, Analytics harus diaktifkan di proyek target.

Node.js

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

Jawa

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

Modifikasi Remote Config menggunakan REST API

Bagian ini menjelaskan kemampuan utama REST API Remote Config di https://firebaseremoteconfig.googleapis.com . Untuk detail selengkapnya, lihat referensi API .

Dapatkan token akses untuk mengautentikasi dan mengotorisasi permintaan API

Proyek Firebase mendukung akun layanan Google , yang dapat Anda gunakan untuk memanggil API server Firebase dari server aplikasi atau lingkungan tepercaya. Jika Anda mengembangkan kode secara lokal atau menerapkan aplikasi secara lokal, Anda dapat menggunakan kredensial yang diperoleh melalui akun layanan ini untuk mengotorisasi permintaan server.

Untuk mengautentikasi akun layanan dan mengotorisasinya untuk mengakses layanan Firebase, Anda harus membuat file kunci pribadi dalam format JSON.

Untuk menghasilkan file kunci pribadi untuk akun layanan Anda:

  1. Di konsol Firebase, buka Pengaturan > Akun Layanan .

  2. Klik Generate New Private Key , lalu konfirmasikan dengan mengklik Generate Key .

  3. Simpan file JSON yang berisi kunci dengan aman.

Saat memberi otorisasi melalui akun layanan, Anda memiliki dua pilihan untuk memberikan kredensial ke aplikasi Anda. Anda dapat menyetel variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS , atau secara eksplisit meneruskan jalur ke kunci akun layanan dalam kode. Opsi pertama lebih aman dan sangat disarankan.

Untuk mengatur variabel lingkungan:

Setel variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file dari file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini, jadi jika Anda membuka sesi baru, atur kembali variabel tersebut.

Linux atau macOS

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

Windows

Dengan PowerShell:

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

Setelah Anda menyelesaikan langkah-langkah di atas, Application Default Credentials (ADC) dapat menentukan kredensial Anda secara implisit, memungkinkan Anda menggunakan kredensial akun layanan saat menguji atau menjalankan di lingkungan non-Google.

Gunakan kredensial Firebase Anda bersama dengan Google Auth Library untuk bahasa pilihan Anda guna mengambil token akses OAuth 2.0 berumur pendek:

node.js

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

Dalam contoh ini, pustaka klien Google API mengautentikasi permintaan dengan token web JSON, atau JWT. Untuk informasi selengkapnya, lihat token web JSON .

Piton

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

Jawa

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

Setelah token akses Anda kedaluwarsa, metode penyegaran token dipanggil secara otomatis untuk mengambil token akses yang diperbarui.

Untuk mengotorisasi akses ke Remote Config, minta cakupan https://www.googleapis.com/auth/firebase.remoteconfig .

Ubah template Remote Config

Saat bekerja dengan template Remote Config, perlu diingat bahwa template tersebut berversi, dan setiap versi memiliki masa pakai terbatas sejak pembuatannya hingga Anda menggantinya dengan pembaruan: 90 hari, dengan batas total 300 versi yang disimpan. Lihat Templat dan Pembuatan Versi untuk informasi lebih lanjut.

Dapatkan Template Remote Config saat ini

Anda dapat menggunakan API backend untuk mendapatkan versi template Remote Config yang aktif saat ini dalam format JSON.

Parameter dan nilai parameter yang dibuat khusus sebagai varian dalam eksperimen Pengujian A/B tidak disertakan dalam template yang diekspor.

Gunakan perintah berikut:

keriting

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

Perintah ini menampilkan payload JSON ke satu file, dan header (termasuk Etag) ke file terpisah.

Permintaan HTTP mentah

Host: firebaseremoteconfig.googleapis.com

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

Panggilan API ini mengembalikan JSON berikut, bersama dengan header terpisah yang menyertakan ETag yang Anda gunakan untuk permintaan berikutnya.

Validasi template Remote Config

Secara opsional, Anda dapat memvalidasi pembaruan Anda sebelum memublikasikannya. Validasi pembaruan template dengan menambahkan parameter URL ?validate_only=true ke permintaan publikasi Anda. Sebagai tanggapan, kode status 200 dan etag yang diperbarui dengan akhiran -0 berarti pembaruan Anda berhasil divalidasi. Respons non-200 apa pun menunjukkan bahwa data JSON berisi error yang harus Anda perbaiki sebelum dipublikasikan.

Perbarui template Remote Config

Setelah mengambil template dan merevisi konten JSON dengan pembaruan yang diinginkan, Anda kemudian dapat memublikasikannya. Menerbitkan template seperti yang dijelaskan di bagian ini akan mengganti seluruh template konfigurasi yang ada dengan file yang diperbarui, dan template aktif baru diberi nomor versi satu nomor lebih besar dari template yang digantikannya.

Jika perlu, Anda dapat menggunakan REST API untuk kembali ke versi sebelumnya . Untuk mengurangi risiko kesalahan dalam pembaruan, Anda dapat melakukan validasi sebelum memublikasikan .

Personalisasi dan ketentuan Remote Config disertakan dalam template yang diunduh, jadi penting untuk mengetahui batasan berikut saat mencoba memublikasikan ke project lain:

  • Personalisasi tidak dapat diimpor dari proyek ke proyek.

    Misalnya, jika Anda mengaktifkan personalisasi di proyek dan mengunduh serta mengedit template, Anda dapat menerbitkannya ke proyek yang sama, tetapi Anda tidak dapat memublikasikannya ke proyek lain kecuali Anda menghapus personalisasi dari template.

  • Ketentuan dapat diimpor dari proyek ke proyek, tetapi perhatikan bahwa nilai bersyarat tertentu (seperti ID aplikasi atau audiens), harus ada di proyek target sebelum dipublikasikan.

    Misalnya, jika Anda memiliki parameter Remote Config yang menggunakan kondisi yang menentukan nilai platform iOS , template dapat dipublikasikan ke proyek lain, karena nilai platform sama untuk semua proyek. Namun, jika berisi kondisi yang bergantung pada ID aplikasi tertentu atau audiens pengguna yang tidak ada di project target, validasi akan gagal.

  • Jika template yang Anda rencanakan untuk dipublikasikan berisi ketentuan yang bergantung pada Google Analytics, Analytics harus diaktifkan di proyek target.

keriting

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

Untuk perintah curl ini, Anda dapat menentukan konten dengan menggunakan karakter "@", diikuti dengan nama file.

Permintaan HTTP mentah

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

Karena ini adalah permintaan tulis, ETag dimodifikasi oleh perintah ini dan ETag yang diperbarui disediakan di header respons dari perintah PUT berikutnya.

Modifikasi kondisi Remote Config

Anda dapat memodifikasi kondisi Remote Config dan nilai kondisional secara terprogram. Dengan REST API, Anda harus mengedit template secara langsung untuk mengubah ketentuan sebelum menerbitkan template.

{
  "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."
    }
  }
}

Modifikasi di atas pertama-tama menentukan sekumpulan kondisi, lalu menentukan nilai default dan nilai parameter berbasis kondisi ( nilai bersyarat ) untuk setiap parameter. Itu juga menambahkan deskripsi opsional untuk setiap elemen; seperti komentar kode, ini untuk penggunaan pengembang dan tidak ditampilkan di aplikasi. ETag juga disediakan untuk tujuan kontrol versi.

API backend Remote Config menyediakan beberapa kondisi dan operator perbandingan yang dapat Anda gunakan untuk mengubah perilaku dan tampilan aplikasi Anda. Untuk mempelajari lebih lanjut tentang ketentuan dan operator yang didukung untuk ketentuan ini, lihat referensi ekspresi bersyarat .

Kode Kesalahan HTTP

Kode status Arti
200 Berhasil diperbarui
400 Terjadi kesalahan validasi. Misalnya, permintaan yang berisi lebih dari jumlah kunci yang diizinkan—2000—akan mengembalikan 400 (Permintaan Buruk) dengan pesan kesalahan, Param count too large . Juga, Kode Status HTTPS ini dapat terjadi dalam dua situasi berikut:
  • Kesalahan ketidakcocokan versi terjadi karena kumpulan nilai dan kondisi telah diperbarui sejak Anda terakhir mengambil nilai ETag. Untuk mengatasinya, Anda harus menggunakan perintah GET untuk mendapatkan template baru dan nilai ETag, memperbarui template, lalu mengirimkan menggunakan template tersebut dan nilai ETag baru.
  • Perintah PUT (Update permintaan template Remote Config) dibuat tanpa menentukan header If-Match .
401 Terjadi error otorisasi (token akses tidak diberikan atau REST API Firebase Remote Config belum ditambahkan ke project Anda di Cloud Developer Console)
403 Terjadi kesalahan autentikasi (token akses yang salah diberikan)
500 Terjadi kesalahan internal. Jika kesalahan ini terjadi, ajukan tiket dukungan Firebase

Kode status 200 berarti template Remote Config (parameter, nilai, dan ketentuan untuk project) telah diperbarui dan kini tersedia untuk aplikasi yang menggunakan project ini. Kode status lainnya menunjukkan bahwa template Remote Config yang ada sebelumnya masih berlaku.

Setelah Anda mengirimkan pembaruan ke template Anda, buka konsol Firebase untuk memverifikasi bahwa perubahan Anda muncul seperti yang diharapkan. Ini penting karena pengurutan kondisi memengaruhi cara mereka dievaluasi (kondisi pertama yang mengevaluasi true berlaku).

Penggunaan ETag dan pembaruan paksa

REST API Remote Config menggunakan tag entitas (ETag) untuk mencegah kondisi balapan dan pembaruan yang tumpang tindih dengan sumber daya. Untuk mempelajari lebih lanjut tentang ETag, lihat ETag - HTTP .

Untuk REST API, Google menyarankan agar Anda meng-cache ETag yang disediakan oleh perintah GET terbaru, dan menggunakan nilai ETag tersebut di header permintaan If-Match saat mengeluarkan perintah PUT . Jika perintah PUT Anda menghasilkan Kode Status HTTPS 409, Anda harus mengeluarkan perintah GET baru untuk mendapatkan ETag dan template baru untuk digunakan dengan perintah PUT berikutnya.

Anda dapat mengakali ETag, dan perlindungan dari yang disediakannya, dengan memaksa template Remote Config diperbarui sebagai berikut: If-Match: * Namun, pendekatan ini tidak disarankan karena berisiko menyebabkan hilangnya pembaruan pada Remote Config Anda template jika banyak klien memperbarui template Remote Config. Konflik semacam ini dapat terjadi dengan banyak klien yang menggunakan API, atau dengan pembaruan yang bertentangan dari klien API dan pengguna konsol Firebase.

Untuk panduan mengelola versi template Remote Config, lihat Template dan pembuatan versi Remote Config .