Web API for Gamesを使用したウェブアプリの開発

Web API for Gamesを使用したウェブアプリの開発

Alexa Web API for Gamesを利用すると、JavaScript、HTML5、CSS、ウェブオーディオを使って、音声対応ゲームを作成できます。グラフィックスやオーディオの管理に、よく知っているテクニックやツールを使用できます。HTMLとCSS、Canvas、SVG、WebGLを使って、アニメーションを追加できます。開発者は、さまざまなJavaScriptゲームフレームワークやライブラリの中から選択できます。以下は、いくつかの一般的なオプションです。

  • Phaser – CanvasとWebGL用のゲームフレームワーク
  • Pixi.js – WebGLを使ったゲームフレームワークと2Dグラフィックス
  • three.js – WebGLを使った3Dライブラリとアプリフレームワーク
  • Howler.js – オーディオライブラリ

Alexa Web API for Gamesを使った開発

Alexa Web API for Gamesを使ってゲームを作成するには、ウェブアプリがブラウザに表示され、ユーザーと対話できる必要があります。

インターネットからアクセス可能なHTTPSエンドポイントでウェブアプリと関連アセットをホストします。ウェブサーバーが有効で信頼できるSSL証明書をAlexaデバイスに提示する必要があります。遅延を減らしてゲームエクスペリエンスを向上させるには、ストレージソリューションと、世界中にエッジロケーションを持つコンテンツ配信ネットワークを使用します。たとえば、Amazon S3、Amazon CloudFront、HTTPSをホストするウェブサーバーなどです。

ウェブアプリまたはスキルのバックエンドにゲームロジックを含めるようにゲームをデザインできます。スキルと通信するには、アプリでAlexa JavaScript APIを使います。

Alexa JavaScriptライブラリをアプリに追加する

Alexa JavaScriptライブラリをロードするには、次の例のように、HTMLページのscriptタグにURLを含めます。

クリップボードにコピーされました。

<head>
      <script src="https://cdn.html.games.alexa.a2z.com/alexa-html/latest/alexa-html.js"></script>
</head>

Alexaクライアントを作成する

アプリは、Alexa Clientオブジェクトを使用して、デバイスおよびスキルと通信します。リクエストを処理する準備ができるまでクライアントを使用できないようにするには、静的ファクトリ関数を使用してAlexa Clientオブジェクトを作成します。この関数を各ページで1回呼び出します。

以下は、Alexa Clientオブジェクトの初期化の例です。

クリップボードにコピーされました。

var alexaClient;
Alexa.create({version: '1.1'})
     .then((args) => {
         const {
             alexa,
             message
         } = args;
        alexaClient = alexa;
        document.getElementById('debugElement').innerHTML = 'Alexaの準備ができました';
     })
     .catch(error => {
        document.getElementById('debugElement').innerHTML = 'Alexaの準備ができていません';
     }); 
</div>

スキルとウェブアプリとの通信

ユーザーがウェブアプリを操作しているときに、デバイスで実行されているウェブアプリとスキルのバックエンドとの間でメッセージを送信できます。この通信により、Alexaスキルは、特定のゲームロジックを保留にしたり、ローカル入力を送信したり、音声入力を受信したり、スキル内課金を組み込んだりすることができます。スキルでは、Alexa.Presentation.HTML.MessageディレクティブとAlexa.Presentation.HTML.HandleMessageイベントを使用して、ウェブアプリと通信します。

ウェブアプリでは、Alexa ClientおよびsendMessageとonMessageのJavaScript APIを使用してスキルと通信します。Alexa JavaScript APIを使うと、ウェブアプリで追加のハンドラーを登録して、Alexa音声の開始や終了といったその他のイベントを待機できます。これらのハンドラーを使って、ボタンの押下といった画面上のイベントと音声コマンドとの間のフローを構築できます。詳細については、ウェブアプリに音声操作と対話を追加するを参照してください。

ウェブアプリセッションを終了する

