Audiences

Audiences personnalisées

Vue d’ensemble

Il existe plusieurs façons pour les partenaires de créer des Audiences personnalisées.

Audience API (CRM)
Web
Mobile
Flexible

Veuillez noter que vous ne pouvez pas exclure les audiences personnalisées similaires (lookalike) du ciblage. De plus, vous ne pouvez pas cibler à la fois une audience personnalisée et une audience personnalisée similaire (lookalike) au sein du même élément de campagne publicitaire (groupe de publicités). Gestion des audiences Les audiences peuvent être gérées via des partenaires d’audience et des partenaires Ads API. Nous proposons une série d’endpoints dans l’API pour accéder aux audiences personnalisées et les gérer. Pour les informations relatives aux audiences personnalisées, nous proposons 2 endpoints :

Pour plus de détails sur la façon de charger et de gérer les audiences, consultez le guide Audience API. Délais de traitement De manière générale, les modifications d’audience sont traitées par lots toutes les 6 à 8 heures. Pendant qu’une modification d’audience est en cours de traitement, l’audience existante devant être mise à jour n’est pas affectée. Nous ne recommandons pas d’effectuer plus d’une mise à jour pour les ajouts et une mise à jour pour les suppressions par audience dans cet intervalle de temps. Ciblage Une audience ne peut être ciblée que si elle correspond à au moins 100 utilisateurs actifs au cours des 90 derniers jours sur les clients détenus et exploités par X. GET accounts/:account_id/custom_audiences/:custom_audience_id indiquera si une audience ne peut pas être ciblée parce qu’elle correspond à un nombre insuffisant d’utilisateurs. Audience API (CRM)

Les partenaires d’audience ou API fournissent une liste d’identifiants hachés et X effectue un appariement et produit des segments qui sont mis à disposition pour l’achat média sur X. Les partenaires peuvent créer ces audiences avec l’Audience API. Fonctionnement

Web Nous proposons un processus standard de mise en correspondance de cookies lorsque nous travaillons avec des partenaires d’audience MPP afin d’identifier les segments à cibler pour l’achat média sur X. En outre, les annonceurs peuvent configurer une balise X Web Event Tag pour collecter les données des utilisateurs de leur site web et créer une audience personnalisée correspondante. Étapes de configuration

Fonctionnement

Mobile Veuillez consulter l’article de blog Custom Audiences from Mobile Apps pour plus de détails. Flexible Les audiences flexibles donnent aux annonceurs la possibilité de créer et d’enregistrer des combinaisons d’audiences basées sur des audiences personnalisées existantes ou des sous-ensembles d’audiences personnalisées existantes. Les sous-ensembles des membres d’une audience personnalisée peuvent être ciblés en fonction de la récence et de la fréquence des interactions. Cas d’utilisation restreints pour les audiences personnalisées En savoir plus sur les restrictions

FAQ sur les audiences

Q : Nous avons transmis une très grande quantité de données, pourquoi la taille de l’audience apparaît-elle comme TOO_SMALL ? R : Actuellement, les données sont ajoutées à l’audience en temps réel, mais la tâche qui traite les données pour fournir la taille de l’audience ne s’exécute qu’après une certaine période. La taille correcte de l’audience devrait s’afficher dans l’interface au bout de quelques heures. Q : Nous avons terminé l’envoi des données d’audience et attendu 24 heures ou plus, mais nous ne pouvons toujours pas cibler l’audience – quelles doivent être les prochaines étapes ? R : Veuillez confirmer les éléments suivants :

L’ID utilisateur transmis est correct et non mal formé.
Les noms d’audience transmis sont corrects et correspondent aux mises à jour de membres précédentes.
Veuillez confirmer la réponse aux commandes POST.
Veuillez confirmer que le pixel ID Sync est correctement implémenté et, comme décrit par le processus ID Sync, qu’un nombre suffisant d’utilisateurs ont visité le site en question pour pouvoir faire la correspondance des utilisateurs. Les utilisateurs non mappés dans les mises à jour de membres ne seront pas traduits en utilisateurs ciblés.

Si tout le reste est confirmé comme correct et fonctionnel, veuillez contacter vos interlocuteurs produit chez X avec des informations aussi détaillées que possible (voir par exemple le Guide to Partner Inbounds pour le type d’informations souhaité). Q : Combien de fois pouvons-nous appeler l’endpoint, et avec quel algorithme ? R : Nous vous recommandons fortement d’appeler notre système avec des deltas incrémentaux et de ne jamais renvoyer l’ensemble complet des membres de l’audience. Le système a été testé avec un débit suffisant pour traiter des mises à jour de données incrémentales pour certains des plus grands sites Web au monde. Le chargement initial des audiences doit être soigneusement limité, et il est prévu que ce premier chargement prenne un temps significatif pour se terminer. Q : Quelle est la taille minimale d’une audience pouvant être utilisée pour le ciblage ?

La taille minimale d’une audience est de 100 utilisateurs (après correspondance). Si une audience avec moins de 500 utilisateurs est mise en correspondance, elle ne sera pas disponible pour le ciblage dans l’interface utilisateur X Ads.

Q : Combien de temps faudra-t-il pour traiter les fichiers d’audience ? Et combien de temps faudra-t-il pour que les fichiers d’audience soient prêts dans l’interface utilisateur X ?

Le traitement des fichiers d’audience prend généralement 4 à 6 heures, mais cela dépendra de la taille du fichier. Une fois le fichier traité, les audiences sont disponibles dans l’interface utilisateur X Ads.

Q : Comment le taux de correspondance est-il calculé ?

Taux de correspondance = utilisateurs X actifs sur 90 jours / nombre d’utilisateurs fournis

Q : Comment tester si un fichier d’audience fonctionne correctement ?

Vous pouvez fournir un fichier d’audience de test et utiliser « keltonlynn » comme handle d’annonceur. Nous pourrons alors vérifier que le fichier est correctement ingéré et chargé dans l’interface X.

Q : Qu’est-ce qu’un identifiant utilisateur partenaire (p_user_id) ?

C’est l’identifiant utilisé par votre entreprise pour identifier de manière unique chacun de vos clients.

Q : Qu’est-ce qu’un ID standard ?

Cela peut être une adresse e-mail, un device ID, un @handle X ou un ID.

Q : Comment puis-je obtenir la clé HMAC ?

Elle sera fournie par un e-mail chiffré. Veuillez fournir votre clé PGP publique à mpp-inquiry@x.com et nous vous enverrons un e-mail de test pour vérifier que tout fonctionne. Une fois la vérification effectuée, nous vous enverrons la clé HMAC.

Q : Comment puis-je vérifier que le processus de hachage a fonctionné en utilisant la clé HMAC fournie ?

X fournira un fichier de test (contenant des exemples d’adresses e-mail, de device IDs, etc.) et un fichier de hachage résultant, que vous pourrez utiliser pour vérifier vos résultats.

Q : Y a-t-il une limite de taille pour le fichier de correspondance de données complet ?

Non, il n’y a pas de limite de taille pour le fichier de correspondance de données complet.

Q : Combien de temps faudra-t-il pour traiter le fichier de correspondance de données complet ?

Une fois le fichier reçu par X, il faudra environ 1 jour pour traiter le fichier.

CRM

