Spécification de l'API des événements serveur

Ce document décrit les points de terminaison (endpoints) pertinents nécessaires pour interagir avec les API de Rokt afin de soumettre des événements à Rokt.

Veuillez travailler avec votre gestionnaire de compte pour obtenir les informations d'identification nécessaires pour interagir avec ce point de terminaison

Points de terminaison

Environnement	Action	URL
Production	POST	https://server-api.rokt.com/v1/partner/events
Test	POST	https://server-api-demo.rokt.com/v1/partner/events

Meilleures pratiques de test

Le point de terminaison de test https://server-api-demo.rokt.com/v1/partner/events est spécifiquement conçu pour les tests et doit être utilisé pour valider l'intégration sans affecter les données ou les performances de production. Assurez-vous que les en-têtes (headers) appropriés et les formats de requête sont utilisés comme spécifié dans la documentation de l'API pour simuler efficacement des scénarios similaires à ceux de la production.

Requête

En-têtes d'autorisation

Clé de l'en-tête	Description	Type	Remarque
rokt-pub-id	Contient l'identifiant public client fourni	string	Cela sera fourni par Rokt.
rokt-secret	Contient le secret public client fourni qui doit correspondre à l'identifiant public	string	Cela sera fourni par Rokt.

En-têtes requis

Clé de l'en-tête	Description	Type	Exemple
content-type	Type de média	string	“application/json”
accept	Type de média attendu de la réponse	string	“application/json”
rokt-tag-id	ID de Tag Rokt	string	1234567890

Racine/Corps

Nom de la propriété	Requis	Type de données	Description
events	Oui	PartnerEvent[]	Une collection d'événements à envoyer à Rokt

PartnerEvent

Nom de la propriété	Requis	Type de données	Description
eventType	Oui	string	Le nom de l'événement publié. Correspond à un EventType dans la section Type d'événement.
eventTime	Oui	string	L'heure à laquelle l'événement a été créé en tant que DateTimeOffset (chaîne ISO avec GMT+0) par exemple : 2022-04-20T00:11:47.529Z
sessionId	Oui	string	L'ID de la session à laquelle l'événement est associé. Récupéré de la réponse /offers, voir Champs clés
parentGuid	Oui	string	Le GUID de l'instance du parent lié. Voir Types d'événements - Source du GUID parent pour savoir où trouver ce champ.
clientUniqueId	Oui	string	Un identifiant pour lier la session Rokt avec la session du partenaire pour le dépannage : <Transaction ID>
metadata	Optionnel	NameValuePair[]	Collection de métadonnées supplémentaires liées à l'événement

NameValuePair

Nom de la propriété	Requis	Type de données	Description
Name	Oui	string	Nom/Identifiant de la propriété fournie
Value	Oui	string	Données liées au Nom fourni

remarque

• La création de instanceGuid de l'événement sera désormais gérée par les API Rokt
• Les métadonnées communes seront ajoutées par les API Rokt
• Le point de terminaison ne permet de traiter qu'un maximum de 25 événements à la fois
• Tous les événements appartenant à la même requête doivent partager le même identifiant de session : sessionId
• L'heure de l'événement pour chaque événement doit être :
  • Pas datée dans le futur (5 minutes de marge)
  • Pas plus de trois (3) jours dans le passé

Type d'événement

Type d'événement	Description
SignalImpression	Déclenché chaque fois qu'un emplacement (placement), un slot ou une création (creative) est rendu et visible pour le client. S'il y a un délai d'apparition, cela se produit lors de l'affichage de la vue. Cela correspond à la métrique des Impressions de placement dans le tableau de bord One Platform. Requis pour chaque placementGuid/slotGuid/creativeGuid.
SignalViewed	Déclenché lorsqu'un emplacement est visible à >= 50% dans la fenêtre d'affichage pendant au moins une seconde. Requis pour chaque creativeGuid.
SignalResponse	Déclenché lorsqu'un consommateur interagit avec une option de réponse sur une création. Requis pour chaque responseOptionGuid.

