Modèles de configuration à distance et gestion des versions

Le modèle Remote Config est l'ensemble côté serveur de paramètres et de conditions au format JSON que vous avez créé pour votre projet Firebase. Vous pouvez modifier et gérer le modèle à l'aide de la console Firebase, qui affiche le contenu du modèle sous forme graphique dans les onglets Paramètres et Conditions . Vous pouvez également utiliser l' API REST Remote Config et le SDK Admin ou la CLI Firebase pour modifier et gérer votre configuration.

Voici un exemple de fichier modèle :

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

Chaque fois que vous mettez à jour les paramètres, Remote Config crée un nouveau modèle Remote Config versionné et stocke le modèle précédent en tant que version que vous pouvez récupérer ou restaurer selon vos besoins. Les numéros de version sont incrémentés séquentiellement à partir de la valeur initiale stockée par Remote Config. Tous les modèles incluent un champ version , comme indiqué, contenant des métadonnées sur cette version spécifique.

Avec la console Firebase, la CLI Firebase ou les API backend Remote Config, vous pouvez effectuer ces tâches de gestion des versions :

  • Répertorier toutes les versions de modèles stockées
  • Récupérer une version spécifique
  • Revenir à une version spécifique

Vous pouvez supprimer les modèles Remote Config selon vos besoins à partir de la page Historique des modifications de la console Remote Config. Il existe une limite totale de 300 versions stockées à vie, qui inclut les numéros de version stockés pour les modèles supprimés. Si vous publiez plus de 300 versions de modèles au cours de la durée de vie d'un projet, les versions les plus anciennes sont supprimées, conservant ainsi un maximum de 300 versions.

Gérer les versions du modèle Remote Config

Cette section décrit comment gérer les versions de votre modèle Remote Config. Pour plus de détails sur la façon de créer, modifier et enregistrer des modèles par programme, consultez Modifier la configuration distante par programme .

Répertorier toutes les versions stockées du modèle Remote Config

Vous pouvez récupérer une liste de toutes les versions stockées du modèle Remote Config. Par exemple:

Noeud.js

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

Java

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

REPOS

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

Console Firebase

Dans l'onglet Paramètres , sélectionnez l'icône "horloge" affichée en haut à droite. Cela ouvre la page Historique des modifications répertoriant toutes les versions de modèles stockées dans un menu de liste à droite.

Les détails affichés pour chaque version stockée incluent des informations indiquant si les modifications proviennent de la console, de l'API REST, d'une restauration ou s'il s'agit de modifications incrémentielles résultant d'un enregistrement forcé du modèle.

CLI Firebase

firebase remoteconfig:versions:list

Utilisez l'option --limit pour limiter le nombre de versions renvoyées. Passez « 0 » pour récupérer toutes les versions.

La liste des modèles comprend des métadonnées pour toutes les versions stockées, y compris l'heure de la mise à jour, l'utilisateur qui l'a effectuée et si elle a été effectuée via la console ou l'API REST. Voici un exemple d'élément de 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"
  }]

Récupérer une version spécifique du modèle Remote Config

Vous pouvez récupérer n'importe quelle version stockée spécifique du modèle Remote Config. Par exemple:

Noeud.js

Transmettez getTemplate() sans aucun argument pour récupérer la dernière version du modèle, ou pour récupérer une version spécifique, utilisez getTemplateAtVersion() .

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

Java

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

REPOS

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

Le paramètre URL ?version_number est valide uniquement pour les opérations GET ; vous ne pouvez pas l'utiliser pour spécifier les numéros de version des mises à jour. Une requête get similaire sans le paramètre ?version_number récupérerait le modèle actif actuel.

Console Firebase

Par défaut, le volet de détails de l'onglet Historique des modifications affiche le modèle actif actuel. Pour afficher les détails d'une autre version de la liste, sélectionnez-la dans le menu de droite.

Vous pouvez afficher une différence détaillée de la version actuellement sélectionnée et de toute autre version stockée en survolant le menu contextuel de toute version non sélectionnée et en sélectionnant Comparer avec la version sélectionnée.

CLI Firebase

firebase remoteconfig:get -v VERSION_NUMBER

Vous pouvez éventuellement écrire la sortie dans un fichier spécifié avec -o, FILENAME .

Revenir à une version stockée spécifique du modèle Remote Config

Vous pouvez revenir à n'importe quelle version stockée du modèle. Par exemple:

Noeud.js

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

Java

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

REPOS

