Aller au contenu principal

Guide d'intégration de l'API d'événements et d'audience

L'API d'événements de Rokt permet aux annonceurs d'envoyer des données de conversion et d'audience directement de votre serveur à Rokt. Cette intégration serveur à serveur offre un suivi de conversion fiable et complet, non affecté par les limitations des navigateurs ou les bloqueurs de publicités.

Vue d'ensemble​

Qu'est-ce que l'API d'événements ?​

L'API d'événements est une intégration côté serveur qui vous permet de :

  • Envoyer des événements de conversion - Signaler des achats, des inscriptions et d'autres actions de conversion à Rokt pour l'optimisation et l'attribution des campagnes
  • Synchroniser les données d'audience - Télécharger des segments d'utilisateurs pour le ciblage ou la suppression dans vos campagnes Rokt

Pourquoi utiliser une intégration côté serveur ?​

AvantageDescription
FiabilitéNon affectée par les bloqueurs de publicités, les paramètres de confidentialité des navigateurs ou les restrictions de cookies
CouvertureSuivre les conversions sur tous les canaux—web, application mobile, en magasin, centre d'appels
Qualité des donnéesEnvoyer des données plus riches et plus précises directement depuis vos systèmes backend
Temps réelLes événements sont traités en quasi temps réel pour une optimisation plus rapide

Prérequis​

Avant de commencer, assurez-vous d'avoir :

  1. Identifiants API - Une clé API et un secret API de votre gestionnaire de compte Rokt
  2. Rokt Click ID (optionnel, pour les conversions attribuées) - Capturé à partir des interactions publicitaires Rokt

Obtention des identifiants API​

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

Capture du Rokt Click ID (Optionnel mais Recommandé)​

La capture du Rokt Click ID est optionnelle mais fortement recommandée. Lorsqu'il est inclus comme passbackconversiontrackingid dans vos requêtes API, cet ID améliore considérablement la capacité à faire correspondre un clic à l'utilisateur qui a converti.

Rokt peut toujours effectuer l'attribution sans le Click ID, mais l'inclure permet un appariement plus précis.

Démarrage rapide​

Voici un exemple d'envoi d'un événement de conversion :

curl -X POST https://s2s.us2.mparticle.com/v2/events \
  --user "YOUR_API_KEY:YOUR_API_SECRET" \
  --header "Content-Type: application/json" \
  --header "Charset: utf-8" \
  --data '{
    "environment": "development",
    "ip": "172.3.51.182",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890"
    },
    "events": [
      {
        "event_type": "custom_event",
        "data": {
          "event_name": "conversion",
          "custom_attributes": {
            "amount": 100.00,
            "currency": "USD",
            "quantity": 1,
            "conversiontype": "purchase",
            "productname": "Maroon 5 t-shirt, Warriors vs. Raptors",
            "sku": "230847",
            "paymenttype": "VISA",
            "margin": 10.0,
            "transactionid": "ABC789",
            "confirmationref": "XYZ123"
          }
        }
      }
    ]
  }'

Une requête réussie retourne HTTP 202 Accepted.

Authentification​

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

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

  2. Vous pouvez définir manuellement l'en-tête Authorization en incluant votre clé et votre secret encodés ensemble :

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

    example-api-key:example-api-secret

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

    ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

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

    Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

    2.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êteValeurDescription
Content-Typeapplication/jsonFormat du corps de la requête
Charsetutf-8Encodage des caractères
AuthorizationBasic base64(api-key:api-secret)Informations d'authentification

Référence de l'API​

Point de terminaison​

POST https://s2s.us2.mparticle.com/v2/events

Structure du corps de la requête​

{
  "environment": "production",
  "ip": "203.0.113.42",
  "device_info": { ... },
  "user_attributes": { ... },
  "user_identities": { ... },
  "integration_attributes": { ... },
  "events": [ ... ]
}

Référence des champs​

Champs de niveau racine​

ChampTypeRequisDescription
environmentstringOuiDoit toujours être "production", même lors des tests.
ipstringNonAdresse IP de l'utilisateur. Utilisée pour la géolocalisation et la détection de fraude.

Identités utilisateur (Requis)​

Au moins un identifiant utilisateur est requis pour que Rokt associe l'événement à un utilisateur.

