主题

JavaScript-SDK ​

信息

JavaScript SDK 运行环境需为浏览器，暂不兼容 IE 8 及以下版本.
SDK 体积大小约为 81 KB

提示

最新版本： ​

v202502181 点击下载 更新时间：2025-02-18

一、引入 sdk 文件 ​

sh
$ npm install yxdatasdk-browser --save
sh
$ <script type="text/javascript" src="yxdatasdk.min.js"></script>

二、设置或获取设备号 ​

信息

为了做到设备号唯一，在初始化之前接入方可以从 YXDataSDK 设置或获取设备号，如果不需要则可可以忽略设置，初始化 SDK 之前如果没有设置设备号，那么 SDK 会自动生成设备号用于后期埋点事件上报

2.1、设置设备号 ​

javascript
YXDataSDK.setDeviceId("YOUR_DEVICEID");

2.3、从 YXDataSDK 获取设备号 ​

javascript
const device_id = YXDataSDK.getDeviceId();

三、SDK 初始化操作 ​

3.1、SDK 初始化 ​

javascript
var config = {
  appid: "YOUR_APPID", //项目APP ID
  app_server: "YOUR_SERVER", //服务器标识
  bConsoleLog: false, //是否打印console日志
};
//sdk初始化
//模式一:
YXDataSDK.init(config);
//模式二:
YXDataSDK.init(config)
  .then(() => {
    //初始化成功
  })
  .catch((err) => {
    //console.log("初始化失败:",err);
  });

参数名类型是否必传描述
appidstring项目 APP ID（YXData平台申请）
app_serverstring否服务器标识，单一服可传空值
bConsoleLogboolean否默认(false), true 表示 debug 需要输出控制台 console 日志

危险




四、常用功能 ​

4.1、设置账号 ID ​

在用户产生登录行为时，可调用 login 来设置用户的账号 ID. YXData 平台优先以账号 ID 作为身份标识，设置后的账号 ID 将会被保存，多次调用 login 将会覆盖先前的账号 ID.

示例：

javascript
// 用户的登录唯一标识.
// 此数据对应上报数据里的 ys_account_id，此时ys_account_id的值为YXData
//模式一:
YXDataSDK.login("YXData"); //传值字符串类型，非空值
//模式二:
YXDataSDK.login("YXData")
  .then(() => {
    //设置成功
  })
  .catch((err) => {
    //console.log("设置失败:",err);
  });

4.2、自定义公共事件属性 ​

信息

公共事件属性指的就是每个事件都会带有的属性，您可以调用 setSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。

1、如果调用 setSuperProperties 上传了先前已设置过的公共事件属性，则会覆盖之前的属性
2、Key 为该属性的名称，为字符串类型，规定只能以字母开头包含(数字/字母/下划线 "_")，长度最大为 50 个字符
3、Value 为该属性的值，支持字符串、数字、布尔、对象、对象组、数组

4.2.1、设置公共事件属性 ​

示例：

javascript
var superProperties = {
  str: "str", //字符串
  age: 1, //数字
  isSuccess: true, //布尔
  object: { key: "value" }, //对象
  object_arr: [{ key: "value" }], //对象组
  arr: ["value"], //数组
};

//模式一:
YXDataSDK.setSuperProperties(superProperties); //设置公共事件属性
//模式二:
YXDataSDK.setSuperProperties(superProperties)
  .then(() => {
    //设置成功
  })
  .catch((err) => {
    //console.log("设置失败:",err);
  });
4.2.2、删除公共事件属性 ​

示例：

javascript
var key_name = "str"; //需要删除的键名称
//模式一:
YXDataSDK.delSuperPropertyByName(key_name); //删除单个公共事件属性
//模式二:
YXDataSDK.delSuperPropertyByName(key_name)
  .then(() => {
    //成功
  })
  .catch((err) => {
    //console.log("失败:",err);
  });

4.3、发送事件 ​

在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。

4.3.1、普通事件 ​

