In-App Purchases

The Cloud Solution provides APIs that mirror Roku calls to the Roku Channel Store to allow for product purchases.

For details on Roku in-app purchases (IAP) and the Roku Channel Store, see:

Implementing Roku Pay
Adding In-Channel Products
roChannelStore component documentation
ifChannelStore interface documentation

Mapping of Roku APIs to Cloud Solution APIs

The mapping from Roku APIs to Cloud Solution APIs is as follows:

Roku API (ifChannelStore)	Cloud Solution IAP Methods - You.i React Native Apps	Cloud Solution IAP Methods - C++ Apps	Notes
`GetChannelCred()`	GetRokuChannelCred()	`GetRokuChannelCred()`	To be successful, an app needs to be side-loaded on the Roku device with a tester account.
`StoreChannelCredData(credentials)`	SaveRokuChannelCred()	`SaveRokuChannelCred(credentials)`	To be successful, an app needs to be side-loaded on the Roku device with a tester account.
`GetPartialUserData("email")`	GetRokuUserAccount()	`GetRokuUserAccount()`	Cloud Solution only supports `email`.
`GetCatalog()`	GetAvailableProducts()	`GetAvailableProducts()`	Roku behavior: On development channels, provides test products.
`GetPurchases()`	GetUserPurchases()	`GetUserPurchases()`
`SetOrder(order)` `DoOrder()`	RequestPurchase()	`RequestPurchase()`	Roku behavior: On development channel, does not process purchase.

Channels can offer free trials and promotions to customers for their subscription services and drive paid subscriptions by participating in the Roku’s Instant Signup program. When a user activates a Roku device and adds the channel that supports the instant signup, they can select the free trial or specific offers. Then the Roku Pay database is checked to confirm the user’s eligibility for the specific offers. After the free trial or offers are activated, the channel is automatically added to the home screen of the user’s device. When the user launches the channel, they can directly access the content without any additional enrollment steps.

Details on the backend development for this feature can be found at Instant Signup in the Roku documentation.

Note

Channels that have streamed more than an average of 10 million hours per month over the last three months must participate in the Instant Signup program to pass certification.

When the channel launches, the channel credential data has to be validated with the application backend before providing the protected content. Here’s an example sequence diagram between the Application backend, the server application, and the Roku client.

Sequence diagram of Instant Signup and Automatic Account Link

Note

For reference descriptions of the Cloud Solution C++ APIs and the associated structure, see CYICloudInterface Class Reference and RokuPurchase Struct Reference.

You.i React Native Example

The application code makes calls to one of the Cloud Solution IAP methods and provides a responder function (a callback). The following is an example for You.i React Native apps:

async getAvailableProducts() {
  this.resetState();
  try {
    await Cloud.getAvailableProducts().then((rokuResponse) => {this.setState({availableProducts: rokuResponse})});
  } catch (e) {
    errorMsg = e.message;
    this.setState({statusMessage: errorMsg})
  }
}

C++ Example

The following is an example for C++ apps:

virtual void GetAvailableProducts(std::function<void(const roku_iap::RequestStatus &status, const std::vector<roku_iap::RokuProduct> &products)> responder)

The Cloud Solution IAP methods all trigger asynchronous network calls, and the provided responder functions are invoked once the results have been propagated back to the Cloud Solution runtime. In the previous C++ example, a vector of available products is provided to the responder.

Note the following:

Roku APIs behave differently based on whether the channel is in development mode (side-loaded), or in an installed private or public channel. This is Roku-specific behavior independent of the You.i TV Cloud Solution.
The Roku store handles one operation at a time, so be sure to wait until the previous request has either succeeded or failed before making a new request.
One alternative to fully test in-app purchases is to create a private channel from a monetized account and add one or more in-channel products. For more information, see the Roku topic Testing a Roku Pay Channel. Another alternate debugging tool for testing in-app purchases is a fake server mechanism. This is also useful for testing side-loaded channels. With this technique, your channel uses a set of XML files that simulate the web service request and response data. In-app purchase API calls are driven by a set of XML files in the channel’s csfake directory. For more details, see the Roku article Supporting In App Purchases in Your Roku BrightScript Channels.
After testing with a fake server, remove the csfake directory by running the youi-tv roku-client build using the --release option. Once the build is complete, you can use the side-loaded channel to test with real products.
You can do an optional check of purchases on launch using a manifest.
In-app purchase commands from the server are handled in IAP.brs.
To enable in-app purchase in the Roku client, add --inAppPurchase to your youi-tv roku-client command. This option adds the IAP.brs file with all necessary functions to the client.zip file. For more details, see Roku Client Builds.

In-App Purchases

Mapping of Roku APIs to Cloud Solution APIs

Instant Signup and Automatic Account Link Support

You.i React Native Example

C++ Example