デバイスにゲームが表示されると、以下のいずれかのアクションが起こるまで、アプリは画面上でアクティブのままになります。

  • ユーザーがスキルセッションまたはゲームを終了した。
  • スキルがセッションを終了した。
  • スキルがAlexa.Presentation.HTML以外のインターフェースを使用した。

スキルとウェブアプリのテスト

開発用コンピューターでは、Chrome DevToolsを使ってAmazon Fire TVデバイスで実行されるスキルのウェブアプリをデバッグできます。詳細については、Web App TesterとDevToolsの使用を参照してください。

ベストプラクティス

ウェブサイト構築に関する一般的なベストプラクティスを、Alexaスキルと共に使用するウェブアプリに適用します。

  • ストレージソリューションとコンテンツ配信ネットワークを使用して、世界中のサーバーのうち、プレイヤーの所在地に近いサーバーでアセットの保存やキャッシュを行います。ウェブサーバーをエッジロケーションに維持することで、プレイヤーのエクスペリエンスに影響を与えるレイテンシーが大幅に低減されます。
  • WebViewブラウザが起動したときに、デバイスに最初に白色のフラッシュを表示します。フラッシュを制御することはできません。
  • アセットのロード中に背景色またはページスタイルを設定し、ゲームを使用する準備ができていることをユーザーに知らせます。
  • 点滅を防ぐために、ロード中およびアプリを使用する準備ができたときは背景色を一定に保ちます。
  • キャッシュ制御ヘッダーに従ってデバイスにアセットをキャッシュします。開発中にキャッシュについて考えておき、本番環境で使用します。
  • プレイヤーは、操作によっては音声を好む場合も、タッチを好む場合もあります。コアのゲーム操作を行う音声対話に対応するタップ対話を追加することを検討します。ウェブアプリのドキュメントオブジェクトモデル（DOM）イベントの大半は完全に制御可能です。
  • ウェブアプリまたはスキルのバックエンドにゲームロジックを含めるようにゲームをデザインします。スキルと通信するには、アプリでAlexa JavaScript APIを使います。
  • ウェブオーディオを使用すると、会話の複数ターンにわたってサウンドの再生を動的にコントロールできます。
  • ウェブオーディオを使用する場合は、デフォルトで音量を下げないことをお勧めします。プレイヤーが話すときに邪魔にならないように、音声イベントをリッスンして音量を下げるようにします。また、読み上げイベントをリッスンして、Alexaの読み上げが再生されているときにウェブオーディオの音量を下げることもできます。
  • スキルがWeb API for GamesとAlexa Presentation Language（APL）の両方を使用する場合は、ゲームで必要な状態情報を必ず保存するようにします。APLとウェブアプリの両方をデバイスで同時に実行することはできません。APLからウェブアプリに移るたびに、ウェブアプリに起動レイテンシーが発生します。

サンプルプロジェクトについては、github.comのMy Cactus Simulation Alexa Gameを参照してください。

HTML環境での制限

デバイス上のWeb APIランタイムは、次のブラウザ機能を無効にします。

  • コンテンツURLアクセス
  • ブラウザの位置情報
  • ファイルfile://</path>からのURLの読み込み
  • File API
  • ローカルストレージ
  • 非HTTPアセット／URI（HTTPSは必須）
  • Web Speech APIを使ったSpeechRecognition
  • Web SQL Database
  • JavaScriptを使ったalert()、prompt()、confirm()
  • getUserMedia（カメラ、マイク）

デバイスのWeb APIランタイムでは、次のブラウザ機能を使用できます。

  • メディア自動再生
  • Cookie
  • フォームデータ
  • 履歴

ランタイムは、スキルセッションの終了時にCookie、フォームデータ、履歴をクリアします。

Alexaオブジェクト

Client

Alexa Clientオブジェクトは、スキルやデバイスと通信するためのインターフェースを提供します。詳細については、Alexa JavaScript APIを参照してください。

Clientオブジェクトの詳細

