Guide d'intégration de l'API Events

L'API Events de Rokt permet aux annonceurs d'envoyer des données de conversion depuis votre serveur directement à Rokt. Cette intégration serveur à serveur offre un suivi de conversion fiable et complet qui n'est pas affecté par les limitations des navigateurs ou les bloqueurs de publicités.

Vue d'ensemble

Qu'est-ce que l'API Events ?

L'API Events est une intégration côté serveur qui vous permet d'envoyer des événements de conversion — signalant des achats, des inscriptions et d'autres actions de conversion à Rokt pour l'optimisation et l'attribution des campagnes.

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

Avantage	Description
Fiabilité	Non affectée par les bloqueurs de publicités, les paramètres de confidentialité des navigateurs ou les restrictions de cookies
Couverture	Suivre les conversions sur tous les canaux — web, application mobile, en magasin, centre d'appels
Qualité des données	Envoyer des données plus riches et plus précises directement depuis vos systèmes backend
Temps réel	Les é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 de clé API et de 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 dans vos requêtes API, cet ID améliore considérablement la capacité à faire correspondre un clic à l'utilisateur qui a converti. Envoyez la même valeur de Click ID dans les deux :

• integration_attributes.1277.passbackconversiontrackingid
• user_identities.other2

Rokt peut toujours effectuer l'attribution sans le Click ID, mais l'inclure (dans les deux champs lorsque c'est possible) 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",
      "customerid": "cust_123456",
      "other2": "YOUR_ROKT_CLICK_ID"
    },
    "integration_attributes": {
      "1277": {
        "passbackconversiontrackingid": "YOUR_ROKT_CLICK_ID"
      }
    },
    "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 renvoie HTTP 202 Accepted.

---

Authentification

L'API Events 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 "nom d'utilisateur" et votre secret pour "mot de passe".

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, y compris 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ê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 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": [ ... ]
}

---

Field Reference

Champs au niveau racine

Champ	Type	Requis	Description
environment	string	Oui	Doit toujours être "production", même lors des tests.
ip	string	Non	Adresse 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 puisse associer l'événement à un utilisateur.

Champ	Type	Requis	Description
user_identities.email	string	Conditionnel	Adresse email en texte brut. Doit être en minuscules et sans espaces. Requis si other n'est pas fourni.
user_identities.other	string	Conditionnel	Identifiant alternatif (par exemple, email haché SHA256). Requis si email n'est pas fourni.
user_identities.customerid	string	Non	Votre ID client ou utilisateur interne. Améliore la correspondance lorsqu'il est présent dans plusieurs événements.
user_identities.other2	string	Non	Pour les événements de vue de page (vue d'écran), utilisez la même valeur que integration_attributes.1277.passbackconversiontrackingid (le Rokt Click ID) afin que l'événement puisse être attribué à la bonne session utilisateur.

Format de l'email

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

ID de clic et autre2

Lorsque vous avez un ID de clic Rokt (par exemple, à partir d'un paramètre d'URL ou d'un cookie), envoyez-le à la fois dans integration_attributes.1277.passbackconversiontrackingid et user_identities.other2 afin que l'événement soit attribué à la bonne session utilisateur. Ceci est particulièrement important pour les événements de vue de page (vue d'écran) où vous ne pouvez pas avoir d'e-mail ou d'autres identifiants.

Informations sur l'appareil

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

Champ	Type	Requis	Description
device_info.http_header_user_agent	string	Non	Chaîne d'agent utilisateur du navigateur ou de l'appareil.
device_info.ios_advertising_id	string	Non	IDFA iOS (Identifiant pour les annonceurs). Format : UUID.
device_info.android_advertising_id	string	Non	ID 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 que possible des attributs utilisateur parmi les suivants :

Champ	Type	Requis	Description
firstname	string	Non	Le prénom du client.
firstnamesha256	string	Non	Hachage SHA-256 du prénom. Avant le hachage, mettre en minuscules et supprimer tous les espaces de fin.
lastname	string	Non	Le nom de famille du client.
lastnamesha256	string	Non	Hachage SHA-256 du nom de famille. Avant le hachage, mettre en minuscules et supprimer 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	L'âge du client.
dob	string	Non	Date de naissance. Formatée comme yyyymmdd.
gender	string	Non	Le genre du client. Par exemple, M, Male, F, ou Female.
city	string	Non	La ville du client.
state	string	Non	L'état du client.
zip	string	Non	Le code postal du client.
title	string	Non	Le titre du client. Par exemple, Mr, Mrs, Ms.
language	string	Non	Langue associée à l'achat.
value	string	Non	La valeur du client.
predictedltv	string	Non	La valeur totale de durée de vie prédite du client.

Normalisation des données pour le hachage

Avant de hacher une valeur avec SHA-256 :

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

Attributs d'intégration

Champ	Type	Requis	Description
integration_attributes.1277.passbackconversiontrackingid	string	Non	L'ID de clic Rokt. Lie cette conversion à une interaction publicitaire Rokt spécifique pour l'attribution. Lorsqu'il est fourni, définissez également user_identities.other2 à la même valeur.

Attribution

Rokt peut effectuer l'attribution avec ou sans le passbackconversiontrackingid. Cependant, inclure l'ID de clic améliore considérablement la capacité à associer un clic à l'utilisateur qui a converti, ce qui entraîne une attribution plus précise. Utilisez la même valeur pour les deux passbackconversiontrackingid et user_identities.other2.

Tableau des événements

Le tableau events contient les données de conversion.

Quand inclure le tableau des événements

Le tableau events est requis lors de l'envoi d'événements de conversion.

Champ	Type	Requis	Description
events	array	Oui	Tableau d'objets d'événements. Doit contenir au moins un événement.
events[].event_type	string	Oui	Doit être "custom_event".
events[].data.event_name	string	Oui	Doit être "conversion".
events[].data.custom_event_type	string	Oui	Doit être "transaction".
events[].data.timestamp_unixtime_ms	number	Oui	Quand la conversion a eu lieu, en millisecondes depuis l'époque Unix.
events[].data.custom_attributes.conversiontype	string	Oui	Le type d'action que l'utilisateur a effectuée (par exemple, "purchase", "signup", "subscription", "screen_view" pour les vues de page). Utilisé avec confirmationref pour la déduplication.
events[].data.custom_attributes.confirmationref	string	Non	Numéro de commande ou de confirmation. Utilisé avec conversiontype pour dédupliquer les événements.
events[].data.custom_attributes.amount	string	Non	Valeur de la transaction sous forme de chaîne (par exemple, "99.99").
events[].data.custom_attributes.currency	string	Non	Code de devise ISO 4217 (par exemple, "USD", "EUR", "GBP").
events[].data.custom_attributes.screen_name	string	Non	Pour les événements screen_view : l'identifiant de la page ou de l'écran (par exemple, nom de fichier ou segment de chemin).
events[].data.custom_attributes.url	string	Non	Pour les événements screen_view : l'URL complète de la page vue.

---

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",
    "other2": "e8335d31-2031-4bff-afec-17ffc1784697"
  },
  "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",
    "customerid": "cust_456789"
  },
  "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"
        }
      }
    }
  ]
}

