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リクエストペイロードの例

以下は、ユニバーサルリンクを使った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