あなたのAlexaダッシュボード 設定

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

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

カードの概要

たとえば、潮の満ち引き情報を検索するスキルは、ユーザーが聞いた潮の満ち引き情報を含むホームカードを追加することができます。ユーザーは、再度音声リクエストをしなくても、スキルからの情報を再度確認することができます。

Tide Poolerのホームカードの例
Tide Poolerのホームカードの例

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

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

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

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

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

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

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

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

シンプルなカードの例
シンプルなカードの例

カードに含めることのできる文字数(タイトルコンテンツの合計)は、8000文字以内です。

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

  • typeSimpleに設定します。
  • テキストに表示するtitleプロパティとcontentプロパティを設定します。改行を挿入するには、content内で「\r\n」または「\n」を使用します。
{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Text to speak back to the user."},
    "card": {
      "type": "Simple",
      "title": "Example of the Card Title",
      "content": "Example of card content. This card has just plain text content.\nThe content is formatted with line breaks to improve readability."
    }
  }
}

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

  • SimpleCardオブジェクトを作成します。
  • オブジェクトのsetTitle()メソッドとsetContent()メソッドを呼び出して、タイトルとコンテンツを設定します。
  • カードオブジェクトをSpeechletResponse.newTellResponse()またはSpeechletResponse.newAskResponse()に渡して、カードを含むSpeechletResponseを取得します。

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

ホームカードに含めることができる画像は1つのみです。この場合、タイトルテキスト、および表示する画像の2つのURL(小さいバージョンと大きいバージョン)を指定します。

画像を使った標準的なカードの例
画像を使ったスタンダードカードの例

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

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

  • typeStandardに設定します。
  • テキストに表示するtitleプロパティとtextプロパティを設定します。
    • このタイプのカードは、Simpleの場合のcontentプロパティではなくtextプロパティを使用することに注意してください。
    • 改行を挿入するには、text内で「\r\n」または「\n」を使用します。
  • smallImageUrlおよびlargeImageUrlを指定したimageオブジェクトを追加します。
  • 表示する画像の小さいバージョンと大きいバージョンのURLに、smallImageUrllargeImageUrlを設定します。画像の形式サイズホスティング要件の詳細については、以下を参照してください。
{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Your Car-Fu car is on the way!"},
    "card": {
      "type": "Standard",
      "title": "Ordering a Car",
      "text": "Your ride is on the way to 123 Main Street!\nEstimated cost for this ride: $25",
      "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

画像は2 MB以内にしてください。

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

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

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

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

たとえば、以下の例では、Alexaアプリが非常に小さい画面を拡大しています。

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

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

画像をホストする

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

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

CORSを有効化するには、画像のサーバーで、応答にAccess-Control-Allow-Originヘッダーを設定する必要があります。Alexaアプリのみにリソースを制限する場合は、取得元としてhttp://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>
</CORSConfiguration>

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

スタンダードカードに画像を含める際のよくある問題

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

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

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

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

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

たとえば、以下のJSONを参照してください。Standardカードとして指定されていますが、imageがありません。

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Your Car-Fu car is on the way!"},
    "card": {
      "type": "Standard",
      "title": "Ordering a Car",
      "text": "Your ride is on the way to 123 Main Street!\nEstimated cost for this ride: $25"
    }
  }
}

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

画像オブジェクトが指定されていないスタンダードカードの例
画像オブジェクトが指定されていない標準的なカードの例

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

一部のAlexaスキルでは、エンドユーザーのIDを別のシステムのユーザーに接続できるようにする必要があります。これを実現するための仕組みを、アカウントリンクと呼び、Alexaに設定されているユーザーと、スキルのシステム(開発者のシステム)のユーザーアカウントを結び付けることを実現します。

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

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

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

  • カードタイトルは、スキル名から自動的に設定されます(上の例では「Car-Fu」)。
  • テキスト「スキルをもっと活用するには...(To get the most...)」はアカウントリンクを使用するすべてのスキルに標準のものです。
  • リンク「アカウントをリンク(Link Account)」は、スキルのアカウントリンクの設定時に開発者ポータルで設定した「認証URL(Authorization URL)」になります。

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

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Please go to your Alexa app and link your account."},
    "card": {
      "type": "LinkAccount"
    }
  }
}

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

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

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