Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Mengubah Remote Config secara terprogram

Dokumen ini menjelaskan bagaimana Anda dapat secara terprogram membaca dan mengubah seperangkat parameter dan kondisi berformat JSON yang dikenal sebagai template Remote Config. Hal ini memungkinkan Anda membuat perubahan template di backend yang dapat diambil oleh aplikasi klien menggunakan library klien.

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

  • Menjadwalkan update Remote Config. Dengan menggunakan panggilan API bersamaan dengan cron job, Anda dapat mengubah nilai Remote Config sesuai jadwal rutin.
  • Melakukan batch import untuk nilai konfigurasi agar dapat melakukan transisi secara efisien dari sistem yang Anda miliki ke Firebase Remote Config.
  • Gunakan Remote Config dengan Cloud Functions for Firebase untuk 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 itu secara otomatis begitu Anda mendeteksi cukup banyak orang yang berinteraksi dengan fitur baru ini.

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

Mengubah Remote Config menggunakan Firebase Admin SDK

Admin SDK adalah serangkaian library server yang dapat Anda gunakan untuk berinteraksi dengan Firebase dari lingkungan istimewa. Selain melakukan update ke Remote Config, Admin SDK memungkinkan pembuatan dan verifikasi token Firebase auth, pembacaan dan penulisan dari Realtime Database, dan sebagainya. Untuk mempelajari prasyarat dan penyiapan Admin SDK lebih lanjut, baca artikel Menambahkan Firebase Admin SDK ke server Anda.

Dalam alur Remote Config biasa, Anda mungkin mendapatkan template saat ini, mengubah beberapa parameter atau grup parameter dan kondisi, memvalidasi template, lalu memublikasikannya. Sebelum melakukan panggilan API tersebut, Anda harus memberi otorisasi permintaan dari SDK.

Menginisialisasi SDK dan memberi otorisasi permintaan API

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

Contoh:

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

Mendapatkan Template Remote Config saat ini

Saat menggunakan template Remote Config, perlu diingat bahwa template tersebut sudah ada versinya, dan setiap versi memiliki masa pakai terbatas dari saat pembuatannya hingga saat Anda menggantinya dengan versi terbaru: 90 hari, dengan batas total 300 versi yang disimpan. Lihat Template dan Pembuatan Versi untuk mengetahui informasi lebih lanjut.

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

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

Mengubah parameter Remote Config

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

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

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

Mengubah kondisi Remote Config

Anda dapat mengubah dan menambahkan kondisi serta nilai bersyarat Remote Config secara terprogram. Misalnya, untuk menambahkan kondisi baru:

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

Dalam semua kasus, Anda harus secara eksplisit memublikasikan template 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 kondisi dan operator yang didukung untuk kondisi ini lebih lanjut, baca artikel referensi ekspresi kondisional.

Memvalidasi template Remote Config

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

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

Proses validasi ini memeriksa error 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 menampilkan pesan error, Param count too large.

Memublikasikan template Remote Config

Setelah mengambil template dan merevisinya dengan update yang diinginkan, Anda dapat memublikasikannya. Memublikasikan template seperti yang dijelaskan di bagian ini menggantikan seluruh template konfigurasi yang ada dengan file yang telah diupdate, dan template aktif yang baru diberi nomor versi satu angka lebih besar daripada template yang digantikannya.

Jika perlu, Anda dapat menggunakan REST API untuk melakukan roll back ke versi sebelumnya. Untuk mengurangi risiko terjadinya error dalam proses update, Anda dapat memvalidasi sebelum memublikasikan.

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

Mengubah Remote Config menggunakan REST API

Bagian ini menjelaskan kemampuan utama dari REST API Remote Config di https://firebaseremoteconfig.googleapis.com. Untuk mengetahui detail selengkapnya, baca Referensi API.

Mendapatkan token akses untuk mengautentikasi dan memberi otorisasi permintaan API

Project 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 men-deploy aplikasi secara lokal, gunakan kredensial yang diperoleh melalui akun layanan ini untuk mengizinkan permintaan server.

Untuk mengautentikasi akun layanan dan memberinya akses ke layanan Firebase, Anda harus membuat file kunci pribadi dalam format JSON.

Untuk membuat file kunci pribadi untuk akun layanan Anda:

  1. Di Firebase console, buka Setelan > Akun Layanan.

  2. Klik Buat Kunci Pribadi Baru, lalu konfirmasikan dengan mengklik Buat Kunci.

  3. Simpan dengan aman file JSON yang memuat kunci tersebut.

Saat mengotorisasi melalui akun layanan, Anda diberi dua pilihan untuk memberikan kredensial ke aplikasi. Anda dapat menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, atau secara eksplisit meneruskan jalur kunci akun layanan dalam kode. Opsi pertama lebih aman dan sangat direkomendasikan.

Untuk menetapkan variabel lingkungan:

Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini, jadi jika Anda membuka sesi baru, tetapkan variabel lagi.

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, Kredensial Default Aplikasi (ADC) secara implisit dapat menentukan kredensial Anda, sehingga Anda dapat menggunakan kredensial akun layanan saat menguji atau menjalankannya di lingkungan non-Google.

Gunakan kredensial Firebase Anda beserta Library Klien Google API untuk bahasa pilihan Anda saat mengambil token akses OAuth 2.0 yang 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, library klien Google API mengautentikasi permintaan dengan token web JSON atau JWT. Untuk informasi lebih lanjut, baca token web JSON.

Python

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

Java

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

Setelah masa berlaku token akses berakhir, metode refresh token akan otomatis dipanggil untuk mengambil token yang telah diupdate.

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

