Last updated 5 déc. 2024

Spécification de l'API des événements des partenaires V2

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 terminaison

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

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 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.

Demande

En-têtes d'autorisation

Veuillez travailler avec votre gestionnaire de compte pour obtenir les identifiants nécessaires pour interagir avec ce point de terminaison

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

En-têtes requis

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

Racine/Corps

Nom de la Propriété	Requis	TypeDeDonnée	Description
Événements	Oui	PartnerEvent[]	Une collection d'événements à envoyer à Rokt
Intégration	Oui	Integration	Données relatives à l'intégration effectuant la demande. Cela peut être obtenu à partir des bibliothèques UXHelper disponibles pour Android, iOS et web

Intégration

Nom de la Propriété	Requis	TypeDeDonnée	Description
Nom	Oui	chaîne	Indique le nom commun de l'intégration effectuant la demande
Version	Oui	chaîne	Version de l'intégration effectuant la demande
Cadre	Oui	chaîne	cadre d'intégration utilisé (par exemple, Flutter, React Native)
Plateforme	Oui	chaîne/énum	Plateforme partenaire demandant des offres (par exemple, Web, Mobile, iOS)
VersionSchémaMiseEnPage	Oui	chaîne	Version de schéma compatible la plus élevée pour l'intégration
LocaleAppareil	Oui	chaîne	Paramètre de langue du appareil de l'utilisateur
ModèleAppareil	Oui	chaîne	Modèle de l'appareil pour iOS ou Modèle de Build pour Android
TypeAppareil	Oui	chaîne	Type d'appareil/facteur de forme (par exemple, Téléphone, Tablette)
SystèmeD'exploitation	Oui	chaîne	Système d'exploitation de l'appareil de l'utilisateur
VersionSystèmeD'exploitation	Oui	chaîne	Version du système d'exploitation de l'appareil de l'utilisateur
NomPackage	Oui	chaîne	Nom du pack ou identifiant 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

PartenaireÉvénement

Nom de la propriété	Requis	TypeDonnées	Description
TypeÉvénement	Oui	string	Le nom de l'événement publié. Correspond à un eventType dans la section Types d'Événements.
TempsÉvénement	Oui	string	Le temps où l'événement a été créé sous `DateTimeOffset` (chaîne ISO avec GMT+0). Exemple : 2022-04-20T00:11:47.529Z
IdSession	Oui	string	L'ID de la session associée à l'événement. Récupéré à partir de la réponse `/experiences`, voir SuccessBody.
ParentGuid	Oui	string	L'instance GUID du parent lié. Voir Types d'Événements - Source du Parent GUID pour l'approvisionnement de ce champ.
PageInstanceGuid	Oui	string	Identifiant unique de la page/vue pour laquelle des offres ont été récupérées. Récupéré à partir 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).
DonnéesÉvénement	Non	string	Données supplémentaires requises pour l'événement.
Métadonnées	Non	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
Nom	Oui	string	Nom/Identifiant de la propriété fournie
Valeur	Oui	string	Données liées au Nom fourni

remarque

L'endpoint ne permet de traiter qu'un maximum de 25 événements à la fois
Tous les événements appartenant à la même demande doivent partager le même identifiant de session : sessionId
L'heure de l'événement par événement doit être :
- Pas daté dans le futur (marge de 5m)
- Pas plus de trois (3) jours dans le passé

Type d'événement

Type d'événement	Description
SignalImpression	Soulevé chaque fois qu'une mise en page, un créneau ou un contenu est rendu et visible pour le client. S'il y a un délai d'apparition impliqué, cela se produit lors de la révélation de la vue. Cela correspond à la métrique des impressions de mise en page dans le tableau de bord One Platform.
SignalViewed	Soulevé lorsqu'une mise en page est >= 50% visible dans le viewport pendant au moins une seconde.
SignalResponse	Soulevé lorsqu'un consommateur interagit avec une option de réponse sur un contenu.
SignalGatedResponse	Soulevé lorsqu'un consommateur interagit avec une option de réponse "Me rappeler plus tard" sur un contenu.
SignalInitialize	Élevé 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 durant le processus de rendu. Les partenaires peuvent écouter cet événement pour gérer les exceptions.

Exemple de Demande

Corps/Payload de la Demande JSON

Cliquez pour développer

{
    "integration": { ... Payload d'intégration standard ... },
    "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éponse

Réponse de succès (200)

Racine/Corps

Nom de la propriété	Type de données	Description
succès	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

UnprocessedEvent

Nom de la propriété	Type de données	Description
événement	PartnerEvent	Indique si les événements ont été reçus avec succès par Rokt
erreurs	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 de renvoyer une réponse mixte (HTTP 207), indiquant le nombre qui ont été acceptés et fournissant les événements qui ne l'étaient pas.

Cliquez pour développer

{
    "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 demande (4XX)

Racine/CORPS

Nom de la propriété	Type de données	Description
title	chaîne	Raison de l'échec au niveau supérieur
status	nombre	Code de statut HTTP
success	booléen	Indique si la demande a été réussie
errors	Error[]	Collection d'erreurs de validation survenues

Erreur de validation

{
    "title": "Échec de la validation",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "TropDÉvénements",
            "message": "Le nombre d'événements fournis dépasse la limite de 25"
        },
        {
            "code": "IntégrationNonFournie",
            "message": "L'intégration est requise"
        }
    ]
}

Requête d'Événements Vides

{
    "title": "Validation échouée",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "NoEventsProvided",
            "message": "Les événements ne peuvent pas être nuls ou vides"
        }
    ]
}

Requête 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 Propriété	TypeDeDonnées	Description
code	string	Code d'erreur correspondant
message	string	Message décrivant l'erreur

Erreurs Serveur Interne (HTTP 5xx)

Dans de rares circonstances, un système peut ne pas être en mesure de traiter une requête de manière inattendue. Dans ce cas, nous renverrons une requête sans corps avec un code d'état approprié qui respecte les codes de réponse HTTP standard. 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 cohérente, veuillez contacter le support (support@rokt.com) pour aider à identifier et corriger le problème.

Points de terminaison​

Meilleures pratiques de test​

Demande​

En-têtes d'autorisation​

En-têtes requis​

Racine/Corps​

Intégration​

PartenaireÉvénement​

NameValuePair​

Type d'événement​

Exemple de Demande​

Réponse​

Réponse de succès (200)​

Racine/Corps​

UnprocessedEvent​

Exemple​

Réponse de succès partiel (207)​

Réponse d'erreur de demande (4XX)​

Racine/CORPS​

Erreur de validation​

Requête d'Événements Vides​

Requête Corps Vide​

Erreur​

Erreurs Serveur Interne (HTTP 5xx)​

Points de terminaison

Meilleures pratiques de test

Demande

En-têtes d'autorisation

En-têtes requis

Racine/Corps

Intégration

PartenaireÉvénement

NameValuePair

Type d'événement

Exemple de Demande

Réponse

Réponse de succès (200)

Racine/Corps

UnprocessedEvent

Exemple

Réponse de succès partiel (207)

Réponse d'erreur de demande (4XX)

Racine/CORPS

Erreur de validation

Requête d'Événements Vides

Requête Corps Vide

Erreur

Erreurs Serveur Interne (HTTP 5xx)