tingyun web SDK
shell
npm install --save @tingyun-sdk/web
`
2. 启动
`js
import Tingyun from '@tingyun-sdk/web';
Tingyun.init({
token: '<应用token>',
domain: '<数据上传地址>',
// ...其他配置项
});
`
- token: Tingyun Web应用唯一标识, 可在控制台获取
- domain: 数据上传地址, 可在控制台获取
API
设置用户ID
语法:
`js
Tingyun.setUid(username)
`
参数:
- username: 用户名。字符串类型。必须
自定义操作
语法:
`js
const action = Tingyun.newAction(options);
`
参数:
- options
操作配置项对象
- key: 操作名称。字符串类型。必须
- context: 操作包含的附加数据。对象类型。可选
- duration: 设置操作时间, 对于立即发送的操作, 可以设置此配置指定操作时间。number类型。可选
- timeout: 操作超时时间, 默认10分钟, 超时后的操作被丢弃, number类型, 可选
- status: 设置操作状态success或fail, 默认success, 只在立即发送模式的操作有效。字符串类型。可选
- immediate: 是否立即发送此操作, boolean类型, 默认为false。可选
返回:
返回操作对象action, 可以用于结束操作。 action对象包含下列函数。
- end: 结束操作
`js
action.end(options);
`
- options: 结束操作配置对象。可选
- context: 操作包含的附加数据。对象类型。可选
- status: 设置操作状态success或fail, 默认success。字符串类型。可选
- store: 暂存操作, 操作相关信息会保存进localStorage中, 可以使用Tingyun.endStoredAction读取并结束。主要用于跨页面的操作。
`js
action.store();
`
结束存储操作:
`js
Tingyun.endStoredAction(options);
`
- options: 结束存储操作配置对象。可选
- key: 结束指定key的操作, 不传会结束当前存储的操作。字符串类型。可选
- status: 指定存储操作的结束状态。success或fail。字符串类型。可选
- timeout: 设置超时时间, 默认60000ms, 如果超时不上传数据。number类型。可选
示例:
提交订单的场景示例:
`js
function submitOrder(order) {
// 创建提交订单操作, 并传入订单id作为额外信息
const action = Tingyun.newAction({
key: '提交订单',
context: {
orderId: order.id
}
});
// 自定义提交订单请求业务逻辑
sendRequest(SUBMIT_ORDER_URL, data)
.then((res) => {
// 提交成功, 结束操作, 并设置附加返回的业务状态码
action.end({
context: {
code: res.data.code
}
});
})
.catch(() => {
// 提交失败, 以失败的状态结束操作
action.fail();
});
}
`
自定义事件
语法:
`js
Tingyun.newEvent(options);
`
参数:
- options
事件配置项对象
- name: 事件名称。 字符串类型。 必须
- msg: 事件信息。字符串类型。可选
- status: 事件状态。字符串类型。可选
- context: 操作包含的附加数据。对象类型。可选
示例:
用户页面提示框触发场景示例:
`js
function messageBox(data) {
// 创建事件, 并设置详细信息到额外信息中
Tingyun.newEvent({
name: data.title,
msg: data.msg,
status: data.level,
context: {
detail: data.detail
}
});
}
`
上报JS错误
语法:
`js
Tingyun.captureException(err[, options])
`
参数:
- err: 错误对象, 需要包含message(错误信息)和stack(错误堆栈)两个属性。必须。
- options: 额外选项。对象类型。可选
- contexts: 额外附加数据。对象类型。可选
- breadcrumbs: 面包屑数据。数组。可选
示例:
拦截Vue框架内错误并上报:
`js
import Tingyun from '@tingyun-sdk/web';
Vue.config.errorHandler = function(err, vm, info) {
Tingyun.captureException(err);
};
`
全局自定义数据
语法:
`js
Tingyun.setContext(key[, value]);
`
参数:
- key: 字符串或对象, 传字符串表示数据分类名称, 如果传对象, 第二个参数值将被忽略
- value: 对象, 当第一个参数传字符串时，表示数据的内容。
示例:
`js
Tingyun.setContext('app', {
name: 'my_app',
version: 'V1.1.1'
});
// 等效使用方式
TINGYUN.setContext({
app: {
name: 'my_app',
version: 'V1.1.1'
}
});
`
局部自定义数据
可以使用Action Hook设置局部自定义数据。Action Hook是SDK在采集数据项数据时触发的回调函数, 回调函数中会传入当前数据项的相关信息和关联到当前数据项的Scope对象。最终通过scope对象在具体数据项设置自定义数据。
注册Action Hook语法:
`js
Tingyun.addActionHook(name, handler)
`
参数:
- name
需要注册的Action hook名称, 必须
取值:
- ajax: Ajax
- error: JS错误
- userAction: 自定义操作
- handler
hook回调函数, 会传入params参数, 必须
- params.target: 数据项原始对象
- params.actionData: 数据项基本信息, 不同类型的数据结构会不同。具体参考具体action hook的文档。
- params.scope: scope对象
示例:
在Ajax返回时设置局部自定义数据:
`js
Tingyun.addActionHook('ajax', function(params) {
const {scope} = params;
// 设置局部自定义数据
scope.setContext({
// ...
});
});
``