@superdata/urchin-tracking-module

Urchin Tracking Module

用户埋点日志记录SDK

功能说明

(待施工)

适用范围

本SDK事件的设计原则是业务驱动，即每个事件都有准确的业务上的含义。

事件的定义需要以下要素：

1. EVENT_NAME 事件中文名 用于识别事件作用

2. 事件文本模板 输出的用户行为日志会根据业务数据对模板进行解析。示例:

   模板: {user_id}使用关键字{keyword}进行全文检索
   业务数据: {"user_id": "FA980000F8620A351700790066D7B3E6", "keyword": "冯潜"}
   输出日志: FA980000F8620A351700790066D7B3E6使用关键字冯潜进行全文检索

3. MODULE_ID 关联的功能模块(可选)

埋点事件的设计原则

1. 完整性
   埋点尽可能覆盖页面的所有元素
   由于目前只有点击事件，因此要尽可能覆盖所有具有点击功能的组件
2. 原子性
   埋点的最小颗粒度为通用组件/业务组件。
   由于本SDK事件是业务驱动，因此不宜在非页面代码内植入。

使用说明

STEP1: 引入SDK

使用yarn命令安装：

  yarn add @superdata/urchin-tracking-module

STEP2: 获取USER_ID，调用UTMTool类

  import UTMTool from '@superdata/urchin-tracking-module';

  window.onload = () => {
    window.utm = new UTMTool({
      userId: user.id,
      organizationId: user.orgId,
      url: `/api/operationLog/v1/addOperationLog`,
    });
  }

STEP3: 进入基础模块注册埋点事件。事件已存在则可跳过此步骤。(待施工)

STEP4: 从基础模块中获取事件ID

STEP5: 业务代码植入埋点

通常，埋点植入需要处理下列问题：

1. 事件类型 事件类型使用data-utm-{事件类型}属性传递，值为响应的事件ID。
   支持点击事件的记录(data-utm-click)
   支持搜索事件(data-utm-search)

2. 业务数据 业务数据使用data-utm-data属性传递，值为JSON字符串。
   发送请求时，SDK会自动将user_id代入，因此使用者可以专注于业务数据本身，不需要自行传入。

3. 功能模块 功能模块使用data-utm-module属性记录，值为功能模块代码。 data-utm-module不需要和其他属性绑定在一起。 触发埋点时，SDK会从当前节点开始向上递归，找到最近的data-utm-module作为参数发送请求。

DEMO:
原生HTML属性植入：

  <button data-utm-click="0" data-utm-data='{"keyword":"冯潜"}'></button>

由于React对data-*属性的继承，React组件亦可执行埋点。需要注意的是，如果React组件最外层是Fragment，则埋点会失效。

  <Button data-utm-click="1" data-utm-data='{"keyword":"冯潜"}'></Button>

自定义事件埋点Demo（不填写eventId则不会发送埋点请求）

javascript原生植入：

  const { send } = window.utm;
  send({
    eventId: '2',
    type: 'search',
    pageX: 0,
    pageY: 0,
    utmData: { keyword: '冯潜' }, // utmData对象模式
    utmModule: 'module name',
  })

修饰符植入：

  const { tracking } = window.utm;
  class A {
    @tracking({
      eventId: '3',
      type: 'search',
      utmData: () => ({ keyword: '冯潜' }), // utmData函数模式
      utmData: { keyword: '冯潜' }, // utmData对象模式
    })
    onSubmit() {
      // ...code
    }
  }
// tracking方法会把React组件的utmModule自动添加到请求参数中
<A utmModule="module name" />

Switch事件发送的业务数据统一为：

  {"checked": "打开"} or {"checked": "关闭"}

Switch事件DEMO:

  <Switch
    data-utm-module="QWJS"
    data-utm-switch="4"
  />

Search事件DEMO:

  import { Input } from 'antd';

  <Input.Search
    data-utm-search="5"
    onSearch={() => {
      // write some code
    }}
  />