Zarządzanie szablonami klienta Zdalnej konfiguracji i obsługą wersji

Szablony Remote Config to zestawy parametrów i warunków w formacie JSON utworzone na potrzeby projektu w Firebase. Szablony klienta udostępniają konfiguracje instancjom aplikacji, które implementują pakiety SDK klienta Firebase dla Remote Config, w tym aplikacji na urządzenia Apple i z Androidem, aplikacji internetowych oraz aplikacji Flutter, Unity i C++.

Możesz używać konsoli Firebase, aby modyfikować szablon klienta i nim zarządzać. Kliknij DevOps i zaangażowanie > Zdalna konfiguracja, aby wyświetlić zawartość szablonu w formacie graficznym na stronach Parametry i Warunki.

Do modyfikowania szablonu klienta i zarządzania nim możesz też używać interfejsu API REST Remote Config i Admin SDK lub interfejsu wiersza poleceń Firebase.

Oto przykład pliku szablonu klienta:

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

Te zadania związane z zarządzaniem wersjami możesz wykonywać w konsoli Firebase (kliknij DevOps i zaangażowanie > Zdalna konfiguracja):

• Wyświetlanie listy wszystkich zapisanych wersji szablonów
• Pobieranie konkretnej wersji
• Przywracanie określonej wersji klienta
• Usuń Remote Config szablony na stronie Historia zmian.

Możesz też wyświetlać, pobierać i przywracać szablony za pomocą interfejsu wiersza poleceń Firebase i interfejsów API backendu Remote Config.

Obowiązuje łączny limit 300 zapisanych wersji na typ szablonu (300 szablonów klienta i 300 szablonów serwera), który obejmuje numery zapisanych wersji usuniętych szablonów. Jeśli w trakcie cyklu życia projektu opublikujesz więcej niż 300 wersji szablonu danego typu, najstarsze wersje zostaną usunięte, aby zachować maksymalnie 300 wersji tego typu.

Za każdym razem, gdy aktualizujesz parametry, Remote Config tworzy nowy szablon Remote Config z numerem wersji i zapisuje poprzedni szablon jako wersję, którą możesz pobrać lub przywrócić w razie potrzeby. Numery wersji są zwiększane sekwencyjnie od wartości początkowej przechowywanej przez Remote Config. Wszystkie szablony zawierają pole version, jak pokazano na ilustracji, które zawiera metadane dotyczące danej wersji.

W razie potrzeby możesz usunąć szablony Remote Config na stronie DevOps i zaangażowanie > Zdalna konfiguracja > Historia zmian w konsoli Firebase.

Zarządzanie wersjami szablonu Remote Config

W tej sekcji opisano, jak zarządzać wersjami szablonu Remote Config.

Więcej informacji o programowym tworzeniu, modyfikowaniu i zapisywaniu szablonów znajdziesz w artykule Modyfikowanie Remote Config za pomocą kodu.

Wyświetl listę wszystkich zapisanych wersji szablonu Remote Config

Możesz pobrać listę wszystkich zapisanych wersji szablonu Remote Config. Aby to zrobić:

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

Lista szablonów zawiera metadane wszystkich zapisanych wersji, w tym czas aktualizacji, użytkownika, który ją wprowadził, oraz sposób jej wprowadzenia. Oto przykład elementu wersji:

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

Pobieranie konkretnej wersji szablonu Remote Config

Możesz pobrać dowolną zapisaną wersję szablonu Remote Config. Aby pobrać zapisaną wersję szablonu:

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

Przywracanie określonej zapisanej wersji szablonu Remote Config

Możesz przywrócić dowolną zapisaną wersję szablonu. Aby przywrócić szablon:

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}'

Pamiętaj, że ta operacja przywracania powoduje utworzenie nowej wersji numerowanej. Na przykład przywrócenie wersji 6 z wersji 10 powoduje utworzenie nowej kopii wersji 6, która różni się od oryginału tylko tym, że jej numer wersji to 11. Oryginalna wersja 6 jest nadal przechowywana, o ile nie wygasła, a wersja 11 staje się aktywnym szablonem.

Usuwanie szablonu Remote Config

Szablony Remote Config możesz usunąć za pomocą konsoli Firebase. Aby usunąć szablon:

1. W konsoli Firebase otwórz stronę DevOps i zaangażowanie > Zdalna konfiguracja > Parametry.

2. Kliknij history Historia zmian.

3. Przejdź do szablonu, który chcesz usunąć, kliknij more_vert Więcej, a następnie wybierz Usuń.

4. Gdy pojawi się prośba o potwierdzenie usunięcia, kliknij Usuń.

Pobieranie i publikowanie szablonów Remote Config

Pobierz i opublikuj szablony Remote Config, aby zintegrować je z systemami kontroli źródła i kompilacji, zautomatyzować aktualizacje konfiguracji oraz synchronizować parametry i wartości w wielu projektach.

Obecnie aktywny szablon Remote Config możesz pobrać automatycznie lub z konsoli Firebase. Następnie możesz zaktualizować wyeksportowany plik JSON i opublikować go w tym samym projekcie lub w nowym albo istniejącym projekcie.

Załóżmy na przykład, że masz kilka projektów, które reprezentują różne etapy cyklu życia oprogramowania, takie jak środowiska programistyczne, testowe, przejściowe i środowiska produkcyjne. W takim przypadku możesz przenieść w pełni przetestowany szablon ze środowiska przejściowego do środowiska produkcyjnego, pobierając go z projektu przejściowego i publikując w projekcie produkcyjnym.

Możesz też użyć tej metody, aby przenieść konfiguracje z jednego projektu do innego lub wypełnić nowy projekt parametrami i wartościami z utworzonego projektu.

Parametry i wartości parametrów utworzone specjalnie jako warianty w eksperymencie A/B Testing nie są uwzględniane w wyeksportowanych szablonach.

Aby wyeksportować i zaimportować szablony Remote Config:

1. Pobierz bieżący szablon Remote Config.
2. Sprawdź poprawność szablonu Remote Config.
3. Opublikuj szablon Remote Config.

Pobierz bieżący szablon Remote Config

Aby pobrać aktywny szablon Remote Config w formacie JSON, użyj tego polecenia:

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

Sprawdzanie poprawności szablonu Remote Config

Zanim opublikujesz aktualizacje szablonu, możesz je sprawdzić za pomocą Firebase Admin SDK lub interfejsu API typu REST. Szablony są też sprawdzane, gdy próbujesz je opublikować za pomocą interfejsu wiersza poleceń Firebase lub konsoli Firebase.

Proces sprawdzania poprawności szablonu wykrywa błędy, takie jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki albo nieprawidłowo sformatowane tagi ETag. Na przykład żądanie zawierające więcej niż dozwoloną liczbę kluczy (2000) zwróci komunikat o błędzie 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

Publikowanie szablonu Remote Config

Po pobraniu szablonu, wprowadzeniu niezbędnych zmian w zawartości JSON i zweryfikowaniu go możesz opublikować go w projekcie.

Opublikowanie szablonu powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem i zwiększenie wersji szablonu o 1. Ponieważ zastępowana jest cała konfiguracja, jeśli usuniesz parametr z pliku JSON i go opublikujesz, parametr zostanie usunięty z serwera i nie będzie już dostępny dla klientów.

Po opublikowaniu zmiany parametrów i wartości są natychmiast dostępne dla aplikacji i użytkowników. W razie potrzeby możesz przywrócić poprzednią wersję.

Aby opublikować szablon, użyj tych poleceń:

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

Personalizacje i warunki Remote Config są uwzględniane w pobranych szablonach, dlatego podczas próby opublikowania w innym projekcie należy pamiętać o tych ograniczeniach:

• Personalizacji nie można importować między projektami.

  Jeśli na przykład masz włączone personalizacje w projekcie i pobierzesz oraz zmodyfikujesz szablon, możesz go opublikować w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, chyba że usuniesz personalizacje z szablonu.

• Warunki można importować z jednego projektu do drugiego, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny istnieć określone wartości warunkowe (np. identyfikatory aplikacji lub listy odbiorców).

  Jeśli na przykład masz parametr Remote Config, który używa warunku określającego wartość platformy iOS, szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same w każdym projekcie. Jeśli jednak zawiera warunek, który opiera się na konkretnym identyfikatorze aplikacji lub grupie odbiorców, która nie istnieje w projekcie docelowym, weryfikacja się nie powiedzie.

• Jeśli szablon, który chcesz opublikować, zawiera warunki zależne od Google Analytics, w projekcie docelowym musi być włączona usługa Analytics.

Pobieranie domyślnych ustawień szablonu Remote Config

Ponieważ aplikacja nie zawsze jest połączona z internetem, należy skonfigurować domyślne wartości po stronie klienta dla wszystkich parametrów Remote Config. Należy też okresowo synchronizować domyślne wartości klienta aplikacji i domyślne wartości parametrów backendu Remote Config, ponieważ mogą się one zmieniać w czasie.

Jak opisano w linkach dotyczących poszczególnych platform na końcu tej sekcji, możesz ręcznie ustawić te wartości domyślne w aplikacji lub usprawnić ten proces, pobierając pliki zawierające tylko pary klucz-wartość dla wszystkich parametrów i ich wartości domyślnych w aktywnym szablonie Remote Config. Następnie możesz dołączyć ten plik do projektu i skonfigurować aplikację tak, aby importowała te wartości.

Możesz pobrać te pliki w formacie XML w przypadku aplikacji na Androida, w formacie listy właściwości (plist) w przypadku aplikacji na iOS i w formacie JSON w przypadku aplikacji internetowych.

Okresowo pobieraj wartości domyślne Remote Config przed każdą nową wersją aplikacji, aby mieć pewność, że aplikacja i backend Remote Config są zsynchronizowane.

Aby pobrać plik zawierający domyślne wartości szablonu:

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

Więcej informacji o importowaniu wartości domyślnych Remote Config do aplikacji znajdziesz tutaj:

• Ustawianie domyślnych wartości parametrów w aplikacji na Androida

• Ustawianie domyślnych wartości parametrów w aplikacji na iOS

• Ustawianie domyślnych wartości parametrów w aplikacji w przypadku stron internetowych

• Ustawianie domyślnych wartości parametrów w aplikacji w Unity

• Ustawianie domyślnych wartości parametrów w aplikacji w przypadku C++