スキルのAPLインターフェース設定

スキルのAPLインターフェース設定

スキルでAlexa Presentation Languageを使用するには、Alexa.Presentation.APLインターフェースのサポートを追加します。

Alexa.Presentation.APLインターフェースに対応するようスキルを設定する

APLのディレクティブとリクエスト（RenderDocument、ExecuteCommands、UserEvent）を使用するには、スキルがAlexa.Presentation.APLインターフェースに対応している必要があります。このインターフェースを有効にすると、スキルに送信されたリクエストがAPLに対応するデバイスから送信されたかどうかを判断できます。

スキルを更新するには、開発者コンソールかASK CLIのいずれかを使用します。

開発者コンソールでAlexa.Presentation.APLを設定する

  1. 開発者コンソールを開き、設定するスキルの編集をクリックします。
  2. ビルド＞インターフェースページに移動します。
  3. Alexa Presentation Languageオプションを有効にします。
  4. インターフェースを保存、モデルをビルドの順にクリックして、対話モデルを再ビルドします。
  5. スキルコードで、APLディレクティブを返す前に、ユーザーのデバイスがAPLに対応しているかどうかを判断します。

ASK CLIまたはSMAPIを使用してAlexa.Presentation.APLを設定する

ASK CLIまたはSMAPIを使用して、スキルマニフェストのmanifest.apis.custom.interfaces配列を更新し、ALEXA_PRESENTATION_APLオブジェクトを含めます。このオブジェクトには、次に示すようにsupportedViewports配列も含まれています。

クリップボードにコピーされました。

{
  "type": "ALEXA_PRESENTATION_APL",
  "supportedViewports": [
    {
      "mode": "HUB",
      "shape": "ROUND",
      "minWidth": 100,
      "maxWidth": 599,
      "minHeight": 100,
      "maxHeight": 599
    },
    {
      "mode": "HUB",
      "shape": "RECTANGLE",
      "minHeight": 600,
      "maxHeight": 959,
      "minWidth": 960,
      "maxWidth": 1279
    },
    {
      "mode": "HUB",
      "shape": "RECTANGLE",
      "minHeight": 600,
      "maxHeight": 1279,
      "minWidth": 1280,
      "maxWidth": 1920
    },
    {
      "mode": "TV",
      "shape": "RECTANGLE",
      "minHeight": 540,
      "maxHeight": 540,
      "minWidth": 960,
      "maxWidth": 960
    }
  ]
}

サポートされているviewportsの詳細については、スキルがサポートするViewportプロファイルの選択を参照してください。

  1. 次のコマンドを実行して、スキルコンポーネントをダウンロードします。 
     ask api get-skill -s amzn1.ask.skill.<skillId>

    get-skillサブコマンドを参照してください。

  2. スキルマニフェスト（skill.jsonとしてダウンロード）を編集し、上記のALEXA_PRESENTATION_APLオブジェクトをmanifest.apis.custom.interfaces配列に追加します。

  3. 次のコマンドを実行して、変更したスキルマニフェストをデプロイします。 
     ask api update-skill -s amzn1.ask.skill.<skillId> -f skill.json

    update-skillサブコマンドを参照してください。

  4. 更新が正しくデプロイされたことを確認するために、手順1を繰り返してスキルマニフェストをダウンロードします。エディターでskill.jsonファイルを開き、インターフェースオブジェクトにALEXA_PRESENTATION_APLオブジェクトが含まれていることを確認します。

  5. スキルコードで、APLディレクティブを返す前に、ユーザーのデバイスがAPLに対応しているかどうかを判断します。

ASK CLIの使用について詳細は、クイックスタート：Alexa Skills Kitコマンドラインインターフェースを参照してください。

ユーザーのデバイスがAPLに対応していることを確認する

スキルコードがAPLディレクティブを送信する前に、ユーザーのデバイスが関連するAPLインターフェースに対応していることを確認してください。すべてのリクエストについて、含まれているcontext.System.device.supportedInterfacesオブジェクトをチェックします。確認するインターフェースは次の2つです。

  • Alexa.Presentation.APL：Echo ShowやFire TVなど、画面付きデバイスであることを示しています。Alexa.Presentation.APLディレクティブを返すことができます。ドキュメントでは、指定されたバージョン（最新バージョンは2023.2）でサポートされているすべてのAPL機能を、画像やその他のメディアを含めて使用できます。
  • Alexa.Presentation.APLT：Echo Dot with clockなど、キャラクターディスプレイ付きデバイスであることを示しています。Alexa.Presentation.APLTディレクティブを返すことができます。ドキュメントでは、デバイスに簡単なテキストコンテンツを表示するためのごく限られたAPL機能を使用できます。

