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ブラウザが起動したときに、デバイスに最初に白色のフラッシュを表示します。フラッシュを制御することはできません。
- アセットのロード中に背景色またはページスタイルを設定し、ゲームを使用する準備ができていることをユーザーに知らせます。
- 点滅を防ぐために、ロード中およびアプリを使用する準備ができたときは背景色を一定に保ちます。
- キャッシュ制御ヘッダーに従ってデバイスにアセットをキャッシュします。開発中にキャッシュについて考えておき、本番環境で使用します。
- ウェブアプリまたはスキルのバックエンドにゲームロジックを含めるようにゲームをデザインできます。アプリでAlexa JavaScript APIを使ってアプリの実行中にスキルと通信します。
- スキルがWeb API for GamesとAPLの両方を使用する場合は、ゲームで必要な状態情報を必ず保存するようにします。APLとウェブアプリの両方をデバイスで同時に実行することはできません。APLからウェブアプリに移るたびに、ウェブアプリの起動レイテンシーが発生します。
Alexaオブジェクト
Client
Alexa Client
オブジェクトは、スキルおよびデバイスと通信するためのインターフェースを提供します。詳細については、Alexa JavaScript APIを参照してください。
Clientオブジェクトの詳細
プロパティ | 説明 | 型 |
---|---|---|
capabilities |
デバイスの機能。 | Capabilityオブジェクト |
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値。 |
any |
SendResponse
messageSentCallback
関数は、SendResponse
オブジェクトのsendMessage
に対する応答を受け取ります。
SendResponseの詳細
プロパティ | 説明 | 型 |
---|---|---|
statusCode |
スキルから受信したメッセージのステータスを示すHTTPステータスコード。 有効値: 200(OK)、401(Unauthorized)、429(Too Many Requests)、500(Internal Server Error/Unknown Error) |
integer |
reason |
statusCode プロパティで検出されたエラー値について説明するテキスト文字列。 |
string |
rateLimit |
ウェブアプリからの送信リクエスト数の制限。 | rateLimit オブジェクト |
RateLimit
RateLimit
オブジェクトは、ウェブアプリからの送信リクエスト数の制限を定義します。
RateLimitの詳細
プロパティ | 説明 | 型 |
---|---|---|
maxRequestsPerSecond |
1秒あたりの最大許容リクエスト数。 | integer |
remainingRequests |
レートリミッタがメッセージをブロックするまでに配信される可能性があるリクエストの数。0は、これ以上のメッセージを許可しないことを示します。 | integer |
timeUntilNextRequestMs |
アプリが次のメッセージを送信できるようになるまでの時間(ミリ秒)。 | integer |
timeUntilResetMs |
remainingRequestsとmaxRequestsPerSecondが等しくなるまでの時間(ミリ秒)。 | integer |
Alexaインターフェース
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 エラーコードで拒否されます。 |
string |
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 |
string |
message |
code プロパティで検出されたエラー値について説明するテキスト文字列。 |
string |
onMessage
alexaClient.skill.onMessage
を使用して、スキルから送信されたメッセージを処理するリスナーを登録します。リスナーに送信されるメッセージは、アプリがスキルに送信するメッセージとは無関係です。スキルから送信されるmessage
の形式は、アプリとスキルの間で一致します。アプリが登録できるコールバックは1つだけです。このためコールバック関数には、message
内で提供されるデータに基づいて複数のメッセージを処理するロジックを含める必要があります。リスナーを登録するまで、メッセージを受信できません。起動時にスキルからの情報が必要な場合は、成功したcreate
インターフェースで返されるmessage
を使用します。
以下は、messageReceivedCallback
というリスナー関数を登録する方法の例です。
// スキルからのメッセージを受信するリスナーを登録する
alexaClient.skill.onMessage(messageReceivedCallback);
// リスナーを実装する
const messageReceivedCallback = function(message) {
// スキルからのメッセージ(JavaScriptオブジェクト)を処理する
};
onMessageインターフェースの詳細
プロパティ | 説明 | 型 |
---|---|---|
messageReceivedCallback |
受信したmessage を処理するために使用されるコールバック関数。 |
function |
message |
スキルによって形式が設定された任意のデータ。HandleMessageディレクティブのdata プロパティのJSON値。 |
any |
sendMessage
ウェブアプリからスキルにメッセージを送信するには、alexaClient.skill.sendMessage
インターフェースを使用します。このインターフェースは、データペイロードと、応答を処理するオプションのコールバックを受け取ります。APIにより、Alexa.Presentation.HTML.Message
がスキルに送信されます。
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 プロパティで送信されます。 |
any |
messageSentCallback |
sendMessage の結果を処理するために使用されるコールバック関数。 |
function |