Remote Config programmatisch ändern

In diesem Dokument wird beschrieben, wie Sie die JSON-formatierten Parameter und Bedingungen, die als Remote Config-Vorlage bezeichnet werden, programmatisch lesen und ändern können. So können Sie Vorlagenänderungen am Backend vornehmen, die die Client-App mithilfe der Clientbibliothek abrufen kann.

Mit der Remote Config REST API oder den in diesem Leitfaden beschriebenen Admin SDKs können Sie die Verwaltung der Vorlage in der Firebase-Konsole umgehen und Remote Config-Änderungen direkt in Ihre eigenen Prozesse einbinden. Mit Remote Config-Backend-APIs haben Sie beispielsweise folgende Möglichkeiten:

• Remote Config-Updates planen Mit API-Aufrufen in Verbindung mit einem Cronjob können Sie Remote Config-Werte regelmäßig ändern.
• Konfigurationswerte im Batchverfahren importieren, um effizient von Ihrem eigenen System zu Firebase Remote Config zu wechseln.

• Verwenden Sie Remote Config mit Cloud Functions for Firebase, um Werte in Ihrer App basierend auf serverseitigen Ereignissen zu ändern. Sie können Remote Config beispielsweise verwenden, um für eine neue Funktion in Ihrer App zu werben, und diese Werbung dann automatisch deaktivieren, sobald genügend Nutzer mit der neuen Funktion interagiert haben.

  

In den folgenden Abschnitten dieses Leitfadens werden Vorgänge beschrieben, die Sie mit den Remote Config-Backend-APIs ausführen können. Codebeispiele für die Ausführung dieser Aufgaben über die REST API finden Sie in einer dieser Beispiel-Apps:

• Einstieg in die Firebase Remote Config REST API in Java
• Einstieg in die Firebase Remote Config REST API mit Node.js
• Einstieg in die Firebase Remote Config REST API mit Python

Remote Config mit dem Firebase Admin SDK ändern

Die Admin SDK ist eine Reihe von Serverbibliotheken, mit denen Sie aus privilegierten Umgebungen mit Firebase interagieren können. Neben der Aktualisierung von Remote Config ermöglicht die Admin SDK die Generierung und Überprüfung von Firebase-Authentifizierungstokens, das Lesen und Schreiben von Realtime Database usw. Admin SDKWeitere Informationen zu den Voraussetzungen und zur Einrichtung finden Sie unter Firebase Admin SDK auf dem Server hinzufügen.

In einem typischen Remote Config-Vorgang rufen Sie möglicherweise die aktuelle Vorlage ab, ändern einige der Parameter oder Parametergruppen und Bedingungen, validieren die Vorlage und veröffentlichen sie dann. Bevor Sie diese API-Aufrufe ausführen, müssen Sie Anfragen vom SDK autorisieren.

SDK initialisieren und API-Anfragen autorisieren

Wenn Sie Admin SDK ohne Parameter initialisieren, verwendet das SDK die Standardanmeldedaten für Google-Anwendungen und liest Optionen aus der Umgebungsvariablen FIREBASE_CONFIG. Wenn der Inhalt der Variablen FIREBASE_CONFIG mit einem { beginnt, wird er als JSON-Objekt geparst. Andernfalls geht das SDK davon aus, dass der String der Name einer JSON-Datei mit den Optionen ist.

Beispiel:

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

Aktuelle Remote Config-Vorlage abrufen

Bei der Arbeit mit Remote Config-Vorlagen ist zu beachten, dass sie versioniert sind und dass jede Version eine begrenzte Lebensdauer hat, die vom Zeitpunkt der Erstellung bis zum Zeitpunkt des Ersetzens durch ein Update beträgt: 90 Tage, mit einem Gesamtlimit von 300 gespeicherten Versionen. Weitere Informationen finden Sie unter Vorlagen und Versionierung.

Mit den Backend-APIs können Sie die aktuell aktive Version der Remote Config-Vorlage im JSON-Format abrufen.

Parameter und Parameterwerte, die speziell als Varianten in einem A/B Testing-Test erstellt wurden, sind in exportierten Vorlagen nicht enthalten.

So rufen Sie die Vorlage ab:

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

Remote Config-Parameter ändern

Sie können Remote Config-Parameter und Remote Config-Parametergruppen programmatisch ändern und hinzufügen. Sie können beispielsweise einer vorhandenen Parametergruppe mit dem Namen „new_menu“ einen Parameter hinzufügen, um die Anzeige saisonaler Informationen zu steuern:

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.")
        );

