Node.js SDK 使用指南

本指南将会为您介绍如何使用Node.js SDK接入您的项目。您可以在访问GitHub获取Node.js SDK的源代码。

最新版本为：1.1.2

更新时间为：2020-09-08

1. 集成 SDK

1.1 安装 SDK

请使用npm获取Node.js SDK：

# 获取 SDK
npm install thinkingdata-node --save

1.2 创建 SDK 实例

首先在代码文件开头引入 thinkingdata-node：

var ThinkingAnalytics = require('thinkingdata-node')

为使用 SDK 上传数据，需首先创建 SDK 实例. 我们提供了三种 SDK 实例的初始化方法:

// Debug Mode: 逐条发送，并返回详细的错误信息
var ta = ThinkingAnalytics.initWithDebugMode('APP-ID', 'https://SERVER_URL');

//如果希望仅仅校验数据格式而不真正入库，可以通过 config 传入:
//config = {
//    dryRun: true
//};
//var ta = ThinkingAnalytics.initWithDebugMode('APP-ID', 'https://SERVER_URL',config);

// Batch Mode：批量发送到接收端
var ta = ThinkingAnalytics.initWithBatchMode('APP-ID', 'https://SERVER_URL');

//也可配置初始化发送：
//config = {
//    batchSize: 2,//设置flush数据
//    compress :false//默认true 代表gzip压缩，false适合在内网设置
//}
//var ta = ThinkingAnalytics.initWithBatchMode('APP-ID', 'https://SERVER_URL',config);  
//

// Logging Mode: 将数据写入本地日志文件，需要配合 LogBus 使用
var ta = ThinkingAnalytics.initWithLoggingMode('/PATH/TO/DATA');

三种模式说明如下:

(1) Debug Mode: 逐条实时向 TA 服务器传输数据，当数据格式错误时会返回详细的错误信息。建议先使用 DebugConsumer 校验数据格式。初始化传入项目 APP ID 和接收端地址。

(2) Batch Mode: 批量实时地向 TA 服务器传输数据，不需要搭配传输工具。在网络条件不好的情况下有可能会导致数据丢失，因此不建议在生产环境中大量使用。初始化传入项目 APP ID 和接收端地址。

Batch Mode 会先将数据存放在缓冲区中，当数据条数超过设定的值(batchSize, 默认为20)，触发上报. 您也可以在初始化 SDK 的时候指定传入配置：

// 初始化 SDK, 指定接收端地址、APP ID、缓冲区大小
var ta = ThinkingAnalytics.initWithBatchMode('APP-ID', 'https://SERVER_URL', {
    batchSize: 10, // 缓存数据到达 10 条时触发上报
    enableLog: true // 允许打印发送数据. 当开启日志的时候会打印详细的发送日志
    });

(3) Logging Mode: 将数据实时写入本地文件，文件以天/小时切分，并需要与 LogBus 搭配使用进行数据上传，建议在生产环境使用。

Logging Mode 使用 log4js 将数据实时保存为本地日志文件，后续需要配合 LogBus 将日志文件导入到 TA 数据库中。默认情况下日志按天切分。如果应用运行在 pm2 模式下，需要传入对应的配置，并且安装 pm2-intercom: pm2 install pm2-intercom

可以在初始化 SDK 的时候传入 config 对象. config 对象支持的参数有：

  • rotateHourly: false(默认) 按天切分；true 按小时切分.
  • pm2: 当使用 pm2 的时候，需要设置
  • pm2InstanceVar: 默认为 'NODE_APP_INSTANCE', 如果改变了该配置，需要传入对应的变量名
// 初始化 SDK，按小时切分日志文件.
var ta = ThinkingAnalytics.initWithLoggingMode('.', { rotateHourly: true});

2. 上报数据

SDK 初始化完成后，后续即可使用 ta 的接口来上报数据。

2.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 个字符，对字母大小写不敏感
  • 事件的属性是 map 类型，其中每个元素代表一个属性
  • 事件属性的 Key 值为属性的名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感
  • 事件属性的 Value 值为该属性的值，支持 string、数值类型、bool、Date、数组类型

SDK 会在本地对数据格式做校验，如果希望跳过本地校验，可以在调用 track 接口的时候传入 skipLocalCheck 参数:

// 跳过本地数据校验
ta.track(event, true);

2.2 设置公共事件属性

公共事件属性是每个事件都会包含的属性，普通的公共属性是定值，您也可以设置动态公共属性，该属性将会在事件上报时取值并加入到事件中。如果有相同的属性，则动态公共属性会覆盖公共事件属性。


// 设置动态公共属性
ta.setDynamicSuperProperties(()=>{
    var date = new Date();
    date.setYear(2018);
    return {
        super_date: date,
        super_int: 5,
    }
});

// 设置公共事件属性
ta.setSuperProperties({
    super_int: 8, // 不会出现在最终上报数据，因为会被动态公共属性覆盖.
    super_debug_string: 'hahahaha',
});

// 清空公共事件属性
ta.clearSuperProperties();

2.3 设置用户属性

a) userSet

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

// 用户属性数据
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);
b) userSetOnce

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

ta.userSetOnce(userData);
c) userAdd

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

// 累加用户属性
ta.userAdd({
    accountId: 'node_test',
    properties: {
        Amount: 222,
    }
});
d) userDel

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

// 删除用户
ta.userDel({
    // 账号 ID （可选)
    accountId: 'node_test',
    // 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
    distinctId: 'node_distinct_id',
});
e) userAppend

当您要为 array 类型追加用户属性值时，您可以调用user_append来对指定属性进行追加操作，如果该属性还未在集群中被创建，则user_append创建该属性

// 为用户列表类型追加属性 key - array ,array 为string数组
ta.userAppend({
    accountId: 'node_test',
    properties:{
      prop_array:['str3','str4']
    }
});
f) userUnset

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

//删除用户某一个属性
ta.userUnset({
    accountId: 'node_test',
    property: 'prop_double'
});

3.其他操作

3.1 立即进行数据 IO

此操作与具体的 Consumer 实现有关. 在收到数据时, Consumer 可以先将数据存放在缓冲区, 并在一定情况下触发真正的数据 IO 操作, 以提高整体性能. 在某些情况下需要立即提交数据，可以调用 Flush 接口：

// 立即提交数据到相应的接收端
ta.flush();

3.2 关闭 SDK

请在退出程序前调用本接口，以避免缓存内的数据丢失:

// 关闭并退出 SDK
ta.close();

3.3 打开日志

设置环境变量 NODE_DEBUG=tda, 可以打开日志.

ChangeLog

v1.1.2 (2020-09-08)

  • 解决只传入 distinctId 不生效的问题

v1.1.1 (2020-04-14)

  • 修复上报地址不支持端口号的bug

v1.1.0 (2020-02-12)

  • 支持上报数组类型
  • 新增 user_append 接口，支持用户的数组类型的属性追加
  • DebugConsumer 优化: 在服务端对数据进行更完备准确地校验
  • BatchConsumer 性能优化：支持配置压缩模式；移除 Base64 编码

v1.0.1 (2019-11-07)

  • 支持三种模式的上报: Debug, Batch, Logging.
  • 支持事件上报和用户属性上报.
  • 支持公共事件属性和动态公共事件属性.

results matching ""

    No results matching ""