プロパティ 説明 型
capabilities デバイスの機能です。 Capabilityオブジェクト
performance デバイスで使用可能なメモリを取得するためのインターフェースを提供します。
詳細については、performanceを参照してください。		 Performanceオブジェクト
skill スキルと通信するためのインターフェースを提供します。
詳細については、onMessageおよびsendMessageを参照してください。		 Skillオブジェクト
speech Alexa音声イベントを受信するためのインターフェースを提供します。
詳細については、Alexaにユーザーと対話させるを参照してください。		 Speechオブジェクト
version Alexaクライアントのバージョンです。
バージョンを指定しないと、最新バージョンが使用されます。
voice ユーザーの発話を受信するマイクをデバイスで開くためのインターフェースを提供します。
詳細については、JavaScript APIを使ってユーザーに何か言うようプロンプトを出すを参照してください。		 Voiceオブジェクト

Capability

Capabilityオブジェクトは、デバイスについての情報を提供します。

Capabilityオブジェクトの詳細

プロパティ 説明 型
microphone デバイス上のマイクの機能です。 Microphoneオブジェクト

Microphone

Microphoneオブジェクトは、デバイスについての情報を提供します。

Microphoneオブジェクトの詳細

プロパティ 説明 型
supportsPushToTalk ユーザーがデバイスの実際のボタンを押したり、リモコンを使用したりしたときに、マイクをアクティブにするかどうかを指定します。 boolean
supportsWakeWord ユーザーがウェイクワードを言ったときにマイクをアクティブにするかどうかを指定します。
trueにすると、ウェブアプリはVoiceインターフェースを使用してマイクイベントを開始できます。		 boolean

AlexaReadyPayload

成功したcreateの呼び出しのPromise解決結果です。

AlexaReadyPayloadの詳細

プロパティ 説明 型
alexa 初期化され、準備が完了したAlexaクライアントです。 Alexa Clientオブジェクト
message スキルによって提供される起動情報です。
StartディレクティブのdataプロパティからのJSON値です。		 任意

SendResponse

コールバック関数は、SendResponseオブジェクトのsendMessageインターフェースに対する応答を受け取ります。詳細については、sendMessageを参照してください。

SendResponseの詳細

プロパティ 説明 型
statusCode スキルから受信したメッセージのステータスを示すHTTPステータスコードです。
有効値： 200（OK）、401（Unauthorized）、429（Too Many Requests）、500（Internal Server Error/Unknown Error）		 整数
reason statusCodeプロパティで検出されたエラー値について説明するテキスト文字列です。 文字列
rateLimit ウェブアプリからの送信リクエスト数の制限です。 RateLimitオブジェクト

RateLimit

RateLimitオブジェクトは、ウェブアプリからの送信リクエスト数の制限を定義します。

RateLimitの詳細

プロパティ 説明 型
maxRequestsPerSecond 1秒あたりの最大許容リクエスト数です。 整数
remainingRequests レート制限がメッセージをブロックするまでに配信される可能性があるリクエストの数です。
0は、これ以上のメッセージを許可しないことを示します。		 整数
timeUntilNextRequestMs アプリが次のメッセージを送信できるようになるまでの時間（ミリ秒）です。 整数
timeUntilResetMs remainingRequestsとmaxRequestsPerSecondが等しくなるまでの時間（ミリ秒）です。 整数

Alexaインターフェース

capabilities

capabilitiesインターフェースを使ってデバイスの機能を確認します。

次の例は、Microphoneオブジェクトを使ってプッシュトゥトーク機能の確認をしています。

クリップボードにコピーされました。

    if (alexaClient.capabilities.microphone.supportsPushToTalk) {
        // ユーザーにマイクボタンを押すようプロンプトを出します
        ...
    };

create

次に示すように、createインターフェースを使用してデバイスでAlexaへの接続を確立します。createはsuccess関数を呼び出し、AlexaReadyPayloadによって実行されるPromiseを返すか、promiseを拒否してfailure関数を呼び出します。

クリップボードにコピーされました。

let client;
Alexa.create({version?: "1.1", messageProvider?: new Alexa.DefaultMessageProvider()})
.then(success)
.catch(failure);

createインターフェースの詳細

