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

Ce document décrit les points de terminaison 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 identifiants 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 appropriés et les formats de requête sont utilisés comme spécifié dans la documentation de l'API pour émuler efficacement des scénarios similaires à la production.

Requête

En-têtes d'autorisation

Clé d'en-tête	Description	Type	Remarque
rokt-pub-id	Contient l'identifiant public client fourni	chaîne	Ceci sera fourni par Rokt.
rokt-secret	Contient le secret public client fourni qui doit correspondre à l'identifiant public	chaîne	Ceci sera fourni par Rokt.

En-têtes requis

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

Racine/Corps

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

PartnerEvent

Nom de propriété	Requis	Type de données	Description
eventType	Oui	chaîne	Le nom de l'événement publié. Correspond à un EventType dans la section Type d'événement.
eventTime	Oui	chaîne	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	chaîne	L'ID de la session à laquelle l'événement est associé. Récupéré d'une réponse au point de terminaison /v1/partner/offers dans l'API des offres.
parentGuid	Oui	chaîne	Le GUID de l'instance du parent lié. Récupéré d'une réponse au point de terminaison /v1/partner/offers dans l'API des offres.
clientUniqueId	Oui	chaîne	Un identifiant pour lier la session Rokt avec la session 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é	Obligatoire	Type de données	Description
Nom	Oui	string	Nom/Identifiant de la propriété fournie
Valeur	Oui	string	Données relatives au Nom fourni

remarque

• La création d'événements instanceGuid 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 permet de traiter 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 par événement doit être :
  • Pas datée dans le futur (marge de 5 minutes)
  • 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, un slot ou une création est rendu et visible pour le client. S'il y a un délai d'apparition, cela se produit lors de l'affichage. 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 >= 50% visible dans la fenêtre d'affichage pendant au moins une seconde continue. Cela correspond à la définition de visibilité définie par le Bureau de la publicité interactive (IAB) et doit également exclure le trafic non humain (bot), les impressions frauduleuses ou toute forme d'activité invalide. 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

Le slotGuid, creativeGuid, placementGuid et responseOptionGuid à utiliser dans le champ parentGuid peuvent être trouvés dans la réponse API des Offres.

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", // This should be a slotGuid, creativeGuid, or 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", // This should be a 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", // This should be a 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
succès	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 toujours de traiter les événements valides et renverra un statut de réponse mixte (HTTP 207), indiquant le nombre qui ont été acceptés et fournissant les événements qui ne l'ont pas été.

{
    "processedEventsCount": 5,
    "unprocessedEvents": [
        {
            "errors": [
                {
                    "code": "InvalidEventType",
                    "message": "Event type is invalid"
                },
                {
                    "code": "SessionIdMissing",
                    "message": "SessionId is missing or invalid"
                },
                {
                    "code": "ParentGuidIsMissing",
                    "message": "ParentGuid is null or empty"
                },
                {
                    "code": "EventTimeIsMissing",
                    "message": "EventTime is null or default"
                }
            ],
            "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 vides

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

Requête de corps vide

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "Request body format is not valid"
        }
    ]
}

Erreur

Nom de la propriété	Type de données	Description
code	string	Code d'erreur correspondant
message	string	Message décrivant l'erreur

Erreurs internes du serveur (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 standard. Dans le cas où cette réponse se produit, nous recommandons que la requête soit réessayée 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.