Migrer des anciennes API FCM vers HTTP v1

Les applications utilisant les anciennes API FCM obsolètes pour HTTP et XMPP doivent migrer vers l'API HTTP v1 dès que possible. L'envoi de messages (y compris les messages en amont) avec ces API est obsolète depuis le 20 juin 2023 et sera supprimé en juin 2024 .

En plus d'un support continu et de nouvelles fonctionnalités, l'API HTTP v1 présente les avantages suivants par rapport aux API existantes :

  • Meilleure sécurité via les jetons d'accès L'API HTTP v1 utilise des jetons d'accès de courte durée selon le modèle de sécurité OAuth2. Dans le cas où un jeton d'accès devient public, il ne peut être utilisé de manière malveillante que pendant environ une heure avant son expiration. Les jetons d'actualisation ne sont pas transmis aussi souvent que les clés de sécurité utilisées dans l'ancienne API, ils sont donc beaucoup moins susceptibles d'être capturés.

  • Personnalisation plus efficace des messages sur toutes les plateformes Pour le corps du message, l'API HTTP v1 possède des clés communes qui vont à toutes les instances ciblées, ainsi que des clés spécifiques à la plateforme qui vous permettent de personnaliser le message sur toutes les plateformes. Cela vous permet de créer des « remplacements » qui envoient des charges utiles légèrement différentes à différentes plates-formes clientes dans un seul message.

  • Plus extensible et évolutive pour les nouvelles versions de plate-forme client L'API HTTP v1 prend entièrement en charge les options de messagerie disponibles sur les plates-formes Apple, Android et Web. Étant donné que chaque plateforme possède son propre bloc défini dans la charge utile JSON, FCM peut étendre l'API à de nouvelles versions et à de nouvelles plateformes selon les besoins.

Mettre à jour le point de terminaison du serveur

L'URL du point de terminaison de l'API HTTP v1 diffère du point de terminaison existant de la manière suivante :

  • Il est versionné, avec /v1 dans le chemin.
  • Le chemin contient l'ID du projet Firebase pour votre application, au format /projects/myproject-ID/ . Cet identifiant est disponible dans l'onglet Paramètres généraux du projet de la console Firebase.
  • Il spécifie explicitement la méthode send comme :send .

Pour mettre à jour le point de terminaison du serveur pour HTTP v1, ajoutez ces éléments au point de terminaison dans l'en-tête de vos requêtes d'envoi.

Requêtes HTTP avant

POST https://fcm.googleapis.com/fcm/send

Requêtes XMPP avant

Les messages XMPP hérités sont envoyés via une connexion au point de terminaison suivant :

fcm-xmpp.googleapis.com:5235

Après

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Mettre à jour l'autorisation des demandes d'envoi

À la place de la chaîne de clé du serveur utilisée dans les requêtes héritées, les requêtes d'envoi HTTP v1 nécessitent un jeton d'accès OAuth 2.0. Si vous utilisez le SDK Admin pour envoyer des messages, la bibliothèque gère le jeton pour vous. Si vous utilisez un protocole brut, obtenez le jeton comme décrit dans cette section et ajoutez-le à l'en-tête sous le nom Authorization: Bearer <valid Oauth 2.0 token> .

Avant

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Après

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

En fonction des détails de votre environnement de serveur, utilisez une combinaison de ces stratégies pour autoriser les requêtes de serveur aux services Firebase :

  • Informations d'identification par défaut de l'application Google (ADC)
  • Un fichier JSON de compte de service
  • Un jeton d'accès OAuth 2.0 de courte durée dérivé d'un compte de service

Si votre application s'exécute sur Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions (y compris Cloud Functions pour Firebase), utilisez les informations d'identification par défaut de l'application (ADC). ADC utilise votre compte de service par défaut existant pour obtenir les informations d'identification permettant d'autoriser les demandes, et ADC permet des tests locaux flexibles via la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS . Pour l’automatisation la plus complète du flux d’autorisation, utilisez ADC avec les bibliothèques du serveur Admin SDK.

Si votre application s'exécute sur un environnement de serveur autre que Google , vous devrez télécharger un fichier JSON de compte de service à partir de votre projet Firebase. Tant que vous avez accès à un système de fichiers contenant le fichier de clé privée, vous pouvez utiliser la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pour autoriser les demandes avec ces informations d'identification obtenues manuellement. Si vous ne disposez pas d'un tel accès aux fichiers, vous devez référencer le fichier du compte de service dans votre code, ce qui doit être fait avec une extrême prudence en raison du risque d'exposition de vos informations d'identification.

Fournir des informations d'identification à l'aide d'ADC

Les informations d'identification par défaut de l'application Google (ADC) vérifient vos informations d'identification dans l'ordre suivant :

  1. ADC vérifie si la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS est définie. Si la variable est définie, ADC utilise le fichier de compte de service vers lequel pointe la variable.

  2. Si la variable d'environnement n'est pas définie, ADC utilise le compte de service par défaut fourni par Compute Engine, Google Kubernetes Engine, App Engine et Cloud Functions pour les applications qui s'exécutent sur ces services.

  3. Si ADC ne peut utiliser aucune des informations d’identification ci-dessus, le système génère une erreur.

L’exemple de code du SDK Admin suivant illustre cette stratégie. L'exemple ne spécifie pas explicitement les informations d'identification de l'application. Cependant, ADC est capable de trouver implicitement les informations d'identification tant que la variable d'environnement est définie ou tant que l'application s'exécute sur Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions.

Noeud.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Aller

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Fournir les informations d'identification manuellement

Les projets Firebase prennent en charge les comptes de service Google, que vous pouvez utiliser pour appeler les API du serveur Firebase à partir de votre serveur d'applications ou d'un environnement approuvé. Si vous développez du code localement ou déployez votre application sur site, vous pouvez utiliser les informations d'identification obtenues 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 en toute sécurité le fichier JSON contenant la clé.

Lors de l'autorisation via un compte de service, vous avez deux choix pour fournir les informations d'identification à votre application. Vous pouvez soit définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS , soit 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 fortement recommandée.

Pour définir la variable d'environnement :

Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin du fichier JSON qui contient la clé de votre compte de service. Cette variable s'applique uniquement à votre session shell actuelle, donc si vous ouvrez une nouvelle session, définissez à nouveau la variable.

Linux ou macOS

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

les fenêtres

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 informations d'identification par défaut de l'application (ADC) sont capables de déterminer implicitement vos informations d'identification, vous permettant d'utiliser les informations d'identification du compte de service lors des tests ou de l'exécution dans des environnements non Google.

Utilisez les informations d'identification pour créer des jetons d'accès

Utilisez vos informations d'identification Firebase avec la bibliothèque d'authentification Google pour votre langue préférée pour récupérer un jeton d'accès OAuth 2.0 de courte durée :

nœud.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Dans cet exemple, la bibliothèque cliente de l'API Google authentifie la requête avec un jeton Web JSON, ou JWT. Pour plus d'informations, consultez Jetons Web JSON .

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}

Après l'expiration de votre jeton d'accès, 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 à FCM, demandez la portée https://www.googleapis.com/auth/firebase.messaging .

Pour ajouter le jeton d'accès à un en-tête de requête HTTP :

Ajoutez le jeton comme valeur de l'en-tête Authorization au format Authorization: Bearer <access_token> :

nœud.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

Mettre à jour la charge utile des requêtes d'envoi

FCM HTTP v1 introduit un changement significatif dans la structuration de la charge utile des messages JSON. Principalement, ces modifications garantissent que les messages sont traités correctement lorsqu'ils sont reçus sur différentes plates-formes clientes ; de plus, les modifications vous offrent une flexibilité supplémentaire pour personnaliser ou « remplacer » les champs de message par plate-forme.

En plus d'inspecter les exemples de cette section, consultez Personnalisation d'un message sur plusieurs plates-formes et consultez la référence de l'API pour vous familiariser avec HTTP v1.

Exemple : simple message de notification

Voici une comparaison d'une charge utile de notification très simple (contenant uniquement les champs title , body et data démontrant les différences fondamentales entre les charges utiles héritées et HTTP v1.

Avant

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

Après

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

Exemple : cibler plusieurs plates-formes

Pour activer le ciblage sur plusieurs plates-formes, l'ancienne API effectuait des remplacements dans le backend. En revanche, HTTP v1 fournit des blocs de clés spécifiques à la plate-forme qui rendent explicites et visibles les différences entre les plates-formes pour le développeur. Cela vous permet de cibler plusieurs plates-formes toujours avec une seule requête, comme le montre l'exemple suivant.

Avant

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Après

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Exemple : personnalisation avec des remplacements de plateforme

En plus de simplifier le ciblage multiplateforme des messages, l'API HTTP v1 offre la flexibilité de personnaliser les messages par plateforme.

Avant

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Après

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Exemple : cibler des appareils spécifiques

Pour cibler des appareils spécifiques avec l'API HTTP v1, fournissez le jeton d'enregistrement actuel de l'appareil dans la clé token au lieu de la clé to .

Avant

  { "notification": {
      "body": "This is an FCM notification message!",
      "time": "FCM Message"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }

Après

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Pour plus d'exemples et d'informations sur l'API FCM HTTP v1, consultez ce qui suit :