Displayインターフェースのリファレンス

画面表示に対応したスキルを作成する方法については、画面付きのAlexa搭載デバイス用のスキルの作成を参照してください。

このリファレンスでは、スキルサービスコードのDisplayテンプレートを使用して、スキルの外観と操作感を想定どおりに設定する方法について説明します。ただし、ユーザーの多くは画面がサポートされていないAlexa搭載デバイスを使用するため、スキルは必ず音声での使用を一番に考えてデザインしてください。

画面表示に対応したスキル用のDisplayテンプレート

注： Fire TV CubeはDisplayインターフェースをサポートしています。他のFire TVデバイスは、現在Displayインターフェースをサポートしていません。

開発したスキルに画面表示を含めるには、スキルサービスコードでDisplayテンプレートを使用する必要があります。これらのテンプレートは、柔軟性の高いスキル開発ができるよう作成されています。

各テンプレートにはJSON表現が含まれており、画面へ送信するスキルの応答に必要に応じて含めることができます。

Alexa Skills Kitには2つのカテゴリーのDisplayテンプレートがあり、各カテゴリーには明確に定義されたテンプレートが複数含まれています。

Bodyテンプレートは、テキストと画像を表示するものです。画像を選択可能には設定できません。
Listテンプレートは、スクロール可能な項目リストと、各項目にテキストおよび省略可能な画像を付記して表示するものです。画像は、このリファレンスで説明するように選択可能に設定できます。

これらのテンプレートはそれぞれテキストと画像のサイズ、数、配置およびリストをスクロールしたときの挙動が異なり、各テンプレートに規定の構造が設定されています。テンプレートは、一貫したユーザーエクスペリエンスが得られるよう綿密に設計されています。

スキル開発でDisplayテンプレートを含む応答を構築するときには、テンプレート、テキスト、および画像を指定します。これにより、目的のユーザーエクスペリエンスを自由に設定できます。

テンプレートインターフェース（JSON）とデザイン

テンプレートの仕様については、Displayテンプレートのリファレンスを参照してください。

各テンプレートのJSONインターフェースでは、テキストフィールドおよび画像フィールドの文字列は空白またはnullに設定できます。ただし、Listテンプレートにはリスト項目を少なくとも1つ含める必要があります。

開発者コンソールの公開>ストアでのプレビューセクションでスキルに指定したスキルアイコンは、どのテンプレートでも、サイズが変更されて右上隅に自動で表示されます。このスキルアイコンは、必要に応じて変更できます。

各Bodyテンプレートは、以下の汎用インターフェースに準拠しています。

Bodyテンプレートのインターフェース

{
  "type": "string",
  "token": "string"
}

各Listテンプレートは、以下の汎用インターフェースに準拠しています。

Listテンプレートのインターフェース

{
  "type": "string",
  "token": "string",
  "listItems": [ ]
}

Display.RenderTemplateディレクティブの形式

templateアトリビュートでは、使用するテンプレート、およびテンプレートの表示時に使用する対応データすべてを指定します。以下は、Display.RenderTemplateディレクティブを含むdirectivesオブジェクトの書式を示したものです。typeプロパティには、この例のBodyTemplate1のように、テンプレート名を値として指定します。templateのその他のプロパティは、typeの値に応じて変化します。

ボタンをクリックすると表示されます。

他のテンプレートの書式については、Displayテンプレートのリファレンスを参照してください。

応答での`Display.RenderTemplate`とその他のディレクティブ

参考として、DisplayとHintの各ディレクティブを含めた応答本文を以下に示します。他のディレクティブも含めることができます。A Hintディレクティブでは、Displayテンプレートも含める必要があります。BodyTemplate2、BodyTemplate6、ListTemplate2のみがHintディレクティブをサポートしています。BodyTemplate1、BodyTemplate3、BodyTemplate7、およびListTemplate1はHintディレクティブをサポートしていません。

AudioPlayerディレクティブとVideoAppディレクティブは併用できません。

次のサンプルは、BodyTemplate1のサンプル応答です。

ボタンをクリックすると表示されます。

例：応答に`BodyTemplate2`を含める場合のディレクティブ

次に示すBodyテンプレートでは、Echo ShowとFire TV Cubeに「お気に入りの車」というタイトル、左上に戻るボタン、右上にスキルアイコン、および必要に応じてこのテンプレートに合わせてサイズの調整された画像が右側に表示されます。戻るボタンと背景画像は任意ですが、この例ではディレクティブに含めています。

ボタンをクリックすると表示されます。

Displayテンプレートのリファレンス

Displayテンプレートのリファレンスを参照してください。

DisplayテンプレートのGUI仕様

画面付きのAlexa搭載デバイスでスキルが正常に動作し適切に表示されるよう、以下の仕様を守ってください。

デバイスの仕様については、画面付きのAlexa搭載デバイスの表示と動作の仕様を参照してください。

Displayテンプレートごとの使用可能な画像サイズと書式

Displayテンプレートで参照する画像は、次の要件を満たす必要があります。

画像は、適切なファイル拡張子を持つJPEG形式またはPNG形式のものを使用できます。
テンプレートは正方形画像と長方形画像のどちらにも対応しています。各テンプレートのアスペクト比は下表に記載されています。
画像を含める場合、URLサイズを複数指定することをお勧めします。画像サイズは、目的のアスペクト比に一致し、表示時の画面のサイズではっきりとした画像が表示される最も小さいサイズが選択されます。以下の表の画面サイズを参照してください。適切なサイズの画像を指定していない場合、次に大きいサイズの画像が目的のスロットに合わせて縮小されて使用されます。縮小により画像の質が低下する可能性があるため、適切なサイズの画像を指定することを強くお勧めします。
応答速度を上げ遅延の問題に対処するには、以下の表で画像サイズを参照してください。画像は送信時に圧縮され、受信時に復元されます。
画像はインターネットからアクセス可能なHTTPS URLにホストする必要があります。
表示の最適化のため、画像の背景は透明にしてください（透過処理できる画像形式はPNGのみです）。
背景を透明にすることで、画像を幅広い形状やサイズで表示できるようになります。
見た目をムラなく高品質なものにするため、わずかなパターンまたはグラデーションのついた背景画像を使用することをお勧めします。
画像とテキストのコントラストを最適にするため、背景画像には不透明度70%の黒いレイヤーを重ねることをお勧めします。

以下の表に示しているとおり、スキル応答のすべての画像の合計ファイルサイズが3MBを超えないようにする必要があります。一般に、画像サイズを小さくすると遅延を軽減し、ユーザーエクスペリエンスを向上させることができます。

スキル応答の画像数	各画像のファイルサイズ
10	300 KB以下
6	500以下
2	1.5 MB以下
1	3 MB以下

画面付きのAlexa搭載デバイス用の各テンプレートの画像サイズを表示する

ASKランタイムコードは、デバイスごとのスキルを開発しなくてもいいようにスキルの実行を管理します。さまざまなサイズの画面で画像がどのように表示されるのかを把握しやすくなります。以下の表に、Echo ShowとFire TV Cube向けの各テンプレートでサポートされる画像サイズを示します。Echo Spotの画像は適宜サイズが小さくなります。backgroundImageフィールドの画面サイズは、フルサイズの画像の画面解像度と同じになります。小さく拡大が必要になる画像では大きなデバイスでの見た目が悪くなるため、こうした画像は使用しないでください。

各テンプレートのimageフィールドで参照する画像は、以下のサイズになります。

テンプレート	Echo Showの画面サイズ（ピクセル）：最大高さ x 幅	Fire TV Cubeの画面サイズ（ピクセル）：最大高さ x 幅
ListTemplate1（縦並び）	88 x 88	110 x 110
ListTemplate2（画像の下にテキストを配置した横並び）	高さは280ピクセルにしてください。目的のアスペクト比に応じて、幅は192～498ピクセルの間にしてください。サポートされるアスペクト比は次のとおりです（幅 x 高さ）。縦長（192 x 280）正方形（280 x 280） 4:3（372 x 280） 16:9（498 x 280）	高さは404ピクセルにしてください。目的のアスペクト比に応じて、幅は284～504ピクセルの間にしてください。サポートされるアスペクト比は次のとおりです（幅 x 高さ）。縦長（320 x 474px）正方形（404 x 404px） 4:3（380 x 284px） 16:9（504 x 284px）
BodyTemplate1（フルワイドテキスト）	インライン画像のみ	インライン画像のみ
BodyTemplate2（画像は右配置）	340 x 340	576 x 576
BodyTemplate3（画像は左配置）	340 x 340	576 x 576
BodyTemplate6（テキストが重ねられたフルスクリーン画像）	340 x 340	1920 x 1080
BodyTemplate7（前景のフルスクリーン画像と背景のフルスクリーン画像）	880 x 346（メインの画像） 1024 x 600（背景のフルスクリーン画像）	1712 x 788（メインの画像） 1920 x 1080（背景のフルスクリーン画像）

