Last modified September 19, 2018 by Shelly Wolfe

Roku

Swrve is a multi-channel customer engagement platform that provides hyper-targeting and hyper-personalization in real-time to automate relevant moments of interaction that acquire, retain and monetize customers.
The Swrve native Roku SDK enables your app to use all of these features on the Roku OTT platform. This guide contains all the information you need to integrate the SDK into your Roku TV channel.

Requirements

  • The Swrve Roku SDK supports Roku firmwares versions 7.7.2 and later.
  • The App ID and API Key for your Swrve app. This information is available on the Integration Settings screen (on the Settings menu, select Integration settings).

Installing the SDK

Step 1: Download the SDK from the GitHub public repository or download a .zip file of the latest Roku SDK.

Step 2: Copy the SwrveSDK folder into your project’s source/ folder, at the same level as your Main file.

Step 3: Copy the SwrveComponents folder into your components/ folder.


Basic integration

After you have installed the SDK, complete the following steps for a basic integration.

Step 1: In your Main.brs, create a config object that can contain customization values. Replace <app_id> and <api_key> with your app ID and API key.

For more information about the parameters you can include in your configuration, see below.

Step 2: When you create a screen element for your channel, you create a Port object that lets you listen for events from the channel. Use the same Port object to initialize the Swrve SDK.

Step 3: If you haven’t already done so, create a global instance from the screen element:

Step 4: In the main loop, you need to process incoming activity with a Swrve Listener. In the while loop in your main file, add the swrveListener as follows:

Step 5:  After creating the screen object to add your scene, for in-app messages to display correctly on startup, ensure you only run the .show() function after you initialize the swrveClient. For example:

Import SDK files to components

To use Swrve features in a component, you must first extend the component from the base components provided by the Swrve SDK.

  • Scenes – <component name="YourSceneName" extends="SwrveBaseScene">
  • Groups – <component name="YourGroupName" extends="SwrveBaseGroup">

This extension imports all the necessary SDK files so you can use them in your component.

Configuration parameters

Depending on your data requirements, Swrve stores all customer data and content in either our US or EU data centers. If you require EU data storage, include the EU stack information in your SDK configuration to point to Swrve’s EU-based URL endpoints. If you have any questions or need assistance configuring the SDK for EU data storage, please contact support@swrve.com.
Parameter Presence Description
ApiKey Required The API key for your Swrve app.
AppID Required Your Swrve app ID.
debug Optional Debug flag, for logs and other QA features. Defaults to true.
newSessionInterval Optional Interval after which a new launch is considered as a new session. Default is 30 seconds. For information on how to change the default setting, see How Do I Configure the New Session Interval?
Stack Optional String used to target EU or US data storage. The default endpoint is us. Specify eu if you require European data storage.
flushingDelay Optional Interval at which the events queue is flushed. Default is 10 seconds.
campaignsAndResourcesDelay Optional Interval at which the SDK re-downloads the campaigns and resources.
queueMaxSize Optional Maximum size of the events buffer queue. If the size exceeds this value, the queue will be flushed immediately. Default is 1000.
mockHTTPPOSTResponses Optional Debug tool to simulate the HTTP response code of HTTP POST requests. Default is false.
mockedPOSTResponseCode Optional Status code you want to be returned when sending an HTTP POST request in debug mode.
mockHTTPGETResponses Optional Debug tool to simulate the HTTP response code of HTTP GET requests. Default is false.
mockedGETResponseCode Optional Status code you want to be returned when sending an HTTP GET request in debug mode.
Basic integration of the Swrve SDK enables you to track important metrics and run in-app message campaigns. To make use of additional Swrve features, complete the following sections as required.

User identity

Swrve supports an Identify API to find preexisting user identities that have been logged by an app either on a single device or multiple devices. You can now identify users and then track and target them safely across multiple devices, platforms, and channels. For more information, see Tracking your users with Swrve User Identity.

The external user ID is a non-discoverable key that identifies your user across multiple channels and platforms. Emails or other personally identifiable information (PIIs) are not accepted as external user IDs, they will be rejected on the server side.

Identify

Call the Identity API with your external user ID:

And then declare and define your custom callback method:

The data returned is an associative array with two key-value properties:

status: string value which can have the following properties

  • new_external_id – Identify successful with first occurrence of that external_user_id on that app recorded in Swrve.
  • existing_external_id_with_matching_swrve_id – Identify successful with the same user ID on an already identified third party external user ID.
  • existing_external_id – Identify successful with different user with a different user ID originally identified with.
  • Other error messages – In the case of a network failure or invalid parameter, we will forward the message to you so you may take the appropriate action.

swrve_id: which is the swrve_user_id

  • If we haven’t identified the user before, it will return the swrve_id sent up.
  • If we have, it will return the swrve_id on record for that user.

If the call fails, then the user will not be correctly linked on the Swrve backend system, which may affect reporting and audiences where the user is logging in on multiple devices. We recommend not queuing or sending events until the identify call completes.


In-app messages

Swrve’s in-app messages campaigns are available as soon as you complete the basic integration described above. These features enable you to send personalized messages to your app users while they’re using your app. For more information, see Intro to in-app messages.

To test in-app messages in your app, you need to first create the campaign in Swrve. For more information, see Creating in-app messages.

In-app message deeplinks

When creating in-app messages in Swrve, you can configure message buttons to direct users to perform a custom action when clicked. For example, you might configure a button to direct the app user straight to the app store to provide a rating. At present, Roku does not support the concept of URL schemes or opening a URL, so if you want to use deeplinks in your in-app messages, you need to implement your own custom callback.

For Roku, the main scene of your channel owns the in-app message screen object, so you must use the main scene to set a custom callback function, as shown below.

setCustomCallback(context, functionName as String)

For example:

Next, declare and define your custom callback method:


Sending events

The Swrve SDK automatically sends certain events and also lets you track user behavior by sending custom events. (For a list of default Swrve events, see About audience filters, Events.) In turn, you can use app-generated events to trigger in-app messages, while both app- and server-generated events help you define segments and perform in-depth analysis.

Custom events

To send a custom event from your Brightscript file, use the following structure:

SwrveEvent(instance as Object, eventName as String, payload as Object)

Return: void

Parameters

  • instance – The global instance object.
  • eventName – Name of the event. Can’t contain spaces or be nil.
  • payload – Optional and has to be an associative array (dictionary) object.

Requirements for sending custom events:

  • Do not send the same named event with different case. For example, if you send registration.start, then ensure you never send Registration.Start.
  • Use a period (.) in your event names to organize their layout in the Swrve dashboard. Each ‘.’ creates a new branch in the Event name column of the Events report, and groups your events so they are easy to locate.
  • Do not send more than 1000 unique named events.
    • Do not add unique identifiers to event names. For example, Registration.Start.ServerID-ABDCEFG
    • Do not add timestamps to event names. For example, Registration.Start.1454458885
  • Do not use the swrve.* or Swrve.* namespace for your own events. This is reserved for Swrve use only. Custom event names beginning with Swrve. are restricted and cannot be sent.

Event payloads

As shown in the above example, you can add and send an event payload with every event. This allows for more detailed reporting around events and funnels.

Notes on associated payloads:

  • The associated payload should be a dictionary of key/value pairs; it is restricted to string and integer keys and values.
  • There is a maximum cardinality of 500 key-value pairs for this payload per event. This parameter is optional, but only the first 500 payloads are displayed in the dashboard. The data is still available in raw event logs and for audience filtering.
  • If you want to use event payloads to target your campaign audiences, you can configure up to 10 custom events with a maximum of 10 payloads per event for audience filtering purposes. For more information, see Targeting your audience by event payloads.

For example, if you want to track when a user starts the registration process, it might make sense to send an event named registration.start and add a payload time that captures how much time it took the user to complete the registration.

Custom user properties

The Swrve SDK sends certain user properties by default and also enables you to assign custom properties to update the user’s status. (For a full list of the default user properties, see Assigning user properties.) When configuring custom properties for Roku, the Swrve SDK only supports string values.

SwrveUserUpdate(instance as Object, attributes as Object)

Return: void

Parameters

  • instance – The global instance object.
  • attributes – Associative array of custom attributes.

For example, you could create a custom user property called premium, and then target non-premium users and premium users in your campaigns.

Example of group of user properties

Example of single date-typed user property

Use the roDateTime object to send a DateTime user property; for example, the current date at the time of a user purchase:

Virtual economy events

To ensure virtual currency events are not ignored by the server, make sure the currency name configured in your app matches exactly the Currency Name you enter in the App Currencies section on the App Settings screen (including case-sensitive). If there is any difference, or if you haven’t added the currency in Swrve, the server will ignore the event and return an error event called Swrve.error.invalid_currency. Additionally, the ignored events are not included in your KPI reports. For more information, see Add your app.

If your app has a virtual economy, send the purchase event when users purchase in-app items with virtual currency.

SwrvePurchaseEvent(instance as Object, quantity as Integer, itemName as String, cost as Float, currency as String)

Return: void

Parameters

  • instance – The global instance object.
  • quantity – Quantity purchased, as integer.
  • itemName – Name of the item purchased.
  • cost – Cost for a single item.
  • currency – Currency name, as set up on the Swrve Dashboard.

Example

Send the currency given event when you give users virtual currency. Examples include initial currency balances, retention bonuses and level-complete rewards.

In-app purchase events

If your app has in-app purchases (IAPs), send the IAP event when a user purchases something with real money. For Roku, Swrve does not currently validate in-app purchases.

Notify Swrve when an in-app purchase occurs as follows:

SwrveProduct(name as String, ID as String, cost as Float, quantity as Integer)

Return: a product object (as associative array)

Parameters

  • name – Name of the product.
  • ID – Identifier of the product.
  • cost – Cost for a single item.
  • quantity – Quantity of this product purchased.

AddSwrveReward(rewardsObject as Object, type as String, name as String, amount as Float)

Return: void

Parameters

  • rewardsObject – Name of the product.
  • type – Identifier of the product.
  • name – Cost for a single item.
  • amount – Quantity of this product purchased.

SwrveIAPWithoutReceipt(instance as Object, product as Object, rewards as Object, localCurrency as String, store as String)

Return: void

Parameters

  • instance – SwrveSDK instance.
  • product – Product object you created.
  • rewards – Rewards dictionary you created.
  • localCurrency – Virtual currency as a string.
  • store – Store as a string.

Example


Shutting down the SDK

The Swrve Roku SDK includes the following method to let you completely shut down the SwrveSDK, clearing all temporary data and shutting off listeners. In case of shutdown, any events that are not sent are saved to persistent storage and sent to Swrve the next time the same user starts a new session.


Resource A/B testing

Integrating Swrve’s resource A/B testing functionality lets you use Swrve to test how users respond to changes to the native app content. For more information about resource A/B testing, see Intro to Resource A/B Testing.

To get the latest version of a resource from Swrve using the Resource Manager, complete the following:

Step 1: In your component, set up an observer and your callback function to receive notifications that the SDK has received and processed new campaigns or resources:

Step 2: Call the resource manager from anywhere using the instance:

You can then get a resource from the manager using the SwrveResource method.

Step 3: Add the following callback function:

SwrveResource("resource_name") returns the associated resource with the resource name in parameters. Use the following attribute methods to return a resource defined in the Swrve Dashboard.

Method Attribute Value
Attribute as String attributeAsString(“AttributeName”,”defaultValue”) Default is an empty string.
Attribute as Integer attributeAsInt(“AttributeName”, defaultValue as Int) Default is 0.
Attribute as Float attributeAsFloat(“AttributeName”, defaultValue as Float) Default is 0.0.
Attribute as Boolean attributeAsBoolean(“AttributeName”, defaultValue as Boolean) Default is false.
Attribute as Color attributeAsColour(“AttributeName”, defaultValue as String) Default is 0xFFFFFF.

If you want to view the old and new values when resources change, you can add a callback function as follows:

Step 1: Make a call to Swrve from your components:

Step 2: Set up the callback function:

Result:

The result is an array that contains two entries: old and new dictionaries of resources.


Testing your integration

After you’ve completed the above, the next step is to test the integration. For more information, see Testing your integration.