API d'événement
Aperçu
L'API d'événement 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 email, montant de l'achat, BIN de carte de crédit).
Les partenaires de Rokt Ecommerce peuvent utiliser l'API d'événement conjointement avec le SDK Web pour la détection d'anomalies, aidant à détecter les incohérences dans le comportement de placement.
Les clients de Rokt Ads peuvent utiliser l'API d'événement pour intégrer les données de conversion avec Rokt, améliorant la performance et l'optimisation des campagnes.
Authentification
Contactez votre gestionnaire de compte Rokt pour créer une paire de clés publique et secrète pour les comptes avec lesquels 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 d'Événement 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 l'utilisation est flexible.
L'API d'Événement a deux principaux cas d'utilisation : détection d'anomalies (pour les partenaires) et rapport de conversion (pour les annonceurs).
POST /v2/events
Requête
En-tête
| Nom | Valeur | Obligatoire | 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. Actuellement, la dernière version est 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 entraînerait une 400 bad request. |
Authorization | Basic base64(rpub-...:rsec-...) | Oui | En-tête standard de l'authentification de base, la valeur d'identification étant un codage en base64 de rpub- et rsec- rejoint 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 | Obligatoire | Type | Description |
|---|---|---|---|---|---|
accountId | Oui | Chaîne; jusqu'à 64 caractères | Rokt Account ID | ||
events | Oui | Liste[EventObject]; jusqu'à 100 éléments par appel | Liste des événements à ingérer | ||
clientEventId | Oui | Chaîne; jusqu'à 36 caractères | Un identifiant utilisé pour identifier de manière unique un événement | ||
eventType | Oui | Chaîne; jusqu'à 128 caractères | Type de l'événement | ||
eventTime | Oui | Chaîne | L'heure de l'événement doit être en UTC et RFC 3339. La demande sera rejetée si elle contient un événement avec un horodatage de plus de 18 mois ou de plus de 5 minutes dans le futur à partir du moment où l'API d'événement le reçoit. Les événements dont les horodatages sont en dehors de cette plage ne sont pas traités. | ||
metaData | Non | Liste[metaData] | Fournit des informations non essentielles sur l'événement | ||
name | Oui | Chaîne; jusqu'à 256 caractères | Nom de champ; Le préfixe rokt. (insensible à la casse) est réservé à l'usage de Rokt uniquement | ||
value | Oui | Chaîne; jusqu'à 65536 caractères | Valeur du champ; pour une valeur binaire encoder avec Base64 | ||
objectData | Non | Liste[objectData] | Contient des détails contextuels de l'événement | ||
name | Oui | Chaîne; jusqu'à 256 caractères | Le préfixe rokt. (insensible à la casse) est réservé à l'usage de Rokt uniquement | ||
value | Oui | Chaîne; jusqu'à 65536 caractères | Valeur du champ; pour une valeur binaire encoder avec Base64 |
Champs standard objectData
Ci-dessous se trouve une liste des champs standard objectData qu'Adjust accepte via l'API d'événement. En fonction de votre cas d'utilisation, certains champs sont plus pertinents que d'autres. Voir détection d'anomalies ou rapport de conversion pour des exemples de charge utile spécifiques à votre cas d'utilisation.
Si vous souhaitez ajouter des champs de données supplémentaires ou utiliser un nom différent pour un champ particulier, informez votre gestionnaire de compte.
| Nom | Description | Valeur exemple |
|---|---|---|
email | Email passé en texte brut, en minuscules et sans espaces à la fin | john@email.com |
emailsha256 | Hash 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 associer les événements de conversion au clic d'origine. Nécessite une intégration séparée. | 1bc29b36f623ba82aaf6724fd3b16718 |
amount | Montant de la transaction (permet les points décimaux) | 100.25 |
currency | Code de la devise | USD |
quantity | La quantité (entier) d'article dans la conversion spécifique | 4 |
conversiontype | Utilisé pour différencier les différents événements de conversion. Remarque: Applicable 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 éléments par une virgule. | Maroon 5 t-shirt, Warriors vs. Raptors |
sku | L'identifiant du produit acheté (Remarque: Accepte uniquement un SKU) | 230847, tshirt-blue-39487, 398fhdnff |
paymenttype | La méthode de paiement utilisée pendant la transaction | VISA, American Express |
ccbin | BIN de carte de crédit du paiement convertissant | 123456 |
margin | Marge bénéficiaire de la conversion | 10 |
transactionid | ID de transaction, utilisé pour identifier une transaction unique. | ABC789 |
confirmationref | Référence de confirmation ID. Identifiant alternatif qui peut être utilisé pour identifier une transaction unique et/ou suivre les confirmations de commande. Remarque: 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, tout mettre en minuscules et supprimer tous les espaces de fin. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
lastname | Nom de famille du client | Smith |
lastnamesha256 | Hachage SHA-256 du nom de famille. Avant le hachage, tout mettre en minuscules et supprimer tous les espaces de fin. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
mobile | Numéro de téléphone portable du client convertissant | 3053211654, +1 (323) 867-5309 |
mobilesha256 | SHA-256 du numéro de mobile. Remarque: Le numéro de mobile doit être formaté dans ce format spécifique avant le hachage : 5551234567 (sans tirets ni espaces). | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
ipaddress | Adresse IP du client | 172.3.51.182 |
ipaddresssha256 | Hachage SHA-256 de l'adresse IP. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
useragent | User agent du navigateur du client convertissant | Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 |
DeviceType | Type de dispositif | 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 | Sexe 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 d'unité associé à l'adresse | Unit A |
address1 | Première ligne de l'adresse de rue | 123 Sesame St |
address2 | Deuxième ligne de l'adresse de rue (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, United States, AU, Australia |
value | Valeur du client | 19.98 |
predictedltv | Valeur à vie prédite du client | 500.0 |
Exemple
Ceci est un exemple d'appel à l'API des événements 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 demande, 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.
Exemple
L'exemple de code 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 un exemple de scénario d'erreur 200 ci-dessous. |
| 400 | RequestBodyReadError | Une erreur s'est produite 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 a échoué à nos vérifications de validation. Vérifiez que vous avez suivi correctement les exigences des paramètres. |
| 401 | UnauthorizedError | Jeton d'authentification non autorisé ou invalide. |
| 403 | Forbidden | 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 le retour exponentiel ou contactez votre équipe de support 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 de traitement par lots, une réponse 200 ne signifie pas nécessairement que toute la requête a été traitée correctement. Les développeurs doivent inspecter 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 é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 les 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 d'origine qui a échoué. |
{
"data": {
"unprocessedRecords": [
{
"error": {
"code": "ValidationError",
"message": "Invalid content"
},
"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)
Cela s'applique uniquement aux utilisateurs existants et aux utilisateurs intégrant des Customer Data Platforms (CDPs) spécifiques (notamment Census, Hightouch, mParticle, Segment, and Tealium). Les nouveaux utilisateurs de l'API Event et toutes les autres intégrations devraient utiliser le /v2/events pour une expérience d'authentification simplifiée.
L'API Event utilise l'approche OAuth 2.0 pour l'intégration du client. Voir Flux d'Identifiants OAuth 2.0 pour plus de détails. Vous avez besoin de votre ID d'application Rokt et de votre Secrets d'application pour accéder à l'API Event de 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 n'importe quel point de terminaison sur l'API Event de Rokt. Les jetons d'accès permettent à Rokt d'identifier les applications clientes, le type de données que chaque application cliente accède, et d'empêcher les applications malveillantes d'accéder aux 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 du profil sous l'icône de votre compte en bas à gauche.
Faites défiler 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 rapports seront générés immédiatement et ressembleront à ceci :
AppId: "40svbin0d194subpohl079rhck"
AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"Stockez l'ID de l'application et le secret d'application dans un endroit sécurisé. Vous n'aurez plus accès au secret de l'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 représentant 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 d'é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
Exemple
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 | header | app_id et app_secret doivent être transmis dans l'en-tête d'autorisation via l'autorisation HTTP de base et peuvent être générés sous Paramètres du profil dans One Platform ; le contenu de l'en-tête est Basic base64encode(app_id:app_secret) | Oui | Basic base64encocde(12345:abcde) |
| Content-Type | header | Le type de média de la demande doit toujours être application/x-www-form-urlencoded | Oui | application/x-www-form-urlencoded |
| grant_type | body | 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, à l'exception de l'en-tête, qui prend la forme suivante :
En-tête
| Nom | Valeur | Obligatoire | 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é depuis le point de terminaison /auth/oauth2/token |
Rokt-Version | 2020-05-21 | Oui | Version de l'API pour Rokt. Actuellement, la dernière version est 2020-05-21. Remarque : Laisser cet en-tête vide applique la dernière version, qui pourrait ne pas être rétrocompatible. Une valeur non valide entraînerait 400 bad request. |