チュートリアル: Alexa for Apps V1からV2への移行
このチュートリアルは、Alexa for Apps V1を使用するスキルを開発済みで、Alexa for Apps V2への移行を希望する開発者向けです。
V2のAPIでは、Echoデバイスを始め、あらゆるAlexa搭載デバイスからの音声によるアプリエクスペリエンスをスキルが橋渡しできるようになります。
V1とV2のユーザーエクスペリエンスの違い
V1とV2のおもな違いは、V1では、スキルがモバイルデバイス上のアプリに移動することのみ可能だったことです。V2では、スキルを使ってAlexa対応デバイス(Amazon Echoデバイスなど)からアプリにつなぐこともできます。
移行ワークフロー
以下のタスクリストは、スキルをAlexa for Apps V2に移行する際の手順をまとめたものです。
ステップ1: スキルマニフェストを更新する
スキルマニフェストを更新し、Alexa for Apps V2のサポートとインテントを宣言します。
スキルマニフェストを更新する
-
Alexa Skills Kitコマンドラインインターフェース(ASK CLI)を開きます。
-
カスタムスキルのスキルマニフェストの
manifest.apis.custom.interfaces
セクションで、"type": "APP_LINKS"
を"type": "APP_LINKS_V2"
に置き換えます。この宣言により、AlexaはスキルがAppLink V2インターフェースをサポートすることを認識できます。AppLink V1インターフェースとAppLink V2インターフェースの両方を宣言することはできません。
-
スキルからスマートフォンへの引き継ぎのプッシュ通知権限を追加するには、
manifest.permissions
に、alexa::devices:app:push_notifications
を追加します。この権限により、ユーザーはAlexaアプリでスキルのプッシュ通知送信を許可できます。Alexa for Appsは、ユーザーが権限を有効にしていない場合のシナリオを音声による同意を使って処理します。スキルがこの権限を確認したり、ユーザーに権限を有効にするようプロンプトを出したりする必要はありません。この行をマニフェストの権限セクションに追加するだけです。
-
スキルがAndroidのカスタムインテントを使う場合、スキルマニフェストの
appLink
セクションを以下の例のように更新します。注: Alexa for Apps V1では、宣言しなくてもスキルでAndroidのカスタムインテントを送信できました。V2では、Androidのカスタムインテントを宣言する必要があります。"appLink": { "linkedApplications": [ { "friendlyName": { "default": "GrubbHouse", "localizedNames": [ { "locale": "de-DE", "name": "GrubbHaus" } ] }, "catalogInfo": { "type": "GOOGLE_PLAY_STORE", "identifier": "com.someapp" }, "customSchemes": [ "grubbhouse://", "grbh://" ], "domains": [ "grubbhouse.com", "grbh.com" ], # Androidカスタムインテントを宣言します "androidCustomIntents": [ { "component": "com.someapp.SomeActivity", "action": "com.someapp.SOME_ACTION" } ] } ] }
-
Alexa for Apps V2で新たに追加された種類のディープリンク(ウェブサイトのみのリンク、共通URIスキーム、Android共通インテント)を追加する場合、
appLink
セクションを更新してlinkedWebDomains
、linkedCommonSchemes
、linkedAndroidCommonIntents
の必要なプロパティを以下の例のように追加します。詳細については、Alexa for Apps V2 Skill Connectionsリクエストのリファレンスを参照してください。
"appLink": { "linkedWebDomains": [ "grubbhouse.com", "amazon.com", "yahoo.com" ], "linkedCommonSchemes": { "IOS_APP_STORE": [ "MAPS", "TEL" ], "GOOGLE_PLAY_STORE": [ "MAPS", "TEL" ] }, "linkedAndroidCommonIntents": [ { "intentName": "SHOW_IN_MAP", "catalogType": "GOOGLE_PLAY_STORE" } ] }
ステップ2: スキルエンドポイントのコードを更新する
ステップ1では、スキルマニフェストでAlexa for Apps V2のサポートを宣言しました。この宣言により、以下のペイロードが変更されます。
- スキルが受信リクエストで受け取るリクエストペイロード
- Skill Connectionsリクエストでスキルが送信するリクエストペイロード
- スキルが受け取るSkill Connections応答ペイロード
このステップでは、スキルエンドポイントのコードを更新してこれらの変更を処理します。
ステップ2a: 更新された受信リクエストのペイロードを解析する
スキルリクエストのペイロードは、スキルが受信リクエストで受け取るオブジェクトです。Alexa for Apps V2で変更されるこのオブジェクトのセクションは、context.System.device.supportedInterfaces
とcontext.AppLink
の2つです。スキルリクエストハンドラーがこれらのセクションを受け取る場合、コードを更新して正しく解析できるようにする必要があります。
context.System.device.supportedInterfaces
セクションにAppLink
プロパティが存在する場合、スキルがAlexa for Appsリクエストを行うことができることを意味します。V1では、AppLink
プロパティは空のオブジェクトでした。V2では、以下の例のようにversion
フィールドに"2.0"
という値が入ります。この値は、リクエストがAlexa for Apps V2リクエストであることを示します。
"supportedInterfaces": {
"AudioPlayer": {...},
===== ALEXA FOR APPSの追加開始 =====
"AppLink": {
"version": "2.0"
},
===== ALEXA FOR APPSの追加終了 =====
}
Alexa for Apps V1では、context.AppLink
オブジェクトにsupportedCatalogTypes
フィールドのみが含まれました。これは、ユーザーがモバイルOSを使っていることを表します。Alexa for Apps V2では、このオブジェクトにdirectLaunch
フィールドとsendToDevice
フィールドが追加され、モバイルエクスペリエンスと非モバイルエクスペリエンスがサポートされることを表します。directLaunch
フィールドは、アプリの直接起動が可能かどうかを表します。sendToDevice
フィールドは、プッシュ通知フローが可能かどうかを表します。
モバイルリクエストのOSの種類は、directLaunch
プロパティの子オブジェクトに移動しました。
モバイルデバイスからのリクエスト
Alexa for Apps V1と同様、ユーザーがモバイルデバイスからリクエストを行うと、通常は直接起動とプッシュ通知のどちらを使うかを選択できます。ユーザーにとっては多くの場合、ハンズフリーでアプリが起動されるほうが使いやすいです。アプリやウェブサイトを直接起動する代わりにスキルとユーザーとの対話を続けることで、押し付けがましくないエクスペリエンスを実現したい場合は通知を送信できます。
モバイルでの直接起動エクスペリエンスが可能かどうかを判断するには
-
スキルで
context.AppLink.directLaunch
フィールドを確認します。iOSデバイスからのリクエストの場合、このプロパティには以下の例のように
"IOS_APP_STORE"
というキーが含まれます。"AppLink": { "directLaunch": { "IOS_APP_STORE": {} } }
Androidデバイスからのリクエストの場合、このプロパティには以下の例のように
"GOOGLE_PLAY_STORE"
というキーが含まれます。"AppLink": { "directLaunch": { "GOOGLE_PLAY_STORE": {} } }
Alexa搭載デバイスからのリクエスト
Amazon Echoなど、Alexa搭載デバイスからのリクエストの場合、スキルはAlexaアプリの通知でユーザーのモバイルデバイス宛にリンクを送信できます。
スキルがユーザーのスマートフォンに通知を送信できるかどうかを判断するには
-
次の例に示すように、スキルで
context.AppLink.sendToDevice
フィールドを確認します。"AppLink": { "sendToDevice": {} }
以下は、直接起動とスマートフォンへの引き継ぎの両方を処理できるiOSデバイスからリクエストを受信するスキルの例です。
"AppLink": { "directLaunch": { "IOS_APP_STORE": {} }, "sendToDevice": {} }
ステップ2b: Skill Connectionsリクエストで新しい形式のペイロードを送信する
Alexa for Apps V2では新しいURIエンドポイントが追加されました。Skill Connectionsリクエストを行う際に使用することで、アプリを直接起動したり、ユーザーにディープリンクを含む通知を送信したりできます。Alexa for Appsリクエストのペイロード構造は形式が変更されました。ただし、実際に提供する情報はほとんど同じです。詳細については、Alexa for Apps V2 Skill Connectionsリクエストのリファレンスを参照してください。
Alexa for Appsに送信してディープリンクをリクエストするSkill Connectionsペイロードに以下の変更を行います。
ディープリンクをリクエストする
response.directives.uri
フィールドで、スキルのLinkApp
接続URIの末尾に以下のように"/2"
を追加します。"uri": "connection://AMAZON.LinkApp/2"
response.directives.input
フィールドを以下のように変更します。-
response.outputSpeech
プロパティを使って、ディープリンクの前に音声応答を指定します。たとえば、フライトスキルで「フライトは定刻通りにロサンゼルス国際空港を太平洋標準時午後2時に出発します」と読み上げてから、ユーザーにフライトの詳細ページのディープリンクを送信します。
-
onAppLinked
フィールドとonScreenLocked
フィールドを削除し、Alexa for Appsがさまざまなシナリオで対応するために使用する"topic"
フィールドを追加します。
たとえば、ユーザーがディープリンクをトリガーするリクエストを行ったときにスマートフォンがロックされている場合、Alexa for Appsは"メッセージを表示するには、端末のロックを解除してください"と応答します。 トピックの文字数は最大23文字で、アクションを表す句を指定します。日本語で言えば「メッセージを見る」や「ラザニアのレシピを見る」のような形式です。この形式にすることで、Alexaは「太郎さんがラザニアのレシピを見られるようにリンクを送ります」のように、文章内でトピックを再利用できます。
- デフォルトの、ロック解除されたモバイルの直接起動の読み上げ("<アプリ名>です")を適用しない場合は
input.prompt.directLaunchDefaultPromptBehavior
を"SUPPRESS"
に設定します。
注: ロックされたスマートフォンのヘルプ応答を指定したり、出さないようにしたりすることはできなくなります。-
-
サポートするカタログの種類ごとにディープリンクを指定します。
Alexaは、ユーザーの受信デバイス(iOSまたはAndroid)に基づいて適切なリンクを選んで使用します。
モバイルデバイスからのリクエストの場合、Alexa for Appsはデフォルトでユーザーのスマートフォンのアプリを開こうとします。
モバイルデバイスからリクエストが送信されたときの動作を無効にするには
-
Skill Connectionsリクエストペイロードで
directLaunch.enabled
をfalse
に設定します。Alexa搭載デバイスからのリクエストの場合、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;i.some_int=100;S.some_str=hello;end"
}
}
}
},
"prompt": {
"topic": "検索の詳細を見る",
},
"sendToDevice": {
"enabled": false
}
},
================== ALEXA FOR APPSの追加終了 ====================
]
}
}
例: スマートフォンへの引き継ぎのみ — Android共通インテントと共通スキーム
以下は、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の追加終了 ====================
]
}
}
ステップ2c: 更新されたAlexa for Apps応答ペイロードを処理する
Alexa for Apps V2では、応答ペイロードのcause.result
フィールドにdirectLaunch
、sendToDevice
のいずれかが含まれます。directLaunch
が含まれる場合、Alexa for Appsがアプリを起動しようとすることを意味します。sendToDevice
の場合、Alexa for Appsがユーザーのモバイルデバイスにリンクを送信しようとすることを意味します。
更新されたAlexa for Apps応答ペイロードを処理するには
- 応答ハンドラーで
directLaunch
、sendToDevice
のどちらが含まれるかを確認する必要があります。 - また、応答ハンドラーでステータスコードやエラーコードを確認し、試行したアクションが成功したかどうかを判断する必要もあります。
Alexa for AppsがsendToDevice
エクスペリエンスを試行するすべてのケースで、スキルはユーザーとの対話を再開できます。
直接起動の応答例
{
"type": "SessionResumedRequest",
"requestId": "<string>",
"timestamp": "<string>",
"locale": "<string>",
"cause": {
"type": "ConnectionCompleted",
"token": "1234",
"status": {
"code": "200", // これは接続呼び出し自体のステータスコードです
"message": "OK"
},
"result": {
"directLaunch": { // Alexaが直接起動を試行したことを意味します
"primary": {
"status": "FAILURE",
"errorCode": "APP_INCOMPATIBLE" // プライマリリンクに失敗しました
},
"fallback": {
"status": "SUCCESS" // フォールバックに成功しました
}
}
}
}
}
スマートフォンへの引き継ぎの応答例
{
"type": "SessionResumedRequest",
"requestId": "<string>",
"timestamp": "<string>",
"locale": "<string>",
"cause": {
"type": "ConnectionCompleted",
"token": "1234",
"status": {
"code": "200",
"message": "OK"
},
"result": {
"sendToDevice": {
"status": "SUCCESS"
}
}
}
}
ステップ3: Alexa for Apps V2スキルをテストする
Alexa for Apps V2開発者プレビュースキルをテストするには
- 開発者プレビュースキルをテストする方法については、ステップ3: Alexa for Apps V2スキルをテストするを参照してください。
関連トピック
- Alexa for Appsをカスタムスキルに追加する
- Alexa for Appsスキルマニフェストのリファレンス
- Alexa for Apps Skill Connectionsリクエストのリファレンス
- カスタムスキルとは
- Skill Connectionsとは
最終更新日: 2024 年 05 月 08 日