Menggunakan REST API Remote Config

Dokumen ini menjelaskan bagaimana Anda dapat menggunakan REST API Remote Config untuk membaca dan memodifikasi seperangkat parameter dan kondisi berformat JSON yang dikenal sebagai template Remote Config. Ini memungkinkan Anda untuk mengelola template secara terprogram, melakukan perubahan template di backend yang dapat diambil oleh aplikasi klien dengan menggunakan library klien.

Dengan menggunakan API ini, Anda dapat melompati langkah pengelolaan template di konsol Remote Config dan langsung mengintegrasikan perubahan Remote Config ke dalam proses Anda sendiri. Misalnya, dengan REST API Remote Config, Anda bisa:

  • Menjadwalkan update Remote Config. Dengan menggunakan REST API secara bersamaan dengan cron job, Anda dapat mengubah nilai Remote Config sesuai jadwal berkala.
  • 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 panduan berikut menjelaskan langkah-langkah yang diperlukan untuk mulai menggunakan REST API Remote Config. Jika Anda hanya ingin menjalankan kode dan memeriksanya, lihat salah satu contoh aplikasi yang mendemonstrasikan penggunaan REST API Remote Config:

Memulai dengan menggunakan REST API Remote Config

Langkah-langkah di bagian ini menjelaskan cara mendapatkan dan memodifikasi template Remote Config dengan API.

Langkah 1: Tetapkan nilai di Firebase console

Biasanya, Anda akan mulai dengan menetapkan nilai di Firebase console. Untuk keperluan panduan ini, anggaplah Anda telah menyiapkan aplikasi sampel Quickstart Remote Config untuk iOS atau Android. Untuk aplikasi ini, Anda hanya perlu menambahkan dua parameter berikut ke Firebase console:

Kunci Parameter Nilai Default Catatan
welcome_message Selamat datang di aplikasi contoh ini Ubahlah dengan menggunakan pesan selamat datang yang berbeda.
welcome_message_caps false Setel ke true agar pesan selamat datang ditampilkan dalam huruf kapital semua.

Langkah 2: Dapatkan 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 di lokasi lokal, Anda dapat menggunakan 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 Anda dapat secara eksplisit meneruskan jalur ke kunci akun layanan dalam kode. Opsi pertama lebih aman dan sangat disarankan.

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 kembali.

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 berlaku singkat:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

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 cakupan https://www.googleapis.com/auth/firebase.remoteconfig.

Langkah 3: Dapatkan JSON dari Remote Config dengan API

Selanjutnya, Anda dapat menggunakan API untuk mendapatkan template Remote Config versi aktif saat ini dalam format JSON. Lakukan langkah ini menggunakan perintah berikut, yang akan menggantikan project ID Anda sendiri (tersedia di Panel Setelan Firebase Console) untuk <my-project-id>:

Perintah 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. Contoh berikut menampilkan JSON yang ditampilkan:

{
  "parameters":[
    {
      "key":"welcome_message",
      "value_options":[
        {
          "value":"Welcome to this sample app"
        }
      ]
    },
    {
      "key":"welcome_message_caps",
      "value_options":[
        {
          "value":"false"
        }
      ]
    }
  ],
  "version":{
    "version_number": "42",
    "update_time":"2018-05-11T18:46:40Z",
    "update_user":{
      "name":"Jane Developer",
      "email":"jane@developer.org",
      "imageUrl":"http://image.google.com/path-to-profile-photo-for-jane"
    },
    "description":"Adding welcome messages",
    "update_origin":"CONSOLE",
    "update_type":"INCREMENTAL_UPDATE"
  }
}

Langkah 4: Tambahkan kondisi ke data JSON

Selanjutnya, tambahkan beberapa kondisi dan nilai kondisi yang akan mengupdate aplikasi sampel untuk:

  • Menampilkan pesan yang sedikit berbeda (dengan menambahkan kata "baru") ke 10% pengguna.
  • Menampilkan pesan dalam huruf besar untuk pengguna di Amerika Serikat atau Inggris Raya.

Untuk memperluas JSON dengan cara ini, buat file yang mengandung hal berikut ini:

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

JSON yang ditunjukkan di atas pertama-tama menetapkan serangkaian kondisi, kemudian menetapkan nilai default dan parameter value berbasis kondisi (nilai bersyarat) untuk masing-masing parameter. Tindakan ini juga menambahkan deskripsi opsional untuk setiap elemen. Seperti komentar kode, nilai ini dapat digunakan oleh developer tetapi tidak ditampilkan dalam aplikasi. ETag juga disediakan dalam header terpisah untuk keperluan pengendalian versi.

REST API 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 referensi ekspresi kondisional.

Langkah 5: Publikasikan data JSON untuk mengganti data di Remote Config

Setelah membuat file JSON untuk mengupdate template Remote Config, Anda dapat memublikasikannya dengan menambahkan JSON yang ditunjukkan di atas ke perintah berikut, dan menggantikannya dengan konfigurasi yang ada. Operasi 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.

Untuk perintah curl, Anda dapat menentukan isi file menggunakan karakter "@" diikuti nama file.

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

Perintah 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

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.

Memvalidasi sebelum memublikasikan

Jika ingin, Anda dapat memvalidasi update sebelum memublikasikannya dengan menambahkan parameter URL ?validate_only=true ke permintaan publikasi. Hasilnya, kode status 200 dan etag hasil update dengan akhiran -0 akan menandakan bahwa update berhasil divalidasi. Hasil non-200 menunjukkan bahwa data JSON memuat error yang harus Anda perbaiki sebelum melakukan publikasi.

Kode error

Kode Status Arti
200 Berhasil Diupdate
400 Terjadi error pada validasi. Misalnya, permintaan yang mengandung lebih dari jumlah kunci yang diizinkan—2000—akan menampilkan 400 (Permintaan Buruk) dengan pesan error, Param count too large.
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)
409 Kode Status HTTPS ini dapat terjadi pada dua situasi:
  • Error pada ketidakcocokan versi terjadi karena rangkaian nilai dan kondisi telah diupdate sejak Anda terakhir kali mengambil nilai ETag. 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.
500 Terjadi error internal. Jika terjadi error ini, ajukan tiket bantuan Firebase

Kode status 200 berarti template Remote Config (parameter, nilai, dan kondisi project) telah diupdate, dan kini 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, baca artikel tentang ETag - HTTP.

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.