スキルの応答にカードを追加する



スキルの応答にカードを追加する

ユーザーとAlexaデバイスとの対話には、Amazon Alexaアプリ(Fire OS(日本未対応)、Android、iOS、デスクトップウェブブラウザで利用可能なコンパニオンアプリ)に表示するホームカードを追加することができます。ホームカードは、音声での対話について説明したり、音声の対話を補強したりする視覚的なカードです。カスタムスキルでは、応答にこのカードを含めることができます。

画面付きEchoデバイス用に開発されたスキルでは、表示テンプレートもサポートされています。表示テンプレートとは、カードに類似したもので、デバイスに直接表示されます。Displayインターフェースのリファレンスを参照してください。Echo Showでは、Alexaアプリでの表示用にデザインされたカードも表示されます。そのため、ユーザーのデバイスがEcho Showの場合、Alexaアプリでの表示用にデザインされたカードが設定されているスキルでは、Echo Showでもこれらのカードが表示されます。

カードの概要

たとえば、潮汐情報を調べるスキルでは、ユーザーが質問した潮汐情報が表示されるホームカードを追加することができます。ユーザーは、再度音声リクエストをしなくても、スキルからの情報を再度確認することができます。

潮汐情報のホームカードの例
潮汐情報のホームカードの例

ホームカードは対話を強化するのに大変有効です。たとえば、音声の応答は、簡潔に、そして「耳で聞き取ることを前提に記述する」必要があります。ホームカードでは、音声で応答するには長すぎたり、聞いただけでは分かりにくかったりする詳細情報や便利な情報を表示させることができます。

Alexa Skills Kitでは、さまざまなタイプのホームカードが提供されています。

  • Simpleカード:プレーンテキストを表示します。開発者は、カードのタイトルと本文のテキストを指定します。
  • Standardカード:プレーンテキストだけでなく、画像も表示できます。開発者は、タイトルと本文のテキストと、表示する画像のURLを指定します。
  • LinkAccountカード:アカウントリンクでのみ使用する特殊なカードタイプです。このカードを使うと、ユーザーはアカウントリンクプロセスを開始できます。

カードをAlexaアプリに送信するには、サービスがAlexaに返す応答にホームカードを含めます。通常、スキルがユーザーのリクエストした情報を応答で返す際、ホームカードのみを返します。ユーザーに詳しい情報をたずねる質問などの、その他の応答には通常ホームカードを含めません。

ホームカードを確認するには、Alexaアプリを開いてホームをクリックします。

効果的なカードを設計する際の推奨事項については、スキルカードデザインのベストプラクティスを参照してください。

テキストを表示する基本的なホームカードを作成する

最もシンプルなホームカードは、プレーンテキストで構成されたものです。タイトルと本文を指定すると、以下のようにAlexaアプリに表示されます。

Simpleカードの例
Simpleカードの例

カードに含めることのできる文字数(タイトルと本文の合計)は、8,000文字以内です。

Simpleカードを作成するには、JSON応答にcardプロパティを追加します。

  • typeSimpleに設定します。
  • titleプロパティとcontentプロパティに、表示するテキストを設定します。改行を挿入するには、content内で「\r\n」または「\n」を使用します。
{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"ユーザーに応答するテキスト"},
    "card": {
      "type": "Simple",
      "title": "カードのタイトルの例",
      "content": "カードコンテンツの例。このカードはプレーンテキストのコンテンツです。\nコンテンツは読みやすいように改行を使用して調整します。"
    }
  }
}

Javaライブラリを使用する場合

  • SimpleCardオブジェクトを作成します。
  • オブジェクトのsetTitle()メソッドとsetContent()メソッドを呼び出して、タイトルと本文を設定します。
  • カードオブジェクトをSpeechletResponse.newTellResponse()SpeechletResponse.newAskResponse()のいずれかに渡して、カードを含むSpeechletResponseを取得します。

テキストと画像を表示するホームカードを作成する

ホームカードでは、1枚のみですが画像を表示することができます。この場合、タイトルと本文のほかに、表示する画像のURLを2つ(小さい画像用と大きい画像用)を指定します。

画像を使ったStandardカードの例
画像を使ったStandardカードの例

カードに含めることのできる文字数(titlecontent、2つのURLの合計)は、8,000文字以内です。画像のURLは、それぞれ2000文字以内でなければなりません。

画像付きのカードを作成するには、JSON応答にcardプロパティを追加します。

  • typeStandardに設定します。
  • titleプロパティとtextプロパティに、表示するテキストを設定します。
    • このタイプのカードでは、Simpleのようにcontentプロパティを使うのではなく、textプロパティを使用することに注意してください。
    • 改行を挿入するには、text内で「\r\n」または「\n」を使用します。
  • smallImageUrllargeImageUrlを指定したimageオブジェクトを追加します。
  • smallImageUrllargeImageUrlに、表示する画像の小さいバージョンと大きいバージョンのURLを設定します。画像の形式サイズホスティング要件の詳細については、以下を参照してください。
{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"タクシーが向かっています。"},
    "card": {
      "type": "Standard",
      "title": "車の手配",
      "text": "予約車は中央通り123番地に向かっています。\n見積料金は2500円です",
      "image": {
        "smallImageUrl": "https://carfu.com/resources/card-images/race-car-small.png",
        "largeImageUrl": "https://carfu.com/resources/card-images/race-car-large.png"
      }
    }
  }
}

Javaライブラリを使用する場合

  • StandardCardオブジェクトを作成します。
  • オブジェクトのsetTitle()メソッドとsetText()メソッドを呼び出して、タイトルと本文を設定します。
  • Imageオブジェクトを作成し、URLをオブジェクトのsetSmallImageUrl()メソッドとsetLargeImageUrl()メソッドに割り当てます。
  • setImage()メソッドを使用して、ImageオブジェクトをStandardCardオブジェクトに渡します。
  • StandardCardオブジェクトをSpeechletResponse.newTellResponse()SpeechletResponse.newAskResponse()のいずれかに渡して、カードを含むSpeechletResponseを取得します。

画像の形式とサイズ

以下の形式の画像が提供できます。

  • JPEG
  • PNG

画像は2MB以下である必要があります。

画像を含める際、解像度の低い画像と高い画像の2つのURLを指定します。異なるサイズの画面にホームカードを表示する際、異なるサイズの画像が使い分けられます。

プロパティ 説明 推奨サイズ(ピクセル)
smallImageUrl 小さい画面に表示されます 横720 x 縦480
largeImageUrl 大きい画面に表示されます 横1200 x 縦800

画面のサイズが変わってもホームカードを適切に表示するには、smallImageUrllargeImageUrlの両方を指定してください。URLを1つしか指定しない場合、表示される画面のサイズにかかわらずその画像が使用されます。それによってホームカードが見えづらくなる場合があります。たとえば、smallImageUrlのみを指定した場合では、大きな画面に表示するときに画像が拡大されるため、画質が低下する可能性があります。

推奨サイズに近い画像を使用すれば、アプリの画像の画質が損なわれることはありません。小さい画像は拡大されることで、画質が下がることがあります。逆に、大きい画像は読み込みに時間がかかるので、必要以上に大きなサイズを指定するとアプリでのカードの表示パフォーマンスが下がる可能性があります。

たとえば、以下は、非常に小さい画像を拡大している例です。

拡大せざるを得ない小さい画像を使ったStandardカードの例
拡大せざるを得ない小さい画像を使ったStandardカードの例

ホームカードは、必ずAlexaアプリで(できれば、さまざまな画面サイズの複数のデバイスを使用して)テストをして、適切に表示されることを確認してください。

画像をホストする

Alexaアプリは、実行時に、指定したURLから画像を読み込みます。指定する画像ファイルは、以下の要件を満たすHTTPSエンドポイントでホストされる必要があります。

  • エンドポイントでは、Amazon認定の認証局が署名したSSL証明書を提供します。これは、多くのコンテンツホスティングサービスで提供されています。たとえば、Amazon Simple Storage Service(Amazon S3)アマゾンウェブサービスが提供)などのサービスでファイルをホストできます。
  • エンドポイントで、画像のCross-Origin Resource Sharing(CORS)が許可する必要があります。これにより、Amazon Alexaアプリが画像をダウンロードして、アプリで表示する前に処理や検証ができるようになります。

