Spécification de l'API des Offres de Session (S2S)

Ce document décrit le point de terminaison nécessaire pour récupérer le contenu Offre de Rokt en utilisant l'API de Session (v2).

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

Point de terminaisonLien direct vers Point de terminaison

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

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

RequêteLien direct vers Requête

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

En-tête	Description	Type	Remarque
`Authorization`	Identifiants d'authentification de base	chaîne	`Basic base64(rpub:rsec)` — utilisez les clés API publiques et secrètes fournies par votre équipe de compte.
`rokt-account-id`	Votre ID de compte Rokt	chaîne	Requis à chaque appel. C'est la source de l'identité du compte sur l'API de Session.

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

En-tête	Description	Type	Exemple
`Content-Type`	Type de média	chaîne	`application/json`
`rokt-platform-type`	Plateforme pour laquelle les offres sont demandées	chaîne	`iOS`, `Android`, `Web`, `WebDesktop`, ou `WebMobile` (insensible à la casse). Par défaut à `Web`.

remarque

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 — sinon la détection de la page ne correspondra pas à vos pages configurées nativement et ne renverra aucune offre. Les pages configurées pour le Web n'ont pas besoin d'en-tête.

Racine/CorpsLien direct vers Racine/Corps

Propriété	Requis	Type	Description
`channel`	Oui	objet	Doit contenir `"type": "s2s"`.
`page`	Oui	objet	Voir Page.
`customer`	Non	objet	Voir Client.
`transaction`	Non	objet	Voir Transaction.
`payment`	Non	objet	Voir Paiement.
`device`	Non	objet	Voir Appareil.
`attributes`	Non	objet	Carte `string → string` libre pour tout signal spécifique au partenaire qui ne correspond pas à un objet typé.

remarque

Envoyez uniquement les valeurs que vous possédez. Les attributs dérivés de Rokt — géo, âge et autres données démographiques, type d'appareil/OS/version, méthode de paiement, et signaux ML — sont calculés côté serveur et écrasés si envoyés ; ne les incluez pas.

PageLien direct vers Page

Propriété	Requis	Type	Description
`page_identifier`	Oui	chaîne de caractères	Texte utilisé pour différencier les vues/pages.
`page_variation_code`	Non	chaîne de caractères	Code de variation optionnel pour la page.

ClientLien direct vers Client

Propriété	Requis	Type	Description
`email`	Non	chaîne de caractères	Adresse email du client.
`first_name`	Non	chaîne de caractères	Prénom du client.
`last_name`	Non	chaîne de caractères	Nom de famille du client.
`gender`	Non	chaîne de caractères	Genre du client.
`postal_code`	Non	chaîne de caractères	Code postal/zip du client.
`language`	Non	chaîne de caractères	Code de langue du client (par ex. `en`).

TransactionLien direct vers Transaction

Propriété	Requis	Type	Description
`transaction_value`	Non	nombre	Valeur de la transaction.
`currency`	Non	chaîne de caractères	Code de devise ISO 4217 (par ex. `USD`).
`confirmation_ref`	Non	chaîne de caractères	Référence de commande ou de confirmation côté partenaire.

PaiementLien direct vers Paiement

Propriété	Requis	Type	Description
`type`	Non	chaîne de caractères	Type de méthode de paiement (par ex. `card`).

AppareilLien direct vers Appareil

Propriété	Requis	Type	Description
`user_agent`	Non	chaîne de caractères	Chaîne de l'agent utilisateur de l'appareil ou de l'application client.

Exemple de requêteLien direct vers Exemple de requête

POST https://api.rokt.com/v2/sessions/offers
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
rokt-platform-type: 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"
  }
}

RéponseLien direct vers Réponse

Réponse de succès (2xx)Lien direct vers Réponse de succès (2xx)

Une réponse 2xx retourne directement l'offre — il n'y a pas d'enveloppe success/errors. plugins peut être vide, ce qui est un scénario valide de non-remplissage représentant une part réelle du trafic de production : ne rien rendre et continuer la page.

Champs clésLien direct vers Champs clés

Ce dont vous avez besoin	Chemin dans la réponse
Offre	`plugins[].plugin.config.slots[].offer`
Titre / texte	`…offer.creative.copy["creative.title"]`
Image	`…offer.creative.copy["creative.image.src"]`
Avertissement	`…offer.creative.copy["creative.disclaimer"]`
Lien des Termes & Conditions	`…offer.creative.copy["creative.termsAndConditions.link"]`
Lien de la Politique de Confidentialité	`…offer.creative.copy["creative.privacyPolicy.link"]`
Annonceur	`…offer.creative.advertiser`
Action positive + URL	`…offer.creative.response_options_map.positive.url`
Action de refus	`…offer.creative.response_options_map.negative`
ID 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 (utiliser comme événement `page_instance_guid`)	`page_instance_guid`
ID de session (utiliser comme événement `session_id`)	`session_id`
Jeton de session (référence de session actualisée)	`session_token.token`

