指色文档

Appearance

指色SDK接入文档(Unity小游戏) ​

如果您是已有老项目接入或没有出海需求，可以继续阅读该文档，否则建议您阅读SeegSdk

SDK版本 ​

SDK兼容性 ​

如果该gid是第一次使用，请跳过该章节

TIPS: 从老版本升级到1.1.0，请务必注意兼容性问题

  • 1.1.0版本SDK的用户存档数据不兼容，请1.1.0版本前升级上来的，请在调用初始化前将Seeg.fixSdkVer设置为1
  • 1.1.3版本增加了配置的请求域名https://gmcfg.aslk2018.com，请注意添加到白名单
  • 如果是抖音跳微信小游戏(巨量上报)，本SDK暂不支持，请联系运营提供兼容SDK(仅替换dll文件以及增加上报和微信官方插件即可)

版本记录 ​

版本号修改时间修改内容下载地址
1.1.32025-04-18SDK优化下载
1.1.22025-03-171. 修复数数接口
2. 增加SDK测试功能		下载
1.1.12025-03-071. 优化初始化接口
2. 修复抖音推荐流直出
1.1.02025-03-011.增加抖音推荐流直出支持
2. 集成数数SDK接入
3. 优化排行榜实现逻辑
4. 优化用户数据上报(注意兼容性)
1.0.82024-12-271. 修复个人排行榜不刷新bug
2. 优化排行榜的刷新机制		下载(不推荐)
1.0.72024-09-241. 添加排行榜
1.0.62024-08-221. 支持快手WASMSDK
2. 优化网络请求
1.0.52024-08-061. 增加用户数据存储
1.0.42024-08-051. 优化多平台接入
1.0.32024-07-301. 增加读取配置下载(不推荐)
1.0.22024-06-241. 适配2022及以上版本
1.0.12024-01-151. 初始版本

快速集成 ​

  1. 导入平台SDK：
  2. 导入本SDKSeegSdk.unitypackage；
  3. 本SDK依赖Newtonsoft.Json，如工程中未使用，请集成；
  4. 在对应平台添加请求域名白名单(request)：
    • https://gamesapi2.aslk2018.com
    • https://gmcfg.aslk2018.com
    • 如果需要上报数数 https://moderate.aslk2018.com
  5. 由我运营提供gid参数：
    1. 一般gid参数我方运营命名为游戏标识
    2. 如果自行申请的appId，则需将appId和appSecret提供给我方运营，生成gid参数
  6. SeegExample提供示例，可按需参考；

选择平台宏(重要) ​

  1. 1.1.3及以上版本

在SeegSDK菜单栏切换平台宏

  1. 1.1.3以下版本

在Seeg.cs文件中将对应的平台的宏打开即可

// 测试或web渠道
// #define PF_WEB
// 微信小游戏渠道
// #define PF_WX
// 头条小游戏渠道
// #define PF_TT
// 快手小游戏Native模式
// #define PF_KS
// 快手小游戏WASM（WebGL）版本
// #define PF_KS_WASM
  • 请选择平台对应的宏，且保证其它平台的宏关闭
  • 另外一种方式是完全注释掉这个，在Unity编辑器中设置，可以根据自己喜好设置，但务必保证同时只有一个宏开启

SDK接口 ​

命名空间为ZhiSe

SDK初始化(必接) ​

Seeg.Init

    /// <summary>
    /// 初始化
    /// </summary>
    /// <param name="option">
    ///     gid: 游戏ID 运营提供的游戏标识，一般格式为[平台标识字符_游戏简拼]，请勿与AppId弄混[必填]
    ///     loggerLevel: 日志等级，从0到5，日志等级越高能打印的信息越多，建议线上关闭[可选，默认0]
    ///     version: 版本号 如果运营没有特别说明，请勿修改[可选，默认1.0.0]
    ///     shushu: 是否开启数数，如果没有运营明确说明，请确认关闭[可选，默认false]
    ///     autoInitPF: 自动初始化平台，是否由SDK内部初始化平台的SDK，如果不需要，请确保初始化完平台SDK，再调用该初始化接口[可选，默认false]
    ///     fixSdkVer: SDK修复版本，请查看SDK兼容性章节[可选，默认为0]
    ///     code: 测试code，请勿自行填写，一般为测试时需要[可选，默认为null]
    /// </param>
    public static void Init(SdkOption option)

     /// 已废弃，请使用Init(SeegSdkOption option)替代
    public static void Init(string gid, int loggerLevel = 0, string version = "1.0.0", string code = null, int fixSdkVer = 0, bool shushu = false);
  • 请尽早调用该接口，让sdk初始化；
  • 除gid外，其它参数都有默认值，如果没有特殊需要，可以不用修改；
  • 如果客户端有需要获取用户的登录态信息，可以调用登录监听接口Seeg.OnLoginResult，该接口一次监听只返回一次结果，1.0.7以下版本仅提供openId和userId信息
    /// <summary>   
    /// 登录结果回调    
    /// </summary>
    /// <param name="option">
    ///     success: 登录成功回调[可选]
    ///         userId: 用户ID
    ///         openId: 用户openID
    ///         abTest: AB测试组
    ///         nickname: 昵称
    ///         avatar: 头像
    ///         regTime: 注册时间
    ///         isTest: 是否是测试用户
    ///     fail: 登录失败回调[可选]
    ///     complete: 登录完成回调[可选]
    /// </param>
    public static void OnLoginResult(LoginOption option);

广告上报(必接) ​

Seeg.ReportAd

    /// <summary>
    /// 上报广告事件
    /// </summary>
    /// <param name="complete">是否观看完成</param>
    public static void ReportAd(bool complete);
  • 目前仅需上报激励视频
  • 广告关闭后（无论是否观看完成），都要调用该接口（广告加载失败或展示失败，无需调用该接口）。可以理解为onClose回调里就调用该方法，只是区分是否看完的传参不同。

获取游戏配置 ​

Seeg.GetGameConfig

SDK要求：>=1.0.3

    /// <summary>
    /// 获取游戏配置
    /// </summary>
    /// <param name="option">
    ///     success: 获取游戏配置成功回调[可选]
    ///     fail: 获取游戏配置失败回调[可选]
    ///     complete: 获取游戏配置完成回调[可选]
    /// </param>
    public static void GetGameConfig(GetGameConfigOption option);

用户数据上报 ​

使用该接口前，务必先与我方运营确认

用户数据存档 ​

SDK要求：>=1.0.5

    /// <summary>
    /// 获取用户数据
    /// </summary>
    /// <param name="option">
    ///     success: 获取用户数据成功回调[可选]
    ///         data: 用户数据
    ///             key: 用户数据key
    ///             value: 用户数据value
    ///     fail: 获取用户数据失败回调[可选]
    ///     complete: 获取用户数据完成回调[可选]
    /// </param>
    public static void GetUserData(GetGameDataOption option);

    /// <summary>
    /// 存储用户数据
    /// </summary>
    /// <param name="data">
    ///     key: 用户数据key，不要包含"."  
    ///     value: 用户数据value
    /// </param>
    public static void SetUserData(Dictionary<string, object> data)
  • 调用该接口，请务必提前与运营沟通，确定方案后使用
  • 存储接口，一分钟不能超过6次，请注意频率
  • 推荐的一种方案
// 启动游戏时，判断本地是否有数据
// 有则取本地数据
// 没有则取远程数据

// 游戏中，每分钟(建议1-3分钟)存档一次数据
// 如可以区分变动数据，每次也可以只上传有改动的数据，而不需要全量存档

个人信息上报 ​

Seeg.ReportUserInfo

SDK要求：>=1.0.7

该方法一般与排行榜功能同时使用

    /// <summary>
    /// 上报用户信息
    /// </summary>
    /// <param name="userInfo">
    ///     avatar: 头像
    ///     nickname: 昵称
    ///     gender: 性别
    /// </param>
    public static void ReportUserInfo(UserInfo userInfo);

排行榜功能 ​

SDK要求：>=1.0.7

排行榜分为两种类型：省份排行榜和个人排行榜。

省份排行榜 ​

    /// <summary>
    /// 获取用户所在省份
    /// </summary>
    /// <param name="option">
    ///     success: 获取用户所在省份成功回调[可选]
    ///         province: 省份
    ///         provinceCode: 省份编码
    ///     fail: 获取用户所在省份失败回调[可选]
    ///     complete: 获取用户所在省份完成回调[可选]
    /// </param>
    public static void GetUserProvince(GetProvinceDataOption option);

    /// <summary>
    /// 获取省份排行榜
    /// </summary>
    /// <param name="option">
    ///     type: 排行榜唯一标识[必填]
    ///     timeType: 刷新周期:TimeType.DAY(天)、TimeType.WEEK(周)、TimeType.MONTH(月)、TimeType.ALL(终身)[可选，默认为ALL]
    ///     round: 轮次 仅支持当前轮次0、上一轮次1[可选，默认为0]
    ///     success: 获取省份排行榜成功回调[可选]
    ///         list: 省份排行榜列表
    ///             province: 省份
    ///             provinceCode: 省份编码  
    ///             num: 上报总数
    ///     fail: 获取省份排行榜失败回调[可选]
    ///     complete: 获取省份排行榜完成回调[可选]
    /// </param>
    public static void GetProvinceList(GetProvinceRankOption option);

    /// <summary>
    /// 修改省份排行榜
    /// </summary>
    /// <param name="option">
    ///     type: 排行榜唯一标识[必填，该参数须与上报参数一致]
    ///     timeType: 刷新周期[可选，默认为ALL，该参数须与上报参数一致]
    ///     num: 增加数量[可选，默认为1]
    /// </param>
    public static void ChangeProvinceData(ProvinceRankOption option);
  • 同一个省份排行榜类型，上报次数可配置，默认不限制上传次数。

