Appearance
指色SDK接入文档(普通小游戏)
如果您是已有老项目接入或没有出海需要，可以继续阅读该文档，否则建议您阅读SeegSdk
SDK版本
SDK兼容性
如果该gid是第一次使用，请跳过该章节
TIPS: 从老版本升级到1.0.2或1.1.0，请务必注意兼容性问题
1.1.0版本SDK的数据不兼容，请1.1.0版本前升级上来的，请将oldSdkVer设置为21.0.2版本的SDK的快手登录不兼容，请1.0.2版本前升级上来的，快手初始化时将oldSdkVer设置为1- 如果是
抖音跳微信小游戏(巨量上报)，本SDK暂不支持，请联系运营提供兼容SDK(仅替换js文件以及增加上报和微信官方插件即可)
版本记录
| 版本号 | 修改时间 | 修改内容 | 下载地址 |
|---|---|---|---|
| 1.1.2 | 2025-02-27 | 1. 接入数数 2. 增加SDK测试功能 | 下载 |
| 1.1.1 | 2025-02-18 | 1. 省份排行榜增加时间和分数 2. 个人排行榜重构 3.新版排行榜支持获取上一个周期排行榜数据 4. 抖音推荐流直出功能 | |
| 1.1.0 | 2024-11-19 | 1. 优化数据存储 2. 增加时长统计 3.支持b站小游戏 | |
| 1.0.8 | 2024-08-14 | 1. 增加数据上报方法 2. 优化数据存储 | 下载(不推荐) |
| 1.0.7 | 2024-07-24 | 1. 增加ab测试说明 | |
| 1.0.6 | 2024-06-24 | 1. 增加排行榜api | |
| 1.0.5 | 2024-05-21 | 1. 优化网络请求 2. 适配es5 | |
| 1.0.4 | 2024-05-06 | 1. 增加获取后台配置 | |
| 1.0.3 | 2024-03-11 | 1. 增加TD打点 2. 增加获取时间戳 3. 增加数据存储 | |
| 1.0.2 | 2024-01-11 | 1. 修改快手登录方式 | |
| 1.0.1 | 2024-01-06 | 1. 增加打印控制 | |
| 1.0.0 | 2023-12-25 | 1. 初始版本 |
快速集成
- 将
seeg_sdk文件夹拖到Cocos项目中或在构建后的的game.js中引用；seeg.js与seeg_td.js请只保留一个，请勿同时集成- seeg_td.js相比会增加约35kb大小
- 如果不清楚td是什么，务必与运营沟通，如果选择了接入seeg_td但是没有填写td参数，SDK将无法初始化
- b站小游戏，占不支持TD版本
- 如果账号由我方运营提供，请提醒我方运营加入白名单
- 在对应平台添加请求域名白名单(request)：
https://gamesapi2.aslk2018.comhttps://gmcfg.aslk2018.com- 如果集成了TD版本
https://h5.udrig.com - 如果需要上报数数
https://moderate.aslk2018.com
- 找运营提供参数
- 由我方提供gid参数，gid参数形式为平台标识_英文游戏名
- 如果集成TD版本，则需要提供TD参数
- 如果开通巨量投微信（由运营提示），则需要自行在game.json中添加插件，参考初始化一节
注意
- 如果是直接在Cocos工程里面引用，拖入即可，不需要导入为插件
- 如果是在构建后的项目里引用，仅需在game.js中引用即可，如下
// game.js
// 2.x
require('./adapter-min.js');
// 3.x
require('./web-adapter');
// 正确引用方式
require('seeg.js');
// td版本
require('seeg_td.js');
// 错误引用方式
const seeg = requrie('seeg.js');
// 执行语句即可
seeg.init({gid: 'ks_xxx'});
// 集成TD
seeg.init({gid: 'ks_xxx', tdAppKey:'xxx'});在设备上查看是否有登录成功的日志
在测试版本中，用户首次登录，在初始化和广告上报阶段会弹框，这是SDK接口自测，属于正常情况
SDK接口
SDK初始化(必接)
seeg.init
/**
* @description 初始化sdk
* @param option sdk参数
* gid: 游戏id
* loggerLevel: 打印等级
* 0: 全部关闭(默认)
* 1: 打印错误信息
* 2: 打印警告信息
* 3: 打印普通信息
* 4: 打印调试信息
* 5: 打印全部信息
* oldSdkVer: 老版本SDK升级兼容
* tdAppKey: 当使用的是包含了TD的sdk，该值必须填写
* version: 版本号
* reportSS: 是否上报数数数据
* reportJL: 是否开启巨量上报
* @returns
*/
export function init(option: { gid: string; loggerLevel?: number; oldSdkVer?: number; tdAppKey?: string; version?: string; reportSS?: boolean, reportJL?: boolean }): void;- 请尽早调用该接口，以便于sdk尽早初始化；
- 请务必注意，调用本初始化接口，sdk内部会自动调用平台的登录接口，如果有登录需求，请务必等该接口的登录回调完毕后进行（或调整次序）；
gid为我方的游戏标识，以平台标识符开头的字符串，例如wx_xxx、ks_xxx、tt_xxx等，特别注意不是游戏的appId；loggerLevel为打印等级，默认不打印任何信息，如果需要调试，可以设置打印等级，打印等级越高能打印的信息越多，建议线上关闭；version为版本号，主要是用来读取配置的，如果有ab测试需求或读取配置需求，可以与运营沟通该参数，否则不需要填写;tdAppKey为td参数，如果选择了集成了td的sdk，则该参数必接，如果该参数由CP自己提供，请务必将所有平台都勾选上；reportJL为巨量投微信参数，如果开启，则必须开通MiniGameCommon插件，并在微信的game.json文件中添加对应的插件
"plugins": {
"MiniGameCommon": {
"version": "latest",
"provider": "wxaed5ace05d92b218",
"contexts": [
{
"type": "isolatedContext"
}
]
}
}- 如果客户端有需要获取用户的登录态信息，可以调用登录监听接口
seeg.onLoginRet，该接口一次监听只返回一次结果，sdk1.0.8以下只返回openid
/**
* @description
* @param callback 回调方法
* ret: 回调参数
* userId: 用户的id
* openId: 用户的openid
* isTest: 是否是白名单用户
* abTest: ab分组
* nickname: 用户昵称 包括以下头像和性别，需要调用seeg.reportUserInfo接口上报数据后，才会返回
* avatar: 用户头像
* gender: 用户性别
* regTime: 注册时间
*/
export function onLoginRet(callback: (ret: { userId: number; openId: string; isTest: boolean; abTest: number; nickname: string; avatar: string; gender: number; regTime:string }) => void): void;广告上报(必接)
seeg.reportAd
/**
* @description 上报广告事件
* @param option 广告事件参数
* name 上报广告名 可选参数 如无特殊要求无需填写，如填写则必须符合编程命名规则
* complete 广告是否观看完成
*
*/
export function reportAd(option: {name?: string, complete: boolean }): void;- 目前仅需上报激励视频
- 广告关闭后（无论是否观看完成），都要调用该接口（广告加载失败或展示失败，无需调用该接口）。可以理解为onClose回调里就调用该方法，只是区分是否看完的传参不同。
- name可以不传，传入后，将会根据name统计广告信息
获取游戏配置
seeg.getGameConfig
SDK要求：>=1.0.4
/**
* @description 获取游戏配置
* @param object 获取参数
* success: 获取成功回调
* fail: 获取失败回调
*/
export function getGameConfig(object: { success?: (ret: any) => void, fail?: Function }): void;用户数据上报
使用该接口前，务必先与我方运营确认
用户数据存档
SDK要求：>=1.0.3
/**
* @description 获取用户远程存储数据
* @param callback errCode 错误码 errMsg 错误信息 data 用户数据
*/
export function getUserData(callback: { errCode: number; errMsg?: string; data?: any }): void;
/**
* @description 上传用户远程存储数据
* @param data 用户数据
*/
export function setUserData(data: { [key: string]: any }): void;注意
- key不支持包含"."
- 调用该接口，请务必提前与运营沟通，确定方案后使用
- 存储接口，一分钟不能超过6次，请注意频率
- 推荐的一种方案
// 启动游戏时，判断本地是否有数据
// 有则取本地数据
// 没有则取远程数据
// 游戏中，每分钟(建议1-3分钟)存档一次数据
// 如可以区分变动数据，每次也可以只上传有改动的数据，而不需要全量存档
// 如仅需一些数据上报到服务器，而本身不需要使用，也可以使用下面的方法
// SDK要求：>=1.0.8
/**
* @description 上报事件
* @param name 事件名
* @param val 事件值
*/
export function reportEvent(name: string, val: any): void;
/**
* @description 增加事件上报计数
* @param name 事件名
* @param val 事件值
*/
export function reportEventAdd(name: string, val: number): void;
/**
* @description 事件开始
* @param name 事件名
*/
export function reportEventStart(name: string): void;
/**
* @description 事件结束
* @param name 事件名
*/
export function reportEventEnd(name: string): void;TD(Talkingdata)数据打点
seeg.onEvent
SDK要求：>=1.0.3
/**
* @description 事件上报（目前上传到td）
* @param eventId td的事件名
* @param params 事件参数
*/
export function onEvent(eventId: string, params: { [key: string]: number | string }): void;数数(TE)数据打点
SDK要求: >=1.1.2
/**
* @description 上报用户信息
* @param type 上报类型
* user_set：对用户表进行操作，覆盖一个或多个用户属性，如果该属性已有值存在，覆盖先前值
* user_setOnce：对用户表进行操作，初始化一个或多个用户属性，如果该属性已有值存在，则忽略本次操作
* user_add：对用户表进行操作，为一个或多个数值型用户属性做累加计算
* user_unset：对用户表进行操作，清空该名用户的一个或多个用户属性的属性值
* user_del：对用户表进行操作，删除该名用户
* user_append：对用户表进行操作，为用户的列表类型属性值添加元素
* user_uniq_append: 对用户表进行操作，为用户的列表类型属性值添加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变）
* @param properties 参数
*/
reportUserInfo(type: string, properties: any): void;
/**
* @description 上报事件
* @param event 事件名
* 必须以字母开头，只能包含：字母（区分大小写）、数字和下划线“_”，长度最大为 50 个字符。
* 请注意配置时不要带有空格。
* @param properties 参数
*/
onEvent(event: string, properties?: any): void;
/**
* @description 上报加载完成事件
* @param properties 可交互时间 单位：秒
*/
loadComplete(time: number): void;- 该api目前放在seeg.ss下，请注意区别
- SDK已集成打点：注册、登录和在线，其它打点请参考数数打点模板
个人信息上报
seeg.reportUserInfo
SDK要求：>=1.0.6
该方法一般与排行榜功能同时使用
/**
* @description 设置用户信息
* @param avatar 用户头像
* @param nickname 用户昵称
* @param gender 用户性别，暂时不需要传入
*/
export function reportUserInfo(avatar: string, nickname: string, gender: number): void;非开放域的排行榜
SDK要求：>=1.0.6
分为省份排行榜、个人排行榜和全球排行榜
省份排行榜
/**
* @description 获取省份代码
* @returns 网络不畅，会返回空，请注意判断
*/
export function getUserProvince(): Promise<{ province: string, province_code: string }>;
/**
* @description 获取省份排行
* @param type 排行榜类型
* @param timeType 时间类型 0：永久(默认) 1: 天 2：周 3：月
* @param round 0: 当前周期(默认) 1: 上一个周期
* @returns
*/
export function getProvinceList(type: string, timeType?: 0 | 1 | 2 | 3, round?: 0|1): Promise<{ list: { province: string; province_code: string; num: number }[] }>;
/**
* @description 增加省份排行榜数据
* @param type 排行榜类型
* @param timeType 时间类型 0：永久(默认) 1: 天 2：周 3：月
* @param num 数值，默认为1
*/
export function addProvinceData(type: string, timeType?: 0 | 1 | 2 | 3, num?: number): void;个人排行榜
/**
* @description 修改排行榜数据
* @param type 排行榜类型
* @param valueType 数值类型 1：累加 2：覆盖
* @param num 数值
* @param timeType 时间类型 1: 天 2：周 3：月
* @param rankData 排行榜额外数据，默认为空字符串
* @param limit 排行榜条数，默认为100
*/
export function changeRankData(type: string, valueType: 1 | 2, num: number, timeType: 1 | 2 | 3, rankData?: string, limit?: number): void;
/**
* @description 获取个人排行
* @param type 排行榜类型
* @param timeType 时间类型 0：老版接口 1: 天 2：周 3：月
* @param limit 排行榜条数，默认为100
* @param round 0: 当前周期(默认) 1: 上一个周期 仅新版接口支持，传0不支持
*/
export function getRankList(type: string, timeType: 0 | 1 | 2 | 3, limit?: number, round?: 0|1): Promise<{ list?: { uid: string; num: number; nickname: string; avatar: string; rank_data?: string }[] }>;
// 以下接口已废弃，如果不需要兼容老的排行榜，请直接使用changeRankData
/**
* @deprecated 请使用 changeRankData 替代
* @description 修改个人日排行榜,隔天重置
*/
export function changeDayRankData(type: string, valueType: 1 | 2, num: number, rankData?: string, limit?: number): void;
/**
* @deprecated 请使用 changeRankData 替代
* @description 修改个人周排行榜，每周一重置
*/
export function changeWeekRankData(type: string, valueType: 1 | 2, num: number, rankData?: string, limit?: number): void;
/**
* @deprecated 请使用 changeRankData 替代
* @description 修改个人月排行榜 每月一号重置
*/
export function changeMonthRankData(type: string, valueType: 1 | 2, num: number, rankData?: string, limit?: number): void;- 特别注意：
- 如果用的是changeDay(Week、Month)RankData，请获取时的timeType设置为0
- 如果不需要兼容老的排行榜，请直接使用changeRankData，同时getRankList的timeType保持一致即可
全球排行榜
/**
* @description 增加全球排行榜分数
* @param type 排行榜标记
* @param addNum 增加的数量
*/
export function addGRank(tag: string, addNum: number): void;
/**
* @description 获取全球排行榜
* @param type 排行榜标记
* @param limit 排行榜条数，默认为100
* @returns
*/
export function getGRank(tag: string, limit?: number): Promise<{ list?: { uid: string; num: number; rank: number; nickname: string; avatar: string; rank_data?: string }[] }>;
/**
* @description 获取个人全球排行榜
* @param type 排行榜标记
*/
export function getUserGRank(tag: string): Promise<{ rank: number, score: number }>;抖音推荐流直出功能（场景化入口）
SDK要求：>=1.1.1
使用前需联系运营开通直出能力
/**
* @description 上报直出数据到服务端（用于游戏内展示直玩入口）
* @param scene 场景类型
* 1: 离线收益 - 挂机类游戏的收益领取场景
* 2: 体力恢复 - 体力自然恢复倒计时场景
* 3: 重要事件 - 关键事件提醒场景
* @param contentIds 预置文案ID数组（需后台申请开通后获取）
* @param timestamp 条件满足时的时间（毫秒单位）
* @param extra 自定义参数（JSON对象，将在直玩启动时回传）
*/
export function setZWData(
scene: 1 | 2 | 3,
contentIds: string[],
timestamp: number,
extra?: { [key: string]: any }
): void;- 本接口仅提供了服务端支持，完整调用请参考文档:推荐流直出小游戏能力接入指引
下面，我们给出一种实现方式以供参考，请注意，以下代码仅为演示逻辑流程，代码为伪代码
// 在首页判断是否来自抖音推荐流直出
if(tt.getLaunchOptionsSync().scene.toString().endsWith('3041')){ // 注意如果是重复可以进入的判断，则仅需判断第一次
// 进入对应的界面
// 如果有多种场景，也可以拿到query下的feed_game_scene 或 feed_game_extra 进行对应的跳转
}
// 在跳转成功后，一定要上报该接口
// 注意上报该接口后，抖音会停止网络相关的访问，所以要确保远程资源已经下载完毕
// 同时也只有在这个方法上报后，抖音才会显示直玩入口，所以也不建议太晚上报
tt.reportScene({ sceneId: 7001, costTime: params.duration });
// 在对应的界面，比如领取界面，进行授权判断
// 如果选择的是all，则必须是用户主动操作的，我们一般建议在领取的时候弹出，然后顺便上报给服务器下一次领取的时间
tt.checkFeedSubscribeStatus({
type: 'play',
allScene: true,
success: (res: { status: boolean }) => {
if (res.status) {
// 已订阅回调
return;
}
// 继续请求
tt.requestFeedSubscribe({
type: 'play',
// 单场景订阅
scene: 1,
contentIDs: ["CONTENT123", "CONTENT234"],
// 对应全场景，则必须是用户点击后触发
allScene: true,
success: (res: { errMsg: string, success: boolean }) => {
if (res.success) {
// 订阅成功回调
} else {
// 用户未订阅
}
},
fail: (err: { errNo: number, errMsg: string }) => {
// 订阅失败
}
});
},
fail: (err: { errNo: number, errMsg: string }) => {
// 查询失败
}
// 订阅成功后，向服务器请求下次成功的领取时间
// 离线收益场景是1 体力恢复场景是2 重大时间提醒场景是3
seeg.setZWData(scene, ["CONTENT_ID"], time);
// 如果需要统计从推荐流直出来的用户，可以使用tt.onFeedStatusChange接口监听注意
- 在网页模式下，本SDK将会产生一个临时的用户登录，该用户不会生成openid，仅供测试使用，请勿直接用于线上web环境
常见问题(FAQ)
提示非投放场景
- 正常打印，无需关注
提示填写正确的TDAppKey
- 请填写td参数，如果不需要TD，请集成seeg.js，删除seeg_td.js即可
运营提示没有数据
- 检查gid是否正确，例如是否填写成AppId
- 检查是否调用了初始化接口
- 是否同时集成了seeg.js 和 seeg_td.js，仅需保留一个
- 如果集成的是seeg_td.js 是否没有填写td参数
- 是否调用了seeg.reportAd方法
推荐流直出报错
- 请联系运营，抖小开平后台设置是否正确
- 请确保setZWData方法传入的content_id和scene与运营配置的一致
数数打点没有数据
- 请确保开通了数数权限，必须找运营开通，每一个gid都需要单独处理
- 初始化确认ssReport设置为true
- 确认数数的域名已经添加到白名单：https://moderate.aslk2018.com