# Node.js
本指南将会为您介绍如何使用 Node.js SDK 接入您的项目。
最新版本为:1.3.0
更新时间为:2022-04-27
# 一、集成SDK
- 请使用
npm
获取 Node.js SDK:
# 获取 SDK
npm install thinkingdata-node --save
# 更新 SDK
npm i thinkingdata-node@{版本号}
- 安装Logbus
我们推荐使用SDK+LogBus的形式,完成服务端数据的采集上报。您可以参考以下文档完成Logbus的安装:LogBus使用指南
# 二、初始化
以下是SDK初始化的示例代码:
var ta = ThinkingAnalytics.initWithLoggingMode(LOG_DIRECTORY);
LOG_DIRECTORY
为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址,即可使用 LogBus 进行数据的监听上传。
当您使用 pm2 管理工具时,请注意:
初始化 loggingMode 时请阅读 API 注释,添加 pm2 相关的参数:
/**
* write data to file, it works with LogBus
*
* The Logging Mode uses log4js to save data, you need to report data by LogBus.
*
* if run in pm2 mode, you need set config, and install pm2-intercom: pm2 install pm2-intercom
*
* config(optional) incloud:
* - rotateHourly: false(default) by the day; true by the hour.
* - filePrefix: file prefix
* - pm2: it need set when you run in pm2 mode
* - pm2InstanceVar: 'NODE_APP_INSTANCE' is default.
*
* @param {string} path
* @param {object} config
*/
initWithLoggingMode: function (path, config) {
return _createClient(LoggingConsumer.init(path, config));
},
初始化示例:
var ta = ThinkingAnalytics.initWithLoggingMode(LOG_DIRECTORY, {pm2: true});
# 三、常用功能
为了保证访客 ID 与账号 ID 能够顺利进行绑定,如果您的游戏中会用到访客 ID 与账号 ID,我们极力建议您同时上传这两个 ID,否则将会出现账号无法匹配的情况,导致用户重复计算,具体的 ID 绑定规则可参考用户识别规则一章。
# 3.1 发送事件
您可以调用track
来上传事件,建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件,以下是发送事件的示例代码:
// 定义事件数据
var event = {
// 账号 ID (可选)
accountId: "node_test",
// 访客 ID (可选),账号 ID 和访客 ID 不可以都为空
distinctId: "node_distinct_id",
// 事件名称 (必填)
event: "test_event",
// 事件时间 (可选) 如果不填,将以调用接口时的时间作为事件时间
time: new Date(),
// 事件 IP (可选) 当传入 IP 地址时,后台可以解析所在地
ip: "202.38.64.1",
// 事件属性 (可选)
properties: {
prop_date: new Date(),
prop_double: 134.1,
prop_string: "hello world",
prop_int: 67
},
// 出错时回调 (可选)
callback(e) {
if (e) {
console.log(e);
}
}
};
// 上传事件
ta.track(event);
- 事件的名称是字符串类型,只能以字母开头,可包含数字,字母和下划线 "_",长度最大为 50 个字符。
- Key 为该属性的名称,为字符串类型,规定只能以字母开头,包含数字,字母和下划线 "_",长度最大为 50 个字符,对字母大小写不敏感,TA会统一转化为小写字母
- Value 为该属性的值,支持字符串、数字、布尔、时间、对象、对象组、数组
用户属性的要求与事件属性保持一致
# 3.2 设置用户属性
对于一般的用户属性,您可以调用 user_set
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致,此处以设置用户名为例:
// 用户属性数据
var userData = {
// 账号 ID (可选)
accountId: "node_test",
// 访客 ID (可选),账号 ID 和访客 ID 不可以都为空
distinctId: "node_distinct_id",
// 用户属性
properties: {
prop_date: new Date(),
prop_double: 134.12,
prop_string: "hello",
prop_int: 666
},
// 出错时回调 (可选)
callback(e) {
if (e) {
console.log(e);
}
}
};
// 设置用户属性
ta.userSet(userData);
# 四、最佳实践
以下示例代码包含以上所有操作,我们推荐按照如下步骤使用:
var ta = ThinkingAnalytics.initWithLoggingMode(LOG_DIRECTORY);
// 定义事件数据
var event = {
// 账号 ID (可选)
accountId: "node_test",
// 访客 ID (可选),账号 ID 和访客 ID 不可以都为空
distinctId: "node_distinct_id",
// 事件名称 (必填)
event: "test_event",
// 事件时间 (可选) 如果不填,将以调用接口时的时间作为事件时间
time: new Date(),
// 事件 IP (可选) 当传入 IP 地址时,后台可以解析所在地
ip: "202.38.64.1",
// 事件属性 (可选)
properties: {
prop_date: new Date(),
prop_double: 134.1,
prop_string: "hello world",
prop_int: 67
},
// 出错时回调 (可选)
callback(e) {
if (e) {
console.log(e);
}
}
};
// 上传事件
ta.track(event);
// 用户属性数据
var userData = {
// 账号 ID (可选)
accountId: "node_test",
// 访客 ID (可选),账号 ID 和访客 ID 不可以都为空
distinctId: "node_distinct_id",
// 用户属性
properties: {
prop_date: new Date(),
prop_double: 134.12,
prop_string: "hello",
prop_int: 666
},
// 出错时回调 (可选)
callback(e) {
if (e) {
console.log(e);
}
}
};
// 设置用户属性
ta.userSet(userData);
//调用flush接口数据会立即写入文件,生产环境注意避免频繁调用flush引发IO或网络开销问题
ta.flush();