imageオブジェクトの仕様

Displayテンプレートのimageオブジェクトの書式は以下のとおりです。カードの画像に使用するimageの書式とは異なることに注意してください。

contentDescriptionプロパティには、スクリーンリーダーで画像の説明に使用するテキストを指定します。size、widthPixels、heightPixelsの各フィールドはオプションです。デフォルトではsizeの値はX_SMALLになります。別のサイズ値を記載した場合、画像表示サイズの優先順位は大きい順であり、X_LARGEが最も高くなります。つまり、大きい画像が指定されている場合、小さい画面での表示に合わせて縮小されます。ユーザーエクスペリエンスを最適化するため、適切なサイズの画像を指定し、これより大きい画像は含めないようにしてください。

widthPixelsおよびheightPixelsの整数値はオプションです。厳密に指定する場合以外は記載しないでください。

{
  "image": {
    "contentDescription": "string",
    "sources": [
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {...}
    ]
  }
}

次の表に、sizeの値の一覧を示します。

プロパティ	説明	推奨サイズ（ピクセル）幅 x 高さ
`X_SMALL`	非常に小さいコンテナ内に表示	480 x 320
`SMALL`	小さいコンテナ内に表示	720 x 480
`MEDIUM`	中サイズのコンテナ内に表示	960 x 640
`LARGE`	大きいコンテナ内に表示	1200 x 800
`X_LARGE`	非常に大きいコンテナ内に表示	1920 x 1280

テンプレートの戻るボタン

Echo ShowとFire TV Cubeではすべてのテンプレートで戻るボタンがサポートされますが、このボタンは非表示にすることもできます。Echo Spotでは戻るボタンは表示されません。ただし、このセクションでの説明に従いbackButtonオブジェクトを「VISIBLE」に設定すると、ユーザーは画面の左端から右へ大きくスワイプすることで同様の操作を行うことができます。

視覚コンポーネントのあるスキルによっては、戻るボタンを使用した方がスキル内のナビゲーションの自由度が高まります。ただし、クイズゲームなどのスキルに戻るボタンを含めると、ユーザーが戻るボタンを使用して回答済みの問題に戻ってしまうなど、不適切な動作や好ましくない動作の原因になる可能性があります。スキル開発時には、スキルに使用するDisplayテンプレートごとに戻るボタンを含めるかどうかを選択できます。戻るボタンは左上に表示されます。backButtonフィールドはすべてのDisplayテンプレートで使用できます。

backButtonオブジェクトには「HIDDEN」または「VISIBLE」アトリビュートを指定できます。テンプレートの応答に含めない場合でも、戻るボタンはデフォルトでは画面に表示されます。

注：ユーザーが戻るボタンを手動で選択した場合にイベントは送信されないため、ユーザーが戻るボタンを選択したかどうかをスキルサービスで把握することはできません。ユーザーが音声で「戻る」と言った場合は、イベントがAMAZON.PreviousIntentで送信されるため、スキルサービスで把握できます。

ユーザーが「戻る」といった場合には、スキル内でAMAZON.Previousインテントを呼び出した場合と同じ効果が得られます。

次の2つの例に、Displayテンプレートを含む応答でのbackButtonオブジェクトの記載方法を示します。

例： Displayテンプレートで戻るボタンを非表示にする

ボタンをクリックすると表示されます。

例： Displayテンプレートで戻るボタンを表示する

ボタンをクリックすると表示されます。

応答にHintディレクティブを含める

応答でHintディレクティブを使用するには、ヒントをサポートしていないBodyTemplate1、BodyTemplate3、BodyTemplate7、およびListTemplate1以外の、他の表示テンプレートも応答に含める必要があります。

ヒントは、重要な情報を伝えるためではなく、ユーザーを楽しませる省略可能なコンテンツに使用してください。Hintディレクティブを応答で使用した場合、Echo ShowとFire TV Cubeではヒントが表示されますが、Echo Spotでは表示されません。このため、ヒントを使用するスキルは、ヒントがなくても良いように設計してください。BodyTemplate3およびListTemplate1を除く各テンプレートには、Hintディレクティブを用いてヒントを含めることができます。

Hintディレクティブでは、Alexaに質問できる内容をユーザーへ知らせる文字列値を指定できます。ヒントテキストは、次の形式で画面に表示されます。

