ウェブアプリゲームのAlexaスキル開発
Alexa Skills Kitディレクティブを使用して、音声対応ゲームのスキルを開発できます。ゲームロジックの全部または一部をスキルに含めるようにゲームをデザインします。ウェブアプリの開始や、ゲーム全体での指示とデータの送信には、HTMLディレクティブを使用します。Alexaサービスとの通信には、通常のAlexaディレクティブを使用します。Alexa Web API for Gamesの詳細については、Alexa Web API for Gamesについてを参照してください。
HTMLディレクティブに対応するようスキルのコンフィギュレーションを行う
スキルでHTMLディレクティブを有効にするには、ASKコマンドラインインターフェース(CLI)または開発者コンソールを使用して、スキルマニフェストにALEXA_PRESENTATION_HTML
インターフェースを追加する必要があります。スキルマニフェストの詳細については、スキルマニフェストのスキーマを参照してください。
CLIを使用してインターフェースを追加する
HTMLディレクティブに対応するようスキルのコンフィギュレーションを行うには、スキルマニフェストJSONファイルのmanifest.apis.custom.interfaces
にALEXA_PRESENTATION_HTML
インターフェースを追加します。
次の例は、HTMLインターフェースのコンフィギュレーションが行われたスキルマニフェストを示しています。
"apis": {
"custom": {
"interfaces": [
{
"type": "ALEXA_PRESENTATION_HTML"
}
]
}
}
マニフェストファイルを保存したら、Alexa Skills Kitコマンドラインインターフェースを使用して、変更後のマニフェストをデプロイします。
開発者コンソールでインターフェースを追加する
開発者コンソールでスキルマニフェストのコンフィギュレーションを行うこともできます。
HTMLインターフェースへの対応を追加するには
- 開発者コンソールを開き、コンフィギュレーションを行うスキルを探して編集をクリックします。
- ビルド>インターフェースページに移動します。
- Alexa Web API for Gamesインターフェースを有効にします。このオプションを選択したら、スキルマニフェストに
ALEXA_PRESENTATION_HTML
を追加します。 - インターフェースを保存をクリックし、対話モデルを再ビルドするためにモデルをビルドをクリックします。
デバイスがHTMLディレクティブに対応していることを確認する
すべてのデバイスがAlexa.Presentation.HTML
ディレクティブに対応しているわけではありません。スキルがウェブアプリを起動する前に、Alexa.Presentation.HTML
のLaunchRequest
、IntentRequest
、(スキル内課金の)Connections.Response
を調べて、デバイスがHTMLディレクティブに対応しているかどうかを確認します。デバイスがHTMLに対応している場合は、Start
ディレクティブで応答してウェブアプリをロードします。
次の例は、HTMLに対応するcontext.System.device.supportedInterfaces
オブジェクトを示しています。
"device": {
"deviceId": "amzn1.ask.device.XXXX",
"supportedInterfaces": {
"Alexa.Presentation.HTML": {
"runtime": {
"maxVersion": "1.1"
}
}
}
}
const supportedInterfaces = Alexa.getSupportedInterfaces(handlerInput.requestEnvelope);
const htmlInterface = supportedInterfaces['Alexa.Presentation.HTML'];
if(htmlInterface !== null && htmlInterface !== undefined) {
// Startディレクティブを追加する。
}
HTMLインターフェースへの対応は、APLへの対応とは別です。APLに対応しているデバイスでも、HTMLに対応していない場合があります。HTMLサポートの確認は別途行ってください。
ウェブアプリを起動する
ウェブアプリを起動しようとしていることをAlexaサービスに通知するには、応答本文でAlexa.Presentation.HTML.Start
ディレクティブを使用します。このディレクティブに、デバイスにロードするウェブページのHTTPSリンクを含めます。Alexa搭載デバイスでこのページを開くには、SSL証明書が有効である必要があります。
詳細については、Alexa.Presentation.HTMLインターフェースを参照してください。
以下は、Startディレクティブの例です。
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "話すプレーンテキストの文字列",
"playBehavior": "REPLACE_ENQUEUED"
},
"directives": [
{
"type": "Alexa.Presentation.HTML.Start",
"data": {
"arbitraryDataKey1": "初期起動情報"
},
"request": {
"uri": "https://mydomain.example.com/mygame.html",
"method": "GET"
},
"configuration": {
"timeoutInSeconds": 300
}
}
],
"shouldEndSession": false
}
スキルがウェブアプリを起動するディレクティブを送信する際、応答にはfalse
または未定義のshouldEndSession
を含める必要があります。この設定により、スキルセッションは開いたままになり、ユーザーは画面上のウェブアプリと対話できます。
shouldEndSession
がfalse
のとき、Alexaは指定されたoutputSpeech
を読み上げてから、数秒間マイクを有効にしてユーザーの応答を待機します。shouldEndSession
が未定義の場合、Alexaは指定されたoutputSpeech
を読み上げますが、マイクは有効にしません。セッションは開いたままになります。
画面上でウェブアプリがアクティブな間は、セッションは開いたままです。
ウェブアプリと通信する
Alexaスキルは、デバイスで実行されているウェブアプリにメッセージを送信できるため、スキル側でゲームロジックの全部または一部を保持できます。スキルがIntentRequest
を受信した場合や、ウェブアプリからのメッセージへの応答として、アプリにメッセージを送信することができます。スキルがウェブアプリからメッセージを受信したら、ディレクティブとAlexaからの出力音声で応答できます。
アプリとの通信には、Alexa.Presentation.HTML.HandleMessage
ディレクティブを使用します。このディレクティブでは、必要に応じてmessage
の形式を設定することで、ウェブアプリへの独自のインターフェースを柔軟に定義できます。詳細については、Alexa.Presentation.HTMLインターフェースを参照してください。
以下は、スキルから任意の状態データを送信する方法の例です。
{
"type": "Alexa.Presentation.HTML.HandleMessage",
"message": {
"players": 1,
"myGameState": "レベル2",
"speech": "次のレベルに進みますか?"
}
}
スキルは、IntentRequest
を処理するのと同じように、受信したAlexa.Presentation.HTML.HandleMessage
ディレクティブを処理できます。以下は、メッセージハンドラーの例です。
const myWebAppLogger = {
canHandle(handlerInput) {
return Alexa.getRequestType(handlerInput.requestEnvelope) === "Alexa.Presentation.HTML.Message";
},
handle(handlerInput) {
const messageToLog = handlerInput.requestEnvelope.request.message;
console.log(messageToLog);
return handlerInput.responseBuilder.getResponse();
}
}
ウェブアプリを終了する
デバイスにウェブアプリが表示されると、アプリは画面上でアクティブになります。アプリは、次のアクションで終了します。
- スキルが
Alexa.Presentation.HTML
以外のインターフェースからディレクティブを返した場合。このアクションによってウェブアプリは終了しますが、スキルセッションが終了するとは限りません。 - スキルの応答で
shouldEndSession
がtrue
に設定されていた場合。 - ユーザーが「アレクサ、終了して」と言ってスキルを終了した場合。
- ユーザーが「アレクサ、ホームに戻って」と言ってスキルを終了した場合。
- ユーザーがウェブアプリとの対話を終了した後、アイドル状態になった場合。
timeoutInSeconds
(最大30分)が経過すると、スキルセッションは終了します。一部のデバイスではコンフィギュレーションを行ったタイムアウト値を無視するか、小さい値のコンフィギュレーションを行うことができます。
たとえば、スキルによってAlexa.Presentation.APL.RenderDocumentが返されると、デバイスはウェブアプリを終了し、提供されたドキュメントをインフレートさせます。すると、スキルが別のAlexa.Presentation.HTML.Start
ディレクティブを送信してウェブアプリを再起動するまで、スキルセッションのライフサイクルが継続します。ライフサイクルについては、画面付きデバイスがスキルセッションに与える影響を参照してください。
同じスキルでAlexa Web API for GamesとAPLを併用する
1つのゲームで、Alexa Web API for GamesとAPLの両方を使うことができます。ただし、同じ画面に2つを混在させることはできません。応答ごとに、ウェブアプリかAPLドキュメントのどちらかを表示できます。
ウェブアプリが既に画面に表示されている場合に、Alexa.Presentation.APL.RenderDocument
またはExecuteCommands
ディレクティブを送信するとアプリが終了します。ゲームで必要な状態情報は必ず保存するようにしてください。
APLとWeb API for Gamesでは、Alexa.Presentation
名前空間内の異なるインターフェースを使用します。併用するには、Alexa.Presentation.APL
とAlexa.Presentation.HTML
の両方に対応するようスキルのコンフィギュレーションを行います。
また、必ずしもデバイスがこれら両方のインターフェースに対応しているとは限りません。関連するディレクティブを送信する前に、使用するインターフェースにデバイスが対応していることを確認してください。
関連トピック
- スキルのビルド(開発者コンソール)
- スキルリソース操作(スキル管理API)/スキル情報の取得
- スキルリソース操作(スキル管理API)/既存スキルの更新
- サービスインターフェースのリファレンス
- ゲーム向けWeb API Extensionsの概要
最終更新日: 2020 年 11 月 26 日