Mengelola template dan pembuatan versi klien Remote Config

Template Remote Config adalah serangkaian parameter dan kondisi berformat JSON yang dibuat untuk project Firebase Anda. Template klien menyajikan konfigurasi ke instance aplikasi yang menerapkan SDK klien Firebase untuk Remote Config, termasuk aplikasi Apple, Android, Web, Flutter, Unity, dan C++.

Anda dapat menggunakan konsol Firebase untuk mengubah dan mengelola template klien. Buka DevOps & Engagement > Remote Config untuk melihat konten template dalam format grafis di halaman Parameters dan Conditions.

Anda juga dapat menggunakan Remote Config REST API dan Admin SDK atau Firebase CLI untuk mengubah dan mengelola template klien.

Berikut adalah contoh file template klien:

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

Anda dapat melakukan tugas pengelolaan versi berikut di konsol Firebase (buka DevOps & Engagement > Remote Config):

• Mencantumkan semua versi template tersimpan
• Mengambil versi tertentu
• Melakukan roll back ke versi klien tertentu
• Menghapus template Remote Config dari halaman Change history.

Anda juga dapat mencantumkan template, mengambil template, dan melakukan roll back pada template menggunakan Firebase CLI dan Remote Config backend API.

Batas total versi masa aktif yang tersimpan per jenis template adalah 300 (300 template klien dan 300 template server), yang meliputi nomor versi tersimpan untuk template yang dihapus. Jika Anda memublikasikan lebih dari 300 versi template per jenis template selama masa aktif project, versi paling awal akan dihapus, sehingga mempertahankan jumlah maksimum 300 versi untuk jenis tersebut.

Setiap kali Anda mengupdate parameter, Remote Config akan 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 berurutan dari nilai awal yang disimpan oleh Remote Config. Semua template menyertakan kolom version seperti yang ditunjukkan, yang berisi metadata tentang versi spesifik tersebut.

Anda dapat menghapus template Remote Config sesuai kebutuhan di DevOps & Engagement > Remote Config > Change history page di konsol Firebase.

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, lihat Mengubah Remote Config secara terprogram.

Mencantumkan semua versi template Remote Config yang tersimpan

Anda dapat mengambil daftar semua versi template Remote Config yang disimpan. Untuk melakukannya:

firebase remoteconfig:versions:list

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

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

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

Daftar template ini mencakup metadata untuk semua versi tersimpan, termasuk waktu update, pengguna yang melakukannya, dan bagaimana hal tersebut dilakukan. 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. Berikut cara mengambil versi template tersimpan:

firebase remoteconfig:get -v VERSION_NUMBER

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

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

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

Melakukan roll back ke versi template Remote Config tertentu yang tersimpan

Anda dapat melakukan roll back ke versi template yang tersimpan. Berikut cara me-roll back template:

firebase remoteconfig:rollback -v VERSION_NUMBER

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

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

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

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, yang akan membuat versi 11 menjadi template aktif.

Menghapus template Remote Config

Anda dapat menghapus template Remote Config menggunakan Firebase console. Berikut cara menghapus template:

1. Di konsol Firebase, buka DevOps & Engagement > Remote Config > Parameters page.

2. Klik history Histori perubahan.

3. Alihkan ke template yang ingin Anda hapus, klik more_vert Lainnya, lalu pilih Hapus.

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

Misalnya, 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.

Untuk mengekspor dan mengimpor template Remote Config:

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

Mendownload template Remote Config saat ini

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

firebase remoteconfig:get -o filename

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

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

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

Memvalidasi template Remote Config

Anda dapat memvalidasi update 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.

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

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

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

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:

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

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

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

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 nilai kondisional 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 semua project. 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 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.

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

Berikut cara mendownload file yang berisi template default:

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

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

• Menetapkan parameter value default dalam aplikasi untuk Android

• Menetapkan parameter value default dalam aplikasi untuk iOS

• Menetapkan parameter value default dalam aplikasi untuk Web

• Menetapkan parameter value default dalam aplikasi untuk Unity

• Menetapkan parameter value default dalam aplikasi untuk C++