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,
or want to view 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.
An S3 bucket in your Amazon AWS account contains a file for each Roku device that uses Favorites.
The name of the S3 file is 36-characters long and is different for each channel and device.
The file name uniquely identifies a single channel installed on a single Roku device.
Each file contains a list of Favorites for a specific Roku device.
Each time the channel is started,
the customer's Roku device reads their Favorites file from your AWS S3 Favorites bucket.
The list contained in the file is used to display the customer's Favorites.
When a customer adds or removes a Favorite,
their Roku device writes an updated copy of the Favorites list to the file in your AWS S3 Favorites bucket.
Because there is a separate Favorites file for each Roku device,
customers with more than one Roku device will have a different Favorites list on each device.
How to add Favorites capability to UNLIMITED and COMMERCIAL channels:
Create the Favorites Bucket
Log into your AWS account and go to the S3 section of your AWS control panel.
Click the Create Bucket button.
This should be a new bucket that is used only for Favorites files.
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)
The bucket Region must be set to "US East (N. Virginia)".
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
Go to the IAM (Identity and Access Management) section of your AWS control panel.
Click the Policies link on the left side of the page.
Click the Create policy button near the top of the page.
Click the JSON tab, and erase the sample lines of JSON text.
Copy the security policy below and paste it into the JSON text box.
Replace the two instances of
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.
Click the Next: Tags button near the bottom of the page.
Click the Next: Review button near the bottom of the page.
Provide a new Policy Name, for example "my-favorites-policy".
You may optionally also enter a Policy Description.
Click the Create policy button near the bottom of the page.
Click the User groups link on the left side of the page.
Click the Create group button near the top of the page.
Provide a new User group name, for example "my-favorites-group".
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.
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.
Click the Users link on the left side of the page.
Click the Add Users button near the top of the page.
Provide a new User name,
for example "my-favorites-user".
Click the Next button near the bottom of the page.
Check the checkbox to the left of the previously created Group name,
then click the Next button near the bottom of the page.
Click the Create user button near the bottom of the page.
Click the previously created User name from the list of users.
This will display a Summary page for the user.
Click the Security credentials link or tab.
Click either of the Create access key buttons.
then click the Next button.
Click the Create access key button.
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.
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
Sign into Instant TV Channel and select the channel that you want to configure for Favorites.
Go to the channel's Keys & CDNs page.
Under AWS S3 Favorites Storage,
copy the new Favorites bucket name into the Favorites Bucket Name box.
Copy the IAM user's Access Key ID into the Favorites Access Key ID box.
Copy the IAM user's Secret Access Key into the Favorites Secret Access Key box.
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.
Click the Account link on the left side of the page to go to your Account page.
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.
Change Show Custom Springboard Buttons to "Yes - Springboard Buttons Can Be Edited".
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.
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.)
Scroll down to the last button parameter.
Usually this will be Button 3.
Click the New button.
This will create a new button.
Change the new button's Action parameter to "Favorites".
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.
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.
At the location in the content tree where you would like the Favorites to be displayed,
add a "New MRSS or Playlist" item.
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
The optional Keys & CDNs 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.
The Keys & CDNs 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.
The Keys & CDNs 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.
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".
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".
The Theme FavoritesEnabled parameter is identical the Keys & CDNs Favorites Enabled parameter.
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".
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.".
The Theme FavoritesMaximumItems parameter is the maximum number of Favorites that can be in a device's Favorites list.
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".
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!".
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.
The Favorites File
It may be useful to periodically examine the contents of your Favorites files in order to analyze which content items your users consider to be favorites.
Favorites files contain a playlist in JSON format text.
The contents of a typical Favorites file might be: