Skip to main content

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

EnvironmentActionURL
ProductionPOSThttps://server-api.rokt.com/v2/partner/experiences
TestingPOSThttps://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-keyRequiredDescriptionTypeNote
rokt-pub-idYesContains the provided client public idstringThis will be provided by Rokt.
rokt-secretYesContains the provided client public secret which must match the public idstringThis will be provided by Rokt.

Required Headers

Header-keyRequiredDescriptionTypeExample
content-typeYesMedia typestring“application/json”
acceptYesExpected media type of responsestring“application/json”
rokt-tag-idYesRokt Tag IDstring1234567890

Body

Property NameRequiredDataTypeDescription
sessionIdNostringSession ID of the existing Rokt Session, if exists
pageIdentifierYesstringText used to differentiate views
attributesYesMap<string, string>Holds user attribute data to be used during offer selection
integrationYesIntegrationData relating to the integration making the request. This can be obtained from the UXHelper libraries available for Android, iOS and web

Integration

Property NameRequiredDataTypeDescription
nameYesstringIndicates the common name of the integration making the request
versionYesstringVersion of the integration making the request
frameworkYesstringintegration framework being utilized (e.g., Flutter, React Native)
platformYesstring/enumPartner platform requesting offers (e.g., Web, Mobile, iOS)
layoutSchemaVersionYesstringHighest compatible schema version for the integration
deviceLocaleYesstringLocale setting from the user’s device
deviceModelYesstringDevice Model for iOS or Build Model for Android
deviceTypeYesstringType of device/form factor (e.g., Phone, Tablet)
operatingSystemYesstringOperating system of the user’s device
operatingSystemVersionYesstringOS version of the user’s device
packageNameYesstringPackage name or bundle identifier of the host application
packageVersionYesstringPackage version or bundle version of the host application
metadataNoMap<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-keyDescription
rokt-account-idAccount ID for which offers were served
rokt-session-idAssociated Rokt Session ID
etagRokt etag value for the user

Success Body

Root

Property NameTypeDescription
PageContextPageContextData relating to the detected page
PluginsLayout[]Plugin object and fonts
SessionIdstringRokt Session ID. For Web, this Session ID is consumed from the header
SuccessboolIndicates whether the request was successful or invalid
TokenstringSession level Data Integrity JWT
OptionsSdkOptionsCollection of runtime configuration to be provided to consuming Rokt SDKs

SdkOptions

Property NameTypeDescription
UseDiagnosticEventsboolIndicates whether Rokt SDK should output diagnostics

PageContext

Property NameTypeDescription
IsPageDetectedboolIndicates if the request resulted in matching a Partner page
PageIdstringGUID representing the matched OP Page configuration
PageInstanceGuidstringGUID representing a specific instance of the selected page
PageVariantNamestringName of the selected Page Variant
PartnerContentTemplatestringTemplate used for Payments experiences
RoktTagIdstringPartner/Advertiser Tag ID
TokenstringPage level Data Integrity JWT

LayoutPlugin

Property NameTypeDescription
FontsFont[]Array of Fonts to be leveraged by SDKs for the offer
PluginPluginPlugin configuration

Plugin

Property NameTypeDescription
ConfigPluginConfigDefines config for rendering the layout
IdstringLayout ID / Transaction Layout External ID
NamestringName of the plugin to be used for rendering
TargetElementPositionstringAction for position placement based on targetElementSelector
TargetElementRelationstringRelationship between placement and targetElementSelector
TargetElementSelectorstringIdentified position to place layout within the page
TargetSectionstringIdentifies different targeting types, e.g., Thank You page
UrlstringURL to download the plugin

PluginConfig

Property NameTypeDescription
InstanceGuidstringGUID representing a specific instance of the plugin / layout
LayoutSchemaVersionstringVersion of the layout schema used for the layout
OuterLayoutSchemastringJSON schema defining the UI of the Outer Layout
SlotsSlot []Collection of offer slots
TokenstringPlugin / Layout level Data Integrity JWT

Slot

Property NameTypeDescription
InstanceGuidstringGUID representing a specific instance of the Slot
LayoutVariantLayoutVariantDefinition of the LayoutVariant to be used for the Slot / Offer
OfferOfferDefinition of the Offer to be used for display for our customers
TokenstringPlugin / Layout level Data Integrity JWT

LayoutVariant

Property NameTypeDescription
LayoutVariantIdstringAutogenerated ID
ModuleNamestringThe Layout Module name
FormatTypestringFormat type to display an offer
LayoutVariantSchemastringJSON schema defining the UI to render the offers which leverage the variant

Offer

Property NameTypeDescription
AccountIdlongThe Rokt account ID associated with the offer
CampaignIdstringID of the linked campaign in OP
CreativeCreativeOffer creative defined in OP
MetadatastringContains metadata related to the offer

Creative

Property NameTypeDescription
ReferralCreativeIdstringID associated with the creative configuration
InstanceGuidstringGUID representing a specific instance of the Creative
CopyMap<string, string>Contains text related to the offer content
ResponseOptionsMapMap<string, ResponseOption>Configuration for CTA buttons
LinksMap<string, Link>Links available for the offer, references by Layout Schema
ImagesMap<string, Image>Images available for the offer, references by Layout Schema
IconsMap<string, Icon>Icons available for the offer, references by Layout Schema
TokenstringCreative level Data Integrity JWT

Font

Property NameData TypeDescription
FontFamilystringSpecifies the font family (e.g., Arial, Helvetica).
FontStylestringSpecifies the font style (e.g., normal, italic).
FontWeightstringSpecifies the font weight (e.g., normal, bold).
Srcstring[]An array of source URLs or paths for the font files.

Response Option

Property NameDataTypeDescription
actionstringThe action of the response
responseOptionGuidstringA GUID generated which is unique to the response option and to be sent as a part of events calls
signalTypestringThe EventType to use when sending event upon interaction. This will almost always be SignalResponse
labelstringLabel to be displayed on button/link
successTextstringText to be displayed upon interaction (not relevant for the pilot)
isPositivebooleanIndicates whether the response is a positive or negative engagement
urlstringURL on which to perform the action

Request Error Response (HTTP 4xx)

Root/Body

Property NameTypeDescription
titlestringTop level failure reason
statusnumberHTTP Status code
successbooleanIndicates whether the request was successful
errorsError[]Collection of Validation Errors which occurred

Error

Property NameTypeDescription
codestringCorresponding error code
messagestringMessage describing the error
valuebooleanProvided 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.

Was this article helpful?