*"<wake-word>、<hint_String>を試してください"*

したがって、値に「上映されている映画を教えて」を設定し、ユーザーのウェイクワードが「Alexa」に設定されている場合、ヒントは次のように表示されます。

*"アレクサ、上映されている映画を教えてを試してください"*

簡潔にするため、次の例にはHintディレクティブのみを示していますが、ヒントが設定された一般的な応答にDisplay.RenderTemplateディレクティブを含めることも可能です。

{
  "directives": [
    {
      "type": "Hint",
      "hint": {
        "type": "PlainText",
        "text": "string"
      }
    }
  ]
}

textContentオブジェクトの仕様

すべてのテンプレートに含まれるtextContentオブジェクトには、primaryText、secondaryText、tertiaryTextの各フィールドを指定できます。これらのフィールドには異なるスタイルを設定できます。ListTemplate1テンプレートでは、テキストのスタイルは階層レベルに合わせて自動で設定されます。他のテンプレートでは、primaryText、secondaryText、tertiaryTextのそれぞれに入力したテキストは間に改行を挟んで連結され、すべて同じフォントで表示されます。primaryText、secondaryText、tertiaryTextの書式は同一であり、それぞれ8,000文字の文字数制限が課されています。

{
  "textContent": {
    "primaryText": TextField,
    "secondaryText": TextField,
    "tertiaryText": TextField
  }
}

各TextFieldの内容は以下のとおりです。typeをPlainTextに設定した場合、マークアップを含めることはできません。typeをRichTextに指定した場合、サポートされるマークアップに記載されているマークアップを含めることができます。

{
"type": "PlainText"  | "RichText",
"text": "string"
}

typeで使用できる値はPlainTextとRichTextのみです。

typeをRichTextに設定した場合、サポートされているマークアップおよびXML文字を使用してテキストの見た目を変更できます。Displayテンプレートのテキストでサポートされているマークアップを参照してください。

また、typeをRichTextに設定した場合、「text」の値で絶対ファイルパスを指定してインライン画像を使用することもできます。インライン画像の高さは特に制限されません。最大幅は880ピクセルであり、この幅には左パディングおよび右パディングが考慮されています。

「text」フィールドのテキストをアクションタグで囲むことで、このテキストを画面上で選択可能にすることができます。

次の例では、値が「cancel_trip」のアクションタグで「キャンセル」という単語を囲んでいます。ユーザーが画面上で「キャンセル」をクリックすると、トークン値が「cancel_trip」のDisplay.ElementSelectedイベントがトリガーされます。このトークンにより、こうしたタッチ対話をマッピングし、スキルサービスコード内の対応する動作を呼び出すことができます。

<action value='cancel_trip'>キャンセル</action>

例： PlainTextインスタンス

  {
    "type": "PlainText",
    "text": "私のスキルへようこそ"
  }

例： RichTextインスタンス

{
    "type": "RichText",
    "text": "<b>私のスキル</b>へようこそ "
}

Displayテンプレートの最大文字数

画面付きのAlexa搭載デバイスでは、使用するテンプレートとフォントサイズに応じて画面に表示される文字数が制限されます。記載したテキストの文字数が以下の制限を超えた場合、表示画面上でテキストの端が切り捨てられます。ユーザーがスクロールをしても、残りのテキストは表示されません。テンプレートで使用するテキストの文字数がこの制限を超えないようにしてください。

最大文字数制限にマークアップは含まれません。この文字数制限はフォントサイズが32ピクセルの場合のものであり、別のフォントサイズを使用する場合は適切に調整する必要があります。デフォルトのフォントサイズは32ピクセルです。

各テンプレートのタイトルの最大文字数は200文字です。

テンプレート	メインテキストフィールド
ListTemplate1（縦並び）	計84文字
ListTemplate2（下にテキストを配置した横並び）	計84文字
BodyTemplate1（フルワイドテキスト）	計85文字
BodyTemplate2	計8,000文字
BodyTemplate3	計8,000文字
BodyTemplate6	計85文字
BodyTemplate7	BodyTemplate7にメインテキストフィールドはありません。

画面付きのAlexa搭載デバイスのフォントサイズマッピング

画面付きのAlexa搭載デバイスのフォントサイズは、以下の更新されたフォントサイズ表に基づいて、自動的に調整されます。各テンプレートには、主要コンテンツが最も読みやすくなるようにデフォルトのフォントサイズが設定されています。これらのデフォルトサイズは、以下の値を使用して変更できます。

サイズ3がデフォルトです。Fire TV Cubeは表に記載されている他のデバイスよりも画面が大きいものの、ピクセルごとの表示サイズが他のデバイスより大きいため、Fire TV Cubeのフォントサイズの値はEcho Showよりも小さくなります。

画面付きのAlexa搭載デバイスの表示フォントサイズ

フォントサイズ	Fire TV Cube	Echo Show	Echo Spot
サイズ7	48	68	48
サイズ5	32	48	38
サイズ3	24	32	32
サイズ2	16	28	28

Displayテンプレートのテキストでサポートされているマークアップ

リッチテキストでは次のマークアップ要素とXML特殊文字がサポートされます。プレーンテキストではサポートされません。形式は常にUTF-8になります。特殊文字のエンコーディングについては、XML特殊文字の処理を参照してください。

名前	要素	マークアップの例	出力
改行	<br/>	1行目<br/>2行目	1行目 2行目
太字	<b>	これは<b>てんとう虫</b>です	これはてんとう虫です
斜体	<i>	学名<i>Coccienellidae</i>	学名Coccienellidae
下線	<u>	てんとう虫の<u>エサ</u>はアブラムシにしてください。	てんとう虫のエサはアブラムシにしてください。
フォントサイズ	<font size="2">小（28ピクセル）</font> <font size="3">中</font> <font size="7">大（68ピクセル）</font>	<font size="7">ケーキ</font> <br> <font size="3">これが史上最高のケーキのレシピです。<br> <font size="2">-小麦粉</font> <br> <font size="2">-砂糖</font> <br>	ケーキこれが史上最高のケーキのレシピです。 -小麦粉 -砂糖
アクション	<action token="VALUE">クリック可能テキスト</action> クリック可能テキストは、画面上でタップできます。	てんとう虫の<action token="2347">歴史</action>を学びましょう。	てんとう虫の歴史を学びましょう。
インライン画像	<img src='URL' width='幅' height='高さ' alt='テキスト' /> インターネットで読み込む画像です。画像のサイズは行の高さに合わせて自動で調整され、並び線またはテキストの下部に合わせて配置されます。	これはインライン<img src='https://www.example.com/test1.jpg' width='500' height='500' alt='test image' />画像です。

XML特殊文字の処理

テンプレートとカードでは、特殊文字の表示方法が異なります。Displayテンプレートのコンテンツで次の文字を使用する場合は、以下のようにエスケープしてください。

アンド記号（&）は&にします。
二重引用符（"）は"または\"にします。
単一引用符（'）は'または\'にします。
小なり記号（<）は<にします。
大なり記号（>）は>にします。
スラッシュ（\）は\\にします。
改行なしスペースはXML形式で のようにエスケープします（HTML形式は使用しないでください）。

注：カードでは、エスケープした文字はマークアップとともに表示されてしまいます。このため、カードとテンプレートの両方に適切に対応できるよう、デフォルトの表示動作を利用するのではなく、それぞれを個別にエンコードしてください。関連トピック： Amazon Alexaアプリにホームカードを追加する

リッチテキストを使用したテキストのアラインメント

リッチテキストの実装方法の概要については、textContentオブジェクトの仕様を参照してください。

テンプレートでtextContentオブジェクトを使用する場合、typeをRichTextに設定することで以下のように中央揃えを指定できるようになりました。

{
    "type" : "RichText",
    "text" : "<div align='center'>このテキストは中央揃えになります</div>"
}

例：応答で`BodyTemplate3`を使用して画面表示を作成する

BodyTemplate3テンプレートは、text、title、token、imageの各フィールドを指定できる単純なBodyテンプレートです。この例では、オプションのbackButtonは非表示にし、backgroundImageは指定していません。Displayテンプレートが画面上に表示されるときには、スキルアイコンが画面右上に必ず表示されます。公開するスキルを準備する際は、開発者コンソールの公開＞ストアでのプレビューセクションでスキルアイコンを個別に指定します。

この表示を作成する手順は次のとおりです。

JSON応答にDisplay.RenderTemplateディレクティブを追加します。
typeはBodyTemplate3に設定します。
titleフィールドとtextContentオブジェクトには、表示するテキストを設定します。
imageオブジェクトには、URLプロパティとcontentDescription（スクリーンリーダー用）を設定します。
戻るボタンの表示と非表示を切り替える場合は、backButtonアトリビュートを設定します。切り替えを指定しない場合はデフォルトのままにします。

