Guide d'Intégration de l'API Audience

L'API Audience de Rokt permet aux annonceurs et partenaires technologiques de transmettre leurs segments d'audience directement à Rokt pour les utiliser dans le ciblage et la suppression des campagnes. En synchronisant vos audiences, vous pouvez vous assurer que vos campagnes atteignent les bons utilisateurs, éviter de diffuser des publicités à ceux qui ne devraient pas les voir, et réduire les dépenses inutiles — ce qui améliore les performances globales des campagnes.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Identifiants API – Contactez votre gestionnaire de compte Rokt pour demander une paire de clé et secret API. Ces identifiants sont utilisés pour l'authentification de base avec toutes les requêtes API.

---

Authentification

L'API Audience de Rokt peut être authentifiée avec une authentification de base de deux manières :

En utilisant les paramètres d'authentification de votre client HTTP

Si votre client HTTP prend en charge l'authentification de base, utilisez votre clé API pour "username" et votre secret pour "password".

En définissant manuellement l'en-tête Authorization

Si votre client HTTP ne gère pas automatiquement l'authentification, construisez vous-même l'en-tête :

1. Concaténez votre clé et votre secret en utilisant un deux-points (:) pour les séparer :

   example-api-key:example-api-secret

2. Encodez le résultat en Base64 avec UTF-8 :

   ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

3. Préfixez la chaîne encodée avec la méthode d'autorisation, en incluant un espace :

   Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

4. Définissez la chaîne résultante comme l'en-tête Authorization dans vos requêtes HTTP :

   Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

En-têtes Requis

En-tête	Valeur	Description
Content-Type	application/json	Format du corps de la requête
Charset	utf-8	Encodage des caractères
Authorization	Basic base64(api-key:api-secret)	Identifiants d'authentification

---

Référence de l'API

Point de terminaison

POST https://inbound.mparticle.com/s2s/v1/UserProfile

Structure du Corps de la Requête

Le corps de la requête est un tableau d'objets, où chaque objet représente un utilisateur unique et contient les champs nécessaires pour l'identifier dans identities et device_updates, ajouter des attributs à son profil dans user_attributes, et l'ajouter ou le retirer d'une ou plusieurs audiences à l'aide de l'objet external_audience_membership_updates.

Pour inclure plusieurs utilisateurs dans une seule charge utile, ajoutez des objets supplémentaires au tableau. Le request_type pour chaque objet doit toujours être défini sur "user_profile_modify".

Chaque charge utile peut inclure jusqu'à 100 utilisateurs.

[
  {
    "request_type": "user_profile_modify",
    "environment": "production",
    "data": {
      "source_request_id": "unique-request-id-here",
      "identities": {
        "customerid": "cust_123456",
        "email": "email@example.com",
        "other": "SHA256-email"
      },
      "device_updates": [
        {
          "device_info": {
            "ios_advertising_id": "00000000-0000-0000-0000-000000000000"
          }
        }
      ],
      "user_attributes": {
        "workspace": [
          {
            "attribute_name": "some_attr_1",
            "attribute_value": "some_val_1"
          },
          {
            "attribute_name": "some_attr_2",
            "attribute_value": "some_val_2"
          }
        ]
      },
      "external_audience_membership_updates": [
        {
          "external_audience_id": "audience_name_1",
          "action": "add",
          "change_timestamp_ms": 1713895200000
        },
        {
          "external_audience_id": "audience_name_2",
          "action": "remove",
          "change_timestamp_ms": 1713895200000
        }
      ]
    }
  }
]

L'API Audience prend en charge jusqu'à 100 utilisateurs par requête.

[
  { "request_type": "user_profile_modify", ... },
  { "request_type": "user_profile_modify", ... },
  { "request_type": "user_profile_modify", ... }
]

---

Field Reference

Champs généraux du corps de la requête

Ces champs sont définis au niveau racine de chaque objet utilisateur.

{
  "request_type": "user_profile_modify",
  "environment": "production",
  "data": {
    "source_request_id": "unique-request-id-here"
  }
}

Champ	Type	Obligatoire	Description
request_type	string	Oui	Doit être défini sur "user_profile_modify".
environment	string	Oui	Doit être défini sur "production".
source_request_id	string	Non	Une valeur pour identifier de manière unique cette requête. Toute chaîne valide est acceptée.

Identités utilisateur

Les identités utilisateur sont définies dans l'objet data.identities. Au moins un identifiant est requis pour que Rokt associe la requête à un utilisateur.

"identities": {
  "email": "email@example.com",
  "other": "SHA256-hashed-email",
  "customerid": "cust_123456"
}

Champ	Type	Obligatoire	Description
email	string	Conditionnellement requis	Adresse email en texte brut. Doit être en minuscules et sans espaces. Requis si l'email haché n'est pas fourni.
other	string	Conditionnellement requis	Email haché SHA-256. Assurez-vous qu'il est en minuscules et sans espaces avant le hachage. Requis si l'email en texte brut n'est pas fourni.
customerid	string	Non	ID client ou utilisateur interne.

Informations sur l'appareil

Les identifiants d'appareil sont envoyés sous forme d'objets dans le tableau data.device_updates[] et améliorent les taux de correspondance, en particulier pour les utilisateurs mobiles.

"device_updates": [
  {
    "device_info": {
      "ios_advertising_id": "00000000-0000-0000-0000-000000000000"
    }
  }
]

