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

Note: Sign in to the developer console to build or publish your skill.

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 – オーディオライブラリ

注： HTMLアプリケーションはゲームである必要があります。その他の種類のアプリをAlexa Web API for Gamesで使用することはできません。

Alexa Web API for Gamesを使った開発

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

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

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

重要： デバイスのWeb APIランタイムにより、ウェブアプリでの特定のブラウザ機能の使用が制限されます。詳細については、HTML環境での制限を参照してください。

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

重要： 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がスキルに送信されます。

重要： スキルでは1秒に2つ以上のメッセージを送信できません。アプリがこの制限を超えた場合の制限エラーは、alexa.skill.sendMessage()でオプションのコールバックを使用してキャッチします。MessageSendResponseは、コールバックにエラー429（Too Many Requests）を返します。

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

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

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

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

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

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

最終更新日: 2022 年 06 月 30 日

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

Alexa Web API for Gamesを使った開発

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

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

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

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

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

ベストプラクティス

HTML環境での制限

Alexaオブジェクト

Client

Capability

Microphone

AlexaReadyPayload

SendResponse

RateLimit

Alexaインターフェース

capabilities

create

performance

onMessage

sendMessage

関連トピック