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>"/>

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
  • name: String Name of the code block variable from the Apptimize dashboard
  • customAttributes: AssocArray (optional) Attributes associated with the user

Sample

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

Response Object

{
    "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
  • 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

Sample

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

Response Object

{
    "value": <value>
}

Feature Flag

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

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

Sample

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

Response Object

{
    "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
  • customAttributes: AssocArray (optional) Attributes associated with the user

Sample

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

Response Object

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

Variant Object

{
    "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
  • name: String Name of the event to track
  • value: Number (optional) Value associated with the user
  • customAttributes: AssocArray (optional) Attributes associated with the user

Sample

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

Response Object

{}