说明
这是小游戏SDK新版集成文档,包含:
如果想继续查看旧版文档,请点击这些链接:小游戏SDK集成
文档导读
以下为您概要介绍小游戏端SDK集成相关文档的组织思路,您可参考以下导读示意图了解文档结构,查阅对应文档完成SDK集成操作。
埋点规划
在进行SDK集成前,您需结合您的业务分析情况先进行埋点规划,明确出待分析的业务指标中可能需要埋点的事件有哪些、属性有哪些等。进行埋点规划时,您需了解一些基本概念和DataFinder为您预置提供的埋点事件和属性、DataFinder的用户标识逻辑等前置信息,结合DataFinder为您提供的能力进行埋点规划。
基本概念 基本概念
概念说明
埋点规划与SDK集成要点
详细指导文档
事件、事件属性、事件公共属性、用户属性
DataFinder的用户行为数据分析是基于事件+用户模型的分析模型。
事件&事件属性:用户的某一种或一类行为称之为“事件”,事件属性即事件触发时同步采集的事件发生的形式、位置等用来描述事件的信息。例如,某个用户购买了某个商品,则该用户的行为事件为“购买”,事件属性为“商品名称”、“商品分类”、“支付金额”等。 事件公共属性:指不与某个事件强关联、在多个或所有事件中都共同存在的属性,例如,应用的版本号、设备信息等。 用户&用户属性:用户指的是事件行为的发生主体人。用户属性指的是用户自身状态的属性(与行为无关,例如年龄、性别等)或与行为有关但不常变化的用户相关属性(如VIP等级、注册时间等)。 您需根据业务分析需要,规划好待采集的事件、事件属性、用户属性有哪些、类型是什么,进行SDK集成时
详细概念介绍请参见数据模型 。
埋点、全埋点、自定义埋点
埋点:通过SDK的开发,将事件逻辑写入代码的过程,称之为埋点 。DataFinder为您提供了预置事件及事件属性,这类事件及事件属性无需您手动埋点,只需打开采集开关即可。 全埋点:是DataFinder提供的预置事件和事件属性的一种,在DataFinder中,采集的全埋点事件为bav2b_click按钮点击, bav2b_page页面浏览。不需要研发额外投入,但会以上报大量数据为代价,并且只可以采集简单的PV、UV,对于丰富业务数据的采集显得有些‘力不从心’。 代码埋点:代码埋点指的是开发工程师,按照业务个性化需求,人工写入代码中以实现数据采集逻辑。采集范围广、应用灵活。但需要研发投入,且需要一定的技术能力。 通常建议您结合DataFinder提供的预置事件/属性和自定义埋点进行埋点规划。
埋点、全埋点
了解数据上报要求(格式、数量限制等) 进行埋点规划时,您需明确清楚需采集上报的事件、属性的数据格式要求,以及采集上报的一些限制要求,避免后续因为数据格式等不满足要求,进而导致数据采集后无法入库、后续无法查询分析。
SDK上报的数据通常有固定的格式,主要包括user
、header
、events
三个部分。
字段
作用
小游戏端数据示例
user
存放用户属性数据,比如web_id、user_unique_id这些重要属性。
[
{
events: [
{
event: 'app_launch',
params: '{"path":"pages/index/index",……}',
local_time_ms: 1745897787714,
session_id: 'd8b28410-6079-42da-***',
},
{
event: 'predefine_pageview',
params: '{"scene":1001,……}',
local_time_ms: 1745897787756,
session_id: 'd8b28410-6079-42da-9f91-5a49d6ffb01f',
},
],
user: {
web_id: '7498573*****',
user_unique_id: 'zhangsan',
},
header: {
app_id: 0,
app_version: '',
os_name: 'devtools',
os_version: 'iOS 10.0.1',
// ……
custom: {
custom_platform: 'miniProduct',
mp_platform: '0',
mp_platform_app_version: '8.0.5',
// ……
},
// ……,
},
},
]
header
存放事件公共属性。
app_id、os_name这些都是预置的,会直接放在header下,如果是您自定义设置的事件公共属性,会放到header.custom下。
events
存放事件及事件属性。
本身是一个数组,支持携带多个事件。
每个事件都有event、params、local_time_ms、session_id几个字段,其中local_time_ms、session_id是SDK自动产生的,而event、params是业务设置的,event是事件名,params存放的是事件属性(值是JSON对象进行了序列化操作)。
其中,需要上报自定义事件、自定义属性时,您需确保事件和属性的数据格式符合要求,当前DataFinder支持的数据格式要求和数据上报的限制请参见支持的数据格式与事件/属性分类 。
常见问题:
了解用户标识逻辑 进行埋点规划时,您需要了解DataFinder的用户标识逻辑,用于结合自身业务的用户标识逻辑进而最终统一用户的标识数据来源。DataFinder默认以用户 作为统计分析的对象,默认使用ssid作为用户唯一标识ID来计算指标,此时用户的SSID就是默认的统计口径。当您的分析对象为用户时,建议保持默认统计口径ssid,DataFinder可通过ID_Mapping将用户的device_id/web_id、user_unique_id等进行mapping后,尽量通过一个ssid还原一个真实的用户个体。
device_id 、web_id 、anonymous_id :均可作为设备的唯一id,多为无法获取用户实名id的场景下使用。user_unique_id :为登录态用户标识,多为在能获取用户实名ID场景下使用,一般情况直接使用产品业务中使用的用户标识,比如登录账号。当 user_unique_id 未设定时,在SaaS版本中,系统会自动使用 device_id/web_id 替代。ssid :为DataFinder的用户统计口径ID,与设备标识device_id/web_id、登录态用户标识user_unique_id 互相Mapping,能保证用户匿名和实名状态下的ID统一。三类ID的mapping逻辑和更多关于用户标识的介绍详情请参见支持的用户唯一标识 。
说明
如果您的业务中用户实名ID有多种ID类型,例如,可通过账号ID、用户手机号等多种ID类型来标注用户的实名信息,您也可以使用多ID类型功能,详情请参见使用多ID类型 。
了解小游戏端的SDK包结构 在进行小游戏端的埋点规划和集成前,您可以先了解一下DataFinder的小游戏端SDK包的结构和能力范围,便于您在规划和集成埋点时有更清晰的思路。详情请参见参考:小游戏SDK包文件结构说明
梳理埋点需求设计埋点方案
准备工作
步骤1(可选):创建埋点需求/录入自定义埋点 完成埋点规划后,建议您根据规划将埋点需求创建再DataFinder的需求管理页面,并将自定义埋点先录入DataFinder完成自定义埋点在DataFinder元数据的入库。
埋点需求管理:您可以通过DataFinder的埋点需求管理功能来管理埋点需求,后续可在埋点需求管理页面中持续维护和管理需求,提高管理效率。创建埋点需求管理的操作请参见需求管理 。 自定义埋点录入:您可以根据埋点规划,先将自定义埋点创建录入至DataFinder的元数据,操作详情请参见新增事件 、新增事件属性 、新增用户属性 。
步骤2:获取APPID 在开始集成前,首先需要在集团中拥有一个应用,进行 SDK 集成前,您需要获取对应应用的 appid 信息。
SaaS-云原生场景下,您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid,详情请参见项目管理 。 SaaS-非云原生场景下,您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid,详情请参见应用列表 。
步骤3:获取上报地址并配置小游戏白名单 进行数据接入上报时,您需要根据当前的环境类型和端类型确认您的数据上报地址,将数据上报地址添加到小游戏后台的“request合法域名”中,如果上报地址设置错误,后续会导致您无法正常上报、查询到数据。
获取数据上报地址 注意
请在上报数据前,务必确认您当前使用的环境类型,根据环境类型配置上报地址。查看当前的环境类型请参见SaaS云原生/非云原生&私有化环境 。 如果您使用的是SaaS-云原生环境,您也需确认您的服务所在的地域,根据所在地域配置上报地址(通常您的服务会在华北2-北京地域,部分用户可能会使用其他地域)。SaaS-云原生用户查看服务所在地域请参见支持的地域 。
SaaS-云原生 & SaaS-非云原生 地址类型
SaaS-云原生环境
(国内:华北2-北京&华南1-广州)
SaaS-云原生
(海外:亚太东南-柔佛)
SaaS-非云原生环境 国内环境
SaaS-非云原生 海外BytePlus环境
(以下 SG 指新加坡)
数据上报地址
(channel_domain)
SaaS-云原生(华北):https://gator.volces.com SaaS-云原生(华南):
https://gator.uba.cn-guangzhou.volces.com 需在小游戏中添加对应上报地址至小游戏的白名单中 https://gator.uba.ap-southeast-1.volces.com 需在小游戏中添加白名单:https://gator.uba.ap-southeast-1.volces.com channel: 'cn'
需在小游戏中添加白名单:https://mcs.volceapplog.com channel: 'sg'
需在小游戏中添加白名单:https://mcs.tobsnssdk.com 分流地址
(ab_channel_domain,仅开启A/B实验时需配置)
https://tab.volces.com 需在小游戏中添加对应地址至小游戏的白名单中 https://tab.ab.ap-southeast-1.volces.com 需在小游戏中添加对应地址至小游戏的白名单中 无需手动配置
无需手动配置
私有化环境 私有化部署场景下,您需要获取部署私有化环境时,自行规划配置的数据上送地址,将私有化部署的数据上报域名添加到小游戏后台的“request合法域名”中。如您不清楚此地址,请联系您的项目经理或客户成功经理。
配置小游戏白名单 在 「小游戏后台-开发-开发设置-服务器域名」 中进行配置,具体可以参考小游戏相应的官方文档,如 微信小游戏网络使用说明 。
集成SDK
(可选)下载示例demo 以下为您提供了一个简单的微信小游戏开发包作为示例demo,下文的SDK集成操作指导也基于此demo,您可先下载demo文件用于学习了解小游戏SDK的集成操作。
注意:使用demo时请将其中的app_id和channel_domain更换成自己的。
step1:安装SDK 您可以使用npm方式安装小游戏端SDK。
操作指导
操作录屏
npm install @datarangers/sdk-qg
注意
请在小游戏开发者工具的“终端”面板中执行npm相关命令。如果执行npm时提示命令不存在等错误信息,请先安装node(具体如何安装node,请参考node官网文档)。 如果项目本身还不支持安装第三方npm包,可以使用npm init相关命令将项目变成支持安装第三方npm包。
step2:初始化SDK:基于小游戏原生平台 初始化SDK时,通常您需要调用SDK的核心API(init、config、event等接口),用来实现采集上报预置事件和属性数据、采集上报自定义事件和数据、定义用户的ID标识字段等。
通常建议小游戏SDK集成时参考以下流程:
导入并初始化 ---> 上报自定义事件 ---> 设置自定义用户 ---> 设置上报域名
以下为一个简单的集成SDK代码示例,您可通过此示例来快速了解SDK集成时的代码结构、涉及的核心接口、典型的配置参数等,后续步骤中会为您逐步介绍SDK集成的详细操作要点。
// 入口文件 game.js
import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';
$$sdk.init({ //调用init接口初始化SDK,配置初始化参数
// 请更换成自己的app_id
app_id: 0,
// channel_domain用于设置数据上报域名,SaaS-云原生环境和私有化环境需设置,示例设置结果假设是SaaS-云原生华北地域环境
channel_domain: 'https://...',
log: true,
});
$$sdk.send(); //当init初始化调用之后,需要调用send方法,SDK才开始上报事件。
// 使用setTimeout模拟异步设置,真实情况由业务自己决定
setTimeout(() => {
// 调用config接口设置自定义用户,假设设置的值是zhangsan,真实场景这个值一般是从业务的服务接口获取到的
$$sdk.config({
user_unique_id: 'zhangsan'
});
}, 1000);
new Main();
// main.js
import $$sdk from '@datarangers/sdk-qg';
export default class Main {
constructor() {
// ...
}
start() {
// ...
// 调用event接口上报自定义事件和事件属性
$$sdk.event('test', {
abc: 123,
});
}
}
以下以小游戏原生平台场景、开发工具提供的默认模版项目进行示例,为您逐步演示大部分场景下初始化SDK的代码接入。
导入并初始化 找到入口文件,如demo中的game.js,在入口文件的App全局配置前嵌入以下初始化SDK的代码。
操作指导
操作录屏
import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';
$$sdk.init({
// 请更换成自己的app_id
app_id: 0,
log: true,
});
$$sdk.send();
new Main();
注意
操作要点:
如果提示“无法发现@datarangers/sdk-qg”等错误,需要执行“构建npm”。 如果提示“不支持export”等错误,需要在开发者工具的详情下本地设置中勾选“将JS编译成ES5”。
涉及核心API:
init:对SDK实例进行初始化配,init接口中需要指明数据上报的appid信息,并配置是否开启日志等初始化参数。全量init接口的参数介绍请参见init 。 send:当init初始化调用之后,需要调用send方法,SDK才开始上报事件。在调用send方法之前,不会有事件上报。更多关于send方法的介绍请参见send 。
上报自定义事件 根据埋点规划,如果需要采集上报自定义事件,您可以调用“event”方法设置自定义事件名和事件属性。
操作指导
操作录屏
在主入口文件(demo中的game.js文件)中初始化,操作与上述步骤类似
import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';
$$sdk.init({
// 请更换成自己的app_id
app_id: 0,
log: true,
});
$$sdk.send();
new Main();
在另外的文件中,比如main.js
import $$sdk from '@datarangers/sdk-qg';
export default class Main {
constructor() {
// ...
}
start() {
// ...
// 调用event接口上报自定义事件和事件属性
$$sdk.event('test', {
abc: 123,
});
}
}
涉及核心API:
event:使用event方法可以上报自定义事件。该方法支持单个事件方式和批量事件方式上报,以上为一个单个事件上报的示例,更多event接口的参数说明和使用示例请参见 event 。
设置自定义用户 如果需要设置自定义用户,可以调用config方法设置user_unique_id属性。
通常对于需要用户实名登录时,业务上会使用一个ID来唯一标识这个用户,您可以通过config方法上报对应的业务的用户标识ID,上报为user_unique_id的取值。通常这个取值可以通过业务接口获取,或者直接读取已有的固定用户标识ID值,以下以上报固定取值作为示例。
操作指导
操作录屏
import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';
$$sdk.init({
// 请更换成自己的app_id
app_id: 0,
log: true,
});
$$sdk.send();
// 使用setTimeout模拟异步设置,真实情况由业务自己决定
setTimeout(() => {
// 调用config接口设置自定义用户,假设设置的值是zhangsan,真实场景这个值一般是从业务的服务接口获取到的
$$sdk.config({
user_unique_id: 'zhangsan'
});
}, 1000);
new Main();
说明
您可以在开发者工具的调试器下的Storage面板中查看“_tea_cache_tokens ${app_id}”的存储值,可以看到设置给user_unique_id的值。
涉及核心API:您可以通过config方法来设置用户的业务标识ID——user_unique_id,设置前您需要先了解DataFinder的用户标识逻辑(详情请参见支持的用户唯一标识 ),更多config接口的介绍和参数说明请参见config 。 更多场景实践参考:
设置上报域名 如果您当前的环境是SaaS-云原生环境或者私有化环境,您需要设置对应环境的数据上报域名,即在初始化时设置channel_domain。如果设置不正确后续会导致数据无法正常查询分析。
操作指导
操作录屏
import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';
$$sdk.init({
// 请更换成自己的app_id
app_id: 0,
// 假设是云原生环境
channel_domain: 'https://gator.volces.com',
log: true,
});
$$sdk.send();
new Main();
操作要点:设置数据上报域名前,您需要先明确您使用的环境和所在的地域,根据实际情况设置上报域名。确认您当前使用的环境类型请参见:SaaS云原生/非云原生&私有化环境 ; 涉及核心API:您可以在init接口中:
通过设置channel_domain来设置上报域名,仅SaaS-云原生环境和私有化环境需要设置,SaaS-非云原生环境无需设置。 SaaS-非云原生的海外 BytePlus环境还需配置init接口中的channel字段为sg,其他环境无需配置channel字段。 如果您还开启了A/B实验的场景,您还需根据您使用的环境和所在的地域配置init接口中的A/B实验的分流地址(ab_channel_domain字段)。
更多关于init接口的介绍和参数说明请参见init 。
step3:初始化结果验证
使用小游戏开发工具 在初始化SDK时,您可以开启log: true
,此时会在控制台打印SDK的一些运行状态信息。可用于验证初始化是否成功
在小游戏开发工具的Console面板中,通过在过滤框中输入emit
关键词进行过滤,如果有emit $ready
这条日志,说明SDK初始化成功。
在Network面板中,可以看到SDK的事件上报请求,说明SDK初始化成功。同时观察请求的Request Payload正常,Response Body中e: 0
表明事件上报成功。 另外在Storage面板中,可以看到SDK存储的token,key叫__tea_cache_tokens_${app_id}
。
更多场景实践
采集上报自定义用户属性 如果您需要采集上报自定义用户属性数据,您需要在SDK初始化设置时,在init接口中开启相应参数:enable_profile: true
,然后调用用户属性模块API进行设置,详情请参见用户属性模块及API 。
更多场景实践 更多场景实践请参见小游戏SDK集成场景实践 。
埋点数据验证
完成初始化验证后,您可以在小游戏端进行测试操作,触发一些待采集上报的事件,测试事件上报后,大约15分钟内,您可以在增长分析平台
中的用户细查
页面查看具体用户行为流数据,即能看到测试事件及事件属性数据,用于验证埋点数据是否可正常采集上报。
用户细查页面中展示的用户行为流数据通常有固定的格式,主要包括user
、header
、events
三个部分,分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据,上报的数据包含了开启采集的预置和自定义的数据。 如果在用户细查处能看到对应事件,表明事件上报成功,通过观察事件的属性,可以确认相应属性是否也成功上报上来了。 如果数据没有正常在用户细查中查询到,您可检查一下:
小游戏SDK API列表
DataFinder为您提供了丰富的API接口,除了上述通用流程中介绍的核心接口和典型场景的使用示例外,您也可以了解当前小游戏支持的主要API接口和其作用,根据业务需求可灵活调用对应接口完成业务数据埋点。
分类
API列表
API说明
核心API
init
对SDK实例进行初始化配置的API。
send
当init初始化调用之后,需要调用send方法,SDK才开始上报事件。在调用send方法之前,不会有事件上报。
config
调用config对事件进行一些设置,比如设置公共属性、设置user_unique_id等。可以调用多次,后面设置会覆盖之前相同设置项。
event
使用event方法可以上报自定义事件。
模块API
AB实验模块及API
此模块提供AB实验能力,并提供了一系列的方法:getVar
、getAllVars
、getAbSdkVersion
、setExternalAbVersion
。
用户属性模块及API
此模块提供设置用户属性能力,并提供了一系列的方法:profileSet
、profileSetOnce
、profileUnset
、profileIncrement
、profileAppend
。
参考:SDK核心运行流程