Alexa for Apps Skill Connectionsリクエストのリファレンス
カスタムスキルにAlexa for Appsを追加したら、追加されたSkill Connectionsリクエストフィールドを使って、ユーザーをスキルに接続します。Alexa for Appsをスキルに追加する方法については、Alexa for Appsをカスタムスキルに追加するを参照してください。完全なSkill Connectionsリクエストと応答の形式については、カスタムスキルのJSONインターフェースのリファレンスを参照してください。
Skill Connectionsリクエストペイロードの例
以下は、ユニバーサルリンクを使ったSkill Connectionsリクエストペイロードの例です。
ユニバーサルリンク – IOS_APP_STORE
ペイロードの例
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {...},
"card": {...},
"reprompt": {...},
"directives": [
================== ALEXA FOR APPSの追加開始 ==================
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/1",
"input": {
"catalogInfo": {
"identifier": "id123456789",
"type": "IOS_APP_STORE"
},
"actions": {
"primary": {
"type": "UNIVERSAL_LINK",
"link": "https://www.cityguide.com/search/search_terms=coffee"
}
},
"prompts": {
"onAppLinked": {
"prompt": {
"ssml": "<speak>わかりました</speak>",
"type": "SSML"
},
"defaultPromptBehavior": "SUPPRESS" // これにより、追加されたヘルパーTTS「<app name>です。」は読み上げられなくなります。
},
"onScreenLocked": {
"prompt": {
"text": "1キロ圏内にカップケーキショップとコーヒーショップがあります。",
"type": "PlainText"
}
}
}
}
},
================== ALEXA FOR APPSの追加終了 ====================
]
}
}
Skill Connectionsリクエストのプロパティリファレンス
type
とuri
の値
最上位のtype
とuri
の値は常に同じです。Alexa Skill Connectionsにはこれらの値が必須です。以下の例とまったく同じ値を使用します。
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/1",
input
ペイロードのcatalogInfo
オブジェクト
catalogInfo
オブジェクトには、AndroidやiOSアプリのリンクリクエストに必要な情報が含まれます。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
IOS_APP_STORE 、GOOGLE_PLAY_STORE のいずれかです。 |
文字列の列挙値 | 〇 |
identifier |
iOS App StoreまたはGoogle Playストア内のアプリのIDです。iOSアプリの場合は、id123456789 など、数値のIDとなります。Androidインテントの場合、通常はcom.cityguide.android.ctgdmobile などのパッケージ名となります。 |
文字列 | ◯ |
input
ペイロードのactions
オブジェクト
actions
オブジェクトは、プライマリおよびフォールバックアクションにリクエストされたリンクを指定します。primary
オブジェクトは必須です。fallback
オブジェクトは任意です。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
primary.type |
プライマリアクションのディープリンクの種類を指定します。 UNIVERSAL_LINK 、CUSTOM_SCHEME 、ANDROID_INTENT 、ANDROID_PACKAGE のいずれかです。 |
文字列の列挙値 | 〇 |
fallback.type |
フォールバックアクションのディープリンクの種類を指定します。現時点では、UNIVERSAL_LINK のみ指定可能です。 |
文字列の列挙値 | 〇(fallback オブジェクトが指定されている場合) |
primary.link |
ユーザーがアプリをデバイスにインストールしていない場合にユーザーに送信するディープリンク(前の例ではhttps URI)です。 |
文字列 | ◯ |
fallback.link |
ユーザーがアプリをデバイスにインストールしていない場合にユーザーをリダイレクトするディープリンクです。App Storeフォールバックの場合、ウェブサイトではなくApp Storeの完全URIを指定します。 | 〇(fallback オブジェクトが指定されている場合) |
input
ペイロードのprompts
オブジェクト
prompts
オブジェクトは、アプリのAlexaプロンプトのプロパティを指定します。このオブジェクトは任意です。onAppLinked
、onScreenLocked
のいずれかに対して指定できます。指定する場合、prompts
オブジェクトにはprompt
プロパティが必要であり、そのtype
フィールドの値はPlainText
、SSML
のいずれかである必要があります。type
がSSML
の場合、prompt
プロパティの値はssml
である必要があります。type
がPlainText
の場合、prompt
プロパティの値はtext
である必要があります。
onAppLinked
のprompts
プロパティ
これらのプロパティは、ユーザーのデバイスがロックされている場合を除く、すべてのケースに使用するプロンプトを指定します。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
prompt.type |
Plaintext 、SSML のいずれかです。SSML を指定すると、Amazon Polly音声、サウンドエフェクト、prosodyといったさまざまなエフェクトを適用できます。 |
文字列の列挙値 | 〇 |
prompt.text |
prompt.type がPlaintext の場合、このフィールドには、ディープリンクが送信される前にAlexaが読み上げる、カスタム音声応答のロケール固有のカスタムテキストが含まれます。i18next などのフレームワークを使ってローカライゼーションコードを簡易化できます。Alexaスキルのローカライズ方法を参照してください。 |
文字列 | 〇(prompt.type がPlaintext の場合) |
prompt.ssml |
prompt.type がSSML の場合、このフィールドには、ユーザーのデバイスがロック解除されたときにAlexaが読み上げるカスタム音声応答のローカル固有のSSMLが含まれます。 |
文字列の列挙値 | 〇(prompt.type がSSML の場合) |
prompt.defaultPromptBehavior |
デフォルトでは、ユーザーのデバイスがロック解除されると、prompt.text のテキストの後で、Alexaが「\<app name\> です。」と言います。 このフレーズは、ヘルパーTTSと呼ばれます。ヘルパーTTSを読み上げないようにするには、このプロパティをSUPPRESS に設定します。前の例では、ヘルパーTTSが読み上げられないため、ディープリンクが送信される前にAlexaが「わかりました。」とだけ言います。 |
文字列 | ✕ |
onScreenLocked
のprompts
プロパティ
これらのプロパティは、ユーザーのデバイスがロックされている場合に使用するプロンプトを指定します。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
prompt.type |
Plaintext 、SSML のいずれかです。SSML を指定すると、Amazon Polly音声、サウンドエフェクト、prosodyといったさまざまなエフェクトを適用できます。 |
文字列の列挙値 | 〇 |
prompt.text |
prompt.type がPlaintext の場合、このフィールドには、ユーザーのデバイスがロックされたときにAlexaが読み上げる、カスタム音声応答のロケール固有のカスタムテキストが含まれます。i18next などのフレームワークを使ってローカライゼーションコードを簡易化できます。Alexaスキルのローカライズ方法を参照してください。 |
文字列 | 〇(prompt.type がPlaintext の場合) |
prompt.ssml |
prompt.type がSSML の場合、このフィールドには、ユーザーのデバイスがロックされたときにAlexaが読み上げるカスタム音声応答のローカル固有のSSMLが含まれます。 |
文字列の列挙値 | 〇(prompt.type がSSML の場合) |
prompt.defaultPromptBehavior |
デフォルトでは、ユーザーのデバイスがロックされると、prompt.text またはprompt.ssml の応答の後、Alexaが「続行するには、デバイスのロックを解除してください。」と言います。 このフレーズは、ヘルパーTTSと呼ばれます。ヘルパーTTSを読み上げないようにするには、このプロパティをSUPPRESS に設定します。ユーザーに必要なガイダンスを提供するため、Amazonでは通常読み上げない設定にすることは推奨していませんが、ガイダンスフローがより自然になる場合は読み上げないようにしてもかまいません。たとえば、カスタムテキストで「この近くにコーヒーショップを3軒見つけました。ショップの場所を確認するにはデバイスのロックを解除してください。」のように言うとします。 前の例では、読み上げを停止していないため、Alexaが「1キロ圏内にカップケーキショップとコーヒーショップがあります。続行するには、デバイスのロックを解除してください。」と言います。 |
文字列 | ✕ |
その他のSkill Connectionsリクエストペイロードの例
カスタムスキーム - GOOGLE_PLAY_STORE
ペイロードの例
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {...},
"card": {...},
"reprompt": {...},
"directives": [
================== ALEXA FOR APPSの追加開始 ==================
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/1",
"input": {
"catalogInfo": {
"identifier": "com.cityguide.android.ctgdmobile",
"type": "GOOGLE_PLAY_STORE"
},
"actions": {
"primary": {
"type": "CUSTOM_SCHEME",
"link": "ctgd://search/search_terms=coffee"
}
},
"prompts": {
"onAppLinked": {
"prompt": {
"ssml": "<speak>わかりました</speak>",
"type": "SSML"
},
"onScreenLocked": {
"prompt": {
"text": "1キロ圏内にカップケーキショップとコーヒーショップがあります。", // この後にデフォルトのヘルパーTTS「
続行するには、デバイスのロックを解除してください。」が再生されます。
"type": "PlainText"
}
}
}
}
},
================== ALEXA FOR APPSの追加終了 ====================
]
}
}
Androidインテントペイロードの例
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {...},
"card": {...},
"reprompt": {...},
"directives": [
================== ALEXA FOR APPSの追加開始 ==================
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/1",
"input": {
"catalogInfo": {
"identifier": "com.cityguide.android.ctgdmobile",
"type": "GOOGLE_PLAY_STORE"
},
"actions": {
"primary": {
"type": "ANDROID_INTENT",
"link": "intent:#Intent;action=com.cityguide.android.ctgdmobile.actions.SEARCH_ACTION;package=com.cityguide.android.ctgdmobile;S.query=coffee;end;"
},
"fallback": {
"type": "UNIVERSAL_LINK",
"link": "http://www.cityguide.com/search?search_terms=coffee" // cityguide.comを起動します。
}
},
"prompts": {
"onAppLinked": {
"prompt": {
"text": "わかりました。",
"type": "PlainText"
},
"defaultPromptBehavior": "SUPPRESS" // これにより、追加されたヘルパーTTS「<app name>です。」は読み上げられなくなります。
},
"onScreenLocked": {
"prompt": {
"ssml": "<speak>1キロ圏内にカップケーキショップとコーヒーショップがあります。</speak>",
"type": "SSML"
}
// この例ではdefaultPromptBehaviorがSUPPRESSに設定されていないため、デフォルトのヘルパーTTS「続行するには、デバイスのロックを解除してください。」が前のonScreenLocked SSML応答の後に再生されます。
}
}
}
},
================== ALEXA FOR APPSの追加終了 ====================
]
}
}
Androidアプリ起動の例
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {...},
"card": {...},
"reprompt": {...},
"directives": [
================== ALEXA FOR APPSの追加開始 ==================
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/1",
"input": {
"catalogInfo": {
"identifier": "com.cityguide.android.ctgdmobile",
"type": "GOOGLE_PLAY_STORE"
},
"actions": {
"primary": {
"type": "ANDROID_PACKAGE",
"link": "com.cityguide.android.ctgdmobile"
}
},
"prompts": {
"onAppLinked": {
"prompt": {
"text": "わかりました。",
"type": "PlainText"
},
"defaultPromptBehavior":"SUPPRESS" // これにより、デフォルトのヘルパーTTS「シティガイドです。」の読み上げは停止されます。
このため、ユーザーがアプリにリダイレクトされる前には「わかりました。」のみが読み上げられます。
},
"onScreenLocked": {
"prompt": {
"text": "1キロ圏内にカップケーキショップとコーヒーショップがあります。", // この後にデフォルトのヘルパーTTS「
アプリで続行するには、デバイスのロックを解除してください。」が再生されます。
"type": "PlainText"
}
}
}
}
},
================== ALEXA FOR APPSの追加終了 ====================
]
}
}
Skill Connections応答ペイロードの例
以下は、Skill Connections応答の例です。
{
"type": "SessionResumedRequest"
"requestId": "<string>",
"timestamp": "<string>",
"locale": "<string>",
"cause":
{
"type": "ConnectionCompleted",
"token": "1234",
"status": {"code": "200","message": "OK"},
"result": {
"primary": {
"status": "FAILURE",
"errorCode": "APP_INCOMPATIBLE"
},
"fallback": {
"status": "SUCCESS"
}
}
}
}
Skill Connections応答のリファレンス
Skill Connections応答ペイロードでは、cause.status
プロパティが、ディープリンクの試行結果ではなく、スキルの接続自体を参照します。result
ペイロードは、cause.result.primary.status
プロパティとcause.result.fallback.status
プロパティを使って、スキルにプライマリアクションとフォールバックアクションが成功か失敗か、また失敗した場合はエラーコードを通知します。エラーコードとその説明については、以下の表を参照してください。
エラーコード | 詳細 | ステータスコード |
---|---|---|
UNSUPPORTED_DEVICE | デバイスがサポートされていません。 | 400 |
UNAUTHORIZED | スキルに権限がありません。たとえば、開発者プレビューに登録されていない場合やマニフェストで宣言されていないアプリへのディープリンクを試行している場合などが考えられます。 | 403 |
INVALID_REQUEST | ペイロードが無効です。 | 400 |
INVALID_STATE | リクエストの時点でデバイスの状態が無効でした。たとえば、ユーザーが運転中の場合やデバイスがロック解除されなかった場合などが考えられます。 | 200 |
UNKNOWN | モバイルデバイスでディープリンクを起動するサービス側のエラーを示します。 | 500 |
APP_NOT_INSTALLED | アプリがインストールされていません。 | 200 |
APP_INCOMPATIBLE | (Androidのみ)アプリはインストールされていますが、インストールされているバージョンには指定されたアクションとの互換性がありません。 | 200 |