Szablony Zdalnej konfiguracji i obsługa wersji

Remote Config to zbiory parametrów i warunków w formacie JSON utworzone przez Ciebie na potrzeby projektu Firebase. Możesz tworzyć szablony klienta, z których aplikacja pobiera wartości, oraz szablony serwera, z których klienci 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 Karty Parametry i Warunki.

Możesz też użyć interfejsu Remote Config REST API i pakietu Admin SDK lub Firebase interfejsu CLI, aby modyfikować szablon klienta i nim zarządzać.

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

Te czynności związane z zarządzaniem wersjami możesz wykonywać w Firebase konsoli:

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

Istnieje łączny limit 300 przechowywanych wersji na typ szablonu (300 szablonów klienta i 300 szablonów serwera), który obejmuje przechowywane numery wersji usuniętych szablonów. Jeśli w trakcie 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 wersją Remote Config i zapisuje poprzedni szablon jako wersję, którą możesz w razie potrzeby przywrócić. Numery wersji są zwiększane kolejno od wartości początkowej przechowywanej przez Remote Config. Wszystkie szablony zawierają pole version, jak pokazano na ilustracji, które zawiera metadane dotyczące tej konkretnej wersji.

Szablony Remote Config możesz w razie potrzeby usuwać ze strony Historia zmian w konsoli Remote Config.

Zarządzanie wersjami szablonu Remote Config

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

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 zapisanych wersji, w tym czas aktualizacji, użytkownika, który ją wprowadził, oraz sposób wprowadzenia zmiany. 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ę Remote Config szablonu. 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

Cofnij do określonej zapisanej wersji szablonu Remote Config

Możesz przywrócić dowolną zapisaną wersję szablonu. Aby cofnąć 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 wycofania powoduje utworzenie nowej wersji numerowanej. Na przykład przywrócenie wersji 10 do wersji 6 spowoduje utworzenie nowej kopii wersji 6, która będzie się różnić od oryginału tylko numerem wersji – będzie to 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ć z Firebase konsoli. 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

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

Obecnie aktywny Remote Configszablonz Firebasekonsoli. 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, np. środowiska programistyczne, testowe, przejściowe i produkcyjne. W takim przypadku możesz promować w środowisku produkcyjnym w pełni przetestowany szablon ze środowiska testowego, pobierając go z projektu testowego 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 bieżący Remote Config szablon konfiguracji.
2. Sprawdź Remote Configszablon.
3. Opublikuj Remote Configszablon.

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

Weryfikowanie szablonu Zdalnej konfiguracji

Proces weryfikacji szablonu sprawdza 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ż 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 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 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

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 w innym, 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 odbiorcy).

  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 domyślne ustawienia szablonu Remote Config

Aplikacja może nie zawsze mieć połączenie z internetem, dlatego skonfiguruj domyślne wartości parametrów Remote Config 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 do 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.

Zalecamy okresowe pobieranie Remote Config wartości domyślnych przed każdą nową wersją aplikacji, aby mieć pewność, że aplikacja i Remote Config backend 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 wartości domyślnych do aplikacji znajdziesz w tych artykułach:

• Ustawianie w aplikacji domyślnych wartości parametrów na urządzeniach z Androidem

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

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

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

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