keytops-game-sdk

keytops-game-sdk 是对外游戏运行时 SDK，面向接入 keytops 能力的业务项目。这个分支只维护对外 facade、类型声明、standalone 包和 npm 包，不包含 Cocos Creator 开发框架层的视图、资源和引擎注入实现。

功能概览

• keytops.init()：初始化运行时环境
• keytops.user：登录、身份与整包存档读写
• keytops.config：基础配置、关卡配置和扩展 method 配置
• keytops.analytics：通用事件与耗时统计
• keytops.ad：Banner、插屏、激励视频
• keytops.level：关卡生命周期与道具行为

安装

npm

npm install keytops-game-sdk

standalone

构建后会生成：

• dist/standalone/keytops.js
• dist/standalone/keytops.min.js
• dist/standalone/keytops.d.ts
• dist/standalone/keytops-game-sdk-<version>.zip

npm 快速开始

import { keytops } from "keytops-game-sdk";

await keytops.init({
    debug: true,
});

初始化

await keytops.init({
    debug: true,
    autoLogin: true,
    customAppInfo: {
        appId: "keytops-web-app",
        version: "1.0.1",
        envVersion: "develop",
        options: {
            scene: "landing",
            query: {
                channel: "summer_campaign",
            },
        },
    },
});

初始化参数说明：

• debug：是否输出调试日志；默认只在非正式环境打印
• autoLogin：初始化完成后是否自动执行平台登录
• customAppInfo：本地 H5 / Web 调试时覆盖 appId、版本号和启动参数

用户模块

SDK 提供的是整包存档能力，不提供单字段存取协议。推荐业务方自行维护存档对象结构。

const loginResult = await keytops.user.login();

if (loginResult.success) {
    const userData = await keytops.user.getUserData<{
        score: number;
        profile: { coins: number };
    }>();

    await keytops.user.saveUserData({
        ...userData,
        score: (userData.score || 0) + 1,
    });

    await keytops.user.sync();
}

常用能力：

• keytops.user.login(force?)
• keytops.user.isLoggedIn
• keytops.user.openid
• keytops.user.anonymousId
• keytops.user.getUserData()
• keytops.user.saveUserData(data)
• keytops.user.clearUserData()
• keytops.user.sync()

配置模块

服务端会先完成 AB 分桶，客户端读取到的是最终命中的配置内容。

const baseConfig = keytops.config.getBase();
const levelConfig = keytops.config.getLevel("default");
const systemConfig = keytops.config.getWithMethod("system");

const latestBase = await keytops.config.refreshBase("default", {
    scope: "new_user",
});

const serverTime = keytops.config.serverTime();
const resolveKey = keytops.config.configMD5("system");

常用能力：

• keytops.config.getBase(gameFlag?)
• keytops.config.getLevel(gameFlag?)
• keytops.config.getWithMethod(method, gameFlag?)
• keytops.config.refreshBase(gameFlag?, data?)
• keytops.config.refreshLevel(gameFlag?, data?)
• keytops.config.refreshWithMethod(method?, gameFlag?, data?)
• keytops.config.serverTime()
• keytops.config.configMD5(method?, gameFlag?)

埋点模块

keytops.analytics.time("page_stay");

await keytops.analytics.report("button_click", {
    id: "start",
    name: "start_button",
});

keytops.analytics.cancelTime("page_stay");

常用能力：

• keytops.analytics.enable(debug?)
• keytops.analytics.onLaunch(step, data?)
• keytops.analytics.report(eventName, data?)
• keytops.analytics.time(eventName, once?, offset?)
• keytops.analytics.cancelTime(eventName)

广告模块

await keytops.ad.loadBanner({
    action: "home_banner",
});

await keytops.ad.showBanner({
    action: "home_banner",
});

const rewardFinished = await keytops.ad.showRewardVideo({
    action: "revive",
    group: "level_fail",
});

常用能力：

• keytops.ad.loadBanner(from)
• keytops.ad.showBanner(from)
• keytops.ad.hideBanner()
• keytops.ad.loadInterstitial(from)
• keytops.ad.showInterstitial(from)
• keytops.ad.showRewardVideo(from, breakConfirm?)

关卡模块

await keytops.level.start("level_1", 1, "default", {
    name: "新手第一关",
});

keytops.level.progress(30);
keytops.level.revive({
    name: "checkpoint_revive",
});
keytops.level.success({
    count: 1,
});

带广告的道具行为也可以直接通过 facade 调用：

const used = await keytops.level.useItemWithAd(
    "hammer",
    {
        id: "level_1",
        index: 1,
    },
    10,
);

常用能力：

• keytops.level.start(id, index, gameFlag?, data?, isReplay?)
• keytops.level.progress(progress)
• keytops.level.success(data?)
• keytops.level.fail(data?)
• keytops.level.break(data?)
• keytops.level.retry(data?)
• keytops.level.skip(data?)
• keytops.level.revive(data?)
• keytops.level.useItemWithoutAd(name, weight, data?)
• keytops.level.useItemWithAd(itemName, analyticsData?, propWeight?, breakConfirm?)

standalone 说明

standalone 包会生成一个全局 keytops 入口，适合不通过 npm 的接入方式：

• keytops.min.js：运行时代码
• keytops.d.ts：类型声明
• README.md：standalone 使用说明

zip 包内会包含以上 3 个文件，方便直接交付给接入方。

构建

npm run build

构建内容：

• standalone bundle：dist/standalone/keytops.js
• standalone min bundle：dist/standalone/keytops.min.js
• standalone types：dist/standalone/keytops.d.ts
• standalone zip：dist/standalone/keytops-game-sdk-<version>.zip
• npm esm：dist/npm/index.esm.js
• npm cjs：dist/npm/index.cjs
• npm types：dist/npm/index.d.ts

注意事项

• 在调用 config、user、analytics、ad、level 前，应先完成 keytops.init()
• AB 分桶由服务端完成，客户端直接读取命中的配置结果
• SDK 只提供整包存档接口，不提供单字段合并协议
• 这个分支不维护 framework 层的 Cocos 视图、资源和引擎注入能力
• Cocos Creator 游戏框架请使用独立的 keytops-game-framework 包