菜单

Node.js

更新时间：2024-12-10
⚠️ 此 SDK 需搭配 FileScout 使用

NPM Version

一、集成 SDK

  1. NPM
Bash 复制代码 
npm i @datatower-ai/sdk-core-nodejs

二、初始化

SDK 初始化示例代码

JavaScript 复制代码 
var dt = require("@datatower-ai/sdk-core-nodejs")

// Outputs to "log" folder in execution path with file prefix "dt_nodejs" 
// for every 200 events, the ideal maximum size for each log file is 10MB 
// (will be larger if size of a single event is over such limit).
let consumer = dt.Consumer.DTLogConsumer("./log", 200, "dt_nodejs", 10*1024*1024)
dt.init(consumer, false)

三、基础功能

事件上报和用户属性的所有接口会对事件名/属性名/类型进行校验

  • 如果校验通过会返回 true，并进行记录上报
  • 未通过则会返回 false，不进行记录上报

3.1 设置事件上报

数据说明文档：当您将要上报的事件/属性在数据说明文档中已存在时，强烈建议您使用文档中的对应属性名，比如您要上报 APP 的操作系统属性，请使用文档里预置的属性名”#os”，不要自定义取名，避免跟客户端上报的预置属性不一致 
用户识别规则：为了让访客 ID（dt_id）与帐号 ID（acid）能够顺利绑定，其中访客 ID（dt_id）为必填

该接口是使用最频繁的接口，通过调用 track 来上报自定义事件，在上报事件之前，建议您根据梳理的文档来设置事件属性，以下是示例代码：

TypeScript 复制代码 
var acId = "account_id_111";
var dt_id = "dt_id_222";

var properties = {
    "#app_id": "appid_1234567890",
    "#bundle_id": "com.example.app",
    "#os": "android",
    "user_level": 20,
    "coin": 1000,
    "from": "entry"
};

dt.track(acId, dt_id, "eventName", properties);

注意：

  1. 以#开头命名的事件/属性，必须按照预置事件/属性规则进行上报，否则将无法上报
  2. 以$开头的事件/属性都被视为非法字段，将无法上报

3.2 设置用户属性

DT 系统支持的用户属性设置类型总览说明如下

操作 对应事件名 处理规则
覆盖用户属性 #user_set 对用户表进行操作，覆盖用户的原有属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与覆盖操作传入属性的类型一致
初始化用户属性 #user_set_once 对用户表进行操作，初始化用户属性，如果该属性已有值存在，系统忽略本次操作
累加用户属性 #user_add 对用户表进行操作，对数值型的用户属性做累加计算，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值等同于相减操作
清空用户属性值 #user_unset 对用户表进行操作，清空用户属性的属性值，即设置成 NULL，如果被清空的属性不存在也不会新建该属性
追加列表型用户属性的元素 #user_append 对用户表进行操作，对列表类型的用户属性追加元素，如果被追加的列表属性不存在，系统将自动生成并进行追加
追加并去重列表类型用户属性的元素 #user_uniq_append 对用户表进行操作，对列表类型的用户属性值追加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变），如果被追加的列表属性不存在，系统将自动生成并进行追加再去重
删除用户 #user_delete 对用户表进行操作，删除对应用户，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

3.2.1 userSet

userSet 是常用的功能，您可以调用它来进行用户属性的设置，调用该操作时，会覆盖原有的属性值，如果用户不存在该属性，则会创建新用户属性，类型与传入属性的类型一致

TypeScript 复制代码 
properties = { "name": "abc" };
# 设置用户属性，"name" 的值为 "abc"
dt.userSet(acid, dt_id, properties);

properties = { "name": "xyz" };
# 再次设置用户属性，此时 "name" 的值会被覆盖为 "xyz"
dt.userSet(acid, dt_id, properties);

3.2.2 userSetOnce

如果您希望用户属性只设置一次，则可以调用 userSetOnce 进行设置，当该属性没有值时，则会创建该属性并赋值，但该属性已经有值时，将不会设置成功

TypeScript 复制代码 
properties = { "name": "abc" };
# 一次性设置用户属性，"name" 的值为 "abc"
dt.userSetOnce(acid, dt_id, properties);

properties = { "name": "xyz" };
# 再次一次性设置用户属性，此时 "name" 的值不会被覆盖为 "xyz"
dt.userSetOnce(acid, dt_id, properties);

3.2.3 userAdd

当您要对数值类型的属性进行累加操作时，可以调用 userAdd 来实现，如果该属性还没有被设置，则会赋值为 0 再进行计算，可传入负值等同于相减操作

TypeScript 复制代码 
properties = {
    "total_count": 10,
    "level": 3
};
# 对用户属性进行累加，数据上传完成后，由于该属性还没有被设置，此时 "total_count" 的值为 10,"level" 的值为 3
dt.userAdd(acid, dt_id, properties);

properties = { "total_count": 20 };
# 对用户属性进行累加，数据上传完成后，此时 "total_count" 的值为 30, "level" 的值为 3
dt.userAdd(acid, dt_id, properties);

3.2.4 userUnset

当您要清空用户属性时，可以调用 userUnset 来实现，如果属性存在，则会删除属性，如果属性不存在，则不会做任何操作

TypeScript 复制代码 
del_set = { "name": 0, "actime_time": 0 };
# 设置后，会删除 name 和 actime_time 两个用户属性
dt.userUnset(acid, dt_id, del_set);

3.2.5 userAppend

当您要追加列表类型用户属性元素时，可以调用 userAppend 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加

TypeScript 复制代码 
properties = {
    "pet": ["cat", "dog"]
};
# 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.userSet(acid, dt_id, properties);

properties = {
    "pet": ["ratbbit"]
};
# 对用户列表类型属性追加元素，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit"]
dt.userAppend(acid, dt_id, properties);

3.2.6 userUniqAppend

当您要追加列表类型用户属性元素并去重时，可以调用 userUniqAppend 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加和去重

TypeScript 复制代码 
properties = {
    "pet": ["cat", "dog"]
};
# 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.userSet(acid, dt_id, properties);

properties = {
    "pet": ["ratbbit", "dot"]
};
# 对用户列表类型属性追加元素并去重，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit]
dt.userUniqAppend(acid, dt_id, properties);

3.2.7 userDelete

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

TypeScript 复制代码 
dt.userDelete(acid, dt_id, {});

四、进阶功能

4.1 设置用户ip地址

在服务端上报数据时，如果您想设置用户的ip地址,可以通过在properties中添加#ip属性，DT会根据您上报的IP地址解析用户的地理位置信息

注：如果是用户事件，仅userSetOnce可上报#ip属性

TypeScript 复制代码 
properties["#ip"] = "127.0.0.1"

五、数据传输

可能使用的数据传输方式：

  • DTLogConsumer：写入文件 + 通过 FileScout 传输

如果生产的数据都是调试数据，建议您开启 debug 标志，当 debug 标志开启时，数据将不会进入生产环境

5.1 DTLogConsumer

参数（按顺序）：

  1. log 文件的文件夹路径
  2. 最大单次写入条数
  3. log 文件的前缀
  4. 单个文件的最大大小（单位：Byte）
JavaScript 复制代码 
var dt = require("@datatower-ai/sdk-core-nodejs");

let consumer = dt.Consumer.DTLogConsumer("log", 200, "dt_nodejs", 10*1024*1024);
# 开启 debug 标志
dt.init(consumer, true);
# 关闭 debug 标志
# dt.init(consumer, false);

5.2 提交数据

如果您期望数据立即上报到 DT 服务器，可以通过 flsuh 完成

TypeScript 复制代码 
# 立即上报数据
dt.flush();

5.3 关闭 SDK

请在退出程序前调用本接口，以避免缓存的数据丢失（重要！)

TypeScript 复制代码 
dt.close();

六、完整示例

从 SDK 初始化、上报到关闭，整个上报流程示例

JavaScript 复制代码 
var dt = require("@datatower-ai/sdk-core-nodejs");

t.toggleLogger(true);
let consumer = dt.Consumer.DTLogConsumer("log", 1000, "dt_nodejs", 10*1024*1024)
dt.init(consumer);
dt.toggleLogger(false);

let dt_id = "1234567890987654321"
let acid = ""

let properties = {}
properties["productNames"] = ["Node", "hello"]
properties["productType"] = "Node book"
properties["producePrice"] = 80
properties["shop"] = "xx-shop"
properties["#os"] = "1.1.1.1"
properties["sex"] = 'female'
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"

dt.track(dt_id, acid, "eventName", properties)

dt.flush();
dt.close();
上一个
Java
下一个
Go
最近修改: 2024-12-10