Accéder aux comptes publicitaires

Comptes utilisateur vs comptes publicitaires

Deux types de comptes différents interviennent dans l’utilisation de l’Ads API : les comptes publicitaires et les comptes utilisateur X. Dans l’ensemble de la documentation de l’Ads API, le terme « compte » fait généralement référence au compte publicitaire.

• Les comptes publicitaires sont enregistrés sur business.x.com et identifiés dans l’API par account_id. Les comptes publicitaires sont directement liés à des sources de financement et utilisent le contenu d’un ou plusieurs comptes utilisateur X en tant que « promotable users ». Chaque compte publicitaire peut accorder des autorisations à un ou plusieurs comptes utilisateur X. Le compte publicitaire, ou « compte actuel », est représenté dans presque toutes les URL exécutées sous la forme d’un paramètre en ligne :account_id.
• Les comptes utilisateur X (comme @AdsAPI) sont identifiés par user_id dans l’Ads API. Un ou plusieurs de ces comptes peuvent être associés à un compte publicitaire. Le compte utilisateur X authentifié qui effectue des requêtes sur l’API est appelé « utilisateur actuel ». La liste des comptes publicitaires auxquels l’utilisateur actuel a accès est disponible via GET accounts. Les « promotable users » sont des handles X qui peuvent être promus par un compte publicitaire spécifique. Pour plus de détails à ce sujet, consultez Obtaining Ads Account Access.

Méthodes d’accès aux comptes publicitaires

Il existe deux méthodes que vous pouvez utiliser pour effectuer des requêtes vers l’API Ads pour le compte d’un annonceur :

1. Effectuer des requêtes au nom d’un annonceur (recommandé)
2. Effectuer des requêtes en utilisant votre propre compte, auquel a été accordé l’accès au compte d’un annonceur, par exemple une agence gérant plusieurs comptes.

Ce document propose un bref aperçu des différences entre ces options et doit être utilisé conjointement avec nos autres ressources, telles que la FAQ sur la connexion multi-utilisateurs. 

Comme décrit dans Authorizing a request, toutes les requêtes vers l’API Ads nécessitent des en-têtes d’autorisation utilisant OAuth 1.0a avec un jeton d’accès obtenu via un flux 3-legged OAuth. Votre application devra implémenter un flux OAuth basé sur le Web pour obtenir des jetons d’accès. Les développeurs de l’API Ads ne doivent jamais demander à nos annonceurs X de partager leurs identifiants de connexion.

Par défaut, chaque application développeur X contient un jeton d’accès statique qui peut être utilisé pour effectuer des requêtes vers l’API Ads pour le compte qui possède l’application. Ces identifiants sont idéaux pour les cas d’usage à compte unique, sans nécessiter de flux OAuth 3-legged ou basé sur un code PIN. Si vous n’accédez pas à un autre compte X Ads, utilisez ces identifiants single-user plutôt que les étapes suivantes.

Niveaux d’accès

Autorisations au niveau de l’App

Chaque utilisateur disposera d’un niveau d’accès correspondant à ce qui a été demandé lors de la demande d’accès à l’Ads API :

• Conversions uniquement : L’utilisateur dispose d’un accès aux endpoints Mobile et Web Conversion avec des autorisations de lecture et écriture.
• Accès standard : L’utilisateur dispose d’un accès aux endpoints Analytics, Gestion des campagnes, Creatives, Audiences personnalisées et Conversion avec des autorisations de lecture et écriture.

Remarque : Les développeurs Ads API qui ont demandé l’accès avant juillet 2023 peuvent disposer de niveaux d’accès et d’autorisations différents et peuvent être limités à cinq jetons OAuth. Consultez notre guide sur l’augmentation de l’accès pour obtenir un accès à des endpoints supplémentaires ou lever les limites de jetons pour les Apps existantes.

Autorisations au niveau du compte publicitaire

Chaque utilisateur qui a accès à un compte publicitaire disposera d’une autorisation spécifique au niveau du compte : Administrateur de compte, Gestionnaire de publicités, Analyste de campagnes, Analyste organique et Gestionnaire de créations ; consultez business.x.com pour la documentation la plus récente concernant les autorisations au niveau du compte. Les applications doivent récupérer les autorisations pour l’utilisateur actuellement authentifié via le point de terminaison d’API Authenticated User Access afin de déterminer à quels points de terminaison d’API et à quelles fonctionnalités publicitaires elles peuvent accéder.

Remarque : Tous les jetons utilisateur utilisés avec la Conversion API doivent appartenir à des utilisateurs disposant d’autorisations au niveau du compte Administrateur de compte ou Gestionnaire de publicités.                                                                                                                                              

Méthodes pour obtenir des jetons d’accès

1. Obtenir le jeton d’accès (Utilisateur) d’un annonceur

Il existe deux méthodes pour obtenir le jeton d’accès d’un annonceur. La méthode la plus courante consiste à utiliser un flux OAuth à 3 volets directement depuis votre interface web. Les applications qui n’ont pas d’interface publique accessible aux annonceurs peuvent implémenter un processus OAuth basé sur un code PIN. Une fois que l’utilisateur a terminé le flux à 3 volets, votre application disposera des identifiants lui permettant d’effectuer des requêtes pour son compte publicitaire via l’API.

L’obtention d’identifiants utilisateur via un flux OAuth est la méthode que nous recommandons fortement à la majorité des développeurs de l’API Ads pour obtenir l’accès à un compte annonceur. Elle vous permet d’appeler l’API au nom d’un utilisateur et d’effectuer des actions en tant que cet utilisateur. Ces jetons n’expirent pas mais peuvent être révoqués par l’utilisateur à tout moment.

2. Obtenir votre jeton d’accès (développeur)

Cette option nécessite que l’annonceur accorde à votre @username (ou à vos @usernames) l’accès à son compte X Ads via l’interface X sur business.x.com. Les jetons d’accès obtenus via le flux OAuth à trois volets pour votre compte pourront accéder au compte X Ads de l’annonceur.

Cela vous permet d’appeler l’API en utilisant les jetons OAuth de votre propre @username plutôt que les jetons OAuth de l’annonceur. La principale différence avec cette option est que vous ne pourrez créer des Publications uniquement promues que si l’autorisation de délégation/de création de Publications a été accordée à votre @username.

Pour obtenir l’accès à la création de Publications uniquement promues pour le compte de l’utilisateur promouvable FULL associé au compte, vous devez également recevoir l’autorisation de créer des Publications dans ce flux. Cela vous donnera accès via la permission TWEET_COMPOSER sur l’endpoint GET accounts/:account_id/authenticated_user_access.

Différences entre ces méthodes

	Jeton OAuth annonceur (utilisateur)	Jeton OAuth (développeur) (@username ajouté à un compte distinct)
Accéder au compte X Ads	✔	✔
Créer des Publications pour le compte de l’utilisateur	✔	✔*
Gérer les campagnes	✔	✔
Accéder aux statistiques	✔	✔
Créer des Cards pour le compte de l’utilisateur	✔	✔
Possibilité pour le développeur d’accéder via l’interface X Ads		✔
Limites de taux	Distinct pour chaque annonceur	Distinct pour chaque compte annonceur

Remarque : Voir la section Obtenir votre jeton d’accès (développeur) ci-dessus pour plus de détails.

Exemple de cas d’usage

Jeton d’accès de l’annonceur via le flux web OAuth à 3 volets

Le flux standard est basé sur le web et utilise le flux OAuth à 3 volets. Les captures d’écran présentées ici font partie d’un exemple dont vous pouvez consulter le code source sur https://github.com/xdevplatform/twauth-web.

À un certain moment dans votre application, vous devrez rediriger l’utilisateur vers X afin qu’il autorise votre application.

Lorsque vous redirigez vers X avec le jeton de requête, l’utilisateur est invité à autoriser votre application.

Une fois l’autorisation accordée à votre application, l’utilisateur est redirigé vers l’URL de rappel fournie lorsque vous avez généré le jeton de requête. Vous utiliserez cette URL pour obtenir le jeton d’accès permanent pour cet utilisateur et le stocker localement !