ChampTypeRequisDescription
user_identities.emailstringConditionnelAdresse email en texte clair. Doit être en minuscules et sans espaces. Requis si other n'est pas fourni.
user_identities.otherstringConditionnelIdentifiant alternatif (par exemple, email haché SHA256). Requis si email n'est pas fourni.
Format d'Email

Envoyez un email en texte brut dans le champ email, ou un email haché SHA-256 dans le champ other. Si vous envoyez un email haché, assurez-vous qu'il est en minuscules et tronqué avant le hachage.

Informations sur l'Appareil​

Les identifiants d'appareil améliorent les taux de correspondance, en particulier pour les utilisateurs mobiles.

ChampTypeRequisDescription
device_info.http_header_user_agentstringNonChaîne de l'agent utilisateur du navigateur ou de l'appareil.
device_info.ios_advertising_idstringNonIDFA iOS (Identifiant pour les Annonceurs). Format : UUID.
device_info.android_advertising_idstringNonID publicitaire Android (AAID). Format : UUID.

Attributs Utilisateur​

Les attributs utilisateur fournissent des données supplémentaires pour la correspondance et la personnalisation. Rokt recommande de définir autant d'attributs utilisateur suivants que possible :

ChampTypeRequisDescription
firstnamestringNonLe prénom du client.
firstnamesha256stringNonHachage SHA-256 du prénom. Avant le hachage, mettez en minuscules et supprimez tous les espaces de fin.
lastnamestringNonLe nom de famille du client.
lastnamesha256stringNonHachage SHA-256 du nom de famille. Avant le hachage, mettez en minuscules et supprimez tous les espaces de fin.
mobilestringNonLes numéros de téléphone peuvent être formatés soit comme 1112345678 soit comme +1 (222) 345-6789.
mobilesha256stringNonHachage SHA-256 du numéro de mobile. Le numéro de mobile doit être formaté comme 5551234567 (sans tirets ni espaces) avant le hachage.
agestringNonL'âge du client.
dobstringNonDate de naissance. Formatée comme yyyymmdd.
genderstringNonLe sexe du client. Par exemple, M, Male, F, ou Female.
citystringNonLa ville du client.
statestringNonL'état du client.
zipstringNonLe code postal du client.
titlestringNonLe titre du client. Par exemple, Mr, Mrs, Ms.
languagestringNonLangue associée à l'achat.
valuestringNonLa valeur du client.
predictedltvstringNonLa valeur totale de la durée de vie prévue du client.
Normalisation des Données pour le Hachage

Avant de hacher une valeur avec SHA-256 :

  • Mettez en minuscules tout le texte
  • Supprimez les espaces de début et de fin
  • Normalisez les numéros de téléphone au format 5551234567 (supprimez les tirets, espaces, parenthèses et indicatif pays)

Attributs d'Intégration​

ChampTypeRequisDescription
integration_attributes.1277.passbackconversiontrackingidstringNonL'ID de clic Rokt. Lie cette conversion à une interaction publicitaire Rokt spécifique pour l'attribution.
Attribution

Rokt peut effectuer l'attribution avec ou sans le passbackconversiontrackingid. Cependant, inclure l'ID de clic améliore considérablement la capacité à faire correspondre un clic à l'utilisateur qui a converti, ce qui entraîne une attribution plus précise.

Tableau des événements​

Le tableau events contient les données de conversion.

Quand inclure le tableau des événements

Le tableau events est nécessaire lors de l'envoi d'événements de conversion. Si vous envoyez uniquement des données d'audience, vous pouvez omettre entièrement le tableau events.

ChampTypeRequisDescription
eventsarrayOuiTableau d'objets événementiels. Doit contenir au moins un événement.
events[].event_typestringOuiDoit être "custom_event".
events[].data.event_namestringOuiDoit être "conversion".
events[].data.custom_event_typestringOuiDoit être "transaction".
events[].data.timestamp_unixtime_msnumberOuiMoment où la conversion a eu lieu, en millisecondes depuis l'époque Unix.
events[].data.custom_attributes.conversiontypestringOuiLe type d'action que l'utilisateur a effectuée (par exemple, "purchase", "signup", "subscription"). Utilisé avec confirmationref pour la déduplication.
events[].data.custom_attributes.confirmationrefstringNonNuméro de commande ou de confirmation. Utilisé avec conversiontype pour dédupliquer les événements.
events[].data.custom_attributes.amountstringNonValeur de la transaction sous forme de chaîne (par exemple, "99.99").
events[].data.custom_attributes.currencystringNonCode de devise ISO 4217 (par exemple, "USD", "EUR", "GBP").