Événement de vue de page (vue d'écran)

Les événements de vue de page sont utilisés pour notre stratégie de reciblage d'audience. Intégrez ces événements pour permettre à Rokt de cibler les abandons de site. Utilisez ce modèle pour envoyer des événements de vue de page ou de vue d'écran. Pour l'intégration, définissez les deux user_identities.other2 et integration_attributes.1277.passbackconversiontrackingid sur la même valeur d'ID de clic Rokt (par exemple, à partir de votre paramètre d'URL ou de cookie).

{
  "environment": "production",
  "ip": "198.51.100.22",
  "device_info": {
    "http_header_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "user_identities": {
    "email": "visitor@example.com",
    "other": "SHA256-hash-of-email",
    "customerid": "cust_visit_001",
    "other2": "b4e7f891-33b2-49df-0bf4-6710ffd96604"
  },
  "integration_attributes": {
    "1277": {
      "passbackconversiontrackingid": "b4e7f891-33b2-49df-0bf4-6710ffd96604"
    }
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "timestamp_unixtime_ms": 1735765200000,
        "custom_attributes": {
          "screen_name": "premium-checkout.html",
          "url": "https://example.com/checkout/premium-checkout.html?rtid=b4e7f891-33b2-49df-0bf4-6710ffd96604",
          "conversiontype": "screen_view"
        }
      }
    }
  ]
}

Identité utilisateur pour les vues de page

Pour les événements de vue de page, incluez l'ID de clic Rokt dans les deux user_identities.other2 et integration_attributes.1277.passbackconversiontrackingid afin que l'événement soit lié à la même session utilisateur provenant de l'annonce Rokt.

Quand l'email ou l'ID client n'est pas disponible

Pour les vues de page, vous pouvez utiliser user_identities.other2 pour transmettre un ID de clic ou un ID de session lorsque l'email ou l'ID client n'est pas disponible. Définissez la même valeur dans integration_attributes.1277.passbackconversiontrackingid afin que l'événement soit attribué à la session utilisateur correcte.

---

Gestion des erreurs

Statut	Code	Description
202	Accepté	Le POST a été accepté.
400	Mauvaise requête	Le JSON de la requête était mal formé ou avait des champs manquants.
401	Non autorisé	L'en-tête d'authentification est manquant.
403	Interdit	L'en-tête d'authentification est présent, mais invalide.
429	Trop de requêtes	Vous 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.
503	Service indisponible	Nous recommandons de réessayer votre requête selon un schéma de backoff exponentiel.
5xx	Erreur serveur	Une erreur côté serveur est survenue, 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 recevrez uniquement le code de statut et le message.

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

{
    "errors": [
        {
            "code": "BAD_REQUEST",
            "message": "Required event field \"event_type\" is missing or empty."
        }
    ]
}

---

Limites

Les limites suivantes s'appliquent à l'API d'événements :

Ressource	Limite
Taille totale de la requête	256 Ko
Lots par seconde	270 lots par seconde
Longueur du nom de l'événement	256 caractères
Longueur du nom d'attribut	256 caractères
Longueur de la valeur d'attribut	4096 caractères
Attributs utilisateur par lot	100
Longueur du nom d'attribut utilisateur	256 caractères
Longueur de la valeur d'attribut utilisateur	4096 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 Too Many Requests.

Types de Limitation de Taux

Type	Description
Vitesse	Nombre maximum de requêtes par fenêtre de temps
Accélération	Taux 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 offre :

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

---

Test

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 réglé sur "production", même pendant les tests. Ce champ indique la version du format de données, et non votre stade 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 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 toute question ou 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.