Spécification de l'API des Offres Serveur

Ce document décrit les points de terminaison pertinents nécessaires pour interagir avec les API de Rokt afin de récupérer le contenu Offre de Rokt.

Veuillez travailler avec votre gestionnaire de compte pour obtenir les identifiants nécessaires pour interagir avec ce point de terminaison.

Points de terminaisonLien direct vers Points de terminaison

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

Meilleures pratiques de testLien direct vers Meilleures pratiques de test

Le point de terminaison 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 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 à 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	Dictionary<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) comme 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	Cela sera fourni par Rokt.
rokt-secret	Contient le secret public client fourni qui doit correspondre à l'identifiant public	string	Cela 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	chaîne	"iOS" ou "Android"
rokt-os-version	Version du système d'exploitation	Chaîne	"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	"iPhone 6s", "Galaxy S9", etc.
rokt-package-name	Nom du paquet ou identifiant de bundle de l'application hôte	Chaîne	iOS : com.APPNAME.ios Android : com.APPNAME.android Utilisez le nom de paquet réel de l'application client donnée
rokt-package-version	Version du paquet ou version du bundle de l'application hôte	Chaîne	1.0.5 Utilisez la version de paquet réelle de l'application client 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ées	Description
sessionId	chaîne	ID de session Rokt
pageInstanceGuid	chaîne	Identifiant unique de l'instance de la page de l'utilisateur
pageDetectionTime	chaîne	Heure à laquelle la détection de la page a eu lieu
success	booléen	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	chaîne	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	chaîne	Un GUID généré qui est unique au placement et doit être envoyé dans le cadre des appels d'événements
configurables	Dictionnaire<string, string> / Carte<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 les annonceurs, pour les exigences de la loi sur les services numériques
offers	PartnerOffer[]	Collection d'offres à afficher

Offre PartenaireLien direct vers Offre Partenaire

Nom de la Propriété	Type de Donnée	Description
creativeId	string	Id unique pour le Créatif de l'offre sur la Plateforme Rokt.¹
campaignId	string	Id unique pour la Campagne de l'offre sur 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 concernant l'annonceur derrière cette offre
formatType	string	Type de format pour afficher une offre

¹ L'Id 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ée	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ée	Description
action	string	L'action de la réponse “CaptureOnly” - juste 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 de l'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

Ciblage des DonnéesLien direct vers Ciblage des Données

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é montré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
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 montré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 marque de l'annonceur

Comment trouver la Mention Légale & les Termes et ConditionsLien direct vers Comment trouver la Mention Légale & les Termes et Conditions

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": "Text displaying how Partners use Rokt to determine the most relevant offers to show customers",
                "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": "This is an Rokt Commerce Email Campaign from Mobile team Account. This should appear in prime position for the mobile SDK automated testing. ",
                        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732356166940819466",
                        "creative.termsAndConditions.close.copy": "Close",
                        "creative.termsAndConditions.title": "Terms of Use",
                        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732356166940819466",
                        "creative.privacyPolicy.close.copy": "Close",
                        "creative.privacyPolicy.title": "Privacy Policy",
                        "creative.confirmation.message": "Details will go to test1593754986316@rokt.com",
                        "creative.success.title": "Success",
                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com."
                    },
                    "advertiser": {
                        "name": "Legal Name One",
                        "brand": "Brand Name One"
                    }
                    "responseOptions": [
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
                            "signalType": "SignalResponse",
                            "label": "Yes",
                            "successText": "Subscribed",
                            "isPositive": true,
                            "url": ""
                        },
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "04c74a56-9fa7-408e-b722-052ae275f53f",
                            "signalType": "SignalResponse",
                            "label": "No thanks",
                            "successText": "",
                            "isPositive": false,
                            "url": ""
                        }
                    ],
                    "formatType": "Text"
                },
                {
                    "creativeId": "2732357120423559183",
                    "campaignId": "2732344566234284034",
                    "slotGuid": "e499763e-769e-4621-8591-c55c6b833e1f",
                    "creativeGuid": "11096aa6-878f-4bb7-acb5-156d0999edb8",
                    "copy": {
                        "creative.disclaimer": "<strong>Disclaimer</strong>",
                        "creative.copy": "This is an acquire email campaign from Mobile team Account for mobile SDK automated testing.",
                        "creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732357120423559183",
                        "creative.termsAndConditions.close.copy": "Close",
                        "creative.termsAndConditions.title": "Terms &amp; Conditions",
                        "creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732357120423559183",
                        "creative.privacyPolicy.close.copy": "Close",
                        "creative.privacyPolicy.title": "Privacy Policy",
                        "creative.confirmation.message": "Confirmation will go to test1593754986316@rokt.com",
                        "creative.success.title": "Success",
                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com."
                    },
                    "advertiser": {
                        "name": "Legal Name Two",
                        "brand": "Brand Name Two"
                    },
                    "responseOptions": [
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "779e41cd-5653-4143-b0bb-3df4eb3a2325",
                            "signalType": "SignalResponse",
                            "label": "Yes please",
                            "successText": "Email Sent",
                            "isPositive": true,
                            "url": ""
                        },
                        {
                            "action": "CaptureOnly",
                            "responseOptionGuid": "87af7302-0c53-4676-a002-8f0f8fcbb530",
                            "signalType": "SignalResponse",
                            "label": "No thanks",
                            "successText": "",
                            "isPositive": false,
                            "url": ""
                        }
                    ],
                    "formatType": "Text"
                }
            ],
            "configurables": {
                "positive.button.color": "red"
            }
        }
    ],
    "success": true
}

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

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

{
    "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 qui se sont produites

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": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "PartnerIdNotIncluded",
            "message": "rokt-tag-id is missing/incorrect",
            "value": "0"
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-os-type."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-package-name."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-package-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-device-model."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-sdk-version."
        },
        {
            "code": "NotEmptyValidator",
            "message": "Missing header: rokt-os-version."
        },
        {
            "code": "ClientUniqueIdIsMissing",
            "message": "Missing header: rokt-client-unique-id."
        },
        {
            "code": "PlatformTypeIsInvalid",
            "message": "Invalid header: rokt-platform-type."
        }
    ]
}

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

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "Request body format is not valid"
        }
    ]
}

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 automatisés 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 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é conforme aux codes de réponse HTTP standard. Dans le cas où cette réponse se produit, nous recommandons que la requête soit réessayée 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 grâce à l'engagement des utilisateurs et aux 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 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 de lancer la récupération du contenu des offres après qu'un utilisateur a dé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 plus tard par le client pour une utilisation dans 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 pour le contexte actuel du client.