Pour revenir à un modèle de configuration distante stocké, émettez un HTTP POST avec la méthode personnalisée :rollback et, dans le corps de la demande, la version spécifique à appliquer. Par exemple:

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

La réponse contient le contenu du modèle stocké désormais actif, avec ses métadonnées de nouvelle version.

Console Firebase

Pour les versions de modèle précédentes éligibles à la restauration, un bouton d'option permettant de revenir à cette version s'affiche en haut à droite de la page Historique des modifications . Cliquez et confirmez ceci uniquement si vous êtes sûr de vouloir revenir à cette version et utiliser ces valeurs immédiatement pour toutes les applications et tous les utilisateurs.

CLI Firebase

firebase remoteconfig:rollback -v VERSION_NUMBER

Notez que cette opération de restauration crée effectivement une nouvelle version numérotée. Par exemple, revenir de la version 10 à la version 6 crée effectivement une nouvelle copie de la version 6, différant de l'original uniquement par le fait que son numéro de version est 11. La version 6 originale est toujours stockée, en supposant qu'elle n'a pas atteint son expiration, et la version 11 devient le modèle actif.

Supprimer un modèle de configuration à distance

Vous pouvez supprimer les modèles Remote Config de la console Firebase. Pour supprimer un modèle de configuration à distance :

  1. Sur la page Paramètres de configuration à distance, cliquez sur Historique des modifications .

  2. Basculez vers le modèle que vous souhaitez supprimer, cliquez sur Plus , puis sélectionnez Supprimer .

  3. Lorsque vous êtes invité à confirmer la suppression, cliquez sur Supprimer .

Télécharger et publier des modèles de configuration à distance

Téléchargez et publiez des modèles Remote Config pour les intégrer dans vos systèmes de contrôle de code source et de build, automatiser les mises à jour de configuration et synchroniser les paramètres et les valeurs sur plusieurs projets.

Vous pouvez télécharger le modèle Remote Config actuellement actif par programme ou à partir de la console Firebase. Vous pouvez ensuite mettre à jour le fichier JSON exporté et le publier dans le même projet, ou le publier dans un projet nouveau ou existant.

Supposons que vous ayez plusieurs projets qui représentent différentes étapes du cycle de vie de votre développement logiciel, comme les environnements de développement, de test, de préparation et de production. Dans ce cas, vous pouvez promouvoir un modèle entièrement testé de votre environnement de test vers votre environnement de production en le téléchargeant depuis votre projet de test et en le publiant dans votre projet de production.

Vous pouvez également utiliser cette méthode pour migrer des configurations d'un projet à un autre ou pour remplir un nouveau projet avec les paramètres et les valeurs d'un projet établi.

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

Pour exporter et importer des modèles Remote Config :

  1. Téléchargez le modèle de configuration Remote Config actuel .
  2. Validez le modèle Remote Config .
  3. Publiez le modèle de configuration à distance .

Téléchargez le modèle de configuration à distance actuel

Vous pouvez télécharger le modèle Remote Config actuel et actif par programme ou à l'aide de la console Firebase.

Utilisez les commandes suivantes pour télécharger le modèle Remote Config actif au format JSON :

Noeud.js

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

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

REPOS

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

