V2 Partner Experiences API
This document outlines the relevant endpoints necessary to interact with Rokt's APIs to retrieve Experiences content from Rokt. The endpoint is designed to serve offer-powered experiences directly to partners. Requests are sent to this endpoint, and the response is passed to the UX Helper library for proper handling.
Endpoints
Environment | Action | URL |
---|---|---|
Production | POST | https://server-api.rokt.com/v2/partner/experiences |
Testing | POST | https://server-api-demo.rokt.com/v2/partner/experiences |
Testing Best Practice
The testing endpoint https://server-api-demo.rokt.com/v2/partner/experiences
is specifically designed for testing and should be used to validate the integration without affecting production data or performance. Ensure the appropriate headers and request formats are used as specified in the API documentation to emulate production-like scenarios effectively.
Request
Authorization Headers
Please work with your Account Manager to obtain the necessary credentials to interact with this endpoint
Header-key | Required | Description | Type | Note |
---|---|---|---|---|
rokt-pub-id | Yes | Contains the provided client public id | string | This will be provided by Rokt. |
rokt-secret | Yes | Contains the provided client public secret which must match the public id | string | This will be provided by Rokt. |
Required Headers
Header-key | Required | Description | Type | Example |
---|---|---|---|---|
content-type | Yes | Media type | string | “application/json” |
accept | Yes | Expected media type of response | string | “application/json” |
rokt-tag-id | Yes | Rokt Tag ID | string | 1234567890 |
Body
Property Name | Required | DataType | Description |
---|---|---|---|
sessionId | No | string | Session ID of the existing Rokt Session, if exists |
pageIdentifier | Yes | string | Text used to differentiate views |
attributes | Yes | Map<string, string> | Holds user attribute data to be used during offer selection |
integration | Yes | Integration | Data relating to the integration making the request. This can be obtained from the UXHelper libraries available for Android, iOS and web |
Integration
Property Name | Required | DataType | Description |
---|---|---|---|
name | Yes | string | Indicates the common name of the integration making the request |
version | Yes | string | Version of the integration making the request |
framework | Yes | string | integration framework being utilized (e.g., Flutter, React Native) |
platform | Yes | string/enum | Partner platform requesting offers (e.g., Web, Mobile, iOS) |
layoutSchemaVersion | Yes | string | Highest compatible schema version for the integration |
deviceLocale | Yes | string | Locale setting from the user’s device |
deviceModel | Yes | string | Device Model for iOS or Build Model for Android |
deviceType | Yes | string | Type of device/form factor (e.g., Phone, Tablet) |
operatingSystem | Yes | string | Operating system of the user’s device |
operatingSystemVersion | Yes | string | OS version of the user’s device |
packageName | Yes | string | Package name or bundle identifier of the host application |
packageVersion | Yes | string | Package version or bundle version of the host application |
metadata | No | Map<string, string> | Additional data related to integration or device |
Request Example
JSON Request Body/Payload
Click to expand
{
"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"
}
},
}
Response
Success Response (200)
Headers
These headers will be returned for consistency with other Ecommerce APIs, but there is no expectation that they will be consumed by the partner or the UX library.
Header-key | Description |
---|---|
rokt-account-id | Account ID for which offers were served |
rokt-session-id | Associated Rokt Session ID |
etag | Rokt etag value for the user |
Success Body
Root
Property Name | Type | Description |
---|---|---|
PageContext | PageContext | Data relating to the detected page |
Plugins | Layout[] | Plugin object and fonts |
SessionId | string | Rokt Session ID. For Web, this Session ID is consumed from the header |
Success | bool | Indicates whether the request was successful or invalid |
Token | string | Session level Data Integrity JWT |
Options | SdkOptions | Collection of runtime configuration to be provided to consuming Rokt SDKs |
SdkOptions
Property Name | Type | Description |
---|---|---|
UseDiagnosticEvents | bool | Indicates whether Rokt SDK should output diagnostics |
PageContext
Property Name | Type | Description |
---|---|---|
IsPageDetected | bool | Indicates if the request resulted in matching a Partner page |
PageId | string | GUID representing the matched OP Page configuration |
PageInstanceGuid | string | GUID representing a specific instance of the selected page |
PageVariantName | string | Name of the selected Page Variant |
PartnerContentTemplate | string | Template used for Payments experiences |
RoktTagId | string | Partner/Advertiser Tag ID |
Token | string | Page level Data Integrity JWT |
LayoutPlugin
Property Name | Type | Description |
---|---|---|
Fonts | Font[] | Array of Fonts to be leveraged by SDKs for the offer |
Plugin | Plugin | Plugin configuration |
Plugin
Property Name | Type | Description |
---|---|---|
Config | PluginConfig | Defines config for rendering the layout |
Id | string | Layout ID / Transaction Layout External ID |
Name | string | Name of the plugin to be used for rendering |
TargetElementPosition | string | Action for position placement based on targetElementSelector |
TargetElementRelation | string | Relationship between placement and targetElementSelector |
TargetElementSelector | string | Identified position to place layout within the page |
TargetSection | string | Identifies different targeting types, e.g., Thank You page |
Url | string | URL to download the plugin |
PluginConfig
Property Name | Type | Description |
---|---|---|
InstanceGuid | string | GUID representing a specific instance of the plugin / layout |
LayoutSchemaVersion | string | Version of the layout schema used for the layout |
OuterLayoutSchema | string | JSON schema defining the UI of the Outer Layout |
Slots | Slot [] | Collection of offer slots |
Token | string | Plugin / Layout level Data Integrity JWT |
Slot
Property Name | Type | Description |
---|---|---|
InstanceGuid | string | GUID representing a specific instance of the Slot |
LayoutVariant | LayoutVariant | Definition of the LayoutVariant to be used for the Slot / Offer |
Offer | Offer | Definition of the Offer to be used for display for our customers |
Token | string | Plugin / Layout level Data Integrity JWT |
LayoutVariant
Property Name | Type | Description |
---|---|---|
LayoutVariantId | string | Autogenerated ID |
ModuleName | string | The Layout Module name |
FormatType | string | Format type to display an offer |
LayoutVariantSchema | string | JSON schema defining the UI to render the offers which leverage the variant |
Offer
Property Name | Type | Description |
---|---|---|
AccountId | long | The Rokt account ID associated with the offer |
CampaignId | string | ID of the linked campaign in OP |
Creative | Creative | Offer creative defined in OP |
Metadata | string | Contains metadata related to the offer |
Creative
Property Name | Type | Description |
---|---|---|
ReferralCreativeId | string | ID associated with the creative configuration |
InstanceGuid | string | GUID representing a specific instance of the Creative |
Copy | Map<string, string> | Contains text related to the offer content |
ResponseOptionsMap | Map<string, ResponseOption> | Configuration for CTA buttons |
Links | Map<string, Link> | Links available for the offer, references by Layout Schema |
Images | Map<string, Image> | Images available for the offer, references by Layout Schema |
Icons | Map<string, Icon> | Icons available for the offer, references by Layout Schema |
Token | string | Creative level Data Integrity JWT |
Font
Property Name | Data Type | Description |
---|---|---|
FontFamily | string | Specifies the font family (e.g., Arial, Helvetica). |
FontStyle | string | Specifies the font style (e.g., normal, italic). |
FontWeight | string | Specifies the font weight (e.g., normal, bold). |
Src | string[] | An array of source URLs or paths for the font files. |
Response Option
Property Name | DataType | Description |
---|---|---|
action | string | The action of the response |
responseOptionGuid | string | A GUID generated which is unique to the response option and to be sent as a part of events calls |
signalType | string | The EventType to use when sending event upon interaction. This will almost always be SignalResponse |
label | string | Label to be displayed on button/link |
successText | string | Text to be displayed upon interaction (not relevant for the pilot) |
isPositive | boolean | Indicates whether the response is a positive or negative engagement |
url | string | URL on which to perform the action |
Request Error Response (HTTP 4xx)
Root/Body
Property Name | Type | Description |
---|---|---|
title | string | Top level failure reason |
status | number | HTTP Status code |
success | boolean | Indicates whether the request was successful |
errors | Error[] | Collection of Validation Errors which occurred |
Error
Property Name | Type | Description |
---|---|---|
code | string | Corresponding error code |
message | string | Message describing the error |
value | boolean | Provided value that was invalid, if any |
Success Response Body
Success Response
Click to expand
{
"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
}
Empty Success Response
There is a rare occurrence where there will not be any relevant offers for a particular user. The chances of this occurring can be reduced by providing more attribute data when making the request. In the event of this case, Rokt will return a payload with no experiences:
{
"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,
}
Example: Request Validation Error
HTTP Response Code: 422
Click to expand
{
"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"
}
]
}
HTTP Response Code: 400
{
"title": "BadRequest",
"status": 400,
"success": false,
"errors": [
{
"code": "InvalidRequestPayload",
"message": "Request body format is not valid"
}
]
}
Internal Server Errors (HTTP 5xx)
In rare circumstances the system may unexpectedly be unable to complete a request, in this case we will return a request without a body and an appropriate status code that complies with standard HTTP response codes. In the case where this response occurs, we recommend that the request be retried after a brief delay (1-2 seconds). If the problem persists or consistently occurs, please reach out to support to assist in identifying and correcting the issue.
Caching offers
Rendering Rokt offers in a timely manner allows you to maximize revenue opportunities from user engagement and conversions. However, a server-to-server integration involves extra network calls between Rokt’s backend servers and yours, which delays the retrieval of data necessary for rendering offers.
To aid with performance, we recommend that you fetch offer content from Rokt’s /v2/partner/experiences
API endpoint at an earlier point in the user’s transaction journey before our offers are expected to render. It’s best practice to initiate the offer content fetch after a user has demonstrated significant interest in completing the transaction in order to avoid unnecessary network calls.
Once received, the data can be stored in a cache. This will allow faster retrieval later by the client for use within the same transaction.
We recommend caching against a combination of unique and ideally contextual information such as transaction ID, user ID, and user device type. In the scenario of a shifting user context (e.g. from an Android device to an iOS device), the client should fetch new experiences from the /v2/partner/experiences
endpoint using updated customer attributes. This ensures that rendered offers remain relevant to the customer’s present context.