V2 Partner Experiences API

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 des Expériences de Rokt. Le point de terminaison est conçu pour servir des expériences alimentées par des offres directement aux partenaires. Les requêtes sont envoyées à ce point de terminaison, et la réponse est transmise à la bibliothèque UX Helper pour un traitement approprié.

Points de terminaison

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

Meilleures pratiques de test

Le point de terminaison de test https://server-api-demo.rokt.com/v2/partner/experiences 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 et formats de requête appropriés sont utilisés comme spécifié dans la documentation de l'API pour émuler efficacement des scénarios similaires à la production.

Requête

En-têtes d'autorisation

Veuillez travailler avec votre gestionnaire de compte pour obtenir les informations d'identification nécessaires pour interagir avec ce point de terminaison

Clé de l'en-tête	Requis	Description	Type	Remarque
rokt-pub-id	Oui	Contient l'identifiant public du client fourni	string	Ceci sera fourni par Rokt.
rokt-secret	Oui	Contient le secret public du client fourni qui doit correspondre à l'identifiant public	string	Ceci sera fourni par Rokt.

En-têtes requis

Clé de l'en-tête	Requis	Description	Type	Exemple
content-type	Oui	Type de média	string	“application/json”
accept	Oui	Type de média attendu de la réponse	string	“application/json”
rokt-tag-id	Oui	Rokt Tag ID	string	1234567890

Corps

Nom de la propriété	Requis	Type de données	Description
sessionId	Non	string	ID de session de la session Rokt existante, si elle existe
pageIdentifier	Oui	string	Texte utilisé pour différencier les vues
attributes	Oui	Map<string, string>	Contient les données d'attribut utilisateur à utiliser lors de la sélection d'offres
integration	Oui	Integration	Données relatives à l'intégration effectuant la demande. Cela peut être obtenu à partir des bibliothèques UXHelper disponibles pour Android, iOS et web

Intégration

Nom de la propriété	Requis	Type de données	Description
name	Oui	string	Indique le nom commun de l'intégration effectuant la demande
version	Oui	string	Version de l'intégration effectuant la demande
framework	Oui	string	Cadre d'intégration utilisé (par exemple, Flutter, React Native)
platform	Oui	string/enum	Plateforme partenaire demandant des offres (par exemple, Web, Mobile, iOS)
layoutSchemaVersion	Oui	string	Version de schéma compatible la plus élevée pour l'intégration
deviceLocale	Oui	string	Paramètre régional du dispositif de l'utilisateur
deviceModel	Oui	string	Modèle de l'appareil pour iOS ou modèle de construction pour Android
deviceType	Oui	string	Type de dispositif/facteur de forme (par exemple, Téléphone, Tablette)
operatingSystem	Oui	string	Système d'exploitation du dispositif de l'utilisateur
operatingSystemVersion	Oui	string	Version du système d'exploitation du dispositif de l'utilisateur
packageName	Oui	string	Nom du package ou identifiant du bundle de l'application hôte
packageVersion	Oui	string	Version du package ou version du bundle de l'application hôte
metadata	Non	Map<string, string>	Données supplémentaires liées à l'intégration ou au dispositif

Exemple de Requête

Corps/Payload de la Requête JSON

Cliquez pour développer

{
    "attributes": {
        "email": "test@rokt.com",
        "locale": "en-AU"
    },
    "pageIdentifier": "your_page_identifier",
    "integration": {
        "name": "UX Helper iOS",
        "version": "1.0",
        "framework": "Swift",
        "platform": "iOS",
        "layoutSchemaVersion": "2.1.0",
        "packageVersion": "1.0.0",
        "packageName": "com.partner",
        "operatingSystem": "iOS",
        "operatingSystemVersion": "18",
        "deviceType": "Phone",
        "deviceModel": "iPhone",
        "metadata": {
          "IsCharging": "true"
        }
    },
}

Réponse

Réponse de Succès (200)

En-têtes

Ces en-têtes seront retournés pour assurer la cohérence avec d'autres API Ecommerce, mais il n'est pas prévu qu'ils soient consommés par le partenaire ou la bibliothèque UX.

Clé de l'en-tête	Description
rokt-account-id	ID de compte pour lequel les offres ont été servies
rokt-session-id	ID de session Rokt associé
etag	Valeur etag de Rokt pour l'utilisateur

Corps de Réussite

Racine