Mengubah template Remote Config

Saat menggunakan template Remote Config, perlu diingat bahwa template tersebut sudah ada versinya, dan setiap versi memiliki masa pakai terbatas dari saat pembuatannya hingga saat Anda menggantinya dengan versi terbaru: 90 hari, dengan batas total 300 versi yang disimpan. Lihat Template dan Pembuatan Versi untuk mengetahui informasi lebih lanjut.

Mendapatkan Template Remote Config saat ini

Anda dapat menggunakan API backend untuk mendapatkan versi aktif saat ini dari template Remote Config dalam format JSON. Gunakan perintah berikut:

cURL

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 sebuah file dan headernya (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 menampilkan JSON berikut ini beserta header terpisah yang menyertakan ETag yang Anda gunakan untuk permintaan berikutnya.

Memvalidasi template Remote Config

Jika ingin, Anda dapat memvalidasi update sebelum memublikasikannya. Validasi update template dengan menambahkan parameter URL ke ?validate_only=true ke permintaan publikasi Anda. Dalam responsnya, kode status 200 dan ETag hasil update dengan akhiran -0 akan menandakan bahwa update berhasil divalidasi. Respons non-200 menunjukkan bahwa data JSON berisi error yang harus Anda perbaiki sebelum melakukan publikasi.

Mengupdate template Remote Config

Setelah mengambil template dan merevisi konten JSON dengan update yang diinginkan, Anda dapat memublikasikannya. Memublikasikan template seperti yang dijelaskan di bagian ini menggantikan seluruh template konfigurasi yang ada dengan file yang telah diupdate, dan template aktif yang baru diberi nomor versi satu angka lebih besar daripada template yang digantikannya.

Jika perlu, Anda dapat menggunakan REST API untuk melakukan roll back ke versi sebelumnya. Untuk mengurangi risiko terjadinya error dalam proses update, Anda dapat memvalidasi sebelum memublikasikan.

cURL

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 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 sudah diupdate akan diberikan sebagai header respons terhadap perintah PUT berikutnya.

Mengubah kondisi Remote Config

Anda dapat mengubah kondisi dan nilai bersyarat Remote Config secara terprogram. Dengan REST API, Anda harus mengedit template secara langsung untuk mengubah kondisi sebelum memublikasikan 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 menetapkan serangkaian kondisi, kemudian menetapkan nilai default dan parameter value berbasis kondisi (nilai bersyarat) untuk masing-masing parameter. Ini juga menambahkan deskripsi opsional untuk setiap elemen; seperti komentar kode, ini untuk penggunaan developer 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 kondisi dan operator yang didukung untuk kondisi ini lebih lanjut, baca artikel referensi ekspresi kondisional.

Kode Error HTTP

Kode Status Arti
200 Berhasil diupdate
400 Terjadi error pada validasi. Misalnya, permintaan yang mengandung jumlah kunci lebih dari yang diizinkan—2000—akan menampilkan 400 (Permintaan Buruk) dengan pesan error, Param count too large. Selain itu, Kode Status HTTPS ini dapat terjadi dalam dua situasi berikut:
  • Error pada ketidakcocokan versi terjadi karena rangkaian nilai dan kondisi telah diupdate sejak terakhir kali nilai ETag diambil. Untuk mengatasinya, sebaiknya gunakan perintah GET untuk mendapatkan template dan nilai ETag baru. Setelah itu, update template, lalu kirimkan update dengan menggunakan template tersebut dan nilai ETag yang baru.
  • Perintah PUT (permintaan update template Remote Config) dibuat tanpa menentukan header If-Match.
401 Terjadi error pada otorisasi (tidak ada token akses yang diberikan atau REST API Firebase Remote Config belum ditambahkan ke project Anda di Cloud Developer Console)
403 Terjadi error pada autentikasi (token akses yang diberikan salah)
500 Terjadi error internal. Jika terjadi error ini, ajukan tiket bantuan Firebase

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

Setelah mengirimkan update ke template Anda, buka Firebase console untuk memastikan bahwa perubahan Anda muncul seperti yang diharapkan. Hal ini penting karena pengurutan kondisi akan memengaruhi cara kondisi tersebut dievaluasi (kondisi pertama yang mengevaluasi true akan berlaku).

Penggunaan ETag dan update paksa

REST API Remote Config menggunakan tag entitas (ETag) untuk mencegah kondisi race dan update yang tumpang tindih pada resource. Untuk mempelajari ETag lebih lanjut, lihat ETag - HTTP.

Untuk REST API, Google menganjurkan Anda untuk menyimpan ETag yang disediakan oleh perintah GET terbaru ke dalam cache, dan menggunakan nilai ETag tersebut dalam header permintaan If-Match saat mengeluarkan perintah PUT. Jika perintah PUT menghasilkan Kode Status HTTPS 409, Anda harus mengeluarkan perintah GET baru guna memperoleh ETag dan template baru untuk digunakan dengan perintah PUT berikutnya.

Anda bisa mengakali ETag dan perlindungan yang menyertainya dengan memaksakan template Remote Config agar diupdate sebagai berikut: If-Match: * Namun, pendekatan ini tidak direkomendasikan karena berisiko menyebabkan hilangnya update pada template Remote Config Anda saat beberapa klien mengupdate template Remote Config tersebut. Konflik semacam ini dapat terjadi ketika beberapa klien menggunakan API, atau jika update dari klien API bertentangan dengan update dari pengguna Firebase Console.

Untuk mendapatkan panduan tentang cara mengelola versi template Remote Config, baca artikel Pembuatan versi dan template Remote Config.