Alexa.Launcherインターフェース

Alexa.Launcherインターフェース（VSK Fire TV）

警告： Video Skills Kit（VSK）のサポートは終了しました。既存の統合に関して質問がある場合は、Amazonのテクニカルアカウントマネージャーにお問い合わせください。

ソフトウェアのバージョンをドロップダウンナビゲーションから選択してください。

Alexa.Launcherバージョン3.1では、カスタムUIショートカットが導入されています。エンドポイントでサポートされる音声ショートカットを定義することで、ユーザーはUI間を移動できるようになります。カスタムUIショートカットは、検出レスポンスで指定できます。

Launcherインターフェースでサポートされているロケールについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。

注： Alexa.Launcherインターフェースはクラウド側の統合とアプリのみの統合のどちらでも使用できますが、アプリのみの統合で使用することをお勧めします。

ディレクティブ

LaunchTargetディレクティブ

カスタムショートカットに移動するリクエストです。ユーザーがリクエストしたショートカットは、パートナーから提供されたターゲットのリストと照合されます。一致するものがある場合は、名前、識別子、ソースIDがAlexaからパートナーに返されます。

ユーザー：アレクサ、<カスタムショートカット>に移動して

LaunchTargetディレクティブの例

{
    "directive": {
        "header": {
            "correlationToken": "<opaque相関トークン>",
            "messageId": "<一意の識別子（バージョン4のUUIDを推奨）>",
            "name": "LaunchTarget",
            "namespace": "Alexa.Launcher",
            "payloadVersion": "3.1"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            },
            "endpointId": "<エンドポイントID>",
            "cookie": {}
        },
        "payload": {
            "name": "<カスタムショートカット>",
            "identifier": "partner.custom.shortcut.identifier",
            "sourceId": "DISCOVERY"
            }
        }
    }
}

LaunchTargetディレクティブのパラメーター

プロパティ	説明	型	必須
`name`	識別子に関連付けられた名前です。	文字列	○
`identifier`	カスタムショートカットの識別子です。	文字列	○
`sourceId`	カタログを一意に識別します。定義済みカタログの場合、有効な値は `ALEXA_VIDEO_SHORTCUT_STORE`、`ALEXA_VIDEO_APP_STORE`です。カスタムショートカットの場合、有効な値は `DISCOVERY`です。	文字列	○
`experience.mode`	リクエストされた結果を表示するモードを示します。`VOICE_OPTIMIZED`は、音声中心の結果（短い検索結果リストなど）を示します。モードの値をサポートしない場合は、`DEFAULT`を使用します。有効な値は `DEFAULT`、`VOICE_OPTIMIZED`です。	文字列	×

LaunchTargetレスポンスの例