Nom de la Propriété	Type	Description
PageContext	PageContext	Données relatives à la page détectée
Plugins	Layout[]	Objet plugin et polices
SessionId	string	ID de session Rokt. Pour le Web, cet ID de session est consommé depuis l'en-tête
Success	bool	Indique si la requête a réussi ou est invalide
Token	string	JWT d'intégrité des données au niveau de la session
Options	SdkOptions	Collection de configurations d'exécution à fournir aux SDKs Rokt consommateurs

SdkOptions

Nom de la propriété	Type	Description
UseDiagnosticEvents	bool	Indique si le SDK Rokt doit produire des diagnostics

PageContext

Nom de la propriété	Type	Description
IsPageDetected	bool	Indique si la requête a abouti à la correspondance d'une page Partenaire
PageId	string	GUID représentant la configuration de la page OP correspondante
PageInstanceGuid	string	GUID représentant une instance spécifique de la page sélectionnée
PageVariantName	string	Nom de la Variante de Page sélectionnée
PartnerContentTemplate	string	Modèle utilisé pour les expériences de paiements
RoktTagId	string	ID de Tag Partenaire/Annonceur
Token	string	JWT d'intégrité des données au niveau de la page

LayoutPlugin

Nom de la propriété	Type	Description
Fonts	Font[]	Tableau de polices à utiliser par les SDKs pour l'offre
Plugin	Plugin	Configuration du plugin

Plugin

Nom de la propriété	Type	Description
Config	PluginConfig	Définit la configuration pour le rendu de la mise en page
Id	string	ID de mise en page / ID externe de la transaction de mise en page
Name	string	Nom du plugin à utiliser pour le rendu
TargetElementPosition	string	Action pour le placement de position basé sur targetElementSelector
TargetElementRelation	string	Relation entre le placement et targetElementSelector
TargetElementSelector	string	Position identifiée pour placer la mise en page dans la page
TargetSection	string	Identifie différents types de ciblage, par exemple, page de remerciement
Url	string	URL pour télécharger le plugin

PluginConfig

Nom de la propriété	Type	Description
InstanceGuid	string	GUID représentant une instance spécifique du plugin / layout
LayoutSchemaVersion	string	Version du schéma de layout utilisé pour le layout
OuterLayoutSchema	string	Schéma JSON définissant l'interface utilisateur du Outer Layout
Slots	Slot []	Collection de slots d'offres
Token	string	JWT d'intégrité des données au niveau du plugin / layout

Slot

Nom de la propriété	Type	Description
InstanceGuid	string	GUID représentant une instance spécifique du Slot
LayoutVariant	LayoutVariant	Définition du LayoutVariant à utiliser pour le Slot / Offre
Offer	Offer	Définition de l'Offre à afficher pour nos clients
Token	string	JWT d'intégrité des données au niveau du plugin / layout

LayoutVariant

Nom de la propriété	Type	Description
LayoutVariantId	string	ID généré automatiquement
ModuleName	string	Le nom du module de mise en page
FormatType	string	Type de format pour afficher une offre
LayoutVariantSchema	string	Schéma JSON définissant l'interface utilisateur pour rendre les offres qui exploitent la variante

Offer

Nom de la propriété	Type	Description
AccountId	long	L'ID de compte Rokt associé à l'offre
CampaignId	string	ID de la campagne liée dans OP
Creative	Creative	Créatif de l'offre défini dans OP
Metadata	string	Contient des métadonnées liées à l'offre

Creative

Nom de la propriété	Type	Description
ReferralCreativeId	string	ID associé à la configuration de la création
InstanceGuid	string	GUID représentant une instance spécifique de la création
Copy	Map<string, string>	Contient le texte lié au contenu de l'offre
ResponseOptionsMap	Map<string, ResponseOption>	Configuration pour les boutons CTA
Links	Map<string, Link>	Liens disponibles pour l'offre, référencés par le schéma de mise en page
Images	Map<string, Image>	Images disponibles pour l'offre, référencées par le schéma de mise en page
Icons	Map<string, Icon>	Icônes disponibles pour l'offre, référencées par le schéma de mise en page
Token	string	JWT d'intégrité des données au niveau de la création

Police

Nom de la propriété	Type de données	Description
FontFamily	string	Spécifie la famille de polices (par exemple, Arial, Helvetica).
FontStyle	string	Spécifie le style de police (par exemple, normal, italique).
FontWeight	string	Spécifie le poids de la police (par exemple, normal, gras).
Src	string[]	Un tableau d'URL sources ou de chemins pour les fichiers de police.

Option de Réponse

Nom de la propriété	Type de données	Description
action	string	L'action de la réponse
responseOptionGuid	string	Un GUID généré qui est unique pour l'option de réponse et à envoyer 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

Réponse d'erreur de requête (HTTP 4xx)

Racine/Corps

Nom de la propriété	Type	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

Erreur

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

Corps de la réponse réussie

Réponse de Succès

Cliquez pour développer

{
    "sessionId": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
    "pageContext": {
        "pageInstanceGuid": "b1fb003c-e905-4375-91bd-242e74b12277",
        "pageId": "6b1214f0-43e1-447d-b0bb-cf493d361411",
        "language": "en",
        "isPageDetected": true,
        "pageVariantName": "iOSVaraint1",
        "token": "<JWT token placeholder>"
    },
    "plugins": [
        {
            "plugin": {
                "id": "3353172846080032866",
                "name": "dcui",
                "url": "https://wsdk.rokt.com/plugins/dcui/index.html",
                "targetElementSelector": "#target_element",
                "targetElementPosition": "append",
                "targetElementRelation": "child",
                "targetSection": "None",
                "config": {
                    "slots": [
                        {
                            "instanceGuid": "8f492d28-83fb-4813-877e-26e752ea9474",
                            "offer": {
                                "campaignId": "2749386944931233793",
                                "accountId": "106",
                                "maxTotalItemsQtyInOffer": 1,
                                "creative": {
                                    "referralCreativeId": "2760914349384466797",
                                    "instanceGuid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
                                    "responseOptionsMap": {
                                        "positive": {
                                            "id": "2760914349384466794",
                                            "action": "Url",
                                            "instanceGuid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "Oui",
                                            "longLabel": "Oui",
                                            "shortSuccessLabel": "Email Envoyé",
                                            "isPositive": true,
                                            "url": "http://example.com",
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
```json
                                    },
                                        "negative": {
                                            "id": "2760914349384466796",
                                            "action": "CaptureOnly",
                                            "instanceGuid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "Non merci",
                                            "longLabel": "Non merci",
                                            "isPositive": false,
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        }
                                    },
                                    "links": {
                                        "termsAndConditions": {
                                            "url": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797",
                                            "title": "Conditions Générales"
                                        }
                                    },
                                    "images": {},
                                    "icons": {},
                                    "token": "<JWT token placeholder>",
                                    "advertiser": {
                                        "name": "000. Pour Test de Widget",
                                        "brand": "000. Pour Test de Widget"
                                    },
                                    "copy": {
                                        "creative.copy": "Nicholas Grasevski 2",
                                        "creative.termsAndConditions.message": "Veuillez visiter [rokt.com](https://www.rokt.com) pour les CGU",
                                        "creative.termsAndConditions.close.copy": "Fermer",
                                        "creative.termsAndConditions.title": "Conditions Générales",
                                        "creative.tag": "Services B2B",
                                        "creative.success.title": "Succès",
                                        "creative.success.copy": "Nous avons envoyé une confirmation à test1593754986316@rokt.com.",

```                                        "creative.termsAndConditions.link": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797"
                                    }
                                },
                                "metadata": {}
                            },
                            "layoutVariant": {
                                "layoutVariantId": "3353172846080032865",
                                "moduleName": "standard-marketing",
                                "formatType": "Texte",
                                "layoutVariantSchema":"<JSON encoded schema>"
                            },
                            "token": "<JWT token placeholder>"
                        },
                    ],
                    "instanceGuid": "ce5158a9-dc59-4a97-9006-a299901e4587",
                    "outerLayoutSchema": "<JSON encoded schema>",
                    "layoutSchemaVersion": "2.0",
                    "token": "<JWT token placeholder>"
                }
            },
            "fonts": []
        }
    ],
    "options": {
        "useDiagnosticEvents": true
    },
    "success": true
}

Réponse de succès vide

Il existe une occurrence rare où il n'y aura pas d'offres pertinentes pour un utilisateur particulier. Les chances que cela se produise peuvent être réduites en fournissant plus de données d'attribut lors de la requête. Dans ce cas, Rokt renverra une charge utile sans expériences :

{
    "sessionId": "b2170028-cf39-4d23-849d-f1c38be50000",
    "pageContext": {
        "pageInstanceGuid": "b2170028-cf39-4ff4-8e7d-d88eb9e441e6",
        "isPageDetected": true,
        "token": "<JWT token placeholder>"
    },
    "plugins": [],
    "options": {
        "useDiagnosticEvents": false
    },
    "token": "<JWT token placeholder>",
    "success": true,
}

Exemple : Erreur de validation de la requête

Code de réponse HTTP : 422

Cliquez pour développer

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "IntegrationNameNotProvided",
            "message": "Integration.Name is required"
        },
        {
            "code": "IntegrationVersionNotProvided",
            "message": "Integration.Version is required"
        },
        {
            "code": "IntegrationFrameworkNotProvided",
            "message": "Integration.Framework is required"
        },
        {
            "code": "IntegrationPlatformInvalid",
            "message": "Integration.Platform is invalid"
        },
        {
            "code": "IntegrationLayoutSchemaVersionNotProvided",
            "message": "Integration.LayoutSchemaVersion is required"
        },
        {
            "code": "IntegrationDeviceLocaleNotProvided",
            "message": "Integration.DeviceLocale is required"
        },
        {
            "code": "IntegrationDeviceModelNotProvided",
            "message": "Integration.DeviceModel is required"
        },
        {
            "code": "IntegrationDeviceTypeNotProvided",
            "message": "Integration.DeviceType is required"
        },
        {
            "code": "IntegrationOperatingSystemNotProvided",
            "message": "Integration.OperatingSystem is required"
        },
        {
            "code": "IntegrationOperatingSystemVersionNotProvided",
            "message": "Integration.OperatingSystemVersion is required"
        },
        {
            "code": "IntegrationPackageNameNotProvided",
            "message": "Integration.PackageName est requis"
        },
        {
            "code": "IntegrationPackageVersionNotProvided",
            "message": "Integration.PackageVersion est requis"
        },
        {
            "code": "PageIdentifierNotProvided",
            "message": "PageIdentifier est requis"
        },
        {
            "code": "PartnerIdNotProvided",
            "message": "rokt-tag-id est manquant/incorrect"
        }
    ]
}