Champ	Type	Obligatoire	Description
ios_advertising_id	string	Non	Identifiant publicitaire de l'appareil Apple iOS (IDFA).
android_advertising_id	string	Non	Identifiant publicitaire Google Android (GAID).
ios_idfv	string	Non	Identifiant de l'appareil Apple iOS (IDFV).
android_uuid	string	Non	Identifiant Android.

Attributs utilisateur

Chaque attribut est envoyé sous forme d'objet dans le tableau data.user_attributes.workspace[]. Définissez attribute_name sur l'attribut que vous souhaitez envoyer et attribute_value sur la valeur correspondante.

"user_attributes": {
  "workspace": [
    {
      "attribute_name": "firstname",
      "attribute_value": "Jane"
    },
    {
      "attribute_name": "lastname",
      "attribute_value": "Smith"
    }
  ]
}

Rokt recommande d'envoyer autant que possible des attributs utilisateur suivants pour améliorer l'attribution, le reporting et l'optimisation.

Attribut	Type	Obligatoire	Description
firstname	string	Non	Prénom du client.
firstnamesha256	string	Non	Hachage SHA-256 du prénom. Avant le hachage, mettez en minuscules et supprimez tous les espaces de fin.
lastname	string	Non	Nom de famille du client.
lastnamesha256	string	Non	Hachage SHA-256 du nom de famille. Avant le hachage, mettez en minuscules et supprimez tous les espaces de fin.
mobile	string	Non	Les numéros de téléphone peuvent être formatés soit comme 1112345678 soit comme +1 (222) 345-6789.
mobilesha256	string	Non	Hachage SHA-256 du numéro de mobile. Le numéro de mobile doit être formaté comme 5551234567 (sans tirets ni espaces) avant le hachage.
age	string	Non	Âge du client.
dob	string	Non	Date de naissance. Formatée comme yyyymmdd.
gender	string	Non	Genre du client. Par exemple, M, Male, F, ou Female.
city	string	Non	Ville du client.
state	string	Non	État du client.
zip	string	Non	Code postal du client.
title	string	Non	Titre du client. Par exemple, Mr, Mrs, Ms.

Normalisation des données pour le hachage

Avant de hacher une valeur avec SHA-256 :

• Mettre en minuscules tout le texte
• Supprimer les espaces blancs en début et fin
• Normaliser les numéros de téléphone au format 5551234567 (supprimer les tirets, espaces, parenthèses et indicatif pays)

Mises à jour de l'appartenance à l'audience

Chaque mise à jour d'audience est envoyée sous forme d'objet dans le tableau data.external_audience_membership_updates[]. Ajoutez un objet par audience.

"external_audience_membership_updates": [
  {
    "external_audience_id": "premium_users",
    "action": "add",
    "change_timestamp_ms": 1713895200000
  },
  {
    "external_audience_id": "retargeting_list",
    "action": "remove",
    "change_timestamp_ms": 1713895200000
  }
]

Champ	Type	Requis	Description
external_audience_id	string	Oui	Nom de l'audience.
action	string	Oui	Valeurs acceptées : "add" ou "remove". Utilisez "add" pour inclure l'utilisateur dans l'audience, ou "remove" pour l'exclure.
change_timestamp_ms	number	Non	Horodatage Unix du changement d'appartenance à l'audience (en millisecondes).

Regroupement des mises à jour d'audience

Dans la mesure du possible, regroupez toutes les mises à jour d'audience pour un seul utilisateur en une seule requête. Cela améliore les performances de traitement interne et réduit les frais généraux. Ajoutez un objet par audience au tableau external_audience_membership_updates.

---

Limites

• Chaque compte annonceur est limité à 1 000 audiences uniques. Contactez votre gestionnaire de compte si cette limite est dépassée.
• Vous pouvez envoyer jusqu'à 100 corps de requête, chacun représentant un utilisateur unique, dans une seule requête.
• La valeur external_audience_id est limitée à 100 caractères.

---

Réponses d'erreur

Statut	Code	Description
202	Accepted	La requête a été acceptée. Notez qu'un 202 ne garantit pas un traitement réussi et des erreurs peuvent encore survenir en aval. Contactez votre gestionnaire de compte pour confirmer que votre audience est en ligne dans Rokt.
400	Bad Request	Le JSON de la requête est mal formé, il n'y a pas de UserProfileRequests valides après validation, ou la charge utile est trop grande. L'API prend en charge 100 requêtes par charge utile.
401	Unauthorized	L'en-tête d'authentification est manquant.
403	Forbidden	L'en-tête d'authentification est présent, mais invalide.
429	Too Many Requests	L'API utilise une limite de débit basée sur l'accélération, commençant à 270 requêtes par seconde, qui augmente automatiquement au fil du temps. Si vous dépassez la limite actuelle, l'API renvoie une réponse 429 Too Many Requests. Nous recommandons de réessayer avec un backoff exponentiel et un jitter aléatoire si aucun en-tête Retry-After n'est présent.
503	Service Unavailable	Nous recommandons de réessayer votre requête selon un modèle de backoff exponentiel.
5xx	Internal Server Error	Une erreur côté serveur s'est produite, veuillez réessayer votre requête. Si cette erreur persiste, contactez votre gestionnaire de compte.

Exemple de corps de réponse pour une requête échouée

{
    "errors" :
    [
        {
            "code" : "BAD_REQUEST",
            "message" : "requests[0].data.external_audience_membership_updates[0].external_audience_id cannot be longer than 100 characters."
        }
    ]
}