Automatycznie modyfikuj Zdalną konfigurację

Z tego dokumentu dowiesz się, jak programowo odczytywać i modyfikować zbiór parametrów i warunków w formacie JSON, czyli Remote Config szablon. Dzięki temu możesz wprowadzać zmiany w szablonie na backendzie, które aplikacja kliencka może pobierać za pomocą biblioteki klienta.

Korzystając z Remote Configinterfejsu REST API lub Admin SDKusług opisanych w tym przewodniku, możesz pominąć zarządzanie szablonem w Firebasekonsoli i bezpośrednio zintegrować zmiany Remote Configz własnymi procesami. Na przykład za pomocą interfejsów API backendu możesz:Remote Config

• Planowanie Remote Config aktualizacji. Wywołując interfejs API w połączeniu z zadaniem cron, możesz regularnie zmieniać wartości Remote Config.
• Importuj wartości konfiguracji w partiach, aby sprawnie przejść z własnego systemu na Firebase Remote Config.

• Używaj Remote Config z Cloud Functions for Firebase, zmieniając wartości w aplikacji na podstawie zdarzeń, które mają miejsce po stronie serwera. Możesz na przykład użyć Remote Config, aby promować nową funkcję w aplikacji, a potem automatycznie wyłączyć tę promocję, gdy zauważysz, że wystarczająca liczba osób skorzystała z tej funkcji.

  

W kolejnych sekcjach tego przewodnika opisujemy operacje, które możesz wykonać za pomocą Remote Configinterfejsów API backendu. Aby przejrzeć kod, który wykonuje te zadania za pomocą interfejsu API REST, zapoznaj się z jedną z tych przykładowych aplikacji:

• Krótkie wprowadzenie do interfejsu Zdalna konfiguracja Firebase REST API w języku Java
• Szybkie wprowadzenie do interfejsu Zdalna konfiguracja Firebase REST API w Node.js
• Krótki przewodnik po interfejsie REST API Zdalnej konfiguracji Firebase w języku Python

Modyfikowanie Zdalnej konfiguracji za pomocą pakietu Firebase Admin SDK

Admin SDK to zestaw bibliotek serwera, które umożliwiają interakcję z Firebase w środowiskach uprzywilejowanych. Oprócz wykonywania aktualizacji Remote Config Admin SDK umożliwia generowanie i weryfikowanie tokenów uwierzytelniania Firebase, odczytywanie i zapisywanie danych w Realtime Database itp. Więcej informacji o Admin SDKwymaganiach wstępnych i konfiguracji znajdziesz w artykule Dodawanie pakietu Firebase Admin SDK do serwera.

W typowym procesie Remote Config możesz pobrać bieżący szablon, zmodyfikować niektóre parametry lub grupy parametrów i warunki, sprawdzić poprawność szablonu, a następnie go opublikować. Zanim wykonasz te wywołania interfejsu API, musisz autoryzować żądania z pakietu SDK.

Inicjowanie pakietu SDK i autoryzowanie żądań interfejsu API

Gdy zainicjujesz Admin SDK bez parametrów, pakiet SDK użyje domyślnego uwierzytelniania aplikacji Google i odczyta opcje ze zmiennej środowiskowej FIREBASE_CONFIG. Jeśli zawartość zmiennej FIREBASE_CONFIG zaczyna się od znaku {, zostanie ona przeanalizowana jako obiekt JSON. W przeciwnym razie pakiet SDK zakłada, że ciąg znaków jest nazwą pliku JSON zawierającego opcje.

Przykład:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Pobieranie bieżącego szablonu Zdalnej konfiguracji

Pamiętaj, że Remote Configszablony są wersjonowane, a każda wersja ma ograniczony czas życia od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w artykule Szablony i obsługa wersji.

Za pomocą interfejsów API backendu możesz pobrać aktualną aktywną wersję szablonuRemote Config w formacie JSON.

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

Aby pobrać szablon:

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());

Modyfikowanie parametrów Zdalnej konfiguracji

Możesz programowo modyfikować i dodawać parametry Remote Config oraz grupy parametrów. Na przykład do istniejącej grupy parametrów o nazwie „new_menu” możesz dodać parametr, który będzie kontrolować wyświetlanie informacji sezonowych:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

Interfejs API umożliwia tworzenie nowych parametrów i grup parametrów oraz modyfikowanie wartości domyślnych, wartości warunkowych i opisów. W każdym przypadku po wprowadzeniu zmian musisz wyraźnie opublikować szablon.

Zmienianie warunków Zdalnej konfiguracji

Możesz programowo modyfikować i dodawać Remote Config warunki oraz wartości warunkowe. Aby na przykład dodać nowy warunek:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

W każdym przypadku po wprowadzeniu zmian musisz wyraźnie opublikować szablon.

Interfejsy API backendu Remote Config udostępniają kilka warunków i operatorów porównania, których możesz używać do zmiany działania i wyglądu aplikacji. Więcej informacji o warunkach i operatorach obsługiwanych w przypadku tych warunków znajdziesz w dokumentacji wyrażeń warunkowych.

Weryfikowanie szablonu Zdalnej konfiguracji

Opcjonalnie możesz sprawdzić aktualizacje przed ich opublikowaniem, jak pokazano poniżej:

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());
  }
}

Ten proces weryfikacji sprawdza, czy nie występują błędy, takie jak zduplikowane klucze parametrów i warunków, nieprawidłowe nazwy warunków lub nieistniejące warunki czy 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.

Opublikuj szablon Zdalnej konfiguracji

Po pobraniu szablonu i wprowadzeniu w nim odpowiednich zmian możesz go opublikować. Opublikowanie szablonu w sposób opisany w tej sekcji zastępuje cały dotychczasowy szablon konfiguracji zaktualizowanym plikiem, a nowy aktywny szablon otrzymuje numer wersji o 1 większy od numeru szablonu, który zastąpił.

W razie potrzeby możesz użyć interfejsu API (typu) REST, aby wycofać zmiany do poprzedniej wersji. Aby zmniejszyć ryzyko błędów w aktualizacji, możesz sprawdzić ją przed opublikowaniem.

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.

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());
  }
}

Modyfikowanie Zdalnej konfiguracji za pomocą interfejsu API REST

W tej sekcji opisujemy główne możliwości interfejsu API typu REST Remote Config pod adresem https://firebaseremoteconfig.googleapis.com. Szczegółowe informacje znajdziesz w dokumentacji interfejsu API.

Uzyskiwanie tokena dostępu do uwierzytelniania i autoryzowania żądań do interfejsu API

Projekty Firebase obsługują konta usługi Google, których możesz używać do wywoływania interfejsów API serwera Firebase z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz kod lokalnie lub wdrażasz aplikację lokalnie, możesz użyć danych logowania uzyskanych za pomocą tego konta usługi do autoryzowania żądań serwera.

Wszystkie konta usługi w projekcie w Firebase możesz wyświetlić na karcie settings Ustawienia > Konta usługi.

Aby uwierzytelnić konto usługi i przyznać mu uprawnienia dostępu do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

Aby wygenerować plik klucza prywatnego dla konta usługi:

1. W konsoli Firebase otwórz settings Ustawienia > kartę Konta usługi.

2. Kliknij Wygeneruj nowy klucz prywatny, a następnie potwierdź, klikając Wygeneruj klucz.

3. Bezpiecznie przechowuj plik JSON zawierający klucz.

Podczas autoryzacji za pomocą konta usługi masz 2 możliwości przekazania danych logowania do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub jawnie przekazać ścieżkę do klucza konta usługi w kodzie. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.

Aby ustawić zmienną środowiskową:

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę pliku JSON zawierającego klucz konta usługi. Ta zmienna jest stosowana tylko w bieżącej sesji powłoki, więc jeśli otworzysz nową sesję, ustaw ją ponownie.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Po wykonaniu powyższych czynności domyślne uwierzytelnianie aplikacji (ADC) będzie mogło niejawnie określać Twoje dane logowania, co umożliwi Ci używanie danych logowania konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

Użyj danych logowania Firebase wraz z biblioteką Google Auth Library w preferowanym języku, aby pobrać krótkotrwały token dostępu OAuth 2.0:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
FirebaseRemoteConfigSnippets.java

Gdy token dostępu wygaśnie, metoda odświeżania tokena zostanie wywołana automatycznie, aby pobrać zaktualizowany token dostępu.

Aby autoryzować dostęp do Remote Config, poproś o zakreshttps://www.googleapis.com/auth/firebase.remoteconfig.

Modyfikowanie szablonu Zdalnej konfiguracji

Pamiętaj, że Remote Configszablony są wersjonowane, a każda wersja ma ograniczony czas życia od momentu utworzenia do momentu zastąpienia jej aktualizacją: 90 dni, przy łącznym limicie 300 przechowywanych wersji. Więcej informacji znajdziesz w artykule Szablony i obsługa wersji.

Pobieranie bieżącego szablonu Zdalnej konfiguracji

Za pomocą interfejsów API backendu możesz pobrać aktualną aktywną wersję szablonuRemote Config w formacie JSON.

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

Użyj tych poleceń:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Weryfikowanie szablonu Zdalnej konfiguracji

Opcjonalnie możesz sprawdzić zmiany przed ich opublikowaniem. Sprawdź aktualizacje szablonu, dodając do żądania publikacji parametr adresu URL ?validate_only=true. W odpowiedzi kod stanu 200 i zaktualizowany tag ETag z sufiksem -0 oznaczają, że aktualizacja została zweryfikowana. Każda odpowiedź inna niż 200 oznacza, że dane JSON zawierają błędy, które musisz poprawić przed opublikowaniem.

Aktualizowanie szablonu Zdalnej konfiguracji

Po pobraniu szablonu i zmodyfikowaniu treści JSON zgodnie z potrzebnymi aktualizacjami możesz go opublikować. Opublikowanie szablonu w sposób opisany w tej sekcji zastępuje cały dotychczasowy szablon konfiguracji zaktualizowanym plikiem, a nowy aktywny szablon otrzymuje numer wersji o 1 większy od numeru szablonu, który zastąpił.

W razie potrzeby możesz użyć interfejsu API (typu) REST, aby wycofać zmiany do poprzedniej wersji. Aby zmniejszyć ryzyko błędów w aktualizacji, możesz sprawdzić ją przed opublikowaniem.

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.

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

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Zmienianie warunków Zdalnej konfiguracji

Możesz programowo modyfikować Remote Config warunki i wartości warunkowe. W przypadku interfejsu REST API musisz edytować szablon bezpośrednio, aby zmodyfikować warunki przed opublikowaniem szablonu.

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

Powyższe modyfikacje najpierw definiują zestaw warunków, a następnie wartości domyślne i wartości parametrów oparte na warunkach (wartości warunkowe) dla każdego parametru. Dodaje też opcjonalny opis każdego elementu. Podobnie jak komentarze do kodu, są one przeznaczone dla deweloperów i nie są wyświetlane w aplikacji. W celu kontroli wersji podawany jest też ETag.

Interfejsy API backendu Remote Config udostępniają kilka warunków i operatorów porównania, których możesz używać do zmiany działania i wyglądu aplikacji. Więcej informacji o warunkach i operatorach obsługiwanych w przypadku tych warunków znajdziesz w dokumentacji wyrażeń warunkowych.

Kody błędów HTTP

Kod stanu 200 oznacza, że Remote Config szablon (parametry, wartości i warunki projektu) został zaktualizowany i jest teraz dostępny dla aplikacji, które korzystają z tego projektu. Inne kody stanu wskazują, że Remote Config wcześniej istniejący szablon nadal obowiązuje.

Po przesłaniu aktualizacji szablonu otwórz Firebase konsolę, aby sprawdzić, czy zmiany są widoczne zgodnie z oczekiwaniami. Jest to bardzo ważne, ponieważ kolejność warunków wpływa na sposób ich oceny (zastosowanie ma pierwszy warunek, który daje wynik true).

Użycie tagu ETag i wymuszone aktualizacje

Interfejs Remote Config REST API używa tagu encji (ETag), aby zapobiegać wyścigom i nakładającym się aktualizacjom zasobów. Więcej informacji o tagach ETag znajdziesz w artykule ETag – HTTP.

W przypadku interfejsu REST API Google zaleca zapisywanie w pamięci podręcznej znacznika ETag podanego przez ostatnie polecenie GET i używanie tej wartości znacznika ETag w nagłówku żądania If-Match podczas wydawania poleceń PUT. Jeśli PUTpolecenie zwróci kod stanu HTTPS 409, wydaj nowe polecenie GET, aby uzyskać nowy tag ETag i szablon do użycia z następnym poleceniem PUT.

Możesz obejść tag ETag i ochronę, jaką zapewnia, wymuszając aktualizację szablonu Remote Config w ten sposób: If-Match: * Nie zalecamy jednak tego podejścia, ponieważ w przypadku aktualizowania szablonu Remote Config przez wielu klientów może to spowodować utratę aktualizacji szablonu Remote Config. Tego rodzaju konflikt może wystąpić w przypadku wielu klientów korzystających z interfejsu API lub w przypadku sprzecznych aktualizacji od klientów interfejsu API i użytkowników konsoli Firebase.

Wskazówki dotyczące zarządzania wersjami szablonów Remote Config znajdziesz w artykule Szablony i obsługa wersji Zdalnej konfiguracji.