Ce document décrit les modalités d’intégration pour les partenaires Custom Audiences CRM, y compris les formats de fichiers et le processus d’échange de données. Résumé La société fournira à X, au nom d’un client, une liste d’identifiants utilisateur courants hachés (c.-à-d. des adresses e‑mail) ou des id utilisateur du partenaire, afin d’effectuer une correspondance à l’aveugle et de produire une liste d’id d’utilisateur X pour le ciblage. Les segments de ciblage seront mis à la disposition du compte annonceur, via le @handle spécifique indiqué par le nom de fichier dans la configuration de campagne sur ads.x.com. Tous les fichiers provenant de la société seront fournis à X au moyen d’un package sécurisé sur IronBox (www.golockbox.com), à l’aide d’un compte spécifique accordé à la société par X. X fournira l’accès à IronBox. La documentation sur les API IronBox est disponible à l’adresse https://secure.goironcloud.com/Docs/Help/.

Exigences de correspondance des ID de partenaire

Si l’entreprise utilise son propre système standard d’ID pour suivre les utilisateurs (c.-à-d. pas d’identifiants utilisateur courants comme les adresses e‑mail, les id d’appareil, l’ID utilisateur X, etc.), alors il s’agit du processus recommandé. 1. Correspondance de données complète Initialement, l’entreprise fournira, dans un fichier unique, une liste exhaustive de tous les enregistrements utilisateur qui incluent avec X un identifiant utilisateur courant unique, afin d’effectuer une correspondance de données complète et de produire une table de correspondance, stockée par X, entre les ID partenaire (p_user_id) et les ID X (tw_id). Cette opération sera effectuée régulièrement tous les 2 à 3 mois pour garantir une mise à jour correcte. Une fois la correspondance terminée, X communiquera à l’entreprise, par e‑mail, un taux de correspondance de référence issu de ce fichier. Le format de ce fichier doit être : Convention de nommage : FullDataMatch.[CompanyName].txt Algorithme de hachage : HMAC_SHA-256 Format : Colonne 1 : valeur hachée HMAC des identifiants courants Colonne 2 : ID utilisateur partenaire (unique par utilisateur, non unique dans le fichier) Délimiteur de colonnes (CSV) : des virgules seront utilisées pour séparer l’identifiant utilisateur courant haché de l’ID partenaire Valeurs séparées par des sauts de ligne

Ex. : si l’enregistrement utilisateur A a l’ID utilisateur partenaire 1 et les identifiants courants 1, 2 et 3 :


identifiant utilisateur courant 1	p_user_1
identifiant utilisateur courant 2	p_user_1
identifiant utilisateur courant 3	p_user_1

*Voir la section Instructions de hachage ci‑dessous pour les identifiants utilisateur courants 2. Listes de segments personnalisés L’entreprise fournira des listes d’utilisateurs sous forme de p_user_id pour créer des audiences personnalisées pour les clients, en vue d’un ciblage sur X.

Valeurs séparées par des sauts de ligne
p_user_id
- (Identique à ce qui est fourni dans la section 1. Correspondance de données complète ci‑dessus. Si la valeur fournie dans la correspondance de données complète est hachée, l’entreprise fournira la même valeur hachée dans le fichier d’audience. Si la valeur fournie n’est pas hachée, l’entreprise fournira la valeur non hachée.)

Exigences de correspondance standard

Si l’entreprise n’utilise pas un identifiant standard pour la mise en correspondance de tous les identifiants utilisateur clients, le processus recommandé est le suivant. Listes de segments personnalisés L’entreprise fournira directement à X, au nom de ses clients, des listes d’identifiants utilisateur courants hachés afin de créer des audiences personnalisées. Le format de ce fichier doit être :

Valeurs séparées par des retours à la ligne
Identifiant utilisateur courant haché (c.-à-d. adresse e-mail)
Suivre les conventions de nommage de fichiers décrites ci-dessous
Suivre les instructions de hachage pour les adresses e-mail ci-dessous (voir la section Instructions de hachage)

Nommage et opérations des fichiers de liste de segments personnalisés

Le traitement appliqué à un fichier est déterminé par le nom du fichier, avec les opérations suivantes disponibles et la convention générale de nommage suivante : audiencename_partnername.handle.operation.filetype

audiencename : le nom de l’audience personnalisée. Ce champ est le nom qui sera affiché lors de la sélection de l’audience dans l’interface de configuration des campagnes ads.x.com, par exemple brand_loyalty_card_holders.
partnername : nom de la société fournissant les données pour le compte de l’annonceur, par exemple company_name.
handle : compte X (@handle) qui aura accès aux audiences personnalisées, par exemple @pepsi, @dietpepsi.
operation : new, add, remove, removeall, replace (détails ci‑dessous)
timestamp : horodatage Unix (epoch) standard en secondes, utilisé pour garantir que chaque fichier d’audience téléversé est unique
filetype : le fichier doit être au format *.txt

Création et mise à jour des audiences

Créer une nouvelle audience avec un seul fichier, par exemple loyalty_card_holders_partnername.pepsi.new.txt Add - Ajouter les correspondances d’une liste à une audience existante, par exemple loyalty_card_holders_partnername.pepsi.add..txt Remove - Supprimer les correspondances d’une liste dans une audience existante, par exemple loyalty_card_holders_partnername.pepsi.remove..txt Remove All - Supprimer les correspondances produites à partir d’une liste cumulative régulièrement mise à jour de toutes les audiences pour ce client (c’est‑à‑dire la liste de désinscription du Client). Ex : partnername.pepsi.removeall.txt

Ceci peut être utilisé pour une liste exhaustive d’utilisateurs qui se sont désinscrits de l’Annonceur.
X ne prendra en compte que la dernière liste fournie dans ce fichier et l’appliquera à toutes les audiences existantes et futures pour les utilisateurs X correspondants au moment où ce fichier a été fourni et traité.

Replace - Supprimer une audience existante et la remplacer par une nouvelle liste d’audience. Ex : loyalty_card_holders_partnername.pepsi.replace..txt Overall Company Opt-Out - L’entreprise fournira un fichier cumulatif de désinscription pour supprimer les utilisateurs qui se sont désinscrits conformément à la politique de désinscription de l’entreprise. X ne prendra en compte que la dernière liste fournie dans ce fichier de désinscription de l’entreprise et l’appliquera à toutes les audiences existantes et futures pour les utilisateurs X correspondants au moment où ce fichier a été fourni et traité. Le format du fichier de désinscription de l’entreprise sera le suivant : Ex : partnername.removeall.txt Delete - Supprimer une audience existante de la liste actuelle des audiences, par exemple loyalty_card_holders_partnername.pepsi.delete.txt

Instructions de hachage

X partagera de façon sécurisée, via PGP, une clé de production encodée en Base64 pour le hachage des identifiants utilisateur courants (c.-à-d. des adresses e-mail). L’entreprise effectuera le décodage Base64 de la clé afin de produire une clé de 32 octets qui sera utilisée pour le hachage. Exemple de clé encodée en Base64 : BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= Exemple de clé décodée en Base64 : /:� TшY Normalisation : l’entreprise appliquera une normalisation simple aux identifiants utilisateur courants avant le hachage (sauf pour les Device IDs, voir la section « Normalisation des ID d’appareil »).

Normalisation des e-mails

En d’autres termes, supprimez les espaces au début et à la fin, puis mettez également l’adresse e-mail en minuscules. Ex : Adresse e-mail brute : testemail_Organisational_baseball+884@It92I6Ev2B.Com Après normalisation : testemail_organisational_baseball+884@it92i6ev2b.com Valeur hachée : 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec Remarque : le nombre exact de caractères, aussi bien pour le HMAC encodé que pour la clé, peut varier en fonction de l’entrée et de l’encodage ; le nombre de caractères précis peut donc différer.

