JavaScript

更新时间：2024-10-16

一、集成

1.1 从 npm 仓库引入

• 安装依赖

npm i @datatower-ai/sdk-core-web

• 引入并使用

import { DataTower } from '@datatower-ai/sdk-core-web';
// 初始化
DataTower.initSDK({/* ... */})

1.2 下载到本地，手动集成 web SDK

• 下载web-sdk压缩包

  下载链接：datatower-web-sdk

• TypeScript ESModule 项目

  1. 将压缩包中的 dt.web.mjs、dt.web.d.mts 放入项目 libs 目录下，如果 libs 不存在，新建 libs 目录
  2. 在 src/ 目录下的文件中导出使用
     TypeScript 复制代码

     import { DataTower } from '../libs/dt.web.mjs';

• JavaScript CommonJS 项目

  1. 将压缩包中的 dt.web.cjs、dt.web.d.cts 放入项目 libs 目录下，如果 libs 不存在，新建 libs 目录
  2. 在 src/ 目录下的文件中导出使用
     JavaScript 复制代码

     const { DataTower } = require('../libs/dt.web.cjs')

• JavaScript UMD 项目

  1. 将压缩包中的 dt.web.js 放入项目 libs 目录下，如果 libs 不存在，新建 libs 目录
  2. 在 index.html 文件中引入
     html 复制代码

     <script type="text/javascript" src="../libs/dt.web.js" />

  3. 在 src/ 目录下的文件中使用，DataTower 已在全局挂载
     JavaScript 复制代码

     const DT = window.DataTower

二、初始化

2.1 初始化

• 说明

DataTower.ai Core SDK 唯一初始化入口

• 方法

class DataTower {
    static initSDK(config: Config): void;
}

• 参数

• 使用

//  DT SDK 初始化
DataTower.initSDK({
    appId: "appId",
    serverUrl: "https://example.com",
    isDebug: true,
    logLevel: LogLevel.VERBOSE,
    manualEnableUpload: false,
});

三、基础功能

3.1 ID 体系

3.1.1 设置账号 ID

• 说明

可以在用户每一次登录时，调用 setAccountId 设置用户的账号 ID， DT 系统将会以账号 ID 作为身份识别 ID，多次调用 setAccountId 将覆盖先前的账号 ID

若您的应用没有账号体系可以不设置

• 方法

class DataTower {
    static setAccountId(id: string): void;
}

• 参数

• 使用

DataTower.setAccountId("123456");

如果需要清除账号 ID，请传入空字符串

typescript 复制代码

DataTower.setAccountId("");

3.1.2 获取 DT ID

• 说明

异步获取由 SDK 生成的设备标识 DT ID。

• 方法

class DataTower {
    static getDataTowerId(callback: (id: string) => void): void;
    static getDataTowerId(): Promise<string>;
}

• 参数

• 使用

DataTower.getDataTowerId((id) => console.log(id));
// or
const id = await DataTower.getDataTowerId();

3.2 设置事件上报

• 说明

调用 track 设置自动上报的埋点事件和事件属性

• 方法

class DataTower {
  static track(eventName: string, properties: Record<string, string | boolean | number>): void;
}

• 参数

• 使用

DataTower.track("test_track", {
    test_property_1: "test",
    test_property_2: 1,
});

3.3 设置用户属性

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

3.3.1 user_set

• 说明

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

• 方法

class DataTower {
  static userSet(properties: Record<string, string | boolean | number>): void;
}

• 参数

• 使用

DataTower.userSet({
    user_sex_man: false,
    user_pwd: "1111111",
    user_age: 23,
});

3.3.2 user_set_once

• 说明

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

• 方法

class DataTower {
  static userSetOnce(properties: Record<string, string | boolean | number>): void;
}

• 参数

• 使用

DataTower.userSetOnce({
    user_first_paid_time: "2020-09-23",
});

3.3.3 user_add

• 说明

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

• 方法

class DataTower {
  static userAdd(properties: Record<string, number>): void;
}

• 参数

• 使用

DataTower.userAdd({ total: 30 });
// 此时"total"为30
DataTower.userAdd({ total: 648 });
// 此时"total"为678

3.3.4 user_unset

• 说明

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

• 方法

class DataTower {
    static userUnset(properties: string[]): void;
}

• 参数

• 使用

DataTower.userUnset(["key1"]);

3.3.5 user_delete

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

class DataTower {
    static userDelete(): void;
}

3.3.6 user_append

• 说明

您可以调用 userAppend 对列表类型的用户数据追加元素

• 方法

class DataTower {
  static userAppend(properties: Record<string, (string | boolean | number)[]>): void;
}

• 参数

• 使用

DataTower.userAppend({ user_list: ["apple", "cube"] });

3.3.7 user_uniq_append

• 说明

您可以调用 userUniqAppend 对列表的用户数据追加唯一元素。调用 userUniqAppend 接口会对追加的用户属性进行去重， userAppend 接口不做去重，用户属性可存在重复

• 方法

class DataTower {
  static userUniqAppend(properties: Record<string, (string | boolean | number)[]>): void;
}

• 参数

• 使用

// 此时user_list的属性值为["apple"，"ball"]
DataTower.userUniqAppend({ user_list: ["apple", "ball"] });
// 此时user_list的属性值为["apple","apple","ball","cube"]
DataTower.userUniqAppend({ user_list: ["apple", "cube"] });

3.4 手动上报

• 说明

调用 enableUpload 手动进行上报，仅在 manualEnableUpload 为 true 时生效

• 方法

class DataTower {
  static enableUpload(): void;
}

• 使用

DT.enableUpload();

四、进阶功能

4.1 公共属性

如需为所有事件添加属性，可以使用公共属性接口进行设置。

4.1.1 静态公共属性

静态公共属性会使用持久化存储，应用退出再开启时，原先设置的值会保持不变。

• 方法

class DataTower {
  static setStaticCommonProperties(properties: Record<string, string | boolean | number>): void；
  static clearStaticCommonProperties(): void；
}

• 使用

const properties = {};
// 设置
DataTower.setStaticCommonProperties(properties);
// 清除
DataTower.clearStaticCommonProperties();

4.1.2 动态公共属性

动态公共属性会在调用相关事件上报接口时动态地进行公共属性的获取，应用重启后需重新设置。

• 方法

class DataTower {
  static setDynamicCommonProperties(callback: () => Record<string, string | boolean | number>): void；
  static clearDynamicCommonProperties(): void；
}

• 使用

const properties = {};
// 设置
DataTower.setDynamicCommonProperties(() => props);
properties["key_sample"] = 20;
// Track 时会调用动态公共属性的函数来获取公共属性，并进行上报，（此时包含 "key_sample": 20）
DataTower.track("simple_event");
// 清除
DataTower.clearDynamicCommonProperties();