ChannelStore

Extends Node

The ChannelStore node class provides an interface to the Streaming Store. It provides functionality equivalent to the roChannelStore component. In general, the ChannelStore node class allows developers to issue one of several commands, which involves the following steps:

1. Set the fields containing the data needed by the command (optional).
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. The field associated with the command is 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 Roku OS outside of control or monitoring by the app SceneGraph markup. The SceneGraph markup merely initiates the purchase and receives a final result.

Fields

command

requestedUserData

requestedUserDataInfo

store = CreateObject("roSGNode", "ChannelStore")
' Doesn't show user data in dialog unless necessary in the user's region.
 store.requestedUserData = "email,firstname,lastname,gender,birth"
store.command = "getUserData"
' Shows user data in dialog.
info = CreateObject("roSGNode", "ContentNode")
info.addFields({forceShowData: true})
store.requestedUserDataInfo = info
store.requestedUserData = "email"
store.command = "getUserData"

Sign-up example

store = CreateObject("roSGNode", "ChannelStore")

' Request several properties for sign-up
store.requestedUserData = "email, phone, firstname, lastname"
store.command = "getUserData"

' Store requested properties
 email = store.userdata.email
 firstname = m.store.userData.firstname
 lastname = m.store.userData.lastname
 phone = m.store.userData.phone

Sign-in example

store = CreateObject("roSGNode", "ChannelStore")

' Set sign-in context for RFI screen
info = CreateObject("roSGNode", "ContentNode")
info.addFields({context: "signin"})
store.requestedUserDataInfo = info

' Request user's email for sign-in
store.requestedUserData = "email"
store.command = "getUserData"

' Store requested properties
 email = store.userdata.email

userData

order

Creating an order

To create an order, this 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": 1})
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": 1}

deltaOrder

requestPartnerOrder

See Creating TVOD apps for how to use this field for transactional purchases.

confirmPartnerOrder

See Creating TVOD apps for how to use this field for transactional purchases.

orderStatus

purchases

catalog

storeCatalog

requestPartnerOrderStatus

confirmPartnerOrderStatus

fakeServer

Commands

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

getUserData

Displays the Roku Pay Request for Information (RFI) screen, which prompts customers to confirm that Roku may share their Roku customer account information with the calling app in order to sign up/sign in to that app. This enables apps to create and update customer accounts in their system without requiring customers to manually enter their personal information in an account creation screen.

To pass certification, all authenticated apps (SVOD, TVOD, other subscription services, and AVOD) must use the getUserData command to display a Request For Information (RFI) screen during the sign-up and sign-in workflows to enable customers to share their Roku account information with the app. Only if the user declines the request may apps require the customer to manually enter their information.

To use this command, follow these steps:

