Skip to content

Subscription Channel Requirements

Jump to bottom
rrirower edited this page Jun 9, 2024 · 3 revisions

Offering subscriptions to your Roku subscribers requires the following:

  1. A Subscription Server that supports Rest API calls.
  2. A Roku Web Service API key.
  3. Updates to the Wizard-generated code. You MUST update the code, or, the code will not work correctly.

Optionally, it is highly recommended that you review the Roku tutorials Offering Subscriptions and On Device Authentication for an understanding of the workflow that is used in the generated code.

NOTE: You are solely responsible for ensuring that the code generated by the wizard and your integrated changes meet your requirements.

Required code changes to the wizard-generated code:

The following section details the changes you need to make to implement a Subscription server with the Wizard-generated code. Examples are given of the API functions that were used to simulate and test a Subscription server. Amazon AWS was used as the test bed server and Python lambda functions were written to implement the required Rest API.

DO NOT USE THE SAMPLE FUNCTIONS AS IS. THEY ARE NOT MEANT TO SUBSTITUTE FOR YOUR SUBSCRIPTION SERVER. YOU WILL NEED TO IMPLEMENT YOUR OWN API FUNCTIONS WITH THE NAMES LISTED BELOW.

Follow these steps:

  • Navigate to the \components\ServerResources folder. Edit the resources.json file to add URL endpoints for your server resources. You need to add the API endpoint URL for each entry in the "subscriptions" end points array. All API calls must return a JSON response.

  • Failure to update the resources.json file with your endpoint URLs will result in code failure or crashes.

  • DO NOT use the following sample endpoints as is. They were used for testing only.

The required endpoints are:

  1. Name: validate-token - Passes an access token that has been stored in the Roku device registry to your Subscription server. A match indicates that the user is entitled to view the content. Set the 'accessToken' field in the JSON response to a new 'refresh' unique token if the tokens match. Otherwise, set the field to an empty string.

Sample Python Lamda function that implements the validate-token Rest API call:

import json
import uuid

def lambda_handler(event, context):
    #token = event['queryStringParameters']['accessToken']
    
    response = {}
    guid = uuid.uuid4()
    response['accessToken'] = guid.hex
    
    responseObject = {}
    responseObject['statusCode'] = 200
    responseObject['headers'] = {}
    responseObject['headers']['Content-Type'] = 'application/json'
    responseObject['body'] = json.dumps(response)
    
    return responseObject
  1. Name: check-linked-subscription - Checks your Subscription server for a valid subscription linked to the passed email address. If you find a valid subscription on your server linked to the email, set the 'subscriptionIsLinked' field in the JSON response to "true". Otherwise, set it to "false".

Sample Python Lamda function that implements the check-linked-subscription Rest API call:

import json

def lambda_handler(event, context):

    response = {}
    response['subscriptionIsLinked'] = 'false'
    
    responseObject = {}
    responseObject['statusCode'] = 200
    responseObject['headers'] = {}
    responseObject['headers']['Content-Type'] = 'application/json'
    responseObject['body'] = json.dumps(response)
    
    return responseObject
  1. Name: validate-credentials - This function calls your Subscription server to validate the user's credentials. It passes the user's email and password. If the user's credentials are valid, set the 'credentialsValid' field in the JSON response to "true". Otherwise, set the field to "false".

Sample Python Lamda function that implements the validate-credentials Rest API call:

import json

def lambda_handler(event, context):

    response = {}
    response['credentialsValid'] = 'true'
    
    responseObject = {}
    responseObject['statusCode'] = 200
    responseObject['headers'] = {}
    responseObject['headers']['Content-Type'] = 'application/json'
    responseObject['body'] = json.dumps(response)
    
    return responseObject
  1. Name: get-access-token - Calls your Subscription server to get a unique access token. You should return a unique access token in the 'accessToken' field of the JSON response.

Sample Python Lamda function that implements the get-access-token Rest API call:

import json
import uuid

def lambda_handler(event, context):
    #token = event['queryStringParameters']['accessToken']
    
    response = {}
    guid = uuid.uuid4()
    response['accessToken'] = guid.hex
    
    responseObject = {}
    responseObject['statusCode'] = 200
    responseObject['headers'] = {}
    responseObject['headers']['Content-Type'] = 'application/json'
    responseObject['body'] = json.dumps(response)
    
    return responseObject
  1. Name: validate-new-order - Passes the user's email, first name, and last name (in that order) to your Subscription server. You should validate the order and if it is OK, return a unique access token in the 'accessToken' field and set the 'orderIsOK' field to "true" in the JSON response. Otherwise, set the 'orderIsOk' field to "false".

Sample Python Lamda function that implements the validate-new-order Rest API call:

import json
import uuid

def lambda_handler(event, context):
    #token = event['queryStringParameters']['accessToken']
    
    response = {}
    guid = uuid.uuid4()
    response['accessToken'] = guid.hex
    response['orderIsOK'] = 'true'
    
    responseObject = {}
    responseObject['statusCode'] = 200
    responseObject['headers'] = {}
    responseObject['headers']['Content-Type'] = 'application/json'
    responseObject['body'] = json.dumps(response)
    
    return responseObject
  1. Name: check-entitlement - Checks your Subscription server to see if the user is entitled to view the video content. Passes a transaction ID to your subscription server. You should validate that the transaction is valid. If the transaction is valid and the user is entitled to view your content, set the 'isEntitled' field in the response to "true". Otherwise, set it to "false" to prevent viewing.

Sample Python Lamda function that implements the check-entitlement Rest API call:

import json

def lambda_handler(event, context):

    response = {}
    response['isEntitled'] = 'true'
    
    responseObject = {}
    responseObject['statusCode'] = 200
    responseObject['headers'] = {}
    responseObject['headers']['Content-Type'] = 'application/json'
    responseObject['body'] = json.dumps(response)
    
    return responseObject
  • Sign up for Roku Pay push notifications to receive notifications at your server when certain transactions occur on the user Roku device. This allows you to update your back-end system in real-time.
Clone this wiki locally