remarque

Les slotGuid, creativeGuid, placementGuid et responseOptionGuid à utiliser dans le champ parentGuid peuvent être trouvés dans la réponse de l'API Offers.

Exemple de requête

Corps/Payload de la requête JSON

{
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394", // Cela devrait être un slotGuid, creativeGuid, ou placementGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionSlot"
                }
            ]
        },
        {
            "eventType": "SignalViewed",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd", // Cela devrait être un creativeGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionCreative"
                }
            ]
        },
        {
            "eventType": "SignalResponse",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863", // Cela devrait être un responseOptionGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "experienceId",
                    "value": "RedButton"
                }
            ]
        }
    ]
}'

Réponse

Réponse de succès (200)

Racine/Corps

Nom de la propriété	Type de données	Description
success	boolean	Indique si les événements ont été reçus avec succès par Rokt
processedEventsCount	number/int	Indique le nombre d'événements qui ont été acceptés avec succès par Rokt
unprocessedEvents	UnprocessedEvent[]	Collection d'événements qui n'ont pas été acceptés avec des descriptions d'erreurs par événement

UnprocessedEvent

Nom de la propriété	Type de données	Description
event	PartnerEvent	Indique si les événements ont été reçus avec succès par Rokt
errors	Error[]	Indique le nombre d'événements qui ont été acceptés avec succès par Rokt

Exemple

{ 
    "processedEventsCount": 5, 
    "unprocessedEvents": [], 
    "success": true }

Réponse de Succès Partiel (207)

Dans le cas où des événements valides sont envoyés avec des événements invalides, Rokt tentera tout de même de traiter les événements valides et renverra un statut de réponse mixte (HTTP 207), indiquant le nombre d'événements acceptés et fournissant les événements qui ne l'ont pas été.

{
    "processedEventsCount": 5,
    "unprocessedEvents": [
        {
            "errors": [
                {
                    "code": "InvalidEventType",
                    "message": "Le type d'événement est invalide"
                },
                {
                    "code": "SessionIdMissing",
                    "message": "SessionId est manquant ou invalide"
                },
                {
                    "code": "ParentGuidIsMissing",
                    "message": "ParentGuid est nul ou vide"
                },
                {
                    "code": "EventTimeIsMissing",
                    "message": "EventTime est nul ou par défaut"
                }
            ],
            "event": {
                "eventType": "Unknown",
                "sessionId": "",
                "eventTime": "0001-01-01T00:00:00+00:00",
                "parentGuid": "",
                "clientUniqueId": "265d3a90-4c84-4c17-99af-e09b862b925c"
            }
        }
    ],
    "success": false
}

Réponse d'erreur de requête (4XX)

Racine/Corps

Nom de la propriété	Type de données	Description
title	string	Raison principale de l'échec
status	number	Code de statut HTTP
success	boolean	Indique si la requête a réussi
errors	Error[]	Collection d'erreurs de validation qui se sont produites

Erreur de validation

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "TooManyEvents",
            "message": "The number of events provided exceeds the limit 25"
        }
    ]
}

Requête d'événements vide

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "NoEventsProvided",
            "message": "Events cannot be null or empty"
        }
    ]
}

Requête avec Corps Vide

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "Le format du corps de la requête n'est pas valide"
        }
    ]
}

Erreur

Nom de la Propriété	Type de Donnée	Description
code	string	Code d'erreur correspondant
message	string	Message décrivant l'erreur

Erreurs Serveur Internes (HTTP 5xx)

Dans de rares circonstances, un système peut ne pas être en mesure de compléter une requête de manière inattendue. Dans ce cas, nous retournerons une requête sans corps avec un code de statut approprié qui respecte les codes de réponse HTTP standards. Dans le cas où cette réponse se produit, nous recommandons de réessayer la requête après un court délai (1-2 secondes). Si le problème persiste ou se produit de manière constante, veuillez contacter le support (support@rokt.com) pour aider à identifier et corriger le problème.