Alexa for Apps Skill Connectionsリクエストのリファレンス

注： Alexa for Appsは開発者プレビュー段階です。フィードバックに基づく改善や今後の機能強化によって変更される場合があります。この機能を利用するには、登録してプレビューを申請する必要があります。Alexa for Appsに関するご質問やご意見がありましたら、alexaforapps-help@amazon.com（英語）までメールでお寄せください。

カスタムスキルにAlexa for Appsを追加すると、Skill Connectionsリクエストを使って、ユーザーをアプリやウェブサイトに接続できます。Alexa for Appsをスキルに追加する方法については、Alexa for Appsをカスタムスキルに追加するを参照してください。Skill Connectionsリクエストと応答の形式についての概要は、カスタムスキルのJSONインターフェースのリファレンスを参照してください。

Skill Connectionsリクエストペイロードの例

以下は、Alexa for Appsペイロードリクエストのペイロードの例です。

デフォルトのリンク動作 – ユニバーサルリンクのペイロード例

以下は、ユニバーサルリンクを使ったSkill Connectionsリクエストペイロードの例です。

ユーザーがモバイルデバイスでリクエストを行うと、Alexaはデフォルトでアプリを直接起動します。非モバイルデバイスでは、Alexaは指定されたリンクを含むプッシュ通知をユーザーのスマートフォンに送信します。

この例では、ユーザーはモバイルデバイスでリクエストを行います。スキルは直接起動か通知の送信かを指定していないため、結果としてユーザーのスマートフォンでアプリを直接起動するエクスペリエンスとなります。

重要： 実際のペイロードでは、「ALEXA FOR APPSの追加開始」、「ALEXA FOR APPSの追加終了」の行は省略します。

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPSの追加開始 ==================
         {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
               "links": {
                  "IOS_APP_STORE": {
                     "primary": {
                        "UNIVERSAL_LINK": {
                           "appIdentifier": "id123456789",
                           "url": "https://www.cityguide.com/search/search_terms=coffee"
                        }
                     }
                  },
                  "GOOGLE_PLAY_STORE": {
                     "primary": {
                        "UNIVERSAL_LINK": {
                           "appIdentifier": "com.cityguide.app",
                           "url": "https://www.cityguide.com/search/search_terms=coffee"
                        }
                     }
                  }
               },
               "prompt": {
                  "topic": "検索結果を見る",
                  "directLaunchDefaultPromptBehavior": "SPEAK"
               }
            }
         }
================== ALEXA FOR APPSの追加終了 ====================
      ]
   }
}

直接起動のみ - AndroidカスタムインテントとExtraデータの例

以下は、ANDROID_CUSTOM_INTENTディープリンクを使ったSkill Connectionsリクエストペイロードの例です。スキルはモバイルデバイス上で直接アプリを起動する必要があるだけなので、sendToDevice.enabledプロパティを明示的にfalseに設定します。

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPSの追加開始 ==================
         {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
               "links": {
                  "GOOGLE_PLAY_STORE": {
                     "primary": {
                        "ANDROID_CUSTOM_INTENT": {
                           "appIdentifier": "com.cityguide.app",
                           "intentSchemeUri": 
intent:#Intent;package=com.cityguide.app;component=com.cityguide.app.SearchActivity;S.stringExtra=stringValue;i.intExtra=20;B.booleanExtra=true;end"
                        }
                     }
                  }
               },
               "prompt": {
                  "topic": "検索の詳細を見る"
               },
               "sendToDevice": {
                  "enabled": false
               }
            }
         }
================== ALEXA FOR APPSの追加終了 ====================
      ]
   }
}

スマートフォンへの引き継ぎのみ - Android共通インテントと共通URIスキームの例