1. Set the requestedUserData field to the Roku customer account information to be requested. This may be set to either "all" to get all the available account information items, or a string with a comma-separated list of specific information items (for example, "email, firstname). Request the minimum amount of information required to create/update an account.

   store = CreateObject("roSGNode", "ChannelStore") store.requesteduserdata = "email, first name, lastname, phone"

2. Send the getUserData command.

   m.store.command = "getUserData"

3. The RFI screen's asks the customer to use their Roku customer account information to sign up or sign in to the app, and it lists the requested information.

   

4. If the customer clicks Continue in the RFI screen to confirm that Roku can share their Roku customer account information with the app, the userData field field is populated with the Roku customer account information that was requested in the requestedUserData field. If the customer clicks Cancel in the RFI screen to decline sharing their information, the userData field is set to "invalid".

   email = store.userdata.email firstname = m.store.userData.firstname lastname = m.store.userData.lastname phone = m.store.userData.phone

Overall, the userData field field may contain the following Roku customer account information fields.

For authenticated free and AVOD apps that are not enrolled in the Roku Partner Payouts Program, the userData field contains a limited set of account information fields:

• Sign-up RFI screen: email, phone, and zip.
• Sign-in RFI screen: email and phone.

getUserRegionData

The getUserRegionData command retrieves the state, zip code, and country associated with the customer's Roku account. The location information returned by this command can be used to determine a customer's eligibility for regional-specific subscription products and content.

When this command is invoked, the ContentNode stored in the userRegionData field contains the following fields:

getCatalog

Lists the In-App Products that are linked to the running app. When this command completes, the catalog the completion status:

If the command is successful, the catalog or storeCatalog ContentNode contains a child ContentNode for each product available for purchase. Each child ContentNode includes the following information related to the product:

getStoreCatalog

Lists the globally available In-App Products, which are available to all apps. When the command completes, the storeCatalog field is set to a ContentNode containing completion status. If successful, the storeCatalog field ContentNode has child ContentNodes for each available item. See the getCatalog command for the fields related to the product that are available in the child ContentNode.

doOrder

Displays the Roku Pay order confirmation screen, which is populated with information about the current order (product name, price, any free trial or discount offer). The customer can then either approve and complete the purchase, or cancel the purchase.

When the command completes, the orderStatus field is set to a ContentNode containing information about the command completion.

If this command is successful, the orderStatus field ContentNode will have child ContentNodes for each item purchased. The fields for each child ContentNode include the same information when the getPurchases command is sent, but only the following fields are populated when the transaction is made:

As of Roku OS 9.4, if the back button is pressed from the Order Confirmation dialog, the doOrder command returns only a status of 2 ("interrupted"). Error handling in apps may need to be updated based on this behavior.

getPurchases

Returns the list of purchases of current subscription products associated with the Roku customer account.

When this command completes, the purchases field is set to a ContentNode containing the completion status.

If this command is successful, the purchases field ContentNode will have child ContentNodes for each item purchased. The fields for each child ContentNode include the following information about the purchased item:

getAllPurchases

The getAllPurchases 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 this command completes, the purchases field is set to a ContentNode containing the completion status.

If this command is successful, the purchases field ContentNode has child ContentNodes for each item purchased. The fields for each child ContentNode include a 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"), and the following information about the purchased item:

storeChannelCredData

Stores an OAuth token, custom token, or other custom data, which you can then retrieve with the getChannelCred command (the token is stored in the channelCred.json.channel_data field). This data is stored securely in the Roku cloud and can be retrieved by other devices linked to the same Roku account. As a result, users do not have to re-enter their account credentials when setting up new devices associated with the same Roku account. For more information, see Automatic Account Link.

function init():
    m.store.ObserveField("storeChannelCredDataStatus", "onStoreChannelCredData")
    m.store.ObserveField("channelCred", "onGetChannelCred")

    ' trigger "storeChannelCredData" command with "test app cred data" in m.store.channelCredData field.
    print "StoreChannelCredData"
    m.store.channelCredData = "test app 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"
end function

function isstr(value)
    return (value <> invalid) and (GetInterface(value, "ifString") <> invalid)
end function

function isNullOrEmpty(obj)
    if obj = invalid return true
    if not isstr(obj) return true
    if Len(obj) = 0 return true
    return false
end function

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
            end if
        end if
    end if
end function

This command returns an roAssociativeArray with the following values:

getChannelCred

Retrieves an oAuth token, custom token, or other authentication artifact (channel_data), or a Roku Partner Unique Customer Identifier (roku_pucid) if the app is using the Roku single-sign on (SSO) authentication service for authenticating users. If successful, the ContentNode stored in the channelCred field represents the app credentials with the following fields:

getDeviceAttestationToken

Generates a signed JSON web token (JWT) in the Roku cloud and returns it to the app. This token can then be used by the publisher's web services to verify that a message originated from a genuine Roku device. The following example demonstrates how to generate the device attestation token:

sub handleData(event)
  data = event.getData()
  print data.status
  print data.token
end sub

m.channelstore_node= m.top.findNode("deviceAttestationToken")
m.data.observeField("deviceAttestationToken", "handleData")
..
m.channelstore_node.nonce = GetHexString(16)
m.channelstore_node.command = "getDeviceAttestationToken"

Sample JWT

The following demonstrates a sample JWT that is returned to the app. Developers can use a JWT debugger to decode this token.

eyJ4NXUiOiJodHRwczovL2V4YW1wbGUucm9rdS5jb20vc2FtcGxlY2VydCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJuYmYiOjE2NTYzNzQyNzQsIngtcm9rdS1hdHRlc3RhdGlvbi1kYXRhIjp7Im5vbmNlIjoiNUUwNjkyRTBBMzg5RjRGNiIsImNoYW5uZWxJZCI6ImRldiIsImRldmVsb3BlcklkIjoiY2FhNzNmYmI1ZTc1YTQ2YTRiNjExNGRlNTFhNWFkYTdkNjE2ZTJlZCIsInRpbWVzdGFtcE1zIjoxNjU2Mzc3ODczOTkwfSwiaXNzIjoidXJuOnJva3U6Y2xvdWQtc2VydmljZXM6ZGV2aWNlLWF0dGVzdGF0aW9uIiwiZXhwIjoxNjU2NDY0Mjc0fQ.nywDvSUys27oeaQZ3yXwNBfOnXbO-TUDuekOPZYjSssfZhNhWwRXvPLbJKHcNMR5Z0vFOQLVDFeqEVGauIMxMEke5UFLuCRxhr3ayBJJPt_BPfrEFbAvYjFEGdKkxJqYUhuFE38R8lU2k7dhO0iFxDw1Qq7W4w8_7CjmDy4YFf7IfyhV7Vf2kGiOx5C94Niw5N2td3s21F3z77Rq_bofQ51DOKIwo_cDVuvPQnDyxG-CNEydZKCZZwGPYCKEHMPrIOOXJ-S9ZjArgaEpBUpMXWJibFxnkpVUVzbC22GEaqz_SjOJXFMQU7TaCKkDeCYVKylgKwCvbvHRDlgogf7kqg

Verifying the JWT

To verify the JWT, developers must download the Roku device attestation token certificate and authenticate that the token is signed by that certificate (see https://jwt.io/introduction for more information on JWT verification methods). The decoded JWT contains the following fields

Decoded JWT

The decoded JWT contains the following fields:

"x-roku-attestation-data": {
    "nonce": "5E0692E0A389F4F6",
    "channelId": "dev",
    "developerId": "caa73fbb5e75a46a4b6114de51a5ada7d616e2ed",
    "timestampMs": 1656377873990
 }

requestPartnerOrder

See Creating TVOD Apps for how to use this command for transactional purchases.

Checks the user's billing status for transactional purchases. This is a prerequisite for sending the confirmPartnerOrder command.

If this command is successful, the requestPartnerOrderStatus field contains the following values:

If this command fails, the requestPartnerOrderStatus field contains the following values:

confirmPartnerOrder

See Creating TVOD Apps for how to use this command for transactional purchases.

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

If this command is successful, the confirmPartnerOrderStatus field contains the following values:

If this command fails, the confirmPartnerOrderStatus field contains the following values: