lagged-js-sdk

Lagged JavaScript SDK

其加载器脚本执行完毕后，会公开 window.LaggedAPI。初始化、玩家查询、广告、排行榜和成就功能都由 LaggedAPI 提供。

概述

支持的功能：初始化握手、玩家资料查询、插屏广告、激励广告、排行榜分数提交和成就解锁。

集成检查清单

1. 加载 SDK — 注入 lagged.js，并等待 window.LaggedAPI
2. 使用凭据初始化 — 调用 sdk.init(devId, publisherId)，传入 Lagged 控制面板中的 ID
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、名称和头像。

在调用位置使用 try/catch 包装 initLagged；如果失败，请禁用排行榜、成就和广告调用，以便游戏在没有 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) 会运行一个分两个阶段的激励广告流程：

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) 可在一次调用中解锁一个或多个成就。显示状态由 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');
        });
    });
}