開発者コンソール

Alexa.Launcherインターフェース

Alexa.Launcherインターフェース

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

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

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

ディレクティブ

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_STOREALEXA_VIDEO_APP_STOREです。
カスタムショートカットの場合、有効な値は DISCOVERYです。
文字列
experience.mode リクエストされた結果を表示するモードを示します。VOICE_OPTIMIZEDは、音声中心の結果(短い検索結果リストなど)を示します。モードの値をサポートしない場合は、DEFAULTを使用します。

有効な値は DEFAULTVOICE_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」の両方を指定する必要があります。

イベントとプロパティ

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

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

構成オブジェクト

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

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

Catalogオブジェクト

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インターフェースは、以下のターゲットを起動するためのディレクティブを提供します。

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

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

ディレクティブ

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": {}
    }
}

ErrorResponse

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