プロパティ 説明 型
version （オプション）Alexaクライアントのバージョンです。
無効なバージョンをリクエストすると、no-such-versionエラーコードで拒否されます。		 文字列
messageProvider （オプション）シミュレーションまたはテストに使用します。 MessageProviderオブジェクト
AlexaReadyPayload AlexaReadyPayloadオブジェクトで実行されます。 promise
success create()が成功すると呼び出されます。 successメソッド
failure create()が失敗すると呼び出されます。 failureメソッド

createメソッドは、次に示すように、AlexaReadPayloadでAlexaクライアントが正常に作成されると、success関数を呼び出します。messageには、スキルから送信されたデータが含まれています。

クリップボードにコピーされました。

const success = function(result) {
    const {alexa, message} = result;
    // Alexaクライアントの初期化が完了した後のアクション
};

createメソッドは、次に示すように、Alexaクライアントの作成に失敗するとfailure関数を呼び出します。

クリップボードにコピーされました。

const failure = function(error) {
    const {
        code,
        message
    } = error;
    // 初期化に失敗した場合のアクション
};

failureインターフェースの詳細

プロパティ 説明 型
code Alexa clientの作成に失敗した理由を示すエラーコードです。
有効値：no-such-version、unauthorized-access、too-many-requests、unknown 		文字列
message codeプロパティで検出されたエラー値について説明するテキスト文字列です。 文字列

performance

performanceインターフェースを使って、デバイスで使用可能なメモリを取得します。このインターフェースは、開発中にすべての種類のデバイスでアセットを最適化したり、デバッグしたりするのに役立ちます。

以下は、使用可能なメモリのログ記録の例です。

クリップボードにコピーされました。

alexaClient.performance.getMemoryInfo().then((memInfo) => {
    // memInfoをログに記録します
});

onMessage

alexaClient.skill.onMessageを使用して、スキルから送信されたメッセージを処理するリスナーを登録します。リスナーに送信されるメッセージは、アプリがスキルに送信するメッセージとは無関係です。スキルから送信されるmessageの形式は、アプリとスキルの間で一致します。アプリが登録できるコールバックは1つだけです。このためコールバック関数には、message内で提供されるデータに基づいて複数のメッセージを処理するロジックを含める必要があります。リスナーを登録するまで、メッセージを受信できません。起動時にスキルからの情報が必要な場合は、成功したcreateインターフェースで返されるmessageを使用します。

以下は、messageReceivedCallbackというリスナー関数を登録する方法の例です。

クリップボードにコピーされました。

// スキルからのメッセージを受信するリスナーを登録する
alexaClient.skill.onMessage(messageReceivedCallback);

// リスナーを実装する
const messageReceivedCallback = function(message) {
    // スキルからのメッセージ（JavaScriptオブジェクト）を処理する
};

onMessageインターフェースの詳細

プロパティ 説明 型
messageReceivedCallback 受信したmessageを処理するために使用されるコールバック関数です。 関数
message スキルによって形式が設定された任意のデータです。
HandleMessageディレクティブのdataプロパティのJSON値です。		 任意

sendMessage

ウェブアプリからスキルにメッセージを送信するには、alexaClient.skill.sendMessageインターフェースを使用します。このインターフェースは、データペイロードと、応答を処理するオプションのコールバックを受け取ります。APIにより、Alexa.Presentation.HTML.Messageがスキルに送信されます。

以下は、スキルにメッセージを送信する方法の例です。

クリップボードにコピーされました。

// スキルにメッセージを送信する
alexaClient.skill.sendMessage(message, messageSentCallback);

// SendMessageの結果を確認する
const messageSentCallback = function(sendResponse) {
    const {
        statusCode,
        reason,
        rateLimit,
    } = sendResponse;
    // 応答コードを処理する
};

sendMessageインターフェースの詳細

プロパティ 説明 型
message アプリによって形式が設定された任意のデータです。
このJSON値はMessageディレクティブのdataプロパティで送信されます。		 任意
messageSentCallback sendMessageの結果を処理するために使用されるコールバック関数です。 関数