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

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

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

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

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

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

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

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

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

{
   "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ペイロードは、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のいずれかです。

列挙

✕

フィールド 説明 型 必須

enabled

モバイルデバイスでアプリの直接起動を許可するにはtrue、それ以外はfalseに設定します。デフォルト値はtrueです。

ブール値

〇

フィールド 説明 型 必須

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が通知の送信に失敗しました。