CORSを有効にするには、画像のサーバーで、応答にAccess-Control-Allow-Originヘッダーを設定する必要があります。リソースをAlexaアプリのみに限定する場合は、取得元としてhttp://ask-ifr-download.s3.amazonaws.comとhttps://ask-ifr-download.s3.amazonaws.comのみを許可してください。

この設定方法は、画像のホストによって異なります。たとえば、Amazon S3バケットで画像をホストする場合は、以下のCORSコンフィギュレーションを使用してバケットを設定します。

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>http://ask-ifr-download.s3.amazonaws.com</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
    <CORSRule>
        <AllowedOrigin>https://ask-ifr-download.s3.amazonaws.com</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
</CORSConfiguration>

S3およびCORSの詳細については、Enabling Cross-Origin Resource Sharingを有効にするを参照してください。

Standardカードに画像を含める際によくある問題

このセクションでは、Standardカードに画像を含める際に発生する可能性がある、よくある問題について説明します。

画像がグレーのボックスで表示される: いくつかの理由が考えられます。

  • 画像がない: 指定した画像のURLが実際の画像を参照していない、公開されていない画像を参照している、URLの有効期限が切れている、などの原因で発生します。

  • 画像のホストがCORS対応ではない: 画像をホストするサーバーがCORS対応ではありません。
  • 画像の形式が正しくない: 画像のURLで参照している画像が、サポート対象外の形式(PNGJPEG以外)になっています。
  • 画像が大きすぎる:指定した画像ファイルのサイズが2 MBを超えています。
画像が表示されないStandardカードの例
画像が表示されないStandardカードの例

画像もプレースホルダーもない状態でカードが表示される: 応答に実際の画像オブジェクトが含まれていない場合に発生します。カードは表示されますが、画像は表示されません。

例として、以下のJSONを見てみましょう。Standardカードとして指定されていますが、imageがありません。

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"タクシーが向かっています。"},
    "card": {
      "type": "Standard",
      "title": "車の手配",
      "text": "予約車は中央通り123番地に向かっています。\n見積料金は2500円です"
    }
  }
}

このコードでは次のようなカードが作成されます。

画像オブジェクトが指定されていないStandardカードの例
画像オブジェクトが指定されていないStandardカードの例

アカウントリンクに使用するカードを定義する

Alexaスキルの中には、エンドユーザーのIDと別のシステムのユーザーアカウントを結び付ける機能が必要なものもあります。この機能を、「アカウントリンク」と呼びます。Alexaユーザーとシステムのユーザーアカウント間でリンクを作成することを目的としているためです。

ユーザーがこのリンクを必要とするインテントを呼び出したときにリンクが確立されていない場合、スキルは通常、Alexaアプリを使用してアカウントをリンクするよう指示する応答をユーザーに返します。アプリに表示されるカードは、ユーザーにアカウントをリンクさせるための特殊なタイプのカードです。

LinkAccountカードの例
LinkAccountカードの例

カードのほとんどの内容は、スキルのコンフィギュレーションから自動的に生成されます。

  • カードのタイトルは、スキル名から自動的に設定されます(上の例では「タクシー予約」)。
  • 「スキルをもっと活用するには...(To get the most...)」という本文は、アカウントリンクを使用するすべてのスキルに標準のものです。
  • 「アカウントをリンク」というリンクは、スキルのアカウントリンクの設定時に開発者ポータルで設定したAuthorization URL認証画面のURIに移動します。

アカウントリンクのカードを作成するには、JSON応答にcardプロパティを追加します。タイプをLinkAccountに設定し、それ以外のプロパティは渡しません。

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Alexaアプリに移動して、アカウントをリンクしてください。"},
    "card": {
      "type": "LinkAccount"
    }
  }
}

Javaライブラリを使用する場合

  • LinkAccountCardオブジェクトを作成します。
  • カードオブジェクトをSpeechletResponse.newTellResponseに渡して、カードを含むSpeechletResponseを取得します。この場合、スキルを使用する前にアカウントをリンクする必要があることをユーザーに伝えた後にセッションをオープンにしておいても意味はないため、SpeechletResponse.newAskResponseを使用しないでください。

アカウントリンクの実装の詳細については、Alexaユーザーとシステムユーザーを関連付けるを参照してください。