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 fournir 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
Test	POST	https://server-api-demo.rokt.com/v2/partner/experiences

Meilleure pratique 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 la performance de 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ê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é d'en-tête	Requis	Description	Type	Remarque
rokt-pub-id	Oui	Contient l'identifiant public client fourni	string	Ceci sera fourni par Rokt.
rokt-secret	Oui	Contient le secret public client fourni qui doit correspondre à l'identifiant public	string	Ceci sera fourni par Rokt.

En-têtes requis

Clé d'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	ID de Tag Rokt	string	1234567890

Corps

Nom de la propriété	Obligatoire	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 attribute de l'utilisateur à utiliser lors de la sélection des 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é	Obligatoire	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 de l'appareil de l'utilisateur
deviceModel	Oui	string	Modèle d'appareil pour iOS ou modèle de construction pour Android
deviceType	Oui	string	Type d'appareil/facteur de forme (par exemple, Téléphone, Tablette)
operatingSystem	Oui	string	Système d'exploitation de l'appareil de l'utilisateur
operatingSystemVersion	Oui	string	Version du système d'exploitation de l'appareil 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 à l'appareil

Exemple de Demande

Corps/Payload de la Demande 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 Rokt pour l'utilisateur

Corps de Succès

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 demande 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 demande 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 mise en page de transaction
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 / mise en page
LayoutSchemaVersion	string	Version du schéma de mise en page utilisé pour la mise en page
OuterLayoutSchema	string	Schéma JSON définissant l'interface utilisateur de la mise en page extérieure
Slots	Slot []	Collection de créneaux d'offre
Token	string	JWT d'intégrité des données au niveau du plugin / mise en page

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 / l'Offre
Offer	Offer	Définition de l'Offre à afficher pour nos clients
Token	string	Plugin / Niveau de mise en page JWT d'intégrité des données

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 créative
InstanceGuid	string	GUID représentant une instance spécifique du Créatif
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	Niveau créatif JWT d'intégrité des données

Font

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 ou de chemins sources 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 comme partie 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

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

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 Réponse de Succès

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": "Yes",
                                            "longLabel": "Yes",
                                            "shortSuccessLabel": "Email Sent",
                                            "isPositive": true,
                                            "url": "http://example.com",
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        },
                                        "negative": {
                                            "id": "2760914349384466796",
                                            "action": "CaptureOnly",
                                            "instanceGuid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "No thanks",
                                            "longLabel": "No thanks",
                                            "isPositive": false,
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        }
                                    },
                                    "links": {
                                        "termsAndConditions": {
                                            "url": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797",
                                            "title": "Terms & Conditions"
                                        }
                                    },
                                    "images": {},
                                    "icons": {},
                                    "token": "<JWT token placeholder>",
                                    "advertiser": {
                                        "name": "000. For Widget Testing",
                                        "brand": "000. For Widget Testing"
                                    },
                                    "copy": {
                                        "creative.copy": "Nicholas Grasevski 2",
                                        "creative.termsAndConditions.message": "Please visit [rokt.com](https://www.rokt.com)for T&Cs",
                                        "creative.termsAndConditions.close.copy": "Close",
                                        "creative.termsAndConditions.title": "Terms & Conditions",
                                        "creative.tag": "B2B Services",
                                        "creative.success.title": "Success",
                                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com.",
                                        "creative.termsAndConditions.link": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797"
                                    }
                                },
                                "metadata": {}
                            },
                            "layoutVariant": {
                                "layoutVariantId": "3353172846080032865",
                                "moduleName": "standard-marketing",
                                "formatType": "Text",
                                "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 un cas 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'attributs 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 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 is required"
        },
        {
            "code": "IntegrationPackageVersionNotProvided",
            "message": "Integration.PackageVersion is required"
        },
        {
            "code": "PageIdentifierNotProvided",
            "message": "PageIdentifier is required"
        },
        {
            "code": "PartnerIdNotProvided",
            "message": "rokt-tag-id is missing/incorrect"
        }
    ]
}

Code de Réponse HTTP : 400

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

Erreurs de Serveur Interne (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 renverrons une requête sans corps et un code de statut approprié qui respecte les 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 bref délai (1-2 secondes). Si le problème persiste ou se produit de manière constante, veuillez contacter le support pour vous aider à identifier et corriger le problème.

Mise en cache des offres

Afficher les offres Rokt en temps opportun vous permet de maximiser les opportunités de revenus grâce à l'engagement et aux conversions des utilisateurs. 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 aider à la performance, nous recommandons de récupérer le contenu des offres à partir du point de terminaison API /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 s'afficher. Il est préférable de lancer la récupération du contenu des offres après qu'un utilisateur a 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'informations uniques et idéalement contextuelles telles que l'ID de transaction, l'ID utilisateur et le 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 nouvelles expériences à partir du point de terminaison /v2/partner/experiences en utilisant des attributs client mis à jour. Cela garantit que les offres affichées restent pertinentes au contexte actuel du client.