Code de réponse HTTP : 400

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

Erreurs internes du serveur (HTTP 5xx)

Dans de rares circonstances, le 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 et un code de statut approprié conforme aux codes de réponse HTTP standard. Dans le cas où cette réponse se produit, nous recommandons de réessayer la requête après un court délai (1-2 secondes). Si le problème persiste ou se produit de manière constante, veuillez contacter le support pour aider à identifier et corriger le problème.

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 afficher les offres.

Pour améliorer les performances, nous vous recommandons de récupérer le contenu des offres à partir de l'API endpoint /v2/partner/experiences 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 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 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'informations uniques et idéalement contextuelles telles que l'ID de transaction, l'ID utilisateur et le type d'appareil utilisateur. Dans le cas d'un changement de contexte utilisateur (par exemple, d'un appareil Android à un appareil iOS), le client devrait récupérer de nouvelles expériences à partir de l'API endpoint /v2/partner/experiences en utilisant des attributs client mis à jour. Cela garantit que les offres affichées restent pertinentes pour le contexte actuel du client.

Points de terminaison​

Meilleures pratiques de test​

Requête​

En-têtes d'autorisation​

En-têtes requis​

Corps​

Intégration​

Exemple de Requête​

Réponse​

Réponse de Succès (200)​

En-têtes​

Corps de Réussite​

Racine​

SdkOptions​

PageContext​

LayoutPlugin​

Plugin​

PluginConfig​

Slot​

LayoutVariant​

Offer​

Creative​

Police​

Option de Réponse​

Réponse d'erreur de requête (HTTP 4xx)​

Racine/Corps​

Erreur​

Corps de la réponse réussie​

Réponse de Succès​

Réponse de succès vide​

Exemple : Erreur de validation de la requête​

Code de réponse HTTP : 422​

Code de réponse HTTP : 400​

Erreurs internes du serveur (HTTP 5xx)​

Mise en cache des offres​

Points de terminaison

Meilleures pratiques de test

Requête

En-têtes d'autorisation

En-têtes requis

Corps

Intégration

Exemple de Requête

Réponse

Réponse de Succès (200)

En-têtes

Corps de Réussite

Racine

SdkOptions

PageContext

LayoutPlugin

Plugin

PluginConfig

Slot

LayoutVariant

Offer

Creative

Police

Option de Réponse

Réponse d'erreur de requête (HTTP 4xx)

Racine/Corps

Erreur

Corps de la réponse réussie

Réponse de Succès

Réponse de succès vide

Exemple : Erreur de validation de la requête

Code de réponse HTTP : 422

Code de réponse HTTP : 400

Erreurs internes du serveur (HTTP 5xx)

Mise en cache des offres