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ブラウザが起動したときに、デバイスに最初に白色のフラッシュを表示します。フラッシュを制御することはできません。
  • アセットのロード中に背景色またはページスタイルを設定し、ゲームを使用する準備ができていることをユーザーに知らせます。
  • 点滅を防ぐために、ロード中およびアプリを使用する準備ができたときは背景色を一定に保ちます。
  • キャッシュ制御ヘッダーに従ってデバイスにアセットをキャッシュします。開発中にキャッシュについて考えておき、本番環境で使用します。
  • ウェブアプリまたはスキルのバックエンドにゲームロジックを含めるようにゲームをデザインできます。アプリで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がスキルに送信されます。

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

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

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

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

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

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