Roku SDK Documentation : ChannelStore

Available since firmware version 7.2

Table of Contents

Extends: Node

Description

The ChannelStore node class provides an interface to the Roku Channel Store. It provides functionality equivalent to the roChannelStore component.

In general, the ChannelStore node class allows developers to issue one of several commands. Issuing each of these commands involves three steps:

1. (optional) Set some field(s) containing data needed by the command
2. Set up an observer of the result field associated with the command
3. Set the command field to the appropriate string to start the command execution
4. At some point in the future, the field associated with the command will be set to a ContentNode object containing the results of the command

Each of the commands starts a sequence of actions associated with the financial transaction that are handled by the firmware outside of control or monitoring by the channel SceneGraph markup. The SceneGraph markup merely initiates the purchase and receives a final result. This will engender trust with users, and give them confidence that they are dealing with the Roku Channel Store.

Fields

Creating an Order

To create an order, the order field needs to be set to a ContentNode that has one child ContentNode for each item to be purchased. There are two approaches to setting the order field: setting it directly, or setting the deltaOrder field.

To set the order field directly, first create a ContentNode, then create one child ContentNode with the "code" and "qty" fields set for each item to be purchased. Assuming m.channelStore is a ChannelStore node object, the following Brightscript code shows how to do this:

myOrder = CreateObject("roSGNode", "ContentNode")

myFirstItem = myOrder.createChild("ContentNode")
myFirstItem.addFields({ "code": "UPC2397", "qty": 1})
mySecondItem = myOrder.createChild("ContentNode")
mySecondItem.addField({ "code": "UPC4321", "qty": 2})
 
m.channelStore.order = myOrder

The order field can be set indirectly as well, by setting the deltaOrder field to add or modify the desired quantity of an item. Assuming m.channelStore is a ChannelStore node object, the following results in the order field containing the same items as the previous example:

m.channelStore.deltaOrder = { "code": "UPC2397", "qty": 1 }
m.channelStore.deltaOrder = { "code": "UPC4321", "qty": 2 }

Command Descriptions

Each of the actions associated with a command string are described in detail below.

getUserData

The getUserData command provides a way to request user authorization to share the user’s account information with the calling channel.  The primary use case of this command is to facilitate partner account creation/updating within channels that have a customer billing relationship with Roku. For example, a developer may have a Roku channel that offers a VOD subscription to users. This subscription may require an account with the content provider. The getUserData command could be called to read the user account information, in order to display information used during account registration.

To request all of the available user data, set the requestedUserData field to "all", then set the command field to getUserData. To request a subset of the user data, set the requestedUserData field to a common separated list of the desired field names (such as "city, state, zip"), then set the command field to getUserData.

When invoked, the command presents a dialog containing the user requested account information, along with two buttons labeled "Share" and "Don’t Share".  If the user presses the "Don’t Share" button, the getUserData command sets the userData field to invalid.  If the user presses the "Share" button, the getUserData command sets the userData field to a ContentNode containing string fields, with the following Roku account information for the channel user. 

If the requestedUserData field is not set to "all", the ContentNode stored in the userData field will only contain fields for the requested values.

getCatalog

getStoreCatalog

The getCatalog command requests the list of In-Channel products that are linked to the running channel. When the command completes, the catalog field will be set to a ContentNode containing command completion status. If successful, the catalog field ContentNode will have child ContentNodes containing information about each available item. 

The getStoreCatalog command requests the list of globally available In-Channel products, which are available to all channels. When the command completes, the storeCatalog field will be set to a ContentNode containing command completion status. If successful, the storeCatalog field ContentNode will have child ContentNodes containing information about each available item. 

The ContentNode stored in the catalog or storeCatalog field will contain two fields that reflect the completion status of the invoking command:

Each child of the catalog/storeCatalog field ContentNode represents an item available for purchase, and contains the following information:

doOrder

The doOrder command displays a dialog populated with information from the current order. The user can then either approve and complete the purchase, or cancel the purchase.

If the user does not approve the order, the orderStatus field will be set to a ContentNode with fields reflecting the completion status of the command.

If the user approves the order, the orderStatus field will be set to a ContentNode containing information about the order completion, as shown in the status table above. In addition, that ContentNode will have child ContentNodes that contain information about each item purchased.

The fields for each child ContentNode returns the same information when getPurchases is called, but not all fields are populated when the transaction is made. The following table only shows the populated fields.

getPurchases

The getPurchases command requests the list of purchases associated with the current user account.

When the command completes, the purchases field will be set to a ContentNode containing information about the command completion as shown in the table below. In addition, that ContentNode will have child ContentNodes that contain information about each purchased item.

If the command fails, the field will be set to a ContentNode with fields reflecting the completion status of the command.

If successful, each child ContentNode of the ContentNode stored in the purchases field represents a purchased item with the following fields:

requestPartnerOrder

Available since firmware version 7.6

This command checks the user's billing status and is a prerequisite for ConfirmPartnerOrder() when doing transactional purchases.

Prior to setting this command, create a ContentNode with the following fields:

code must be added as a field to the ContentNode via the addField() method. The currency symbols for priceDisplay and price should also be excluded.

Next, set the ContentNode to the ChannelStore node's requestPartnerOrder field.

m.orderInfo = createObject("roSGNode", "contentNode")
m.orderInfo.priceDisplay = "1.99"
m.orderInfo.price = "1.99"