Normalisation des identifiants d’appareil

Nous appliquerons les mêmes exigences en matière de hachage des identifiants d’appareil à l’aide de l’algorithme de hachage SHA-256 et d’un sel commun que nous mettons à disposition de nos partenaires de données. Nous supprimons les espaces comme nous le faisons pour les adresses e-mail, mais il n’y a aucune normalisation en minuscules pour les IDFA/identifiants Android et le format exact de l’IDFA/de l’identifiant Android doit être utilisé. Voici un exemple de format brut des identifiants d’appareil pour iOS et Android, avant hachage : IDFA iOS : DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 ID Android : b5bf2122961b3595 IDFA iOS haché : 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b ID Android haché : 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

Normalisation des ID utilisateur X

Les ID X continueront d’être hachés, car le regroupement des données – par exemple une Liste de clients composée de @handles – reste privé pour l’annonceur, même s’il ne s’agit pas de données personnelles (PII). Nous appliquerons les mêmes exigences de hachage des ID X à l’aide de l’algorithme de hachage SHA-256 et d’un sel (« salt ») commun que nous fournissons aux partenaires de données. Les espaces doivent être supprimés à la fois de l’ID X et du @username, mais les User IDs ne nécessitent pas de normalisation. Les @usernames doivent être convertis en minuscules pour la normalisation. Le symbole @ ne doit pas être inclus dans le username. Le format brut de l’ID sera :

User ID : 27674040
@username : testusername

User ID haché : bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 @username haché : 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

Intégration de synchronisation d’ID

Les partenaires qui envoient des données avec un p_id doivent passer par un processus de synchronisation d’ID afin de générer une correspondance entre les identifiants utilisateur de l’annonceur ou du partenaire et les identifiants utilisateur X. Cela permet aux annonceurs de cibler directement leurs propres segments d’utilisateurs sur X. Les partenaires doivent également attribuer au paramètre user_identifier_type la valeur TALIST_PARTNER_USER_ID ou TAWEB_PARTNER_USER_ID lorsqu’ils envoient leurs mises à jour d’appartenance.

Web uniquement : cela peut se faire en plaçant un pixel sur le site de l’annonceur, comme indiqué ci‑dessous.
Liste : cela peut se faire en utilisant l’une des méthodes décrites sur la page CRM.

URL du pixel


URL de base
https://analytics.x.com/i/adsct

Paramètres du pixel


Paramètre	Description
`p_id`	Votre identifiant de partenaire attribué par X
`p_user_id`	L’identifiant de l’utilisateur dans le système partenaire

Pixel de synchronisation d’ID :

En utilisant un exemple d’id partenaire égal à 111 et un exemple de p_user_id égal à abc, le pixel généré serait le suivant :

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

Configuration des fichiers de désinscription et envoi des fichiers de désinscription Les partenaires doivent fournir à X une liste d’utilisateurs qui, à leur connaissance, ont choisi de se désinscrire de la diffusion de publicités ciblées. Le fichier doit être au format suivant :


Column Number	Column Name	Column Type	Description
1	Partner ID	string	Le « partner id » est l’ID qu’X fournit au partenaire afin d’identifier de manière unique chaque partenaire.
2	The user’s id in the partner system	string	Le `p_user_id` est l’ID unique utilisé par le partenaire pour identifier l’utilisateur. Le fichier contenant ces utilisateurs désinscrits doit être téléversé à l’aide de l’endpoint TON upload et le chemin des données téléversées doit être envoyé à l’endpoint Global Opt Out ici : PUT accounts/:account_id/custom_audiences/global_opt_out.

Envoi des mises à jour d’appartenance Comme indiqué dans la documentation de notre endpoint, lorsque vous transmettez des utilisateurs via l’endpoint POST custom_audience_memberships, vous devez transmettre un customer ID (ID client) pour activer la correspondance basée sur les cookies. Les partenaires qui envoient des données avec un p_id doivent définir user_identifier_type sur TALIST_PARTNER_USER_ID ou TAWEB_PARTNER_USER_ID. Toutes les autres étapes resteront identiques à celles répertoriées dans le Guide d’intégration de l’API Real-Time Audience.

Données utilisateur des Custom Audiences

Ce document décrit le format des données utilisateur des [Custom Audience]/x-ads-api/audiences. Normalisation des données Identifiants d’appareil :

IDFA - en minuscules avec des tirets ; ex. : 4b61639e-47cc-4056-a16a-c8217e029462
AdID - le format d’origine sur l’appareil est requis, non mis en majuscules, avec des tirets ; ex. : 2f5f5391-3e45-4d02-b645-4575a08f86e
Android id - le format d’origine sur l’appareil est requis, non mis en majuscules, sans tirets ni espaces ; ex. : af3802a465767e36

Adresses e‑mail :

en minuscules, supprimer les espaces de début et de fin ; ex. : support@x.com

Noms d’utilisateur X :

sans @, en minuscules, et suppression des espaces de début et de fin ; ex. : jack

ID utilisateur X :

Entier standard ; ex. : 143567

Hachage des données Les données de chaque ligne doivent être hachées à l’aide de SHA256, sans sel. De plus, le hachage final produit doit être en minuscules. Par exemple : 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d et non 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# hachage de l'utilisateur @AdsAPI avec Python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Des exemples de code supplémentaires pour le hachage sont disponibles sur github.com/xdevplatform/ads-platform-tools.

Audiences personnalisées : Web

Information Les partenaires enverront une liste d’ID (p_user_ids) à cibler pour le compte d’un annonceur. Cela se fait via un processus de synchronisation d’ID (ID Sync) qui établit une correspondance entre les p_user_ids et l’ID utilisateur X. Cette correspondance est ensuite utilisée pour produire des listes d’ID utilisateur X pouvant être utilisées pour le ciblage. Ces audiences personnalisées seront mises à disposition sur le @handle spécifique de l’annonceur, indiqué par le libellé lors de la configuration de campagne Custom Audiences Web sur ads.x.com. X fournira le pixel sécurisé qui pourra être intégré dans les balises et sur les sites des partenaires afin de faire correspondre les ID (p_user_ids) aux ID utilisateur X. Une fois le processus de synchronisation d’ID terminé, les fichiers de ciblage seront créés par le partenaire et mis à disposition de X via un endpoint HTTPS. Ces fichiers de ciblage sont régulièrement ingérés par X, puis rendus disponibles dans l’interface X. Pixel sécurisé X Le pixel sécurisé X se présentera comme suit : https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz représente l’ID utilisateur du partenaire p_id - 123 représente l’ID unique du partenaire (fourni par X) Endpoint HTTPS du partenaire & fichier d’utilisateurs pour le ciblage Le partenaire devra fournir à X un endpoint HTTPS et des identifiants (nom d’utilisateur/mot de passe) pouvant être utilisés pour ingérer régulièrement le fichier de ciblage. Un exemple d’endpoint HTTPS se présentera comme suit :

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - Code de format pour l’année (YYYY) %M - Code de format pour le mois (MM) %D - Code de format pour le jour (DD) Les données transmises comprendront les fichiers suivants :

Partner Targeting User File
Targeting Conversion File

Tous les fichiers seront au format TSV, où les différents champs de chaque ligne sont séparés les uns des autres par un caractère de tabulation. Les valeurs de champs valides ne contiendront jamais le caractère de tabulation. Plage d’adresses IP X autorisées : Voici la plage d’adresses IP pouvant être autorisées pour accéder au Partner Endpoint.

199.16.156.0/22
199.59.148.0/22

Partner Targeting User File :

Column Number	Column Name	Column Type	Description
1	partner id	string	Le « partner id » est l’identifiant qu’X fournit au partenaire afin d’identifier chaque partenaire de façon unique.
2	advertiser id	string	L’« advertiser id » est le @handle de l’annonceur.
3	p_user_id	string	Le « p_user_id » est l’identifiant unique utilisé par le partenaire pour identifier l’utilisateur.
3	confidence score	integer	Le « confidence score » est facultatif. Nous recommandons d’utiliser une valeur de confidence score comprise entre 0 et 100. Si le cas d’usage est le reciblage, alors un confidence score de « 100 » correspond à un utilisateur qui a été directement reciblé. Toute valeur de 0 à 99 correspondrait au niveau de confiance pour le profil similaire (look-alike).
4	segment label	string	Le « segment label » est facultatif. Les partenaires peuvent utiliser le « segment label » pour spécifier, par exemple, des catégories de produits. Nous recommandons d’utiliser ce « segment label », car il s’agit du nom lisible pour les Custom Audiences dans l’interface ads.x.com.

Remarques : Chaque fois que nous recevons un nouveau Partner Targeting File, nous nous attendons à ce qu’il s’agisse de la liste complète des utilisateurs que le partenaire nous recommande de cibler, et non d’une liste incrémentale, sauf accord contraire. Nous conviendrons avec chaque partenaire de la fréquence de livraison de ce Partner Targeting File. Si nous ne recevons pas de Partner Targeting File comme prévu, nous utiliserons la version précédente avec un délai d’expiration prédéfini.

Intégration de l’API Audience

Vue d’ensemble

L’Audience API a été lancée dans le cadre de la v4 de l’Ads API et apporte plusieurs améliororations par rapport aux anciens endpoints Audiences. Ce nouveau endpoint s’appuie sur un nouveau backend de traitement des Audiences et fournit plusieurs améliorations en termes de stabilité, de robustesse et de fiabilité. L’objectif de ce guide est de mettre en évidence les différences entre l’Audience API et les anciens processus de téléversement et de gestion d’Audience. La documentation de référence est disponible sur la page de référence de l’Audience API. Remarque : toutes les données utilisateur d’Audience doivent être hachées en SHA-256 avant le téléversement. Davantage de détails, ainsi que les types d’identifiants utilisateur acceptés et la normalisation des données, sont disponibles sur la page user data. Modifications de la fonctionnalité Audience Les changements suivants apportés aux Audiences personnalisées ont été introduits à partir de la v4 et tous les endpoints obsolètes ne seront plus disponibles une fois que la v3 de l’Ads API aura été retirée :

Obsolète : téléversement TON :
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
Obsolète : Real Time Audiences :
- POST custom_audience_memberships
Audience personnalisée :
- Le paramètre list_type sera supprimé de la requête et de la réponse sur tous les endpoints Custom Audience. Ce paramètre était auparavant utilisé pour identifier le type d’identifiant utilisateur de l’Audience (c.-à-d. email, X User ID, etc.). Cependant, les Audiences peuvent désormais accepter plusieurs identifiants utilisateur pour une même Audience, ce qui rend cette valeur non pertinente.
Général :
- La période de rétrospection (lookback window) de l’Audience a été mise à jour pour faire correspondre les utilisateurs actifs au cours des 90 derniers jours (au lieu de 30 jours).
- Le nombre minimum d’utilisateurs correspondants requis pour qu’une Audience soit ciblable a été réduit à 100 utilisateurs (au lieu de 500 utilisateurs).

Prérequis

Accès à l’Ads API
Pour accéder au endpoint Audience, vous devrez être ajouté à une allowlist. Veuillez remplir ce formulaire et accepter le nouvel X Ads Products and Services Agreement si vous aviez initialement accepté une version antérieure au 1er août 2018.

Processus de téléversement d’Audience Le tableau suivant répertorie les principales différences entre les anciens et les nouveaux flux de création d’Audience, avec plus de détails disponibles plus bas :

Étape du processus	Audience API	(Obsolète) téléversement TON
Créer une Audience « coquille »	Peut être créée via le [POST custom_audience endpoint]/x-ads-api/audiences	Peut être créée via le [POST custom_audience endpoint]/x-ads-api/audiences
Ajouter un nouvel utilisateur	Utiliser `operation_type` `Update` avec le Audience endpoint	Utiliser `operation` `ADD` avec le endpoint POST custom_audience_changes
Supprimer un utilisateur	Utiliser `operation_type` `Delete` avec le Audience endpoint	Utiliser `operation` `REMOVE` avec le endpoint POST custom_audience_changes
Exclure des utilisateurs (opt-out)	Utiliser `operation_type` `Delete` avec le Audience endpoint et les `custom_audience_id` correspondants dont l’utilisateur fait partie	Utiliser le Global opt-out endpoint

Remarque : toutes les Audiences mises à jour ou pour lesquelles un opt-out est effectué via le flux de téléversement TON doivent disposer d’une liste correspondante téléversée via le endpoint TON Upload et associée à une Audience à l’aide du endpoint custom_audience_changes. Limitation de débit Le endpoint Audience API a une limite de débit de 1500/1 min par compte. Il n’y a aucune limite quant au nombre d’utilisateurs pouvant être envoyés dans une seule charge utile (payload). Les seules contraintes sur la charge utile sont :

Nombre total d’opérations : 2500 opérations
Taille maximale de la charge utile : 5 000 000 octets

Gestion des utilisateurs d’Audience Pour créer une nouvelle Audience, les étapes suivantes sont requises

Créer une nouvelle Audience personnalisée

Créez une nouvelle Audience personnalisée « vide » à l’aide de l’endpoint [POST custom_audience]/x-ads-api/audiences et récupérez l’id de l’Audience personnalisée correspondante. Cette étape est requise si vous créez une Audience à partir de zéro. Si vous mettez à jour une Audience existante, passez à la section suivante.

Ajouter des utilisateurs à une audience

Utilisez l’endpoint POST accounts/:account_id/custom_audiences/:custom_audience_id/users avec l’id de la Custom Audience et un exemple de payload comme suit : POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Toutes les valeurs doivent être hachées ; les valeurs non hachées sont utilisées dans cet exemple à titre d'illustration
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Pour ajouter un utilisateur à une Audience, utilisez la valeur Update pour le champ operation_type. La nouvelle interface Audience permet d’envoyer plusieurs clés d’utilisateur pour un même utilisateur. Chaque objet dans le tableau d’objets JSON correspond à un seul utilisateur. En utilisant l’exemple de payload ci‑dessus, la requête ajoutera deux utilisateurs à une Audience, l’un avec un email et un handle, et l’autre avec un email et un twitter_id.

Supprimer des utilisateurs d’une audience

De manière similaire au processus décrit pour l’ajout d’utilisateurs, des utilisateurs peuvent être supprimés d’une audience de la manière suivante : POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # Toutes les valeurs doivent être hachées ; les valeurs non hachées sont utilisées dans cet exemple à titre d'illustration
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Le champ operation_type doit être défini sur la valeur Delete et les utilisateurs seront mis en correspondance sur n’importe laquelle des clés qui étaient présentes lors de leur ajout à l’audience. Par exemple, si un utilisateur a été ajouté à une audience à l’aide d’un email et d’un twitter_id, alors ce même utilisateur peut être supprimé en utilisant l’une quelconque de ces clés, c’est‑à‑dire email ou twitter_id, ou les deux. Il est également possible d’ajouter et de supprimer des utilisateurs d’une audience dans la même requête. Le point de terminaison prend en charge plusieurs valeurs de operation_type par requête.

