Spécification de l'API des Événements 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`
Test	`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écialement 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 simuler efficacement des scénarios similaires à la production.

Requête

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	Requis	Description	Type	Remarque
rokt-pub-id	Oui	Contient l'identifiant public du client fourni	string	Ceci sera fourni par Rokt.
rokt-secret	Oui	Contient le secret public du client fourni qui doit correspondre à l'identifiant public	string	Ceci sera fourni par Rokt.

En-têtes requis

Clé de l'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	Rokt Tag ID	string	1234567890

Root/Body

Nom de la propriété	Obligatoire	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 demande. Cela peut être obtenu à partir des bibliothèques UXHelper disponibles pour Android, iOS et web

Integration

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	framework 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 du dispositif 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 du dispositif de l'utilisateur
OperatingSystemVersion	Oui	string	Version du système d'exploitation du dispositif 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

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 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 du partenaire pour le dépannage (par exemple, ID de session Uber).
EventData	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

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 5m)
- 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 layout, 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 Layout Impressions dans le tableau de bord One Platform.
SignalViewed	Déclenché lorsqu'un layout est visible à >= 50% dans la fenêtre d'affichage pendant au moins une seconde.
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 "Me rappeler 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ête

Corps/Payload de la Requête 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 réussie (200)

Racine/Corps

Nom de la propriété	Type de données	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 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 d'événements acceptés et fournissant les événements qui ne l'ont pas été.

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

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 Vides

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

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 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 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 constante, veuillez contacter le support (support@rokt.com) pour aider à identifier et corriger le problème.

Points de terminaison​

Meilleures Pratiques de Test​

Requête​

En-têtes d'autorisation​

En-têtes requis​

Root/Body​

Integration​

PartnerEvent​

NameValuePair​

Type d'événement​

Exemple de Requête​

Réponse​

Réponse réussie (200)​

Racine/Corps​

UnprocessedEvent​

Exemple​

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

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

Racine/Corps​

Erreur de validation​

Requête d'Événements Vides​

Requête avec Corps Vide​

Erreur​

Erreurs Internes du Serveur (HTTP 5xx)​

Points de terminaison

Meilleures Pratiques de Test

Requête

En-têtes d'autorisation

En-têtes requis

Root/Body

Integration

PartnerEvent

NameValuePair

Type d'événement

Exemple de Requête

Réponse

Réponse réussie (200)

Racine/Corps

UnprocessedEvent

Exemple

Réponse de succès partiel (207)

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

Racine/Corps

Erreur de validation

Requête d'Événements Vides

Requête avec Corps Vide

Erreur

Erreurs Internes du Serveur (HTTP 5xx)