ifChannelStore

Implemented by

Supported methods

GetIdentity() as Integer

Description

Returns a unique number for this object that can be used to identify whether a roChannelStoreEvent event originated from this object, by comparing with the roChannelStoreEvent object's GetSourceIdentity() value.

The value can be any arbitrary value as assigned by the Roku OS, and should only be used for comparison purposes. For example, the value should not be used as an array index.

For use as a look-up key, you can use GetIdentity().ToStr() as an associative array key.

Return Value

The unique number generated for the object.

GetCatalog() as Void

Description

Requests the list of in-app products that are linked to the running app.

If successful, a subsequent roChannelStoreEvent will be received that contains an roList of roAssociativeArray items. Each associative array will contain the following parameter names with specified value type:

GetStoreCatalog() as Void

Description

Requests the list of globally available in-app products, which are available to all apps.

If successful, a subsequent roChannelStoreEvent will be received that contains an roList of roAssociativeArray items. Each associative array will contain the following parameter names with specified value type:

GetPurchases() as Void

Description

Requests the list of purchases associated with the current user account.

If successful, a subsequent roChannelStoreEvent will be received that contains an roList of roAssociativeArray items. Each associative array will contain the following parameter names with specified value type:

GetAllPurchases() as Void

Description

The getAllPurchases function is similar to the getPurchases function 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.

If successful, a subsequent roChannelStoreEvent will be received that contains an roList of roAssociativeArray items.

SetOrder(order as Object, orderInfo as Object) as Void

Description

Sets the current Order (shopping cart) to the elements specified in the parameter, which must be an roList of roAssociativeArray items.

Passing an empty roList clears the Order, like calling ClearOrder().

Parameters

<br>m.store = CreateObject("roChannelStore")​<br>' Populate myOrderItems<br>myOrderInfo.action = "Upgrade"<br>m.store.setOrder(myOrderItems, myOrderInfo)<br>

ClearOrder() as Void

DeltaOrder(code as Object, qty as Integer) as Integer

Description

Applies a change in quantity to one item in the current Order (shopping cart).

• If the item identified by code is not in the Order, it is added with the specified qty.
• If the item already exists in the Order, qty is added to the quantity of this item in the Order.

Parameters

Return Type

The quantity of the item remaining in the Order after applying the change. If the returned value is zero or negative, the item is deleted from the Order.

GetOrder() as Object

Description

Retrieves the current Order.

Return Value

The returned object is an roList of roAssociativeArray items, where each item contains the following parameter names with specified value type:

DoOrder() as Boolean

Description

Displays the Streaming Store Product Purchase Screen populated with information from the current Order.

The user can then either approve and complete the purchase, or cancel the purchase. In the case that the user approves, the app should wait for and respond to the roChannelStoreEvent.isRequestSucceeded event to get the details of the completed transaction.

Return Value

A flag indicating whether the user approved the order (true if the order was approved; false otherwise).

FakeServer(enable as Boolean) as Void

It is recommended that developers use billing testing instead of this method.

Description

This test mode short circuits communication to the Streaming Store. It makes other methods get their responses to async queries and operations from configuration files, rather than actual server communication.

Do not call this method in a production app.

Parameters

To use this test method, create a csFake folder and add the following XML files to it in order to simulate web service request and response data:

• csfake/GetCatalog.xml: Simulates the list of products available for purchase in the app.
• csfake/GetPurchases.xml: Simulates the list of products already purchased by the user.
• csfake/PlaceOrder.xml: Contains information about the product to be ordered.
• csfake/CheckOrder.xml: Verifies the validity of the order placed. For example, if the order and id values in the PlaceOrder and CheckOrder XML files do not match, the fake server will report an error in the order processing.

See the SimpleChannelStore sample app for how to use this testing method.

GetUserData() as Object

Description

The GetUserData() function provides a way to request user authorization to share the user’s account information with the calling app.

The primary use case of this method is to facilitate partner account creation/updating within apps that have a customer billing relationship with Roku.

For example, a developer may have a Roku app that offers a VOD subscription to users. This subscription may require an account with the content provider. The GetUserData() method could be called to read the user’s account information in order to prepopulate an account registration screen.

Return Value

When called, the method presents a dialog screen containing the user’s account information, along with two buttons labeled Share and Don’t Share.

• If the user presses the Cancel button, GetUserData() returns invalid.
• If the user presses the Continue button, GetUserData() returns an roAssociativeArray containing the following Roku account information for the app user (all values are Strings):

  • firstname

  • lastname

  • email

  • street

  • city

  • state

  • zip

  • country

  • phone

  • birth ("YYYY-MM")

  • gender ("Male", "Female", or unspecified)

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

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

GetPartialUserData(properties as String, requestInfo as Object) as Object

Description

This function works like GetUserData(), but allows the caller to specify which user data elements to return. The specified values are also displayed in the user data dialog screen.

Parameters

<br><br>store = CreateObject("roChannelStore")<br><br>' Doesn't show user data in dialog unless necessary in he user's region.<br>userData = store.GetPartialUserData("email,firstname,lastname,gender,birth")<br>' Show user data values in dialog.<br>userData = store.GetPartialUserData("email,firstname,lastname,gender,birth", }context: "signup", forceShowData: true})<br>' forceShowData currently has no effect in signin context, as the shared data is always shown.<br>userData = store.GetPartialUserData("email", }context: "signin", forceShowData: false})<br>

Return Value

An roAssociativeArray containing the Roku account information passed in the method.

For authenticated free and AVOD apps that are not enrolled in the Roku Partner Payouts Program, a limited set of account information may be requested and returned:

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

Sign-up example

store = CreateObject("roChannelStore")

' Request user's email, phone, first name, and last name for sign-up
userData = store.GetPartialUserData("email, phone, firstname, lastname")

Sign-in example

store = CreateObject("roChannelStore")

' Request user's email for sign-in
userData = store.GetPartialUserData("email"}context: "signin"})

GetUserRegionData() as Object

Description

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.

Return Value

An associative array that contains the following fields:

StoreChannelCredData(data as String) as Object

Description

Stores an access token, oAuth token, or other authentication artifact that can be retrieved by calling the GetChannelCred()method. This data is stored securely in the Roku cloud and can be retrieved by other devices linked to the same Roku account.

This method can be used to store an authentication artifact with Roku for a signed in user, associating that user with a particular Roku account. For more information, see Automatic Account Link.

Parameters

Return Value

This command returns an roAssociativeArray with the following values:

GetChannelCred() as Object

Description

Retrieves a Roku Partner Unique Customer Identifier (roku_pucid), or retrieves an access token, oAuth token, or other authentication artifact (channel_data).

Return Value

An associative array that contains the following fields:

GetDeviceAttestation(nonce as String) as String

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:

store  = CreateObject("roChannelStore")
nonce = GetRandomHexString(16)
token = store.GetDeviceAttestation(nonce)

Parameters

Return Value

The generated JWT token. 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(orderInfo as roAssociativeArray, productID as String) as Object

Description

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

Parameters

Return Value

If the order is successful, an roAssociativeArray is returned that contains the following keys with string values:

• id. This ID must be passed in the confirmOrderInfo parameter in ConfirmPartnerOrder() method.
• status. Success.
• tax. Cost of tax (if applicable).
• total. Total cost of transaction.

If the order fails, an roAssociativeArray is returned that contains the following keys with string values:

• errorCode. An error code representing why the transaction failed.
• errorMessage. An error message explaining why the transaction failed.
• failed. Failure.

ConfirmPartnerOrder(confirmOrderInfo as roAssociativeArray, productID as String) as Object

Description

This function is equivalent to doOrder() for transactional purchases. The user's billing status must first be confirmed with RequestPartnerOrder() prior to calling this function.

Parameters

Return Value

If the order is successful, an roAssociativeArray is returned that contains the following keys with string values:

• purchaseId. The transaction ID..
• status. Success.

If the order fails, an roAssociativeArray is returned that contains the following keys with string values:

• errorCode. An error code representing why the transaction failed.
• errorMessage. An error message explaining why the transaction failed.
• status. Failure.