API d'importation d'audience personnalisée

Notre plateforme de gestion de données offre la possibilité à Rokt de recevoir des données d'audience personnalisées à la fréquence que vous préférez. Si vous travaillez avec Rokt en tant qu'annonceur, ces listes peuvent être utilisées dans vos campagnes pour cibler ou exclure certains clients de voir vos offres. Si vous travaillez avec Rokt en tant que partenaire, ces listes peuvent être utilisées pour déterminer quels clients voient l'expérience Rokt sur votre site.

Une méthode courante pour livrer des données d'audience personnalisées à Rokt est l'utilisation d'une API.

Nous recommandons de regrouper vos requêtes avant de les envoyer à Rokt. Vous pouvez le faire plusieurs fois par jour (ou à la fréquence que vous préférez).

Endpoint

URL de l'endpoint	https://data.rokt.com/v3/import/suppression

L'API accepte une charge utile (payload) au format JSON. Vous devez définir l'en-tête Content-Type sur application/json.

Authentification

Remarque : Actuellement en version bêta publique

Contactez votre gestionnaire de compte Rokt pour créer une paire de clés publique et secrète pour les comptes pour lesquels vous souhaitez soumettre des événements de conversion. Les clés que vous recevrez seront :

Nom	Valeur
Clé publique Rokt	rpub-*****-*****
Clé secrète Rokt	rsec-*****-*****

Cela doit être utilisé comme nom d'utilisateur et mot de passe en utilisant Authentification HTTP de base (Basic HTTP Auth) - qui est la chaîne "Basic " + chaîne encodée en base64 de rpub-*:rsec-*.

Corps de la requête

Exactement une des clés suivantes doit être présente dans le corps de la requête.

Si vous utilisez un email haché, assurez-vous d'abord de supprimer tous les espaces et de mettre l'adresse email en minuscules avant de la hacher.

Paramètre	Description
email	Une seule adresse email
emails	Un tableau d'adresses email
sha256	Un email haché en SHA-256
sha256s	Un tableau d'emails hachés en SHA-256

Les paramètres supplémentaires incluent :

Paramètre	Type	Description	Exemple
accountId	Requis	ID de compte Rokt tel que visible dans OnePlatform.	123456789
action	Requis	Utilisez include si vous souhaitez ajouter quelqu'un à la liste spécifiée qui pourrait ensuite être utilisée pour le ciblage ou la suppression. Utilisez exclude si vous souhaitez retirer quelqu'un de la liste spécifiée.	include exclude
list	Optionnel	Le nom de la liste d'audience personnalisée à utiliser. Si aucune valeur de liste n'est fournie, les adresses email seront importées dans la liste AdvertiserDatabase par défaut.	US_Customers

Limites

Type	Limite
Taille de la requête	100,000 emails par requête.
Limite de taux	4 par seconde.
Limite de concurrence	4

remarque

Les limites ci-dessus sont recommandées pour cette API. Des montants plus importants peuvent réussir, mais ne sont pas recommandés.

Gestion des réponses

Code de statut HTTP	Corps	Description
201	Created	Le(s) email(s) ont été ajoutés ou supprimés avec succès de la liste d'audience personnalisée.
400	Bad Request	Vous recevez un 400 Bad Request s'il manque des champs requis, ou si votre requête est envoyée dans un mauvais format.

Exemples de ligne de commande

Sur un système Linux ou Mac OS X avec la commande curl installée, la commande suivante effectue une importation des adresses email alice@example.com et bob@example.com, en supposant que la variable d'environnement API_KEY est définie sur votre clé API :

cURL

curl -X POST https://data.rokt.com/v3/import/suppression \
    --user "rpub-aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:rsec-aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
    --header "Content-Type: application/json" \
    --data '{"accountId": "REPLACE_ME", "emails":["alice@example.com","bob@example.com"],"action":"include"}'

La commande suivante importerait le hachage SHA256 unique "1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206" dans une liste d'audience personnalisée appelée US_Customers. Cette chaîne est le hachage SHA256 de hello@example.com (puisque nous nous attendons à ce que les hachages soient des adresses email en minuscules, c'est le hachage que nous rechercherions pour déterminer si l'adresse email HELLO@EXAMPLE.COM est dans la liste d'audience personnalisée) :

cURL

curl -X POST https://data.rokt.com/v3/import/suppression \
    --user "rpub-aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:rsec-aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
    --header "Content-Type: application/json" \
    --data '{"accountId": "REPLACE_ME", "list":"US_Customers","sha256":"1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206","action":"exclude"}'

Authentification (Héritage)

L'API attend un en-tête d'autorisation dans la requête. Cela garantit que vous disposez des autorisations nécessaires pour envoyer des données à votre compte sur la plateforme Rokt. La valeur de l'en-tête d'autorisation doit être la clé API unique de votre compte. Contactez votre gestionnaire de compte pour obtenir cette valeur si vous utilisez encore l'API héritée.

remarque

Uniquement pour les utilisateurs existants et les utilisateurs intégrant des plateformes de données clients spécifiques (CDPs) (à savoir Hightouch et mParticle). Les nouveaux utilisateurs de l'API d'audience personnalisée et toutes les autres intégrations doivent utiliser le dernier point de terminaison pour une expérience d'authentification simplifiée.

Point de terminaison (Héritage)

URL du point de terminaison	https://data.rokt.com/api/1.0/import/suppression

L'API accepte une charge utile JSON. Vous devez définir l'en-tête Content-Type sur application/json. Le corps de la requête, les limites de l'API et la gestion des réponses sont exactement les mêmes que pour l'API POST /v3/import/suppression.

Exemples de ligne de commande (Legacy)

Sur un système Linux ou Mac OS X avec la commande curl installée, la commande suivante effectue une importation des adresses email alice@example.com et bob@example.com, en supposant que la variable d'environnement API_KEY est définie sur votre clé API :

cURL

curl -X POST https://data.rokt.com/api/1.0/import/suppression \
    --header "Authorization: $API_KEY" \
    --header "Content-Type: application/json" \
    --data '{"emails":["alice@example.com","bob@example.com"],"action":"include"}'

La commande suivante importerait le seul hash SHA256 "1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206" dans une liste d'audience personnalisée appelée US_Customers. Cette chaîne est le hash SHA256 de hello@example.com (puisque nous nous attendons à ce que les hashes soient des adresses email en minuscules, c'est le hash que nous rechercherions pour déterminer si l'adresse email HELLO@EXAMPLE.COM est dans la liste d'audience personnalisée) :

cURL

curl -X POST https://data.rokt.com/api/1.0/import/suppression \
    --header "Authorization: $API_KEY" \
    --header "Content-Type: application/json" \
    --data '{"list":"US_Customers","sha256":"1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206","action":"exclude"}'

Test

Notez que les exemples ci-dessus pointent vers notre système de production en direct. Ainsi, si vous testez avec des adresses e-mail comme alice@example.com, alors, en plus de vos vrais clients, nous considérerions alice@example.com comme un membre de votre liste d'audience personnalisée dans Rokt. Si vous utilisez cette liste pour un ciblage d'exclusion, par exemple, nous ne montrerions pas le widget Rokt à quiconque a saisi alice@example.com comme adresse e-mail.