Set Up the Category Recipe

In this step, you will query for the categories from your feed. Categories group your media into different collections or channels. It's a way of organizing your media so that all your video isn't in one long list. For a general overview of recipe configuration, see Recipe Configuration Overview.

Configure the Category Recipe

  1. If you didn't already name the LightCast recipe files, see Customize the Recipe Files in the previous topic.

  2. Open the <project name>CategoriesRecipe.json file (located in app > assets > recipes).
  3. Configure the file's values as explained in the following table. For parameters need more explanation, the explanations appear in sections after the table.

    Key Description

    cooker

    Defines which utility will take the parameters defined in the recipe and execute the logic. In other words, the cooker "cooks" the recipe. Leave it at the default value: DynamicParser.

    format

    Specifies the data format for the incoming data feed. Options are json or xml.

    model

    Specifies the content model for the data. The content model provides the structure for your content and maps it into the Fire App Builder UI. Leave it at the default: com.amazon.android.model.content.ContentContainer.

    translator

    Specifies whether translation or reflection is used when converting your feed's objects to the Fire App Builder content model. Translation is faster and recommended. To use translation, simply leave the value at the default: ContentContainerTranslator. If you want to use reflection instead, remove the translator parameter altogether from the recipe.

    modelType

    Specifies whether the feed is an array or a single object. Available options are array or single. Almost all feeds are array. For example, if your JSON feed is enclosed within square brackets, or your XML feed has nested angle brackets, choose array. If your feed is structured as a single object, choose single.

    query

    A query used to return categories from your media feed. The syntax of the query depends on the structure of your feed. You will need to construct the right query to get your categories. For JSON feeds, use Jayway JsonPath syntax for the query syntax. For XML feeds, use XPath expressions for the query syntax. See query Parameter below for more details.

    queryResultType

    If the result from the query (a specified in the query parameter) returns a list of strings, include this queryResultType parameter and set it equal to []$. If the query's result is an object (a map), omit this parameter. (Fire App Builder needs to know the result type because it will needs to push an object into a Java hashmap.)

    matchList

    The query that you defined in the query parameter returns a result. This result needs to be mapped from your feed's names to the names Fire App Builder uses in its content model. The matchList parameter maps the results from the query to the name for media categories in Fire App Builder. See matchList Parameter for more details.

    keyDataType

    The media objects that are related to the category. It's essential to identify which media should be grouped into which category. Similar to matchList, you target the items on the left followed by @ and then keyDataPath to map and identify these media objects to the category. For example: StringKey@keyDataPath. See keyDataType Parameter for more details.

query Parameter

The syntax you use differs between JSON and XML. See the tab that is relevant to your feed:

JSON Feeds

The sample app in Fire App Builder reads from a generic LightCast media feed that uses a JSON format. The Categories recipe uses the following value for the query parameter to return a list of categories from your feed: $..categories[*]. This is Jayway JsonPath syntax. Here's what this syntax means:

Query Syntax What It Matches
$ Specifies the root directory as the beginning of the search.
.. Indicates a recursive search in every directory and subdirectory of the root for matches.
categories[] Says to look for the named array called "categories".
* Matches any contents (wildcard).

Putting it all together: $..categories[*] Starts at the root ($), looks in every directory and subdirectory recursively for matches (..), and looks to match on a named array called categories, with any contents in the array (*).

You can test your queries using the Jayway JsonPath Evaluator.

