開発者コンソール

手順8: コンテンツレシピ: matchListパラメーター

手順8: コンテンツレシピ: matchListパラメーター

コンテンツレシピの構成を続行して、matchListパラメーターを設定しましょう。

matchListパラメーター

matchListパラメーターは、queryの結果から特定のプロパティを選択し、結果内のプロパティをFire App Builderのコンテンツモデルにマッピングします。matchListで使用される構文はFire App Builderのカスタム構文で、特定のプロパティをターゲットにします。

Fire App Builderのサンプルアプリの場合、コンテンツレシピの値は、タイトル、ID、説明、メディア、画像をFire App Builderのコンテンツモデルにマッピングする、プロパティマッピングの配列です。サンプルアプリのmatchListパラメーターは次のようになっています。

"matchList": [
  "title@mTitle",
  "id@mId",
  "description@mDescription",
  "videoURL@mUrl",
  "imgURL@mCardImageUrl",
  "imgURL@mBackgroundImageUrl",
  "channel_id@mChannelId"
]

このmatchList構文の動作について説明すると、matchListの処理は、queryパラメーターによって返された結果(この例ではフィード内のアイテム)から始まります。アットマーク(@)の左側には、ターゲットにするプロパティ(たとえばtitle)を指定します。アットマーク(@)の右側には、プロパティのマッピング先となるFire App Builderモデル要素(たとえばmTitle)を指定します。

次の表は、フィードのプロパティをマッピングできるFire App Builderの要素の一覧です。アスタリスクは必須のタグを示します。

Fire App Builderでの名前 説明

mTitle

ビデオのタイトル。

mId

ビデオID(文字列)。メディアオブジェクトを一意に識別するために使用されます。

mDescription

ビデオの説明。

mUrl

ビデオへのリンク。

mCardImageUrl

ホーム画面に表示される画像のサムネイル。ほかのメディアのサムネイルと並べて表示されます。最適なサイズは548 x 452pxです。詳細については、画像解像度のセクションを参照してください。

mBackgroundImageUrl

メディアが選択されたときに表示される大きな画像。最適なサイズは1920 x 1080pxです。詳細については、画像解像度のセクションを参照してください。

mSubtitle

ビデオのサブタイトル。

mTags

関連コンテンツを関連付けるために使用されます。詳細については、関連コンテンツ(タグを使用)を参照してください。

mRecommendations

コンテンツの再生後にユーザーに薦めるコンテンツIDのリスト。JSON文字列配列の文字列表現です。この機能の実装方法の詳細については、おすすめ機能の概要を参照してください。

mSubscriptionRequired

このコンテンツに定期購入が必要かどうかを検出するブール値。Amazonアプリ内課金で使用されます。コンテンツを視聴するために定期購入が必要な場合はtrue、それ以外の場合はfalseです。

live

ライブストリームコンテンツを識別するために使用されます。ライブストリームコンテンツでは、ユーザーが以前に視聴していたメディアに戻っても、[最初から観る] ボタンは表示されません。詳細については、ライブストリームの構成を参照してください。このタグはmLiveではなくliveであることに注意してください。

mAvailableDate

コンテンツを利用できる日付の文字列表現。指定されている場合、分析とおすすめ機能に使用されます。

mDuration

コンテンツの再生時間を表すlong値。ここで設定すると、再生アクティビティで使用され、進行状況バーに表示されます。

mFormat

コンテンツのビデオ形式の文字列表現(「HLS」など)。ビデオの再生中にContentMimeTypeを設定するときに使用されます(指定されている場合)。

mAdCuePoints

広告再生用のキューポイントを表す整数のリスト。指定したキューポイントで広告が再生されます。このタグはBrightcoveの広告で使用されます。各コンテンツには広告キューポイントのリストがあります(10003000など)。Fire App Builderは、これらのキューポイント(10003000)の位置でBrightcoveを呼び出して広告を再生します。

mCloseCaptionUrls

コンテンツのクローズドキャプションを表す文字列(URL)のリスト。プレーヤーが字幕の表示に使用する実際のクローズドキャプションは、これらのURLから提供されます。URLは、使用しているクローズドキャプションの形式に一致する必要があります。たとえば、webvttを使用している場合、クローズドキャプションのURLは、プレーヤーが使用するwebvttファイルを指す必要があります。

必須

以下では、matchListパラメーターの動作を理解しやすくするために、JSONとXMLの例を詳しく取り上げます。

JSON

Fire App Builderのサンプルアプリの動作を順番に見ていきましょう。Fire App BuilderのLightCastメディアフィードでは、queryパラメーターの結果として次の値が返されます。

[  
   {  
      "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"
   }
]

matchListパラメーターは、フィード内のこれらのプロパティ名を、Fire App Builderのコンテンツモデルで使用される名前に変換します。

[
    "title@mTitle",
    "id@mId",
    "description@mDescription",
    "videoURL@mUrl",
    "imgURL@mCardImageUrl",
    "imgURL@mBackgroundImageUrl"
  ]

次に例を示します。

  • title@mTitleは、フィードのtitleをFire App BuilderコンテンツモデルのmTitleに変換します。
  • id@mIdは、フィードのidをFire App BuilderコンテンツモデルのmIdに変換します。
  • description@mDescriptionは、フィードのdescriptionをFire App BuilderコンテンツモデルのmDescriptionに変換します。
  • videoURL@mUrlは、フィードのvideoURLをFire App BuilderコンテンツモデルのmUrlに変換します。
  • imgURL@mCardImageUrlは、フィードのimgURLをFire App BuilderコンテンツモデルのmCardImageUrlに変換します。
  • imgURL@mBackgroundImageUrlは、フィードのimgURLをFire App BuilderコンテンツモデルのmBackgroundImageUrlに変換します。

(この例では名前の多くが一致していますが、独自のフィードには、videoTitlevideoSummaryなどの用語が含まれていることがあります。)

独自のフィードの用語に合わせてアットマーク@の左側をカスタマイズし、Fire App Builderコンテンツモデルでの用語に合わせて@の右側をカスタマイズします。

フィードでは、各要素が単純なキーと値のペアになっているとは限りません。さまざまなレベルの入れ子がある場合、matchListの値は次のようになります。

    "common/title@mTitle",
    "assetId@mId",
    "common/subtitle@mSubtitle",
    "common/description@mDescription",
    "video/videoURL@mUrl",
    "imgURLs/ImageSmall@mCardImageUrl",
    "imgURLs/ImageLarge@mBackgroundImageUrl"

この構文では、要素の各レベルをスラッシュ(/)で区切ります。たとえば、common/titleは、commonオブジェクト内のtitleプロパティに一致します。

XML

XMLを使用した例を見てみましょう。次のようなXMLフィードがあるとします。

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0"  >
  <channel>
    <title>写真で見る米国ニュースのコンテンツミックス 9x16</title>
    <description>スクリーンフィードコンテンツサーバー</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>ニュース</category>
      <media:content url="http://samples.screenfeed.com/1" type="jpg" type="image/jpeg">
        <media:title type="plain">1080x1920 - 英語 - 字幕付き</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>

ここで、queryパラメーターは既にコンテンツ(各<item>)を識別しているものとします。したがって、matchListパラメーターではqueryの結果をマッピングするだけです。

これらのプロパティをFire App Builderのコンテンツモデルにマッピングする場合、matchListパラメーターは次のようになります。

  "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",
  ]

この場合、次のような変換が行われます。

  • title/#text@mTitleは、フィードのtitle/#textをFire App BuilderコンテンツモデルのmTitleに変換します。
  • guid/#text@mIdは、フィードのguid/#textをFire App BuilderコンテンツモデルのmIdに変換します。
  • media:content/media:title/#text@mDescriptionは、フィードのmedia:content/media:title/#textをFire App BuilderコンテンツモデルのmDescriptionに変換します。
  • media:content/#attributes/url@mUrは、フィードのmedia:content/#attributes/urlをFire App BuilderコンテンツモデルのmUrlに変換します。
  • media:content/#attributes/url@mCardImageUrlは、フィードのmedia:content/#attributes/urlをFire App BuilderコンテンツモデルのmCardImageUrlに変換します。
  • media:content/#attributes/url@mBackgroundImageUrlは、フィードのmedia:content/#attributes/urlをFire App BuilderコンテンツモデルのmBackgroundImageUrlに変換します。

JSONとは異なり、XMLパーサーには、テキスト、属性、CDATAの各アイテムをターゲットにする非標準の方法がいくつか用意されています。以下のセクションで詳細を説明します。

テキストをターゲットにする方法

要素内のテキストをターゲットにするには、#textセレクターを使用します(これはXPathのtext()と似ています)。 たとえば、次のような要素をターゲットにするとします。

<title>チャンネル1</title>

この場合、次の構文を使用できます。

title/#text

属性をターゲットにする方法

属性も特別な方法で処理されます。たとえば、次のような要素のurl属性をターゲットにするとします。

<media:content url="http://samples.screenfeed.com/1" type="jpg" type="image/jpeg">

要素の属性をターゲットにするには、次のように#attributesを使用する必要があります。

media:content/#attributes/url

CDATAをターゲットにする方法

CDATA要素内の値をターゲットにするには、特別な#cdata-sectionセレクターを使用します。たとえば、次の要素をターゲットにするとします。

<description><![CDATA[<p>内部に<a rel="nofollow" href="https://randomlinkurl.com”>リンク</a>を含む複雑な説明テキスト。</p>]]></description>

このCDATAで囲まれた値をターゲットにするには、次のように#cdata-sectionを使用します。

description/#cdata-section

特別な要素をターゲットにする方法を示す例

これらの特別な要素をターゲットにするフィードとレシピの例を以下に示します。次のようなXMLフィードがあるとします。

<?xml version="1.0" encoding="UTF-8"?>
<rss
    xmlns:atom="http://www.example.com” version="2.0">
    <channel>
        <title>チャンネル1</title>
        <description>チャンネルの説明テキスト。</description>
        <language>ja-JP</language>
        <item>
            <title>アイテム1</title>
            <link>http://www.example.com/item1.mp4</link>
            <id>1234</id>
            <description>
                <![CDATA[<p>内部に<a rel="nofollow" href="https://randomlinkurl.com">リンク</a>を含む複雑な説明テキスト。</p>]]>
            </description>
            <image url="http://www.example.com/item1.png" />
        </item>
    </channel>
</rss>

コンテンツレシピは次のようになります。

{
    "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"
    ]
}

もう1つの例を示します。次のようなフィードがあるとします。

<rss>
    <channel>
        <item>
        <title>サンプルタイトル1</title>
        <pubDate>Wed, 26 Oct 2016 20:34:22 PDT</pubDate>
        <link>https://example.com/myshow/episodes/110</link>
        <author>サンプル作者名1</author>
        <category>テクノロジー</category>
        <category>ガジェット</category>
        </item>

        <item>
        <title>サンプルタイトル2</title>
        <pubDate>Wed, 23 Oct 2016 08:33:12 PDT</pubDate>
        <link>https://example.com/myshow/episodes/109</link>
        <author>サンプル作者名2</author>
        <category>ニュース</category>
        </item>
    </channel>
</rss>

matchListパラメーターは次のようになります。

"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"
]

次のようなXMLがあるとします。

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
   <channel>
      <title>チャンネル1</title>
      <description>チャンネルの説明テキスト。</description>
      <language>ja-JP</language>
      <item>
         <title>アイテム1</title>
         <link>http://www.example.com/item1.mp4</link>
         <id>1234</id>
         <description><![CDATA[<p>内部に<a rel="nofollow" href="https://randomlinkurl.com">リンク</a>を含む複雑な説明テキスト。</p>]]></description>
         <image url="http://www.example.com/item1.png" />
      </item>
   </channel>
</rss>

この例のmatchListパラメーターは次のようになります。

"matchList": [
  "title/#text@mTitle"
  "link/#text@mUrl"
  "description/#cdata-section@mDescription"
  "id/#text@mId"
  "image/#attributes/url@mCardImageUrl"
]
}

(ここで、queryパラメーターは既にコンテンツ(各<item>)を識別しています。この場合のquery//itemです。次に、matchListパラメーターにより、各<item>のプロパティがFire App Builderのコンテンツモデルにマッピングされます。)

画像解像度

アプリでは、メディア用に画像カードと背景画像の2つの画像を使用できます。2種類の画像は使用場所が異なり、各画像が使用されるコンテナにも多少の違いがあります。

以下のスクリーンショットは、コンテンツのホーム画面における2種類の画像の違いを示しています。

画像カードはサムネイルの一覧に表示されます。画像カードの1つを選択すると、画面右上の領域に大きい背景画像が表示されます。

2つの画像は、コンテンツのプレビュー画面にも表示されます。

ここでは画像カードが少し大きく表示され、背景画像が画面の背景全体を占めます。背景画像には、濃いグレーのオーバーレイが適用されます。

推奨される画像サイズ(幅x高さ)は次のとおりです。

  • 画像カード: 548 x 452px。これより大きい画像も使用できますが、縮小されます。この画像は、トリミングされて320 x 240pxのコンテナに表示される場合もあります。
  • 背景画像: 1920 x 1080px。これより大きい画像も使用できますが、縮小されます。この画像は、トリミングされて1120 x 800pxのコンテナに表示される場合もあります。

Fire App Builderで画像がトリミングされる場合は、画像の両側が切り取られ、縦横比が維持されます(つまり、中央部分が残されます)。

関連コンテンツ(タグを使用)

ビデオの下には関連コンテンツセクションがあり、同じタグを持つほかのビデオが表示されます。

関連コンテンツ

アプリの関連コンテンツセクションにビデオを表示するには、matchListパラメーターで、独自のタグをFire App BuilderモデルのmTagsにマッチさせる必要があります。次に例を示します。

common/tags@mTags

ここでは、tags要素がcommon要素内に配置されています。この構文は、common/tagsmTagsに変換します。これにより、Fire App Builderでタグを読み取り、関連するメディアオブジェクトを表示できるようになります。

ただし、Fire App BuilderのサンプルアプリのLightCastフィードにはタグが含まれていません。このような場合は、フィードにタグがなくても関連コンテンツを表示するフォールバックパラメーターをtrueに設定できます。

Navigator.jsonファイル(アプリのassetsフォルダ内)には、configオブジェクトにuseCategoryAsDefaultRelatedContentというプロパティが含まれています。

  "config": {
    "showRelatedContent": true,
    "useCategoryAsDefaultRelatedContent": true,
    "searchAlgo": "basic"
  }

useCategoryAsDefaultRelatedContenttrueに設定すると、Fire App Builderは、同じタグのコンテンツを取得するのではなく、同じカテゴリーのほかのメディアアセットを関連コンテンツとして使用します。

関連コンテンツセクションをオフにするには、Navigator.jsonapp > assets内)でshowRelatedContentをfalseに設定します。

ビデオURLの指定に関する注意事項

フィードにビデオURLを指定するときは、ビデオURLに.mp4などのファイル拡張子を含める必要があります。Fire App Builderでは、ファイル拡張子のないURL値は処理できません。

次のステップ

これでアプリのメディアフィードのカテゴリーとコンテンツが構成されました。次は、フィードをアプリのUIに関連付ける必要があります。ナビゲーターを構成するを参照してください。