以下は、Android共通インテントとディープリンク用の共通URIスキームの両方を使ったSkill Connectionsリクエストペイロードの例です。押し付けがましくならないようプッシュ通知の送信のみを行い、ユーザーのスマートフォンでアプリを直接起動しないようにします。このため、スキルはdirectLaunch.enabledの値をfalseに設定します。

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPSの追加開始 ==================
         {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
               "links": {
                  "GOOGLE_PLAY_STORE": {
                     "primary": {
                        "ANDROID_COMMON_INTENT": {
                           "intentName": "OPEN_SETTINGS",
                           "intentSchemeUri": "intent:#Intent;action=android.settings.WIFI_SETTINGS;end"
                        }
                     }
                  },
                  "IOS_APP_STORE": {
                     "primary": {
                        "COMMON_SCHEME": {
                           "scheme": "TEL",
                           "uri": "tel:1234567"
                        }
                     }
                  }
               },
               "prompt": {
                  "topic": "設定を見る"
               },
               "directLaunch": {
                  "enabled": false
               }
            }
         }
================== ALEXA FOR APPSの追加終了 ====================
      ]
   }
}

Skill Connectionsリクエストのプロパティリファレンス

typeとuriの値

最上位のtypeとuriの値は常に同じです。Alexa Skill Connectionsにはこれらの値が必須です。以下の例とまったく同じ値を使用します。

"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/2",

inputペイロードのlinksオブジェクト

スキルが送信するリンクを指定します。inputペイロードは、catalogTypeごとにリンクをグループ化します。現在サポートされているcatalogTypeの値は、"IOS_APP_STORE"と"GOOGLE_PLAY_STORE"です。

フィールド	説明	型	必須
`links.IOS_APP_STORE`	`IOS_APP_STORE`カタログのリンクです。	オブジェクト	✕（`links.GOOGLE_PLAY_STORE`が指定されている場合）。〇（それ以外）。
`links.IOS_APP_STORE.primary`	プライマリリンクです。詳細については、ディープリンクのリファレンスを参照してください。	次のいずれかになります： `UNIVERSAL_LINK`、 `ANDROID_CUSTOM_INTENT`、 `CUSTOM_SCHEME`、 `WEBSITE_LINK`、 `COMMON_SCHEME`、 `ANDROID_COMMON_INTENT`、 `ANDROID_PACKAGE`。	〇
`links.IOS_APP_STORE.fallback`	フォールバックのリンクです。詳細については、ディープリンクのリファレンスを参照してください。	次のいずれかになります： `UNIVERSAL_LINK`、`WEBSITE_LINK`。	✕
`links.GOOGLE_PLAY_STORE`	`GOOGLE_PLAY_STORE`カタログのリンクです。	オブジェクト	✕（`links.IOS_APP_STORE`が指定されている場合）。〇（それ以外）。
`links.GOOGLE_PLAY_STORE.primary`	プライマリリンクです。詳細については、ディープリンクのリファレンスを参照してください。	次のいずれかになります： `UNIVERSAL_LINK`、`ANDROID_CUSTOM_INTENT`、`CUSTOM_SCHEME`、`WEBSITE_LINK`、`COMMON_SCHEME`、`ANDROID_COMMON_INTENT`、`ANDROID_PACKAGE`。	〇
`links.GOOGLE_PLAY_STORE.fallback`	フォールバックのリンクです。詳細については、ディープリンクのリファレンスを参照してください。	次のいずれかになります： `UNIVERSAL_LINK`、`WEBSITE_LINK`。	✕

inputペイロードのpromptオブジェクト

promptオブジェクトは、アプリのカスタムAlexaプロンプトを指定します。このオブジェクトはオプションです。

フィールド	説明	型	必須
`prompt.topic`	リンクを説明するトピック文字列です。Alexaはトピック文字列を使ってユーザーにリンクの目的を説明します。この文字列は動詞句の形式で、`「メッセージを見る」`のように指定します。	文字列	〇
`prompt.directLaunchDefaultPromptBehavior`	モバイルリクエストでスマートフォンをロック解除するときに出す「こちらが<フレンドリー名>です」のような直接起動ヘルププロンプトを出すかどうかを指定します。`SPEAK`か`SUPPRESS`のいずれかです。	列挙	✕

inputペイロードのdirectLaunchオブジェクト

フィールド	説明	型	必須
`enabled`	モバイルデバイスでアプリの直接起動を許可するには`true`、それ以外は`false`に設定します。デフォルト値は`true`です。	ブール値	〇

inputペイロードのsendToDeviceオブジェクト

フィールド	説明	型	必須
`enabled`	このリクエストで通知の送信を許可するには`true`、それ以外は`false`に設定します。デフォルト値は`true`です。	ブール値	〇

