API Marketing

Authentification

Chaque appel d’API à destination des API Graph et Marketing doit inclure un token d’accès dans ses paramètres. Ce guide vous explique comment obtenir des tokens d’accès à tester.

Pour en savoir plus sur l’authentification, consultez notre documentation principale : Tokens d’accès pour les technologies Meta

Cette documentation traite des points suivants :

Explorateur de l’API Graph

Vous pouvez obtenir un token d’accès d’utilisateur·ice test à l’aide de l’Explorateur de l’API Graph. Pour apprendre à utiliser l’explorateur, consultez le Guide de l’Explorateur de l’API Graph.

Obtenir le token d’accès d’utilisateur·ice

  1. Accédez à l’Explorateur de l’API Graph.
  2. Dans Application Facebook, sélectionnez une application utilisée pour obtenir le token d’accès.
  3. Dans Utilisateur ou Page, sélectionnez Token utilisateur.
  4. Sous Autorisations, cochez ads_read.
  5. Cliquez sur Générer un token d’accès. Le token d’accès apparaît dans le champ situé au-dessus du bouton.
  6. Notez-le pour plus tard.

Débogage

Pour en savoir plus sur le token que vous venez de générer, cliquez sur le bouton i affiché avant le token. Une fenêtre contextuelle s’affiche avec les informations de base sur le token. Cliquez sur Ouvrir dans l’outil Access Token pour être redirigé vers le débogueur de tokens d’accès.

Vous pouvez également accéder directement au Débogueur de token d’accès et coller le token que vous avez généré dans le champ de texte.

Pendant le débogage, vérifiez les éléments suivants :

  • ID d’application : l’ID d’application mentionné dans la section des conditions requises.
  • Expiration : un horodatage. Un token de courte durée expire après une ou deux heures.
  • Étendues : autorisations ajoutées dans l’Explorateur de l’API Graph.

Étendre le token d’accès

  1. Réalisez toutes les étapes pour obtenir le token d’accès en utilisant l’Explorateur de l’API Graph.
  2. Copiez votre token. Collez-le dans le champ de texte du Débogueur de token d’accès.
  3. Dans le Débogueur de token d’accès, faites défiler la page jusqu’en bas.
  4. Cliquez sur Étendre le token d’accès pour obtenir un token de longue durée. Copiez ce token pour l’utiliser plus tard.

Vérifiez les propriétés de votre nouveau token avec le Débogueur de token d’accès. Sa durée de vie sous « Expiration » devrait être plus longue (60 jours ou Jamais, par exemple). Consultez la page Tokens d’accès de longue durée.

Utiliser un token d’accès d’utilisateur·ice système

Un token d’accès d’utilisateur·ice système est un type de token d’accès associé à un compte d’utilisateur·ice système, qui est un compte créé dans Business Manager dans le but de gérer des éléments et d’appeler l’API Marketing. Les tokens d'accès d’utilisateur·ice système sont utiles pour les interactions entre serveurs lorsqu’aucun·e utilisateur·ice n’est présent·e pour l'authentification. Ils peuvent être utilisés pour effectuer des actions au nom de l’entreprise, comme la lecture et la rédaction de données professionnelles, la gestion de campagnes publicitaires et d’autres objets publicitaires.

L'un des avantages du token d'accès d’utilisateur·ice système est qu'il n'expire pas ; il peut donc être utilisé dans des scripts ou des services de longue durée qui ont besoin d'accéder à l’API Graph. De plus, comme les comptes d’utilisateur·ice système ne sont pas liés à une personne spécifique, ils peuvent être utilisés pour assurer un niveau de séparation entre l’activité personnelle et l’activité professionnelle sur Facebook.

Les tokens d’accès d’utilisateur·ice système sont également moins susceptibles d'être invalidés pour d'autres raisons par rapport aux tokens d'accès d’utilisateur·ice de longue durée.

Obtenir un token manuellement

Si l’utilisateur·ice clique sur le bouton Autoriser lorsque vous l’invitez à accorder des autorisations étendues, il ou elle est redirigé·e vers une URL contenant la valeur du paramètre redirect_uri et un code d’autorisation :

http://YOUR_URL?code=<AUTHORIZATION_CODE>

Créez une URL comprenant le point de terminaison pour obtenir un token, votre ID d’application, votre URL de site Web, votre clé secrète et le code d’autorisation que vous venez de recevoir. L’URL ressemblera à la suivante :

https://graph.facebook.com/<API_VERSION>/oauth/access_token?
  client_id=<YOUR_APP_ID>
  &redirect_uri=<YOUR_URL>
  &client_secret=<YOUR_APP_SECRET>
  &code=<AUTHORIZATION_CODE>

La réponse doit contenir le token d’accès pour l’utilisateur·ice :

  • Si vous suivez le flux d’authentification côté serveur, vous obtenez un token permanent.
  • Si vous suivez le flux d’authentification côté client, vous obtenez un token ayant une période de validité déterminée d’environ une à deux heures. Vous pouvez l’échanger contre un token permanent en appelant le point de terminaison de l’API Graph pour étendre les tokens.

Si l’API doit être invoquée par un·e utilisateur·ice système dans une entreprise, vous pouvez utiliser un token d’accès d’utilisateur·ice système.

Vous pouvez déboguer le token d’accès, vérifier la date d’expiration et valider les autorisations accordées à l’aide du débogueur de tokens d’accès ou de l’API de validation par programmation.

Enregistrer le token

Le token doit être conservé en toute sécurité dans votre base de données pour des appels d’API ultérieurs. Déplacez les tokens entre votre client et votre serveur en toute sécurité au moyen du protocole HTTPS afin de protéger les comptes des utilisateur·ices. Apprenez-en davantage sur les conséquences du déplacement de tokens entre vos clients et votre serveur.

Vous devez vérifier régulièrement la validité du token et, le cas échéant, inviter l’utilisateur·ice à accorder une autorisation. Même un token permanent peut devenir non valide dans certains cas, y compris les suivants :

  • Modification du mot de passe de l’utilisateur·ice
  • Annulation des autorisations par l’utilisateur·ice

Étant donné que les tokens d’accès d’utilisateur·ice peuvent perdre leur validité ou être annulés à tout moment, votre application doit disposer d’un flux permettant de demander à nouveau l’autorisation de l’utilisateur·ice. Lorsqu’un utilisateur ou une utilisatrice commence à utiliser votre application Web, vérifiez la validité du token dont vous disposez pour cette personne. Envoyez-le au besoin par le biais du flux d’authentification pour obtenir un token mis à jour.

Si votre application ne le permet pas, vous devrez peut-être avoir recours à une autre façon d’inviter l’utilisateur·ice. Par exemple, si les appels d’API ne sont pas déclenchés directement par une interface d’utilisation ou sont effectués par des scripts exécutés sur une base régulière. Une solution possible consiste à envoyer aux utilisateur·ices un e-mail comportant des instructions.