lagged-js-sdk

Lagged JavaScript SDK

ローダースクリプトの読み込みが完了すると、window.LaggedAPI が公開されます。初期化、プレイヤー検索、広告、リーダーボード、実績はすべて LaggedAPI にまとめられています。

概要

対応機能：初期化ハンドシェイク、プレイヤープロフィールの検索、インタースティシャル広告、リワード広告、リーダーボードへのスコア送信、実績の解除。

組み込みチェックリスト

1. SDK を読み込む — lagged.js を挿入し、window.LaggedAPI が利用可能になるまで待ちます
2. 認証情報を使って初期化する — Lagged ダッシュボードで取得した ID を使い、sdk.init(devId, publisherId) を呼び出します
3. プレイヤーの認証状態を確認する — sdk.User.get を呼び出します。id > 0 はサインイン済み、id = 0 はゲストを意味します
4. シーンの切り替わりに広告を組み込む — レベル間でインタースティシャル広告を表示し、プレイヤーの操作を条件にリワード広告を表示します
5. ゲームオーバー時にスコアを送信する — ボード ID と最終スコアを指定して sdk.Scores.save を呼び出します
6. 実績を解除する — 条件を満たしたときに sdk.Achievements.save を呼び出します

インストール

SDK の URL は https://lagged.com/api/rev-share/lagged.js です。スクリプトタグを動的に挿入し、処理を進める前に window.LaggedAPI が利用可能になるまでポーリングします。

const SDK_URL = 'https://lagged.com/api/rev-share/lagged.js';

async function loadLaggedSDK(timeoutMs = 10000) {
    await new Promise((resolve, reject) => {
        const s = Object.assign(document.createElement('script'), {
            src: SDK_URL,
            async: true,
            onload: resolve,
            onerror: () => reject(new Error('Failed to load Lagged SDK'))
        });
        document.head.appendChild(s);
    });
    const started = Date.now();
    while (typeof window.LaggedAPI === 'undefined') {
        if (Date.now() - started > timeoutMs)
            throw new Error('LaggedAPI did not appear within ' + timeoutMs + 'ms');
        await new Promise((r) => setTimeout(r, 50));
    }
    return window.LaggedAPI;
}

初期化

LaggedAPI.init には、Lagged ダッシュボードで取得した開発者 ID とパブリッシャー ID の両方が必要です。init の直後に現在のプレイヤーを取得し、その ID、名前、アバターを読み取ります。

呼び出し元で initLagged を try/catch で囲みます。失敗した場合はリーダーボード、実績、広告の呼び出しを無効にし、SDK を利用できない状態でもゲームをプレイできるようにします。

async function initLagged(devId, publisherId) {
    if (!devId || !publisherId) throw new Error('devId and publisherId are required');

    const sdk = await loadLaggedSDK();
    sdk.init(devId, publisherId);

    const player = await new Promise((resolve) => {
        sdk.User.get((response) => {
            resolve(response && response.user ? response.user : {});
        });
    });

    // id > 0 = signed-in player; id = 0 = guest
    const profile = {
        isAuthorized: player.id > 0,
        id: player.id || null,
        name: player.name || null,
        avatar: player.avatar || null
    };

    console.debug('[Lagged] init complete', profile);
    return { sdk, profile };
}

プレイヤー

プレイヤーデータは、初期化時に LaggedAPI.User.get(callback) を使って一度だけ読み取ります。コールバックには { user: { id, name, avatar } } が渡されます。取得の全体的なロジックは、上記の initLagged 関数で示しています。ゲスト用のフォールバックが必要な場合は、ローカル ID を生成して localStorage に保存します。

広告

インタースティシャル広告

LaggedAPI.APIAds.show(onClosed) はインタースティシャル広告を表示します。呼び出し前にシミュレーションを一時停止して音声をミュートし、onClosed で再開します。

function showInterstitial(sdk, { onOpened, onClosed } = {}) {
    onOpened?.();
    sdk.APIAds.show(() => {
        onClosed?.();
    });
}

リワード広告

LaggedAPI.GEvents.reward(canShowReward, rewardSuccess) は、2 段階のリワード広告を実行します。

1. canShowReward(success, showAdFn) — success が true の場合は showAdFn() を呼び出して広告を表示します。それ以外の場合は代替の処理を提示します。
2. rewardSuccess(success) — true はプレイヤーが報酬を獲得したことを意味します。false は途中で閉じたか、失敗したことを意味します。

function showRewarded(sdk, { onOpened, onRewarded, onClosed, onFailed } = {}) {
    onOpened?.();
    sdk.GEvents.reward(
        (success, showAdFn) => {
            if (success) showAdFn();
            else onFailed?.('unavailable');
        },
        (success) => {
            if (success) {
                onRewarded?.();
                onClosed?.();
            } else onFailed?.('not_completed');
        }
    );
}

リーダーボード

各ボードは、Lagged ダッシュボードで設定する文字列 ID で識別されます。エントリーの取得やネイティブポップアップを開く API はありません。

function submitScore(sdk, boardId, score) {
    return new Promise((resolve, reject) => {
        sdk.Scores.save({ score, board: boardId }, (response) => {
            if (response && response.success) resolve(response);
            else reject((response && response.errormsg) || 'leaderboard_failed');
        });
    });
}

実績

LaggedAPI.Achievements.save(achievements, callback) は、1 回の呼び出しで 1 つ以上の実績を解除します。表示状態は Lagged が管理するため、リスト取得や個別取得の API はありません。

function unlockAchievement(sdk, achievement) {
    if (!achievement) return Promise.reject(new Error('achievement is required'));
    return new Promise((resolve, reject) => {
        const payload = Array.isArray(achievement) ? achievement : [achievement];
        sdk.Achievements.save(payload, (response) => {
            if (response && response.success) resolve(response);
            else reject((response && response.errormsg) || 'achievement_failed');
        });
    });
}