Cette commande génère la charge utile JSON dans un fichier et les en-têtes (y compris l'ETag) dans un fichier headers distinct.

Console Firebase

  1. Dans l'onglet Paramètres ou Conditions de configuration à distance , ouvrez le menu et sélectionnez Télécharger le fichier de configuration actuel .
  2. Lorsque vous y êtes invité, cliquez sur Télécharger le fichier de configuration , choisissez l'emplacement où vous souhaitez enregistrer le fichier, puis cliquez sur Enregistrer .

CLI Firebase

firebase remoteconfig:get -o filename

Valider le modèle de configuration à distance

Vous pouvez valider les mises à jour de vos modèles avant de les publier à l'aide du SDK Firebase Admin ou de l'API REST. Les modèles sont également validés lorsque vous tentez de publier à partir de la CLI Firebase ou de la console Firebase.

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

Noeud.js

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

Java

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

REPOS

Validez les mises à jour du modèle en ajoutant le paramètre d'URL ?validate_only=true à votre demande de publication :

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

Si votre modèle a été validé avec succès, la commande curl renvoie le modèle JSON que vous avez soumis et, dans le fichier headers enregistré, vous trouverez un statut HTTP/2 200 et un ETag mis à jour avec le suffixe -0 . Si votre modèle n'a pas été validé, vous recevrez l'erreur de validation dans la réponse JSON et votre fichier headers contiendra une réponse non-200 (et aucun ETag).

Publier le modèle de configuration à distance

Après avoir téléchargé un modèle, apporté les modifications nécessaires au contenu JSON et l'avoir validé, vous pouvez le publier dans un projet.

La publication d'un modèle remplace l'intégralité du modèle de configuration existant par le fichier mis à jour et incrémente la version du modèle de une. Étant donné que l'intégralité de la configuration est remplacée, si vous supprimez un paramètre du fichier JSON et le publiez, le paramètre est supprimé du serveur et n'est plus disponible pour les clients.

Après la publication, les modifications apportées aux paramètres et aux valeurs sont immédiatement disponibles pour vos applications et vos utilisateurs. Si nécessaire, vous pouvez revenir à une version précédente .

Utilisez les commandes suivantes pour publier votre modèle :

Noeud.js

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

Java

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

REPOS

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

Pour cette commande curl , vous pouvez spécifier le contenu en utilisant le caractère "@", suivi du nom de fichier.

Console Firebase

  1. Dans l'onglet Paramètres ou Conditions de configuration à distance , ouvrez le menu et sélectionnez Publier à partir d'un fichier .
  2. Lorsque vous y êtes invité, cliquez sur Parcourir , recherchez et sélectionnez le fichier Remote Config que vous souhaitez publier, puis cliquez sur Sélectionner .
  3. Le fichier sera validé et, en cas de succès, vous pourrez cliquer sur Publier pour rendre la configuration immédiatement disponible pour vos applications et utilisateurs.

Les personnalisations et conditions de Remote Config sont incluses dans les modèles téléchargés. Il est donc important d'être conscient des limitations suivantes lorsque vous tentez de publier sur un autre projet :

  • Les personnalisations ne peuvent pas être importées d’un projet à l’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, mais 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 à l'autre, mais notez que toutes les valeurs conditionnelles spécifiques (telles que les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

    Par exemple, si vous disposez d'un paramètre Remote Config qui utilise une condition qui spécifie une valeur de plateforme iOS , le modèle peut être publié dans un autre projet, car les valeurs de plateforme sont les mêmes pour tous les projets. Toutefois, s’il contient une condition qui repose sur un ID d’application spécifique ou un public d’utilisateurs qui n’existe pas dans le projet cible, la validation échouera.

  • Si le modèle que vous envisagez de publier contient des conditions qui s'appuient sur Google Analytics, Analytics doit être activé dans le projet cible.

Télécharger les valeurs par défaut du modèle de configuration à distance

Étant donné que votre application n'est pas toujours connectée à Internet, vous devez configurer les valeurs par défaut de l'application côté client pour tous les paramètres de configuration à distance. Vous devez également synchroniser périodiquement les valeurs par défaut de votre client d'application et les valeurs par défaut des paramètres du backend de Remote Config, car elles peuvent changer au fil du temps.

Comme décrit dans les liens spécifiques à la plate-forme à la fin de cette section, vous pouvez définir manuellement ces valeurs par défaut dans votre application ou rationaliser ce processus en téléchargeant des fichiers contenant uniquement les paires clé-valeur pour tous les paramètres et leurs valeurs par défaut dans le fichier. modèle de configuration à distance actif. Vous pouvez ensuite inclure ce fichier dans votre projet et configurer votre application pour importer ces valeurs.

Vous pouvez télécharger ces fichiers au format XML pour les applications Android, au format liste de propriétés (plist) pour les applications iOS et JSON pour les applications Web.

Nous vous recommandons de télécharger périodiquement les valeurs par défaut de Remote Config avant toute nouvelle version d'application pour garantir que votre application et le backend de Remote Config restent synchronisés.

Pour télécharger un fichier contenant les valeurs par défaut du modèle :

REPOS

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

Utilisez XML , PLIST ou JSON comme valeur format , selon le format de fichier que vous souhaitez télécharger.

Console Firebase

  1. Dans l'onglet Paramètres , ouvrez le menu et sélectionnez Télécharger les valeurs par défaut .
  2. Lorsque vous y êtes invité, cliquez sur la case d'option correspondant au format de fichier que vous souhaitez télécharger, puis cliquez sur Télécharger le fichier .

Pour plus d'informations sur l'importation des valeurs par défaut de Remote Config dans votre application, consultez :