ディープリンクの例

次の例は、ディープリンクオブジェクトの形式を示しています。

"UNIVERSAL_LINK": {
    "appIdentifier": "id123456789", # Androidの場合は"com.someapp"
    "url": "https://www.cityguide.com/search/search_terms=coffee",
}

"ANDROID_CUSTOM_INTENT": {
    "appIdentifier": "com.someapp",
    "intentSchemeUri": "intent:#Intent;package=com.someapp;action=com.example.myapp.MY_ACTION;i.some_int=100;S.some_str=hello;end"
}

"CUSTOM_SCHEME": {
    "appIdentifier": "id123456789", # または "com.someapp"
    "uri": "twitter://feeds/"
}

"WEBSITE_LINK": {
    "url": "https://www.cityguide.com/search/search_terms=coffee"
}

"COMMON_SCHEME": {
    "scheme": "TEL",
    "uri": "tel:8001234567"
}

"ANDROID_PACKAGE": {
    "packageIdentifier": "com.someapp"
}

"ANDROID_COMMON_INTENT": {
    "intentName": :"OPEN_SETTINGS",
    "intentSchemeUri": "intent:#Intent;action=android.settings.WIFI_SETTINGS;end"
}

ディープリンクのリファレンス

次の表では、ディープリンクオブジェクトのフィールドを説明しています。

フィールド	説明	型	必須
`UNIVERSAL_LINK`	特定のアプリでユーザーが起動できるユニバーサルリンクを表すオブジェクトです。	オブジェクト	✕
`UNIVERSAL_LINK.appIdentifier`	ユーザーがリンクを開くターゲットアプリです。	文字列	〇
`UNIVERSAL_LINK.url`	ユニバーサルリンクのURLです。	文字列	〇
`ANDROID_CUSTOM_INTENT`	特定のアプリでユーザーが起動できるAndroidカスタムインテントを表すオブジェクトです。	オブジェクト	✕
`ANDROID_CUSTOM_INTENT.appIdentifier`	ユーザーがリンクを開くターゲットアプリです。	文字列	〇
`ANDROID_CUSTOM_INTENT.intentSchemeUri`	Androidインテントのインテントスキームの文字列です。	文字列	〇
`CUSTOM_SCHEME`	特定のアプリでユーザーが起動できるカスタムスキームを表すオブジェクトです。	オブジェクト	✕
`CUSTOM_SCHEME.appIdentifier`	ユーザーがリンクを開くターゲットアプリです。	文字列	〇
`CUSTOM_SCHEME.uri`	リンクのURIです。Androidの場合、スキームは`"geo:"`です。iOSの場合、スキームは`"maps:"`です。	文字列	〇
`WEBSITE_LINK`	ユーザーがブラウザで開けるウェブリンクを表すオブジェクトです。	オブジェクト	✕
`WEBSITE_LINK.url`	リンクのURLです。	文字列	〇
`COMMON_SCHEME`	システムが開ける共通スキームURIを表すオブジェクトです。Alexa for Appsは、`scheme`に基づいてこのオブジェクトのフィールドを実行時に検証します。たとえば、スキルで`TEL`のサポートを宣言している場合、Alexa for Appsは`uri`値に`"tel:"`とそれに続く数値があることを確認します。	オブジェクト	✕
`COMMON_SCHEME.scheme`	スキームです。 `MAPS`、`TEL`のいずれかになります。	列挙	〇
`COMMON_SCHEME.uri`	スキームのURLです。	文字列	〇
`ANDROID_PACKAGE`	Androidパッケージを表すオブジェクトです。	オブジェクト	✕
`ANDROID_PACKAGE.packageIdentifier`	Androidアプリのパッケージ名です。	文字列	〇
`ANDROID_COMMON_INTENT`	デフォルトアプリが開くことのできるAndroid共通インテントを表すオブジェクトです。Alexa for Appsは、マニフェストで宣言された`linkedAndroidCommonIntents.intentName`の値に基づいて実行時にこのオブジェクトのフィールドを検証します。たとえば、この値が`SHOW_IN_MAP`の場合、`action`値は`"android.intent.action.VIEW"`となり、`data`値は`"geo:"`で始まらなければなりません。	オブジェクト	✕
`ANDROID_COMMON_INTENT.intentName`	インテント名です。この値は、スキルマニフェストの`linkedAndroidCommonIntents.intentName`値と一致する必要があります。次のいずれかになります： `SHOW_IN_MAP`、`ADD_CALENDAR_EVENT`、`PLAY_MEDIA`、`START_PHONE_CALL`、`OPEN_SETTINGS`	列挙	〇
`ANDROID_COMMON_INTENT.intentSchemeUri`	Androidインテントのインテントスキームの文字列です。	文字列	〇

Skill Connectionsリクエスト応答のペイロードの例とリファレンス

スキルからスマートフォンへの引き継ぎから受け取れるSkill Connectionsの応答には3つの種類があります。directLaunchリクエスト（Alexaがスマートフォンから直接アプリを開く場合）への応答、sendToDeviceリクエスト（ユーザーがEchoデバイスで開始してスマートフォンに送信されるプッシュ通知フローを受け取る場合）への応答、この2つのフローのどちらかが実行される前にリクエストが失敗した場合の応答の3つです。

directLaunchへの応答のペイロードの例

以下は、directLaunchで受け取るペイロードの形式の例です。

{
   "type": "SessionResumedRequest",
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "<see table>",
         "message": "<see table>"
      },
      "result": {
         "directLaunch": {
            "primary": {
               "status": "<see table>",
               "errorCode": "<see table>"
            },
            "fallback": {
                "status": "<see table>",
                "errorCode": "<see table>"
            }
         }
      }
   }
}

directLaunchへの応答のペイロードのリファレンス

次の表は、前の例の「see table」というラベルの付いたフィールドで受け取れる可能性のある応答の一覧です。fallbackプロパティは、フォールバックが試行された場合にのみ存在します。これは、プライマリリンクに関連付けられたアプリがインストールされていない場合や、アプリのバージョンが指定されたディープリンクと互換性がない場合（Androidアプリの場合）に発生します。

Skill Connectionsのコード	Skill Connectionsのメッセージ	directLaunchのプライマリステータス	directLaunchのプライマリerrorCode	directLaunchフォールバックステータス	directLaunchのフォールバックerrorCode
400	デバイスがAppLinkまたはリクエストされたカタログの種類をサポートしていません。	FAILURE	UNSUPPORTED_DEVICE	なし	なし
500	不明なエラーを受け取りました。	FAILURE	UNKNOWN	なし	なし
200	デバイスが無効な状態です。	FAILURE	INVALID_STATE	なし	なし
200	リクエストは正常に実行されました。	SUCCESS	なし	なし	なし
200	フォールバックアクションが正常にレンダリングされました。	FAILURE	APP_NOT_INSTALLED	SUCCESS	なし
200	フォールバックアクションが正常にレンダリングされました。	FAILURE	APP_INCOMPATIBLE	SUCCESS	SUCCESS
500	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_NOT_INSTALLED	FAILURE	UNKNOWN
200	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_NOT_INSTALLED	FAILURE	APP_NOT_INSTALLED
200	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_NOT_INSTALLED	FAILURE	APP_INCOMPATIBLE
200	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_NOT_INSTALLED	FAILURE	INVALID_STATE
500	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_INCOMPATIBLE	FAILURE	UNKNOWN
200	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_INCOMPATIBLE	FAILURE	APP_NOT_INSTALLED
200	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_INCOMPATIBLE	FAILURE	APP_INCOMPATIBLE
200	接続が完了しました。フォールバックアクションが失敗しました。	FAILURE	APP_INCOMPATIBLE	FAILURE	INVALID_STATE
200	接続が完了しました。フォールバックアクションが指定されていません。	FAILURE	UNKNOWN	なし	なし

sendToDeviceへの応答のペイロードの例

以下は、sendToDeviceで受け取るペイロードの形式の例です。

{
   "type": "SessionResumedRequest",
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "<see table>",
         "message": "<see table>"
      },
      "result": {
         "sendToDevice": {
            "status": "<see table>",
            "errorCode": "<see table>"
         }
      }
   }
}