以下にLaunchRequestの例を示します。一方はAlexa.Presentation.APLインターフェースのバージョン2023.2をサポートするデバイスの例、もう一方はAlexa.Presentation.APLTインターフェースのバージョン1.0をサポートするデバイスの例です。

クリップボードにコピーされました。

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "2023.2"
            }
          }
        }
      },
      "apiEndpoint": "https://api-amazonalexa.amazon.com",
      "apiAccessToken": ""
    },
    "Viewport": {
      "experiences": [
        {
          "canRotate": true,
          "canResize": true
        },
        {
          "canRotate": false,
          "canResize": false
        }
      ],
      "shape": "RECTANGLE",
      "pixelWidth": 1024,
      "pixelHeight": 600,
      "dpi": 160,
      "currentPixelWidth": 640,
      "currentPixelHeight": 500,
      "touch": [
        "SINGLE"
      ],
      "keyboard": [
        "DIRECTION"
      ],
      "video": {
        "codecs": [
          "H_264_42",
          "H_264_41"
        ]
      }
    }
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2019-06-27T15:52:19Z",
    "locale": "ja-JP",
    "shouldLinkResultBeReturned": false
  }
}

クリップボードにコピーされました。

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APLT": {
            "runtime": {
              "maxVersion": "1.0"
            }
          }
        }
      },
      "apiEndpoint": "https://api-amazonalexa.amazon.com",
      "apiAccessToken": ""
    },
    "Viewports": [
      {
        "id": "main",
        "type": "APLT",
        "supportedProfiles": [
          "FOUR_CHARACTER_CLOCK"
        ],
        "lineLength": 4,
        "lineCount": 1,
        "format": "SEVEN_SEGMENT",
        "interSegments": [
          {
            "x": 2,
            "y": 0,
            "characters": "':."
          }
        ]
      }
    ]
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2019-06-27T15:52:19Z",
    "locale": "ja-JP",
    "shouldLinkResultBeReturned": false
  }
}

簡潔な説明のために、リクエストプロパティの一部は省略されています。スキーマ全文については、リクエスト本文の構文を参照してください。

ASK SDKを使用する際にこのオブジェクトをチェックする方法を示すコードサンプルについては、ASK SDK v2でのAlexa Presentation Languageの使用を参照してください。

コードでAPLのディレクティブとリクエストを使用する

スキルコードで、Alexa.Presentation.APLとAlexa.Presentation.APLTのディレクティブおよびリクエストを使用します。

表示コンテンツをデバイスに送信するには、RenderDocumentディレクティブを使用します。

ドキュメント関連のコマンドをデバイスに送信するには、ExecuteCommandsディレクティブを使用します。

デバイスから送信されたユーザーのイベント（ボタンを押すなど）を処理するには、UserEventリクエストを使用します。UserEventは画面付きデバイスに使用できますが、キャラクターディスプレイ付きデバイスには使用できません。

全体的なスキルフローでAPLを使用する方法の概要については、APLとスキルフローを参照してください。

ASK SDKでAPLのディレクティブとリクエストを使用する方法を示すコードサンプルについては、ASK SDK v2でのAlexa Presentation Languageの使用を参照してください。

APLを使用したキャラクターディスプレイへのコンテンツの表示については、Alexa Presentation Languageとキャラクターディスプレイの概要を参照してください。

APLディレクティブをDisplayインターフェースと組み合わせないでください。

リソースのCross-Origin Resource Sharing（CORS）を設定する

HTTPSエンドポイントでホスティングされている外部リソース（画像など）をスキルが参照している場合、このエンドポイントが以下の要件を満たすことを確認してください。

  • エンドポイントで、Amazon認定の認証局が署名したSSL証明書を提供していること。これは、多くのコンテンツホスティングサービスで提供されています。たとえば、Amazon Simple Storage Service（Amazon S3）（Amazon Web Servicesが提供）などのサービスでファイルをホストできます。
  • エンドポイントで、画像のCross-Origin Resource Sharing（CORS）を許可していること。

CORSを有効にするには、リソースサーバーで、応答にAccess-Control-Allow-Originヘッダーを設定する必要があります。リソースをAlexaのみに制限するには、取得元として*.amazon.comのみをホワイトリストに登録します。

リソースがAmazon S3バケット内にある場合は、以下のCORS設定（JSONを参照）を使用してバケットを設定します。

[
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
]

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

このページは役に立ちましたか？

最終更新日: 2023 年 11 月 15 日