Utilisateurs ayant refusé l’utilisation

Avec l’abandon de l’endpoint global d’opt-out, les partenaires doivent Delete tous les utilisateurs qui ont choisi l’opt-out d’une Audience. Il existe plusieurs façons d’y parvenir :

Suivre quels utilisateurs font partie de quelles Audiences et retirer ces utilisateurs individuellement de chaque Audience.
Retirer l’utilisateur de toutes les Audiences associées à un compte Ads.

Bonnes pratiques générales

Nous recommandons fortement d’appeler cet endpoint avec des lots traités en quasi temps réel afin d’éviter des pics dans les files d’attente, qui prennent plus de temps à être traités et génèrent en général une charge inutile sur notre système. Cela garantit également que les utilisateurs sont disponibles plus rapidement pour le ciblage des campagnes.
Un appel d’API réussi renverra un success_count et un total_count correspondant au nombre d’objets user reçus dans la requête.
Cet endpoint est atomique par nature, c’est-à-dire que soit l’intégralité de la requête réussit, soit, en cas de errors, l’intégralité de la requête échoue. En cas de réponse d’erreur, il est recommandé aux consommateurs de l’API de corriger l’erreur et de réessayer la requête avec l’intégralité du payload.
En cas d’échec, il est recommandé aux partenaires d’utiliser une approche de backoff exponentiel avec des tentatives de nouvelle exécution. Par exemple, réessayez immédiatement après le premier échec, réessayez après 1 minute après le deuxième échec et réessayez après 5 minutes après le troisième échec consécutif, et ainsi de suite.

Référence de l’API

Analyses de mots-clés

GET insights/keywords/search

À partir d’un groupe de mots-clés, récupère le volume de Tweets associé ainsi qu’un ensemble de 30 mots-clés connexes. Le volume de Tweets correspond uniquement aux mots-clés en entrée, et non aux mots-clés connexes. Une plage de temps maximale (end_time - start_time) de 7 jours est autorisée. Veuillez noter que les résultats sont limités à une seule zone géographique (pays). Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	Spécifie la granularité des données renvoyées pour la plage de temps définie par `start_time` et `end_time`. Par exemple, lorsqu’elle est définie sur `HOUR`, un point de données est fourni pour chaque heure entre `start_time` et `end_time`. Type : enum Valeurs possibles : `DAY`, `HOUR`
keywords required	Chaîne de mots-clés séparés par des virgules pour affiner la recherche. Tous les mots-clés sont reliés entre eux par l’opérateur logique OR. Remarque : un maximum de 10 mots-clés (`keywords` et `negative_keywords` combinés) peut être utilisé. Type : string Exemple : `developers`
start_time required	Restreint les données récupérées à celles collectées dans la fenêtre de temps comprise entre `start_time` et `end_time`. Exprimé au format ISO 8601. Type : string Exemple : `2017-07-10T00:00:00Z`
end_time optional	Restreint les données récupérées à celles collectées dans la fenêtre de temps comprise entre `start_time` et `end_time`. Exprimé au format ISO 8601. Remarque : la valeur par défaut est l’heure actuelle. Type : string Exemple : `2017-07-11T00:00:00Z`
location optional	Valeur de ciblage obtenue à partir du point de terminaison GET targeting_criteria/locations pour restreindre les résultats en fonction de l’emplacement de l’utilisateur du compte. Notez qu’à l’heure actuelle, seuls les emplacements au niveau du pays sont pris en charge. Type : string Exemple : `0ce8b9a7b2742f7e`
negative_keywords optional	Chaîne de mots-clés séparés par des virgules à exclure. Tous les mots-clés négatifs sont reliés entre eux par l’opérateur logique OR. Remarque : un maximum de 10 mots-clés (`keywords` et `negative_keywords` combinés) peut être utilisé. Type : string Exemple : `rain`

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

Exemple de réponse*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

Autorisations de l’audience personnalisée

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Récupère les détails de certaines ou de l’ensemble des autorisations associées à l’audience personnalisée spécifiée. URL de la ressource https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Paramètres

Nom	Description
account_id requis	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
tailored_audience_id requis	Une référence à l’audience personnalisée avec laquelle vous interagissez dans la requête. Type : string Exemple : `1nmth`
count optionnel	Indique le nombre d’enregistrements à récupérer par requête distincte. Type : int Valeur par défaut : `200` Min, Max : `1`, `1000`
cursor optionnel	Indique un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : `8x7v00oow`
granted_account_ids optionnel	Limite la réponse aux comptes souhaités en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : `18ce54aymz3`
sort_by optionnel	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type : string Exemple : `created_at-asc`
tailored_audience_permission_ids optionnel	Limite la réponse aux autorisations d’audience personnalisée souhaitées en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : `ri`
with_total_count optionnel	Inclut l’attribut de réponse `total_count`. Remarque : Ce paramètre et `cursor` sont mutuellement exclusifs. Remarque : Les requêtes qui incluent `total_count` seront soumises à des limites de taux plus faibles, actuellement définies à 200 par 15 minutes. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false`

Exemple de requête GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

Crée un nouvel objet d’autorisation permettant de partager l’audience spécifiée avec un compte donné. Remarque : la création ou la modification des autorisations pour une audience personnalisée nécessite que l’audience soit détenue par le compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une audience personnalisée en consultant l’attribut de réponse is_owner dans la réponse renvoyée pour une audience donnée. Remarque : les audiences ne peuvent être partagées qu’entre des comptes publicitaires appartenant à la même entreprise ou si le compte publicitaire qui possède l’audience dispose de la fonctionnalité de compte SHARE_AUDIENCE_OUTSIDE_BUSINESS. URL de la ressource https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
granted_account_id required	Le compte auquel vous souhaitez accorder des autorisations sur l’audience personnalisée. Type : string Exemple : `18ce54aymz3`
permission_level required	Le type d’accès à l’audience personnalisée que `granted_account_id` doit avoir. Type : enum Valeurs possibles : `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	Une référence à l’audience personnalisée que vous utilisez dans la requête. Type : string Exemple : `2906h`

Exemple de requête

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Révoquez l’autorisation de partage de la Tailored Audience spécifiée. Remarque : la création ou la modification d’autorisations pour une Tailored Audience nécessite que l’audience appartienne au compte qui tente de modifier les autorisations. Vous pouvez vérifier la propriété d’une Tailored Audience en consultant l’attribut de réponse is_owner dans la réponse pour une audience donnée. Une fois révoquée, nous garantissons que le compte bénéficiaire (granted_account_id) ne pourra plus cibler l’audience dans de futures campagnes. Les campagnes existantes continueront de s’exécuter avec les audiences partagées ; les campagnes ne s’arrêtent pas et l’audience n’est pas supprimée de la campagne. Il n’est pas possible de dupliquer cette campagne après la révocation de l’autorisation de partage d’audience. URL de la ressource

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
tailored_audience_id required	Une référence à la Tailored Audience utilisée dans la requête. Type: string Example: `1nmth`
tailored_audience_permission_id required	Une référence à l’autorisation de Tailored Audience utilisée dans la requête. Type: string Example: `ri`

Exemple de requête DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