sendToDeviceへの応答のペイロードのリファレンス

次の表は、前の例の「see table」というラベルの付いたフィールドで受け取れる可能性のある応答の一覧です。errorCodeフィールドは通常プッシュ通知とアクティビティカードの両方が試行され正常に送信されたか、試行と正常送信のどちらかのみが発生したかを参照します。Alexa for Appsがプッシュ通知の送信を試行しない理由としては、ユーザーがAlexaアプリのプッシュ通知を無効にしたか、スキルの通知を有効にしていない場合が考えられます。Skill Connections応答のコードは、接続の呼び出しが成功したかどうかを示します。sendToDeviceステータスは、リンクの送信が成功したかどうかを示します。

Skill Connectionsのコード	Skill Connectionsのメッセージ	sendToDeviceのステータス	sendToDeviceのerrorCode
200	通知は試行されませんでした。	FAILURE	NOTIFICATION_NOT_ATTEMPTED
200	Alexa for Appsはアクティビティカードの送信を試行し、成功しました。	SUCCESS	CARD_ATTEMPTED_AND_SENT
500	Alexa for Appsはアクティビティカードの送信を試行し、失敗しました。	FAILURE	CARD_ATTEMPTED_AND_FAILED
200	Alexa for Appsはアクティビティカードとプッシュ通知の送信を試行しましたが、アクティビティカードの送信のみ成功しました。	SUCCESS	ALL_ATTEMPTED_CARD_SENT
200	Alexa for Appsはアクティビティカードとプッシュ通知の送信を試行しましたが、プッシュ通知の送信のみ成功しました。	SUCCESS	ALL_ATTEMPTED_PUSH_SENT
200	Alexa for Appsはアクティビティカードとプッシュ通知の送信を試行し、両方の送信に成功しました。	SUCCESS	ALL_ATTEMPTED_ALL_SENT
500	Alexa for Appsはアクティビティカードとプッシュ通知の送信を試行し、両方の送信に失敗しました。	FAILURE	ALL_ATTEMPTED_ALL_FAILED
500	不明なエラーが発生しました。	FAILURE	UNKNOWN

リクエストが早期に失敗した場合のペイロードの例

以下は、リクエストがフローの決定前に終了した場合に受け取るペイロードの形式を示した例です。

{
   "type": "SessionResumedRequest",
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "<see table>",
         "message": "<see table>"
      }
   }
}

リクエストが早期に失敗した場合のペイロードのリファレンス

次の表は、前の例の「see table」というラベルの付いたフィールドで受け取れる可能性のある応答の一覧です。

Skill Connectionsのコード	Skill Connectionsのメッセージ	説明
403	`Skill not allowlisted.`	スキルはAlexa for Appsのスキルからスマートフォンへの引き継ぎの許可リストに登録されていません。
500	`Unknown error occurred.`	サービスエラーが発生しました。
400	`Domain or Android intent {URI or intent} provided at runtime was not declared in skill manifest.`	ディープリンクのURIまたは実行時に指定されたインテントがスキルマニフェストで宣言されていません。
400	`Fallback URI type is not supported.`	無効な種類のフォールバックが指定されました。フォールバックディープリンクを指定する場合は、ウェブサイトかユニバーサルリンクのいずれかにする必要があります。アプリのディープリンクの場合、デフォルトのフォールバックはApple App StoreかGoogle Playストアです。
400	`Request version does not match skill manifest.`	スキルマニフェストで宣言されたAppLinksのインターフェースバージョンが、リクエストされたランタイムのバージョンと一致しません。
400	`Required field {fieldName} cannot be null.`	スキルが送信したAlexa for Appsペイロードに足りない必須フィールドがあります。
400	`Customer-facing content does not comply with Alexa skill policy.`	スキルのAlexa for Apps API呼び出しのユーザー向けコンテンツに問題がありました。
400	`Adding URI in notification title content is not supported.`	通知タイトルにリンクを指定することはできません。
400	`{dataPath} cannot contain {dataValue}.`	指定されたカスタムスキームのいずれかがサポートされていません。
204	`User canceled to use the connection.`	ユーザーが対話中にキャンセルしたため、Alexa for Appsが通知の送信に失敗しました。