LaunchTargetディレクティブが正常に処理された場合は、Alexa.Responseイベントで応答します。contextオブジェクトにtargetプロパティの値を含めます。

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

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "<一意の識別子（バージョン4のUUIDを推奨）>",
            "correlationToken": "<リクエストに一致するopaque相関トークン>",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "<エンドポイントID>"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.Launcher",
                "name": "target",
                "value": {
                    "name": "<カスタムショートカット>",
                    "identifier": "partner.custom.shortcut.identifier"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

ペイロードターゲットを送信してアプリやショートカットを起動する方法については、Discoveryインターフェースのレスポンスの例を参照してください。

ショートカットの名前の要件

キャリアフレーズはAlexaが処理するため、ショートカットには含めないでください。たとえば、「go to settings」ではなく「settings」を使用します。ショートカットの名前から除外するキャリアフレーズの一覧は以下のとおりです。
- navigate to
- go
- go to
- select
- pick
- choose
- click
- click on
- hit
- launch
- take me/us to
- open
- show
- show me/us
- display
ショートカットの名前を定義する際は、すべて小文字を使用してください。
ショートカットの名前には英数字を使用する必要があります。
「ホーム」は予約済みの発話であるため、デフォルトで常にFire TVのホーム画面になります。
ショートカットの名前のバリエーションはカバーされません。「go to movie」と「go to movies」をどちらも機能させるには、同じ識別子を指すショートカットの名前として「movie」と「movies」の両方を指定する必要があります。

注：ショートカットの数は50個に制限されています。

イベントとプロパティ

レポート可能なプロパティ

プロパティ名	型	説明
target	Target	起動されるアプリまたはショートカットです。

構成オブジェクト

Alexa.Launcherには、通常の検出レスポンスフィールドに加えて、次のフィールドを含む構成オブジェクトを含めます。

プロパティ	説明	型	必須
`catalogs`	インポートするカタログを識別します。デバイスで構成されている言語をサポートするカタログのみを含めます。定義済みカタログをエンドポイントでサポートしない場合は、空の配列を格納します。最大で 5つのカタログを含めることができます。有効な値は `ALEXA_VIDEO_SHORTCUT_STORE`、`ALEXA_VIDEO_APP_STORE`です。	`Catalog`オブジェクトの配列	○
`targets`	エンドポイントでサポートするカスタムUIショートカットを含めます。カスタムショートカットと定義済みショートカットカタログの両方がスキルで定義されている場合、Alexaはまずtargetsフィールドで一致するものを探し、次に定義済みショートカットカタログを検索します。カスタムショートカットをエンドポイントでサポートしない場合は、空の配列を格納します。最大で 50個のショートカットを含めることができます。	`Target`オブジェクトの配列	○

Catalogオブジェクト

Catalogオブジェクトは、エンドポイントでサポートする定義済みカタログを定義します。

重要： バージョン3.1では、カタログ統合をサポートするためのCatalogオブジェクトが追加されています。現時点では、カスタムカタログはサポートされていません。

次の表に、Catalogオブジェクトの定義を示します。

プロパティ	説明	型	必須
`sourceId`	カタログを一意に識別します。定義済みアプリカタログをエンドポイントでサポートする場合は、`ALEXA_VIDEO_APP_STORE`に設定します。定義済みUIショートカットカタログをエンドポイントでサポートする場合は、`ALEXA_VIDEO_SHORTCUT_STORE`に設定します。定義済みカタログのアプリターゲットとショートカットターゲットについては、起動ターゲットのリファレンスを参照してください。	文字列	○
`targets`	エンドポイントでサポートするカスタムUIショートカットを含めます。カスタムショートカットと定義済みショートカットカタログの両方がスキルで定義されている場合、Alexaはまずtargetsフィールドで一致するものを探し、次に定義済みショートカットカタログを検索します。カスタムショートカットをエンドポイントでサポートしない場合は、空の配列を格納します。最大で 50個のショートカットを含めることができます。	`Target`オブジェクトの配列	○

Targetオブジェクト

Targetオブジェクトには、定義したカスタムUIショートカットを表す名前と識別子が格納されます。

以下に、カスタムUIショートカットターゲットの例を示します。

{
  "name": "target",
  "value": {
      "name": "Watchlist",
      "identifier": "custom.shortcut.id.0000"
    }
}

次の表に、Targetオブジェクトの定義を示します。

プロパティ	説明	型	必須
`name`	カスタムショートカットの名前です。カスタムショートカットの名前には、英数字のみを使用する必要があります。	文字列	○
`identifier`	ショートカットに関連付けられたカスタム識別子です。	文字列	○

Response

LaunchTargetディレクティブが正常に処理された場合は、Responseを送信します。

レスポンスの例

以下に、Responseメッセージの例を示します。メッセージのコンテキストでtargetプロパティの値をレポートします。

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

{
    "context": {
        "properties": [
            {
                "name": "target",
                "namespace": "Alexa.Launcher",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": {
                     "name": "<カスタムショートカット>",
                     "identifier": "partner.custom.shortcut.identifier"
                }
            }
        ]
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

ErrorResponse

何らかの理由でユーザーのリクエストを完了できない場合は、エラーレスポンスを返す必要があります。詳細については、エラー処理を参照してください。

Alexa.Launcherバージョン3.0を使用すると、サードパーティのデバイス上でターゲットを起動することができます。これは、アプリやショートカット（設定など）を起動する場合に役立ちます。

Alexa.Launcherインターフェースは、以下のターゲットを起動するためのディレクティブを提供します。

Prime Videoなどのアプリターゲット
Home、SettingsなどのGUIショートカットターゲット

ターゲットを起動するディレクティブには、定義済みの起動ターゲットのリストにある名前と識別子が含まれます。起動ターゲットのリストを確認して、スキルの機能をサポートするアイテムを、スキルが確実に正しく解決できるようにしてください。

Launcherインターフェースでサポートされているロケールについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。

注： Alexa.Launcherインターフェースは、クラウド側の統合でのみ使用できます。

ディレクティブ

LaunchTarget

指定したアプリまたはショートカットを起動するようリクエストします。ユーザーが指定したアプリまたはショートカットは、定義済みの起動ターゲットのリストにある識別子と照合され、その名前と識別子がリクエストで送信されます。

ユーザー：アレクサ、Prime Videoを起動して

例： Prime Videoを起動する

{
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "LaunchTarget",
            "namespace": "Alexa.Launcher",
            "payloadVersion": "3"
        },
        "payload": {
            "identifier": "amzn1.alexa-ask-target.app.72095",
            "name": "Prime Video"
        }
    }
}

ペイロードの詳細

プロパティ	説明	型	必須
`identifier`	起動するアイテムの識別子です。アプリの識別子には`app`、ショートカットの識別子には`shortcut`が含まれます。識別子のリストについては、起動ターゲットのリファレンスを参照してください。	文字列	○
`name`	識別子に関連付けられた名前です。	文字列	○

イベントとプロパティ

レポート可能なプロパティ

プロパティ名	型	説明
target	Target	起動されるアプリまたはショートカットです。

Response

LaunchTargetディレクティブが正常に処理されたら、Responseを送信します。

レスポンスの例

以下に、Responseメッセージの例を示します。メッセージのコンテキストでtargetプロパティの値をレポートします。

{
    "context": {
        "properties": [
            {
                "name": "target",
                "namespace": "Alexa.Launcher",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": {
                    "identifier": "amzn1.alexa-ask-target.app.72095",
                    "name": "Prime Video"
                }
            }
        ]
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}