Roku Billing and In-Channel Purchasing

Transcription

1 Roku Billing and In-Channel Purchasing Table of Contents Overview of Billing Customers for Purchases Tutorial for In-Channel Purchasing Install the Sample Roku Billing Channel Package and Publish the Sample Channel Step 1. Open a telnet session to your Roku player Step 2. Run the genkey utility to create a signing key Step 3. Package the side-loaded channel Step 4. Create a non-certified channel Properties Channel Store Info Monetization Package Upload Preview and Publish Add an In-Channel Product to Your Roku Developer Account Test the In-Channel Product on a Device Sample Code Overview Purchasing the product Placing the order Addendum: How to Set Up a Pay-to-Install Channel Overview of Billing Customers for Purchases Roku's cloud infrastructure supporting customer purchases allows you to bill customers on your Roku channel or prior to installing your channel. Also, your channel can leverage the billing information many customers already have on record with Roku, reducing your customer support costs. Pricing Models Roku billing offers two pricing models, pay-to-install and in-channel purchasing Pay-to-install: Useful for specific types of applications, such as themes and screensavers. See the Addendum below for more information. In-channel purchasing: Useful for purchases in your channel, such as free trials and multiple purchasing options per channel. See the tutori al below and, for further instructions on how to test billing for in-channel purchasing, see Testing In-Channel Purchasing. Using the Developer Dashboard to Set Up Billing Roku can handle many operations and transactional processing to minimize your billing efforts. The core services include billing customers, subscription management, and customer invoicing. For developers new to billing, see the overview about billing your customers on Purchases. You can use the Developer Dashboard for many of these processes. Purchases and other transactions can be verified and processed programmatically through the Roku Web Services API, the component rochannelstore and the node ChannelStore. To sign up for Roku billing: Create a Roku customer account: my.roku.com/signup Create a Roku developer account: developer.roku.com/enrollment/standard Enroll in the Roku Partner Payouts Program to receive payments for channels, games, content, and ads: developer.roku.com/developer/bill ing

2 Tutorial for In-Channel Purchasing This tutorial uses a sample, non-certified channel to focus on how to set up an in-channel purchasing product, test it, and then bill a customer for a purchase. Requirements to follow along: Set up a Roku device: Create a Roku developer account: developer.roku.com/enrollment/standard Enroll in the Roku Partner Payouts Program: developer.roku.com/developer/billing Understand how to install a sample channel ( Hello world guide) The primary steps for this tutorial are: Install the Sample Roku Billing Channel Package and Publish the Sample Channel Step 1. Open a telnet session to your Roku player Step 2. Run the genkey utility to create a signing key Step 3. Package the side-loaded channel Step 4. Create a non-certified channel Properties Channel Store Info Monetization Package Upload Preview and Publish Add an In-Channel Product to Your Roku Developer Account Test the In-Channel Product on a Device Sample Code Overview Purchasing the product Placing the order Install the Sample Roku Billing Channel Download the sign up sample channel. Refer to the Developer Setup Guide on how to install ("side-load") a channel onto a Roku device. PRELIMINARY 2

3 Package and Publish the Sample Channel Once you have the sample channel side-loaded onto your device, you ll need to generate a key to sign your package using a telnet client such as P utty on Windows or using the built-in client through terminal on OSX. Step 1. Open a telnet session to your Roku player Windows Instructions: Download the telnet client PuTTY. Enter the IP address of your Roku player. Use " 8080" for the Port Click the Telnet radio button for the Connection Type. PRELIMINARY 3

4 OSX / Linux Instructions: Open terminal and type: telnet your Roku player s IP address 8080 Step 2. Run the genkey utility to create a signing key Type genkey and wait for the process to complete. If the prompt says Command not recognized, type it again. PRELIMINARY 4

5 A key has been successfully generated to sign packages. Make note of the developer ID and password as it ll be required in the next section (and anytime code is updated and needs to be repackaged). Note: It is a good practice to generate a new developer ID and password for each channel you create unless you explicitly want to share registry information between channels. Step 3. Package the side-loaded channel 1. Return to your browser tab with the Developer Application Installer. There should now be a Packager option available. If you do not see this option, please go through the previous section and run genkey again. PRELIMINARY 5