m.orderInfo.addField("code", "string", false)
m.orderInfo.code = "tvod-rental"

m.channelStore.requestPartnerOrder = m.orderInfo
m.channelStore.command = "requestPartnerOrder"

If the command fails, requestPartnerOrderStatus will contain the following values:

If successful, requestPartnerOrderStatus will contain the following values:

confirmPartnerOrder

Available since firmware version 7.6

This command is equivalent to doOrder for transaction purchases. The user's billing status must first be confirmed with requestPartnerOrder prior to calling this command.

Prior to setting this command, create a ContentNode with the following fields:

Once these fields have been populated in a ContentNode, set the ContentNode to the ChannelStore node's confirmPartnerOrder field. Finally, set the ChannelStore node's command to confirmPartnerOrder to create a prompt for the user to complete the purchase.

'Create a ContentNode containing the details of the purchase
m.confirmOrderInfo = CreateObject("roSGNode", "ContentNode")
m.confirmOrderInfo.title = "The Best Movie Ever"
m.confirmOrderInfo.price = Mid(m.channelStore.requestPartnerOrderStatus.total, 2)
m.confirmOrderInfo.priceDisplay = m.orderInfo.priceDisplay
m.confirmOrderInfo.orderID = m.store.requestPartnerOrderStatus.orderID

'Add a code field to the ContentNode
m.confirmOrderInfo.addField("code", "string", false)

'Set the code to the product identifier of your generic tvod product
m.confirmOrderInfo.code = "tvod-rental"

'Set the ContentNode to the ChannelStore node
m.store.confirmPartnerOrder = m.confirmOrderInfo

'Prompt the user to complete the transaction
m.store.command = "confirmPartnerOrder"

If the command fails, confirmPartnerOrderStatus will contain the following values:

If successful, confirmPartnerOrderStatus will contain the following values:

getAllPurchases

Available since firmware version 9.1

The geAllPurchases command is similar to the getPurchases command except that it requests the historical list of all canceled, expired, and terminated subscriptions over the lifetime of the current user account—in addition to the active subscriptions. You can use this method to leverage purchase history in order to implement subscription renewal flows and more easily determine if subscriptions have expired. 

When the command completes, the purchases field will be set to a ContentNode containing information about the command completion as shown in the table below. In addition, that ContentNode will have child ContentNodes that contain information about each purchased item. Each child ContentNode will include an additional status field that indicates whether the purchase is for a current subscription ("Valid") or for a subscription that has been canceled, expired, or terminated ("Invalid")

If the command fails, the field will be set to a ContentNode with fields reflecting the completion status of the command.

If successful, each child ContentNode of the ContentNode stored in the purchases field represents a purchased item with the following fields:

storeChannelCredData

Available since firmware version 9.1

Stores an OAuth token, custom token, or other custom data, which you can then retrieve with the getChannelCred command. This data is stored securely in the cloud and can be retrieved by other devices linked to the same Roku account. Your channel can use the  storeChannelCredData command to store an authentication artifact with Roku for a signed in user, associating that user with a particular Roku account. For more information, see Universal Authentication Protocol for Single Sign-On. 

function init(): m.store.ObserveField("storeChannelCredDataStatus", "onStoreChannelCredData") m.store.ObserveField("channelCred", "onGetChannelCred")
' trigger "storeChannelCredData" command with "test channel cred data" in m.store.channelCredData field. print "StoreChannelCredData" m.store.channelCredData = "test channel cred data" print "store.channelCredData: " m.store.channelCredData m.store.command = "storeChannelCredData" end function function onStoreChannelCredData() as void print "onStoreChannelCredData" if (m.store.storeChannelCredDataStatus <> invalid) print "- response: " m.store.storeChannelCredDataStatus.response print "- status: " m.store.storeChannelCredDataStatus.status end if '
trigger "getChannelCred"
command.print "GetChannelCred"
m.store.command = "getChannelCred"
endfunction
function isstr(value) return (value < > invalid) and(GetInterface(value, "ifString") < > invalid) 
endfunction
function isNullOrEmpty(obj) 
	if obj = invalid
  	return true
	if not isstr(obj) return true
		if Len(obj) = 0
			return true
		return false 
endfunction
function onGetChannelCred() as void print "onGetChannelCred"
  if (m.store.channelCred < > invalid) print "- channelID: "
    m.store.channelCred.channelID print "- status: "
    m.store.channelCred.status print "- publisherDeviceID: "
    m.store.channelCred.publisherDeviceID
  	if (not isNullOrEmpty(m.store.channelCred.json)) json = parsejson(m.store.channelCred.json) 	
  		if (json < > invalid) and(not isNullOrEmpty(json.roku_pucid)) print "- error: "
      		json.error print "- roku_pucid: "
      		json.roku_pucid print "- token_type: "
      		json.token_type print "- channel_data: "
      		json.channel_data 
    	endif 
	endif
  endif
endfunction

If successful, the ContentNode stored in storeChannelCredDataStatus represents the completion status of the request:  

getChannelCred

Available since firmware version 9.1

Retrieves a Roku Partner Unique Customer Identifier (roku_pucid). The PUCID can be used in place of requiring the user to enter their email address or username again (for example, when setting up a new device on the same Roku account).

If successful, the ContentNode stored in the channelCred field represents the channel credentials with the following fields: 

Sample Channels