ウェブアプリゲームのAlexaスキル開発

ウェブアプリゲームの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インターフェースへの対応を追加するには

  1. 開発者コンソールを開き、コンフィギュレーションを行うスキルを探して編集をクリックします。
  2. ビルド＞インターフェースページに移動します。
  3. Alexa Web API for Gamesインターフェースを有効にします。このオプションを選択したら、スキルマニフェストにALEXA_PRESENTATION_HTMLを追加します。
  4. インターフェースを保存をクリックし、対話モデルを再ビルドするためにモデルをビルドをクリックします。

デバイスが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の両方に対応するようスキルのコンフィギュレーションを行います。

また、必ずしもデバイスがこれら両方のインターフェースに対応しているとは限りません。関連するディレクティブを送信する前に、使用するインターフェースにデバイスが対応していることを確認してください。

このページは役に立ちましたか？

最終更新日: 2020 年 11 月 26 日