API V2 Expériences Partenaires
Ce document décrit les points de terminaison pertinents nécessaires pour interagir avec les APIs 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 une gestion appropriée.
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 les performances de production. Assurez-vous que les en-têtes et les formats de requête appropriés sont utilisés comme spécifié dans la documentation API pour émuler efficacement des scénarios similaires à ceux de la production.
Requête
En-têtes d'autorisation
Veuillez travailler avec votre responsable de compte pour obtenir les identifiants nécessaires pour interagir avec ce point de terminaison
| Clé-En-tête | Obligatoire | Description | Type | Note |
|---|---|---|---|---|
| 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é-En-tête | Obligatoire | 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 | Identifiant de Tag Rokt | 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 des attributs utilisateur à utiliser lors de la sélection d'une offre |
| 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 | Framework 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/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 paquet ou identifiant du bundle de l'application hôte |
| packageVersion | Oui | string | Version du paquet 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 Requête JSON
Cliquez pour afficher
{
"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 renvoyés pour garantir la cohérence avec d'autres APIs 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 des offres ont été servies |
| rokt-session-id | ID de session Rokt associé |
| etag | Valeur etag 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 de 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 été réussie ou invalide |
| Token | string | JWT d'Intégrité des Données au niveau de la session |
| Options | SdkOptions | Collection de configuration d'exécution à fournir aux SDKs Rokt consommateurs |
SdkOptions
| Nom de Propriété | Type | Description |
|---|---|---|
| UseDiagnosticEvents | bool | Indique si le SDK Rokt doit produire des diagnostics |
PageContext
| Nom de Propriété | Type | Description |
|---|---|---|
| IsPageDetected | bool | Indique si la requête a abouti à correspondre à 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 Paiement |
| RoktTagId | string | ID 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 SDK 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 transaction |
| Name | string | Nom du plugin à utiliser pour le rendu |
| TargetElementPosition | string | Action pour le placement de la 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 ex., page de remerciement |
| Url | string | URL pour télécharger le plugin |
PluginConfig
| Nom de 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 Layout Extérieur |
| Slots | Slot [] | Collection de slots d'offre |
| Token | string | JWT d'Intégrité des Données au niveau Plugin / Layout |
Slot
| Nom de 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 à utiliser pour l'affichage à nos clients |
| Token | string | JWT d'Intégrité des Données au niveau Plugin / Layout |
LayoutVariant
| Nom de Propriété | Type | Description |
|---|---|---|
| LayoutVariantId | string | ID généré automatiquement |
| ModuleName | string | Le nom du Module Layout |
| FormatType | string | Type de format pour afficher une offre |
| LayoutVariantSchema | string | Schéma JSON définissant l'UI pour afficher les offres utilisant la variante |
Offre
| Nom de 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éation de l'offre définie dans OP |
| Metadata | string | Contient les métadonnées liées à l'offre |
Créatif
| 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 d'appel à l'action (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 créatif |
Police
| Nom de propriété | Type de données | Description |
|---|---|---|
| FontFamily | chaîne | Spécifie la famille de polices (par exemple, Arial, Helvetica). |
| FontStyle | chaîne | Spécifie le style de police (par exemple, normal, italique). |
| FontWeight | chaîne | Spécifie le poids de la police (par exemple, normal, gras). |
| Src | chaîne[] | Un tableau d'URL ou de chemins source pour les fichiers de police. |
Option de réponse
| Nom de propriété | Type de données | Description |
|---|---|---|
| action | chaîne | L'action de la réponse |
| responseOptionGuid | chaîne | Un GUID généré qui est unique à l'option de réponse et à envoyer dans le cadre des appels d'événements |
| signalType | chaîne | Le EventType à utiliser lors de l'envoi de l'événement après interaction. Ce sera presque toujours SignalResponse |
| label | chaîne | Étiquette à afficher sur le bouton/lien |
| successText | chaîne | Texte à afficher lors de l'interaction (non pertinent pour le pilote) |
| isPositive | booléen | Indique si la réponse est un engagement positif ou négatif |
| url | chaîne | 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 la 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": "fr",
"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>"
},
"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 le Test du Widget",
"brand": "000. Pour le Test du Widget"
},
"copy": {
"creative.copy": "Nicholas Grasevski 2",
"creative.termsAndConditions.message": "Veuillez visiter [rokt.com](https://www.rokt.com) pour les C&CG",
"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": "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 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'attributs lors de la demande. Dans ce cas, Rokt retournera 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 Demande
Code de Réponse HTTP : 422
Cliquez pour développer
{
"title": "Échec de la validation",
"status": 422,
"success": false,
"errors": [
{
"code": "IntegrationNameNotProvided",
"message": "Integration.Name est requis"
},
{
"code": "IntegrationVersionNotProvided",
"message": "Integration.Version est requis"
},
{
"code": "IntegrationFrameworkNotProvided",
"message": "Integration.Framework est requis"
},
{
"code": "IntegrationPlatformInvalid",
"message": "Integration.Platform n'est pas valide"
},
{
"code": "IntegrationLayoutSchemaVersionNotProvided",
"message": "Integration.LayoutSchemaVersion est requis"
},
{
"code": "IntegrationDeviceLocaleNotProvided",
"message": "Integration.DeviceLocale est requis"
},
{
"code": "IntegrationDeviceModelNotProvided",
"message": "Integration.DeviceModel est requis"
},
{
"code": "IntegrationDeviceTypeNotProvided",
"message": "Integration.DeviceType est requis"
},
{
"code": "IntegrationOperatingSystemNotProvided",
"message": "Integration.OperatingSystem est requis"
},
{
"code": "IntegrationOperatingSystemVersionNotProvided",
"message": "Integration.OperatingSystemVersion est requis"
},
{
"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 du serveur interne (HTTP 5xx)
Dans de rares circonstances, le système peut être incapable 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 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 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 provenant de l'engagement des utilisateurs et des conversions. Cependant, une intégration serveur à serveur implique des appels réseaux 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 vous recommandons de récupérer le contenu des offres depuis le point d'accès API /v2/partner/experiences de Rokt à un point 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éseaux 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 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 de l'utilisateur. Dans le cas d'un changement de contexte utilisateur (par exemple d'un appareil Android à un appareil iOS), le client doit récupérer de nouvelles expériences depuis le point d'accès /v2/partner/experiences en utilisant des attributs client mis à jour. Cela garantit que les offres affichées restent pertinentes pour le contexte présent du client.