Données d'audience​

Pour envoyer des données de segment d'audience (pour le ciblage ou la suppression), ajoutez des attributs d'audience à user_attributes.

Quand envoyer des données d'audience

Lors de l'envoi uniquement de données d'audience, vous devez seulement inclure les objets user_identities et user_attributes. Le tableau events n'est pas requis pour les requêtes uniquement d'audience.

Convention de nommage : Tous les attributs d'audience doivent être préfixés par audience_. Incluez un attribut pour chaque audience que vous souhaitez envoyer à Rokt.

ChampTypeRequisDescription
audience_{audience_name}booleanNonDéfinir sur true pour ajouter l'utilisateur à cette audience, false pour le retirer.

Exemples d'attributs d'audience :

ChampTypeRequisDescription
audience_all_users: truebooleanNonAjouter l'utilisateur à la liste "tous les utilisateurs".
audience_all_users: falsebooleanNonRetirer l'utilisateur de la liste "tous les utilisateurs".
audience_premium_users: truebooleanNonAjouter l'utilisateur à la liste "utilisateurs premium".
audience_retargeting_list: falsebooleanNonRetirer l'utilisateur de la liste d'audience de reciblage.

Exemple : Requête uniquement d'audience

curl -X POST https://s2s.us2.mparticle.com/v2/events \
  --user "your-api-key:your-api-secret" \
  --header "Content-Type: application/json" \
  --header "Charset: utf-8" \
  --data '{
    "environment": "production",
    "user_identities": {
      "email": "customer@example.com"
    },
    "user_attributes": {
      "audience_premium_users": true,
      "audience_retargeting_list": false
    }
  }'

Exemples complets​

###Conversion avec données utilisateur complètes

{
  "environment": "production",
  "ip": "203.0.113.42",
  "device_info": {
    "http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0"
  },
  "user_attributes": {
    "firstname": "John",
    "firstnamesha256": "a8cfcd74832004951b4408cdb0a5dbcd8c7e52d43f1f6c5f9fdb7c3c7a0e2d4",
    "lastname": "Doe",
    "lastnamesha256": "c1572d05424d0ecb2a65ec6a82aeacbf8c7f28f3f8f3a9dfb7a3c8b5d7a6f6a1",
    "mobile": "3125551515",
    "mobilesha256": "f6d7c3a9b82d7cbb6f3d8e4a0c2f5d1b9f6c2a5f4e7d8b3c9a2f5e8d1c4b7a6",
    "age": "33",
    "dob": "19900717",
    "gender": "M",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "title": "Mr",
    "language": "en",
    "value": "52.25",
    "predictedltv": "136.23"
  },
  "user_identities": {
    "email": "john.doe@example.com",
    "customerid": "cust_123456"
  },
  "integration_attributes": {
    "1277": {
      "passbackconversiontrackingid": "e8335d31-2031-4bff-afec-17ffc1784697"
    }
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "source_message_id": "order_789012",
        "timestamp_unixtime_ms": 1735689600000,
        "custom_attributes": {
          "conversiontype": "purchase",
          "confirmationref": "ORD-789012",
          "amount": "149.99",
          "currency": "USD"
        }
      }
    }
  ]
}

Requête axée sur la confidentialité (données hachées uniquement)​

{
  "environment": "production",
  "user_identities": {
    "other": "8b1a9953c4611296a827abf8c47804d7e6c49c6b97d"
  },
  "user_attributes": {
    "firstnamesha256": "a8cfcd74832004951b4408cdb0a5dbcd8c7e52d9c3f1f6c5f9fdb7c3c7a0e2d4",
    "lastnamesha256": "c1572d05424d0ecb2a65ec6a82aeacbf8c7f28f3f8f3a9dfb7a3c8b5d7a6f6a1"
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "source_message_id": "evt_unique_456",
        "timestamp_unixtime_ms": 1735689600000,
        "custom_attributes": {
          "conversiontype": "signup"
        }
      }
    }
  ]
}

##Gestion des erreurs

