Spécification de l'API des événements de session (S2S)

Ce document décrit le point de terminaison nécessaire pour soumettre des Événements à Rokt en utilisant l'API de Session (v2).

Travaillez avec votre équipe de compte Rokt pour obtenir les identifiants nécessaires. Pour un guide d'intégration de bout en bout, voir Intégration de l'API de Session (S2S).

Point de terminaison

Environnement	Action	URL
Production	POST	https://api.rokt.com/v2/sessions/events

remarque

Il n'y a pas d'URL de bac à sable séparée. Pour valider avant de passer en production, envoyez l'en-tête rokt-test-session: true sur le même point de terminaison. Les sessions de test sont étiquetées et filtrées hors des métriques de production. L'en-tête marque uniquement le rapport — il ne force pas une offre à être servie. Retirez l'en-tête pour passer en production.

Requête

En-têtes d'autorisation

En-tête	Description	Type	Remarque
Authorization	Identifiants d'authentification de base	chaîne	Basic base64(rpub:rsec) — la même paire de clés API publique/secrète utilisée pour l'appel des Offres.
rokt-account-id	Votre ID de compte Rokt	chaîne	Requis à chaque appel.

En-têtes requis

En-tête	Description	Type	Exemple
Content-Type	Type de média	chaîne	application/json

Racine/Corps

Propriété	Requis	Type	Description
channel	Oui	objet	Doit contenir "type": "s2s".
single_session	Oui	booléen	Défini sur true. Lie chaque événement de la requête à la session identifiée par session_id de chaque événement.
events	Oui	Event[]	Collection d'événements à envoyer à Rokt.

Événement

Propriété	Requis	Type	Description
event_type	Oui	chaîne	Le type d'événement. Voir Types d'événements.
instance_id	Oui	chaîne (UUID)	UUID généré par le client identifiant cet événement, utilisé pour la déduplication.
session_id	Oui	chaîne	Le session_id de niveau supérieur retourné par l'appel des offres.
timestamp	Oui	nombre	Millisecondes de l'époque Unix auxquelles l'événement s'est produit.
data	Oui	objet	Voir Données de l'événement.

Données d'événement

Propriété	Requis	Type	Description
parent_id	Oui	chaîne	Le instance_guid de l'élément auquel cet événement se rapporte, pris de la réponse des offres (par exemple, le instance_guid du créatif pour une impression ; le instance_guid d'une option de réponse pour une réponse). Construit l'arborescence de session. Répétez la valeur de la réponse des offres telle quelle — elle peut contenir un préfixe de type (par exemple, ad:<uuid>); envoyez-la exactement comme retournée.
page_instance_guid	Oui	chaîne	Le page_instance_guid de la réponse des offres.
token	Oui	chaîne	Le jeton d'événement pour cet élément de la réponse des offres.
capture_method	Non	chaîne	Comment l'événement a été capturé (par exemple, ClientProvided).

remarque

Authentifiez-vous avec les mêmes identifiants Basic rpub:rsec que l'appel d'offres, et identifiez la session avec single_session: true plus un session_id par événement (le session_id de niveau supérieur de la réponse des offres).

Types d'événements

Événement	event_type	Description
Impression	impression	Déclenché lorsqu'un emplacement, un slot ou un créatif est rendu et visible pour le client. S'il y a un délai d'apparition, cela se produit lors du démasquage de la vue. Requis pour chaque élément qui se rend visible.
Vu	viewed	Déclenché lorsqu'un emplacement est ≥50% visible dans la fenêtre d'affichage pendant au moins une seconde continue. Correspond à la définition de visibilité IAB et doit exclure le trafic de bots/invalides. Requis pour chaque créatif qui devient visible.
Réponse	signal_response	Déclenché lorsqu'un client interagit avec une option de réponse. Requis pour chaque interaction avec une option de réponse.
Rejet	dismissal	Déclenché lorsqu'un client rejette une offre.
Conversion	conversion_signal	Déclenché lorsqu'une conversion se produit.
Achat	purchase	Déclenché lorsqu'un achat est complété.

Exemple de requête

POST https://api.rokt.com/v2/sessions/events
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
Content-Type: application/json

{
  "channel": { "type": "s2s" },
  "single_session": true,
  "events": [
    {
      "event_type": "impression",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ab",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234567000,
      "data": {
        "parent_id": "018f2a1b-3333-7abc-8def-creative001",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>",
        "capture_method": "ClientProvided"
      }
    },
    {
      "event_type": "viewed",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ac",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234568000,
      "data": {
        "parent_id": "018f2a1b-3333-7abc-8def-creative001",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>"
      }
    },
    {
      "event_type": "signal_response",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ad",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234572000,
      "data": {
        "parent_id": "018f2a1b-4444-7abc-8def-responseoption01",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>"
      }
    }
  ]
}

Réponse

Réponse de succès (202 Accepté)

Un appel réussi retourne 202 Accepted avec un jeton de session rafraîchi à utiliser pour les appels suivants, plus les résultats par événement.

Propriété	Type	Description
session_token	objet	Jeton de session rafraîchi (session_token.token) pour le prochain appel.
event_ids	chaîne[]	IDs attribués aux événements acceptés, dans l'ordre de la requête.
errors	objet[]	Erreurs par événement, chacune contenant index, code, et message. Vide lorsque chaque événement est accepté.
warnings	objet[]	Avertissements par événement, même forme index/code/message. Vide lorsqu'il n'y en a pas.

Lorsque chaque événement est accepté, errors et warnings sont vides et event_ids a une entrée par événement soumis :

{
  "session_token": {
    "token": "<session_token>"
  },
  "event_ids": [
    "018f9c40-1a2b-7abc-8def-eventimpression",
    "018f9c40-1a2b-7abc-8def-eventviewed0001",
    "018f9c40-1a2b-7abc-8def-eventresponse01"
  ],
  "errors": [],
  "warnings": []
}

En cas d'échec partiel, l'appel retourne toujours 202; les événements acceptés apparaissent dans event_ids et chaque événement rejeté est signalé dans errors par son index dans le tableau de requête :

{
  "session_token": {
    "token": "<session_token>"
  },
  "event_ids": [
    "018f9c40-1a2b-7abc-8def-eventimpression",
    "018f9c40-1a2b-7abc-8def-eventviewed0001"
  ],
  "errors": [
    {
      "index": 2,
      "code": "invalid_token",
      "message": "token does not match the element identified by parent_id"
    }
  ],
  "warnings": []
}

Réponses d'erreur (4xx / 5xx)

Les erreurs renvoient un statut HTTP sémantique avec un corps structuré :

{
  "error": "<code>",
  "message": "<detail>"
}

Codes d'erreur communs

Statut HTTP	Signification
400	Corps de la requête mal formé.
401	En-tête Authorization manquant ou invalide.
422	Validation de la requête échouée.
429	Limitation de débit. Ne pas réessayer automatiquement — faites une pause et contactez votre représentant Rokt si les erreurs 429 persistent.
5xx	Erreur serveur inattendue. Réessayez après un court délai (1–2 secondes). Si le problème persiste, contactez support@rokt.com.