Szablony Zdalnej konfiguracji i obsługa wersji

Szablony Zdalnej konfiguracji to zbiory parametrów i warunków w formacie JSON, które zostały utworzone dla Twojego projektu 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 zarządzać nim w konsoli Firebase, która wyświetla zawartość szablonu w formacie graficznym na kartach Parametry i Warunki. Do modyfikowania szablonu klienta i zarządzania nim możesz też używać interfejsu API typu REST Remote Config i Admin SDK lub interfejsu wiersza poleceń Firebase.

Oto przykładowy plik 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"
        }
      }

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świetl listę wszystkich przechowywanych wersji szablonów
• Pobieranie konkretnej wersji
• Przywracanie określonej wersji klienta
• Usuń szablony Zdalnej konfiguracji ze strony Historia zmian

Jeśli zarządzasz szablonami klientów, możesz też wyświetlać listę szablonów, pobierać szablony i wycofywać szablony za pomocą interfejsu wiersza poleceń Firebase oraz interfejsów API backendu Zdalnej konfiguracji.

Obowiązuje limit 300 przechowywanych wersji bezterminowo na typ szablonu (300 szablonów klienta i 300 szablonów serwera), w tym numery zapisanych 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, Zdalna konfiguracja tworzy nowy szablon Zdalnej konfiguracji z różnymi wersjami 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 zapisanej przez Zdalną konfigurację. Wszystkie szablony zawierają pole version, jak pokazano poniżej, zawierające metadane konkretnej wersji.

Za pomocą konsoli Firebase, interfejsu wiersza poleceń Firebase lub interfejsów API backendu Zdalnej konfiguracji możesz wykonywać te zadania związane z zarządzaniem wersjami:

• Wyświetl listę wszystkich przechowywanych wersji szablonów
• Pobieranie konkretnej wersji
• Przywracanie określonej wersji

W razie potrzeby możesz usunąć szablony Zdalnej konfiguracji na stronie Historia zmian w konsoli Zdalnej konfiguracji. Obowiązuje limit 300 przechowywanych wersji bezterminowo, w tym numery zapisanych wersji usuniętych szablonów. Jeśli w czasie trwania projektu opublikujesz więcej niż 300 wersji szablonu, zostaną usunięte najstarsze wersje, zachowując ich maksymalną liczbę 300.

Zarządzanie wersjami szablonów Zdalnej konfiguracji

W tej sekcji dowiesz się, jak zarządzać wersjami szablonu Zdalnej konfiguracji. Więcej informacji o automatycznym tworzeniu, modyfikowaniu i zapisywaniu szablonów znajdziesz w artykule Automatyczne modyfikowanie Zdalnej konfiguracji.

Wyświetl listę wszystkich zapisanych wersji szablonu Zdalnej konfiguracji

Możesz pobrać listę wszystkich zapisanych wersji szablonu Zdalnej konfiguracji. Przykład:

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

firebase remoteconfig:versions:list

Lista szablonów zawiera metadane wszystkich przechowywanych wersji, w tym czas aktualizacji, nazwę użytkownika, który ją utworzył, oraz informacje o tym, czy zostały one utworzone za pomocą konsoli czy interfejsu API REST. 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 Zdalnej konfiguracji

Możesz pobrać dowolną zapisaną wersję szablonu Zdalnej konfiguracji. Przykład:

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

firebase remoteconfig:get -v VERSION_NUMBER

Cofnięcie do określonej zapisanej wersji szablonu Zdalnej konfiguracji

Możesz przywrócić dowolną zapisaną wersję szablonu. Przykład:

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

firebase remoteconfig:rollback -v VERSION_NUMBER

Pamiętaj, że ta operacja przywracania tworzy nową wersję numerowaną. Na przykład powrót z wersji 10 do wersji 6 skutecznie tworzy nową kopię wersji 6, która różni się od oryginału tylko tym, że numer wersji to 11. Oryginalna wersja 6 jest nadal przechowywana, o ile nie upłynęła data ważności, a wersja 11 staje się aktywnym szablonem.

Usuń szablon Zdalnej konfiguracji

Szablony Zdalnej konfiguracji możesz usunąć z poziomu konsoli Firebase. Aby usunąć szablon Zdalnej konfiguracji:

1. Na stronie Parametry Zdalnej konfiguracji kliknij history Historia zmian.

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

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

Pobieranie i publikowanie szablonów Zdalnej konfiguracji

Pobieraj i publikuj szablony Zdalnej konfiguracji, aby zintegrować je z systemami źródłowymi i kompilacji, automatyzować aktualizacje konfiguracji oraz synchronizować parametry i wartości w wielu projektach.

Aktywny szablon Zdalnej konfiguracji możesz pobrać automatycznie lub z konsoli Firebase. Potem 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 reprezentujących różne etapy cyklu tworzenia oprogramowania, takich jak środowisko programistyczne, testowe, przejściowe i środowisko produkcyjne. W takim przypadku możesz przenieść w pełni przetestowany szablon ze środowiska testowego do środowiska produkcyjnego. W tym celu pobierz go z projektu przejściowego i opublikuj w projekcie produkcyjnym.

Za pomocą tej metody możesz też przenieść konfiguracje z jednego projektu do innego lub wypełnić nowy projekt parametrami i wartościami ze skonfigurowanego projektu.

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

Aby wyeksportować lub zaimportować szablony Zdalnej konfiguracji:

1. Pobierz aktualny szablon Zdalnej konfiguracji.
2. Zweryfikuj szablon Zdalnej konfiguracji.
3. Opublikuj szablon Zdalnej konfiguracji.

Pobierz bieżący szablon Zdalnej konfiguracji

Bieżący i aktywny szablon Zdalnej konfiguracji możesz pobrać automatycznie lub za pomocą konsoli Firebase.

Aby pobrać aktywny szablon Zdalnej konfiguracji w formacie JSON, użyj tych poleceń:

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

firebase remoteconfig:get -o filename

Weryfikowanie szablonu Zdalnej konfiguracji

Przed opublikowaniem aktualizacji w szablonach możesz je sprawdzić za pomocą pakietu SDK Firebase Admin lub interfejsu API REST. Szablony są też weryfikowane, gdy próbujesz opublikować szablony za pomocą interfejsu wiersza poleceń Firebase lub konsoli Firebase.

Proces weryfikacji szablonu sprawdza, czy nie występują błędy, na przykład zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki czy niewłaściwie sformatowane tagi ETag. Na przykład żądanie, które zawiera więcej kluczy niż dozwolona liczba – 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

Opublikuj szablon Zdalnej konfiguracji.

Po pobraniu szablonu, wprowadzeniu odpowiednich zmian w treści JSON i zweryfikowaniu go możesz opublikować w projekcie.

Opublikowanie szablonu powoduje zastąpienie całego istniejącego szablonu konfiguracji zaktualizowanym plikiem i zwiększenie wersji szablonu o 1. Zastąpi się cała konfiguracja, więc 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

Personalizacja i warunki Zdalnej konfiguracji są zawarte w pobieranych szablonach, dlatego pamiętaj o tych ograniczeniach, które obowiązują podczas próby opublikowania treści w innym projekcie:

• Nie można importować personalizacji z projektu do projektu.

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

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

  Jeśli na przykład masz parametr Zdalnej konfiguracji, który używa warunku określającego wartość platformy wynoszącą iOS, szablon można opublikować w innym projekcie, ponieważ wartości platformy są takie same dla każdego projektu. Jeśli jednak zawiera warunek oparty na konkretnym identyfikatorze aplikacji lub odbiorcach, których nie ma w projekcie docelowym, weryfikacja się nie powiedzie.

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

Pobierz domyślne szablony Zdalnej konfiguracji

Ponieważ aplikacja nie zawsze ma połączenie z internetem, należy skonfigurować domyślne wartości aplikacji po stronie klienta dla wszystkich parametrów Zdalnej konfiguracji. Warto też okresowo synchronizować wartości domyślne klienta aplikacji i domyślne wartości parametrów backendu Zdalnej konfiguracji, ponieważ z czasem mogą się one zmieniać.

Jak opisano w linkach na temat poszczególnych platform 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, które zawierają tylko pary klucz-wartość wszystkich parametrów i ich wartości domyślne w aktywnym szablonie Zdalnej konfiguracji. Możesz uwzględnić ten plik w projekcie i skonfigurować importowanie tych wartości w aplikacji.

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 lub w formacie JSON w przypadku aplikacji internetowych.

Zalecamy okresowe pobieranie ustawień domyślnych Zdalnej konfiguracji przed udostępnieniem jej nowej wersji, aby zapewnić synchronizację aplikacji z backendem Zdalnej konfiguracji.

Aby pobrać plik zawierający wartości domyślne 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 do aplikacji wartości domyślnych Zdalnej konfiguracji znajdziesz w tych materiał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 w przypadku witryn internetowych

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

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