Spécification de l'API Server Offers

Ce document décrit les endpoints pertinents nécessaires pour interagir avec les APIs de Rokt afin de récupérer le contenu Offer de Rokt.

Veuillez travailler avec votre Account Manager pour obtenir les identifiants nécessaires pour interagir avec cet endpoint.

EndpointsLien direct vers Endpoints

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

Meilleures Pratiques de TestLien direct vers Meilleures Pratiques de Test

L'endpoint de test https://server-api-demo.rokt.com/v1/partner/offers est spécifiquement conçu pour les tests et doit être utilisé pour valider l'intégration sans affecter les données ou la performance en production. Assurez-vous d'utiliser les en-têtes et formats de requête appropriés comme spécifié dans la documentation de l'API pour émuler efficacement des scénarios similaires à ceux de la production.

RequêteLien direct vers Requête

Racine/CorpsLien direct vers Racine/Corps

Nom de la propriété	Requis	Type de données	Description
pageIdentifier	Oui	string	Texte utilisé pour différencier les vues
attributes	Oui	Dictionnaire<string, string> / Map<string, string>	Contient les données d'attribut utilisateur à utiliser pour la sélection des offres. Pour les requêtes `WebMobile`/`WebDesktop` uniquement : Inclure userAgent (dérivé du navigateur) en tant qu'attribut. Voir exemple ci-dessous.

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

Clé d'en-tête	Description	Type	Remarque
rokt-pub-id	Contient l'identifiant public client fourni	string	Celui-ci sera fourni par Rokt.
rokt-secret	Contient le secret public client fourni qui doit correspondre à l'identifiant public	string	Celui-ci sera fourni par Rokt.

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

Clé d'en-tête	Description	Type	Exemple
content-type	Type de média	string	“application/json”
accept	Type de média attendu de la réponse	string	“application/json”
rokt-tag-id	ID de Tag Rokt	String	1234567890
rokt-ui-locale	Culture et pays de l'interface utilisateur	String	Identifiant de locale et de pays ISO, par ex. en-US
rokt-client-unique-id	Pour le dépannage entre les systèmes partenaires et Rokt	String	Un ID de transaction de référence (ID unique)
rokt-platform-type	Indique la plateforme pour laquelle les offres sont demandées	string	Par défaut : `Mobile` Valeurs acceptées : `Mobile`, `Web`, `WebMobile`, `WebDesktop`

En-têtes supplémentaires requis pour MobileLien direct vers En-têtes supplémentaires requis pour Mobile

Lors de la demande d'offres pour la plateforme Mobile, les en-têtes suivants sont également requis :

Clé de l'en-tête	Description	Type	Exemple
rokt-os-type	Type de système d'exploitation (OS)	chaîne de caractères	"iOS" ou "Android"
rokt-os-version	Version du système d'exploitation (OS)	Chaîne de caractères	"8.0" ou "4.4.1"
rokt-device-model	Modèle de l'appareil pour iOS ou modèle de construction pour Android	Chaîne de caractères	"iPhone 6s", "Galaxy S9", etc.
rokt-package-name	PackageName ou BundleIdentifier de l'application hôte	Chaîne de caractères	iOS : com.APPNAME.ios Android : com.APPNAME.android Utilisez le nom de package réel de l'application cliente donnée
rokt-package-version	Version du package ou version du bundle de l'application hôte	Chaîne de caractères	1.0.5 Utilisez la version réelle du package de l'application cliente donnée

Exemple de requête (Application Mobile)Lien direct vers Exemple de requête (Application Mobile)

Corps/Payload de la requête JSON

{
    "attributes": {
        "country": "AU",
        "firstname": "jenny",
        "mobile": "(323) 867-5309",
        "postcode": "90210",
        "email": "test1593754986316@rokt.com",
        "lastname": "Smith"
    },
    "pageIdentifier": "page_identifier"
}

Exemple de Requête (Web Mobile/Desktop)Lien direct vers Exemple de Requête (Web Mobile/Desktop)

Corps/Payload de la Requête JSON

{
    "attributes": {
        "country": "AU",
        "firstname": "jenny",
        "mobile": "(323) 867-5309",
        "postcode": "90210",
        "email": "test1593754986316@rokt.com",
        "lastname": "Smith",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3.1 Safari/605.1.15"
    },
    "pageIdentifier": "page_identifier"
}

userAgent peut être dérivé du navigateur, par exemple via window.navigator.userAgent.

RéponseLien direct vers Réponse

Réponse de Succès (200)Lien direct vers Réponse de Succès (200)

Racine/CorpsLien direct vers Racine/Corps

Nom de la Propriété	Type de Donnée	Description
sessionId	string	ID de Session Rokt
pageInstanceGuid	string	Identifiant unique de l'instance de la page de l'utilisateur
pageDetectionTime	string	Heure à laquelle la détection de la page a eu lieu
success	boolean	Indique si la requête a réussi
placements	Placement[]	Collection d'offres/placement

PlacementLien direct vers Placement

Nom de la propriété	Type de données	Description
experienceId	string	Identifiant représentant l'expérience sélectionnée de Rokt. Si aucune expérience n'est explicitement sélectionnée, la valeur sera `NotSet`
placementGuid	string	Un GUID généré qui est unique pour le placement et à envoyer dans le cadre des appels d'événements
configurables	Dictionary<string, string> / Map<string, string>	Collection de paramètres dynamiques utilisés pour le rendu des offres
targetingData	TargetingData	Informations sur les raisons pour lesquelles l'ensemble actuel d'offres a été affiché, y compris les informations sur l'annonceur, pour les exigences de la loi sur les services numériques (Digital Services Act)
offers	PartnerOffer[]	Collection d'offres à afficher

Offre PartenaireLien direct vers Offre Partenaire

Nom de la propriété	Type de données	Description
creativeId	string	Identifiant unique pour le Créatif de l'offre dans la plateforme Rokt.¹
campaignId	string	Identifiant unique pour la Campagne de l'offre dans la plateforme Rokt.¹
slotGuid	string	GUID unique représentant l'emplacement de l'offre
creativeGuid	string	GUID unique représentant l'offre/créatif
copy	Dictionary<string, string> / Map<string, string>	Collection de KVP utilisée pour fournir les données de l'offre
responseOptions	ResponseOption[]	Collection des options de réponse possibles
advertiser	Advertiser	Détails sur l'annonceur derrière cette offre
formatType	string	Type de format pour afficher une offre

¹ L'identifiant sera fourni pour les campagnes Ecommerce, d'autres types de campagnes recevront la valeur : NotSet

CopieLien direct vers Copie

Nom de la propriété	Type de données	Description
creative.copy	string	Contenu de la copie
creative.title	string	Titre de la copie
creative.disclaimer	string	Texte de la clause de non-responsabilité
creative.termsAndConditions.link	string	Lien vers les termes et conditions
creative.privacyPolicy.link	string	Lien vers la politique de confidentialité

Option de réponseLien direct vers Option de réponse

Nom de la propriété	Type de données	Description
action	string	L'action de la réponse “CaptureOnly” - seulement déclencher l'événement “Url” - L'url doit être ouverte et déclencher l'événement
responseOptionGuid	string	Un GUID généré qui est unique à l'option de réponse et doit être envoyé dans le cadre des appels d'événements
signalType	string	Le EventType à utiliser lors de l'envoi d'un événement lors d'une interaction. Ce sera presque toujours `SignalResponse`
label	string	Étiquette à afficher sur le bouton/lien
successText	string	Texte à afficher lors de l'interaction (non pertinent pour le pilote)
isPositive	boolean	Indique si la réponse est un engagement positif ou négatif
url	string	URL sur laquelle effectuer l'action

Données de CiblageLien direct vers Données de Ciblage

Nom de la Propriété	Type de Donnée	Description
link	string	Un hyperlien vers des détails sur la raison pour laquelle cette sélection d'offres a été affichée, y compris les informations des annonceurs uniques à la session. Afficher ce lien peut aider à remplir les obligations de la loi sur les services numériques (Digital Services Act)
copy	string	Texte expliquant comment les Partenaires utilisent Rokt pour déterminer les offres les plus pertinentes à montrer aux clients
advertisers	Advertiser[]	La collection d'annonceurs derrière l'ensemble actuel d'offres, ordonnée selon la séquence dans laquelle les offres sont affichées

AnnonceurLien direct vers Annonceur

Nom de la Propriété	Type de Donnée	Description
name	string	Le nom de compte/entité légale de l'annonceur
brand	string	Le nom de la marque de l'annonceur

Comment trouver la Mention Légale & les Conditions GénéralesLien direct vers Comment trouver la Mention Légale & les Conditions Générales

Nom de la Propriété	Type de Donnée	Emplacement de la Réponse des Offres (chemin JSON)
Disclaimer	string	body.placements[i].offers[j].copy.creative.disclaimer
Terms and Conditions Link	string	body.placements[i].offers[j].copy.creative.termsAndConditions.link

Où :

i représente l'index du placement affiché
j représente l'index de l'emplacement affiché

ExempleLien direct vers Exemple

{
    "sessionId": "aec20020-2d5c-45e7-ac3d-6f5daa22b983",
    "pageInstanceGuid": "aec20020-2d5c-4497-87e8-475576ddffa5",
    "pageDetectionTime": "2022-06-28T01:57:09.2147413+00:00",
    "placements": [
        {
            "experienceId": "RedButton",
            "placementGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "targetingData": {
                "link": "https://apps-demo.rokt.com/dsa/rokt-en.html?name=Legal%20Name%20One&brand=Brand%20Name%20One&name=Legal%20Name%20Two&brand=Brand%20Name%20Two",
                "copy": "Texte affichant comment les partenaires utilisent Rokt pour déterminer les offres les plus pertinentes à montrer aux clients",
                "advertisers": [
                    {
                        "name": "Legal Name One",
                        "brand": "Brand Name One"
                    },
                    {
                        "name": "Legal Name Two",
                        "brand": "Brand Name Two"
                    }
                ]
        },
            "offers": [
                {
                    "creativeId": "NotSet",
                    "campaignId": "NotSet",
                    "slotGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394",
                    "creativeGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd",
                    "copy": {
                        "creative.copy": "Ceci est une campagne email Rokt Commerce de l'équipe Mobile. Cela devrait apparaître en position de choix pour les tests automatisés du SDK mobile.",
                        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732356166940819466",
                        "creative.termsAndConditions.close.copy": "Fermer",
                        "creative.termsAndConditions.title": "Conditions d'utilisation",
                        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732356166940819466",
                        "creative.privacyPolicy.close.copy": "Fermer",
                        "creative.privacyPolicy.title": "Politique de confidentialité",
                        "creative.confirmation.message": "Les détails seront envoyés à test1593754986316@rokt.com",
                        "creative.success.title": "Succès",
                        "creative.success.copy": "Nous avons envoyé une confirmation à test1593754986316@rokt.com."
                    },
```json
"advertiser": {
    "name": "Nom légal Un",
    "brand": "Nom de marque Un"
},
"responseOptions": [
    {
        "action": "CaptureOnly",
        "responseOptionGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
        "signalType": "SignalResponse",
        "label": "Oui",
        "successText": "Abonné",
        "isPositive": true,
        "url": ""
    },
    {
        "action": "CaptureOnly",
        "responseOptionGuid": "04c74a56-9fa7-408e-b722-052ae275f53f",
        "signalType": "SignalResponse",
        "label": "Non merci",
        "successText": "",
        "isPositive": false,
        "url": ""
    }
],
"formatType": "Texte"
},
{
    "creativeId": "2732357120423559183",
    "campaignId": "2732344566234284034",
    "slotGuid": "e499763e-769e-4621-8591-c55c6b833e1f",
    "creativeGuid": "11096aa6-878f-4bb7-acb5-156d0999edb8",
    "copy": {
        "creative.disclaimer": "<strong>Avertissement</strong>",
        "creative.copy": "Ceci est une campagne d'acquisition d'e-mail de l'équipe Mobile pour les tests automatisés du SDK mobile.",
        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732357120423559183",
        "creative.termsAndConditions.close.copy": "Fermer",
        "creative.termsAndConditions.title": "Termes &amp; Conditions",
        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732357120423559183",
        "creative.privacyPolicy.close.copy": "Fermer",
        "creative.privacyPolicy.title": "Politique de confidentialité",
        "creative.confirmation.message": "La confirmation sera envoyée à test1593754986316@rokt.com",

```                        "creative.success.title": "Succès",
                        "creative.success.copy": "Nous avons envoyé une confirmation à test1593754986316@rokt.com."
                    },
                    "advertiser": {
                        "name": "Nom Légal Deux",
                        "brand": "Nom de Marque Deux"
                    },
                    "responseOptions": [
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "779e41cd-5653-4143-b0bb-3df4eb3a2325",
                            "signalType": "SignalResponse",
                            "label": "Oui s'il vous plaît",
                            "successText": "Email Envoyé",
                            "isPositive": true,
                            "url": ""
                        },
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "87af7302-0c53-4676-a002-8f0f8fcbb530",
                            "signalType": "SignalResponse",
                            "label": "Non merci",
                            "successText": "",
                            "isPositive": false,
                            "url": ""
                        }
                    ],
                    "formatType": "Texte"
                }
            ],
            "configurables": {
                "positive.button.color": "rouge"
            }
        }
    ],
    "success": true
}

Réponse de Succès Vide (200)Lien direct vers Réponse de Succès Vide (200)

Il y a une occurrence rare où il n'y aura pas d'offres pertinentes pour un utilisateur particulier. Dans ce cas, Rokt renverra une charge utile sans emplacements :

{
    "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
    "pageInstanceGuid": "aec20024-8d24-4ee5-8b6b-2b45364e678b",
    "pageDetectionTime": "2022-06-28T02:13:04.7608276+00:00",
    "placements": [],
    "success": true
}

Réponse d'Erreur de Requête (4XX)Lien direct vers Réponse d'Erreur de Requête (4XX)

Racine/CorpsLien direct vers Racine/Corps

Nom de la Propriété	Type de Donnée	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

ErreurLien direct vers Erreur

Nom de la Propriété	Type de Donnée	Description
code	string	Code d'erreur correspondant
message	number	Message décrivant l'erreur
value	boolean	Valeur fournie qui était invalide, le cas échéant

Exemple : Erreur de Validation de Requête (422)Lien direct vers Exemple : Erreur de Validation de Requête (422)

{
    "title": "Échec de la validation",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "PartnerIdNotIncluded",
            "message": "rokt-tag-id est manquant/incorrect",
            "value": "0"
        },
        {
            "code": "NotEmptyValidator",
            "message": "En-tête manquant : rokt-os-type."
        },
        {
            "code": "NotEmptyValidator",
            "message": "En-tête manquant : rokt-package-name."
        },
        {
            "code": "NotEmptyValidator",
            "message": "En-tête manquant : rokt-package-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "En-tête manquant : rokt-device-model."
        },
        {
            "code": "NotEmptyValidator",
            "message": "En-tête manquant : rokt-sdk-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "En-tête manquant : rokt-os-version."
        },
        {
            "code": "ClientUniqueIdIsMissing",
            "message": "En-tête manquant : rokt-client-unique-id."
        },
        {
            "code": "PlatformTypeIsInvalid",
            "message": "En-tête invalide : rokt-platform-type."
        }
    ]
}

Exemple : Requête videLien direct vers Exemple : Requête vide

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "Le format du corps de la requête n'est pas valide"
        }
    ]
}

Exemple : Trop de requêtes (429)Lien direct vers Exemple : Trop de requêtes (429)

Rokt peut limiter ou bloquer temporairement le trafic pour protéger la stabilité de la plateforme ou appliquer une politique. Dans ces cas, l'API renvoie un HTTP 429 avec un corps vide et sans en-tête Retry-After. Veuillez ne pas réessayer ces requêtes — les réessais automatiques peuvent augmenter la charge et prolonger la limitation. Suspendez les appels ultérieurs pour ce flux, examinez votre taux de requêtes, et contactez votre représentant Rokt si les 429 persistent.

Erreurs de service interne (5XX)Lien direct vers Erreurs de service interne (5XX)

Dans de rares circonstances, un système peut être incapable de compléter 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 standards. Dans le cas où cette réponse se produit, nous recommandons de réessayer la requête après un bref 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.

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

Rendre les offres Rokt en temps opportun vous permet de maximiser les opportunités de revenus issues de l'engagement des utilisateurs et des conversions. Cependant, une intégration serveur à serveur implique des appels réseau supplémentaires entre les serveurs backend de Rokt et les vôtres, ce qui retarde la récupération des données nécessaires pour rendre les offres.

Pour améliorer les performances, nous vous recommandons de récupérer le contenu des offres depuis le point de terminaison API /offers de Rokt à un moment antérieur dans le parcours de transaction de l'utilisateur, avant que nos offres ne soient censées être rendues. Il est préférable d'initier la récupération du contenu des offres après qu'un utilisateur ait montré un intérêt significatif pour compléter la transaction afin d'éviter des appels réseau inutiles.

Une fois reçues, les données peuvent être stockées dans un cache. Cela permettra une récupération plus rapide ultérieurement par le client pour une utilisation 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. Dans le scénario d'un changement de contexte utilisateur (par exemple, d'un appareil Android à un appareil iOS), le client devrait récupérer de nouveaux emplacements depuis le point de terminaison /offers en utilisant des attributs client mis à jour. Cela garantit que les offres rendues restent pertinentes par rapport au contexte actuel du client.