Szablony Zdalnej konfiguracji i obsługa wersji

Szablony Zdalnej konfiguracji to zestawy parametrów i warunków w formacie JSON utworzone przez Ciebie dla projektu Firebase. Możesz utworzyć szablony client, 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 za pomocą 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żyć interfejsu API typu REST Zdalnej konfiguracji i pakietu Admin SDK lub interfejsu wiersza poleceń Firebase.

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

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

Za pomocą konsoli Firebase możesz wykonać te zadania związane z zarządzaniem wersjami:

• Wyświetlanie listy wszystkich zapisanych wersji szablonu
• 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ć szablony, pobierać je i wycofywać za pomocą interfejsu wiersza poleceń Firebase i interfejsów API backendu Zdalnej konfiguracji.

Obowiązuje limit 300 przechowywanych wersji wszystkich wersji na typ szablonu (300 szablonów klienta i 300 szablonów serwera). Obejmuje to zapisane numery wersji usuniętych szablonów. Jeśli w trakcie trwania projektu opublikujesz więcej niż 300 wersji szablonów na typ szablonu, najstarsze wersje zostaną usunięte, co pozwoli zachować maksymalnie 300 wersji tego 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ą widoczne pole version, które zawiera metadane dotyczące tej konkretnej wersji.

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

• Wyświetlanie listy wszystkich zapisanych wersji szablonu
• Pobieranie konkretnej wersji
• Przywracanie określonej wersji

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

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 o automatycznym modyfikowaniu Zdalnej konfiguracji.

Wyświetl wszystkie zapisane wersje szablonu Zdalnej konfiguracji

Możesz pobrać listę wszystkich przechowywanych 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ła ona utworzona za pomocą konsoli czy interfejsu API REST. Oto przykład elementu version:

{
  "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"
  }]

Pobierz konkretną wersję 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

Cofnij do określonej zapisanej wersji szablonu Zdalnej konfiguracji

Możesz wrócić do dowolnej zapisanej wersji 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 powoduje utworzenie nowej wersji numerowanej. Na przykład przejście z wersji 10 do 6 w efekcie powoduje utworzenie nowej kopii wersji 6, która różni się od oryginału tylko numerem 11. Oryginalna wersja 6 jest nadal przechowywana, o ile nie minęła data wygaśnięcia, a wersja 11 staje się aktywnym szablonem.

Usuń szablon Zdalnej konfiguracji

Szablony Zdalnej konfiguracji możesz usunąć z 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 i 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 integrować je ze źródłem kontroli i systemami 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. Następnie możesz zaktualizować wyeksportowany plik JSON i opublikować go w tym samym projekcie albo w nowym lub istniejącym projekcie.

Załóżmy, że masz wiele projektów, które reprezentują różne etapy cyklu tworzenia oprogramowania, np. środowiska programistyczne, testowe, przejściowe i produkcyjne. W takim przypadku możesz przenieść do środowiska produkcyjnego w pełni przetestowany szablon, pobierając go z projektu testowego i publikując w projekcie produkcyjnym.

Tej metody możesz też używać do przenoszenia konfiguracji z jednego projektu do innego lub do wypełniania nowego projektu parametrami i wartościami z dotychczasowego projektu.

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

Aby wyeksportować i zaimportować szablony Zdalnej konfiguracji:

1. Pobierz bieżący 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 przez konsolę 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

Sprawdzanie szablonu Zdalnej konfiguracji

Przed opublikowaniem aktualizacji szablonu możesz je zweryfikować za pomocą pakietu SDK Firebase Admin lub interfejsu API REST. Szablony są też weryfikowane przy próbie publikacji z poziomu interfejsu wiersza poleceń Firebase lub konsoli Firebase.

Proces weryfikacji szablonu sprawdza, czy nie ma w nim błędów takich jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków, nieistniejące warunki i nieprawidłowo sformatowane tagi ETag. Na przykład żądanie zawierające więcej kluczy niż jest dozwolona – 2000 – zwróciło 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 niezbędnych 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 powoduje zwiększenie wersji szablonu o jeden. Ponieważ zastępowana jest cała konfiguracja, jeśli usuniesz parametr z pliku JSON i go opublikujesz, 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 Twoich 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

Personalizacje i warunki Zdalnej konfiguracji są zawarte w pobranych szablonach, dlatego podczas próby publikowania w innym projekcie należy pamiętać o tych ograniczeniach:

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

  Jeśli na przykład w projekcie masz włączone personalizacje oraz pobierzesz i wyedytujesz szablon, możesz opublikować go w tym samym projekcie, ale nie możesz go opublikować w innym projekcie, chyba że usuniesz personalizacje z szablonu.

• Warunki można importować z projektu do projektu, ale pamiętaj, że wszystkie określone wartości warunkowe (takie jak identyfikatory aplikacji lub odbiorcy) powinny występować w projekcie docelowym przed opublikowaniem.

  Jeśli na przykład masz parametr Zdalnej konfiguracji, który korzysta z warunku, który określa wartość platformy równą 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 na liście odbiorców użytkownika, który 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 musisz włączyć Analytics.

Pobierz ustawienia domyślne szablonu Zdalnej konfiguracji

Twoja aplikacja nie zawsze jest połączona z internetem, dlatego musisz skonfigurować domyślne wartości aplikacji po stronie klienta dla wszystkich parametrów Zdalnej konfiguracji. Należy też okresowo synchronizować wartości domyślne klienta aplikacji i domyślne wartości parametrów backendu Zdalnej konfiguracji, ponieważ mogą się one zmieniać.

Zgodnie z linkami do 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 w aktywnym szablonie Zdalnej konfiguracji pliki zawierające tylko pary klucz-wartość dla wszystkich parametrów i ich wartości domyślne. Następnie możesz uwzględnić ten plik w projekcie i skonfigurować w aplikacji importowanie tych wartości.

Możesz je pobrać w formacie XML dla aplikacji na Androida, w formacie listy właściwości (plist) dla aplikacji na iOS i w formacie JSON w przypadku aplikacji internetowych.

Zalecamy okresowe pobieranie wartości domyślnych Zdalnej konfiguracji przed wprowadzeniem każdej nowej wersji aplikacji, aby zapewnić synchronizację aplikacji i backendu Zdalnej konfiguracji.

Aby pobrać plik, który zawiera ustawienia 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 wartości domyślnych Zdalnej konfiguracji do aplikacji znajdziesz tutaj:

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

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

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

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

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