The BlueConic SDK for Roku makes it easy for developers to collect profile data from their CTV Roku apps.
You can use the SDK to do the following:
Capture customer journey events by capturing each page view interaction
Set and retrieve profile property values to enrich the customer profile or app experience
Personalize the app experience through dialogues
Enhance user behavior insights by using listeners
The BlueConic SDK for Roku provides the basis for communication with BlueConic.
Before you begin
Before you start implementing the SDK, make sure you meet the following requirements:
Set up your CTV Roku application in BlueConic and enable it. To do that, follow the steps described in the article Enabling a CTV app for BlueConic.
Roku SDK 12.0+
Roku Device
Note: It is recommended that you develop using Visual Studio Code with the Brightscript Plugin. The BlueConic SDK release is compiled using the BrighterScript language superset.
Getting started
Note: The latest SDK version is 1.0.0.
Before you start implementing the SDK, perform the following tasks:
Add the SDK to your project
Navigate to the release section of the Roku SDK repository and download the latest release package: https://github.com/blueconic/blueconic-roku-sdk/releases
Copy the contents of
sourceandcomponentsfolders into your project'spkg:/source/andpkg:/components/folders. Make sure that there is a subfolder namedblueconicin each of your project'ssourceandcomponentsfolders.
Configure the SDK
m.global = screen.getGlobalNode() ' Get the Global Node
configurationBuilder = BlueConicConfigurationBuilder()
configurationBuilder.setHostName([BlueConic server url]) ' Replace with hostname of the BlueConic server
configurationBuilder.setOverrideAppId([Overriding app id]) ' Set this if you need your channel ID to be different
configurationBuilder.build(m.global)
Using the BlueConic Roku SDK
Import the SDK dependency
Include the BlueConicClient.brs BrightScript file dependency in each of your application's scene .xml files.
<script type="text/brightscript" uri="pkg:/source/blueconic/BlueConicClient.brs"/>
This allows you to retrieve the BlueConicClient instance.
m.blueConicClient = getBlueConicClientInstance()
Create a page view event
To keep track of every scene viewed in the app, you need to create a page view event. Make sure that a unique screen name is passed in the call. The screen name can be used in listener rules or to restrict interactions to specific screens.
m.blueConicClient = getBlueConicClientInstance()
m.blueConicClient.createPageViewEvent("screenName", properties)
The "screenName" property sent via a PAGEVIEW event is used by BlueConic to identify the location in the app.
Now the BlueConic user can retrieve the screen name "Main/Section1" as a value like so (using the regular expression (.*)):
The BlueConic user can add values when the Screen name contains certain words. Create a rule of type "URL / Mobile Screen" and configure the Screen name to listen to:
Once the "PAGEVIEW" event was triggered, the current screen name is saved in the SDK. You can use this value to validate that the SDK is currently registered to the desired screen. To retrieve the value, use the following method:
m.blueConicClient.getScreenName(sub(screenName)
print "Screen name: " + screenName
end sub)
Configure consent
In order to configure the consent information for the BlueConic SDK you can use the following methods:
' Get the SDK privacy legislation.
m.blueConicClient.profile().getPrivacyLegislation(sub(privacyLegislation)
print "Privacy Legislation: " + privacyLegislation
end sub)
' Configure the SDK privacy legislation (e.g. GDPR, CCPA).
m.blueConicClient.profile().setPrivacyLegislation("GDPR")
' Add consented objective.
' First, the objectives need to be configured in the BlueConic platform.
m.blueConicClient.profile().addConsentedObjective("Marketing")
' Add refused objective.
' First, the objectives need to be configured in the BlueConic platform.
m.blueConicClient.profile().addRefusedObjective("Tracking")
To configure consent information in BlueConic read more about it in the following article: Privacy management in BlueConic.
Create a timeline event
The BlueConic SDK supports the ability to send timeline events using the following dedicated methods:
' Set the properties of the timeline event.
properties = {
"test": "testvalue",
"testnested": {
"nestedtesttext": "nested text",
"nestedtestnumber": 123,
"nestedtestbool": true
}
}
' Trigger the timeline event.
' Note that when using this method, the ID of the timeline event will be an automatically generated UUID.
m.blueConicClient.createTimelineEvent("MY_TIMELINE_EVENT", (CreateObject("roDateTime").asSecondsLong()*1000).toStr(), properties)
' Trigger the timeline event by ID.
m.blueConicClient.createTimelineEventById("MY_TIMELINE_ID", "MY_TIMELINE_EVENT", (CreateObject("roDateTime").asSecondsLong()*1000).toStr(), properties)
To learn more about timeline events and how to configure them in BlueConic, check out the following article: Overview: Timeline events in BlueConic.
Gather profile information
When you first interact with BlueConic using the SDK a profile ID is generated. This profile ID can be used to identify users in BlueConic. To retrieve the BlueConic assigned profile ID, you can use the following method:
m.blueConicClient.profile().getId(sub(profileId)
print "Profile ID: " + profileId
end sub)
The BlueConic SDK supports the ability to get or set a profile property directly from inside the app. Ask your BlueConic users for the ID of the profile property in BlueConic and use one or more of the following BlueConic methods from the SDK:
' Get profile property value
m.blueConicClient.profile().getValue("propertyKey", sub(value)
print "Value: " + value
end sub)
' Get profile property values (for multi-value properties)
m.blueConicClient.profile().getValues("propertyKey", sub(values)
print "Values: " + values
end sub)
' Set profile property value
' Passing a property that was already set with values will cause for the old values to be removed.
m.blueConicClient.profile().setValue("propertyKey", "propertyValue")
' Set profile property values (for multi-value properties)
' Passing a property that was already set with values will cause for the old values to be removed.
m.blueConicClient.profile().setValues("propertyKey", ["propertyValue1", "propertyValue2"])
' Add profile property value
' If there are already values for a property the new value will be added.
m.blueConicClient.profile().addValue("propertyKey", "propertyValue")
' Add profile property values (for multi-value properties)
' If there are already values for a property the new values will be added.
m.blueConicClient.profile().addValues("propertyKey", ["propertyValue1", "propertyValue2"])
' Increment profile property value
' If there are already values for a property the new value will be the sum of all values.
m.blueConicClient.profile().incrementValue("propertyKey", "1")
' Update the profile to sync over the data from the Roku app to the BlueConic servers and also pull in the data that has changed on the BlueConic side.
m.blueConicClient.updateProfile()
A common use case for setting profile properties directly is to store attributes of the user, especially those that can be used for profile merging across devices. To do this, you would first need to note the ID of the user and email address profile properties you wish to populate (e.g. user_id and email). Then, the setProfileValue method should be used to populate these profile properties accordingly.
If it is required to reset your profile ID locally on the device, use the following method:
' Clears the profile ID from the BlueConic client locally (cache). A new profile ID will be generated.
m.blueConicClient.createProfile()
' Removes the profile from the BlueConic servers. The profile ID will be removed from the BlueConic client. A new profile ID will be generated.
m.blueConicClient.deleteProfile()
Publish events
The BlueConic SDK allows you to send events to BlueConic. This allows you to keep BlueConic informed of what is happening in your app, even when it happens outside the scope of the basic operations.
Events are sent using the BlueConicEventManager's dedicated functions. Several kinds of events can be published:
ClickEvent - This event signals to BlueConic that a component with a specific ID has been clicked in your app.
UpdateContentEvent - This event signals to BlueConic that the content of a component with a specific ID has updated its content and also passes on the updated content.
UpdateValuesEvent - This event signals to BlueConic that a component with a specific ID has received an updated list of values and passes on these updated values.
AdvancedEvent - This allows you to send a custom event to BlueConic with its own specific name and a list of values.
Click event
BlueConic enables users to indicate the button that defines the click area in a Click / Tap rule as follows:
To make this work for your BlueConic users, add the following code to your app:
' Publish click event for selector "#nextButton"
m.blueConicClient.eventManager().publishClickEvent("#nextButton",["value"])
Update content
BlueConic enables you to detect words on the Roku app screen:
To enable this for the BlueConic users at your site, publish an UpdateContentEvent. Add the following code to your app:
' Define update content event for textview or button component "body"
m.blueConicClient.eventManager().publishUpdateContentEvent("content", "#body")
Update values
BlueConic enables you to create a form listening rule that updates a profile property when a form field changes its value:
"TextView" and "Spinner" widgets will automatically pick up value changes. All other field types have to be facilitated with code within your app.
To make this work for your BlueConic users for non-supported fields, add the following code to your app:
' Define update values event for selector "#emailAddress"
m.blueConicClient.eventManager().publishUpdateValuesEvent("#emailAddress", ["email"])
Now, when the user enters an email address in your app, it will be picked up in BlueConic as well.
Custom-defined event
BlueConic enables you to set profile property values when a custom-defined event is received. It even allows you to check for specific values in the context of the event:
To enable this feature for your BlueConic users, add the following code to your app:
valueList = ["blueberry","sushi","pancakes"]
' Define advanced event with the name "video_started"
m.blueConicClient.eventManager().publishAdvancedEvent("video_started", valueList)
The app publishes an event with the name "video_started" and a list of three values ("blueberry," "sushi," and "pancakes") is added as context. Adding values is optional; it provides extra information to allow BlueConic users at your site to make more specific rules.
On the BlueConic side, the example rule in the screenshot says "... if event video_started is received with a context that contains blueberry, raspberry for any value". The published example event contains one of those values (blueberry) for the event, which means there is a match. As a result, BlueConic will add the value "fruit" to the profile property "Food Preferences" of the profile for this particular app user.
Add context
Adding context to an event makes it a lot easier to develop and configure which values a developer is able to use and send through the event to BlueConic, where the event context can be used with BlueConic Listeners. Previously, this had to be configured by using a public UI element in order to retrieve data from an app. Now developers can use private or dynamic values and apply them directly as context to an event. This gives you more control and flexibility to publish BlueConic events within an app, and the BlueConic users at your site can use them to define BlueConic Listeners, without having to know about the internal UI IDs of the app.
Developers can trigger these events in their code, for example to publish a ClickEvent whenever a customer clicks on their favorite sport (code shown below). In addition, you can define a BlueConic Listener to keep track of a customer's favorite category or sport.
You can add the ClickEvent to a function in your app, for example, by adding a click handler that a customer interacts with in the UI or when they navigate to a different page.
m.blueConicClient.eventManager().publishClickEvent("#favoriteSport", ["soccer"])
Once the developer adds the events within the app, BlueConic users at your site can define BlueConic Listeners to keep track of these events and store data to the profile. To create listeners for these events, they just have to know the selectors the developer used in their events (e.g. “#favoriteSport”).
BlueConic users can use the event feature in the Visit listener.
Subscribe to events
BlueConic allows you to subscribe to events received by the SDK from the platform when you use certain plugins or dialogues, in order to receive information from them. To subscribe to events, you can use the BlueConicEventManager with the following code:
' Use to subscribe to specific events from the SDK
m.blueConicClient.eventManager().subscribe(
' The name of the event to which you subscribe to
"event",
' Callback that is invoked to handle info of the subscribed event
sub(event as object)
' Event object to your specific event to retrieve data
end sub,
' Optional parameter specifying if the callback should be invoked only one time
onlyOnce = false/true,
' Optional parameter used to identify the callback that can be used to unsubscribe
"callbackIdentifier"
)
' Use to unsubscribe from events from the SDK using defined identifier
m.blueConicClient.eventManager().unsubscribe("callbackIdentifier")
Depending on the configured plugin, the Event Handler function is invoked when the data from the server is received, specifically after PAGE VIEW events. Due to this, it is recommended that you set up your subscribed events before invoking any PAGE VIEW events.
BlueConic users can use the event subscribing feature for any of the following BlueConic plugins:
Properties Dialogue Event
To interact with the Properties-Based Dialogue plugin and receive the configured JSON data in your app, you need to subscribe to the Properties Dialogue Event. The received event in the handler will contain the data. To subscribe to the event, use the following implementation:
// Use to subscribe to specific events from the SDK ' Use to subscribe to specific events from the SDK
m.blueConicClient.eventManager().subscribe("propertiesDialogueEvent", sub(event as object)
// Use event to retrieve data (variantId, position & data)
print "Variant ID: " + event.variantId
print "Position: " + event.position
data = ParseJson(event.data)
end sub, onlyOnce, "callbackIdentifier")
// Trigger a PAGE VIEW event
// Use to unsubscribe from receiving events from the SDK
m.blueConicClient.eventManager().unsubscribe("callbackIdentifier")
The structure of the PropertiesDialogueEvent is as follows:
PropertiesDialogueEvent {
variantId as String,
position as String,
data as String
}
The data parameter, which is the JSON configured in the plugin, is a stringified JSON that you will need to convert to a JSON object or your specific data structure in the app.
Additional functionality
To retrieve the segments the current user is currently part of, use the following methods:
m.blueConicClient.getSegments(sub(segments)
segmentId = segments[0].id
segmentName = segments[0].name
end sub)
Test the SDK integration
Enable debug mode
Add the following setting to the BlueConicConfiguration object when initializing the SDK:
configurationBuilder = BlueConicConfigurationBuilder()
...
configurationBuilder.setDebugMode(true)
...
configurationBuilder.build(m.global)
Note: Setting Debug to true will provide more logging and enable the use of the BlueConic Simulator.
Warning: When you publish your apps, Debug should always be set false.
Additionally, you can pass Simulator information directly to the SDK when you initialize it in the BlueConicConfiguration object, if you know your Simulator username and session ID, by using the following method:
configurationBuilder = BlueConicConfigurationBuilder()
...
configurationBuilder.setSimulatorData(username, simulatorSessionId)
...
configurationBuilder.build(m.global)
Note: The use of the BlueConic Simulator is restricted to Debug mode only.
To test your Roku app, you will need access to a BlueConic environment. There are two options:
Are you working on behalf of a BlueConic Customer that has a BlueConic environment set up? Ask a representative of the BlueConic Customer to request a Sandbox environment in which you can test your Roku app.
Alternatively, request a free Pyxis environment yourself, and test your Roku app with that instance of BlueConic.
For more information on how to configure connecting to the BlueConic simulator, see: Testing a native app in BlueConic.
Release Notes
To see a list of updates and bug fixes for the SDK, see the BlueConic SDK for Roku Release Notes.