Displayインターフェースのリファレンス
APLについて詳しくは、Alexa Presentation Language(APL)の概要を参照してください。
Alexa Design System for APLにはDisplayテンプレートに似た一連のテンプレートが含まれており、スキルを移行できます。使用可能なテンプレートの詳細については、Displayテンプレートからレスポンシブ対応テンプレートに移行するを参照してください。
このリファレンスでは、スキルサービスコードのDisplayテンプレートを使用して、スキルの外観と操作感を想定どおりに設定する方法について説明します。ただし、ユーザーの多くは画面がサポートされていないAlexa搭載デバイスを使用するため、スキルは必ず音声での使用を一番に考えてデザインしてください。
関連トピック:
-
画面をサポートするAlexaスキルの作成に関するクイックスタートガイドについては、画面付きのAlexa搭載デバイスでAlexaスキルをビルドする方法を参照してください。
-
デザインについてはDisplayテンプレートのベストプラクティスを参照してください。
-
デバイスの表示と動作の仕様についてはDisplayテンプレートを使用して画面にコンテンツを表示するを参照してください。
-
Displayテンプレートの仕様については、Displayテンプレートのリファレンスを参照してください。
画面表示に対応したスキル用の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搭載デバイスでスキルが正常に動作し適切に表示されるよう、以下の仕様を守ってください。
デバイスの仕様についてはDisplayテンプレートを使用して画面にコンテンツを表示するを参照してください。
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 高さ)。
|
高さは404ピクセルにしてください。目的のアスペクト比に応じて、幅は284~504ピクセルの間にしてください。サポートされるアスペクト比は次のとおりです(幅 x 高さ)。
|
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(メインの画像) |
1712 x 788(メインの画像) |
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>を試してください"*
したがって、
*"アレクサ、上映されている映画を教えてを試してください"*
簡潔にするため、次の例には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テンプレートのテキストでサポートされているマークアップを参照してください。
例: 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>はアブラムシにしてください。 | てんとう虫のエサはアブラムシにしてください。 |
XML特殊文字の処理
テンプレートとカードでは、特殊文字の表示方法が異なります。Displayテンプレートのコンテンツで次の文字を使用する場合は、以下のようにエスケープしてください。
- アンド記号(&)は
&
にします。 - 二重引用符(")は
"
または\"
にします。 - 単一引用符(')は
'
または\'
にします。 - 小なり記号(<)は
<
にします。 - 大なり記号(>)は
>
にします。 - スラッシュ(\)は
\\
にします。 - 改行なしスペースはXML形式で
 
のようにエスケープします(HTML形式は使用しないでください)。
例: 応答で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テンプレートを参照してください。トークンには自由に名前を付けることができます。
スキルでは任意の選択可能要素に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秒間にわたりアクティビティが行われないとセッションは終了されます。
再プロンプトが指定されている場合、マイクがオンになり青い輪が表示されて再プロンプトが行われ、数秒後にタイムアウトになります。また、その後さらに数秒間ユーザーの返事が受け付けられます。Alexaに返事が返されなかった場合、再プロンプトが表示され、再び数秒間ユーザーの返事が受け付けられます。引き続き返事がない場合、shouldEndSession
がfalseに設定されていると、表示がタイムアウトになるまでセッションは開かれたままになります。
画面付きのAlexa搭載デバイス用のスキル開発のベストプラクティス
Displayテンプレートのベストプラクティスを参照してください。
Alexaシミュレーターを使用したスキルのテスト
画面付きデバイスを所有していなくても、開発者コンソールのテストページでAlexaシミュレーターを使用して、Echo ShowまたはEcho Spotで表示する際のテンプレートの見た目をテストできます。スキルシミュレーションでFire TV Cubeはサポートされていません。
各デバイスでのスキルの表示形式を確認するための表示オプションをすべて選択してください。
Displayテンプレートのリファレンスで述べたように、デバイスが異なれば同じテンプレートでも表示が異なります。たとえば、一部のテンプレートでは、Fire TV CubeとEcho Showで前景に表示される画像が、Echo Spotでは背景画像として表示されます。したがって、ユーザーエクスペリエンスのため、テストはできる限り詳細に行ってください。
Alexaシミュレーターには次の制限があります。
-
現時点でサポートされているのはカスタムスキルのみです。
-
この表示は実際の画面での表示内容に近いものですが、ピクセルサイズは正確ではありません。
-
シミュレーターではスキルは動作せず、項目をクリックで選択することもできません。セッションは維持されません。
-
Alexaシミュレーターを複数のブラウザタブで使用することはできません。

関連トピック: スキルのテスト
サービスインターフェースのリファレンス(JSON)
リクエストの形式と標準のリクエストタイプ:
インターフェース: