Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 19 Next »

Description of Interface

The query methods (GetCatalog, GetStoreCatalog, GetPurchases and GetUpgrade) return information about products in the Channel Store.  These are asynchronous methods.  The method call returns immediately, and the requested information is returned later in an roChannelStoreEvent. The purchase methods (DoOrder and DoUpgrade) take a small amount of information from the channel, lead the user through Roku Channel Store screens to complete the purchase or cancel, and return final status to the channel. These methods are synchronous and transactional, and in general will may take a long time to return (depending on the user's actions).

The order modifiers (SetOrder, ClearOrder and DeltaOrder) change the list of items (commonly called a "shopping cart") that will be the initial list used by the DoOrder purchase method.

Description of Methods

GetCatalog() as Void

Requests the list of In-Channel products which are linked to the running channel.

If successful, a later roChannelStoreEvent will be received which contains an roList of roAssociativeArray items where each item contains the following parameter names with specified value type:

  • String code
  • String name
  • String description
  • String SDPosterUrl
  • String HDPosterUrl
  • String cost (Localized cost with local currency symbol)

GetStoreCatalog() as Void

Requests the list of globally available In-Channel products, which are available to all channels.

If successful, a later roChannelStoreEvent will be received which contains an roList of roAssociativeArray items where each item contains the following parameter names with specified value type:

  • String code
  • String name
  • String description
  • String SDPosterUrl
  • String HDPosterUrl
  • String cost (Localized cost with local currency symbol)

GetPurchases() as Void

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

If successful, a later roChannelStoreEvent will be received which contains an roList of roAssociativeArray items where each item contains the following parameter names with specified value type:

  • String code
  • String name
  • String description
  • String SDPosterUrl
  • String HDPosterUrl
  • String cost (Localized cost with local currency symbol)
  • Integer qty

GetUpgrade() as Void

Requests information about the upgrade for the current channel.  Each channel may have one "In-Channel Upgrade" channel associated with it.

If successful, a later roChannelStoreEvent will be received which contains an roList of roAssociativeArray items where each item contains the following parameter names with specified value type:

  • String code
  • String name
  • String description
  • String SDPosterUrl
  • String HDPosterUrl
  • String cost (Localized cost with local currency symbol)

If the current channel has no In-Channel Upgrade, an empty roList is returned.

SetOrder(order as Object)

Sets the current Order (shopping cart) to the elements specified in the parameter, which must be an roList of roAssociativeArray items where each item contains the following parameter names with specified value type:

  • String code
  • Integer qty

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

ClearOrder() as Void

Clears the current Order (shopping cart).  After this call, the Order is empty.

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

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 quantity.  If the item already exists in the Order, qty is added to the quantity of this item in the Order.  qty may be negative.  The returned value is the quantity of the item remaining in the Order after applying the change.  If this number is zero or negative, the item is deleted from the Order. 

GetOrder() as Object

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

  • String code
  • Integer qty

DoOrder() as Boolean

Displays the Roku Channel 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.  If the user approves the order, this function returns true.  Otherwise it returns false.  In the case that  the user approves, the channel should wait for and respond to the roChannelStoreEvent.isRequestSucceeded event to get the details of the completed transaction.

DoUpgrade() as String

Displays the Roku Channel Store Product Purchase Screen populated with information about the "In-Channel Upgrade" available for the currently running channel.  The user can then either approve and complete the purchase or cancel the purchase.  If the purchase was completed successfully, the return value is the item code of the purchased upgrade; otherwise it is an empty string.  If a code is returned, then the new channel has already been downloaded and installed on the unit, and the currently running channel will be automatically deleted when the user exits it.

You must call GetUpgrade() on the same roChannelStore object before calling DoUpgrade(). 

FakeServer(enable as Boolean) as Void

If enable is true, enables a test mode for the roChannelStore component.

This test mode short circuits communication to the Ropku Channel store. It makes other methods get their responses to async queries and operations rom configuration files rather than actual server communication

This should never be called in a production channel.

GetUserData() as Object

The GetUserData() function provides a way to request user authorization to share the user’s account information with the calling channel.  The primary use case of this method 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() method could be called to read the user’s account information in order to prepopulate an account registration screen.

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 Don’t Share button, GetUserData() returns invalid.  If the user presses the Share button, GetUserData() returns an roAssociativeArray containing the following Roku account information for the channel user.  All values are Strings.

  • firstname
  • lastname
  • email
  • street1
  • street2
  • city
  • state
  • zip
  • country
  • phone
In order to call this function, the roChannelStore object needs to have a valid roMessagePort assigned to it by calling the ifChannelStore.SetMessagePort function. Also, since this method displays a dialog, the application must display a UI screen or canvas prior to calling the method. Otherwise, the behavior is undefined.

GetPartialUserData(properties as String) as Object

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.  To tell the function which properties to return, pass a string with a comma separated list of the attribute names.  For example, to return only the email address and first name of the user's account, you would call GetPartialUserData("email, firstname").  The full set of user account properties that can be queried with the function is:

  • firstname
  • lastname
  • email
  • street
  • city
  • state
  • zip
  • country
  • phone

In order to call this function, the roChannelStore object needs to have a valid roMessagePort assigned to it by calling the ifChannelStore.SetMessagePort function. Also, since this method displays a dialog, the application must display a UI screen or canvas prior to calling the method. Otherwise, the behavior is undefined.

GetUserPaymentConsent() as Object

When called, this method presents a dialog screen asking for user consent to allow the partner to charge their Roku account per the terms and conditions of the partner service. The user must provide their PIN if their Roku account is PIN protected. If the user account is set to “No Pin Required”, the user just provides consent in the dialog.

After the user confirms they agree, and the PIN is validated (if needed), Roku will attempt to process a zero dollar authorization. If the consent transaction succeeds, the partner will be able to bill against the Roku account. If the transaction fails, the partner will not be able to charge against the Roku account, and the user will receive an error message that Roku was unable to validate the payment method on file.

The method returns only after the user agrees to consent, or they cancel the dialog. If a PIN is required, and the user enters an invalid PIN, the user is asked to reenter their PIN.

The method returns an associative array containing the following information:

Key
Type 
Value
statusstringSuccess if the transaction succeeds, Failure if the transaction fails
errorCodestring

If the status key has a value of Failure, indicates the type of failure as follows:

Value
Meaning
InvalidPaymentMethodThe user entered an invalid payment method
NetworkUnavailableThe network connection failed during the transaction
UserCancelledThe user cancelled the dialog
UnknownErrorAn unknown error occurred that caused the transaction to fail
cibstring If the status key has a value of Success, contains the customer identifier for billing for use in the partner channel

Since this method displays a dialog, the application must display a UI screen or canvas prior to calling the method. Otherwise, the behavior is undefined.

  • No labels