ボタンをクリックすると表示されます。

例：応答で`ListTemplate1`を使用して画面表示を作成する

Listテンプレートにはスクロール可能な項目のリストが含まれており、リストはテキストのみを付記して縦方向に並べて、または画像を付記して横方向に並べて画面に表示できます。ListTemplate1では、項目が縦方向に並べられます。このListTemplate1テンプレートには、titleフィールド（画面上部に表示されます）、backgroundImage、およびlistItemsフィールドが1つずつ含まれます。各リスト項目には、オプションでtoken、textContent、imageの各フィールドを含めます。この表示を作成する手順は次のとおりです。

JSON応答にDisplay.RenderTemplateディレクティブを追加します。
テンプレートのtypeをListTemplate1に設定します。
titleの文字列を目的の値に設定します。
backgroundImageの文字列を目的のURLに設定します。
各リスト項目を定義します。

ボタンをクリックすると表示されます。

例：応答で`ListTemplate2`を使用して画面表示を作成する

ListTemplate2では横並びのリストが作成されます。このListTemplate2テンプレートには、titleフィールド（画面上部に表示されます）およびlistItemsフィールドが1つずつ含まれます。リスト項目の各要素には、オプションでtoken、textContent、imageの各フィールドを含めます。この表示を作成する手順は次のとおりです。

JSON応答にDisplay.RenderTemplateディレクティブを追加します。
テンプレートのtypeをListTemplate1に設定します。
titleの文字列を目的の値に設定します。
必要に応じてbackButtonの値を設定します。
以下のように、各リスト項目の構文を追加します。

この例のトークンlist_template_twoは表示内容に影響しませんが、このトークンをスキルサービスコード内で使用して項目を選択可能に設定し、追跡を行うことができます。

ボタンをクリックすると表示されます。

音声およびタッチによる選択イベントの処理

リストの各項目は、タッチで選択できるよう設定できます。画面上の選択可能要素それぞれに、要素の選択時にコールバック応答で送信される関連トークンを指定します。DisplayテンプレートのリファレンスのListテンプレートを参照してください。トークンには自由に名前を付けることができます。

注：タッチイベントに対する応答に含まれているカードは、Alexaアプリには表示されません。

スキルでは任意の選択可能要素にtokenフィールドを設定でき、設定したトークンは要素が選択されるとDisplay.ElementSelectedリクエストで送信されます。このようなイベントの例を次に示します。

 "request": {
    "type": "Display.ElementSelected",
    "requestId": "amzn1.echo-api.request.7zzzzzzzzz",
    "timestamp": "2018-06-06T20:05:04Z",
    "locale": "ja-JP",
    "token": "getTopicName-Cookie-Contest"
  }

アクションやリスト項目を選択するためのビルトインインテントは存在しません。ただし、この用途のインテントを作成し、インテントスキーマに追加することは可能です。このようなインテントは、スキルが応答でDisplay.ElementSelectedイベントを受信したときにアクティブ化する必要があります。

こうしたインテントを設計することで、Listテンプレートの使用時に画面に表示される項目を、ユーザーが項目の名前または番号を言うことで選択できるようになります。名前と序数のどちらで選択できるようにするかは、サービス（AWS LambdaまたはWebサービス）で指定します。

スキルの開発時には、リストの項目およびアクションをユーザーが音声で選択できるようにするインテントを作成し、スキルへ転送する必要があります。スキルサービスでは、「選択」や「開く」、「表示」、「1番」、「2番」、「1」、「2」などのインテントを定義する必要があります。

リスト項目がタッチで選択されたときに適切に応答できるよう、各リスト項目はトークンを使用して追跡します。

ユーザーのスキル内の移動に合わせて、スキルコンテンツの配信に使用するBodyテンプレートおよびListテンプレートを変えることをお勧めします。たとえばレシピスキルでは、検索画面からレシピの選択、成分の表示、レシピの用意へと進みますが、それぞれで異なる画面表示を行う必要があります。開発では、このような流れを綿密に計画してください。

テンプレートが指定された画面表示は、セッションが終了され新しいテンプレートが送信されるまでスキルの画面に表示され続けます。カードを含む応答が送信された場合も、画面にはテンプレートが表示されたままになります。このため、別のテンプレートを含むスキル応答で表示を意図的に変更しない限り、スキルは同じ画面のままさまざまなやり取りを行うことになります。

画面表示でのテンプレートとカードの優先順位

画面付きのAlexa搭載デバイスでは、表示オプションに合わせて応答が解析されます。表示オプションが複数指定されている場合、表示の優先順位は次のようになります。

Display.RenderTemplateディレクティブ。別のテンプレートが送信されるかスキルが終了されるまで、最後に表示されたテンプレートが画面に残ります。このため、別のテンプレートを明示的に送信しない限り、複数のやり取りで同じテンプレートが画面に表示され続けることになります。
カード。画面にテンプレートが送信されておらず、カードが送信された場合、画面にはカードが表示されます。カードはBodyTemplate1により、画面付きのAlexa搭載デバイスに表示されます。
スキル応答でテンプレートもカードも指定されておらず、その時点で画面になにも表示されていない場合には、デフォルトのテンプレート（BodyTemplate1）が自動で作成され表示されます。

サポートする表示バージョンの指定

互換性の確保のため、デバイスのリクエストでは、現在のデバイスでサポートされるマークアップとテンプレートのバージョンが送信されます。現在サポートされているバージョンは「1」のみですが、以下のアトリビュートを応答で指定することで後方互換性を確保できます。

{
  "display": {
    "templateVersion": "1",
    "markupVersion": "1"
  }
}

アトリビュート	説明
`markupVersion`	マークアップのバージョンです。
`templateVersion`	リクエスト元のデバイスでサポートされるテンプレートのバージョンです。
`token`	画面に現在表示されているコンテンツのトークンです。

画面の有無に応じたデバイスのGUI応答の形式

以下に示す応答はカードと音声応答のみに対応した簡単なものであり、画面表示を特にサポートしない場合はこれで十分です。画面付きのAlexa搭載デバイスで表示する場合、カードはBodyTemplate1で表示されます。

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoroscopePeriods": {
      "daily": true,
      "weekly": false,
      "monthly": false
    }
  },
  "response": {
    "card": {
      "type": "Simple",
      "title": "ホロスコープ",
      "content": "今日はいい一日でしょう。"
    }
  },
  "reprompt": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "他に何かありますか？"
    }
  }
}

次の例でも同じカードと音声応答に対応していますが、Displayテンプレートを使用して画面表示もサポートしています。この例では、BodyTemplate1をDisplayテンプレートとして使用しています。この例の画面上のテキストには、太字で強調されたフレーズが表示されます。

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoroscopePeriods": {
      "daily": true,
      "weekly": false,
      "monthly": false
    }
  },
  "response": {
    "card": null,
    "outputSpeech": {
      "type": "PlainText",
      "text": "今日はいい一日でしょう。"
    },
    "reprompt": {
      "outputSpeech": {
        "type": "PlainText",
        "text": "他に何かありますか？"
      }
    },
    "directives": [
      {
        "type": "Display.RenderTemplate",
        "template": {
          "type": "BodyTemplate1",
          "token": "horoscope",
          "title": "これはホロスコープです",
          "image": {
            "contentDescription": "みずがめ座",
            "sources": [
              {
                "url": "https://example.com/resources/card-images/aquarius-symbol.png"
              }
            ]
          },
          "textContent": {
            "primaryText": {
              "type": "RichText",
              "text": "今日は<b>いい一日</b>でしょう。"
            }
          }
        }
      }
    ],
    "shouldEndSession": false
  }
}

応答の検証ルール

画面付きのAlexa搭載デバイスを含むAlexaを使用するデバイスでは、以下の検証ルールを守ってください。

応答で指定できるDisplay.RenderTemplateディレクティブは1つまでです。
同じ応答内で、長時間の音声を指定したAudioPlayer.PlayディレクティブとVideoApp.Launchディレクティブを併用しないでください。
必須フィールドはすべて指定する必要があります。
不明なプロパティを指定することはできません。

応答が無効な場合、画面付きのAlexa搭載デバイスにはエラーカードが表示され、スキルにはエラーが送信されます。

shouldEndSessionアトリビュートおよびセッションタイムアウトの使用

shouldEndSessionが指定されていないかこの値にnullが設定されており、Display.RenderTemplate、Alexa.Presentation.APL.RenderDocument、またはAlexa.Presentation.APL.ExecuteCommandsディレクティブがアクティブな場合、セッションは開かれたままになり、画面付きデバイスは音声応答を行いません。ユーザーがウェイクワードとコマンドを言っても、発話はスキルのコンテキストで認識されます。

shouldEndSessionの動作を明確に制御するため、セッションを終了する場合はtrue、セッションを継続する場合はfalseにこのアトリビュートを設定してください。

shouldEndSessionがfalseに設定され、再プロンプトが指定されていない場合、30秒間にわたりアクティビティが行われないとセッションは終了されます。

再プロンプトが指定されている場合、マイクがオンになり青い輪が表示されて再プロンプトが行われ、8秒後にタイムアウトになります。また、その後さらに8秒間ユーザーの返事が受け付けられます。Alexaに返事が返されなかった場合、再プロンプトが表示され、再び8秒間ユーザーの返事が受け付けられます。引き続き返事がない場合、shouldEndSessionがfalseに設定されていると、表示がタイムアウトになるまでセッションは開かれたままになります。

画面付きのAlexa搭載デバイス用のスキル開発のベストプラクティス

画面付きのAlexa搭載デバイス向けスキルデザインのベストプラクティスを参照してください。

Alexaシミュレーターを使用したスキルのテスト

画面付きデバイスを所有していなくても、開発者コンソールのテストページでAlexaシミュレーターを使用して、Echo ShowまたはEcho Spotで表示する際のテンプレートの見た目をテストできます。スキルシミュレーションでFire TV Cubeはサポートされていません。

各デバイスでのスキルの表示形式を確認するための表示オプションをすべて選択してください。

Displayテンプレートのリファレンスで述べたように、デバイスが異なれば同じテンプレートでも表示が異なります。たとえば、一部のテンプレートでは、Fire TV CubeとEcho Showで前景に表示される画像が、Echo Spotでは背景画像として表示されます。したがって、ユーザーエクスペリエンスのため、テストはできる限り詳細に行ってください。

Alexaシミュレーターには次の制限があります。

現時点でサポートされているのはカスタムスキルのみです。
この表示は実際の画面での表示内容に近いものですが、ピクセルサイズは正確ではありません。
シミュレーターではスキルは動作せず、項目をクリックで選択することもできません。セッションは維持されません。
Alexaシミュレーターを複数のブラウザタブで使用することはできません。

関連トピック：スキルのテスト

サービスインターフェースのリファレンス（JSON）

リクエストの形式と標準のリクエストタイプ：

インターフェース：

Displayインターフェースのリファレンス

画面表示に対応したスキル用のDisplayテンプレート

テンプレートインターフェース（JSON）とデザイン

Display.RenderTemplateディレクティブの形式

応答でのDisplay.RenderTemplateとその他のディレクティブ

例： 応答にBodyTemplate2を含める場合のディレクティブ

Displayテンプレートのリファレンス

DisplayテンプレートのGUI仕様

Displayテンプレートごとの使用可能な画像サイズと書式

画面付きのAlexa搭載デバイス用の各テンプレートの画像サイズを表示する

imageオブジェクトの仕様

テンプレートの戻るボタン

例： Displayテンプレートで戻るボタンを非表示にする

例： Displayテンプレートで戻るボタンを表示する

応答にHintディレクティブを含める

textContentオブジェクトの仕様

例： PlainTextインスタンス

例： RichTextインスタンス

Displayテンプレートの最大文字数

画面付きのAlexa搭載デバイスのフォントサイズマッピング

画面付きのAlexa搭載デバイスの表示フォントサイズ

Displayテンプレートのテキストでサポートされているマークアップ

XML特殊文字の処理

リッチテキストを使用したテキストのアラインメント

例： 応答でBodyTemplate3を使用して画面表示を作成する

例： 応答でListTemplate1を使用して画面表示を作成する

例： 応答でListTemplate2を使用して画面表示を作成する

音声およびタッチによる選択イベントの処理

スキルからのナビゲーション

画面表示でのテンプレートとカードの優先順位

サポートする表示バージョンの指定

画面の有無に応じたデバイスのGUI応答の形式

応答の検証ルール

shouldEndSessionアトリビュートおよびセッションタイムアウトの使用

画面付きのAlexa搭載デバイス用のスキル開発のベストプラクティス

Alexaシミュレーターを使用したスキルのテスト

サービスインターフェースのリファレンス（JSON）

応答での`Display.RenderTemplate`とその他のディレクティブ

例：応答に`BodyTemplate2`を含める場合のディレクティブ

例：応答で`BodyTemplate3`を使用して画面表示を作成する

例：応答で`ListTemplate1`を使用して画面表示を作成する

例：応答で`ListTemplate2`を使用して画面表示を作成する