AnnonceurLien direct vers Annonceur

Propriété	Type	Description
`name`	string	Le nom de l'entité légale de l'annonceur.
`brand`	string	Le nom de marque de l'annonceur.

Exemple de réponse réussie (2xx)Lien direct vers Exemple de réponse réussie (2xx)

Un compte configuré par mise en page renvoie des champs outer_layout_schema remplis et par emplacement layout_variant; un compte d'intégration de données renvoie le même contenu offer/creative avec ces schémas de mise en page vides. Toutes les valeurs ci-dessous sont des exemples synthétiques — lisez les champs dont vous avez besoin en utilisant les chemins Champs clés ci-dessus.

{
  "session_id": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
  "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
  "session_token": {
    "token": "<session_token>"
  },
  "plugins": [
    {
      "plugin": {
        "id": "3353172846080032866",
        "name": "dcui",
        "config": {
          "instance_guid": "ce5158a9-dc59-4a97-9006-a299901e4587",
          "outer_layout_schema": "<JSON-encoded layout schema>",
          "layout_schema_version": "2.0",
          "slots": [
            {
              "instance_guid": "8f492d28-83fb-4813-877e-26e752ea9474",
              "offer": {
                "campaign_id": "2749386944931233793",
                "account_id": "<your Rokt account ID>",
                "creative": {
                  "referral_creative_id": "2760914349384466797",
                  "instance_guid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
                  "advertiser": {
                    "name": "Example Advertiser Inc.",
                    "brand": "Example Brand"
                  },
                  "copy": {
                    "creative.title": "Get 20% off your next order",
                    "creative.image.src": "https://example.com/creative/hero.png",
                    "creative.disclaimer": "New customers only. Terms apply.",
                    "creative.termsAndConditions.link": "https://example.com/terms",
                    "creative.privacyPolicy.link": "https://example.com/privacy"
                  },
                  "response_options_map": {
                    "positive": {
                      "id": "2760914349384466794",
                      "action": "Url",
                      "instance_guid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
                      "signal_type": "SignalResponse",
                      "short_label": "Yes",
                      "long_label": "Yes please",
                      "is_positive": true,
                      "url": "https://example.com/redeem",
                      "url_behavior": "newTab",
                      "token": "<event-token>"
                    },
                    "negative": {
                      "id": "2760914349384466796",
                      "action": "CaptureOnly",
                      "instance_guid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                      "signal_type": "SignalResponse",
                      "short_label": "No thanks",
                      "long_label": "No thanks",
                      "is_positive": false,
                      "token": "<event-token>"
                    }
                  },
                  "token": "<event-token>"
                }
              },
              "layout_variant": {
                "layout_variant_id": "3353172846080032865",
                "module_name": "standard-marketing",
                "format_type": "Text",
                "layout_variant_schema": "<JSON-encoded layout schema>"
              },
              "token": "<event-token>"
            }
          ]
        }
      },
      "fonts": []
    }
  ]
}

Réponse sans remplissage (2xx)Lien direct vers Réponse sans remplissage (2xx)

Lorsqu'il n'y a pas d'offres pertinentes pour un utilisateur particulier, Rokt renvoie un 2xx avec un tableau plugins vide. Ne rien afficher et continuer votre page.

{
  "plugins": [],
  "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
  "session_token": {
    "token": "<session_token>"
  }
}

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

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

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

Les échecs de validation incluent un tableau details[] supplémentaire.

Codes d'erreur courantsLien direct vers Codes d'erreur courants

Statut HTTP	Signification
`400`	Corps de requête mal formé.
`401`	En-tête `Authorization` manquant ou invalide.
`422`	Échec de la validation de la requête (voir `details[]`).
`429`	Limité par le taux. Ne pas réessayer automatiquement — faites une pause et contactez votre représentant Rokt si les 429 persistent.
`5xx`	Erreur serveur inattendue. Réessayez après un bref délai (1–2 secondes). Si le problème persiste, contactez support@rokt.com.

Mise en cache des offresLien direct vers Mise en cache des offres

Pour maximiser les opportunités de revenus, récupérez le contenu de l'offre de /v2/sessions/offers plus tôt dans le parcours de transaction de l'utilisateur — avant que l'offre ne soit censée être affichée — puis mettez-le en cache pour une récupération rapide par le client au sein de la même transaction.

Nous recommandons de mettre en cache en fonction d'une combinaison d'ID de transaction unique, d'ID utilisateur et de type d'appareil utilisateur. Si le contexte utilisateur change (par exemple, changement d'appareil), récupérez à nouveau avec des attributs mis à jour pour garantir la pertinence de l'offre.