API d'Événements
Aperçu
L'API d'Événements de Rokt est une interface flexible et robuste qui peut prendre en charge tout type d'événement client (par exemple, achat, ouverture d'application ou visite en magasin) ainsi que tout attribut associé (par exemple, adresse e-mail, montant d'achat, BIN de carte de crédit).
Les partenaires Rokt Ecommerce peuvent utiliser l'API d'Événements en conjonction avec le Web SDK pour la détection d'anomalies, aidant à détecter les incohérences dans le comportement de placement.
Les clients Rokt Ads peuvent utiliser l'API d'Événements pour intégrer les données de conversion avec Rokt, améliorant ainsi les performances et l'optimisation des campagnes.
Authentification
Contactez votre responsable de compte Rokt pour créer une paire de clés publiques et secrètes pour les comptes auxquels vous souhaitez soumettre des événements de conversion. Ces clés que vous recevrez seront :
| Nom | Valeur |
|---|---|
| Clé Publique Rokt | rpub-*****-* |
| Clé Secrète Rokt | rsec-*****-* |
Point de terminaison de l'API
POST Événements
L'API des événements permet aux clients d'intégrer un ou plusieurs événements avec la plateforme Rokt. Les événements se réfèrent généralement à des événements de conversion ou de transaction, mais leur utilisation est flexible.
L'API des événements a deux cas d'utilisation principaux : détection d'anomalies (pour les partenaires) et rapports de conversion (pour les annonceurs).
POST /v2/events
Demande
En-tête
| Nom | Valeur | Requis | Description |
|---|---|---|---|
Content-Type | application/json | Oui | N/A |
Charset | utf-8 | Oui | N/A |
Rokt-Version | 2020-05-21 | Oui | Version de l'API pour Rokt. La dernière version est actuellement 2020-05-21. Remarque : Laisser cet en-tête vide applique la dernière version, ce qui pourrait potentiellement être incompatible avec les versions antérieures. Une valeur invalide donnerait 400 bad request. |
Authorization | Basic base64(rpub-...:rsec-...) | Oui | En-tête d'authentification basique, avec la valeur d'identification étant un encodage base64 de rpub- et rsec- joints par un deux-points. |
Paramètres
La demande contient des événements et des détails associés au format JSON.
| Niveau 1 | Niveau 2 | Niveau 3 | Requis | Type | Description |
|---|---|---|---|---|---|
accountId | Oui | String; jusqu'à 64 caractères | Rokt Account ID | ||
events | Oui | List[EventObject]; jusqu'à 100 éléments par appel | Liste des événements à ingérer | ||
clientEventId | Oui | String; jusqu'à 36 caractères | Un identifiant utilisé pour identifier de manière unique un événement | ||
eventType | Oui | String; jusqu'à 128 caractères | Type d'événement | ||
eventTime | Oui | String | L'heure de l'événement doit être en UTC et conforme à RFC 3339. La demande sera rejetée si elle contient un événement avec un horodatage plus ancien que 18 mois ou plus de 5 minutes dans le futur par rapport au moment où l'API d'événements la reçoit. Les événements avec des horodatages en dehors de cette plage ne sont pas traités. | ||
metaData | Non | List[metaData] | Fournit des informations non critiques pour l'entreprise concernant l'événement | ||
name | Oui | String; jusqu'à 256 caractères | Nom du champ ; Préfixe rokt. (sans distinction de casse) est préservé uniquement pour l'utilisation de Rokt | ||
value | Oui | String; jusqu'à 65536 caractères | Valeur du champ ; pour les valeurs binaires, encodez avec Base64 | ||
objectData | Non | List[objectData] | Contient des détails contextuels sur l'événement | ||
name | Oui | String; jusqu'à 256 caractères | Préfixe rokt. (sans distinction de casse) est préservé uniquement pour l'utilisation de Rokt | ||
value | Oui | String; jusqu'à 65536 caractères | Valeur du champ ; pour les valeurs binaires, encodez avec Base64 |
Champs objectData standards
Voici une liste des champs objectData standards que Rokt accepte via l'API d'événements. En fonction de votre cas d'utilisation, certains champs sont plus pertinents que d'autres. Consultez la détection d'anomalies ou le reporting de conversion pour des exemples de payload spécifiques selon votre cas d'utilisation.
Si vous souhaitez ajouter des champs de données supplémentaires ou utiliser un autre nom pour un champ particulier, faites-le savoir à votre responsable de compte.
| Nom | Description | Valeur d'exemple |
|---|---|---|
email | Email transmis en texte brut, en lettres minuscules et sans espaces à la fin | john@email.com |
emailsha256 | Hachage SHA-256 de l'adresse email. Avant le hachage, en minuscules et sans espaces à la fin. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
passbackconversiontrackingid | Un ID généré par Rokt utilisé pour faire correspondre les événements de conversion au clic d'origine. Nécessite une intégration séparée. | 1bc29b36f623ba82aaf6724fd3b16718 |
amount | Montant de la transaction (autorise les décimales) | 100.25 |
currency | Code de la devise | USD |
quantity | La quantité (entier) d'articles dans la conversion spécifique | 4 |
conversiontype | Utilisé pour différencier les différents événements de conversion. Remarque: S'applique uniquement si le type d'événement de conversion par défaut est fourni. | ticketpurchase, seatupgrade, signup |
productname | Le nom du ou des produits achetés. Vous pouvez séparer plusieurs articles par une virgule. | Maroon 5 t-shirt, Warriors vs. Raptors |
sku | L'identifiant du produit acheté (Remarque : n'accepte qu'un seul SKU) | 230847, tshirt-blue-39487, 398fhdnff |
paymenttype | Méthode de paiement utilisée lors de la transaction | VISA, American Express |
ccbin | BIN de carte de crédit du paiement en cours | 123456 |
margin | Marge bénéficiaire de la conversion | 10 |
transactionid | ID de transaction, utilisé pour identifier une transaction unique. | ABC789 |
confirmationref | ID de référence de confirmation. Identifiant alternatif qui peut être utilisé pour identifier une transaction unique et/ou suivre les confirmations de commande. Note: Si fourni, Rokt utilise cet identifiant pour dédupliquer les événements de conversion. | XYZ123 |
firstname | Prénom du client | John |
firstnamesha256 | Hachage SHA-256 du prénom. Avant le hachage, mettez en minuscules et supprimez tous les espaces à la fin. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
lastname | Nom de famille du client | Smith |
lastnamesha256 | Hachage SHA-256 du nom de famille. Avant le hachage, mettez en minuscules et supprimez tous les espaces à la fin. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
mobile | Numéro de téléphone mobile du client en cours | 3053211654, +1 (323) 867-5309 |
mobilesha256 | SHA-256 du numéro mobile. Note: Le numéro mobile doit être formaté selon ce format spécifique avant le hachage : 5551234567 (ne contenant pas de tirets ou d'espaces). | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
ipaddress | Adresse IP du client | 172.3.51.182 |
ipaddresssha256 | Hachage SHA-256 de l'adresse IP. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
useragent | Agent utilisateur du navigateur du client en cours | Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 |
DeviceType | Type d'appareil | Desktop, Mobile, Tablet |
os | Système d'exploitation de l'appareil | iOS |
osversion | Version du système d'exploitation | 8.1 |
browser | Navigateur | Safari |
browserversion | Version du navigateur | 11.1 |
title | Titre du client | Mr, Mrs, Ms, Miss |
gender | Genre du client | M, Male, F, Female |
dob | Au format yyyymmdd | 19851220 |
age | Âge du client | 33 |
language | Langue associée à l'achat | en, en-US |
unitno | Numéro de l'unité associé à l'adresse | Unit A |
address1 | Première ligne de l'adresse | 123 Sesame St |
address2 | Deuxième ligne de l'adresse (numéro d'appartement, étage, etc.) | Alphabet Boulevard |
zipcode | Code postal du client | 90210, SW1W 0DT |
city | Ville du client | San Francisco |
state | État du client | CA, California, NY, New York |
country | Pays du client | US, États-Unis, AU, Australie |
Exemple
Ceci est un exemple d'appel API Event avec une charge utile JSON contenant deux événements de réservation.
POST /v2/events
{
"accountId": "12345",
"events": [
{
"clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
"eventType": "booking",
"eventTime": "2020-05-22T10:21:29.339Z",
"metaData": [
{
"name": "sourceServer",
"value": "192.0.0.1"
}
],
"objectData": [
{
"name": "email",
"value": "email123@emailserver.com"
},
{
"name": "amount",
"value": "85.00"
}
]
},
{
"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
"eventType": "booking",
"eventTime": "2020-05-22T10:21:29.339Z",
"metaData": [
{
"name": "sourceServer",
"value": "192.0.0.1"
}
],
"objectData": [
{
"name": "email",
"value": "email456@emailserver.com"
},
{
"name": "amount",
"value": "99.99"
}
]
}
]
}
Réponse
En-tête
| Nom | Description |
|---|---|
X-Rokt-Trace-Id | Identifiant unique associé à la requête, utilisé à des fins de dépannage. |
Corps
Les appels réussis à l'API d'Événements renvoient un statut 200. L'objet unprocessedRecords doit être vide, indiquant que tous les événements ont été traités avec succès.
Exemples
Le code exemple ci-dessous représente un appel réussi à l'API d'Événements.
{
"data": {
"unprocessedRecords": []
}
}
Lorsque vous validez une réponse 200, assurez-vous qu'aucun événement n'est renvoyé dans unprocessedRecords. S'il y a des enregistrements dans unprocessedRecords, un ou plusieurs de vos événements peuvent ne pas avoir été traités correctement.
Réponses
| Code de réponse HTTP | Code d'erreur | Description |
|---|---|---|
| 200 | N/A | Typiquement OK, mais voir l'exemple d'un scénario d'erreur 200 ci-dessous. |
| 400 | RequestBodyReadError | Une erreur est survenue lors de la lecture du corps de la requête. |
| 400 | RequestJsonUnmarshalError | L'API d'événements n'a pas pu désérialiser le corps de la requête. |
| 400 | RequestValidationError | Le contenu du corps de la requête n'a pas réussi nos vérifications de validation. Vérifiez que vous avez bien suivi les exigences de paramètres. |
| 401 | UnauthorizedError | Jeton d'authentification non autorisé ou invalide. |
| 403 | Interdit | Le jeton d'accès fourni n'est pas autorisé sur votre compte. |
| 500, 502, 503 | InternalServerError, ServiceUnavailableError | Erreurs inattendues du côté de Rokt. Réessayez en utilisant un délai exponentiel ou contactez votre équipe d'assistance Rokt. |
Exemple
{
"data": {
"code": "RequestJsonUnmarshalError",
"message": "impossible de désérialiser le corps de la requête"
}
}
Scénario d'erreur 200
HTTP Status 200 indique généralement un appel réussi. Cependant, comme l'API d'événements est une API par lots, une réponse 200 ne signifie pas nécessairement que toute la demande a été traitée correctement. Les développeurs doivent examiner la charge utile de la réponse pour s'assurer que tous les enregistrements ont été traités. La charge utile de la réponse contient un message d'erreur ainsi que l'objet d'événement spécifique qui a échoué.
| Niveau 1 | Niveau 2 | Niveau 3 | Niveau 4 | Type | Description |
|---|---|---|---|---|---|
data | BulkResponseItemObject | ||||
unprocessedRecords | List[BulkResponseItemObject] | Une liste d'objets contenant des enregistrements qui n'ont pas pu être traités. | |||
error | ErrorObject | Décrit l'erreur liée à l'enregistrement. | |||
code | String | Code d'erreur | |||
message | String | Message d'erreur détaillé | |||
record | EventObject | Le champ contient l'enregistrement original qui a échoué. |
{
"data": {
"unprocessedRecords": [
{
"error": {
"code": "ValidationError",
"message": "Contenu invalide"
},
"record": {
"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
"eventType": "conversion",
"eventTime": "2020-05-22T10:21:29.339Z",
"objectData": [
{
"name": "firstname",
"value": "john"
}
]
}
}
]
}
}
Authentification Héritée (v1)
Les utilisateurs existants et les utilisateurs en cours d'intégration dans des plateformes de données clients spécifiques (CDPs) (à savoir Census, Hightouch, mParticle, Segment et Tealium) Les nouveaux utilisateurs de l'API d'événements doivent utiliser le /v2/events pour une expérience d'authentification simplifiée.
L'API d'événements utilise l'approche OAuth 2.0 pour l'intégration des clients. Voir OAuth 2.0 Credentials Flow pour plus de détails. Vous avez besoin de votre ID d'application Rokt et de votre secret d'application pour accéder à l'API d'événements Rokt.
Vous pouvez générer des identifiants pour l'API de Reporting Rokt avec ces mêmes étapes.
Un jeton d'accès est nécessaire pour appeler tout point de terminaison sur l'API d'événements Rokt. Les jetons d'accès permettent à Rokt d'identifier les applications clientes, le type de données auquel chaque application cliente accède, et d'empêcher les applications malveillantes d'accéder à des données auxquelles elles n'ont pas accès.
Génération de l'ID d'application et du secret d'application
Connectez-vous à One Platform.
Accédez à Paramètres de Profile sous votre icône de compte en bas à gauche.
Faites défiler vers le bas jusqu'à la section Générer des identifiants API personnels.
Entrez le nom de votre application.
Cliquez sur Générer.
Vos identifiants pour l'API d'événements et l'API de reporting seront générés immédiatement et ressembleront à quelque chose comme ceci :
AppId: "40svbin0d194subpohl079rhck"
AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"Conservez l'ID d'application et le secret d'application dans un endroit sécurisé. Vous n'aurez plus accès au secret d'application après cette session.
Vous pouvez utiliser ces identifiants immédiatement.
Vous devez garder les identifiants confidentiels afin de protéger votre compte et ils ne doivent jamais être envoyés par e-mail. Ne les partagez pas en dehors de votre organisation, même si une demande semble provenir de Rokt. Personne qui représente légitimement Rokt ne vous demandera jamais votre secret d'application.
Quand appeler
Appelez ce point de terminaison pour générer un jeton d'accès qui vous permet d'interagir avec l'API Événement pendant une heure. Si vous avez besoin de continuer à interagir avec l'API pendant plus d'une heure, appelez à nouveau ce point de terminaison pour obtenir un nouveau jeton d'accès.
Demande
Exemplar
curl -vX POST https://api.rokt.com/auth/oauth2/token \
-H 'Authorization: Basic ${AuthToken}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
Champs
| Clé | Dans | Description | Requis? | Exemple |
|---|---|---|---|---|
| Authorization | en-tête | app_id et app_secret doivent être passés dans l'en-tête d'autorisation via l'autorisation HTTP Basique et peuvent être générés sous Paramètres de Profil dans One Platform ; le contenu de l'en-tête est Basic base64encode(app_id:app_secret) | Oui | Basic base64encode(12345:abcde) |
| Content-Type | en-tête | Le type de média de la demande doit toujours être application/x-www-form-urlencoded | Oui | application/x-www-form-urlencoded |
| grant_type | corps | Doit être client_credentials | Oui | client_credentials |
Réponse
Exemple
{
"access_token":
"eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA"
"expires_in": 3600,
"token_type": "Bearer"
}
POST /v1/events
Demande
La demande est identique à tous égards à POST /v2/events, sauf pour l'en-tête, qui prend la forme suivante :
En-tête
| Nom | Valeur | Requis | Description |
|---|---|---|---|
Content-Type | application/json | Oui | N/A |
Charset | utf-8 | Oui | N/A |
Authorization | Bearer ${access-token} | Oui | Jeton d'accès récupéré à partir de l'endpoint /auth/oauth2/token |
Rokt-Version | 2020-05-21 | Oui | Version de l'API pour Rokt. Actuellement, la dernière version est 2020-05-21. Note : Laisser cet en-tête vide applique la dernière version, qui pourrait potentiellement être incompatible avec les versions précédentes. Une valeur invalide renverrait 400 mauvaise demande. |