Roku Developer Help

How to Add Video Favorites to a Roku Channel

Favorites may only be used in SDK channels at Update #520 or later. An AWS S3 Favorites bucket is required for Updates #521 through #525. Starting with Update #526 an AWS S3 Favorites bucket is optional.

Users of your channel can add and remove their favorite videos from an on-screen Favorites list. This improves retention and increases revenue by providing an easy-to-use way for your customers to keep track of content that they want to view again at a later date. You'll need an Unlimited or Commercial channel type in order to use Favorites.

How it works:

A Favorites list is designed into your channel using a Playlist item.
A Favorites button is added to each video to allow it to be added to or removed from the Favorites list.
The Favorites list is saved in the non-volatile memory contained in each Roku device.
An optional S3 bucket in your Amazon AWS account contains a copy of the Favorites list for each Roku device that uses Favorites. This can be used to monitor which Favorites your customers are selecting.
When a customer adds or removes a Favorite, their Roku device writes an updated copy of the Favorites list into its non-volatile memory and optionally to your AWS S3 Favorites bucket.
Because the Favorites list is stored in each Roku device, customers with more than one Roku device will have a different Favorites list on each device.

A note about Amazon AWS pricing: Amazon's S3 pricing is separate from Instant TV Channel's monthly charges. Amazon has a Free Tier for new customers which may include some or all of your S3 charges. All Amazon S3 charges are billed directly from Amazon, and are dependent mainly on the sizes of the files and how often they are accessed. A Favorites file for a customer with 20 favorites might be around 2KB (2000 bytes) in size. You can check the actual sizes of your Favorites files by looking in your Favorites bucket using the Amazon AWS console. Because this is a relatively small file, the cost from Amazon will be mostly due to the HTTP POST requests used to write the file. Amazon will bill you approximately $0.005 (1/2 of one cent) for each 1000 writes of the file. One write occurs each time a user adds or removes a Favorite.

DISCLAIMER: Instant TV Channel cannot guarantee that this AWS pricing information is accurate or complete. Please visit Amazon at https://aws.amazon.com/s3/pricing/ for current pricing.

How to add Favorites capability to UNLIMITED and COMMERCIAL channels:

Create the Favorites Bucket (Skip to Step D if not using AWS S3)

Shortcut for Setting Up the S3 Favorites Bucket If you have not yet entered keys for the Favorites bucket, an AWS Wizard symbol will be visible at the top of the Favorites section on the Services page. Click on the AWS Wizard symbol (on the Services page) and follow the on-screen directions to create the Favorites bucket and keys.

After using the AWS Wizard, skip the next sections and continue at Review Other Favorites Parameters.
1. Log into your AWS account and go to the S3 section of your AWS control panel.
2. Click the Create Bucket button.
  
  This should be a new bucket that is used only for Favorites files.
3. Provide a Bucket Name, for example "my-favorites-bucket".
  
  Very Important: Use only lower-case characters, digits, and dashes in your bucket name. Instant TV Channel does not support the use of upper-case characters or other symbols in bucket names.
  
  Good Bucket Name: favorites-bucket
  
  Good Bucket Name: fav123
  
  Bad Bucket Name: fav.bucket (contains unsupported period character ".")
  
  Bad Bucket Name: fav+123 (contains unsupported plus character "+")
  
  Bad Bucket Name: FAV-Bucket (contains upper-case characters)
4. The bucket Region must be set to "US East (N. Virginia)".
5. Click the Create button, do not click the Next button.
The default ACL (Access Control List) on your new bucket is "Private", meaning that an AWS key is required to access files in the bucket. The bucket cannot be accessed using a plain http:// or https:// URL. This is usually the correct setting for a Favorites bucket used in an SDK channel, as it only allows the Instant TV Channel your channel running in a Roku device to access the Favorites files.