StatutCodeDescription
202AcceptéLe POST a été accepté.
400Mauvaise requêteLe JSON de la requête était mal formé ou avait des champs manquants.
401Non autoriséL'en-tête d'authentification est manquant.
403InterditL'en-tête d'authentification est présent, mais invalide.
429Trop de requêtesVous avez dépassé votre limite provisionnée. Le point de terminaison v2/events peut renvoyer un en-tête de réponse Retry-After avec une valeur contenant un entier décimal non négatif indiquant le nombre de secondes à attendre. Si l'en-tête n'est pas présent, nous recommandons de réessayer votre requête avec un backoff exponentiel et un jitter aléatoire.
503Service indisponibleNous recommandons de réessayer votre requête selon un modèle de backoff exponentiel.
5xxErreur serveurUne erreur côté serveur s'est produite, veuillez réessayer votre requête.

Dans certains cas, le serveur fournit des informations supplémentaires dans le corps de la réponse. Si aucune information supplémentaire n'est disponible, le corps de la réponse sera omis et vous ne recevrez que le code de statut et le message.

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

{
    "errors": [
        {
            "code": "BAD_REQUEST",
            "message": "Le champ requis \"event_type\" est manquant ou vide."
        }
    ]
}

Limites​

Voici les limites de taux et de taille pour l'API d'événements :

RessourceLimite
Taille totale de la requête256 KB
Lots par seconde270 lots par seconde
Longueur du nom de l'événement256 caractères
Longueur du nom d'attribut256 caractères
Longueur de la valeur d'attribut4096 caractères
Attributs utilisateur par lot100
Longueur du nom d'attribut utilisateur256 caractères
Longueur de la valeur d'attribut utilisateur4096 caractères

Limitation de débit​

Rokt applique des limites de débit pour assurer la stabilité de la plateforme. Lorsque les limites sont dépassées, l'API renvoie HTTP 429 Trop de requêtes.

###Types de Limitation de Taux

TypeDescription
VitesseNombre maximum de requêtes par fenêtre de temps
AccélérationTaux maximum d'augmentation du trafic

Gestion des Limitations de Taux​

Lorsque vous recevez une réponse 429 :

  1. Vérifiez l'en-tête Retry-After pour le temps d'attente recommandé
  2. Implémentez un backoff exponentiel avec jitter :
import random

def calculate_backoff(attempt, retry_after=None, max_delay=60):
    base_delay = retry_after if retry_after else 1
    exponential_delay = min(base_delay * (2 ** attempt), max_delay)
    jitter = random.uniform(0, exponential_delay)
    return exponential_delay + jitter

Gestion Proactive des Taux​

Les réponses réussies incluent l'en-tête X-mp-rate-limit-percentage-used montrant votre pourcentage d'utilisation actuel. Surveillez cela pour ajuster votre taux de requêtes avant d'atteindre les limites.

X-mp-rate-limit-percentage-used: 75

Combinaison avec le SDK Web​

Pour une couverture maximale, vous pouvez envoyer des conversions à la fois via le SDK Web et l'API d'Événements. Rokt dédupliquera automatiquement les événements lorsque vous incluez des identifiants cohérents.

Pour activer la déduplication, incluez les mêmes valeurs pour conversiontype et confirmationref dans les deux intégrations. Rokt utilise la combinaison de ces deux champs pour identifier et dédupliquer les événements.

Cette approche fournit :

  • Redondance - Les conversions sont capturées même si une intégration échoue
  • Validation - Comparez les données des deux sources pour identifier les divergences

Tests​

Environnement de Développement​

Travaillez avec votre gestionnaire de compte Rokt pour configurer les tests dans un environnement de développement avant de passer en production.

remarque

Le champ environment doit toujours être défini sur "production", même pendant les tests. Ce champ indique la version du format de données, pas votre étape de déploiement.

Liste de Vérification des Tests​

  • Vérifiez que l'authentification fonctionne avec vos identifiants
  • Envoyez un événement test et confirmez la réponse 202 Accepted
  • Testez la gestion des erreurs avec des charges utiles invalides
  • Vérifiez que les événements apparaissent dans le rapport de Rokt (coordonnez-vous avec votre gestionnaire de compte)
  • Testez la gestion des limitations de taux
  • Fournissez quelques adresses e-mail de test que vous avez envoyées à votre gestionnaire de compte Rokt pour confirmer que l'intégration fonctionne de bout en bout

##Support

Pour des questions ou de l'assistance concernant votre intégration, contactez votre gestionnaire de compte Rokt qui vous fournira les ressources appropriées pour vous aider à résoudre tout problème.

Cet article vous a-t-il été utile ?
Last updated Jan 28, 2026