Step 8: Contents Recipe: Matchlist Parameters
Let's continue configuring the Contents recipe by populating the matchlist
parameter.
- matchList Parameter
- Targeting Text
- Targeting Attributes
- Targeting CDATA
- Examples Showing How to Target Special Elements
- Note About Targeting Video URLs
- Next Steps
matchList Parameter
The matchList
parameter selects specific properties in the result from query
and maps the properties in the results to Fire App Builder's content model. The syntax used by matchList
is custom Fire App Builder syntax that targets specific properties.
In the sample app in Fire App Builder, the value for the Contents recipe is an array of property mappings that maps the title, id, description, media, and images to Fire App Builder's content model. This is what the matchlist
parameter looks like in the sample app:
"matchList": [
"title@mTitle",
"id@mId",
"description@mDescription",
"videoURL@mUrl",
"imgURL@mCardImageUrl",
"imgURL@mBackgroundImageUrl",
"channel_id@mChannelId"
]
Here's how this matchList
syntax works. matchList
starts with the result returned from the query
parameter — in this case, the items in your feed. On the left of the ampersand (@
) you put the property you want to target (for example, title
). On the right of the ampersand (@
), you put the Fire App Builder model element you want to map the property to (for example, mTitle
).
The following table lists the Fire App Builder elements that you can map properties of your feed to. Asterisks indicate required tags.
Fire App Builder Name | Description |
---|---|
|
Video title. |
|
Video ID (string). Used to uniquely identify the media object. |
|
Description of the video. |
|
Link to the video. |
|
Image thumbnail that appears on the home screen alongside other media thumbnails. The ideal size is 548px by 452px. See the following section on Image Resolutions for more detail. |
|
Larger image that appears when media is selected. The ideal size is 1920px x 1080px. See the following section on Image Resolutions for more detail. |
|
Subtitle for a video. |
|
Used to associate related content. See Related Content (Through Tags) for more information. |
|
A list of content ids to recommend to the user after the content is played. A string representation of a JSON array of strings. See Recommendations for more details on implementing this feature. |
|
Boolean value to detect if a subscription is required for this content. Used with Amazon In-App Purchase. True if the a subscription is required in order to watch the content, and false otherwise. |
|
Used to identify live stream content. For live stream content, the "Watch from Beginning" button is not shown when users return to the media after having previously watching it. See Configure Live Streams for more information. Note that this tag is |
|
The date the content is available represented as a String. Used in analytics and recommendations if present. |
|
The content's duration represented as a long. If this is set here, it will be used in the playback activity, shown in the progress bar. |
|
The content's video format represented as a String such as "HLS". Used when setting the ContentMimeType during video playback (if present). |
|
A list of integers that represent the cue points for ad playback. At the given cue points, the ad will play. This tag is used with ads for Brightcove. Each content has a list of ad cue points (for example, |
|
A list of Strings (URLs) that represent the closed captions of the content. These URLs provide the actual closed captions that the player uses to display the captions. The URLs correspond with whatever closed caption format you're using. For example, if you're using webvtt, the closed caption URL should lead to a webvtt file that the player will use. |
Required
mTitle
, mId
, mDescription
, mUrl
, mCardImageUrl
, and mBackgroundImageUrl
. If you have just one image (not both a card image and background image), you can map the same property in your feed to both mCardImageUrl
and mBackgroundImageUrl
.To better understand how the matchlist
parameter works, here are some examples in JSON and XML with more detail.
Let's step through the details in the Fire App Builder sample app. In the LightCast media feed for Fire App Builder, the selections from the query
parameter returns the following:
[
{
"id":"169313",
"title":"Beautiful Whale Tail Uvita Costa Rica",
"description":"Beautiful Whale Tail Uvita Costa Rica",
"duration":"86",
"thumbURL":"http://le2.cdn01.net/videos/0000169/0169313/thumbs/0169313__007f.jpg",
"imgURL":"http://le2.cdn01.net/videos/0000169/0169313/thumbs/0169313__007f.jpg",
"videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169313/video_1880k/T7J66Z106.mp4?source=firetv&channel_id=13454",
"categories":[
"Costa Rica Islands"
],
"channel_id":"13454"
},
{
"id":"169322",
"title":"Scuba Diving - Costa Rica",
"description":"Scuba Diving - Costa Rica (Playa Ocotal & The Bat Islands)",
"duration":"205",
"thumbURL":"http://le1.cdn01.net/videos/0000169/0169322/thumbs/0169322__002f.jpg",
"imgURL":"http://le1.cdn01.net/videos/0000169/0169322/thumbs/0169322__002f.jpg",
"videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169322/video_1880k/S6IZ6M1QM.mp4?source=firetv&channel_id=13455",
"categories":[
"Costa Rica Underwater"
],
"channel_id":"13455"
},
{
"id":"169312",
"title":"San Lucas Trip",
"description":"Isla San Lucas, Puntarenas, Costa Rica",
"duration":"192",
"thumbURL":"http://le1.cdn01.net/videos/0000169/0169312/thumbs/0169312__003f.jpg",
"imgURL":"http://le1.cdn01.net/videos/0000169/0169312/thumbs/0169312__003f.jpg",
"videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169312/video_1880k/M0CAAG18G.mp4?source=firetv&channel_id=13454",
"categories":[
"Costa Rica Islands"
],
"channel_id":"13454"
},
{
"id":"169309",
"title":"San Jose, Costa Rica",
"description":"San Jose, Costa Rica",
"duration":"130",
"thumbURL":"http://le2.cdn01.net/videos/0000169/0169309/thumbs/0169309__009f.jpg",
"imgURL":"http://le2.cdn01.net/videos/0000169/0169309/thumbs/0169309__009f.jpg",
"videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169309/video_1880k/88HFXX0IL.mp4?source=firetv&channel_id=13453",
"categories":[
"Costa Rica Attractions"
],
"channel_id":"13453"
}
]
The matchList
parameter converts these property names in the feed to the names used in Fire App Builder's content model:
[
"title@mTitle",
"id@mId",
"description@mDescription",
"videoURL@mUrl",
"imgURL@mCardImageUrl",
"imgURL@mBackgroundImageUrl"
]
For example:
title@mTitle
convertstitle
from your feed tomTitle
in the Fire App Builder content modelid@mId
convertsid
from your feed tomId
in the Fire App Builder content modeldescription@mDescription
convertsdescription
from your feed tomDescription
in the Fire App Builder content modelvideoURL@mUrl
convertsvideoURL
from your feed tomUrl
in the Fire App Builder content modelimgURL@mCardImageUrl
convertsimgURL
from your feed tomCardImageUrl
in the Fire App Builder content modelimgURL@mBackgroundImageUrl
convertsimgURL
from your feed tomBackgroundImageUrl
in the Fire App Builder content model
(In this example, a lot of the names are the same, but in your feed, might might have terms such as videoTitle
, videoSummary
, and so on.)
Customize the left side of the ampersand @
to correspond with your own feed's terminology; customize the right side of the @
to correspond with Fire App Builder's term in its content model.
Your feed might not list each element in a simple key-value pair. If you have various levels of nesting, your matchList
value might look like this:
"common/title@mTitle",
"assetId@mId",
"common/subtitle@mSubtitle",
"common/description@mDescription",
"video/videoURL@mUrl",
"imgURLs/ImageSmall@mCardImageUrl",
"imgURLs/ImageLarge@mBackgroundImageUrl"
With this syntax, the forward slash (/
) separates elements at each level. For example, common/title
looks inside the common
object to match on the title
property.
Let's look an an example using XML. Suppose your XML feed looks like this:
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" … …>
<channel>
<title>Content Mix for US News-in-Pictures 9x16</title>
<description>Screenfeed Content Server</description>
<lastBuildDate>Mon, 08 Dec 2014 22:55:16 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>John Anderson ……</title>
<guid isPermaLink="false">1</guid>
<pubDate>Mon, 08 Dec 2014 22:55:16 GMT</pubDate>
<category>News</category>
<media:content url="http://samples.screenfeed.com/1" type="jpg" type="image/jpeg">
<media:title type="plain">1080x1920 - English - with caption</media:title>
<media:credit>© 2014 News Agency</media:credit>
<media:thumbnail url="http://samples.screenfeed.com/public/us-news-in-pictures/1080x1920/h9xnRIN9CUGiTWNQBBrjOw-1080x1920h-1" type="jpg" />
</media:content>
</item>
...
</channel>
</rss>
The query
parameter already identifies the content (each <item>
). So the matchList
parameter just needs to map the results from query
.
To map these properties to the Fire App Builder content model, the matchList
parameter would look like this:
"matchList": [
"title/#text@mTitle",
"guid/#text@mId",
"media:content/media:title/#text@mDescription",
"media:content/#attributes/url@mUrl",
"media:content/#attributes/url@mCardImageUrl",
"media:content/#attributes/url@mBackgroundImageUrl",
]
In this case, here's how the conversions happen:
title/#text@mTitle
convertstitle/#text
from your feed tomTitle
in the Fire App Builder content model.guid/#text@mId
convertsguid/#text
from your feed tomId
in the Fire App Builder content model..media:content/media:title/#text@mDescription
convertsmedia:content/media:title/#text
from your feed tomDescription
in the Fire App Builder content model.media:content/#attributes/url@mUr
convertsmedia:content/#attributes/url
from your feed tomUrl
in the Fire App Builder content model.media:content/#attributes/url@mCardImageUrl
convertsmedia:content/#attributes/url
from your feed tomCardImageUrl
in the Fire App Builder content model.media:content/#attributes/url@mBackgroundImageUrl
convertsmedia:content/#attributes/url
from your feed tomBackgroundImageUrl
in the Fire App Builder content model.
In contrast to JSON, the parser for XML has a few non-standard ways of targeting text, attributes, and CDATA items. Details are in the following sections.
Targeting Text
To target text inside an element, use the #text
selector. (This is similar to text()
in XPath.) For example, suppose you want to target an element like this:
<title>Channel 1</title>
You would use this syntax:
title/#text
Targeting Attributes
Attributes are also handled in a special way. Suppose you want to target the url
attribute of an element such as this:
<media:content url="http://samples.screenfeed.com/1" type="jpg" type="image/jpeg">
To target attributes of elements, you must use #attributes
, like this:
media:content/#attributes/url
Targeting CDATA
To target a value inside a CDATA
element, you use a special #cdata-section
selector. For example, suppose you want to target this element:
<description><![CDATA[<p>A complicated description text that contains a <a rel="nofollow" href="https://randomlinkurl.com”>link</a> inside.</p>]]></description>
To target this value inside CDATA
, you muse use #cdata-section
, like this:
description/#cdata-section
Examples Showing How to Target Special Elements
Here's an example showing a feed and recipe that targets these special elements. Suppose your XML feed looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<rss
xmlns:atom="http://www.example.com” version="2.0">
<channel>
<title>Channel 1</title>
<description> Channel’s description text. />
<language>en-US</language>
<item>
<title>Item 1</title>
<link>http://www.example.com/item1.mp4</link>
<id>1234</id>
<description>
<![CDATA[<p>A complicated description text that contains a <a rel="nofollow" href="https://randomlinkurl.com”>link</a> inside.</p>]]>
</description>
<image url="http://www.example.com/item1.png" />
</item>
</channel>
</rss>
Your Contents recipe would look like this:
{
"cooker": "DynamicParser",
"format": "xml",
"model": "com.amazon.android.model.content.Content",
"translator": "ContentTranslator",
"modelType": "array",
"query": "//item",
"matchList": [
"title/#text@mTitle",
"link/#text@mUrl",
"description/#cdata-section@mDescription",
"id/#text@mId",
"image/#attributes/url@mCardImageUrl"
]
}
Here's another example. Suppose your feed looks like this:
<rss>
<channel>
<item>
<title>Sample Title 1</title>
<pubDate>Wed, 26 Oct 2016 20:34:22 PDT</pubDate>
<link>https://example.com/myshow/episodes/110</link>
<author>Sample Author name 1</author>
<category>Technology</category>
<category>Gadgets</category>
</item>
<item>
<title>Sample Title 2</title>
<pubDate>Wed, 23 Oct 2016 08:33:12 PDT</pubDate>
<link>https://example.com/myshow/episodes/109</link>
<author>Sample Author name 2</author>
<category>News</category>
</item>
</channel>
</rss>
Here's what the matchlist
parameter would look like:
"matchList": [
"title/#text@mTitle",
"guid/#text@mId",
"itunes:subtitle/#text@mDescription",
"media:content/#attributes/url@mUrl",
"media:content/media:thumbnail/#attributes/url@mCardImageUrl",
"media:content/media:thumbnail/#attributes/url@mBackgroundImageUrl"
]
Suppose your XML looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<title>Channel 1</title>
<description>Channel’s description text.</description>
<language>en-US</language>
<item>
<title>Item 1</title>
<link>http://www.example.com/item1.mp4</link>
<id>1234</id>
<description><![CDATA[<p>A complicated description text that contains a <a rel="nofollow" href="https://randomlinkurl.com”>link</a> inside.</p>]]></description>
<image url="http://www.example.com/item1.png" />
</item>
</channel>
</rss>
The matchList
parameter for this example would be as follows:
"matchList": [
"title/#text@mTitle"
"link/#text@mUrl"
"description/#cdata-section@mDescription"
"id/#text@mId"
"image/#attributes/url@mCardImageUrl"
]
}
(Remember that first the query
parameter identifies the content (each <item>
). The query
in this case is //item
. Then the matchList
parameter maps the properties in each <item>
to the Fire App Builder content model. )
Image Resolutions
You can use two images for media in your app: an image card and a background image. The two types of images get used in different places, and the containers where each image is used also varies slightly.
The following screenshot shows the difference between the two types of images on the Content Home screen:
The two images also appear on the Content Preview screen:
The recommended image sizes (width x height) are as follows:
- Image cards: 548px by 452px. This image can be larger but will be scaled down. The image will also be cropped to fill a 320px x 240px container in some cases.
- Background images: 1920px x 1080px. This image can be larger but will be scaled down. The image will also be cropped to fill a 1120px x 800px container in some cases.
When Fire App Builder does image cropping, it preserves the aspect ratio of the image by cropping the sides of the image (thus focusing on the center).
Related Content (Through Tags)
Below the video is a Related Content section that shows other videos with the same tags:
To populate the Related Content section in the app, you need to match your tags to mTags
in the Fire App Builder model in the matchList
parameter. For example:
common/tags@mTags
Here the tags
element appears inside a common
element. This syntax converts common/tags
to tags
so Fire App Builder can read it and display related media objects.
Note that the LightCast feed in the Fire App Builder sample app doesn't include tags. However, there's a fallback parameter that you can set to true
if you want to show related content, but you don't have tags in your feed.
In your Navigator.json file (located in your app's assets folder), the config
object has a property called useCategoryAsDefaultRelatedContent
:
"config": {
"showRelatedContent": true,
"useCategoryAsDefaultRelatedContent": true,
"searchAlgo": "basic"
}
If you set useCategoryAsDefaultRelatedContent
to true
, Fire App Builder will use other media assets from the same category for the related content (rather than pulling content with the same tags).
To turn off the Related Content section, you can set showRelatedContent
to false in Navigator.json (located in app > assets).
Note About Targeting Video URLs
Note that when you target the video URL in a feed, the video URL must include a file extension such as .mp4
. Fire App Builder can't handle a URL value without file extension.
Next Steps
Now that you've configured the categories and contents for your app's media feed, you need to associate the feed with the app's UI. See Configure Navigator.
Last updated: Apr 06, 2017