LAYABOX 引擎小游戏 SDK 使用指南

本文将会为您介绍如何使用 LAYABOX 引擎 SDK 接入您的项目。建议在接入开始前，先阅读数据规则一章，在了解 TA 数据规则后再进行接入。您可以在访问 GitHub (opens new window) 获取 LAYABOX 引擎小游戏 SDK 的源代码。

最新版本为: 1.6.0

更新时间为: 2020-06-10

下载地址 (opens new window)

# 1 集成 SDK

# 1.1 集成方法

1.下载并解压 LAYABOX SDK (opens new window)

2.引入 SDK 库

3.初始化 SDK

appid是您的项目的 APP_ID，需要进行配置，在您申请项目时会给出，请在此处填入 server_url为上传数据的 URL，需要进行配置 autoTrack表示是否开启自动采集功能，每一个元素分别代表如下的自动采集事件，默认全部关闭： appShow自动采集小游戏启动，或从后台进入前台 appHide自动采集小游戏从前台进入后台，并记录本次访问（启动至调入后台）的时间

关于自动采集事件的详细信息，可以查看自动采集事件一节

在上报数据之前，请先在微信公众平台或其他平台的开发设置中，将数据传输 URL 加入到服务器域名的 request 列表中

如果您使用的是云服务，请使用以下传输 URL:

https://receiver.ta.thinkingdata.cn

如果您使用的是私有化部署的版本，由于微信等平台的服务器域名中不能出现端口号，因此需要您自行配制域名，绑定 TA 私有化服务器的接收端。

在 config 中其他可选参数有：

# 1.2 使用 SDK 实例

在其他页面中，可以调用以下代码获取 SDK 实例：

# 1.3 初始化 SDK 实例

在 SDK 集成完毕之后，即可调用 SDK 方法，但只有调用了 init 之后，数据才会被上报，在调用 init 之前触发的数据（包括自动采集数据），将会被暂存，直到 init 被调用时才会上报，这些数据的上报时间为埋点触发时间，而非 init 被调用的时间

init 被调用时，会将 init 调用前设置的用户 ID 以及公共属性同步到被暂存的数据中，动态公共属性会在 init 时获取上传值加入到事件中，也就是说在 init 调用前设置的用户 ID 以及公共属性会对所有数据生效，因此如果您需要设置用户 ID 或公共属性，请在调用对应接口之后再进行初始化。

为了以避免重复用户的情况发生，如果您调用 authorizeOpenID 设置访客 ID，务必保证在初始化前先进行设置，即设置完用户 ID 后再初始化。

# 2. 设置用户 ID

在集成 SDK 之后，SDK 会使用 UUID 作为每个用户的默认访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，UUID 在用户更换设备及清理缓存时将会变更。

# 2.1 设置访客 ID

如果您希望使用其他 ID 来作为用户的访客 ID，您可以调用 identify 或者 authorizeOpenID 来设置访客 ID（两个方法是等价的，根据使用习惯保留两个接口名）：

需要注意以下几点：

设置后的 OpenID 将会被设置为访客 ID #distinct_id，如果使用 login 传入账号 ID，则根据用户识别规则，会优先以账号 ID 为准 如果需要进行设置，必须在 init 之前调用本接口

# 2.2 设置账号 ID

在用户产生登录行为时，可调用 login 来设置用户的账号 ID。TA 平台优先以账号 ID 作为身份标识，设置后的账号 ID 将会被保存，多次调用 login 将会覆盖先前的账号 ID：

请注意，该方法不会上传用户登录的事件

# 2.3 清除账号 ID

在用户产生登出行为之后，可调用 logout 来清除账号 ID，在下次调用 login 之前，将会以访客 ID 作为身份识别 ID：

请注意，该方法不会上传用户登出的事件

# 3. 发送事件

您可以直接调用 track 上传自定义事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：

track 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性 事件的名称是字符串，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。 事件的属性是 JS 对象，每个元素代表一个属性。 元素的 name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。 元素的 value 为该属性的值，支持 String、Number、Boolean、Date 和 Array.

注意: Array 类型属性需要配合 TA 平台 2.5 及之后的版本.

# 3.1 设置事件上报时间

事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：

第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间

# 3.2 记录事件时长

您可以调用 timeEvent 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 #duration 这一属性来表示记录的时长，单位为秒。

# 3.3 设置公共属性

对于一些重要的属性，譬如用户的设备 ID、来源渠道、用户状态等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共属性，即每个事件中都带有的属性。我们推荐您在发送事件前，先设置公共属性。

公共属性包含两种，事件公共属性和动态公共属性。在事件上报时，公共属性将会被插入到数据的 properties 中。如果此时公共属性与事件中设置的自定义属性有相同 key 值，则属性会根据下述优先级判断该取什么值：

用户自定义事件属性 > 动态公共属性 > 事件公共属性

# 3.3.1 设置事件公共属性

事件公共属性指的是静态的公共属性，在设置时只能传入常量，适合设置稳定不变的属性，您可以调用 setSuperProperties 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。

根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。

如果多次调用 setSuperProperties 设置公共事件属性，则同名字段后面的调用会覆盖之前的，不同名字段。

如果您需要清除公共事件属性，可以调用 clearSuperProperties 将所有公共属性清除。

# 3.3.2 设置动态公共属性

动态公共属性会在事件上报时，执行一个 function ，并把返回值作为该动态公共属性的值，加入到事件中。您可以调用 setDynamicSuperProperties 接口设置动态公共属性。该接口接受一个 function 作为参数。

function 必须返回一个 JS 对象，其中每个元素代表一个属性。 属性格式要求与事件属性一致。

# 4. 用户属性

# 4.1 设置用户属性（userSet）

对于一般的用户属性，您可以调用 userSet 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性

与上传事件时的事件属性一致，此处传入的用户属性也是对象类型，name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感，value 为该属性的值，支持 String、Number、Boolean、Date 和 Array。

注意：Array 类型需要配合 TA 平台 2.5 及之后版本使用.

# 4.2 初始化用户属性（userSetOnce）

如果您要上传的用户属性只要设置一次，则可以调用 userSetOnce 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。

userSetOnce 的参数要求与 userSet 一致。

# 4.3 累加用户属性（userAdd）

当您要上传数值型的属性时，您可以调用 userAdd 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算

与上传事件时的事件属性一致，此处传入的用户属性也是对象类型，name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感，value 为该属性需要累加的值，只支持 Number 类型，传入负数相当于做减法。

# 4.4 重置用户属性（userUnset）

当您要清空用户的某个用户属性值时，您可以调用 userUnset 来对指定属性进行清空操作，如果该属性还未在集群中被创建，则 userUnset 不会创建该属性

# 4.5 删除用户（userDel）

如果您要删除某个用户，可以调用 userDel 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

# 4.6 为 Array 类型的用户属性追加元素 (userAppend)

您可以调用 userAppend 对 Array (List) 类型的用户数据追加元素。

注意：该特性需要配合 TA 平台 2.5 及之后版本使用

# 5. 自动采集事件

在创建实例的 config 中开启您需要自动采集的事件，SDK 将会自动采集小游戏的一些行为，现在主要有以下几种事件支持自动采集：

现在支持的自动化收集数据有：

小游戏回到前台的事件 小游戏调入后台，并记录本次访问（启动至调入后台）的时间

接下来将会详细介绍每种数据的采集方法

# 5.1 开启自动采集事件

在 config 中，参数 autoTrack 中的元素表示每个自动采集事件的开关，设置为 true 为开启自动采集：

appShow：自动采集小游戏启动，或从后台进入前台 appHide：自动采集小游戏从前台进入后台

# 5.2 自动采集事件详解

# 5.2.1 小游戏启动

小游戏启动将会在小游戏被启动、或小游戏被从后台调回前台时触发，详细的事件介绍如下：

事件名：ta_mp_show 自动采集属性： #scene，场景值，取自微信提供的场景值

小游戏启动由于会受到调出前后台的影响（条数较多），因此不太适合直接进行分析，但是可以在行为路径中标识用户的一次使用，可以作为用户行为路径的初始行为

# 5.2.2 小游戏隐藏

小游戏隐藏将会在小游戏被调入后台时触发，并记录本次使用的时长，详细的事件介绍如下：

事件名：ta_mp_hide 自动采集属性： #scene，场景值，取自微信提供的场景值 #duration，数值型，表示本次启动（ta_mp_show）到隐藏的持续时长

小游戏隐藏事件会记录使用时长（单位为秒），因此可以直接计算用户使用总时长以及人均时长，也可以除以初始化次数计算单次使用时长。

# 6. 其他功能

# 6.1 多实例

本 SDK 支持多实例。我们称通过上文描述的方法完成初始化的实例 ta 为主实例，通过本节描述的方法创建的实例为子实例。

多个实例之间共享设备相关的预置属性（包括设备 ID），其他的属性均不共享，包括：

#distinct_id 访客 ID #account_id 账号 ID 公共事件属性、动态公共属性 timeEvent 监控的事件

您可以通过创建子实例，向另一个项目中上报数据，或者以另一套用户 ID 上报数据。

# 6.2 获取设备 ID

您可以调用 getDeviceId() 获取设备 ID，由于运行环境的原因，设备 ID 会保存在本地缓存，一旦用户删除缓存，则设备 ID 将会变更，因此设备 ID 不能保证稳定不变