6 2. Click on to bring up the Application Packager screen. The Dev ID should match the same developer ID that was generated with Packager genkey. Enter an App Name and Version and enter the password created by genkey. PRELIMINARY 6

7 3. Click on Package and a few short moments later you can download the signed package using the.pkg link. Step 4. Create a non-certified channel The next step is to create a non-certified channel with the signed package just generated On the Developer Dashboard, select Manage My Channels Select Add Channel on the following screen. 3. Select Developer SDK, Private, enter a Channel Name and then click Continue. PRELIMINARY 7

8 Properties On the Properties screen, all default values have been pre-selected, however, you may modify as needed. PRELIMINARY 8

9 Channel Store Info Edit the channel's Description as needed. Upload a Channel Poster (540 x 405 pixel size). Select a Preferred Category from the drop-down list. Click Continue when done. Monetization On the Monetization screen, select how you plan to monetize your channel. For this example, select My channel contains in-channel subscriptions. PRELIMINARY 9

10 Package Upload Upload your signed package and click Continue. PRELIMINARY 10

11 Preview and Publish On the Preview and Publish screen, review your data and then click Publish at the bottom. PRELIMINARY 11

12 Add an In-Channel Product to Your Roku Developer Account After you have published your non-certified channel, the next step is to create an In-Channel product. Return to the Developer Dashboard and select Manage My In-Channel Products. On the following screen, select Add a Product. For this example, a subscription product called monthly subscription will be created. 1. Under Channels, select the non-certified channel you just published and fill out the remaining fields as appropriate. PRELIMINARY 12

13 Purchase Type: Monthly Subscription Free Trial Period: Disabled Classification: Video Internet Connection Required: Yes Requires Additional Purchase: No Cleared for Sale: Yes Price Tier: 5 2. Click Save when finished and you will be directed back to the Manage In-Channel Products screen. The product you just created should be available with a Submit for review option. Select it and your product will change to Approved under status. PRELIMINARY 13

14 Test the In-Channel Product on a Device With an approved product, now you can install the non-certified channel on a Roku device and see if the product works. If you haven t yet installed the non-certified channel, return to the Manage Channels screen and click on Preview and Update. 1. Click on the / on the following screen to add the channel to your Roku. Access Code Vanity Access Code Once the channel is installed, launch it and you should see the following screen: PRELIMINARY 14

15 2. 3. Select New subscriber (sign up) which brings up a Request to share information dialog. Select Share to use your Roku account s address or Don t share to enter a different on the KeyboardDialog screen. PRELIMINARY 15

16 4. To create a password enter it (or play around with the error handling dialogs). PRELIMINARY 16

17 The next screen displays an example Terms Of Use dialog. Select Accept to show a dialog displaying the product(s) associated with your channel. PRELIMINARY 17

18 If you see the following, congrats! You ve just successfully created a channel with an in-channel purchase. 1. PRELIMINARY 18

19 Sample Code Overview Now you can examine the code to see how the channel is requesting the product and how it is purchased Open up the unzipped sample source code folder (or download the sample again) and open the components folder. Go into the RokuSignUp folder and open up the RokuBillingTask.brs file in your code editor of choice where line numbers will be displayed. Use the following diagram to see if your channel is following Roku's standard flow for programmatically retrieving a user's subscription status or purchase history: PRELIMINARY 19

20 To see what product(s) are available for purchase, use the rochannelstore component. In the sample, this is set up in sub GetPartialUserDa ta() in lines 20-22: port = CreateObject("roMessagePort") channelstore = CreateObject("roChannelStore") channelstore.setmessageport(port) Now you have an interface to the Channel Store, so you can make requests to see what products are available for purchase and what products have already been purchased. In the sample, you can make these requests through sub GetProducts() which provides an associative array of products available for purchase. PRELIMINARY 20

21 sub GetProducts() result = { availforpurchase : { list : [] map : {} } validpurchased : { list : [] map : {} } } allproducts = Helper_GetAllProducts() purchasedproducts = Helper_GetPurchasedProducts() datetime = CreateObject("roDateTime") utimenow = datetime.asseconds() for each product in allproducts baddtoavail = true for each purchase in purchasedproducts if purchase.code = product.code then baddtoavail = false if purchase.expirationdate invalid then datetime.fromiso8601string(purchase.expirationdate) utimeexpire = datetime.asseconds() if utimeexpire > utimenow then result.validpurchased.list.push(purchase) result.validpurchased.map[purchase.code] = purchase end if end if exit for end if end for if baddtoavail then result.availforpurchase.list.push(product) result.availforpurchase.map[product.code] = product end if end for m.top.products = result end sub On, you ll see two helper functions, and. lines Helper_GetAllProducts() Helper_GetPurchasedProducts() Helper_GetAllP roducts() returns an associative array with the details for each product associated with the channel. PRELIMINARY 21

22 function Helper_GetAllProducts() as Object result = [] port = CreateObject("roMessagePort") channelstore = CreateObject("roChannelStore") channelstore.setmessageport(port) channelstore.getcatalog() msg = invalid while type(msg) "rochannelstoreevent" msg = Wait(0, port) end while if msg.isrequestsucceeded() then response = msg.getresponse() if response invalid then result = response end if end if return result end function Helper_GetPurchasedProducts() returns an associative array with the details for each valid product (a subscription that has not expired) the user has purchased. PRELIMINARY 22

23 function Helper_GetPurchasedProducts() result = [] port = CreateObject("roMessagePort") channelstore = CreateObject("roChannelStore") channelstore.setmessageport(port) channelstore.getpurchases() msg = invalid while type(msg) "rochannelstoreevent" msg = Wait(0, port) end while if msg.isrequestsucceeded() then response = msg.getresponse() if response invalid then result = response end if end if return result end function Returning to sub GetProducts(), lines determines whether a subscription product that has been purchased has expired and is available for purchasing again. Purchasing the product Once the products that are available for purchase have been identified, you can set up calls to actually purchase the product. In the sample, this is done in sub PurchaseProduct(). PRELIMINARY 23

24 sub PurchaseProduct() port = CreateObject("roMessagePort") channelstore = CreateObject("roChannelStore") channelstore.setmessageport(port) channelstore.clearorder() channelstore.setorder([{ code : m.top.products.availforpurchase.list[m.top.indexpurchase].code qty : 1 }]) channelstore.doorder() msg = invalid while type(msg) "rochannelstoreevent" msg = Wait(0, port) end while result = { issuccess : msg.isrequestsucceeded() } if msg.isrequestsucceeded() then response = msg.getresponse() if response invalid AND response[0] invalid then result.append(response[0]) end if else if msg.isrequestfailed() then result.failurecode = msg.getstatus() result.failuremessage = msg.getstatusmessage() end if m.top.purchaseresult = result end sub This task function is called when the user selects the product from the dialog. To determine which product is selected, use with the indexpurchas e field, referencing the current index in the Subscription dialog shown below. PRELIMINARY 24

25 Placing the order In line 80, the sample calls ClearOrder(), which is good practice to be sure there are no anomalies when creating an order. In lines 81-85, the order is set up using the product identifier specified when the product was created. In SetOrder(), use a quantity of 1 to focusing on subscriptions for this example. Once the order is set up, the final step is to place the order. This is done in line 85: channelstore.doorder(). The remaining lines of code in sub PurchaseProduct() ensures that a response is given indicating the order was placed successfully or, if not, displaying an error. Addendum: How to Set Up a Pay-to-Install Channel In addition to in-channel purchases, Roku also offers a "pay-to-install" option for channels. Pay-to-install requires users to purchase before the channel can be installed. This pricing model is best suited for apps such as screensavers and themes where users can quickly see what is offered by reviewing the Channel Store details. To set up a channel with pay-to-install pricing, on the Monetization screen, select " Customers will pay before installing my channel" and any other options as appropriate. PRELIMINARY 25

26 You can then select the Purchase Type: one-time purchase, monthly subscription or yearly subscription, and a corresponding Price Tier. PRELIMINARY 26