Guide d'Intégration de l'API d'Événements

Les annonceurs peuvent configurer une intégration serveur-à-serveur pour envoyer des données de conversion et d'attribution depuis un serveur backend directement à Rokt via l'API d'Événements.

L'envoi de données de conversion à Rokt via l'API d'Événements offre plusieurs avantages :

Rapidité : L'API d'Événements permet un transfert de données quasi en temps réel, maximisant le potentiel des outils d'optimisation de Rokt.
Couverture : L'API d'Événements vous permet d'envoyer des données depuis tous vos canaux et appareils, résultant en une couverture plus large.
Fiabilité : Contrairement aux SDKs, l'API d'Événements n'est pas susceptible d'interférences de la part des technologies web comme les bloqueurs de publicités. Elle prend également en charge la gestion des erreurs, vous aidant à prévenir les pertes de données indésirables.

AuthentificationLien direct vers Authentification

Votre représentant dédié de compte Rokt vous fournira votre clé API et votre secret API que vous pouvez utiliser pour vous authentifier à l'API d'Événements.

Selon votre client HTTP, vous pouvez vous authentifier à l'API avec votre clé et votre secret de deux manières :

En définissant votre clé et votre secret comme votre nom d'utilisateur et mot de passe dans votre client, OU
En passant votre clé et votre secret dans votre en-tête d'authentification.

Nom d'utilisateur et mot de passeLien direct vers Nom d'utilisateur et mot de passe

Si votre client HTTP prend en charge l'authentification de base (basic authentication), définissez simplement votre clé API comme nom d'utilisateur et votre secret API comme mot de passe.

En-tête d'authentification de baseLien direct vers En-tête d'authentification de base

Vous pouvez également définir l'en-tête d'authentification de base de votre requête HTTP vers l'API Event pour utiliser votre clé et votre secret :

Concaténez votre clé et votre secret ensemble en utilisant un deux-points (:)

example-api-key:example-api-secret
En utilisant Base64/UTF-8, encodez votre clé et votre secret concaténés. Cela ressemblera à :

ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==
Préfixez cette chaîne avec la méthode d'authentification (Basic) suivie d'un espace.
Définissez cette chaîne comme l'en-tête d'authentification dans votre requête :

Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

Point de terminaison (Endpoint) de l'API EventLien direct vers Point de terminaison (Endpoint) de l'API Event

L'API Event accepte les requêtes POST envoyées à :

https://s2s.{pod}.mparticle.com/v2/events

Où {pod} est remplacé par le pod de localisation des données partagé avec vous par votre représentant de compte Rokt.

Localisation des donnéesLien direct vers Localisation des données

Rokt stocke et traite vos données dans des régions isolées et localisées appelées pods. Votre représentant Rokt dédié vous fournira l'identifiant de pod correct pour votre compte. En fonction de l'identifiant de pod qu'ils vous donnent, utilisez l'URL de l'API d'événements (Event API) correspondante selon le tableau ci-dessous :

Région	Pod	URL de l'API d'événements
États-Unis	US1	`https://s2s.us1.mparticle.com/v2`
États-Unis	US2	`https://s2s.us2.mparticle.com/v2`
Europe	EU1	`https://s2s.eu1.mparticle.com/v2`
Australie	AU1	`https://s2s.au1.mparticle.com/v2`

Créez votre charge utileLien direct vers Créez votre charge utile

Rokt vous demande d'envoyer les champs suivants pour suivre avec succès une conversion et l'associer à une campagne :

Champs de configurationLien direct vers Champs de configuration

Nom du champ	Type de données	Description
`environment`	string	Peut être soit `development` soit `production`. Indique si les données sont des données de test ou des données en direct.

Identités des utilisateursLien direct vers Identités des utilisateurs

Nom du champ	Type de données	Description
`email`	string	L'adresse email de l'utilisateur.
`other`	string	L'adresse email hachée de l'utilisateur.

remarque

Vous devez inclure soit l'adresse email brute et non hachée de l'utilisateur en utilisant le champ email, soit leur adresse email hachée en utilisant le champ other. Au moins un de ces identifiants doit être inclus dans votre charge utile (payload) pour l'API Event.

Attributs des utilisateursLien direct vers Attributs des utilisateurs

