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 toutes les attributs associés (par exemple, adresse e-mail, montant de l'achat, BIN de la carte de crédit).
Les partenaires de Rokt Ecommerce peuvent utiliser l'API d'événement en conjonction avec le SDK Web pour la détection d'anomalies, ce qui permet de 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 ainsi les performances et l'optimisation des campagnes.
Authentification
L'API d'événement utilise l'approche OAuth 2.0 pour l'intégration client. Consultez 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énement Rokt.
Vous pouvez générer des informations d'identification pour l'API de reporting Rokt avec les mêmes étapes.
Un jeton d'accès est nécessaire pour appeler n'importe quel point de terminaison de l'API d'événement 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 du profil en cliquant sur l'icône de votre compte en bas à gauche.
Faites défiler jusqu'à la section Générer des identifiants d'API personnels.
Entrez le nom de votre application.
Cliquez sur Générer.
Vos identifiants pour l'API d'événement et l'API de rapport seront générés immédiatement et ressembleront à ceci :
AppId: "40svbin0d194subpohl079rhck"
AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"Stockez 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 ne jamais les envoyer 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 cet endpoint pour générer un jeton d'accès qui vous permet d'interagir avec l'API Event pendant une heure. Si vous avez besoin de continuer à interagir avec l'API pendant plus d'une heure, appelez à nouveau cet endpoint pour obtenir un nouveau jeton d'accès.
Requête
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 | Obligatoire? | 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 dans 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 requête 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"
}
Point de terminaison de l'API
POST Événements
L'API Événements permet aux clients d'intégrer un ou plusieurs événements avec la plateforme Rokt. Les événements font généralement référence à des événements de conversion ou de transaction, mais leur utilisation est flexible.
L'API Événements a deux cas d'utilisation principaux : détection d'anomalies (pour les partenaires) et rapports de conversion (pour les annonceurs).
POST /v1/events
Requête
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 du point de terminaison /auth/oauth2/token |
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, qui pourrait potentiellement être incompatible avec les versions antérieures. Une valeur invalide entraînerait une 400 bad request. |
Idempotency-Key | ${uuid-v4} | Oui | Identifiant unique du client utilisé pour permettre la répétition sécurisée des événements. Les demandes ultérieures avec la même idempotency-key entraîneraient une HTTP 409. Les clés peuvent être purgées après trois heures. Une nouvelle demande sera acceptée si la même clé est réutilisée après son expiration. |
Paramètres
La requête contient des événements et des détails associés au format JSON.
| Niveau 1 | Niveau 2 | Niveau 3 | Requis | Type | Description |
|---|---|---|---|---|---|
accountId | Oui | Chaîne de caractères ; jusqu'à 64 caractères | ID de compte Rokt | ||
events | Oui | Liste[ObjetÉvénement] ; jusqu'à 100 éléments par appel | Liste des événements à ingérer | ||
clientEventId | Oui | Chaîne de caractères ; jusqu'à 36 caractères | Un identifiant utilisé pour identifier de manière unique un événement | ||
eventType | Oui | Chaîne de caractères ; jusqu'à 128 caractères | Type d'événement | ||
eventTime | Oui | Chaîne de caractères | L'heure de l'événement doit être en UTC et au format RFC 3339. La requête sera rejetée si elle contient un événement avec une horodatage antérieur de plus de 18 mois ou de plus de 5 minutes dans le futur par rapport à l'heure à laquelle l'API d'événement le reçoit. Les événements avec des horodatages en dehors de cette plage ne sont pas traités. | ||
metaData | Non | Liste[métaDonnées] | Fournit des informations non critiques sur l'événement | ||
name | Oui | Chaîne de caractères ; jusqu'à 256 caractères | Nom du champ ; Le préfixe rokt. (insensible à la casse) est réservé à l'usage de Rokt uniquement | ||
value | Oui | Chaîne de caractères ; jusqu'à 65536 caractères | Valeur du champ ; pour une valeur binaire, encodez avec Base64 | ||
objectData | Non | Liste[donnéesObjet] | Contient des détails contextuels de l'événement | ||
name | Oui | Chaîne de caractères ; jusqu'à 256 caractères | Le préfixe rokt. (insensible à la casse) est réservé à l'usage de Rokt uniquement | ||
value | Oui | Chaîne de caractères ; jusqu'à 65536 caractères | Valeur du champ ; pour une valeur binaire, encodez avec Base64 |
Champs objectData standard
Ci-dessous se trouve une liste des champs objectData standard que Rokt accepte via l'API d'événements. Selon votre cas d'utilisation, certains champs sont plus pertinents que d'autres. Consultez la détection d'anomalies ou les rapports de conversion pour des exemples spécifiques de charge utile basés sur 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-en votre gestionnaire de compte.
| Nom | Description | Valeur d'exemple |
|---|---|---|
email | Adresse e-mail transmise en texte brut, en minuscules et sans espaces superflus | john@email.com |
emailsha256 | Hash SHA-256 de l'adresse e-mail. Avant le hachage, en minuscules et sans espaces superflus. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
passbackconversiontrackingid | Identifiant 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 devise | USD |
quantity | La quantité (entier) de l'article dans la conversion spécifique | 4 |
conversiontype | Utilisé pour différencier entre 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/des produit(s) acheté(s). Vous pouvez séparer plusieurs articles par une virgule. | T-shirt Maroon 5, Warriors vs. Raptors |
sku | L'identifiant du produit acheté (Remarque : n'accepte qu'un seul SKU) | 230847, tshirt-bleu-39487, 398fhdnff |
paymenttype | La méthode de paiement utilisée lors de la transaction | VISA, American Express |
ccbin | BIN de la carte de crédit du paiement converti | 123456 |
margin | Marge bénéficiaire de la conversion | 10 |
transactionid | Identifiant de transaction, utilisé pour identifier une transaction unique. Remarque: Si fourni, Rokt utilise cet identifiant pour dédupliquer les événements de conversion sur différents canaux. | ABC789 |
confirmationref | Identifiant de référence de confirmation. Identifiant alternatif pouvant ê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 et transactionid n'est pas disponible. | XYZ123 |
firstname | Prénom du client | John |
firstnamesha256 | Hash 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 | Hash 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 convertissant | 3053211654, +1 (323) 867-5309 |
mobilesha256 | SHA-256 du numéro de téléphone mobile. Remarque: Le numéro de téléphone mobile doit être formaté selon ce format spécifique avant le hachage : 5551234567 (sans tirets ni espaces). | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
ipaddress | Adresse IP du client | 172.3.51.182 |
ipaddresssha256 | Hash SHA-256 de l'adresse IP. | fab1e2e699b3b927cbf875046a64f2225df02d5cb306f3857424c2bbb87be61f |
useragent | Navigateur de l'utilisateur convertissant | Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 |
DeviceType | Type de l'appareil | Ordinateur de bureau, Mobile, Tablette |
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 | Monsieur, Madame, Mademoiselle |
gender | Genre du client | M, Masculin, F, Féminin |
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 |
Exemple
Il s'agit d'un appel d'API d'événement d'exemple avec une charge utile JSON contenant deux événements de réservation.
POST /v1/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 des événements renvoient un statut 200. L'objet unprocessedRecords devrait être vide, ce qui indique 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 des événements.
{
"data": {
"unprocessedRecords": []
}
}
Lorsque vous validez une réponse 200, assurez-vous qu'il n'y a pas d'événements renvoyés dans unprocessedRecords. S'il y a des enregistrements dans unprocessedRecords, un ou plusieurs de vos événements n'ont peut-être pas été traités correctement.
Réponses
| Code de réponse HTTP | Code d'erreur | Description |
|---|---|---|
| 200 | N/A | Généralement OK, mais voir l'exemple d'un 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énement 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 un délai d'attente 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
Le code HTTP 200 indique généralement un appel réussi. Cependant, étant donné que l'API Event est une API de lot, une réponse 200 ne signifie pas nécessairement que la requête entière 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 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 | Champ contenant l'enregistrement d'origine 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"
}
]
}
}
]
}
}