Mit der API können Sie neue Parameter und Parametergruppen erstellen oder Standardwerte, bedingte Werte und Beschreibungen ändern. In jedem Fall müssen Sie die Vorlage nach den Änderungen ausdrücklich veröffentlichen.

Remote Config-Bedingungen ändern

Sie können Remote Config-Bedingungen und bedingte Werte programmatisch ändern und hinzufügen. So fügen Sie beispielsweise eine neue Bedingung hinzu:

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

In jedem Fall müssen Sie die Vorlage nach den Änderungen ausdrücklich veröffentlichen.

Die Remote Config-Backend-APIs bieten mehrere Bedingungen und Vergleichsoperatoren, mit denen Sie das Verhalten und das Erscheinungsbild Ihrer App ändern können. Weitere Informationen zu Bedingungen und den für diese Bedingungen unterstützten Operatoren finden Sie in der Referenz zu Bedingungsausdrücken.

Remote Config-Vorlage validieren

Optional können Sie Ihre Änderungen vor der Veröffentlichung validieren:

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

Bei diesem Validierungsprozess werden Fehler wie doppelte Schlüssel für Parameter und Bedingungen, ungültige Bedingungsnamen oder nicht vorhandene Bedingungen oder falsch formatierte E-Tags geprüft. Wenn eine Anfrage beispielsweise mehr als die zulässige Anzahl von Schlüsseln (2.000) enthält, wird die Fehlermeldung Param count too large zurückgegeben.

Remote Config-Vorlage veröffentlichen

Nachdem Sie eine Vorlage abgerufen und mit den gewünschten Änderungen überarbeitet haben, können Sie sie veröffentlichen. Wenn Sie eine Vorlage wie in diesem Abschnitt beschrieben veröffentlichen, wird die gesamte vorhandene Konfigurationsvorlage durch die aktualisierte Datei ersetzt. Der neuen aktiven Vorlage wird eine Versionsnummer zugewiesen, die um eins höher ist als die der ersetzten Vorlage.

Bei Bedarf können Sie mit der REST API ein Rollback auf die vorherige Version durchführen. Um das Risiko von Fehlern bei einer Aktualisierung zu verringern, können Sie sie vor der Veröffentlichung validieren.

Remote Config Personalisierungen und Bedingungen sind in heruntergeladenen Vorlagen enthalten. Beachten Sie daher die folgenden Einschränkungen, wenn Sie versuchen, in einem anderen Projekt zu veröffentlichen:

• Personalisierungen können nicht von einem Projekt in ein anderes importiert werden.

  Wenn Sie beispielsweise in Ihrem Projekt Personalisierungen aktiviert haben und eine Vorlage herunterladen und bearbeiten, können Sie sie in demselben Projekt veröffentlichen. In einem anderen Projekt ist dies jedoch nur möglich, wenn Sie die Personalisierungen aus der Vorlage löschen.

• Bedingungen können von einem Projekt in ein anderes importiert werden. Beachten Sie jedoch, dass alle spezifischen bedingten Werte (z. B. App-IDs oder Zielgruppen) vor der Veröffentlichung im Zielprojekt vorhanden sein müssen.

  Wenn Sie beispielsweise einen Remote Config-Parameter mit einer Bedingung haben, die einen Plattformwert von iOS angibt, kann die Vorlage in einem anderen Projekt veröffentlicht werden, da die Plattformwerte für alle Projekte gleich sind. Wenn die Vorlage jedoch eine Bedingung enthält, die auf einer bestimmten App-ID oder Zielgruppe basiert, die im Zielprojekt nicht vorhanden ist, schlägt die Validierung fehl.

• Wenn die Vorlage, die Sie veröffentlichen möchten, Bedingungen enthält, die auf Google Analytics basieren, muss Analytics im Zielprojekt aktiviert sein.

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

Remote Config mit der REST API ändern

In diesem Abschnitt werden die wichtigsten Funktionen der Remote Config REST API unter https://firebaseremoteconfig.googleapis.com beschrieben. Weitere Informationen finden Sie in der API-Referenz.

Zugriffstoken zum Authentifizieren und Autorisieren von API-Anfragen abrufen

Firebase-Projekte unterstützen Google-Dienstkonten, mit denen Sie Firebase-Server-APIs von Ihrem App-Server oder einer vertrauenswürdigen Umgebung aus aufrufen können. Wenn Sie Code lokal entwickeln oder Ihre Anwendung vor Ort bereitstellen, können Sie über dieses Dienstkonto abgerufene Anmeldedaten verwenden, um Serveranfragen zu autorisieren.

Wenn Sie ein Dienstkonto authentifizieren und autorisieren möchten, auf Firebase-Dienste zuzugreifen, müssen Sie eine private Schlüsseldatei im JSON-Format generieren.

So generieren Sie eine private Schlüsseldatei für Ihr Dienstkonto:

1. Öffnen Sie in der Firebase-Konsole Einstellungen > Dienstkonten.

2. Klicke auf Neuen privaten Schlüssel generieren und bestätige die Aktion mit einem Klick auf Schlüssel generieren.

3. Speichern Sie die JSON-Datei mit dem Schlüssel sicher.

Wenn Sie die Autorisierung über ein Dienstkonto vornehmen, haben Sie zwei Möglichkeiten, die Anmeldedaten für Ihre Anwendung bereitzustellen. Sie können entweder die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen oder den Pfad zum Dienstkontoschlüssel explizit im Code übergeben. Die erste Option ist sicherer und wird dringend empfohlen.

So legen Sie die Umgebungsvariable fest:

Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält. Diese Variable gilt nur für Ihre aktuelle Shell-Sitzung. Wenn Sie eine neue Sitzung öffnen, müssen Sie die Variable noch einmal festlegen.

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

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

Nachdem Sie die oben genannten Schritte ausgeführt haben, können Ihre Anmeldedaten ermittelt werden, sodass Sie Anmeldedaten für Dienstkonten verwenden können, wenn Sie die Anwendung in Umgebungen testen oder ausführen, die nicht von Google stammen.

Verwenden Sie Ihre Firebase-Anmeldedaten zusammen mit der Google Auth-Bibliothek für Ihre bevorzugte Sprache, um ein kurzlebiges OAuth 2.0-Zugriffstoken abzurufen:

 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

Nach Ablauf des Zugriffstokens wird die Tokenaktualisierungsmethode automatisch aufgerufen, um ein aktualisiertes Zugriffstoken abzurufen.

Wenn Sie Zugriff auf Remote Config gewähren möchten, fordern Sie den Umfang https://www.googleapis.com/auth/firebase.remoteconfig an.

Remote Config-Vorlage ändern

Bei der Arbeit mit Remote Config-Vorlagen ist zu beachten, dass sie versioniert sind und dass jede Version eine begrenzte Lebensdauer hat, die vom Zeitpunkt der Erstellung bis zum Zeitpunkt des Ersetzens durch ein Update beträgt: 90 Tage, mit einem Gesamtlimit von 300 gespeicherten Versionen. Weitere Informationen finden Sie unter Vorlagen und Versionierung.

Aktuelle Remote Config-Vorlage abrufen

Mit den Backend-APIs können Sie die aktuell aktive Version der Remote Config-Vorlage im JSON-Format abrufen.

Parameter und Parameterwerte, die speziell als Varianten in einem A/B Testing-Test erstellt wurden, sind in exportierten Vorlagen nicht enthalten.

Verwenden Sie die folgenden Befehle:

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

Remote Config-Vorlage validieren

Optional können Sie Ihre Änderungen vor der Veröffentlichung validieren. Validiere Vorlagenaktualisierungen, indem du deiner Veröffentlichungsanfrage den URL-Parameter ?validate_only=true anhängst. Ein Statuscode 200 und ein aktualisiertes etag mit dem Suffix -0 in der Antwort bedeuten, dass Ihre Aktualisierung erfolgreich validiert wurde. Wenn die Antwort nicht 200 lautet, enthalten die JSON-Daten Fehler, die Sie vor der Veröffentlichung korrigieren müssen.

Remote Config-Vorlage aktualisieren

Nachdem Sie eine Vorlage abgerufen und den JSON-Inhalt mit den gewünschten Änderungen überarbeitet haben, können Sie sie veröffentlichen. Wenn Sie eine Vorlage wie in diesem Abschnitt beschrieben veröffentlichen, wird die gesamte vorhandene Konfigurationsvorlage durch die aktualisierte Datei ersetzt. Der neuen aktiven Vorlage wird eine Versionsnummer zugewiesen, die um eins höher ist als die der ersetzten Vorlage.

Bei Bedarf können Sie mit der REST API ein Rollback auf die vorherige Version durchführen. Um das Risiko von Fehlern bei einer Aktualisierung zu verringern, können Sie sie vor der Veröffentlichung validieren.

Remote Config Personalisierungen und Bedingungen sind in heruntergeladenen Vorlagen enthalten. Beachten Sie daher die folgenden Einschränkungen, wenn Sie versuchen, in einem anderen Projekt zu veröffentlichen:

