Ce document explique comment lire et modifier de manière programmatique l'ensemble de paramètres et de conditions au format JSON appelé modèle Remote Config. Vous pouvez ainsi apporter des modifications au modèle sur le backend que l'application cliente peut récupérer à l'aide de la bibliothèque cliente.
À l'aide de l'API REST Remote Config ou des Admin SDK décrits 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 backend Remote Config, vous pouvez:
- Planifier les mises à jour de Remote Config En utilisant des appels d'API avec une tâche cron, vous pouvez modifier les valeurs Remote Config de manière régulière.
- Importez les valeurs de configuration par lot afin de 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é que suffisamment 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 backend Remote Config. Pour examiner du code qui effectue ces tâches via l'API REST, consultez l'un de ces exemples d'applications:
- Démarrage rapide Java de l'API REST Firebase Remote Config
- Guide de démarrage rapide de l'API REST Firebase Remote Config pour 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 serveurs qui vous permettent d'interagir avec Firebase à partir d'environnements privilégiés. En plus d'effectuer des mises à jour de Remote Config, Admin SDK permet de générer et de valider des jetons d'authentification Firebase, de lire et d'écrire à partir de Realtime Database, etc. Pour en savoir plus sur les conditions préalables et la configuration de Admin SDK, consultez Ajouter le SDK Firebase Admin à votre serveur.
Dans un flux Remote Config typique, vous pouvez obtenir le modèle actuel, modifier certains des paramètres ou groupes de paramètres et des conditions, valider le modèle, puis le publier. Avant d'effectuer ces appels d'API, vous devez autoriser les requêtes à partir du SDK.
Initialiser le SDK et autoriser les requêtes d'API
Lorsque vous initialisez Admin SDK sans paramètres, 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é en tant qu'objet JSON. Sinon, le SDK suppose que la chaîne est le nom d'un fichier JSON contenant les options.
Exemple :
Node.js
const admin = require('firebase-admin');
admin.initializeApp();Java
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 travaillez avec des modèles Remote Config, gardez à l'esprit qu'ils sont versionnés et que chaque version a une durée de vie limitée entre le moment de sa création et celui où vous la remplacez par une mise à jour: 90 jours, avec une limite totale de 300 versions stockées. Pour en savoir plus, consultez la section Modèles et gestion des versions.
Vous pouvez utiliser les API 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:
Node.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());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 à un groupe de paramètres existant nommé "new_menu" pour contrôler l'affichage des informations saisonnières:
Node.js
function addParameterToGroup(template) {
template.parameterGroups['new_menu'].parameters['spring_season'] = {
defaultValue: {
useInAppDefault: true
},
description: 'spring season menu visibility.',
};
}Java
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 avoir apporté des modifications.
Modifier les conditions Remote Config
Vous pouvez modifier et ajouter de manière programmatique des conditions et des valeurs conditionnelles Remote Config. Par exemple, pour ajouter une condition:
Node.js
function addNewCondition(template) {
template.conditions.push({
name: 'android_en',
expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
tagColor: 'BLUE',
});
}Java
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 avoir apporté des modifications.
Les API 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 éventuellement valider vos mises à jour avant de les publier, comme illustré ci-dessous:
Node.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());
}
}Ce processus de validation recherche des erreurs telles que des clés en double pour les paramètres et les conditions, des noms de conditions non valides ou des conditions inexistantes, ou des etags mal formatés.
Par exemple, une requête contenant plus de clés que le nombre autorisé (2 000) renvoie le message d'erreur Param count too large.
Publier le modèle Remote Config
Après avoir récupéré un modèle et l'avoir modifié avec les modifications 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 d'un à celui du modèle qu'il remplace.
Si nécessaire, vous pouvez utiliser l'API REST pour effectuer un rollback vers la version précédente. Pour limiter le risque d'erreurs dans une mise à jour, vous pouvez la valider avant de la publier.
Les personnalisations et 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, mais pas dans un autre, 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 (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 spécifiant une valeur de plate-forme de
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 d'utilisateurs spécifiques qui n'existent 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.
Node.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());
}
}Modifier la configuration à distance à l'aide de l'API REST
Cette section décrit les principales fonctionnalités de l'API REST Remote Config sur 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 de serveur Firebase à partir de votre serveur d'application ou de votre environnement approuvé. Si vous développez du code localement ou 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:
Dans la console Firebase, ouvrez Settings > Service Accounts (Paramètres > Comptes de service).
Cliquez sur Générer une nouvelle clé privée, puis confirmez en cliquant sur Générer une clé.
Stockez de manière sécurisée le fichier JSON contenant la clé.
Lorsque vous autorisez l'accès via un compte de service, vous avez deux choix pour fournir les identifiants à votre application. Vous pouvez définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS ou transmettre 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 vivement recommandée.
Pour définir la variable d'environnement:
Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pour qu'elle pointe vers le chemin du fichier JSON contenant la clé de votre compte de service. Cette variable ne s'applique qu'à la session de shell actuelle. Par conséquent, si vous ouvrez une nouvelle session, vous devez la définir à nouveau.
Linux ou macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
Avec PowerShell :
$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) peuvent déterminer implicitement vos identifiants, ce qui vous permet d'utiliser les identifiants du compte de service lors des tests ou de l'exécution dans des environnements autres que Google.
Utilisez vos identifiants Firebase avec la bibliothèque Google Auth dans la langue de votre choix pour récupérer un jeton d'accès OAuth 2.0 de courte durée:
Node.js
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);
});
}
Dans cet exemple, la bibliothèque cliente de l'API Google authentifie la requête avec un jeton Web JSON (JWT). Pour en savoir plus, consultez la section Jetons Web JSON.
Python
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
Java
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();
}
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 travaillez avec des modèles Remote Config, gardez à l'esprit qu'ils sont versionnés et que chaque version a une durée de vie limitée entre le moment de sa création et celui où vous la remplacez par une mise à jour: 90 jours, avec une limite totale de 300 versions stockées. Pour en savoir plus, consultez la section Modèles et gestion des versions.
Obtenir le modèle Remote Config actuel
Vous pouvez utiliser les API 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
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 distinct.
Requête HTTP brute
Host: firebaseremoteconfig.googleapis.com GET /v1/projects/my-project-id/remoteConfig HTTP/1.1 Authorization: Bearer token Accept-Encoding: gzip
Cet appel d'API renvoie le code JSON suivant, ainsi qu'un en-tête distinct qui inclut un ETag que vous utiliserez pour la requête suivante.
Valider le modèle Remote Config
Vous pouvez également valider vos mises à jour avant de les publier.
Validez les mises à jour du 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 code etag mis à jour avec le suffixe -0 signifient que votre mise à jour a bien été validée. Toute réponse autre que 200 indique que les données JSON contiennent des erreurs que vous devez corriger avant de les publier.
Mettre à jour le modèle Remote Config
Après avoir récupéré un modèle et révisé le contenu JSON avec les modifications 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 d'un à celui du modèle qu'il remplace.
Si nécessaire, vous pouvez utiliser l'API REST pour effectuer un rollback vers la version précédente. Pour limiter le risque d'erreurs dans une mise à jour, vous pouvez la valider avant de la publier.
Les personnalisations et 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, mais pas dans un autre, 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 (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 spécifiant une valeur de plate-forme de
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 d'utilisateurs spécifiques qui n'existent 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
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 à l'aide du caractère "@", suivi du nom du fichier.
Requête HTTP brute
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
Comme il s'agit d'une requête d'écriture, l'ETag est modifié par cette commande et un ETag mis à jour est fourni dans les en-têtes de réponse de la prochaine commande PUT.
Modifier les conditions Remote Config
Vous pouvez modifier par programmation les conditions et les valeurs conditionnelles Remote Config. 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 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, ils sont destinés aux développeurs et ne s'affichent pas dans l'application. Un ETag est également fourni à des fins de contrôle des versions.
Les API 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
| Code d'état | Signification |
|---|---|
| 200 | La mise à jour a bien été effectuée |
| 400 | Une erreur de validation s'est produite. Par exemple, une requête contenant plus du nombre de clés autorisé (2 000) renvoie 400 (Bad Request) avec le message d'erreur Param count too large.
Ce code d'état HTTPS peut également se produire dans les deux situations suivantes:
|
| 401 | Une erreur d'autorisation s'est produite (aucun jeton d'accès n'a été fourni ou l'API REST Remote Config Firebase n'a pas été ajoutée à votre projet dans la console de développement Cloud) |
| 403 | Une erreur d'authentification s'est produite (le mauvais jeton d'accès a été fourni) |
| 500 | Une erreur interne s'est produite. Si cette erreur se produit, ouvrez une demande d'assistance Firebase. |
Un code d'état de 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. D'autres codes d'état indiquent que le modèle Remote Config existant est toujours en vigueur.
Une fois que vous avez envoyé les modifications de votre modèle, accédez à la console Firebase pour vérifier que vos modifications s'affichent comme prévu. Cela est essentiel, car l'ordre des conditions affecte la façon dont elles sont évaluées (la première condition qui évalue true prend effet).
Utilisation des ETags 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 des ressources qui se chevauchent. Pour en savoir plus sur les ETags, consultez la page 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 d'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 émettre 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'il offre en forçant la mise à jour du modèle Remote Config comme suit: If-Match: *
Cependant, cette approche n'est pas recommandée, car elle risque de perdre les mises à jour de votre modèle Remote Config si plusieurs clients le mettent à jour.Remote Config Ce type de conflit peut se produire avec plusieurs clients utilisant l'API ou avec des mises à jour en conflit de la part des clients de l'API et des utilisateurs de la console Firebase.
Pour obtenir des conseils sur la gestion des versions de modèles Remote Config, consultez la section Modèles et gestion des versions Remote Config.