V2 Partner Events API Specification

Ce document décrit le point de terminaison pertinent nécessaire pour interagir avec l'API de Rokt afin de soumettre des Événements à Rokt.

Points de terminaisonLien direct vers Points de terminaison

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

Meilleures pratiques de testLien direct vers Meilleures pratiques de test

Le point de terminaison de test https://server-api-demo.rokt.com/v2/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 la performance de production. Assurez-vous d'utiliser les en-têtes et formats de requête appropriés comme spécifié dans la documentation de l'API pour émuler efficacement des scénarios similaires à la production.

RequêteLien direct vers Requête

En-têtes d'autorisationLien direct vers En-têtes d'autorisation

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

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

En-têtes requisLien direct vers En-têtes requis

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

Racine/CorpsLien direct vers Racine/Corps

Nom de la propriété	Requis	Type de données	Description
Events	Oui	PartnerEvent[]	Une collection d'événements à envoyer à Rokt
Integration	Oui	Integration	Données relatives à l'intégration effectuant la requête. Cela peut être obtenu à partir des bibliothèques UXHelper disponibles pour Android, iOS et web

IntégrationLien direct vers Intégration

Nom de la propriété	Obligatoire	Type de données	Description
Name	Oui	string	Indique le nom commun de l'intégration effectuant la demande
Version	Oui	string	Version de l'intégration effectuant la demande
Framework	Oui	string	Cadre d'intégration utilisé (par exemple, Flutter, React Native)
Platform	Oui	string/enum	Plateforme partenaire demandant des offres (par exemple, Web, Mobile, iOS)
LayoutSchemaVersion	Oui	string	Version de schéma compatible la plus élevée pour l'intégration
DeviceLocale	Oui	string	Paramètre régional de l'appareil de l'utilisateur
DeviceModel	Oui	string	Modèle de l'appareil pour iOS ou modèle de construction pour Android
DeviceType	Oui	string	Type d'appareil/facteur de forme (par exemple, Téléphone, Tablette)
OperatingSystem	Oui	string	Système d'exploitation de l'appareil de l'utilisateur
OperatingSystemVersion	Oui	string	Version du système d'exploitation de l'appareil de l'utilisateur
PackageName	Oui	string	Nom du package ou identifiant du bundle de l'application hôte
PackageVersion	Oui	string	Version du package ou version du bundle de l'application hôte
Metadata	Non	Map<string, string>	Données supplémentaires liées à l'intégration ou à l'appareil

ÉvénementPartenaireLien direct vers ÉvénementPartenaire

Nom de la propriété	Obligatoire	Type de données	Description
EventType	Oui	string	Le nom de l'événement publié. Correspond à un eventType dans la section Types d'événements.
EventTime	Oui	string	L'heure à laquelle l'événement a été créé en tant que `DateTimeOffset` (chaîne ISO avec GMT+0). Exemple : 2022-04-20T00:11:47.529Z
SessionId	Oui	string	L'ID de la session associée à l'événement. Récupéré de la réponse `/experiences`, voir SuccessBody.
ParentGuid	Oui	string	Le GUID de l'instance du parent lié. Voir Types d'événements - Source du GUID Parent pour l'origine de ce champ.
PageInstanceGuid	Oui	string	Identifiant unique de la page/vue pour laquelle les offres ont été récupérées. Récupéré de la réponse `/experiences`, voir PageContext.
ClientUniqueId	Non	string	Un identifiant pour lier la session Rokt avec la session partenaire pour le dépannage (par exemple, ID de session Uber).
EventData	Non	string	Données supplémentaires requises pour l'événement.
Metadata	Non	NameValuePair[]	Collection de métadonnées supplémentaires liées à l'événement.

NameValuePairLien direct vers NameValuePair

Nom de la propriété	Obligatoire	Type de données	Description
Nom	Oui	chaîne	Nom/Identifiant de la propriété fournie
Valeur	Oui	chaîne	Données liées au Nom fourni

remarque

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
EventTime par événement doit être :
- Pas daté dans le futur (marge de 5 minutes)
- Pas plus de trois (3) jours dans le passé

Type d'événementLien direct vers Type d'événement

Type d'événement	Description
SignalImpression	Déclenché chaque fois qu'une mise en page, un emplacement 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 de la vue. Cela correspond à la métrique des impressions de mise en page dans le tableau de bord One Platform.
SignalViewed	Déclenché lorsqu'une mise en page est visible à >= 50% 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.
SignalResponse	Déclenché lorsqu'un consommateur interagit avec une option de réponse sur une création.
SignalGatedResponse	Déclenché lorsqu'un consommateur interagit avec une option de réponse "Rappelle-moi plus tard" sur une création.
SignalInitialize	Déclenché lorsque la bibliothèque tente d'afficher la mise en page
SignalDismissal	Déclenché lorsque le client ferme ou rejette la mise en page.
SignalActivation	Déclenché lorsque le client interagit avec une mise en page.
SignalSdkDiagnostic	Déclenché lorsqu'une erreur se produit au sein de la mise en page Rokt ou pendant le processus de rendu. Les partenaires peuvent écouter cet événement pour gérer les exceptions.

Exemple de RequêteLien direct vers Exemple de Requête

Corps/Payload de la Requête JSON

Cliquez pour développer

{
    "integration": { ... Standard integration payload ... },
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.710Z",
            "parentGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2"
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f"
        },
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionSlot"
                }
            ]
        },
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionCreative"
                }
            ]
        },
        {
            "eventType": "SignalResponse",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "experienceId",
                    "value": "RedButton"
                }
            ]
        }
    ]
}

RéponseLien direct vers Réponse

Réponse de Succès (200)Lien direct vers Réponse de Succès (200)

Racine/CorpsLien direct vers Racine/Corps

Nom de la Propriété	Type de Donnée	Description
success	booléen	Indique si les événements ont été reçus avec succès par Rokt
processedEventsCount	nombre/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 les descriptions des erreurs par événement

UnprocessedEventLien direct vers UnprocessedEvent

Nom de la Propriété	Type de Donnée	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

ExempleLien direct vers Exemple

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

Réponse de Succès Partiel (207)Lien direct vers 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é.

Cliquez pour développer

{
    "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)Lien direct vers Réponse d'Erreur de Requête (4XX)

Racine/CorpsLien direct vers Racine/Corps

Nom de la Propriété	Type de Donnée	Description
title	chaîne	Raison principale de l'échec
status	nombre	Code de statut HTTP
success	booléen	Indique si la requête a été réussie
errors	Error[]	Collection d'erreurs de validation qui se sont produites

Erreur de ValidationLien direct vers Erreur de Validation

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

Requête d'Événements VideLien direct vers 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 VideLien direct vers Requête avec Corps Vide

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

ErreurLien direct vers 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 Interne du Serveur (HTTP 5xx)Lien direct vers Erreurs Interne du Serveur (HTTP 5xx)

Dans de rares circonstances, un système peut être incapable 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 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.