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

Remote Config to zbiory parametrów i warunków w formacie JSON utworzone dla Twojego projektu w Firebase. Szablony klienta dostarczają konfiguracje do instancji aplikacji, które implementują pakiety SDK Firebase na Remote Config, w tym aplikacje na Apple, Androida, internetowe, Flutter, Unity i C++.

Za pomocą Firebasekonsoli możesz modyfikować szablon klienta i nim zarządzać. Aby wyświetlić zawartość szablonu w formacie graficznym na stronie Parametry i na stronie Warunki, kliknij DevOps i zaangażowanie > Zdalna konfiguracja.

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

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 czynności związane z zarządzaniem wersjami możesz wykonać w Firebase konsoli (otwórz DevOps i zaangażowanie > Zdalna konfiguracja):

• Wyświetlanie wszystkich zapisanych wersji szablonu
• Pobieranie konkretnej wersji
• Wycofaj zmiany do konkretnej wersji klienta
• Usuń Remote Config szablony ze strony Historia zmian.

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

Łączny limit przechowywanych wersji w całym okresie istnienia szablonu wynosi 300 na typ szablonu (300 szablonów klienta i 300 szablonów serwera), co obejmuje przechowywane numery wersji usuniętych szablonów. Jeśli w trakcie trwania projektu opublikujesz więcej niż 300 wersji szablonu danego typu, najstarsze wersje zostaną usunięte, a maksymalna liczba wersji tego typu wyniesie 300.

Za każdym razem, gdy aktualizujesz parametry, Remote Config tworzy nowy szablon z obsługą wersji Remote Config i zapisuje poprzedni szablon jako wersję, którą możesz w razie potrzeby przywrócić lub wycofać zmiany. Numery wersji są zwiększane kolejno od wartości początkowej zapisanej przez Remote Config. Wszystkie szablony zawierają pole version, jak pokazano na ilustracji, które zawiera metadane dotyczące tej konkretnej 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 opisujemy, jak zarządzać wersjami Remote Configszablonu.

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

Wyświetl wszystkie zapisane wersje 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 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 przywrócić 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

Wycofaj zmiany do konkretnej zapisanej wersji szablonu Remote Config

Możesz wycofać zmiany do dowolnej zapisanej wersji szablonu. Aby wycofać zmiany w szablonie:

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 wycofania powoduje utworzenie nowej wersji numerowanej. Na przykład przywrócenie wersji 10 do wersji 6 powoduje utworzenie nowej kopii wersji 6, która różni się od oryginału tylko numerem wersji 11. Oryginalna wersja 6 jest nadal przechowywana (o ile nie upłynął jej okres ważności), a wersja 11 staje się aktywnym szablonem.

Usuwanie szablonu Remote Config

Szablony Remote Config możesz usuwać 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. Przełącz się na szablon, 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 Remote Config szablony, aby zintegrować je z systemami kontroli wersji i kompilacji, zautomatyzować aktualizacje konfiguracji oraz synchronizować parametry i wartości w wielu projektach.

Obecnie aktywny szablon Remote Config możesz pobrać programowo lub z Firebase konsoli. Następnie możesz zaktualizować wyeksportowany plik JSON i opublikować go w tym samym projekcie lub w nowym bądź 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 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 drugiego lub wypełnić nowy projekt parametrami i wartościami z istniejącego projektu.

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

Aby wyeksportować i zaimportować szablony Remote Config:

1. Pobierz aktualny Remote Config szablon.
2. Sprawdź Remote Configszablon.
3. Opublikuj Remote Configszablon.

Pobierz bieżący szablon Remote Config

Aby pobrać aktywny szablon Remote Config w formacie JSON, wykonaj te czynności:

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

Weryfikowanie szablonu Remote Config

Przed opublikowaniem aktualizacji szablonu możesz sprawdzić jego poprawność za pomocą Firebase Admin SDK lub interfejsu API REST. Szablony są też weryfikowane podczas próby opublikowania ich za pomocą Firebaseinterfejsu CLI lub Firebasekonsoli.

Proces weryfikacji szablonu sprawdza błędy, takie jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki czy nieprawidłowo sformatowane tagi ETag. Na przykład żądanie zawierające więcej niż dozwolona liczba 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 treści JSON i zweryfikowaniu go możesz opublikować go w projekcie.

Opublikowanie szablonu zastępuje cały istniejący szablon konfiguracji zaktualizowanym plikiem i zwiększa numer wersji szablonu o 1. Ponieważ cała konfiguracja jest zastępowana, jeśli usuniesz parametr z pliku JSON i opublikujesz go, 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 wycofać zmiany do poprzedniej wersji.

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

Remote Config personalizacje i warunki 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ć z jednego projektu do drugiego.

  Jeśli na przykład masz włączoną personalizację w projekcie, a pobierzesz i edytujesz szablon, możesz opublikować go w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, chyba że usuniesz z niego personalizację.

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

  Jeśli np. 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 zależy od konkretnego identyfikatora aplikacji lub listy 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 funkcja Analytics.

Pobierz Remote Config domyślne ustawienia szablonu

Aplikacja może nie zawsze mieć połączenie z internetem, dlatego dla wszystkich parametrów Remote Config należy skonfigurować domyślne wartości po stronie klienta. Okresowo synchronizuj też domyślne wartości klienta aplikacji i Remote Configdomyślne wartości parametrów backendu, ponieważ mogą się one z czasem zmieniać.

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 uprościć ten proces, pobierając pliki, które zawierają tylko pary klucz-wartość dla wszystkich parametrów i ich wartości domyślnych w aktywnym szablonie Remote Config. Następnie możesz uwzględnić ten plik w projekcie 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 ustawienia 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 ustawienia 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 w tych artykułach:

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

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

• Ustawianie w aplikacji domyślnych wartości parametrów dla internetu

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

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