Modifier Remote Config par programmation

Ce document explique comment lire et modifier de manière programmatique l'ensemble des paramètres et conditions au format JSON, appelé modèle Remote Config. Cela vous permet de modifier les modèles dans le backend, que l'application cliente peut récupérer à l'aide de la bibliothèque cliente.

En utilisant l'API REST Remote Config ou les Admin SDK décrites dans ce guide, vous pouvez éviter de gérer le modèle dans la console Firebase pour intégrer directement les modifications Remote Config dans vos propres processus. Par exemple, avec les API de backend Remote Config, vous pouvez :

• Mises à jour de la Remote Configplanification En utilisant des appels d'API en association avec une tâche Cron, vous pouvez modifier les valeurs Remote Config à intervalles réguliers.
• Importez les valeurs de configuration par lot pour passer efficacement de votre propre système propriétaire à Firebase Remote Config.

• Utilisez Remote Config avec Cloud Functions for Firebase pour modifier les valeurs de votre application en fonction des événements qui se produisent côté serveur. Par exemple, vous pouvez utiliser Remote Config pour promouvoir une nouvelle fonctionnalité dans votre application, puis désactiver automatiquement cette promotion une fois que vous avez détecté qu'un nombre suffisant de personnes ont interagi avec la nouvelle fonctionnalité.

  

Les sections suivantes de ce guide décrivent les opérations que vous pouvez effectuer avec les API de backend Remote Config. Pour examiner du code qui effectue ces tâches via l'API REST, consultez l'une de ces applications exemples :

• Démarrage rapide de l'API REST Firebase Remote Config en Java
• Guide de démarrage rapide de l'API REST Firebase Remote Config Node.js
• Guide de démarrage rapide de l'API REST Firebase Remote Config pour Python

Modifier Remote Config à l'aide du SDK Admin Firebase

Admin SDK est un ensemble de bibliothèques de serveur qui vous permettent d'interagir avec Firebase à partir d'environnements privilégiés. En plus d'effectuer des mises à jour sur Remote Config, Admin SDK permet de générer et de valider des jetons d'authentification Firebase, de lire et d'écrire des données à partir de Realtime Database, et ainsi de suite. Pour en savoir plus sur les Admin SDK conditions préalables et la configuration, consultez Ajouter le SDK Firebase Admin à votre serveur.

Dans un flux Remote Config typique, vous pouvez obtenir le modèle actuel, modifier certains paramètres ou groupes de paramètres et conditions, valider le modèle, puis le publier. Avant d'effectuer ces appels d'API, vous devez autoriser les requêtes du SDK.

Initialiser le SDK et autoriser les requêtes d'API

Lorsque vous initialisez Admin SDK sans aucun paramètre, le SDK utilise les identifiants par défaut de l'application Google et lit les options à partir de la variable d'environnement FIREBASE_CONFIG. Si le contenu de la variable FIREBASE_CONFIG commence par un {, il sera analysé comme un objet JSON. Sinon, le SDK suppose que la chaîne est le nom d'un fichier JSON contenant les options.

Exemple :

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

Obtenir le modèle Remote Config actuel

Lorsque vous utilisez des modèles Remote Config, n'oubliez pas qu'ils sont versionnés et que chaque version a une durée de vie limitée (90 jours) à partir de sa date de création, avec une limite totale de 300 versions stockées. Pour en savoir plus, consultez Modèles et gestion des versions.

Vous pouvez utiliser les API de backend pour obtenir la version active actuelle du modèle Remote Config au format JSON.

Les paramètres et leurs valeurs créés spécifiquement en tant que variantes dans un test A/B Testing ne sont pas inclus dans les modèles exportés.

Pour obtenir le modèle :

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

Modifier les paramètres Remote Config

Vous pouvez modifier et ajouter des paramètres et des groupes de paramètres Remote Config de manière programmatique. Par exemple, vous pouvez ajouter un paramètre pour contrôler l'affichage des informations saisonnières à un groupe de paramètres existant nommé "new_menu" :

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

L'API vous permet de créer des paramètres et des groupes de paramètres, ou de modifier les valeurs par défaut, les valeurs conditionnelles et les descriptions. Dans tous les cas, vous devez publier explicitement le modèle après l'avoir modifié.

Modifier les conditions Remote Config

Vous pouvez modifier et ajouter des conditions Remote Config et des valeurs conditionnelles de manière programmatique. Par exemple, pour ajouter une condition :

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

Dans tous les cas, vous devez publier explicitement le modèle après l'avoir modifié.

Les API de backend Remote Config fournissent plusieurs conditions et opérateurs de comparaison que vous pouvez utiliser pour modifier le comportement et l'apparence de votre application. Pour en savoir plus sur les conditions et les opérateurs compatibles avec ces conditions, consultez la documentation de référence sur les expressions conditionnelles.

Valider le modèle Remote Config

Vous pouvez également valider vos modifications avant de les publier, comme indiqué ci-dessous :

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

Ce processus de validation recherche les erreurs telles que les clés en double pour les paramètres et les conditions, les noms de conditions non valides ou les conditions inexistantes, ou les etags mal formatés. Par exemple, une requête contenant plus de clés que le nombre autorisé (2 000) renverrait le message d'erreur Param count too large.

Publier le modèle Remote Config

Une fois que vous avez récupéré un modèle et que vous l'avez modifié comme vous le souhaitez, vous pouvez le publier. La publication d'un modèle, comme décrit dans cette section, remplace l'intégralité du modèle de configuration existant par le fichier mis à jour. Le nouveau modèle actif se voit attribuer un numéro de version supérieur de un au modèle qu'il a remplacé.

Si nécessaire, vous pouvez utiliser l'API REST pour revenir à la version précédente. Pour limiter le risque d'erreurs dans une mise à jour, vous pouvez valider avant de publier.

Les personnalisations et les conditions Remote Config sont incluses dans les modèles téléchargés. Il est donc important de connaître les limites suivantes lorsque vous essayez de publier dans un autre projet :

• Les personnalisations ne peuvent pas être importées d'un projet à un autre.

  Par exemple, si les personnalisations sont activées dans votre projet, et que vous téléchargez et modifiez un modèle, vous pouvez le publier dans le même projet. Toutefois, vous ne pouvez pas le publier dans un autre projet, sauf si vous supprimez les personnalisations du modèle.

• Les conditions peuvent être importées d'un projet à un autre, mais notez que toutes les valeurs conditionnelles spécifiques (comme les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

  Par exemple, si vous avez un paramètre Remote Config qui utilise une condition spécifiant une valeur de plate-forme iOS, le modèle peut être publié dans un autre projet, car les valeurs de plate-forme sont les mêmes pour tous les projets. Toutefois, si elle contient une condition qui repose sur un ID d'application ou une audience utilisateur spécifique qui n'existe pas dans le projet cible, la validation échouera.

• Si le modèle que vous prévoyez de publier contient des conditions qui reposent sur Google Analytics, Analytics doit être activé dans le projet cible.

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

Modifier Remote Config à l'aide de l'API REST

Cette section décrit les principales fonctionnalités de l'API REST Remote Config à l'adresse https://firebaseremoteconfig.googleapis.com. Pour en savoir plus, consultez la documentation de référence de l'API.

Obtenir un jeton d'accès pour authentifier et autoriser les requêtes API

Les projets Firebase sont compatibles avec les comptes de service Google, que vous pouvez utiliser pour appeler les API serveur Firebase depuis votre serveur d'application ou votre environnement de confiance. Si vous développez du code localement ou que vous déployez votre application sur site, vous pouvez utiliser les identifiants obtenus via ce compte de service pour autoriser les requêtes du serveur.

Pour authentifier un compte de service et l'autoriser à accéder aux services Firebase, vous devez générer un fichier de clé privée au format JSON.

Pour générer un fichier de clé privée pour votre compte de service :

1. Dans la console Firebase, ouvrez Paramètres > Comptes de service.

2. Cliquez sur Générer une nouvelle clé privée, puis confirmez en cliquant sur Générer une clé.

3. Stockez le fichier JSON contenant la clé de manière sécurisée.

Lorsque vous autorisez l'accès via un compte de service, vous avez deux choix pour fournir les identifiants à votre application. Vous pouvez soit définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS, soit indiquer explicitement le chemin d'accès à la clé du compte de service dans le code. La première option est plus sécurisée et est fortement recommandée.

Pour définir la variable d'environnement :

Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS de façon à pointer vers le chemin du fichier JSON contenant la clé de votre compte de service. Cette variable ne s'applique qu'à la session d'interface système actuelle. Par conséquent, si vous ouvrez une nouvelle session, vous devez la définir à nouveau.

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

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

Une fois que vous avez terminé les étapes ci-dessus, les identifiants par défaut de l'application (ADC) sont en mesure de déterminer implicitement vos identifiants, ce qui vous permet d'utiliser les identifiants de compte de service lors des tests ou de l'exécution dans des environnements non Google.

Utilisez vos identifiants Firebase avec la bibliothèque Google Auth pour votre langage préféré afin de récupérer un jeton d'accès OAuth 2.0 de courte durée :

 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

Une fois votre jeton d'accès expiré, la méthode d'actualisation du jeton est appelée automatiquement pour récupérer un jeton d'accès mis à jour.

Pour autoriser l'accès à Remote Config, demandez le champ d'application https://www.googleapis.com/auth/firebase.remoteconfig.

Modifier le modèle Remote Config

Lorsque vous utilisez des modèles Remote Config, n'oubliez pas qu'ils sont versionnés et que chaque version a une durée de vie limitée (90 jours) à partir de sa date de création, avec une limite totale de 300 versions stockées. Pour en savoir plus, consultez Modèles et gestion des versions.

Obtenir le modèle Remote Config actuel

Vous pouvez utiliser les API de backend pour obtenir la version active actuelle du modèle Remote Config au format JSON.

Les paramètres et leurs valeurs créés spécifiquement en tant que variantes dans un test A/B Testing ne sont pas inclus dans les modèles exportés.

Utilisez les commandes suivantes :

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

Valider le modèle Remote Config

Vous pouvez également valider vos modifications avant de les publier. Validez les modifications apportées au modèle en ajoutant le paramètre d'URL ?validate_only=true à votre demande de publication. Dans la réponse, un code d'état 200 et un tag d'entité mis à jour avec le suffixe -0 signifient que votre mise à jour a été validée avec succès. Toute réponse autre que 200 indique que les données JSON contiennent des erreurs que vous devez corriger avant de publier.

Mettre à jour le modèle Remote Config

Une fois que vous avez récupéré un modèle et modifié le contenu JSON avec les mises à jour souhaitées, vous pouvez le publier. La publication d'un modèle, comme décrit dans cette section, remplace l'intégralité du modèle de configuration existant par le fichier mis à jour. Le nouveau modèle actif se voit attribuer un numéro de version supérieur de un au modèle qu'il a remplacé.

Si nécessaire, vous pouvez utiliser l'API REST pour revenir à la version précédente. Pour limiter le risque d'erreurs dans une mise à jour, vous pouvez valider avant de publier.

Les personnalisations et les conditions Remote Config sont incluses dans les modèles téléchargés. Il est donc important de connaître les limites suivantes lorsque vous essayez de publier dans un autre projet :

• Les personnalisations ne peuvent pas être importées d'un projet à un autre.

  Par exemple, si les personnalisations sont activées dans votre projet, et que vous téléchargez et modifiez un modèle, vous pouvez le publier dans le même projet. Toutefois, vous ne pouvez pas le publier dans un autre projet, sauf si vous supprimez les personnalisations du modèle.

• Les conditions peuvent être importées d'un projet à un autre, mais notez que toutes les valeurs conditionnelles spécifiques (comme les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

  Par exemple, si vous avez un paramètre Remote Config qui utilise une condition spécifiant une valeur de plate-forme iOS, le modèle peut être publié dans un autre projet, car les valeurs de plate-forme sont les mêmes pour tous les projets. Toutefois, si elle contient une condition qui repose sur un ID d'application ou une audience utilisateur spécifique qui n'existe pas dans le projet cible, la validation échouera.

• Si le modèle que vous prévoyez de publier contient des conditions qui reposent sur Google Analytics, Analytics doit être activé dans le projet cible.

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

Modifier les conditions Remote Config

Vous pouvez modifier par programmation les conditions Remote Config et les valeurs conditionnelles. Avec l'API REST, vous devez modifier directement le modèle pour modifier les conditions avant de le publier.

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

Les modifications ci-dessus définissent d'abord un ensemble de conditions, puis définissent des valeurs par défaut et des valeurs de paramètre basées sur des conditions (valeurs conditionnelles) pour chaque paramètre. Il ajoute également une description facultative pour chaque élément. Comme les commentaires de code, ces descriptions sont destinées aux développeurs et ne sont pas affichées dans l'application. Un ETag est également fourni à des fins de contrôle des versions.

Les API de backend Remote Config fournissent plusieurs conditions et opérateurs de comparaison que vous pouvez utiliser pour modifier le comportement et l'apparence de votre application. Pour en savoir plus sur les conditions et les opérateurs compatibles avec ces conditions, consultez la documentation de référence sur les expressions conditionnelles.

Codes d'erreur HTTP

Un code d'état 200 signifie que le modèle Remote Config (paramètres, valeurs et conditions du projet) a été mis à jour et est désormais disponible pour les applications qui utilisent ce projet. Les autres codes d'état indiquent que le modèle Remote Config qui existait précédemment est toujours en vigueur.

Une fois que vous avez envoyé les modifications apportées à votre modèle, accédez à la console Firebase pour vérifier qu'elles s'affichent comme prévu. C'est essentiel, car l'ordre des conditions affecte la façon dont elles sont évaluées (la première condition qui renvoie true prend effet).

Utilisation des ETag et mises à jour forcées

L'API REST Remote Config utilise un tag d'entité (ETag) pour éviter les conditions de concurrence et les mises à jour qui se chevauchent pour les ressources. Pour en savoir plus sur les ETags, consultez ETag – HTTP.

Pour l'API REST, Google vous recommande de mettre en cache l'ETag fourni par la commande GET la plus récente et d'utiliser cette valeur ETag dans l'en-tête de requête If-Match lorsque vous émettez des commandes PUT. Si votre commande PUT génère un code d'état HTTPS 409, vous devez exécuter une nouvelle commande GET pour acquérir un nouvel ETag et un nouveau modèle à utiliser avec votre prochaine commande PUT.

Vous pouvez contourner l'ETag et la protection qu'elle offre en forçant la mise à jour du modèle Remote Config comme suit : If-Match: *. Toutefois, cette approche n'est pas recommandée, car elle risque d'entraîner la perte des mises à jour de votre modèle Remote Config si plusieurs clients mettent à jour le modèle Remote Config. Ce type de conflit peut se produire avec plusieurs clients utilisant l'API ou avec des mises à jour conflictuelles provenant de clients API et d'utilisateurs de la console Firebase.

Pour obtenir des conseils sur la gestion des versions de modèles Remote Config, consultez Modèles et gestion des versions de Remote Config.