チュートリアル: Alexa for Appsをカスタムスキルに追加する
Alexa for Appsをカスタムスキルに追加するには、アプリとウェブサイトのメタデータをスキルマニフェストに追加し、ディープリンクを送信するスキルのエンドポイントを編集して、スキルのテストと公開を行う必要があります。このチュートリアルでは、「シティガイド」カスタムスキルを例にとって、Alexa for Appsを追加する方法を説明します。
この機能の概要については、Alexa for Appsとはを参照してください。
前提条件
スキルにAlexa for Appsを追加するには、以下の項目が必要です。
- 開発したAlexaカスタムスキル
- ディープリンクを利用可能なiOSアプリ、Androidアプリ、ウェブサイトのいずれか
Alexa for Appsをカスタムスキルに追加する手順の概要
Alexa for Appsは、以下の手順でスキルに追加します。
- ステップ1: アプリとウェブサイトのメタデータをスキルマニフェスト(skill.json)に追加する
- ステップ2: ディープリンクを送信するスキルのエンドポイントを編集する
- ステップ3: スキルをテストして公開する
ステップ1: アプリとウェブサイトのメタデータをスキルマニフェスト(skill.json)に追加する
このステップでは、スキルマニフェストでスキルのリンク先となるアプリやウェブサイトを指定し、それぞれの情報を追加します。
get-skill-manifest
とupdate-skill-manifest
のCLIコマンドを使って既存スキルのマニフェストを直接取得して更新する代わりに、スキル全体のクローンを作成できます。クローンは、ask clone
(ASK CLI v1)、ask init
(ASK CLI v2)のいずれかのコマンドで作成できます。更新による問題を回避するため、初めて既存スキルのクローンを作成する際には必ずプロファイル名(ask init -p <profile-name>
)を指定してください。アプリとウェブサイトのメタデータをスキルマニフェストに追加する
- クイックスタート: Alexa Skills Kitコマンドラインインターフェース(ASK CLI)の手順に従ってASK CLIをインストールします。
-
カスタムスキルのスキルマニフェストを
skill.json
という新しいファイルにダウンロードするには、次のようにget-skill-manifest
CLIコマンドを使用します。ask smapi get-skill-manifest -s <skill-id> -g <stage> > skill.json
- スキルマニフェストでAlexa for Appsのサポートを宣言するには、以下の例のように、
interfaces
配列(manifest.apis.custom.interfaces
)のtype
プロパティにAPP_LINKS
の値を追加します。{ "type":"APP_LINKS" },
- スキルのリンク先アプリのメタデータをスキルマニフェストに追加するには、
manifest.apis.custom.appLink
の下にappLink
オブジェクトを追加します。以下の、ドイツ語にローカライズした名前のシティガイドスキルの例を参照してください。注:localizedNames
値を指定できるのは、スキルマニフェストのmanifest.publishingInformation.locales
セクションに含まれるロケールのみです。重要: 実際のスキルマニフェストでは、「ALEXA FOR APPSの追加開始」の行は省略します。{ "manifest": { "apis": { "custom": { "endpoint": { ... }, "interfaces": [ { "type": "APP_LINKS" } ], ================== ALEXA FOR APPSの追加開始 ================== "appLink": { "linkedApplications": [ { "friendlyName":{ "default":"シティガイド", "localizedNames": [ {"locale":"de-DE", "name":"Stadtführer"} ] }, "catalogInfo": { "type": "IOS_APP_STORE", "identifier": "id123456789" }, "customSchemes": ["cityguide://","ctgd://"], "domains": ["cityguide.com","ctgd.com"] }, { "friendlyName":{ "default":"シティガイド", "localizedNames": [ {"locale":"de-DE", "name":"Stadtführer"} ] }, "catalogInfo": { "type": "GOOGLE_PLAY_STORE", "identifier": "com.cityguide.android.ctgdmobile" }, "customSchemes": ["cityguide://","ctgd://"], "domains": ["cityguide.com","ctgd.com"] } ] },
-
ユーザーにモバイルデバイスでのスキルの使い方を知ってもらうために、スキルの
description
アトリビュートやexamplePhrases
アトリビュートを更新することを検討してください。これらのアトリビュートは、スキルマニフェストのmanifest.publishingInformation.locales
セクションで直接更新できます。また、この情報はスキルをテストして公開する前に、いつでもAlexa開発者コンソールから更新できます。スキルがアクセスできるモバイルアプリや、モバイルで使えるサンプル発話についての情報をユーザーに知らせるようにします。スキルがモバイルデバイスでのみ動作する場合は、これをユーザーに伝えてください。以下は、シティガイドスキルでこれらのアトリビュートを更新する方法の例です。{ "locales": { "ja-JP": { "name": "シティガイド", "smallIconUri": "<s3 link>", "largeIconUri": "<s3 link>", "summary": "シティガイドでさまざまなスポットを見つけましょう。", "description": "モバイルデバイスのシティガイドならすばやく検索できます。 「アレクサ、シティガイドでタピオカティーを探して」と言ってみましょう。 Alexaに徒歩での行き方をたずねると、アプリのライブ追跡マップにすぐにアクセスできます。", "examplePhrases": [ "アレクサ、シティガイドで近くのコーヒーショップを探して", "アレクサ、シティガイドでバスの時刻表を見せて", "アレクサ、シティガイドでお気に入りランドマークへの徒歩での行き方を教えて" ], "keywords": [] }, } }
発話の競合を最小限にするには、サポートされている呼び出しフレーズを参考にサンプルフレーズを決定し、音声でスキルをテストしてください。
- 更新したカスタムスキルのスキルマニフェストをアップロードするには、次のように
update-skill-manifest
CLIコマンドを使います。ask smapi update-skill-manifest -s <skill-id> -g <stage> --manifest <manifest>
ステップ2: ディープリンクを送信するスキルのエンドポイントを編集する
このステップでは、スキルが受け取ったリクエストを確認し、Alexa for Appsをサポートするデバイスからのものかどうかを判断します。また、リクエスト元のプラットフォーム(Android、iOS)とロケールについても確認します。
ディープリンクを送信するスキルのエンドポイントを編集する
- ユーザーのデバイスがAlexa for Appsをサポートすることを確認するには、スキルで
context.System.device.SupportedInterfaces
オブジェクトにAppLink
フィールドがあるかどうかを確認します。 -
Androidデバイス、iOSデバイスのどちらがリクエスト元であるかを判断するには、スキルで
context.AppLink.supportedCatalogTypes
フィールドを確認します。リクエスト元がiOSデバイスの場合、このフィールドに["IOS_APP_STORE"]
の値が設定されています。"AppLink": {"supportedCatalogTypes": ["IOS_APP_STORE"]},
リクエスト元がAndroidデバイスの場合、このフィールドに
["GOOGLE_PLAY_STORE"]
の値が設定されています。"AppLink": {"supportedCatalogTypes": ["GOOGLE_PLAY_STORE"]},
以下は、iOSデバイスからリクエストを受信するスキルの例です。
重要: 実際のスキルでは、「ALEXA FOR APPSの追加開始」、「ALEXA FOR APPSの追加終了」の行は省略します。{ "version": "1.0", "session": {...}, "context": { "System": { "device": { "deviceId": "string", "supportedInterfaces": { "AudioPlayer": {...}, ================== ALEXA FOR APPSの追加開始 ================== "AppLink": {...}, ================== ALEXA FOR APPSの追加終了 ==================== } }, "application": { "applicationId": "amzn1.ask.skill.[unique-value-here]" }, "user": {...}, "apiEndpoint": "https://api.amazonalexa.com", "apiAccessToken": "AxThk..." }, "AudioPlayer": {...}, ================== ALEXA FOR APPSの追加開始 ================== "AppLink": { "supportedCatalogTypes": ["IOS_APP_STORE"] }, ================== ALEXA FOR APPSの追加終了 ==================== }, "request": {...}
- スキルがロケールごとに異なるリンクを送信する場合は、
handlerInput.requestEnvelope.request.locale
でリクエスト元デバイスのロケールを判断する必要があります。注: スキルは、スキルを配信しているロケールからのリクエストのみを受信します。多言語に対応するスキルを開発するを参照してください。ヒント: ロケールはすべてのリクエストで利用できるため、どのディープリンクを送信するかを判断するのにロケールを使うことを検討してください。ディープリンクがロケールではなく国によって異なる場合、ユーザーの国にアクセスする権限をユーザーにリクエストする必要があります。このリクエストを実行する方法の1つは、ユーザーがAlexaに登録したデバイスアドレスにアクセスすることです。詳細については、所在地情報を使用してスキルを拡張するを参照してください。ユーザーに紐づいたアプリストアを反映しているとは限りませんが、ユーザーのリアルタイムの位置情報にアクセスすることもできます。リアルタイム位置情報サービスについての詳細は、 Alexaスキル向け位置情報サービスを参照してください。 - Alexa for Appsは、ユニバーサルリンク、カスタムスキーム、Androidインテント、Android Package Managerアプリ起動のリンクをサポートします。詳細については、ディープリンクの種類を参照してください。アプリやウェブサイトへのディープリンクを送信するには、Skill Connectionsリクエストの応答本文に
Connections.StartConnection
ディレクティブが必要です。詳細については、Skill Connectionsリクエストペイロードの例を参照してください。 -
Skill Connectionsリクエストが完了すると、スキルは、プライマリのディープリンクアクションとフォールバックの成功/失敗、および失敗の場合は失敗の理由を示す応答を受け取ります。スキルは常に、
ConnectionCompleted
とSessionResumedRequest
を処理する必要があります。成功の場合、スキルはモバイルアプリやデバイスで残りの対話が行えるようにクリーンアップと終了の処理を実行できます。プライマリとフォールバックが成功しなかった場合やプライマリがフォールバックを試行することなくエラーになった場合は、ユーザーが音声でリクエストを完了できるようスキルでの対話を続けるという選択肢があります。以下は、応答の例です。
{ "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応答のリファレンスを参照してください。
注: 子ども向けスキルは現在、ディープリンクを利用できません。子ども向けスキルでAlexa for Appsのご利用を検討されている場合は、alexaforapps-help@amazon.comまでお問い合わせください。
デフォルトでは、安全上の理由から、運転中のユーザーのディープリンクリクエストは失敗します。ユーザーが運転中にリクエストを行っても、スキルはスキルリクエストオブジェクトのAppLink
プロパティを受け取りません。ただし、それでもスキルがディープリンクリクエストを送信する場合は、INVALID_STATE
エラー応答を受け取ります。運転中のユーザーにカスタマイズした音声応答を提供する場合は、スキルリクエストオブジェクトのAutomotive
プロパティを検討してください。ハンズフリーでの操作や通話を支援するアプリの使用など、運転中のシナリオにスキルを登録する必要があるとお考えの場合、スキルIDと事例を添えてalexaforapps-help@amazon.comまでお問い合わせください。
ステップ3: スキルをテストして公開する
スキルのテスト
現時点では、Alexa開発者コンソールのテストページは、スキルリクエストでAppLink
オブジェクトを送信しません。エンドツーエンドのテストでは、スキルにアクセスできる開発者またはベータアカウントに接続されたモバイルデバイスでテストを実施してください。
次の3つのいずれかの方法を使って、どのモバイルデバイスでもスキルをテストできます。
- Alexa搭載スマートフォンを使用する。
- Alexaモバイルアクセサリ(Echo Budsなど)を使用する。
- Alexaモバイルアプリから直接テストする。
Alexaモバイルアプリで、ビルトインのウェイク機能を使ったリクエストやAlexaアイコンのタップによってテストすることができます。
テスト項目は次のとおりです。
- アプリ固有のアクションを含む、エンドツーエンドの事例が想定どおりに動作するかどうかをテストします。
- デバイスのロック/ロック解除をテストします。
- スキルがサポートするさまざまなロケールでテストします。
- アプリがインストールされていないフォールバックシナリオをテストします。
- ディープリンクが失敗した場合の復旧シナリオをテストします(サポートされていない種類のデバイスなど)。ディープリンクが失敗しても、スキルがユーザーとの対話を続行できることを確認します。
スキルの認定と公開
マニフェストをアップロードし、Lambda関数のランタイムを変更して、モバイルデバイスでのテストを完了したら、スキルを公開(再公開)できます。スキルの認定と公開は、ASK CLIのsubmit-skill-for-certification
コマンドで実行できます。詳細については、スキルの認定と公開を参照してください。また、このステップをAlexaコンソールで行うこともできます。
以下は、submit-skill-for-certification
コマンドの例です。
$ ask smapi submit-skill-for-certification -s {skillId}
submit-skill-for-certification
コマンドのデフォルトは、自動公開です。認定はするが公開はしないMANUAL_PUBLISHING
を指定した場合は、別途、publish-skill
サブコマンドを実行してリリース日を設定する必要があります。
ほかのカスタムスキル同様、基本的な検証を行い、Alexaスキルのポリシーに準拠していることを確認し、通常の公開フローに従って公開してください。Alexa for Appsの開発者プレビュー中に、マニフェストのAlexa for Appsセクションを変更した場合は、必ずskill.json
をalexaforapps-help@amazon.comに送信して検証(再検証)する必要もあります。