アソバースのログインとゲームをつなぐ：作者向けSDK入門

ブリッジが解決すること

ゲームがアソバースの /play/:id に埋め込まれると、プレイヤーは親画面のアソバースアカウントでログインしている可能性があります。しかし、この状態はゲームの内側に自動では届きません。ゲーム内のスクリプトから親画面に直接アクセスすることも、セキュリティ上の制約からできません。SDKを読み込んでAPIを呼ぶことで、親画面からゲームへ情報が橋渡しされます。

ゲームは Asoverse.ready() を呼ぶだけで、プレイヤーのログイン状態とそのゲーム固有のIDを取得できます。ゲームのHTMLやJavaScriptに大きな変更を加えずに組み込めるのは、このブリッジがアソバース側で管理されているためです。アップロードしたゲームも、公開URLを登録した外部ゲームが埋め込まれている場合も、SDKのAPIを呼べばブリッジは同様に応答します。ただし、外部ゲームがiframe埋め込みを拒否している場合や別タブで起動する設定になっている場合には、ブリッジは機能しません。この点はSDK入門の終盤で詳しく説明します。

受け渡す情報と受け渡さない情報

Asoverse.ready() が返すオブジェクトには次のフィールドが含まれます。

• player: ログイン済みなら {id, authenticated}、未ログインなら null
• gameId: このゲームのID
• locale: プレイヤーの言語設定（ja または en）
• capabilities: {save, maxSaveBytes} — クラウドセーブの可否と上限バイト数

player.id はユーザーとゲームのペアに固定されたランダムなUUIDです。アソバースへのログイン状態が続く間は同じ値が返り続けます。Firebase UID、JWT、パスワード、メールアドレス、別のゲームのセーブデータは一切共有されません。player.id は読み取り専用の識別子であり、外部バックエンドでプレイヤーを識別する認証証明には使えません。外部サーバーで「このplayer.idを送ってきた相手がアソバース登録ユーザー本人である」と確認する手段はSDK単体には含まれていません。ゲーム側でサーバー認証が必要な場合は、別途実装が必要です。

SDKの読み込みとready()

SDKはアソバースが公開するscriptタグ一行で読み込みます。asoverse.js をゲームのHTMLに追加するだけで、埋め込み時に Asoverse オブジェクトが利用できます。

<!-- SDKの読み込み（説明用） -->
<script src="https://aso-verse.com/sdk/asoverse.js"></script>

Asoverse.ready() はPromiseを返します。解決後に初期状態を取得し、必要に応じてセーブデータを読み込みます。ゲームの初期化処理の中で一度だけ呼ぶ設計が基本です。capabilities.save が true であることを確認してからセーブ機能を使うと、クラウドセーブが有効でない環境への対応が明確になります。

// 説明用のコード例（動作確認は公式ガイドで行ってください）
const state = await Asoverse.ready();
const { player, gameId, locale, capabilities } = state;

if (player?.authenticated && capabilities.save) {
  const saved = await Asoverse.load();
  if (saved) restoreProgress(saved);
}

capabilities.maxSaveBytes には現在 131072（128 KiB）が返ります。ゲームがアソバースの外から開かれた場合、Asoverse オブジェクトは存在しないかブリッジに接続していません。typeof Asoverse !== 'undefined' のような確認を入れておくと、開発環境でのエラーを避けられます。開発用のローカルホスト（localhost / 127.0.0.1）はSDKの許可済みオリジンに含まれています。

セーブの読み書きと同期

Asoverse.load() はそのゲームに保存された直近のJSONを返します。セーブがない場合は null です。Asoverse.save(value) はJSONオブジェクトを渡すと、保存を受け付けてから {storage, pending, localCopy} で解決します。

// 説明用のコード例
const saved = await Asoverse.load();
if (saved) restoreProgress(saved);

// 進行を保存
const result = await Asoverse.save({ level: 3, score: 1200 });
console.log(result.storage);  // 'cloud' または 'device'
console.log(result.pending);  // true なら書き込みはまだ処理中

save() が解決しても pending: true が返る場合は、クラウド書き込みの完了確認ではありません。ローカルへの一時保存は行われており、ブリッジが後でクラウドへ送信します。クラウド書き込みの完了を検知したい場合は on('sync', callback) イベントを使います。コールバック登録は解除関数を返すため、不要になったタイミングで呼び出してください。

// 説明用のコード例
const off = Asoverse.on('sync', ({ state }) => {
  if (state === 'saved') {
    showSavedIndicator(); // クラウドへの書き込みが完了した
  }
});
// 不要になったら off() を呼んで解除

ゲストプレイ（未ログイン）のセーブはゲスト専用のキーに保存されます。プレイヤーがログインしてもゲスト時のセーブはアカウントに自動でマージされません。途中でログインした場合の継続処理は、ゲーム側で設計が必要です。

イベントとロケール対応

on('locale', callback) はプレイヤーの言語設定が変わるたびに呼ばれます。コールバックには 'ja' または 'en' が渡されます。ready() で取得した locale と組み合わせることで、ゲームの初期表示から言語切り替えまで一貫して対応できます。

// 説明用のコード例
const { locale } = await Asoverse.ready();
updateUILanguage(locale);

Asoverse.on('locale', (lang) => {
  // lang は 'ja' または 'en'
  updateUILanguage(lang);
});

on('session', callback) と on('load', callback) もサポートされています。どの on() も解除関数を返します。ゲームの再初期化やコンポーネントの破棄タイミングで解除しておくと、古いコールバックの重複呼び出しを防げます。

外部ゲームとログインの関係

アソバースにログインしても、外部ゲームのアカウントには自動でサインインされることはありません。公開URLを登録した作者のサイトが独自のFirebaseプロジェクトやGoogle OAuthを使っている場合、アソバースのログインはそのシステムへ引き継がれません。SDKのブリッジはアソバース内に埋め込まれたゲームのための仕組みであり、クロスサイトのシングルサインオン（SSO）ではありません。

iframeの内部でGoogle OAuthの signInWithPopup を呼び出すと、Googleのポリシーにより認証が失敗する場合があります。Googleは開発者が管理する埋め込みユーザーエージェントへのOAuth認可リクエストを認めておらず、このポリシーはiframeのsandbox属性の調整だけでは回避できません。外部ゲームでユーザーログインが必要な場合は、プレイヤーが直接作者のサイトを別タブで開くフローを用意してください。

アソバースには、既知のiframe互換性問題があるゲームを自動的に別タブ起動に切り替える仕組みがあります。別タブで起動されたゲームではSDKのブリッジは使えないため、アカウントや進行データの管理はそれぞれ作者のサイト側で行う必要があります。外部ゲームの起動履歴はアソバース側で記録しますが、それはゲームのログイン成功やセーブの完了を意味するものではありません。

iframeのloadイベントはネットワークエラーが起きても発火し、errorイベントはセキュリティ上の理由から発火しません（MDN仕様）。そのため onLoad が呼ばれた事実を「ゲームが正常に表示された」という判定には使えません。ゲームの表示確認と認証の動作確認は、実際のブラウザで行ってください。