个人排行榜 ​

新版接口（推荐使用） ​
    /// <summary>
    /// 获取周期排行榜
    /// </summary>
    /// <param name="option">
    ///     type: 排行榜唯一标识[必填]
    ///     timeType: 刷新周期[可选，默认为WEEK]
    ///     round: 轮次 仅支持当前轮次0、上一轮次1[可选，默认为0]
    ///     success: 获取周期排行榜成功回调[可选]
    ///         list: 周期排行榜列表
    ///             uid: 用户ID
    ///             nickname: 昵称
    ///             avatar: 头像
    ///             num: 数量
    ///             rankData: 排名数据
    ///     fail: 获取周期排行榜失败回调[可选]
    ///     complete: 获取周期排行榜完成回调[可选]
    /// </param>
    public static void GetPersonRankList(GetRankOption option);

    /// <summary>
    /// 修改周期排行榜数据
    /// </summary>
    /// <param name="option">
    ///     type: 排行榜唯一标识[必填，该参数须与上报参数一致]
    ///     timeType: 刷新周期[可选，默认为WEEK，该参数须与上报参数一致]
    ///     num: 增加数量[可选，默认为1]
    ///     valueType: 值类型 1:累加 2:覆盖[可选，默认为2]
    ///     rankData: 排名数据[可选，默认为""]
    /// </param>
    public static void ChangePersonRankData(RankOption option);
旧版接口 ​
    /// 已废弃
    public static void GetRankList(GetRankOption option);

    /// 已废弃
    public static void ChangeDayRankData(RankOption option);

    /// 已废弃
    public static void ChangeWeekRankData(RankOption option);

    /// 已废弃
    public static void ChangeMonthRankData(RankOption option);

    //// 已废弃
    public static void ChangeLifeRankData(RankOption option);
  • 如果必须兼容老版本数据才使用该接口

直玩数据上报 ​

SDK要求：>=1.1.0

    /// <summary>
    /// 上报直玩数据到服务端（用于游戏内展示直玩入口）
    /// </summary>
    /// <param name="scene">
    ///     场景
    ///        1: 离线收益 
    ///        2: 体力恢复  
    ///        3: 重要事件
    /// </param >
    /// <param name="contentIds">
    ///     自定义文案contentID数组（需在后台申请开通直玩能力后获取）
    /// </param>
    /// <param name="timestamp">
    ///     可领取奖励的时间戳（毫秒单位），例如：体力满的时间/离线收益可领取时间
    /// </param>
    /// <param name="extra">
    ///     自定义扩展字段（对象格式），将在直玩启动参数中回传给游戏
    /// </param>
    public static void SetZWData(int scene, string[] contentIds, long timestamp, string extra);

下面，我们给出一种实现方式以供参考，请注意，以下代码仅为演示逻辑流程，代码为伪代码

// 在首页判断是否来自抖音推荐流直出
if(TT.GetLaunchOptionsSync().Scene.ToString().endsWith('3041')){ // 注意如果是重复可以进入的判断，则仅需判断第一次
    // 进入对应的界面
    // 如果有多种场景，也可以拿到query下的feed_game_scene 或 feed_game_extra 进行对应的跳转
}

// 在跳转成功后，一定要上报该接口
// 注意上报该接口后，抖音会停止网络相关的访问，所以要确保远程资源已经下载完毕
// 同时也只有在这个方法上报后，抖音才会显示直玩入口，所以也不建议太晚上报
var param = new JsonData();
int id = 7001;
long time = 100;
param["sceneId"] = id;
param["costTime"] = time;
TT.ReportScene(param);

// 在对应的界面，比如领取界面，进行授权判断
// 订阅单场景，我们一般建议在领取的时候弹出，然后顺便上报给服务器下一次领取的时间
var contentIDs = JsonData.NewJsonArray();
contentIDs.Add("CONTENT123");
contentIDs.Add("CONTENT234");
var param = new JsonData
{
    ["type"]: "play", // play=直玩
    ["scene"]: 1, // 一次只能订阅一个
    ["contentIDs"]: contentIDs,
};
// 如果选择的是all，则必须是用户主动操作的
 var param = new JsonData
{   
    ["type"]: "play", // play=直玩
    ["allScene"]: true, // 全场景订阅
};
TT.CheckFeedSubscribeStatus({
    param,
    success: (res) => {
        if (res.status) {
            // 已订阅回调
            return;
        }
        // 继续请求
        var param2 = new JsonData
        {   
            ["type"]: "play", // play=直玩
            ["allScene"]: true, // 全场景订阅
        };
        TT.RequestFeedSubscribe(param2, (res) => {
                if (res.success) {
                    // 订阅成功回调
                } else {
                    // 用户未订阅             
                }
            },
            fail: (errNo, errMsg) => {
                // 订阅失败                  
            }
        });

    },
    fail: (err: { errNo: number, errMsg: string }) => {
        // 查询失败                 
    }

// 订阅成功后，向服务器请求下次成功的领取时间
// 离线收益场景是1 体力恢复场景是2 重大时间提醒场景是3
Seeg.SetZWData(scene, new string[]{"CONTENT_ID"}, time);

// 如果需要统计从推荐流直出来的用户，可以使用tt.onFeedStatusChange接口监听

数数SDK (ThinkingData) ​

SDK要求：>=1.1.0

    /// <summary>
    /// 上报用户信息
    /// </summary>
    /// <param name="type">
    ///     类型
    ///         user_set：对用户表进行操作，覆盖一个或多个用户属性，如果该属性已有值存在，覆盖先前值
    ///         user_setOnce：对用户表进行操作，初始化一个或多个用户属性，如果该属性已有值存在，则忽略本次操作
    ///         user_add：对用户表进行操作，为一个或多个数值型用户属性做累加计算
    ///         user_unset：对用户表进行操作，清空该名用户的一个或多个用户属性的属性值
    ///         user_del：对用户表进行操作，删除该名用户
    ///         user_append：对用户表进行操作，为用户的列表类型属性值添加元素
    ///         user_uniq_append: 对用户表进行操作，为用户的列表类型属性值添加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变）
    /// </param>
    /// <param name="param">
    ///     key: 参数名
    ///     value: 参数值
    /// </param>
    public static void ReportUserInfo(string type, Dictionary<string, object> param);

    // <summary>
    /// 上报事件
    /// </summary>
    /// <param name="name">
    ///     事件名
    /// </param>
    /// <param name="param">
    ///     key: 参数名
    ///     value: 参数值
    /// </param>
    public static void ReportEvent(string name, Dictionary<string, object> param);

    /// <summary>
    /// 上报加载完成
    /// </summary>
    /// <param name="time">
    ///     加载时间
    /// </param>
    public static void LoadComplete(int time);
  • 如果要使用数数，则必须在SDK的初始化传入shushu参数为true
  • SDK已集成打点：注册、登录和在线，其它打点请参考数数打点模板

自定义网络请求 ​

    /// <summary>
    /// 请求接口
    /// </summary>
    /// <param name="router">
    ///     路由
    /// </param>
    /// <param name="param">
    ///     key: 参数名
    ///     value: 参数值
    /// </param>
    /// <param name="success">
    ///     成功回调
    /// </param>
    /// <param name="fail">
    ///     失败回调
    /// </param>
    public static void Req(string router, Dictionary<string, object> param, ZhiSe.Bridge.OnSuccess<string> success, ZhiSe.Bridge.OnFail fail);
  • 仅限用于访问服务器内部接口，不支持第三方服务器或其它网址、API访问

常见问题(FAQ) ​

  1. 抖音平台没有登录数据

    • 请先检查是否调用了TT.InitSDK(), 如果没调用 大于1.1.0版本（不含），请初始化传入autoInitPF参数为true 其它版本或autoInitPF参数为false，请先调用平台初始化，并回调后再调用sdk的初始化

  2. 提示非投放场景

    • 正常打印，无需关注

  3. 运营提示没有数据

    • 检查gid是否正确，例如是否填写成AppId
    • 检查是否调用了初始化接口
    • 是否调用了Seeg.reportAd方法

  4. 推荐流直出报错

    • 请联系运营，抖小开平后台设置是否正确
    • 请确保setZWData方法传入的content_id和scene与运营配置的一致

  5. 数数打点没有数据

    • 请确保开通了数数权限，必须找运营开通，每一个gid都需要单独处理
    • 初始化确认ssReport设置为true
    • 确认数数的域名已经添加到白名单：https://moderate.aslk2018.com