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 bagaimana Anda dapat membaca dan memodifikasi kumpulan parameter dan ketentuan berformat JSON secara terprogram yang dikenal sebagai template Remote Config . Ini memungkinkan Anda membuat perubahan template di backend yang dapat diambil oleh aplikasi klien menggunakan pustaka klien.

Dengan menggunakan REST API Remote Config atau Admin SDK yang dijelaskan dalam panduan ini, Anda dapat mengabaikan pengelolaan template di Firebase console untuk secara 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 bersama dengan tugas cron, Anda dapat mengubah nilai Remote Config pada jadwal reguler.
  • Nilai konfigurasi impor batch untuk bertransisi 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 berinteraksi dengan fitur baru tersebut.

    Diagram yang menunjukkan backend Remote Config berinteraksi dengan alat dan server khusus

Bagian berikut dari 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 contoh aplikasi berikut:

Ubah Remote Config menggunakan Firebase Admin SDK

Admin SDK adalah kumpulan pustaka server yang memungkinkan Anda berinteraksi dengan Firebase dari lingkungan istimewa. Selain melakukan pembaruan pada Remote Config, Admin SDK memungkinkan pembuatan dan verifikasi token autentikasi Firebase, membaca dan menulis dari Realtime Database, dan sebagainya. Untuk mempelajari lebih lanjut tentang prasyarat dan penyiapan Admin SDK, lihat 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 ketentuan, memvalidasi template, lalu menerbitkannya. 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. Jika tidak, SDK mengasumsikan 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 bahwa setiap versi memiliki masa pakai terbatas dari waktu pembuatannya hingga saat Anda menggantinya dengan pembaruan: 90 hari, dengan batas total 300 versi tersimpan. Lihat Template dan Versi untuk informasi lebih lanjut.

Anda dapat menggunakan API backend untuk mendapatkan versi aktif template Remote Config 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 templatenya:

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

Ubah 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 mempublikasikan template secara eksplisit setelah melakukan modifikasi.

Ubah kondisi Remote Config

Anda dapat memodifikasi dan menambahkan kondisi Remote Config dan nilai bersyarat 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 mempublikasikan 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 kondisi dan operator yang didukung untuk kondisi 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 tag yang salah format. Misalnya, permintaan yang berisi lebih dari jumlah kunci yang diizinkan—2000—akan menampilkan pesan kesalahan, Param count too large .

Publikasikan template Remote Config

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

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

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

  • Personalisasi tidak dapat diimpor dari proyek ke proyek.

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

  • Ketentuan dapat diimpor dari proyek ke proyek, tetapi perhatikan bahwa setiap 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 menetapkan nilai platform iOS , template dapat dipublikasikan ke proyek lain, karena nilai platform sama untuk proyek apa pun. Namun, jika berisi kondisi yang bergantung pada ID aplikasi tertentu atau audiens pengguna yang tidak ada di proyek target, validasi akan gagal.

  • Jika template yang Anda rencanakan untuk diterbitkan berisi ketentuan yang mengandalkan 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());
  }
}

Ubah 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 Anda. Jika Anda mengembangkan kode secara lokal atau menerapkan aplikasi di tempat, Anda dapat menggunakan kredensial yang diperoleh melalui akun layanan ini untuk mengotorisasi permintaan server.

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

Untuk membuat 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 Anda dapat 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 file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini, jadi jika Anda membuka sesi baru, setel variabel lagi.

Linux atau macOS

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

jendela

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) 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 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, pustaka klien Google API mengautentikasi permintaan dengan token web JSON, atau JWT. Untuk informasi selengkapnya, lihat 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

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 bahwa setiap versi memiliki masa pakai terbatas dari waktu pembuatannya hingga saat Anda menggantinya dengan pembaruan: 90 hari, dengan batas total 300 versi tersimpan. Lihat Template dan Versi untuk informasi lebih lanjut.

Dapatkan Template Remote Config saat ini

Anda dapat menggunakan API backend untuk mendapatkan versi aktif template Remote Config 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 mengeluarkan 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 menunjukkan bahwa data JSON berisi kesalahan yang harus Anda perbaiki sebelum dipublikasikan.

Perbarui template Remote Config

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

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

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

  • Personalisasi tidak dapat diimpor dari proyek ke proyek.

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

  • Ketentuan dapat diimpor dari proyek ke proyek, tetapi perhatikan bahwa setiap 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 menetapkan nilai platform iOS , template dapat dipublikasikan ke proyek lain, karena nilai platform sama untuk proyek apa pun. Namun, jika berisi kondisi yang bergantung pada ID aplikasi tertentu atau audiens pengguna yang tidak ada di proyek target, validasi akan gagal.

  • Jika template yang Anda rencanakan untuk diterbitkan berisi ketentuan yang mengandalkan 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.

Ubah kondisi Remote Config

Anda dapat mengubah kondisi dan nilai kondisional 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 menentukan sekumpulan kondisi, lalu mendefinisikan nilai default dan nilai parameter berbasis kondisi ( nilai kondisional ) untuk setiap parameter. Itu juga menambahkan deskripsi opsional untuk setiap elemen; seperti komentar kode, ini untuk penggunaan pengembang dan tidak ditampilkan di aplikasi. Sebuah 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 kondisi dan operator yang didukung untuk kondisi 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 . Selain itu, Kode Status HTTPS ini dapat terjadi dalam dua situasi berikut:
  • Terjadi galat ketidakcocokan versi karena kumpulan nilai dan ketentuan telah diperbarui sejak terakhir kali Anda mengambil nilai ETag. Untuk mengatasi ini, Anda harus menggunakan perintah GET untuk mendapatkan template baru dan nilai ETag, memperbarui template, lalu mengirimkan menggunakan template itu dan nilai ETag baru.
  • Perintah PUT (Perbarui permintaan template Remote Config) dibuat tanpa menentukan header If-Match .
401 Terjadi kesalahan otorisasi (tidak ada token akses yang diberikan atau REST API Firebase Remote Config belum ditambahkan ke proyek Anda di Cloud Developer Console)
403 Terjadi kesalahan otentikasi (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 proyek) telah diperbarui dan sekarang tersedia untuk aplikasi yang menggunakan proyek 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. Hal ini penting karena pengurutan kondisi mempengaruhi bagaimana 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 pada sumber daya. Untuk mempelajari lebih lanjut tentang ETag, lihat ETag - HTTP .

Untuk REST API, Google menyarankan Anda untuk menyimpan 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 memperoleh ETag dan template baru untuk digunakan dengan perintah PUT berikutnya.

Anda dapat menghindari ETag, dan perlindungan yang diberikannya, 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 beberapa klien memperbarui template Remote Config. Konflik semacam ini dapat terjadi dengan beberapa klien yang menggunakan API, atau dengan update yang bentrok dari klien API dan pengguna konsol Firebase.

Untuk panduan tentang mengelola versi template Remote Config, lihat template dan versi Remote Config .