Roku API¶

Apptimize provides a Roku endpoint that allows for the execution of experiments and tracking of user events on all Roku devices.

The Roku SDK is based on the Apptimize REST API, so all calls are asynchronous, and return a unique ID for each call. This ID can be used as a lookup when the content node of the Apptimize object changes. The content node will contain an object with the following structure:

{
           "id": "<ID returned from callFunc>",
           "success": "<bool: true|false>",
           "method": "<name of method called>",
           "response": "<Response Object from method>"
}

For more information on setting up Apptimize for Roku, see Roku Getting Started.

Authentication¶

Authentication is done via an Apptimize API Token, which can be found on the Install and Organization Details pages of the Apptimize dashboard. Note that the API Token is different from the App Key used with Apptimize SDKs.

The API Token should be included with the Apptimize node:

<Apptimize id="apptimize" apiToken="<API Token>"/>

User Identification and Attributes¶

UserID, PilotID, and CustomAttributes can be passed as parameters for all API Endpoints. However, they can also be set one time at the start of the Application via fields on the Apptimize node.

m.apptimize = m.top.findNode("Apptimize")

m.apptimize.userId = "<user ID>"
m.apptimize.pilotId = "<pilot targeting ID>"
m.apptimize.customAttributes = {...}

These properties are used for all API endpoints, but can be overwritten by passing them directly into the method parameter set as well.

API Endpoints¶

Because the Roku SDK utilizes REST, use the appropriate REST endpoint for your account’s geographic region, either North America or Europe. Our EU cloud site is identical to our NA site in every way, except that all data is handled within the EU, with traffic routed over EU-specific APIs.

You can specify the proper region using the region parameter on the Apptimize node:

<Apptimize id="apptimize" region="<default|eucs>"/>

Experiments API¶

The Experiment endpoints provide information on which variant a given user has been allocated into for a specific A/B Eperiment or Feature Flag. If the Experiment is targeted using either the application attributes above or custom user attributes, make sure you include these optional parameters in each request.

Code Block¶

Retrieve the Code Block variant for a user. Making this call will result in the user being marked as a participant in the given experiment.

Method	Parameters
getCodeBlock	userid: `String` Customer-provided user ID pilotid: `String` (optional) Customer pilot targeting ID name: `String` Name of the code block variable from the Apptimize dashboard customAttributes: `AssocArray` (optional) Attributes associated with the user

m.id = m.apptimize.callFunc("getCodeBlock", {userid: "<userid>", name: "<code block name>", customAttributes: {}})

{
           "codeBlockVariant": "{baseline|variation#}"
}

Dynamic Variable¶

Retrieve the Dynamic Variable value for a user. Making this call will result in the user being marked as a participant in the given experiment.

Method	Parameters
getInt	userid: `String` Customer-provided user ID pilotid: `String` (optional) Customer pilot targeting name: `String` Name of the code block variable from the Apptimize dashboard defaultValue: `<Variable>` The default value to return if in original experiment customAttributes: `AssocArray` (optional) Attributes associated with the user
getString
getDouble
getBool
getIntArray
getStringArray
getDoubleArray
getBoolArray
getIntDictionary
getStringDictionary
getDoubleDictionary
getBoolDictionary

m.id = m.apptimize.callFunc("getInt", {userid: "<userid>", name: "<code block name>", customAttributes: {}})

{
           "value": <value>
}

Feature Flag¶

Retrieve the Feature Flag status (on or off) for a user.

Method	Parameters
isFeatureFlagEnabled	userid: `String` Customer-provided user ID pilotid: `String` (optional) Customer pilot targeting ID name: `String` Name of the Feature Flag variable from the Apptimize dashboard customAttributes: `AssocArray` (optional) Attributes associated with the user

m.id = m.apptimize.callFunc("isFeatureFlagEnabled", {userid: "<userid>", name: "<feature flag name>", customAttributes: {}})

{
           "isFeatureFlagEnabled": {true|false}
}

Variant Info¶

Retrieve detailed information about the experiments a given user is enrolled in.

Method	Parameters
getVariantInfo	userid: `String` Customer-provided user ID pilotid: `String` (optional) Customer pilot targeting ID customAttributes: `AssocArray` (optional) Attributes associated with the user

m.id = m.apptimize.callFunc("getVariantInfo", {userid: "<userid>", customAttributes: {}})

{
           "variants": [list of variant objects]
}

{
           "variantName": "<string>",
           "variantID": "<number>",
           "experimentName": "<string>",
           "experimentType": "<string>",
           "experimentID": "<number>",
           "cycle": "<number>",
           "currentPhase": "<number>"
}

Events API¶

The Events endpoint allows you to providing tracking data for a given user. These events can then be used as goals in order to measure the success of an experiment.

Track an Event¶

Log an event associated with a user.

Method	Parameters
track	userid: `String` Customer-provided user ID pilotid: `String` (optional) Customer pilot targeting ID name: `String` Name of the event to track value: `Number` (optional) Value associated with the user customAttributes: `AssocArray` (optional) Attributes associated with the user

m.id = m.apptimize.callFunc("track", {userid: "<userid>", name: "<event name>", value: <number value>, customAttributes: {}})

{}