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 ?

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 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ê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)	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

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 associe l'événement à un utilisateur.

Champ	Type	Requis	Description
user_identities.email	string	Conditionnel	Adresse email en texte clair. 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.

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.

Champ	Type	Requis	Description
device_info.http_header_user_agent	string	Non	Chaîne de l'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 d'attributs utilisateur suivants que possible :

Champ	Type	Requis	Description
firstname	string	Non	Le 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	Le 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	L'âge du client.
dob	string	Non	Date de naissance. Formatée comme yyyymmdd.
gender	string	Non	Le sexe 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 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

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.

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.

Champ	Type	Requis	Description
events	array	Oui	Tableau d'objets événementiels. 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	Moment où 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"). 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").

---

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.

Champ	Type	Requis	Description
audience_{audience_name}	boolean	Non	Définir sur true pour ajouter l'utilisateur à cette audience, false pour le retirer.

Exemples d'attributs d'audience :

Champ	Type	Requis	Description
audience_all_users: true	boolean	Non	Ajouter l'utilisateur à la liste "tous les utilisateurs".
audience_all_users: false	boolean	Non	Retirer l'utilisateur de la liste "tous les utilisateurs".
audience_premium_users: true	boolean	Non	Ajouter l'utilisateur à la liste "utilisateurs premium".
audience_retargeting_list: false	boolean	Non	Retirer 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

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 modèle de backoff exponentiel.
5xx	Erreur serveur	Une 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 :

Ressource	Limite
Taille totale de la requête	256 KB
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 Trop de requêtes.

###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 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.