# 6.3 onCompelete 回调函数

对于 track, userSet, userSetOnce, userAdd, userDel 等接口，支持传入 onComplete 回调. 可以直接在原参数列表后传入 onComplete, 也可以使用参数对象的方式. 如果使用参数对象，参数对象中必须包含 onComplete, 否则会出现参数错误.

以上传事件为例：

onComplete 的参数 res 为 object 类型，有两个属性 code 和 msg.

res.code 为 int 类型，定义如下:

0: 成功 -1: 数据格式不正确 -2: APP ID 无效 -3: 网络或服务端异常

Debug 模式定义如下:

0: 成功 -1: 参数或者权限校验的问题 1: 表示字段基本的错误, 会给出详细的错误字段和原由 2: 表示整条错误 -3: 网络或服务端异常

res.msg 是对 res.code 的文字说明。

# 6.4 开启 Debug 模式

从 v1.6.0 版本开始，客户端 SDK 支持 Debug 模式，需要配合 TA 平台 2.5 之后的版本使用。

Debug 模式可能会影响数据采集质量和 App 的稳定性，只用于集成阶段数据验证，不要在线上环境使用。

当前 SDK 实例支持三种运行模式：

"none": 不开启 Debug "debug": 开启 Debug 模式，并入库 "debugOnly": 开启 Debug 模式，不入库

SDK 初始化：

为了避免 Debug 模式在生产环境上线，规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式，并且设备 ID 在 TA 后台的"埋点管理"页的"Debug 数据"板块中配置了的设备才能开启 Debug 模式。

设备 ID 可以通过以下三种方式获取：

TA 平台中事件数据中的 #device_id 属性 通过实例接口调用：获取设备 ID

# 7. 相关预置属性

# 7.1 所有事件带有的预置属性

以下预置属性，是小游戏 SDK 中所有事件（包括自动采集事件）都会带有的预置属性

属性名 中文名 说明 #ip IP 地址 用户的 IP 地址，TA 将以此获取用户的地理位置信息 #country 国家 用户所在国家，根据 IP 地址生成 #country_code 国家代码 用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成 #province 省份 用户所在省份，根据 IP 地址生成 #city 城市 用户所在城市，根据 IP 地址生成 #device_model 设备型号 用户设备的型号，如 iPhone 8 等 #device_id 设备 ID 用户的设备 ID，取初始化时生成的 UUID #screen_height 屏幕高度 用户设备的屏幕高度，如 1920 等 #screen_width 屏幕宽度 用户设备的屏幕高度，如 1080 等 #manufacturer 设备制造商 用户设备的制造商，如 Apple，vivo 等 #os_version 操作系统版本 iOS 11.2.2、Android 8.0.0 等 #os 操作系统 如 Android、iOS 等 #network_type 网络状态 上传事件时的网络状态，如 WIFI、3G、4G 等 #lib SDK 类型 您接入 SDK 的类型，如 MG（小游戏） #lib_version SDK 版本 您接入 SDK 的版本 #scene 场景值 微信小游戏启动时传入的场景值 #mp_platform 小游戏平台 标识应用所在的平台 #zone_offset 时区偏移 数据时间相对 UTC 时间的偏移小时数

# 7.2 自动采集事件的预置属性

以下预置属性，是各个自动采集事件中所特有的预置属性

小游戏隐藏（ta_mp_hide）的预置属性 属性名 中文名 说明 #duration 事件时长 表示本次启动 ta_mp_show 到隐藏 ta_mp_hide 的持续时长，单位是秒

# Release Note

v1.6.0 2020/06/10

支持 debug 模式

v1.5.1 2020/03/21

支持白鹭引擎小游戏平台：微信小游戏、百度小游戏、QQ 小游戏、VIVO 小游戏、OPPO 小游戏 支持 LAYABOX 引擎小游戏平台：微信小游戏、百度小游戏、QQ 小游戏、VIVO 小游戏、OPPO 小游戏 支持 CocosCreator 引擎小游戏平台：微信小游戏、百度小游戏、VIVO 小游戏、OPPO 小游戏

相关知识

LAYABOX 引擎小游戏 SDK 使用指南
小程序/小游戏 SDK 使用指南
该如何选择小游戏开发引擎？
腾讯广告小游戏SDK重磅发布
小游戏 SDK
近期发布微信小游戏的流程与心得：引擎选择、资源分包、软著申请、SDK接入及审核流程
微信SDK安装
游戏盾 隧道加密 sdk
小游戏2.0时代来临！FinClip实时内容互动引擎引领新风尚
小游戏2.0时代来临，FinClip实时互动引擎引领新变革

网址: LAYABOX 引擎小游戏 SDK 使用指南 http://www.hyxgl.com/newsview358415.html