Aller au contenu principal

Intégration de l'API Session (S2S)

Intégrez avec le serveur à serveur de Rokt en utilisant l'API Session (v2) unifiée — les mêmes /v2/sessions/* points de terminaison qui alimentent les SDKs de Rokt. Votre serveur appelle Rokt pour récupérer une offre, la rend, et rapporte les événements d'engagement et de conversion.

Travaillez avec votre équipe de compte Rokt pour obtenir des identifiants.

Points de terminaisonLien direct vers Points de terminaison

ObjectifMéthodeURL
Obtenir des offresPOSThttps://api.rokt.com/v2/sessions/offers
Rapporter des événementsPOSThttps://api.rokt.com/v2/sessions/events

Pour la référence complète des requêtes/réponses pour chaque point de terminaison, consultez la spécification de l'API Offers et la spécification de l'API Events.

Le trafic serveur à serveur est classé par défaut comme Web. Si vos pages Rokt sont configurées pour une plateforme native (iOS ou Android), définissez l'en-tête rokt-platform-type sur cette plateforme pour chaque appel d'offres — sinon la requête est traitée comme Web, vos pages configurées pour le natif ne correspondront pas, et la détection de page ne renverra aucune offre. Les pages configurées pour le Web n'ont pas besoin d'en-tête. Les valeurs acceptées sont iOS, Android, Web, WebDesktop, et WebMobile (insensible à la casse); tout autre valeur revient à Web.

remarque

Pour valider avant de passer en production, envoyez l'en-tête rokt-test-session: true sur les mêmes points de terminaison — il n'y a pas d'URL sandbox séparée. Les sessions de test sont marqué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. Pour des tests déterministes de bout en bout, votre équipe de compte peut configurer une page de mise en scène avec des campagnes de test dédiées. Retirez l'en-tête pour passer en production.

AuthentificationLien direct vers Authentification

  • L'en-tête rokt-account-id est requis à chaque appel (offres et événements) — c'est la source de l'identité du compte sur l'API Session.
  • Appel d'offres — lors de votre premier appel sans session, authentifiez-vous avec Authorization: Basic base64(rpub:rsec), où rpub et rsec sont les clés API publiques et secrètes fournies par votre équipe de compte. (Authorization: Bearer <session_token> est utilisé uniquement pour continuer une session existante.)
  • Appel d'événements — authentifiez-vous avec Authorization: Basic base64(rpub:rsec), en utilisant les mêmes clés API publiques et secrètes que pour l'appel d'offres.

1. Demander des offresLien direct vers 1. Demander des offres

Envoyez un corps de requête typé et définissez channel.type à "s2s". Toutes les valeurs ci-dessous sont des exemples synthétiques.

POST https://api.rokt.com/v2/sessions/offers
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
rokt-platform-type: <iOS | Android | Web>
Content-Type: application/json
{
  "channel": { "type": "s2s" },
  "page": { "page_identifier": "checkout" },
  "customer": {
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "gender": "F",
    "postal_code": "10001",
    "language": "en"
  },
  "transaction": {
    "transaction_value": 19.99,
    "currency": "USD",
    "confirmation_ref": "ORDER-000123"
  },
  "payment": { "type": "card" },
  "device": {
    "user_agent": "YourApp/1.0 (mobile)"
  },
  "attributes": {
    "your_custom_attribute": "value"
  }
}
  • Les objets de niveau supérieur (page, customer, transaction, payment, device, cart, shipping) sont typés et n'acceptent que leurs champs définis; mettez tout signal spécifique au partenaire qui ne leur correspond pas dans la carte de chaîne libre attributes.
  • Envoyez uniquement les valeurs que vous possédez. Les attributs dérivés de Rokt — géo, âge et autres données démographiques (du profil Rokt), type/version de l'appareil/OS (analysé à partir de l'agent utilisateur), méthode de paiement/sous-méthode (à partir du BIN de la carte), et signaux ML/Carbon — sont calculés côté serveur et écrasés s'ils sont envoyés; ne les incluez pas.

2. Analyser la réponse des offresLien direct vers 2. Analyser la réponse des offres

Un 2xx retourne directement l'offre (il n'y a pas d'enveloppe success/errors). plugins peut être vide — un no-fill valide et une véritable part du trafic de production : ne rien afficher et continuer votre page. slots contient uniquement les emplacements effectivement remplis, jusqu'au maximum défini par votre mise en page. Lisez l'offre à partir de la structure imbriquée du plugin ; en cas de non-2xx, analysez le corps d'erreur structuré.

Ce dont vous avez besoinChemin dans la réponse
Offreplugins[].plugin.config.slots[].offer
Titre / texte…offer.creative.copy["creative.title"]
Image…offer.creative.copy["creative.image.src"]
Annonceur…offer.creative.advertiser
Action positive + URL…offer.creative.response_options_map.positive.url
Action de refus…offer.creative.response_options_map.negative
Identifiants d'instance d'élément (à utiliser comme événement parent_id)…slots[].instance_guid, …offer.creative.instance_guid, …response_options_map[key].instance_guid
Instance de page (événement page_instance_guid)page_instance_guid
ID de session (événement session_id)session_id
Jeton de session (référence de session actualisée)session_token.token

Les erreurs retournent un statut HTTP sémantique avec un corps de { "error": "<code>", "message": "<detail>" } (les échecs de validation ajoutent un tableau details[]).

3. Afficher l'offreLien direct vers 3. Afficher l'offre

La façon dont vous affichez dépend de la configuration des mises en page de votre compte — confirmez avec votre équipe Rokt quel contrat votre compte sert :

  • Auto-rendu (intégration de données) — la réponse transporte les composants de l'offre (texte créatif, image, options de réponse — les chemins de l'étape 2) sans description de mise en page : vous dessinez l'offre dans votre propre interface utilisateur pour correspondre à votre page, et vous rapportez chaque événement d'engagement vous-même (étape 4).
  • Rokt UX Helper (mises en page conçues par Rokt) — les plugins[] de la réponse transportent une description complète de la mise en page que les bibliothèques open-source UX Helper de Rokt (Web, iOS, Android) rendent dans votre interface utilisateur, en élevant les événements d'engagement que vous devez transmettre. Notez que les UX Helpers consomment la forme de charge utile de l'API Experiences ; l'API Session retourne le même contenu de mise en page dans une enveloppe différente (snake_case), donc les associer avec /v2/sessions/offers nécessite actuellement une petite adaptation de la réponse — demandez à votre équipe Rokt.

Vous pouvez distinguer les contrats à partir de la réponse elle-même : un compte d'intégration de données retourne des offres avec des schémas de mise en page vides, tandis qu'un compte de mise en page retourne des champs outer_layout_schema peuplés et par emplacement layout_variant.

4. Rapporter les événementsLien direct vers 4. Rapporter les événements

Rapportez les événements d'engagement et de conversion à /v2/sessions/events, authentifiés avec les mêmes identifiants Basic que l'appel d'offres. Identifiez la session avec single_session: true et le session_id de haut niveau retourné par la réponse des offres pour chaque événement.

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 — le type d'événement sous forme de chaîne snake_case. Valeurs courantes :

    Événementevent_type
    Impressionimpression
    Vuviewed
    Réponse positive / négativesignal_response
    Rejetdismissal
    Conversionconversion_signal
    Achatpurchase

  • instance_id — un UUID généré par le client identifiant cet événement, utilisé pour dédupliquer.

  • session_id — le session_id de haut niveau retourné par la réponse des offres.

  • data.parent_id — le instance_guid de l'élément concerné par l'événement, pris de la réponse des offres (par exemple, le instance_guid du créatif pour une impression, celui d'une option de réponse pour une réponse). Construit l'arbre de session. Répétez la valeur telle quelle ; elle peut porter un préfixe de type tel que ad:<uuid>.

  • data.page_instance_guid — le page_instance_guid de la réponse des offres.

  • data.token — le jeton d'événement pour cet élément de la réponse des offres.

  • timestamp — millisecondes de l'époque Unix.

  • Définissez single_session à true et incluez session_id sur chaque événement dans la requête.

Un appel réussi retourne 202 Accepted avec session_token (actualisé pour le prochain appel), event_ids[], errors[] (par événement {index, code, message}), et warnings[].

ChecklistLien direct vers Checklist

  • Confirmez les identifiants et la référence complète de l'API avec votre équipe de compte Rokt.
  • Appelez /v2/sessions/offers avec le corps typé, channel.type: "s2s", et l'en-tête rokt-account-id (plus rokt-platform-type si vos pages sont configurées pour une plateforme native).
  • Analysez l'offre de plugins[].plugin.config.slots[].offer.creative; utilisez le statut HTTP pour le succès/l'échec, et gérez les plugins vides (no-fill) en ne rendant rien.
  • Rendez l'offre vous-même ou via une bibliothèque UX Helper, selon la configuration de mise en page de votre compte.
  • Capturez session_id et rapportez les événements à /v2/sessions/events en utilisant l'authentification Basic, single_session: true, un session_id par événement, et les valeurs data.parent_id et data.page_instance_guid de la réponse.
  • Validez avec l'en-tête rokt-test-session: true (uniquement pour le reporting — cela ne force pas une offre à être servie), puis retirez-le pour passer en production.
Cet article vous a-t-il été utile ?
Last updated Aug 4, 2026