Audiences ciblées

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Récupérer une liste des line items et campagnes actifs, ou de l’ensemble des line items et campagnes qui ciblent un custom_audience_id donné.

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : `18ce54d4x5t`
custom_audience_id required	Une référence à la custom audience que vous utilisez dans la requête. Type: string Exemple : `2906h`
with_active optional	Lorsque `false`, inclut les line items dont le statut est `servable=false`. Type: boolean Valeur par défaut : `true` Valeurs possibles : `true`, `false`
cursor optional	Spécifie un curseur pour obtenir la page suivante de résultats. Consultez la section Pagination pour plus d’informations. Type: string Exemple : `8x7v00oow`

Exemple de requête GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "test-campaign",
          "line_items": [
            {
              "id": "5gzog",
              "name": "test-line-item",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Untitled campaign",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

Utilisateurs d’audiences personnalisées

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

Cet endpoint permet aux partenaires d’ajouter, de mettre à jour et de supprimer des utilisateurs d’un custom_audience_id donné. L’endpoint accepte également plusieurs types d’identifiants utilisateur pour un même utilisateur. Toutes les données fournies dans le champ users de la requête, sauf partner_user_id, doivent être hachées à l’aide de SHA256 et normalisées. Requêtes en lot

La taille maximale actuelle d’un lot est de 2500 pour cet endpoint. La taille du lot est déterminée par le nombre d’opérations (Update/Delete) par requête. Par exemple, plus de 2500 objets d’opération ({"operation_type": "Update/Delete", [..] }) dans un même tableau entraînent une erreur.
La taille maximale du corps POST de la requête que cet endpoint peut accepter est de 5,000,000 octets.
Les limites de taux pour cet endpoint sont de 1500 par fenêtre de 1 minute.
Tous les paramètres sont envoyés dans le corps de la requête et un Content-Type de application/json est requis.
Les requêtes en lot échouent ou réussissent toutes ensemble en tant que groupe et toutes les réponses de l’API, qu’il s’agisse d’erreurs ou de succès, préservent l’ordre des éléments de la requête initiale.

Réponses en lot La réponse renvoyée par l’API Ads contient deux champs, un success_count et un total_count. Ces valeurs doivent toujours être égales, et elles correspondent au nombre d’enregistrements dans la requête qui ont été traités par le backend. Une situation où le nombre d’enregistrements envoyés dans le corps de la requête n’est pas égal à success_count et total_count doit être traitée comme une erreur nécessitant une nouvelle tentative. Erreurs en lot

Les erreurs au niveau de la requête (par ex. taille maximale du lot dépassée) sont indiquées dans la réponse sous l’objet errors.
Les erreurs au niveau des éléments (par ex. paramètres obligatoires manquants) sont indiquées dans la réponse sous l’objet operation_errors.
L’index de l’erreur dans operation_errors correspond à l’index de l’élément d’entrée, avec le message d’erreur correspondant.

URL de ressource

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

Paramètres

Name	Description
operation_type required	Le type d’opération effectué pour chaque groupe de `users`. Type : enum Valeurs possibles : `Update`, `Delete`
params required	Un objet JSON contenant le tableau `users`, ainsi que les horodatages `effective_at` et `expires_at`. Type : JSON
users required	Un tableau d’objets JSON contenant tous les paramètres pour un utilisateur donné. Type : JSON
effective_at optional	L’heure UTC à laquelle l’association ou les associations à l’audience personnalisée doivent prendre effet. Exprimée au format ISO 8601. Par défaut, la date et l’heure actuelles. Type : string Exemple : `2017-07-05T07:00:00Z`
expires_at optional	L’heure UTC à laquelle l’association ou les associations à l’audience personnalisée doivent expirer. L’heure spécifiée doit être postérieure à la valeur de `effective_at`. Exprimée au format ISO 8601. Par défaut, 13 mois après l’horodatage de la requête. Type : string Exemple : `2017-07-05T07:00:00Z`

Compte tenu de l’approche multi-clés pour l’objet users, chaque élément de cet objet est documenté ci‑dessous :

Name	Description
email optional	Adresse(s) e‑mail de l’utilisateur. Type : Array[String]
device_id optional	IDFA/AdID/Android ID Type : Array[String]
handle optional	Le ou les @handles appartenant à l’utilisateur Type : Array[String]
twitter_id optional	L’ID X appartenant à l’utilisateur Type : Array[String]
phone_number optional	Numéro(s) de téléphone de l’utilisateur Type : Array[String]
partner_user_id optional	L’ID de l’utilisateur dans le système du partenaire. Type : Array[String]

Exemple de requête

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

Autorisations d’audience personnalisée

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Récupère les détails de certaines ou de toutes les autorisations associées à l’audience personnalisée spécifiée. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
custom_audience_id required	Référence à l’audience personnalisée que vous utilisez dans la requête. Type : string Exemple : `1nmth`
count optional	Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte. Type : int Valeur par défaut : `200` Min, max : `1`, `1000`
cursor optional	Spécifie un curseur pour obtenir la page de résultats suivante. Voir Pagination pour plus d’informations. Type : string Exemple : `8x7v00oow`
granted_account_ids optional	Limite la réponse aux seuls comptes souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : `18ce54aymz3`
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations. Type : string Exemple : `created_at-asc`
custom_audience_permission_ids optional	Limite la réponse aux seules autorisations d’audience personnalisée souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Type : string Exemple : `ri`
with_total_count optional	Inclure l’attribut de réponse `total_count`. Remarque : ce paramètre et `cursor` sont exclusifs. Remarque : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false`

Exemple de requête GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Créer un nouvel objet d’autorisation permettant de partager l’audience spécifiée avec un compte donné. Remarque : la création ou la modification des autorisations pour une audience personnalisée nécessite que l’audience soit détenue par le compte qui tente de modifier ces autorisations. Vous pouvez vérifier la propriété d’une audience personnalisée en consultant l’attribut de réponse is_owner dans la réponse pour une audience donnée. Remarque : les audiences ne peuvent être partagées qu’entre des comptes publicitaires appartenant à la même entreprise ou si le compte publicitaire qui détient l’audience dispose de la fonctionnalité de compte SHARE_AUDIENCE_OUTSIDE_BUSINESS. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	Identifiant du compte exploité. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
granted_account_id required	Le compte auquel vous souhaitez accorder des autorisations pour l’audience personnalisée. Type : string Exemple : `18ce54aymz3`
permission_level required	Type d’accès à l’audience personnalisée que `granted_account_id` doit avoir. Type : enum Valeurs possibles : `READ_ONLY`, `READ_WRITE`
custom_audience_id required	Référence à l’audience personnalisée utilisée dans la requête. Type : string Exemple : `2906h`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Révoque l’autorisation de partage de la Custom Audience spécifiée. Remarque : la création ou la modification des autorisations pour une Custom Audience nécessite que l’audience appartienne au compte qui tente de modifier ces autorisations. Vous pouvez vérifier la propriété d’une Custom Audience en consultant l’attribut de réponse is_owner dans la réponse pour une audience donnée. Une fois révoquée, nous garantissons que le compte à qui l’accès a été accordé (granted_account_id) ne pourra plus cibler l’audience dans de futures campagnes. Les campagnes existantes continueront à s’exécuter avec les audiences partagées ; les campagnes ne s’arrêtent pas et l’audience n’est pas supprimée de la campagne. Il n’est pas possible de copier cette campagne après la révocation de l’autorisation de partage d’audience. URL de la ressource

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
custom_audience_id required	Une référence à la Custom Audience sur laquelle porte la requête. Type: string Example: `1nmth`
custom_audience_permission_id required	Une référence à l’autorisation de Custom Audience sur laquelle porte la requête. Type: string Example: `ri`

Exemple de requête DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

Audiences personnalisées

GET accounts/:account_id/custom_audiences

Récupérer les détails de certaines ou de toutes les audiences personnalisées associées au compte actuel. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple: `18ce54d4x5t`
count optional	Indique le nombre d’enregistrements à récupérer par requête distincte. Type: int Valeur par défaut: `200` Min, max: `1`, `1000`
cursor optional	Indique un curseur pour obtenir la page suivante de résultats. Consultez Pagination pour plus d’informations. Type: string Exemple: `8x7v00oow`
permission_scope optional	Permet de filtrer la réponse sur les listes que vous possédez ou celles qui ont été partagées avec vous. Par défaut, sans spécifier ce paramètre, vous ne verrez que les audiences que vous possédez. Type: enum Valeur par défaut: `OWNER` Valeurs possibles: `OWNER`, `SHARED`
q optional	Requête optionnelle permettant de restreindre la ressource par `name`. Note : effectue une correspondance de préfixe insensible à la casse. Type: string Longueur min, max: `1`, `255`
sort_by optional	Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Consultez Sorting pour plus d’informations. Type: string Exemple: `created_at-asc`
custom_audience_ids optional	Restreint la réponse aux audiences personnalisées souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 ID peuvent être fournis. Type: string Exemple: `1nmth`
with_deleted optional	Inclut les résultats supprimés dans votre requête. Type: boolean Valeur par défaut: `false` Valeurs possibles: `true`, `false`
with_total_count optional	Inclut l’attribut de réponse `total_count`. Note : ce paramètre et `cursor` sont exclusifs. Note : les requêtes qui incluent `total_count` auront des limites de taux plus faibles, actuellement fixées à 200 par tranche de 15 minutes. Type: boolean Valeur par défaut: `false` Valeurs possibles: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

GET accounts/:account_id/custom_audiences/:custom_audience_id

Récupérer des Custom Audiences spécifiques associées au compte actuel. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Paramètres

Nom	Description
account_id required	Identifiant du compte concerné. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
custom_audience_id required	Référence à la Custom Audience avec laquelle vous opérez dans la requête. Type : string Exemple : `2906h`
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false`

Exemple de requête GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Exemple de réponse

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

POST accounts/:account_id/custom_audiences

Crée une nouvelle Custom Audience factice associée au compte actuel. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : `18ce54d4x5t`
name required	Le nom d’affichage de cette audience. Une valeur de nom unique doit être utilisée. Le non‑respect de cette contrainte entraînera une erreur. Type: string Exemple : `ads api users`
description optional	Une description de cette audience. Type: string Exemple : `Collection of all users of the Ads API`

Exemple de requête POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers Exemple de réponse

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

PUT accounts/:account_id/custom_audiences/:custom_audience_id

Met à jour la Custom Audience spécifique associée au compte actuel. Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	Identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
custom_audience_id required	Référence à la Custom Audience que vous utilisez dans la requête. Type : string Exemple : `2906h`
name optional	Nom d’affichage de cette audience. Une valeur de nom unique doit être utilisée. Dans le cas contraire, une erreur sera renvoyée. Type : string Exemple : `ads api users`
description optional	Description de cette audience. Type : string Exemple : `Collection of all users of the Ads API`

Example Request PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

POST batch/accounts/:account_id/custom_audiences

Permet la création par lot de Custom Audiences. Consultez la page Présentation des Custom Audiences pour plus d’informations sur les audiences. Remarque : Cet endpoint de lot est actuellement en bêta fermée et disponible pour un nombre limité d’annonceurs. Pendant cette période de bêta, seules les Flexible Audiences basées sur des audiences mobiles personnalisées peuvent être créées. Requêtes par lot

La taille maximale actuelle d’un lot est de 10.
Tous les paramètres sont envoyés dans le corps de la requête et un Content-Type de application/json est requis.
Les requêtes par lot échouent ou réussissent ensemble en tant que groupe et toutes les réponses de l’API, en cas d’erreur comme de succès, préservent l’ordre des éléments de la requête initiale.

Réponses par lot Les réponses de l’API par lot renvoient une collection ordonnée d’éléments. Pour le reste, elles sont identiques en termes de structure à leurs endpoints correspondants pour un seul élément. Erreurs de lot

Les erreurs au niveau de la requête (par ex. taille maximale de lot dépassée) apparaissent dans la réponse sous l’objet errors.
Les erreurs au niveau des éléments (par ex. paramètre obligatoire manquant) apparaissent dans la réponse sous l’objet operation_errors.

Flexible Audiences

Les Flexible Audiences sont immuables une fois créées.
Les Custom Audiences sont transmises sous forme d’arborescence avec des combinaisons de logique booléenne pour créer des Flexible Audiences.
Un maximum de 10 nœuds feuille de Custom Audiences peut être utilisé pour créer une Flexible Audience.

URL de ressource https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
audience_type required	Le type d’audience à créer. Type: enum Valeurs possibles : `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments required	Un tableau contenant des objets qui définissent le sous-ensemble des membres d’une Custom Audience que vous souhaitez cibler. Chaque objet doit contenir un `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate` et, dans certains cas, des `child_segments` supplémentaires. Type: array
name required	Le nom d’affichage de l’audience. Une valeur de nom unique doit être utilisée. Le non-respect de cette règle entraînera une erreur. Type: string Example: `my_flexible_audience_name`
operation_type required	Le type d’opération appliqué à chaque élément. Type: enum Valeurs possibles : `Create`, `Update`, `Delete`
boolean_operator sometimes required	La relation logique entre les segments enfants dans leur objet parent (contenant). Obligatoire si `child_segments` n’est pas vide pour l’objet parent. Type: enum Valeurs possibles : `AND`, `OR`
lookback_window sometimes required	Une valeur entière indiquant l’intervalle de jours pendant lequel l’utilisateur a effectué l’action spécifique et a été qualifié pour la Custom Audience donnée. Type: int Valeurs possibles : `1`, `7`, `14`, `30`
segments sometimes required	Un objet contenant un `boolean_operator` et des `child_segments` qui définissent le sous-ensemble des membres d’une Custom Audience que vous souhaitez cibler. Type: object
custom_audience_id sometimes required	L’id de la Custom Audience à utiliser comme segment enfant. Type: string Example: `tyfo`
frequency optional	Une valeur entière indiquant, dans la fenêtre de lookback, la fréquence à laquelle l’utilisateur a effectué l’action spécifique et a été qualifié pour la Custom Audience donnée. Type: int Valeur par défaut : `1`
frequency_comparator optional	Le comparateur appliqué à la `frequency` passée dans la requête. Remarque : Dans les valeurs ci-dessous, `GTE` signifie greater than or equal (supérieur ou égal), `LT` signifie less than (inférieur), etc. Type: string Valeurs possibles : `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Valeur par défaut : `NUM_GTE`
negate optional	Négation du segment, qui est ainsi exclu de la combinaison. Type: boolean Valeur par défaut : `true` Valeurs possibles : `true`, `false`

Example Request POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

Exemple de réponse

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Supprime l’Audience personnalisée spécifiée appartenant au compte actuel. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Exemple : `18ce54d4x5t`
custom_audience_id required	Une référence à l’Audience personnalisée que vous utilisez dans la requête. Type: string Exemple : `2906h`

Exemple de requête DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Exemple de réponse

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

Listes d’exclusion de contact

GET accounts/:account_id/do_not_reach_lists

Récupérer les détails d’une ou de toutes les listes Do Not Reach associées au compte actuel. Remarque : un account_id ne peut avoir qu’au maximum une liste Do Not Reach URL de la ressource https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Paramètres

Name	Description
account_id required	Identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
with_deleted optional	Inclure les résultats supprimés dans votre requête. Type : boolean Valeur par défaut : `false` Valeurs possibles : `true`, `false`

Exemple de requête GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "Do Not Reach List",
          "description": "test DNRL",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/do_not_reach_lists

Créer une nouvelle Liste Ne Pas Contacter associée au compte actuel. Remarque : un account_id ne peut avoir au maximum qu’une seule Liste Ne Pas Contacter URL de ressource https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Paramètres

Nom	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : `18ce54d4x5t`
description optional	Une description pour cette audience. Type : string Exemple : `A list of users to exclude`

Exemple de requête POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude Exemple de réponse

    {
      "request": {
        "params": {
          "description": "A list of users to exclude",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": "A list of users to exclude",
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

Cet endpoint permet d’ajouter, de mettre à jour et de supprimer des utilisateurs dans un do_not_reach_list_id donné. Cet endpoint n’accepte que les e-mails comme type d’identifiant utilisateur valide. Toutes les données fournies dans le champ emails de la requête doivent être hachées en utilisant SHA256 et normalisées. Remarques

Un account_id ne peut être associé au maximum qu’à une seule Do Not Reach List
Les utilisateurs ajoutés à cette liste doivent avoir un horodatage expires_at défini à moins de 13 mois à compter de l’horodatage actuel
L’API Do Not Reach List n’accepte pas d’horodatage effective_at et utilise par défaut l’horodatage actuel
La Do Not Reach List ne supprime pas les utilisateurs d’une ou de toutes les audiences personnalisées du compte, mais agit comme un ciblage d’exclusion pour toutes les campagnes diffusées pour le compte

Requêtes par lots

La taille maximale actuelle d’un lot est de 2500 pour cet endpoint. La taille du lot est déterminée par le nombre d’opérations (Update/Delete) par requête. Par exemple, plus de 2500 objets d’opération ({"operation_type": "Update/Delete", [..] }) dans un seul tableau entraînent une erreur.
La taille maximale du corps de requête POST que cet endpoint peut accepter est de 5,000,000 octets.
Les limites de taux pour cet endpoint sont de 1500 par fenêtre de 1 minute.
Tous les paramètres sont envoyés dans le corps de la requête et un Content-Type de application/json est requis.
Les requêtes par lots échouent ou réussissent ensemble en tant que groupe et toutes les réponses de l’API, pour les erreurs comme pour les succès, préservent l’ordre des éléments de la requête initiale.

Réponses par lots La réponse renvoyée par l’Ads API contient deux champs, un success_count et un total_count. Ces valeurs doivent toujours être égales, et elles correspondent au nombre d’enregistrements dans la requête qui ont été traités par le backend. Une situation où le nombre d’enregistrements envoyés dans le corps de la requête n’est pas égal à success_count et total_count doit être traitée comme une condition d’erreur nécessitant une nouvelle tentative. Erreurs par lots

Les erreurs au niveau de la requête (par ex. taille de lot maximale dépassée) sont indiquées dans la réponse dans l’objet errors.
Les erreurs au niveau des éléments (par ex. paramètres obligatoires manquants) sont indiquées dans la réponse dans l’objet operation_errors.
L’index de l’erreur dans operation_errors fait référence à l’index de l’élément en entrée, avec le message d’erreur correspondant

URL de la ressource https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users Paramètres

Name	Description
account_id required	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	Une référence à la Do Not Reach List avec laquelle vous opérez dans la requête Type: string Example: `2906h`
operation_type required	Le type d’opération par groupe `users` en cours d’exécution. Type: enum Possible values: `Update`, `Delete`
params required	Un objet JSON contenant le tableau `emails` et l’horodatage `expires_at`. Type: JSON
users required	Un tableau d’objets JSON contenant tous les paramètres pour un utilisateur individuel. Type: JSON
expires_at optional	L’heure UTC à laquelle l’association ou les associations d’utilisateurs doivent expirer. L’heure spécifiée doit être postérieure à la valeur de l’horodatage actuel. Exprimée au format ISO 8601. Par défaut : 13 mois à partir de l’horodatage actuel. Type: string Example: `2017-07-05T07:00:00Z`

Compte tenu de l’approche multi-clés pour l’objet users, chaque élément de cet objet est documenté ci-dessous :

Name	Description
email facultatif	Adresse(s) e-mail de l’utilisateur. Type : Array[String]
phone_number facultatif	Numéro(s) de téléphone de l’utilisateur. Type : Array[String]

Exemple de requête

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

Exemple de réponse

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Supprimer la Do Not Reach List spécifiée appartenant au compte en cours. URL de la ressource https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id Paramètres Aucun Exemple de requête DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp Exemple de réponse

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }

API X Ads

Notions de base

Ressources

Mesure

​Audiences personnalisées

​Vue d’ensemble

​FAQ sur les audiences

​CRM

​Exigences de correspondance des ID de partenaire

​Exigences de correspondance standard

​Nommage et opérations des fichiers de liste de segments personnalisés

​Création et mise à jour des audiences

​Instructions de hachage

​Normalisation des e-mails

​Normalisation des identifiants d’appareil

​Normalisation des ID utilisateur X

​Intégration de synchronisation d’ID

​URL du pixel

​Paramètres du pixel

​Pixel de synchronisation d’ID :

​Données utilisateur des Custom Audiences

​Audiences personnalisées : Web

​Intégration de l’API Audience

​Vue d’ensemble

​Créer une nouvelle Audience personnalisée

​Ajouter des utilisateurs à une audience

​Supprimer des utilisateurs d’une audience

​Utilisateurs ayant refusé l’utilisation

​Référence de l’API

​Analyses de mots-clés

​GET insights/keywords/search

​Autorisations de l’audience personnalisée

​GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

​Audiences ciblées

​GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

​Utilisateurs d’audiences personnalisées

​POST accounts/:account_id/custom_audiences/:custom_audience_id/users

​URL de ressource

​Paramètres

​Exemple de requête

​Exemple de réponse

​Autorisations d’audience personnalisée

​GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

​Audiences personnalisées

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​Listes d’exclusion de contact

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

​POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

Audiences personnalisées

Vue d’ensemble

FAQ sur les audiences

CRM

Exigences de correspondance des ID de partenaire

Exigences de correspondance standard

Nommage et opérations des fichiers de liste de segments personnalisés

Création et mise à jour des audiences

Instructions de hachage

Normalisation des e-mails

Normalisation des identifiants d’appareil

Normalisation des ID utilisateur X

Intégration de synchronisation d’ID

URL du pixel

Paramètres du pixel

Pixel de synchronisation d’ID :

Données utilisateur des Custom Audiences

Audiences personnalisées : Web

Intégration de l’API Audience

Vue d’ensemble

Créer une nouvelle Audience personnalisée

Ajouter des utilisateurs à une audience

Supprimer des utilisateurs d’une audience

Utilisateurs ayant refusé l’utilisation

Référence de l’API

Analyses de mots-clés

GET insights/keywords/search

Autorisations de l’audience personnalisée

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Audiences ciblées

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

Utilisateurs d’audiences personnalisées

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

URL de ressource

Paramètres

Exemple de requête

Exemple de réponse

Autorisations d’audience personnalisée

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Audiences personnalisées

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

Listes d’exclusion de contact

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id