Szablony Zdalnej konfiguracji i obsługa wersji

Remote Config szablony to zbiory parametrów i warunków w formacie JSON, które zostały utworzone na potrzeby projektu w Firebase. Możesz tworzyć szablony klientów, z których aplikacja pobiera wartości, oraz szablony serwerów, z których klienci serwerów mogą pobierać wartości.

Szablon możesz modyfikować i nim zarządzać w konsoli Firebase, która wyświetla jego zawartość w formacie graficznym na kartach Parametry i Warunki karty.

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

Oto przykład pliku szablonu serwera:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

W konsoli Firebase możesz wykonywać te zadania związane z zarządzaniem wersjami:

• Wyświetlanie listy wszystkich zapisanych wersji szablonu
• Pobieranie konkretnej wersji
• Wycofaj zmiany do konkretnej wersji klienta
• Usuwanie szablonów Remote Config ze strony Historia zmian

Łączny limit zapisanych wersji szablonu wynosi 300 (300 szablonów klientów i 300 szablonów serwerów). Obejmuje on numery 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, a maksymalna liczba wersji tego typu wyniesie 300.

Za każdym razem, gdy zaktualizujesz parametry, Remote Config utworzy nowy szablon Remote Config z obsługą wersji i zapisze poprzedni szablon jako wersję, którą w razie potrzeby możesz pobrać 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 poniżej), które zawiera metadane dotyczące konkretnej wersji.

Szablony Remote Config możesz w razie potrzeby usuwać na stronie Historia zmian w konsoli Remote Config.

Zarządzanie wersjami szablonu Remote Config

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

Wyświetlanie listy wszystkich zapisanych wersji szablonu Remote Config

Możesz pobrać listę wszystkich zapisanych wersji szablonu Remote Config. W tym celu:

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 <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:listVersions

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

```json
{
  "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 <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/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 <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}'

Pamiętaj, że ta operacja przywracania powoduje utworzenie nowej wersji z numerem. Na przykład przywrócenie wersji 10 do wersji 6 spowoduje 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 termin ważności), a wersja 11 staje się aktywnym szablonem.

Usuwanie szablonu Remote Config

Szablony Remote Config możesz usuwać w konsoli Firebase. Aby usunąć szablon:Remote Config

1. Przełącz się na szablon, który chcesz usunąć, kliknij more_vertWięcej, a następnie wybierz Usuń.

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

Pobieranie i publikowanie szablonów Remote Config

Pobieraj i publikuj 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.

Aktualnie aktywny szablon Remote Config możesz pobrać w konsoli Firebase. 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, że masz kilka projektów, które reprezentują różne etapy cyklu życia oprogramowania, takie jak środowiska deweloperskie, 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 do przenoszenia konfiguracji z jednego projektu do drugiego lub do wypełniania nowego projektu parametrami i wartościami z projektu już istniejącego.

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

Aby wyeksportować i zaimportować szablony Remote Config:

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

Pobieranie bieżącego szablonu Zdalnej konfiguracji

Aby pobrać aktywny szablon Remote Config w formacie 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

Sprawdzanie poprawności szablonu Zdalnej konfiguracji

Proces weryfikacji szablonu sprawdza błędy, takie jak duplikaty kluczy parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki oraz 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 sprawdzeniu jego poprawności możesz opublikować go w projekcie.

Opublikowanie szablonu powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem i zwiększenie numeru 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 projektu do projektu.

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

• 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 odbiorcy).

  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 on warunek, który zależy od konkretnego identyfikatora aplikacji lub odbiorców, którzy nie istnieją w projekcie docelowym, weryfikacja się nie powiedzie.

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

Pobieranie domyślnych ustawień szablonu Remote Config

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

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

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

Zalecamy okresowe pobieranie domyślnych ustawień 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 Remote Config domyślnych wartości do swojej aplikacji znajdziesz w tych artykułach:

• 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 internetowej

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

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