Accès aux comptes publicitaires

​

Comptes utilisateur vs comptes publicitaires

Il existe deux types de comptes impliqués dans l’utilisation de la X Ads API : les comptes publicitaires et les comptes utilisateur X. Dans l’ensemble de la documentation de la X 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. Ils sont directement liés aux sources de financement et exploitent le contenu d’un ou plusieurs comptes utilisateur X en tant qu’« utilisateurs promouvables ». Chaque compte publicitaire peut accorder des autorisations à un ou plusieurs comptes utilisateur X. Le compte publicitaire, ou « compte courant », est présent dans presque toutes les URL exécutées sous la forme d’un paramètre en ligne :account_id.
• Les comptes utilisateur X (tels que @AdsAPI) sont identifiés par user_id dans la X 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 peut être obtenue avec GET accounts. Les « utilisateurs promouvables » 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 au compte publicitaire

Il existe deux méthodes pour effectuer des requêtes vers la X Ads API 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 l’accès au compte d’un annonceur a été accordé, par exemple une agence gérant plusieurs comptes.

Ce document offre 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-utilisateur.

Comme décrit dans Autoriser une requête, toutes les requêtes vers la X Ads API exigent des en-têtes Authorization utilisant OAuth 1.0a avec un access token obtenu via un flux OAuth à 3 intervenantsOAuth. Votre application devra implémenter un flux OAuth basé sur le Web pour obtenir des access tokens. Les développeurs de la X Ads API ne doivent jamais demander à nos annonceurs X de partager leurs identifiants de connexion.

Par défaut, chaque X developer application contient un access token statique qui peut être utilisé pour effectuer des requêtes vers la X Ads API pour le compte propriétaire de l’application. Ces identifiants sont idéaux pour des cas d’usage mono-compte sans nécessiter un flux OAuth à 3 intervenants ou basé sur un PIN. Si vous n’accédez pas à un autre compte X Ads, utilisez plutôt ces identifiants mono-utilisateur au lieu des étapes suivantes.

​

Niveaux d’accès

​

Autorisations au niveau de l’App

Chaque utilisateur se verra attribuer un niveau d’accès tel que demandé lors de la demande d’accès à la X Ads API :

• Conversions uniquement : l’utilisateur a accès aux endpoints Mobile et Web Conversion avec des droits de lecture et écriture.
• Accès standard : l’utilisateur a accès aux endpoints Analytics, Campaign Management, Creatives, Custom Audiences et Conversion avec des droits de lecture et écriture.

Remarque : Les développeurs de la X Ads API ayant 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 l’accès à des endpoints supplémentaires ou lever les limites de jetons pour les applications existantes.

​

Autorisations au niveau du compte publicitaire

Chaque utilisateur ayant accès à un compte publicitaire dispose d’une autorisation spécifique au niveau du compte : Account administrator, Ad manager, Campaign analyst, Organic analyst et Creative Manager ; consultez business.x.com pour la documentation la plus récente relative aux autorisations au niveau du compte. Les applications doivent récupérer les autorisations de l’utilisateur actuellement authentifié via l’endpoint d’API Authenticated User Access afin de déterminer quels endpoints d’API et quelles fonctionnalités Ads sont accessibles.

Remarque : Tous les jetons utilisateur utilisés avec la Conversion API doivent appartenir à des utilisateurs disposant des autorisations au niveau du compte Account administrator ou Ad manager.                                                                                                                                              

​

Méthodes d’obtention des access tokens

​

1. Obtenir l’access token d’un annonceur (Utilisateur)

Il existe deux méthodes pour obtenir un access token d’annonceur. La plus courante consiste à utiliser un flux OAuth à 3 étapes directement depuis votre interface web. Les applications qui n’ont pas d’interface publique accessible aux annonceurs peuvent mettre en œuvre un processus OAuth basé sur un code PIN. Une fois que l’utilisateur a terminé le flux à 3 étapes, votre application disposera des identifiants nécessaires pour effectuer des requêtes sur son compte Ads via l’API.

L’obtention des identifiants utilisateur via un flux OAuth est la méthode que nous recommandons vivement à la majorité des développeurs de la X Ads API pour accéder à un compte annonceur. Cela vous permet d’appeler l’API au nom d’un utilisateur et d’agir en tant que cet utilisateur. Ces tokens n’expirent pas, mais peuvent être révoqués par l’utilisateur à tout moment.

​

2. Obtenir votre access token (Developer)

Cette option requiert que l’annonceur accorde l’accès à votre @username (ou à des @usernames) à son compte X Ads via l’interface X sur business.x.com. Les Access Tokens obtenus via le flux OAuth à 3 étapes pour votre compte pourront accéder au compte X Ads de l’annonceur.

Cela vous permet d’appeler l’API en utilisant les tokens OAuth de votre propre @username plutôt que ceux de l’annonceur. La principale distinction avec cette option est que vous ne pouvez créer des Posts « Promoted‑Only » que si l’autorisation de délégation/composition de Post a été accordée à votre @username.

Pour obtenir l’accès à la création de Posts « Promoted‑Only » au nom de l’utilisateur promouvable FULL sur le compte, vous devez également obtenir l’autorisation de créer des Posts dans ce flux. Cela activera l’accès via l’autorisation 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é pour distinguer le compte)
Accès au compte publicitaire	✔	✔
Création de Posts au nom de l’utilisateur	✔	✔*
Gestion des campagnes	✔	✔
Accès aux analytics	✔	✔
Création de Cards au nom de l’utilisateur	✔	✔
Accès du développeur via l’interface X Ads		✔
Limites de taux	Distinctes par annonceur	Distinctes par compte annonceur

Remarque : Voir la section Obtenir votre access token (développeur) ci-dessus pour plus de détails.

​

Exemple d’utilisation

​

Access Token de l’annonceur via le flux web OAuth à 3 étapes

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

À un moment donné dans votre application, vous souhaiterez rediriger l’utilisateur vers X afin d’autoriser votre application.

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

Après avoir autorisé votre application, l’utilisateur est redirigé vers l’URL de rappel fournie lorsque vous avez généré le jeton de requête. Vous l’utiliserez pour obtenir l’Access Token permanent pour cet utilisateur et le stocker localement.