@tingyun-sdk/web

听云web SDK

使用

1. 安装

npm install --save @tingyun-sdk/web

2. 启动

import Tingyun from '@tingyun-sdk/web';

Tingyun.init({
    token: '<应用token>',
    domain: '<数据上传地址>',
    // ...其他配置项
});

• token: Tingyun Web应用唯一标识, 可在控制台获取
• domain: 数据上传地址, 可在控制台获取

API

设置用户ID

语法:

Tingyun.setUid(username)

参数:

• username: 用户名。字符串类型。必须

自定义操作

语法:

const action = Tingyun.newAction(options);

参数:

• options
  操作配置项对象

  • key: 操作名称。字符串类型。必须
  • context: 操作包含的附加数据。对象类型。可选
  • duration: 设置操作时间, 对于立即发送的操作, 可以设置此配置指定操作时间。number类型。可选
  • timeout: 操作超时时间, 默认10分钟, 超时后的操作被丢弃, number类型, 可选
  • status: 设置操作状态success或fail, 默认success, 只在立即发送模式的操作有效。字符串类型。可选
  • immediate: 是否立即发送此操作, boolean类型, 默认为false。可选

返回:

返回操作对象action, 可以用于结束操作。 action对象包含下列函数。

• end: 结束操作

  action.end(options);

  • options: 结束操作配置对象。可选
    • context: 操作包含的附加数据。对象类型。可选
    • status: 设置操作状态success或fail, 默认success。字符串类型。可选
• store: 暂存操作, 操作相关信息会保存进localStorage中, 可以使用Tingyun.endStoredAction读取并结束。主要用于跨页面的操作。

  action.store();

  结束存储操作:

  Tingyun.endStoredAction(options);

  • options: 结束存储操作配置对象。可选
    • key: 结束指定key的操作, 不传会结束当前存储的操作。字符串类型。可选
    • status: 指定存储操作的结束状态。success或fail。字符串类型。可选
    • timeout: 设置超时时间, 默认60000ms, 如果超时不上传数据。number类型。可选

示例:

提交订单的场景示例:

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();
        });
}

自定义事件

语法:

Tingyun.newEvent(options);

参数:

• options 事件配置项对象

  • name: 事件名称。 字符串类型。 必须
  • msg: 事件信息。字符串类型。可选
  • status: 事件状态。字符串类型。可选
  • context: 操作包含的附加数据。对象类型。可选

示例:

用户页面提示框触发场景示例:

function messageBox(data) {
    // 创建事件, 并设置详细信息到额外信息中
    Tingyun.newEvent({
        name: data.title,
        msg: data.msg,
        status: data.level,
        context: {
            detail: data.detail
        }
    });
}

上报JS错误

语法:

Tingyun.captureException(err[, options])

参数:

• err: 错误对象, 需要包含message(错误信息)和stack(错误堆栈)两个属性。必须。
• options: 额外选项。对象类型。可选
  • contexts: 额外附加数据。对象类型。可选
  • breadcrumbs: 面包屑数据。数组。可选

示例:

拦截Vue框架内错误并上报:

import Tingyun from '@tingyun-sdk/web';

Vue.config.errorHandler = function(err, vm, info) {
    Tingyun.captureException(err);
};

全局自定义数据

语法:

Tingyun.setContext(key[, value]);

参数:

• key: 字符串或对象, 传字符串表示数据分类名称, 如果传对象, 第二个参数值将被忽略
• value: 对象, 当第一个参数传字符串时，表示数据的内容。

示例:

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语法:

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返回时设置局部自定义数据:

Tingyun.addActionHook('ajax', function(params) {
    const {scope} = params;    

    // 设置局部自定义数据
    scope.setContext({
        // ...
    });
});