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 Remote Config REST API atau Admin SDK yang dijelaskan dalam panduan ini, Anda tidak perlu melakukan pengelolaan template di Firebase console untuk mengintegrasikan perubahan Remote Config langsung ke dalam proses Anda sendiri. Misalnya, dengan API backend Remote Config, Anda dapat:
- Menjadwalkan pembaruan Remote Config. Dengan menggunakan panggilan API bersamaan dengan cron job, Anda dapat mengubah value Remote Config secara rutin.
- Mengimpor nilai konfigurasi dalam batch agar dapat melakukan transisi secara efisien dari sistem milik Anda ke Firebase Remote Config.
Menggunakan 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-bagian berikut dalam panduan ini menjelaskan operasi yang dapat Anda lakukan dengan API backend Remote Config. Untuk meninjau beberapa kode yang melakukan tugas tersebut melalui REST API ini, lihat salah satu aplikasi contoh berikut:
- Panduan memulai Java Firebase Remote Config REST API
- Panduan memulai Node.js Firebase Remote Config REST API
- Panduan memulai Python Firebase Remote Config REST API
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 pembaruan ke Remote Config, Admin SDK memungkinkan pembuatan dan verifikasi token autentikasi Firebase, 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.
Dalam alur Remote Config biasa, Anda bisa mendapatkan template saat ini, mengubah beberapa parameter atau grup parameter dan kondisi, memvalidasi template, lalu memublikasikannya. Sebelum melakukan panggilan API tersebut, Anda harus mengizinkan 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.
Contoh:
Node.js
const admin = require('firebase-admin');
admin.initializeApp();Java
FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.fromStream(serviceAccount))
.build();
FirebaseApp.initializeApp(options);Mendapatkan Template Remote Config saat ini
Saat menggunakan template Remote Config, perhatikan bahwa template tersebut berversi, dan setiap versi memiliki masa pakai terbatas sejak pembuatannya hingga 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 template Remote Config yang aktif saat ini dalam format JSON.
Parameter dan parameter value yang dibuat khusus sebagai varian dalam eksperimen A/B Testing tidak disertakan dalam template yang diekspor.
Untuk mendapatkan template:
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);
});
}Java
Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());Mengubah parameter Remote Config
Anda dapat mengubah dan menambahkan parameter dan grup parameter Remote Config secara terprogram. Misalnya, Anda dapat menambahkan parameter untuk mengontrol tampilan informasi musiman ke grup parameter yang sudah ada yang bernama "new_menu":
Node.js
function addParameterToGroup(template) {
template.parameterGroups['new_menu'].parameters['spring_season'] = {
defaultValue: {
useInAppDefault: true
},
description: 'spring season menu visibility.',
};
}Java
template.getParameterGroups().get("new_menu").getParameters()
.put("spring_season", new Parameter()
.setDefaultValue(ParameterValue.inAppDefault())
.setDescription("spring season menu visibility.")
);API ini memungkinkan Anda membuat parameter dan grup parameter baru, atau mengubah nilai default, nilai kondisional, 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 value kondisional Remote Config 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',
});
}Java
template.getConditions().add(new Condition("android_en",
"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 lebih lanjut kondisi dan operator yang didukung untuk kondisi ini, baca referensi ekspresi kondisional.
Memvalidasi template Remote Config
Secara opsional, Anda dapat memvalidasi pembaruan 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);
});
}Java
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 mencari 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 kunci lebih banyak daripada yang diizinkan (jumlah maksimal 2.000) akan menampilkan pesan error, Param count too large.
Memublikasikan template Remote Config
Setelah mengambil template dan merevisinya dengan pembaruan yang diinginkan, Anda dapat memublikasikannya. Memublikasikan template seperti yang dijelaskan di bagian ini berarti mengganti seluruh template konfigurasi yang ada dengan file yang telah diperbarui, dan template aktif yang baru diberi nomor versi satu angka lebih besar daripada template yang digantikannya.
Jika perlu, Anda dapat menggunakan REST API ini untuk melakukan roll back ke versi sebelumnya. Untuk mengurangi risiko error dalam pembaruan, Anda dapat melakukan validasi sebelum melakukan publikasi.
Personalisasi dan kondisi Remote Config termasuk dalam template yang didownload. Oleh karena itu, penting untuk mengetahui batasan berikut saat mencoba melakukan publikasi ke project yang berbeda:
Personalisasi tidak dapat diimpor dari satu project ke project lain.
Misalnya, setelah mengaktifkan personalisasi di project serta mendownload dan mengedit template, Anda dapat memublikasikan personalisasi tersebut ke project yang sama. Namun, personalisasi tidak dapat dipublikasikan ke project yang berbeda kecuali jika Anda menghapusnya dari template.
Kondisi dapat diimpor dari satu project ke project lain. Namun, perlu diperhatikan bahwa setiap nilai bersyarat tertentu (seperti ID aplikasi atau audience) harus ada dalam project target sebelum dipublikasikan.
Misalnya, jika Anda memiliki parameter Remote Config yang menggunakan kondisi yang menentukan nilai platform
iOS, template dapat dipublikasikan ke project lain. Ini dikarenakan nilai platform sama untuk project apa pun. Namun, jika parameter tersebut berisi kondisi yang bergantung pada ID aplikasi atau audience pengguna tertentu yang tidak ada dalam project target, validasi akan gagal.Jika template yang akan Anda publikasikan berisi kondisi yang bergantung pada Google Analytics, Analytics harus diaktifkan di project 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);
});
}Java
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());
}
}Mengubah Remote Config menggunakan REST API
Bagian ini menjelaskan kemampuan utama Remote Config REST API di https://firebaseremoteconfig.googleapis.com.
Untuk mengetahui detail selengkapnya, baca referensi API.
Mendapatkan token akses untuk mengautentikasi dan mengizinkan 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 bagi akun layanan Anda:
Di Firebase console, buka Settings > Service Accounts.
Klik Generate New Private Key, lalu konfirmasikan dengan mengklik Generate Key.
Simpan dengan aman file JSON yang memuat kunci tersebut.
Saat Anda memberi otorisasi melalui akun layanan, ada dua opsi untuk menyediakan kredensial ke aplikasi. Anda dapat menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, atau secara eksplisit meneruskan jalur ke 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 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 menjalankan di lingkungan non-Google.
Gunakan kredensial Firebase Anda beserta Library Google Auth untuk bahasa pilihan Anda guna mengambil token akses OAuth 2.0 yang memiliki masa aktif singkat:
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 yang disebut 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
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();
}
Setelah masa berlaku token akses berakhir, metode refresh token akan otomatis dipanggil untuk mengambil token akses yang telah diperbarui.
Untuk memberikan akses ke Remote Config, mintalah cakupan https://www.googleapis.com/auth/firebase.remoteconfig.
Mengubah template Remote Config
Saat menggunakan template Remote Config, perhatikan bahwa template tersebut berversi, dan setiap versi memiliki masa pakai terbatas sejak pembuatannya hingga 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 template Remote Config yang aktif saat ini dalam format JSON.
Parameter dan parameter value yang dibuat khusus sebagai varian dalam eksperimen A/B Testing tidak disertakan dalam template yang diekspor.
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 menghasilkan payload JSON dalam sebuah file, dan headernya (termasuk ETag) dalam file lain.
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 pembaruan sebelum memublikasikannya.
Validasi pembaruan template dapat dilakukan dengan menambahkan parameter URL ?validate_only=true ke permintaan publikasi Anda.
Dalam responsnya, kode status 200 dan ETag yang diperbarui dengan akhiran -0 akan menandakan bahwa pembaruan berhasil divalidasi. Respons selain 200 menunjukkan bahwa data JSON berisi error yang harus Anda perbaiki sebelum melakukan publikasi.
Memperbarui template Remote Config
Setelah mengambil template dan merevisi konten JSON dengan pembaruan yang diinginkan, Anda dapat memublikasikannya. Memublikasikan template seperti yang dijelaskan di bagian ini berarti mengganti seluruh template konfigurasi yang ada dengan file yang telah diperbarui, dan template aktif yang baru diberi nomor versi satu angka lebih besar daripada template yang digantikannya.
Jika perlu, Anda dapat menggunakan REST API ini untuk melakukan roll back ke versi sebelumnya. Untuk mengurangi risiko error dalam pembaruan, Anda dapat melakukan validasi sebelum melakukan publikasi.
Personalisasi dan kondisi Remote Config termasuk dalam template yang didownload. Oleh karena itu, penting untuk mengetahui batasan berikut saat mencoba melakukan publikasi ke project yang berbeda:
Personalisasi tidak dapat diimpor dari satu project ke project lain.
Misalnya, setelah mengaktifkan personalisasi di project serta mendownload dan mengedit template, Anda dapat memublikasikan personalisasi tersebut ke project yang sama. Namun, personalisasi tidak dapat dipublikasikan ke project yang berbeda kecuali jika Anda menghapusnya dari template.
Kondisi dapat diimpor dari satu project ke project lain. Namun, perlu diperhatikan bahwa setiap nilai bersyarat tertentu (seperti ID aplikasi atau audience) harus ada dalam project target sebelum dipublikasikan.
Misalnya, jika Anda memiliki parameter Remote Config yang menggunakan kondisi yang menentukan nilai platform
iOS, template dapat dipublikasikan ke project lain. Ini dikarenakan nilai platform sama untuk project apa pun. Namun, jika parameter tersebut berisi kondisi yang bergantung pada ID aplikasi atau audience pengguna tertentu yang tidak ada dalam project target, validasi akan gagal.Jika template yang akan Anda publikasikan berisi kondisi yang bergantung pada Google Analytics, Analytics harus diaktifkan di project target.
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 diperbarui akan diberikan dalam header respons perintah PUT berikutnya.
Mengubah kondisi Remote Config
Anda dapat mengubah kondisi dan nilai kondisional Remote Config secara terprogram. Dengan REST API ini, 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 nilai berbasis kondisi (nilai kondisional) untuk tiap parameter. Modifikasi tersebut juga menambahkan deskripsi opsional untuk setiap elemen; seperti komentar kode, yang ditujukan bagi 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 lebih lanjut kondisi dan operator yang didukung untuk kondisi ini, baca referensi ekspresi kondisional.
Kode Error HTTP
| Kode Status | Arti |
|---|---|
| 200 | Berhasil Diperbarui |
| 400 | Terjadi error pada validasi. Misalnya, permintaan yang berisi kunci lebih banyak daripada yang diizinkan (jumlah maksimal 2.000) akan menampilkan 400 (Permintaan Tidak Valid) dengan pesan error, Param count too large.
Selain itu, Kode Status HTTPS ini dapat terjadi dalam dua situasi berikut:
|
| 401 | Terjadi error pada otorisasi (tidak ada token akses yang diberikan atau Firebase Remote Config REST API 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 kondisi untuk project) telah diperbarui dan sekarang tersedia untuk aplikasi yang menggunakan project ini. Kode status lainnya menunjukkan bahwa template Remote Config yang ada sebelumnya masih berlaku.
Setelah mengirimkan pembaruan 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 pembaruan paksa
Remote Config REST API menggunakan tag entity (ETag) untuk mencegah kondisi race dan pembaruan resource yang tumpang tindih. Untuk mempelajari ETag lebih lanjut, lihat ETag - HTTP.
Untuk REST API ini, 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 diberikannya dengan
memaksa template Remote Config agar diperbarui sebagai berikut: If-Match: *
Namun, pendekatan ini tidak direkomendasikan karena berisiko menyebabkan hilangnya
pembaruan template Remote Config Anda saat beberapa klien memperbarui
template Remote Config tersebut. Konflik semacam ini dapat terjadi ketika beberapa klien menggunakan API ini, atau jika pembaruan dari klien API bertentangan dengan pembaruan dari pengguna Firebase console.
Untuk mendapatkan panduan mengelola versi template Remote Config, baca artikel Pembuatan versi dan template Remote Config.