Remote Config programmatisch ändern

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

Mit der Remote Config REST API oder den Admin SDKs in dieser Anleitung können Sie die Vorlage in der Firebase Konsole umgehen und Remote Config Änderungen direkt in Ihre eigenen Prozesse einbinden. Mit den Remote Config Backend-APIs können Sie beispielsweise Folgendes tun:

• Updates Remote Configplanen. Durch die Verwendung von 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 proprietären 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 eine neue Funktion in Ihrer App zu bewerben, und diese Werbung dann automatisch deaktivieren, sobald Sie feststellen, dass genügend Nutzer mit der neuen Funktion interagiert haben.

  

In den folgenden Abschnitten dieser Anleitung werden Vorgänge beschrieben, die Sie mit den Remote Config Backend-APIs ausführen können. Beispielcode, mit dem diese Aufgaben über die REST API ausgeführt werden, finden Sie in einer der folgenden Beispiel-Apps:

• Firebase Remote Config REST API Java-Schnellstart
• Firebase Remote Config REST API Node.js-Schnellstart
• Firebase Remote Config REST API Python-Schnellstart

Remote Config mit dem Firebase Admin SDK ändern

Das Admin SDK ist eine Reihe von Serverbibliotheken, mit denen Sie aus privilegierten Umgebungen mit Firebase interagieren können. Neben der Durchführung von Updates für Remote Config, ermöglicht das Admin SDK auch das Generieren und Überprüfen von Firebase-Authentifizierungstokens, das Lesen und Schreiben in Realtime Database, usw. Weitere Informationen zu Admin SDK Voraussetzungen und zur Einrichtung finden Sie unter Firebase Admin SDK zu Ihrem Server hinzufügen.

In einem typischen Remote Config Ablauf 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 das Admin SDK ohne Parameter initialisieren, verwendet das SDK die Standardanmeldedaten für Anwendungen von Google und liest Optionen aus der FIREBASE_CONFIG Umgebungsvariable. Wenn der Inhalt der Variablen FIREBASE_CONFIG mit einem { beginnt, wird er als JSON-Objekt geparst. Andernfalls geht das SDK davon aus, dass die 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

Wenn Sie mit Remote Config Vorlagen arbeiten, beachten Sie, dass sie versioniert sind und jede Version eine begrenzte Lebensdauer hat, von der Erstellung bis zum Zeitpunkt, an dem Sie sie durch ein Update ersetzen: 90 Tage, mit einem Limit von insgesamt 300 gespeicherten Versionen. Weitere Informationen finden Sie unter Vorlagen und Versionierung.

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

Parameter und Parameterwerte, die speziell als Varianten in einem A/B Testing Experiment 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 Parametergruppen programmatisch ändern und hinzufügen. Beispielsweise können Sie 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 allen Fällen müssen Sie die Vorlage nach den Änderungen explizit 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 allen Fällen müssen Sie die Vorlage nach den Änderungen explizit veröffentlichen.

Die Remote Config Backend-APIs bieten mehrere Bedingungen und Vergleichs operatoren, 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 bedingten Ausdrücken.

Remote Config-Vorlage validieren

Optional können Sie Ihre Updates vor der Veröffentlichung validieren, wie hier gezeigt:

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 dieser Validierung werden Fehler wie doppelte Schlüssel für Parameter und Bedingungen, ungültige oder nicht vorhandene Bedingungsnamen oder falsch formatierte ETags geprüft. Beispielsweise würde eine Anfrage mit mehr als der zulässigen Anzahl von Schlüsseln (2.000) die Fehlermeldung Param count too large zurückgeben.

Remote Config-Vorlage veröffentlichen

Nachdem Sie eine Vorlage abgerufen und mit den gewünschten Updates ü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 Vorlage, die sie ersetzt hat.

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

Remote Config Personalisierungen und Bedingungen sind in heruntergeladenen Vorlagen enthalten. Daher ist es wichtig, die folgenden Einschränkungen zu beachten, 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 Personalisierungen in Ihrem Projekt aktiviert haben und eine Vorlage herunterladen und bearbeiten, können Sie sie im selben Projekt veröffentlichen. Sie können sie jedoch nicht in einem anderen Projekt veröffentlichen, es sei denn, Sie löschen die Personalisierungen aus der Vorlage.

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

  Wenn Sie beispielsweise einen Remote Config Parameter haben, der eine Bedingung verwendet, 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 sie 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, Analytics basieren, muss im Ziel Projekt 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. Ausführliche 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 mit den Anmeldedaten, die Sie mit diesem Dienstkonto erhalten haben, Serveranfragen autorisieren.

Alle Dienstkonten für Ihr Firebase-Projekt finden Sie in den settings Einstellungen > Dienstkonten auf dem Tab.

Um ein Dienstkonto zu authentifizieren und ihm Zugriff auf Firebase-Dienste zu gewähren, müssen Sie eine Datei mit einem privaten Schlüssel im JSON-Format generieren.

So generieren Sie eine Datei mit einem privaten Schlüssel für Ihr Dienstkonto :

1. Rufen Sie in der Firebase Konsole die settings Einstellungen auf und wechseln Sie zum Tab Dienstkonten.

2. Klicken Sie auf Neuen privaten Schlüssel generieren und bestätigen Sie mit Schlüssel generieren.

3. Speichern Sie die JSON-Datei mit dem Schlüssel an einem sicheren Ort.

Bei der Autorisierung über ein Dienstkonto haben Sie zwei Möglichkeiten, die Anmeldedaten für Ihre Anwendung bereitzustellen. Sie können entweder die GOOGLE_APPLICATION_CREDENTIALS Umgebungsvariable 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 Dateipfad 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 die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) Ihre Anmeldedaten implizit ermitteln. So können Sie Dienstkontoanmeldedaten verwenden, wenn Sie in Nicht-Google-Umgebungen testen oder ausführen.

Verwenden Sie Ihre Firebase-Anmeldedaten zusammen mit der Google-Authentifizierungsbibliothek 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 Methode zur Tokenaktualisierung automatisch aufgerufen, um ein aktualisiertes Zugriffstoken abzurufen.

Um den Zugriff auf Remote Config zu autorisieren, fordern Sie den Bereich https://www.googleapis.com/auth/firebase.remoteconfig an.

Remote Config-Vorlage ändern

Wenn Sie mit Remote Config Vorlagen arbeiten, beachten Sie, dass sie versioniert sind und jede Version eine begrenzte Lebensdauer hat, von der Erstellung bis zum Zeitpunkt, an dem Sie sie durch ein Update ersetzen: 90 Tage, mit einem Limit von insgesamt 300 gespeicherten Versionen. Weitere Informationen finden Sie unter Vorlagen und Versionierung.

Aktuelle Remote Config-Vorlage abrufen

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

Parameter und Parameterwerte, die speziell als Varianten in einem A/B Testing Experiment 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 Updates vor der Veröffentlichung validieren. Fügen Sie Ihrer Veröffentlichungsanfrage den URL-Parameter ?validate_only=true hinzu, um Vorlagenupdates zu validieren. In der Antwort bedeutet ein Statuscode 200 und ein aktualisiertes ETag mit dem Suffix -0, dass Ihr Update erfolgreich validiert wurde. Jede Antwort, die nicht 200 ist, gibt an, dass die JSON-Daten Fehler enthalten, die Sie vor der Veröffentlichung beheben müssen.

Remote Config-Vorlage aktualisieren

Nachdem Sie eine Vorlage abgerufen und den JSON-Inhalt mit den gewünschten Updates ü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 Vorlage, die sie ersetzt hat.

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

Remote Config Personalisierungen und Bedingungen sind in heruntergeladenen Vorlagen enthalten. Daher ist es wichtig, die folgenden Einschränkungen zu beachten, 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 Personalisierungen in Ihrem Projekt aktiviert haben und eine Vorlage herunterladen und bearbeiten, können Sie sie im selben Projekt veröffentlichen. Sie können sie jedoch nicht in einem anderen Projekt veröffentlichen, es sei denn, Sie löschen die Personalisierungen aus der Vorlage.

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

  Wenn Sie beispielsweise einen Remote Config Parameter haben, der eine Bedingung verwendet, 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 sie 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, Analytics basieren, muss im Ziel Projekt 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 die Vorlage 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."
    }
  }
}

Mit den oben genannten Änderungen wird zuerst eine Reihe von Bedingungen definiert und dann werden Standardwerte und bedingte Parameterwerte (bedingte Werte) für jeden Parameter definiert. Außerdem wird für jedes Element eine optionale Beschreibung hinzugefügt. Wie Codekommentare sind diese für Entwickler bestimmt und werden nicht in der App angezeigt. Ein ETag wird auch für die Versionsverwaltung bereitgestellt.

Die Remote Config Backend-APIs bieten mehrere Bedingungen und Vergleichs operatoren, 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 bedingten Ausdrü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 Remote Config Vorlage, die zuvor vorhanden war, weiterhin gültig ist.

Nachdem Sie Updates an Ihrer Vorlage vorgenommen haben, prüfen Sie in der Firebase Konsole, ob die Änderungen wie erwartet angezeigt werden. Das ist wichtig, da die Reihenfolge der Bedingungen sich darauf auswirkt, wie sie ausgewertet werden (die erste Bedingung, die true ergibt, wird angewendet).

ETag-Verwendung und erzwungene Updates

Die Remote Config REST API verwendet ein Entity-Tag (ETag), um Race-Bedingungen und überlappende Updates für Ressourcen zu verhindern. Weitere Informationen zu ETags finden Sie unter ETag – HTTP.

Für die REST API empfiehlt Google, das ETag zu cachen, das vom letzten GET-Befehl bereitgestellt wurde, und diesen ETag-Wert im If-Match-Anfrageheader zu verwenden, wenn Sie PUT-Befehle ausführen. Wenn Ihr 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 zu erhalten.

Sie können das ETag und den damit verbundenen Schutz umgehen, indem Sie das Update der Remote Config Vorlage erzwingen: If-Match: * Diese Methode wird jedoch nicht empfohlen, da sie das Risiko birgt, dass Updates an Ihrer Remote Config Vorlage verloren gehen, wenn mehrere Clients die Remote Config Vorlage aktualisieren. Diese Art von Konflikt kann auftreten, wenn mehrere Clients die API verwenden oder wenn es zu Konflikten zwischen Updates von API-Clients und Firebase Konsolennutzern kommt.

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