With the sample app in Fire App Builder, if you run this query ($..categories[*]) against the default LightCast feed URL (http://www.lightcast.com/api/firetv/channels.php?app_id=249&app_key=gtn89uj3dsw&action=channels_videos), the result returns the category names as strings, like this:

[
   "Jamaican Attractions",
   "The Country Jamaica",
   "Jamaican Attractions",
   "The Country Jamaica",
   "The Country Jamaica",
   "The Country Jamaica",
   "Jamaican Attractions",
   "The Country Jamaica",
   "Jamaican Attractions",
   "The Country Jamaica",
   "Jamaican Attractions",
   "Jamaican History",
   "The Country Jamaica",
   "Jamaican Attractions",
   "Jamaican History",
   "Jamaican History",
   "The Country Jamaica",
   "Jamaican Attractions",
   "Jamaican History",
   "The Country Jamaica",
   "Jamaican Attractions",
   "Jamaican History",
   "Jamaican History",
   "Jamaican History",
   "The Country Jamaica",
   "Jamaican Wildlife",
   "Jamaican Attractions",
   "The Country Jamaica",
   "Jamaican Wildlife",
   "The Country Jamaica",
   "Jamaican Attractions",
   "Jamaican Wildlife",
   "Jamaican Attractions",
   "Jamaican Wildlife"
]

(Fire App Builder will remove duplicates from the query result.)

Fire App Builder needs to take the array of objects and convert the array to a hashmap to process in a Java class. So the next parameter (queryResultType) is used to convert the array of strings into an array of objects.

"queryResultType": "[]$",

See Querying JSON for more details about constructing Jayway JsonPath queries. See also Jayway JsonPath for more details about Jayway JsonPath in general.

XML Feeds

If your feed is XML, instead of using Jayway JsonPath, you must use XPath expressions to target the specific elements in your feed. XPath reduces your XML document into various items called "nodes." The XPath syntax targets the location of specific nodes.

Suppose your XML feed contains a structure like this:

<rss>
    <channel>
        <item>
        <title>Sample Title</title>
        <pubDate>Wed, 26 Oct 2016 20:34:22 PDT</pubDate>
        <link>https://example.com/myshow/episodes/110</link>
        <author>Sample Author name</author>
        <category>Technology</category>
        <category>Gadgets</category>
        </item>
    </channel>
</rss>

Here's a sample XPath expression to get the categories in this XML feed:

//category/text()

The // looks recursively in all nodes for matches, no matter where those nodes are located in the hierarchy. category selects the category node, and text() selects the text from that node.

You can test this out using the XPath Tester/Evaluator. The response from the expression is as follows:

Text='Technology'
Text='Gadgets'

(You can ignore the Text= part. This is just part of the XPath Tester/Evaluator's display, not what was matched in the query.)

Note that with iTunes feeds, there's a general category for the feed (such as <itunes:category text="Technology">) as well as categories for each item (<category>Technology</category>). When you target categories for your recipe, you want to target the categories for each item in the feed, not the general feed categories.

Try copying your XML feed into the XPath Tester/Evaluator and selecting the categories using a similar syntax.

See Querying XML for more examples showing XPath expressions. See also XPath syntax and the examples section on XPath Examples for more details about XPath expressions in general.

matchList Parameter

The purpose of the matchList parameter is to select specific properties from the category query result and map them to the Fire App Builder content model.

The syntax used by matchList is not Jayway JsonPath or XPath expressions but rather custom Fire App Builder syntax that targets specific elements in the query result. (Hence the JSON and XML instructions are combined in the same sections.)

In the sample app in Fire App Builder, the value for the Categories recipe is StringKey@mName.

Here's how this syntax works. On the left of the @ symbol you put the property you want to target in the query result (StringKey selects the list of strings). On the right of the @ symbol you put the Fire App Builder element you want to map the property to (mName).

For the Categories recipe, your matchList parameter should map your feed's categories to mName.

In the Fire App Builder sample app, since the query result is a list of strings, StringKey is used to match the strings.

JSON Feeds

Instead of just a list of strings, suppose the result set from your query contained a JSON object such as the following:

"list": { "title" : "My category title" }

To match on My category title and convert it to mName, you would use the following:

list/title@mName

Use the forward slash (/) to go deeper in object levels (just like with with XPath). In this case, title is one object below list, which is one object below the root. After moving past these two levels, the result is simply the category name.

XML Feeds

To match XML elements, you follow a similar technique. Supposing the result is a list of strings:

Text='Technology'
Text='Gadgets'

To match the text contents and map them to the category element in the Fire App Builder UI, you would use the following syntax:

StringKey@mName

If your query result looked like this:

<list>
<title>My category title</title>
</list>

Then you would map the category title like this:

/list/title@mName

The forward slash (/) takes you one level deeper in the XML nodes.

keyDataType Parameter

Fire App Builder needs to know which media items should be grouped with the selected categories. The keyDataType parameter identifies the media items that are related to a category. This parameter is used for the Category recipe and later passed into a variable in the Contents recipe.

The Fire App Builder query result is a list of strings, so StringKey@keyDataPath is used to target the media items and associate them with the category. If your result is also a list of strings, then you would use the default:

"keyDataType": "StringKey@keyDataPath"

However, suppose your media objects were listed inside an assets node that in turn was nested inside a container node, like this:

"container": {
    "assets": [
    "5825652561001",
    "5825652558001",
    "5825652569001",
    "5873045223001",
    ]
}

or this:

<container>
  <assets>
    <id>5825652561001</id>
    <id>5825652558001</id>
    <id>5825652569001</id>
    <id>5873045223001</id>
  </assets>
</container>

To get the media objects, you would write the query like this:

container/assets@keyDataPath

Similar to the matchList parameter, the keyDataType query does not use Jayway JsonPath syntax either. Instead, you match each node by writing the node name followed by / to move into the next level. container/assets matches all the items at this level.

On the right of the ampersand @, the keyDataPath key is how these media objects are stored and used by Fire App Builder. The @keyDataPath helps match up the items with the Fire App Builder content model.

Feeds without Categories

If your feed lacks categories but you have separate feeds for each category, you can hard-code the category names when you configure Navigator.json. This will group all the videos in a particular feed with a particular category. More detail for this approach is provided in the "Hardcoding Your Categories."

Next Steps

Now that you've configured the categories for your app's media feed, you need to configure the contents. See Set Up your Contents Recipe.