It is not possible to use a Favorites bucket with Direct Publisher channels.
Create IAM Keys to Access the Favorites Bucket
1. Go to the IAM (Identity and Access Management) section of your AWS control panel.
2. Click the Policies link on the left side of the page.
3. Click the Create policy button near the top of the page.
4. Click the JSON tab, and erase the sample lines of JSON text.
5. Copy the security policy below and paste it into the JSON text box. Replace the two instances of
```
my-favorites-bucket
```
  in the policy with the name of the bucket that you just created. This security policy allows files in the Favorites bucket to be created, read, modified, or deleted.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:*"
      ],
      "Resource": [
        "arn:aws:s3:::my-favorites-bucket",
        "arn:aws:s3:::my-favorites-bucket/*"
      ]
    }
  ]
}
```
6. Click the Next: Tags button near the bottom of the page.
7. Click the Next: Review button near the bottom of the page.
8. Provide a new Policy Name, for example "my-favorites-policy". You may optionally also enter a Policy Description.
9. Click the Create policy button near the bottom of the page.
10. Click the User groups link on the left side of the page.
11. Click the Create group button near the top of the page.
12. Provide a new User group name, for example "my-favorites-group".
13. Scroll down to the list of policies, and locate the "my-favorites-policy" policy that you just created, or type the name of your newly created policy in the "Filter" box. You may need to scroll through a large number of built-in AWS policies until your policy is visible.
14. Check the checkbox to the left of your policy name. making sure that no other checkboxes are checked, then click the Create Group button near the bottom of the page.
15. Click the Users link on the left side of the page.
16. Click the Add Users button near the top of the page.
17. Provide a new User name, for example "my-favorites-user".
18. Click the Next button near the bottom of the page.
19. Check the checkbox to the left of the previously created Group name, then click the Next button near the bottom of the page.
20. Click the Create user button near the bottom of the page.
21. Click the previously created User name from the list of users. This will display a Summary page for the user.
22. Click the Security credentials link or tab.
23. Click either of the Create access key buttons.
24. Select Other, then click the Next button.
25. Click the Create access key button.
26. Click the Show link beneath "Secret access key" or click the Download .csv button to copy and save the Access Key ID and Secret Access Key. These keys will be used exclusively for read-write access to your Favorites bucket. They cannot be used to access any other AWS buckets or services. Make sure that you save the keys for future use, Amazon will not display them again. If you misplace the keys you will have to create a new IAM user.
27. After copying the Security Credentials, click the Close button near the bottom of the page.
  
  At this point we have a new IAM user that is a member of a new IAM group - the user has the keys and the group has the security policy. The keys for this IAM user can be used in the Roku channel to access the Favorites bucket specified by the security policy.
Copy the Favorites Bucket Name & Keys to your Channel
1. Sign into Instant TV Channel and select the channel that you want to configure for Favorites.
2. Go to the channel's Services page.
3. Under AWS S3 Favorites Storage, copy the new Favorites bucket name into the Favorites Bucket Name box.
4. Copy the IAM user's Access Key ID into the Favorites Access Key ID box.
5. Copy the IAM user's Secret Access Key into the Favorites Secret Access Key box.
6. Click the TEST S3 FAVORITES STORAGE button and verify that the S3 Favorites bucket tests OK message is displayed. If the test fails, verify that your S3 keys were copied correctly and try again.
Add Favorites Buttons
- Before you can add any new buttons, you'll need to set your Instant TV Channel Developer Mode to "Advanced" and enable Springboard button editing.
  1. Click the Account link on the left side of the page to go to your Account page.
  2. On your Account page, change Developer Mode to "Advanced - Show All Parameters". This will cause the advanced parameters, which were previously hidden, to be displayed on all Instant TV Channel pages.
  3. Change Show Custom Springboard Buttons to "Yes - Springboard Buttons Can Be Edited".
  4. Click the green SAVE CHANGES button at the top of the page.
- A Favorites button must be placed into each video item in the channel to allow the user to add or remove the video item from the Favorites list.
  
  Video items originally created in an Update older than #520 will not be able to directly add a Favorites button, even if the channel itself is at Update #520 or later. Instead, it will be necessary to create one new video item at the top of the channel, and use that item as a Springboard Template in order to have a Favorites button appear in the older video items.
  1. On the Content page, select a video item in which you would like to add a Favorites button.
    
    If creating a Template, select the first (highest or top-most) video item in the content tree. You will need to create a new top-most video item if the current top-most video item was created earlier than Update #520. (You'll know if it was created earlier than Update #520 if "Favorites" is not available as a button Action selection.)
  2. Scroll down to the last button parameter. Usually this will be Button 3.
  3. Click the New button. This will create a new button.
  4. Change the new button's Action parameter to "Favorites".
  5. A Favorites button should now be visible in this video's Springboard screen.
- A Springboard Template can be used to quickly add a Favorites button to all video items in the channel. The Template is always the first (highest or top-most) video item in the channel's content tree. When the Template is enabled, the Springboard buttons configured in the Template are used for all video items, and any custom buttons configured for the non-Template items are ignored. Enabling the Template only requires changing a single Theme parameter.
  1. On the Theme page, locate the SpringboardTemplateEnabled parameter and change it to "yes".
Add the Favorites Playlist

A Favorites Playlist must be added somewhere in the Content Tree, for example as a selectable item in a List or Grid Row, or as a complete Grid Row. The appearance of each Favorite will be the same as the original video content item, with the same artwork and any other options.

Video ads, if configured, will run based on the location of the original video item in the channel, not the Favorite's location.
1. At the location in the content tree where you would like the Favorites to be displayed, add a "New MRSS or Playlist" item.
  or
2. Change the item's Url parameter to be "FAVORITES". If this is a Free channel type, then the Url parameter cannot be changed. You must have an Unlimited or Commercial channel type in order to use Favorites.
Review Other Favorites Parameters
1. The optional Services Favorites Bucket Prefix parameter can be used with a value such as "my-channel/" to store the Favorites files for this channel in a separate folder within the bucket. Because the names of the Favorites files are unique for each device and channel, the Favorites files for different channels on the same device will not overwrite each other even if you do not use the Favorites Bucket Prefix parameter. Using the Favorites Bucket Prefix allows you to separate the Favorites information for each channel into separate folders or groups, should you wish to examine the files' contents to perform analytics.
2. The Services Favorites Enabled parameter is by default set to "Yes". Change this to "No" to disable Favorites. Favorites are disabled regardless of this parameter if the Bucket and Key parameters are invalid.
3. The Services Maximum Favorites parameter limits the number of favorites that can be stored for a single device. The default is 50 and the maximum allowed for this parameter is 200.
4. The Theme SpringboardFavoritesAddButton parameter is the on-screen text that is displayed for a Favorites button when the video is not currently in the Favorites list. The default value is "Add to Favorites".
5. The Theme SpringboardFavoritesRemoveButton parameter is the on-screen text that is displayed for a Favorites button when the video is already in the Favorites list. The default value is "Remove from Favorites".
6. The Theme FavoritesEnabled parameter is identical the Services Favorites Enabled parameter.
7. The Theme FavoritesMaximumTitle parameter is the title text for the on-screen Favorites dialog box that is displayed when the user attempts to exceed the maximum allowable number of Favorites. The default value is "Maximum Favorites".
8. The Theme FavoritesMaximumBody parameter is the body text for the on-screen Favorites dialog box that is displayed when the user attempts to exceed the maximum allowable number of Favorites. The default value is "The maximum number of Favorites has been reached. You will need to remove an old Favorite before you can add a new one.".
9. The Theme FavoritesMaximumItems parameter is the maximum number of Favorites that can be in a device's Favorites list.
10. The Theme FavoritesNoneTitle parameter is the title text for the on-screen Favorites dialog box that is displayed when the user attempts to view an empty Favorites list. The default value is "No Favorites".
11. The Theme FavoritesNoneBody parameter is the body text for the on-screen Favorites dialog box that is displayed when the user attempts to view an empty Favorites list. The default value is "You do not have any Favorites selected yet!".
12. The Theme FavoritesNonePosterUrl parameter is the URL for the poster displayed in an empty Favorites Grid Row. It disappears as soon as at least one Favorites item is in the Favorites Grid Row. The default poster size is 800x450 (16:9) however the optimal size depends on the configured size of the Grid Row posters.
AWS S3 Favorites Files
It may be useful to periodically examine the contents of your optional Favorites files stored in AWS S3 in order to analyze which content items your users consider to be favorites.
- There is one file for each Roku device using Favorites within your channel.
- The Favorites filenames are unique 36-character strings provided by Roku's GetChannelClientID() method.
Each Favorites file contains a playlist in JSON format text. The contents of a typical Favorites file might be:
```
{
  "modified": "2023-01-19T17:53:33.535Z",
  "added": [
     "2023-01-18T02:25:19.064Z",
     "2023-01-18T02:47:26.688Z",
     "2023-01-19T17:53:33.535Z"
   ],
  "titles": [
     "Primer",
     "Oh Lucky Man!",
     "Being There"
   ],
  "uids": [
     "e3e435ab-659b-4741-9bff-243ce0906a28",
     "e6e07110-07da-423d-bde3-02eb1addad8d",
     "91e2425e-1665-467d-a507-4c03b18b5649"
   ]
}
```
- The "modified" value contains the most recent file modification date and time in ISO 8601 format.
- The "added" value is an ordered list containing the date and time in ISO 8601 format that each Favorite was added to the file.
- The "titles" value is an ordered list containing the Title of each Favorite.
- The "uids" value is an ordered list containing the 36-character Content UID of each Favorite.

Want to know how to make a Roku channel in 5 minutes? Check out this Instant TV Channel Walk-Through!