Pembuatan Versi dan Template Remote Config

Template Remote Config adalah serangkaian parameter dan kondisi berformat JSON di sisi server yang telah Anda buat untuk project Firebase. Anda dapat mengubah dan mengelola template ini menggunakan Firebase console yang akan menampilkan konten template dalam format grafis di tab Parameters dan Conditions. Anda juga dapat menggunakan Remote Config REST API dan Admin SDK atau Firebase CLI untuk mengubah dan mengelola konfigurasi.

Berikut contoh file template:

  {
    "conditions": [
      {
        "name": "ios",
        "expression": "device.os == 'ios'"
      }
    ],
    "parameters": {
      "welcome_message": {
        "defaultValue": {
          "value": "Welcome to this sample app"
        },
        "conditionalValues": {
          "ios": {
            "value": "Welcome to this sample iOS app"
          }
        }
      },
      "welcome_message_caps": {
        "defaultValue": {
          "value": "false"
        }
      },
      "header_text": {
        "defaultValue": {
          "useInAppDefault": true
        }
      }
    },
    "version": {
      "versionNumber": "28",
      "updateTime": "2020-05-14T18:39:38.994Z",
      "updateUser": {
        "email": "user@google.com"
      },
      "updateOrigin": "CONSOLE",
      "updateType": "INCREMENTAL_UPDATE"
    }
  }

Setiap kali Anda memperbarui parameter, Remote Config membuat template Remote Config versi baru dan menyimpan template sebelumnya sebagai versi yang dapat Anda ambil atau roll back sesuai kebutuhan. Nomor versi bertambah secara urut dari nilai awal yang disimpan oleh Remote Config. Semua template menyertakan kolom version seperti yang ditunjukkan, yang berisi metadata tentang versi spesifik tersebut.

Dengan API backend Firebase console, Firebase CLI, atau Remote Config, Anda dapat melakukan tugas pengelolaan versi berikut:

  • Mencantumkan semua versi template tersimpan
  • Mengambil versi tertentu
  • Melakukan roll back ke versi tertentu

Anda dapat menghapus template Remote Config sesuai kebutuhan dari halaman Change history di konsol Remote Config. Batas total versi masa aktif yang tersimpan adalah 300. Hal ini meliputi nomor versi tersimpan untuk template yang dihapus. Jika Anda memublikasikan lebih dari 300 versi template selama masa aktif project, versi paling awal akan dihapus, sehingga mempertahankan maksimum 300 versi.

Mengelola versi template Remote Config

Bagian ini menjelaskan cara mengelola versi template Remote Config. Untuk mengetahui detail selengkapnya tentang cara membuat, mengubah, dan menyimpan template secara terprogram, baca artikel Mengubah Remote Config secara terprogram.

Mencantumkan semua versi tersimpan template Remote Config

Anda dapat mengambil daftar semua versi tersimpan template Remote Config. Contoh:

Node.js

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

Java

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

REST

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

Firebase console

Di tab Parameters, pilih ikon "jam" yang ditampilkan di kanan atas. Tindakan ini akan membuka halaman Change history yang mencantumkan semua versi template tersimpan di menu daftar di sebelah kanan.

Detail yang ditampilkan untuk setiap versi tersimpan berisi informasi tentang apakah perubahan berasal dari Console, dengan REST API, dari rollback, atau apakah perubahan tersebut merupakan perubahan inkremental dari penyimpanan template yang dipaksa.

Firebase CLI

firebase remoteconfig:versions:list

Gunakan opsi --limit untuk membatasi jumlah versi yang ditampilkan. Teruskan '0' untuk mengambil semua versi.

Daftar template ini mencakup metadata untuk semua versi tersimpan, termasuk waktu update, pengguna yang melakukannya, dan apakah update dilakukan melalui konsol atau REST API. Berikut adalah contoh elemen versi:

{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]

Mengambil versi template Remote Config tertentu

Anda dapat mengambil versi template Remote Config tertentu yang tersimpan. Contoh:

Node.js

Teruskan getTemplate() tanpa argumen apa pun untuk mengambil versi terbaru template. Untuk mengambil versi tertentu, gunakan getTemplateAtVersion().

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

REST

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6

Parameter URL ?version_number hanya valid untuk operasi GET; Anda tidak dapat menggunakannya untuk menentukan nomor versi untuk update. Permintaan get yang serupa tanpa parameter ?version_number akan mengambil template aktif saat ini.

Firebase console

Secara default, panel detail di tab Change history menampilkan template aktif saat ini. Untuk melihat detail dari versi lain dalam daftar, pilih dari menu di sebelah kanan.

Anda dapat melihat perbedaan terperinci dari versi yang saat ini dipilih dan versi lain yang tersimpan dengan mengarahkan kursor ke menu konteks untuk setiap versi yang tidak dipilih dan memilih Compare with selected version.

Firebase CLI

firebase remoteconfig:get -v VERSION_NUMBER

Jika ingin, Anda dapat menulis output ke file tertentu dengan -o, FILENAME.

Melakukan roll back ke template Remote Config tersimpan versi tertentu

Anda dapat melakukan roll back ke versi template yang tersimpan. Contoh:

Node.js

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

Java

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

REST

Untuk melakukan roll back ke salah satu template Remote Config tersimpan, keluarkan HTTP POST dengan metode kustom :rollback dan, dalam isi permintaan, tetapkan versi tertentu yang ingin diterapkan. Contoh:

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

Respons ini berisi konten dari template tersimpan yang aktif saat ini, dengan metadata versi barunya.

Firebase console

Untuk beralih ke versi template sebelumnya yang memenuhi syarat untuk rollback, tombol opsi untuk roll back ke versi tersebut ditampilkan di kanan atas halaman Change history. Klik dan konfirmasi tombol ini hanya jika Anda yakin ingin melakukan rollback ke versi itu dan gunakan nilai tersebut segera untuk semua aplikasi dan pengguna.

Firebase CLI

firebase remoteconfig:rollback -v VERSION_NUMBER

Perhatikan bahwa operasi rollback ini secara efektif membuat versi bernomor baru. Misalnya, melakukan roll back dari versi 10 ke versi 6 akan menghasilkan salinan baru untuk versi 6, yang berbeda dari aslinya hanya pada nomor versinya, yaitu 11. Versi 6 yang asli masih disimpan, dengan asumsi bahwa akhir masa berlakunya belum tercapai, dan akan membuat versi 11 menjadi template aktif.

Menghapus template Remote Config

Anda dapat menghapus template Remote Config dari Firebase console. Untuk menghapus template Remote Config:

  1. Dari halaman Parameters Remote Config, klik Change history.

  2. Alihkan ke template yang ingin Anda hapus, klik More, lalu pilih Delete.

  3. Saat diminta untuk mengonfirmasi penghapusan, klik Delete.

Mendownload dan memublikasikan template Remote Config

Download dan publikasikan template Remote Config untuk mengintegrasikannya ke dalam kontrol sumber dan sistem build, mengotomatiskan update konfigurasi, serta menjaga parameter dan nilai tetap sinkron di beberapa project.

Anda dapat mendownload template Remote Config yang saat ini aktif secara terprogram atau dari Firebase console. Selanjutnya, Anda dapat memperbarui file JSON yang diekspor dan memublikasikannya ke project yang sama, atau memublikasikannya ke project baru atau yang sudah ada.

Sebagai contoh, Anda memiliki beberapa project yang mewakili berbagai tahap siklus proses pengembangan software, seperti lingkungan pengembangan, pengujian, staging, dan produksi. Dalam hal ini, Anda dapat mempromosikan template yang telah diuji sepenuhnya dari lingkungan staging ke lingkungan produksi dengan mendownloadnya dari project staging dan memublikasikannya ke project produksi.

Anda juga dapat menggunakan metode ini untuk memigrasikan konfigurasi dari satu project ke project lainnya, atau mengisi project baru dengan parameter dan nilai dari project yang sudah stabil.

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

Cara mengekspor dan mengimpor template Remote Config:

  1. Download template Remote Config saat ini.
  2. Validasikan template Remote Config.
  3. Publikasikan template Remote Config.

Mendownload Template Remote Config saat ini

Anda dapat mendownload template Remote Config yang saat ini aktif secara terprogram, atau menggunakan Firebase console.

Gunakan perintah berikut untuk mendownload template Remote Config yang aktif dalam format JSON:

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

REST

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 headers lain.

Firebase console

  1. Dari tab Remote Config Parameters or Conditions, buka Menu, lalu pilih Download current config file.
  2. Saat diminta, klik Download config file, pilih lokasi yang diinginkan untuk menyimpan file, lalu klik Save.

Firebase CLI

firebase remoteconfig:get -o filename

Memvalidasi template Remote Config

Anda dapat memvalidasi pembaruan template sebelum memublikasikannya menggunakan Firebase Admin SDK atau REST API. Template juga divalidasi saat Anda mencoba memublikasikan konten dari Firebase CLI atau Firebase console.

Proses validasi template ini mencari error, antara lain kunci duplikat untuk parameter dan kondisi, nama kondisi tidak valid atau tidak ada kondisi, 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.

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

REST

Validasikan pembaruan template dengan menambahkan parameter URL ?validate_only=true ke permintaan publikasi Anda:

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?validate_only=true -d @filename

Jika template Anda berhasil divalidasi, perintah curl akan menampilkan template JSON yang Anda kirimkan. Kemudian, dalam file headers yang tersimpan, Anda akan menemukan status HTTP/2 200 dan ETag yang sudah diperbarui dengan akhiran -0. Jika template tidak divalidasi, Anda akan menerima error validasi dalam respons JSON dan file headers Anda akan berisi respons non-200 (dan tidak ada ETag).

Memublikasikan template Remote Config

Setelah mendownload template, melakukan perubahan yang diperlukan pada konten JSON, dan memvalidasinya, Anda dapat memublikasikannya ke project.

Memublikasikan template berarti mengganti seluruh template konfigurasi yang ada dengan file yang telah diperbarui dan menambahkan versi template satu per satu. Karena seluruh konfigurasi diganti, jika Anda menghapus parameter dari file JSON dan memublikasikannya, parameter akan dihapus dari server dan tidak lagi tersedia untuk klien.

Setelah dipublikasikan, perubahan pada parameter dan nilai akan segera tersedia untuk aplikasi dan pengguna Anda. Jika perlu, Anda dapat melakukan roll back ke versi sebelumnya.

Gunakan perintah berikut untuk memublikasikan template Anda:

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

REST

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.

Firebase console

  1. Dari tab Remote Config Parameters or Conditions, buka Menu, lalu pilih Publish from a file.
  2. Saat diminta, klik Browse, buka dan pilih file Remote Config yang ingin Anda publikasikan, lalu klik Select.
  3. File akan divalidasi dan, jika berhasil, Anda dapat mengklik Publish agar konfigurasi bisa langsung tersedia bagi aplikasi dan pengguna Anda.

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.

Mendownload nilai default template Remote Config

Karena aplikasi mungkin tidak selalu terhubung ke internet, Anda harus mengonfigurasi nilai default aplikasi sisi klien untuk semua parameter Remote Config. Anda juga harus menyinkronkan nilai default klien aplikasi dan parameter value default backend Remote Config secara berkala karena nilai tersebut dapat berubah dari waktu ke waktu.

Seperti yang dijelaskan pada link khusus platform di akhir bagian ini, Anda dapat menetapkan default ini secara manual di aplikasi atau menyederhanakan proses ini dengan mendownload file yang hanya berisi key-value pair untuk semua parameter dan nilai defaultnya di template Remote Config yang aktif. Selanjutnya, Anda dapat menyertakan file ini dalam project dan mengonfigurasi aplikasi untuk mengimpor nilai ini.

Anda dapat mendownload file ini dalam format XML untuk aplikasi Android, format daftar properti (plist) untuk aplikasi iOS, dan JSON untuk aplikasi web.

Sebaiknya download default Remote Config secara berkala sebelum rilis aplikasi baru, untuk memastikan aplikasi dan backend Remote Config tetap sinkron.

Untuk mendownload file yang berisi template default:

REST

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

Gunakan XML, PLIST, atau JSON sebagai nilai format, bergantung pada format file yang ingin Anda download.

Firebase console

  1. Di tab Parameters, buka Menu, lalu pilih Download default values.
  2. Jika diminta, klik tombol pilihan yang sesuai dengan format file yang ingin didownload, lalu klik Download file.

Untuk mengetahui informasi lebih lanjut tentang cara mengimpor nilai default Remote Config ke aplikasi, lihat: