Szablony Zdalnej konfiguracji i obsługa wersji

Remote Config szablony to zestawy parametrów i warunków w formacie JSON utworzonych w Twoim projekcie Firebase. Możesz tworzyć szablony klientów, z których aplikacja pobiera wartości, oraz szablony serwera, z których klienty serwera mogą pobierać wartości.

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

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

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 czynności związane z zarządzaniem wersjami:

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

Łączny limit liczby zapisanych wersji na typ szablonu (300 szablonów klienta i 300 szablonów serwera) wynosi 300 wersji, w tym wersji usuniętych szablonów. Jeśli w czasie trwania projektu opublikujesz więcej niż 300 wersji szablonów na typ szablonu, zostaną usunięte najstarsze wersje, zachowując przy tym maksymalnie 300 wersji danego typu.

Za każdym razem, gdy aktualizujesz parametry, Remote Config tworzy nową wersję szablonu Remote Config i przechowuje poprzednią wersję szablonu jako wersję, do której możesz wrócić w razie potrzeby. Numery wersji są zwiększane sekwencyjnie z wartości początkowej zapisanej przez funkcję Remote Config. Wszystkie szablony zawierają pole version, jak pokazano poniżej, zawierające metadane konkretnej wersji.

W razie potrzeby możesz usunąć szablony Remote Config ze strony Historia zmian w konsoli Remote Config.

Zarządzaj wersjami szablonu Remote Config

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

Lista szablonów zawiera metadane wszystkich przechowywanych wersji, w tym czas aktualizacji, użytkownika, który ją utworzył, i sposób jej wykonania. Oto przykładowy element 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

Przywróć określoną zapisaną wersję szablonu Remote Config

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

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 spowoduje utworzenie nowej wersji z numerem. Na przykład powrót z wersji 10 do wersji 6 powoduje utworzenie nowej kopii wersji 6, która różni się od oryginału tylko tym, że numer wersji to 11. Pierwotna wersja 6 jest nadal przechowywana, o ile nie minął jej okres 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. Przejdź do szablonu, 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 Remote Config szablonów

Pobieraj i publikuj szablony Remote Config, aby integrować je z systemami kontroli źródła i kompilacji, automatyzować aktualizacje konfiguracji oraz utrzymywać parametry i wartości w zsynchronizowanym stanie w wielu projektach.

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

Załóżmy, że masz wiele projektów, które reprezentują różne etapy cyklu życia rozwoju oprogramowania, takie jak środowisko programistyczne, testowe, przejściowe i produkcyjne. W takim przypadku możesz przenieść w środowisku produkcyjnym szablon, który został w pełni przetestowany w środowisku testowym. Aby to zrobić, pobierz go z projektu testowego i opublikuj w projekcie produkcyjnym.

Możesz też użyć tej metody do migracji konfiguracji z jednego projektu do innego lub do wypełnienia nowego projektu parametrami i wartościami z istniejącego projektu.

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

Aby eksportować i importować szablony Remote Config:

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

Pobieranie bieżącego szablonu Zdalnej konfiguracji

Aby pobrać aktywny szablon Remote Config w formacie JSON, użyj tych instrukcji:

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 Zdalnej konfiguracji

Proces sprawdzania szablonu wykrywa błędy, takie jak zduplikowane klucze 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ż 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 w nim niezbędnych zmian i sprawdzeniu go możesz opublikować go w projekcie.

Publikowanie szablonu powoduje zastąpienie całego dotychczasowego szablonu konfiguracji zaktualizowanym plikiem i zwiększenie wersji szablonu o 1. Ponieważ cała konfiguracja zostaje zastąpiona, 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ą od razu 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

Pobierane szablony i warunki usługi Remote Config są zawarte w pobranych szablonach, dlatego pamiętaj o tych ograniczeniach, które obowiązują podczas publikowania w innym projekcie:

• Personalizacji nie można importować z jednego projektu do drugiego.

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

• Warunki można importować z jednego projektu do drugiego, ale pamiętaj, że przed opublikowaniem w projekcie docelowym powinny znajdować się określone 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, możesz opublikować szablon w innym projekcie, ponieważ wartości platformy są takie same w przypadku każdego projektu. Jeśli jednak zawiera on warunek, który zależy od określonego identyfikatora aplikacji lub listy odbiorców, która nie istnieje w docelowym projekcie, weryfikacja się nie powiedzie.

• Jeśli szablon, który planujesz opublikować, zawiera warunki oparte na atrybucie Google Analytics, w projekcie docelowym musisz włączyć atrybut Analytics.

Pobierz domyślne szablony Remote Config

Aplikacja nie zawsze ma połączenie z internetem, dlatego musisz skonfigurować domyślne wartości aplikacji po stronie klienta dla wszystkich parametrów Remote Config. Co jakiś czas synchronizuj domyślne wartości klienta aplikacji i domyślne wartości parametrów backendu Remote Config, ponieważ z czasem mogą się one zmieniać.

Zgodnie z opisem w linkach na poszczególnych platformach na końcu tej sekcji możesz ręcznie ustawić te wartości domyślne w aplikacji lub możesz uprościć ten proces, pobierając pliki zawierające tylko pary klucz-wartość wszystkich parametrów i ich wartości domyślne 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.

Pliki te możesz pobrać w formacie XML (aplikacje na Androida), plist (aplikacje na iOS) lub JSON (aplikacje internetowe).

Zalecamy okresowe pobieranie domyślnych wartości Remote Config przed każdą nową wersją aplikacji, aby mieć pewność, że aplikacja i back-end Remote Config są zsynchronizowane.

Aby pobrać plik z domyślnymi ustawieniami 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 domyślnych wartości Remote Config do aplikacji znajdziesz w tych artykułach:

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

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

• Ustawianie w aplikacji domyślnych wartości parametrów na potrzeby wersji internetowej

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

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