Nom du champ	Type de données	Description
`firstname`	string	Le prénom de l'utilisateur.
`lastname`	string	Le nom de famille de l'utilisateur.
`mobile`	string	Le numéro de téléphone de l'utilisateur, formaté soit comme `3053211654`, soit `+1 (323) 867-5309`
`ipaddress`	string	L'adresse IP de l'utilisateur qui a converti.

Vous devriez inclure autant d'attributs d'utilisateur que possible pour améliorer la qualité et l'efficacité de vos données d'attribution.

Données d'événementLien direct vers Données d'événement

Nom du champ	Type de données	Description
`event_type`	string	Doit être défini sur `custom_event`.
`event_name`	string	Le nom de l'événement doit toujours être défini sur `conversion`. Vous pouvez utiliser le champ `conversion_type` pour inclure des informations supplémentaires sur le type de conversion, comme s'il s'agissait d'un `purchase` ou d'un `subscription`.
`amount`	decimal	Le prix total de tous les articles. Par exemple, si le prix total de tous les articles est de 20 $, définissez le montant à 20,00.
`currency`	string	Le code de devise pour la conversion. Par exemple : `USD` ou `CAD`.
`quantity`	integer	Le nombre d'articles dans la conversion.
`conversiontype`	string	Le type de conversion qui a eu lieu.
`productname`	string	Le nom de l'article acheté lors de la conversion.
`sku`	string	Le SKU pour l'article. S'il y a plus d'un article, ne fournissez aucun SKU.
`paymenttype`	string	Le type de paiement utilisé. Par exemple : `visa`.
`margin`	decimal	La marge bénéficiaire totale de la conversion ou de la transaction, en pourcentage. Par exemple, pour indiquer une marge de 10 $, définissez `margin` à `10`.
`transactionid`	string	L'ID de transaction de la conversion.
`confirmationref`	string	ID de référence de confirmation. Il s'agit d'un identifiant alternatif. Remarque : Si fourni, Rokt utilise ce champ pour dédupliquer les événements de conversion.

Le corps de votre requête doit contenir ces champs formatés dans un objet JSON avec la structure suivante :

Exemple de charge utile :Lien direct vers Exemple de charge utile :

{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "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"
           }
        }
      }
    ]
}

Envoyez votre charge utile à RoktLien direct vers Envoyez votre charge utile à Rokt

Pour envoyer votre charge utile à Rokt, envoyez une requête POST à https://s2s.{pod}.mparticle.com/v2/events, en veillant à remplacer {pod} par l'identifiant du pod fourni par votre représentant de compte Rokt.

Exemple de requêteLien direct vers Exemple de requête

curl --location 'https://s2s.mparticle.com/v2/events' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key-secret' \
--data-raw '{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "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,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}'

POST /v2/events HTTP/1.1
Host: s2s.mparticle.com
Content-Type: application/json
Accept: application/json
Authorization: key-secret
Content-Length: 920

{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "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,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}

RéponseLien direct vers Réponse

Une requête réussie reçoit une réponse vide 202 Accepted.

Pour un aperçu des erreurs possibles qui peuvent survenir, voir la section Gestion des erreurs ci-dessous.

Gestion des erreursLien direct vers Gestion des erreurs

Statut	Code	Description
400	Bad Request	Le corps JSON de la requête est mal formé ou des champs obligatoires sont manquants.
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	La limite de débit a été dépassée. La réponse inclut un en-tête Retry-After avec une valeur contenant un entier décimal non négatif indiquant le nombre de secondes à attendre avant de réessayer. Si l'en-tête Retry-After n'est pas présent, réessayez votre requête en utilisant un backoff exponentiel et un jitter aléatoire.
503	Service Unavailable	Réessayez votre demande en suivant un modèle de backoff exponentiel.
5xx	Server Error	Erreur interne, réessayez votre demande.

LimitesLien direct vers Limites

Voici les limites de taux et de taille pour l'API Event :

Ressource	Limite
Taille totale de la requête	256kb
Lots par seconde	270 lots par seconde
Longueur du nom de l'événement	256 caractères
Longueur du nom de l'attribut de l'événement	256 caractères
Longueur de la valeur de l'attribut de l'événement	4096 caractères
Attributs utilisateur par lot	100
Longueur du nom de l'attribut utilisateur	256 caractères
Longueur de la valeur de l'attribut utilisateur	4096 caractères