信息

  1. 事件的名称（eventname）是字符串类型，只能以字母开头，可包含数字，字母和下划线 ""，长度最大为 50 个字符。
  2. 自定义属性（properties）是 json 对象类型，对象里面的属性值支持字符串、数字、布尔、对象、对象组、数组 类型

您可以直接调用 eventReport 上传自定义事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件，此处以用户选择服务器作为范例：

javascript
var data_json = {
  event_name: "select_server", //事件名称
  properties: {
    guid: 1000, //自定义属性，选择的大区ID
  },
};
//模式一:
YXDataSDK.eventReport(data_json);
//模式二:
YXDataSDK.eventReport(data_json)
  .then(() => {
    //成功
  })
  .catch((err) => {
    //console.log("失败:",err);
  });
4.3.2、首次事件 ​

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。您可以使用属性赋值进行控制，例如在一些场景下，您可能希望记录在某个设备上的激活事件。示例如下：

javascript
var data_json = {
  event_name: "active", //事件名称
  is_first_event: true, //是否首次事件，true=首次事件
  properties: {
    //自定义事件属性（可选）
    guid: 1000, //自定义属性，选择的大区ID
  },
};
//模式一:
YXDataSDK.eventReport(data_json);
//模式二:
YXDataSDK.eventReport(data_json)
  .then(() => {
    //成功
  })
  .catch((err) => {
    //console.log("失败:",err);
  });

提示

4.4、设置用户属性及修改属性值 ​

您可以使用接口进行设置、修改用户属性、或有值存在时忽略设置。

用户属性名称（name）允许字符：英文字母及下划线,长度为最大 50 个字符 属性值（value）允许类型：数值、字符串、布尔、列表、浮点数、对象、对象组

以下为设置用户属性“金币”值是 100（数值类型）为例如下：

javascript
var set_json = {
  name: "amount",
  value: 100,
};
//模式一:
YXDataSDK.configAccountProperty(set_json);
//模式二:
YXDataSDK.configAccountProperty(set_json)
  .then(() => {
    //成功
  })
  .catch((err) => {
    //console.log("失败:",err);
  });

参数名类型是否必传描述
namestring属性名称
valueany属性值（允许类型：数值、字符串、布尔、列表、浮点数、对象、对象组）
optnumber否1:设置属性(默认)、2:修改值、3:属性值存在则忽略

若需要忽略操作有值的用户属性您可以使用赋值进行控制；比如我们希望用户首次登录时间只记录第一次上报的时间，后期不在改变为例如下：

javascript
var set_json = {
  name: "first_login_time",
  value: "2025-02-01 10:32:00",
  opt: 3, //此时opt为必传值3，入库时有值则忽略本次操作
};
//模式一:
YXDataSDK.configAccountProperty(set_json);
//模式二:
YXDataSDK.configAccountProperty(set_json)
  .then(() => {
    //成功
  })
  .catch((err) => {
    //console.log("失败:",err);
  });

五、最佳实践 ​

javascript
<script type="text/javascript" src="yxdatasdk.min.js"></script>;

var config = {
  appid: "YOUR_APPID", //项目APP ID
};
YXDataSDK.init(config); //sdk初始化

//如果用户已登录，可以设置用户的账号ID唯一标识
YXDataSDK.login("YXData");

//设置公共事件属性
var superProperties = {
  str: "str", //字符串
  age: 1, //数字
  isSuccess: true, //布尔
  object: { key: "value" }, //对象
  object_arr: [{ key: "value" }], //对象组
  arr: ["value"], //数组
};
YXDataSDK.setSuperProperties(superProperties); //设置公共事件属性

//发送事件
YXDataSDK.eventReport({
  event_name: "select_server", //事件名称
  properties: {
    guid: 1000, //自定义属性，选择的大区ID
  },
});

//设置用户属性
YXDataSDK.configAccountProperty({
  name: "username", //用户属性名称（允许字符：英文字母及下划线）
  value: "YXDatae", //属性值（字符串）
});

版权所有 © 2023-2025 涌现数据