Developer Console
Sign In
Sign In
Developer Console

Step 8: Contents Recipe: Matchlist Parameters

 II: Configure your Feed

STEP 1:
Load Media Feed
→
STEP 2:
Recipe Config Overview
→
STEP 3:
Set Up the Categories Recipe
→
STEP 4:
Categories Recipe: Query Parameters
→
STEP 5:
Categories Recipe: Matchlist Parameters
→
STEP 6:
Set Up the Contents Recipe
→
STEP 7:
Contents Recipe: Query Parameters
→
STEP 8:
Contents Recipe: Matchlist Parameters
→
STEP 9:
Configure Navigator

Let's continue configuring the Contents recipe by populating the matchlist parameter.

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

mTitle

Video title.

mId

Video ID (string). Used to uniquely identify the media object.

mDescription

Description of the video.

mUrl

Link to the video.

mCardImageUrl

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.

mBackgroundImageUrl

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.

mSubtitle

Subtitle for a video.

mTags

Used to associate related content. See Related Content (Through Tags) for more information.

mRecommendations

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.

mSubscriptionRequired

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.

live

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 live and not mLive.

mAvailableDate

The date the content is available represented as a String. Used in analytics and recommendations if present.

mDuration

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.

mFormat

The content's video format represented as a String such as "HLS". Used when setting the ContentMimeType during video playback (if present).

mAdCuePoints

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, 1000, 3000, etc.). At these cue point locations (1000 and 3000), Fire App Builder calls Brightcove to play an ad.

mCloseCaptionUrls

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

To better understand how the matchlist parameter works, here are some examples in JSON and XML with more detail.

JSON

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 converts title from your feed to mTitle in the Fire App Builder content model
  • id@mId converts id from your feed to mId in the Fire App Builder content model
  • description@mDescription converts description from your feed to mDescription in the Fire App Builder content model
  • videoURL@mUrl converts videoURL from your feed to mUrl in the Fire App Builder content model
  • imgURL@mCardImageUrl converts imgURL from your feed to mCardImageUrl in the Fire App Builder content model
  • imgURL@mBackgroundImageUrl converts imgURL from your feed to mBackgroundImageUrl 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.

XML

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 converts title/#text from your feed to mTitle in the Fire App Builder content model.
  • guid/#text@mId converts guid/#text from your feed to mId in the Fire App Builder content model..
  • media:content/media:title/#text@mDescription converts media:content/media:title/#text from your feed to mDescription in the Fire App Builder content model.
  • media:content/#attributes/url@mUr converts media:content/#attributes/url from your feed to mUrl in the Fire App Builder content model.
  • media:content/#attributes/url@mCardImageUrl converts media:content/#attributes/url from your feed to mCardImageUrl in the Fire App Builder content model.
  • media:content/#attributes/url@mBackgroundImageUrl converts media:content/#attributes/url from your feed to mBackgroundImageUrl 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 image cards appear in a list of thumbnails. When you select one of the image cards, a larger background image appears in the upper-right area of the screen.

The two images also appear on the Content Preview screen:

Here the image card appears a little larger, with the background image filling the entire background of the screen. The background image has a dark gray overlay.

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:

Related content

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