• Personalisierungen können nicht von einem Projekt in ein anderes importiert werden.

  Wenn Sie beispielsweise in Ihrem Projekt Personalisierungen aktiviert haben und eine Vorlage herunterladen und bearbeiten, können Sie sie in demselben Projekt veröffentlichen. In einem anderen Projekt ist dies jedoch nur möglich, wenn Sie die Personalisierungen aus der Vorlage löschen.

• Bedingungen können von einem Projekt in ein anderes importiert werden. Beachten Sie jedoch, dass alle spezifischen bedingten Werte (z. B. App-IDs oder Zielgruppen) vor der Veröffentlichung im Zielprojekt vorhanden sein müssen.

  Wenn Sie beispielsweise einen Remote Config-Parameter mit einer Bedingung haben, die einen Plattformwert von iOS angibt, kann die Vorlage in einem anderen Projekt veröffentlicht werden, da die Plattformwerte für alle Projekte gleich sind. Wenn die Vorlage jedoch eine Bedingung enthält, die auf einer bestimmten App-ID oder Zielgruppe basiert, die im Zielprojekt nicht vorhanden ist, schlägt die Validierung fehl.

• Wenn die Vorlage, die Sie veröffentlichen möchten, Bedingungen enthält, die auf Google Analytics basieren, muss Analytics im Zielprojekt aktiviert sein.

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

Remote Config-Bedingungen ändern

Sie können Remote Config-Bedingungen und bedingte Werte programmatisch ändern. Mit der REST API müssen Sie die Vorlage direkt bearbeiten, um Bedingungen zu ändern, bevor Sie sie veröffentlichen.

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

Bei den oben genannten Änderungen werden zuerst eine Reihe von Bedingungen und dann Standardwerte und bedingungenbasierte Parameterwerte (bedingte Werte) für jeden Parameter definiert. Außerdem wird für jedes Element eine optionale Beschreibung hinzugefügt. Diese ist wie Codekommentare nur für Entwickler gedacht und wird nicht in der App angezeigt. Für die Versionskontrolle wird auch ein ETag bereitgestellt.

Die Remote Config-Backend-APIs bieten mehrere Bedingungen und Vergleichsoperatoren, mit denen Sie das Verhalten und das Erscheinungsbild Ihrer App ändern können. Weitere Informationen zu Bedingungen und den für diese Bedingungen unterstützten Operatoren finden Sie in der Referenz zu Bedingungsausdrücken.

HTTP-Fehlercodes

Ein Statuscode von 200 bedeutet, dass die Remote Config-Vorlage (Parameter, Werte und Bedingungen für das Projekt) aktualisiert wurde und jetzt für Apps verfügbar ist, die dieses Projekt verwenden. Andere Statuscodes geben an, dass die zuvor vorhandene Remote Config-Vorlage noch in Kraft ist.

Nachdem Sie die Änderungen an Ihrer Vorlage eingereicht haben, rufen Sie die Firebase-Konsole auf, um zu prüfen, ob die Änderungen wie erwartet angezeigt werden. Das ist wichtig, da sich die Reihenfolge der Bedingungen auf die Auswertung auswirkt. Die erste Bedingung, die true bewertet, wird angewendet.

ETag-Nutzung und erzwungene Aktualisierungen

Die Remote Config REST API verwendet ein Entitäts-Tag (ETag), um Race-Bedingungen und sich überschneidende Aktualisierungen von Ressourcen zu verhindern. Weitere Informationen zu ETags finden Sie unter ETag – HTTP.

Für die REST API empfiehlt Google, das ETag aus dem letzten GET-Befehl im Cache zu speichern und diesen ETag-Wert im If-Match-Anfrageheader zu verwenden, wenn PUT-Befehle ausgegeben werden. Wenn der PUT-Befehl den HTTPS-Statuscode 409 zurückgibt, sollten Sie einen neuen GET-Befehl ausführen, um ein neues ETag und eine neue Vorlage für den nächsten PUT-Befehl abzurufen.

Sie können das ETag und den damit verbundenen Schutz umgehen, indem Sie die Aktualisierung der Remote Config-Vorlage auf folgende Weise erzwingen: If-Match: * Dieser Ansatz wird jedoch nicht empfohlen, da es zu Datenverlusten bei der Remote Config-Vorlage kommen kann, wenn mehrere Clients die Remote Config-Vorlage aktualisieren. Diese Art von Konflikt kann bei mehreren Clients auftreten, die die API verwenden, oder bei widersprüchlichen Aktualisierungen von API-Clients und Firebase-Console-Nutzern.

Eine Anleitung zum Verwalten von Remote Config-Vorlagenversionen finden Sie unter Remote Config-Vorlagen und Versionierung.