@ssv-lab

Appearance

Return to top
On this page

Anim 数据埋点上报插件

Anim 框架集成了腾讯内部的大同小程序数据埋点上报工具，通过简单配置和上报 API，可以完成无侵入埋点与动作埋点。

支持自动/半自动上报功能

功能上报方式备注代码片段示例
应用曝光自动--
页面曝光自动可以自定义进行 pgid 标注，若不标注则默认为页面路径示例
元素曝光半自动需要在 wxml 上进行 .expose-el 与 data-dt-eid 进行标注。如果为自定义组件，还需要进行 .expose-container 进行标注。示例
元素点击半自动需要进行 data-dt-eid 进行标注，若不标注则默认上报函数名称示例
用户分享自动分享页面/分享朋友圈/收藏操作会自动上报-
自定义上报手动统一格式的手动上报方式示例
公参定义手动可以在配置中进行公参设置，或者利用 SDK 动态设置公参。示例

快速使用

安装 Anim 插件

bash
npm install @ssv-lab/anim-plugin-datong --save

注意该 npm 包为 Coding Npm 的私有源，请先确定已经正确配置了 Coding Npm

  1. 点击开发者工具中的菜单栏：工具 --> 构建 npm
  2. 点击开发者工具中的菜单栏：设置 --> 项目设置 --> 勾选“使用 npm 模块”选项
  3. 构建完成后即可使用

版本要求

@ssv-lab/anim 和 @ssv-lab/anim-plugin-datong 都需要为 ^@1.1.0。

初始化插件

js
// app.js
import Anim from '@ssv-lab/anim';
import DatongPlugin from '@ssv-lab/anim-plugin-datong';

// 埋点插件需要初始化
Anim.use(DatongPlugin, {
  // 小程序appKey，从灯塔官网获取。
  beacon: 'xxx',
  // 是否为开发调试模式(可查看日志)
  debug: false,
  // 静态公参设置
  publicParams: {
    openid: wx.getStorageSync('openid'),
    is_test: false,
  },
});

小程序使用 npm 包，请参考 小程序使用 npm 包

配置参数

options.beacon

必填。 上报的应用 ID，通过灯塔数据仓库提供。

options.debug

调试模式，会自动打印日志，方便查看调试。

options.publicParams

静态公参，如果有动态公参需要注入，请参考后续的动态公参的使用方法。

options.pageSelector

页面曝光，需要获取的页面节点的 class。默认值为.expose-page。

options.exposeSelector

元素曝光，需要获取到元素节点的 class。默认值为.expose-el。

options.exposeParentSelector

组件内元素曝光，需要通过获取曝光容器节点的 class，再穿透获取曝光元素。默认值为.expose-container。

options.autoReport

配置开启哪些自动上报，支持 page/handler。

js
import Anim from '@ssv-lab/anim';
import DatongPlugin from '@ssv-lab/anim-plugin-datong';

// 埋点插件需要初始化
Anim.use(DatongPlugin, {
  autoReport: {
    // 是否开启页面自动上报，不开启则有 pgid 才会上报
    page: true,

    // 是否开启 tap 函数自动上报，不开启则有 eid 才会上报
    handler: true,
  },
});

options.pageAsync

支持页面的异步曝光，可以配置为在 onLoad 或者 onShow 结束后再进行页面曝光。

使用方法

注意，后续的 API 中 wx.universalReport 与 Anim.$datong 是同一个作用。前者是大同数据上报埋点 SDK 的标准使用方式，一个是基于 Anim 框架会增强部分 typescript 提示。后续都以 Anim 为使用示例。

注入动态参数

部分公共参数，需要在后续异步操作中才可以获取，这个时候推荐使用动态参数注入。例如用户 ID，组织 ID 等业务参数。

js
import Anim from '@ssv-lab/anim';

App({
  onLaunch() {
    // 异步设置公参
    getUserInfo().then((res) => {
      Anim.$datong.setPublicParams({
        userId: res.userId,
        isVip: false,
      });
    });

    // 可多次调用并做合并
    getOrganization().then((res) => {
      Anim.$datong.setPublicParams({
        orgId: res.orgId,
      });
    });

    // 公参设置完后，后续上报都会带上合并后的公参。
  },
});

页面曝光

常规页面曝光

页面节点挂载 expose-page 类后，可通过配置 data-dt-pgid 来手动定义 pgid。若没有在 WXML 元素上配置相关 data-dt-pgid 则会默认将该路径作为 pgid 进行上报。

js
Anim.Page({
  data: {},
});
xml
<view
  class="expose-page"
  data-dt-pgid="xxxx"
  data-dt-params="testkey1=value&testkey2=value"
>
  <!-- 其他元素省略 -->
</view>

异步页面曝光

当页面曝光的参数需要通过接口传入的情况下，我们可以考虑异步曝光的使用方式。

页面级异步曝光

可以通过对页面节点标注 data-dt-pgasync="onLoad"，则页面会在 onLoad 结束后才进行曝光。

除了 onLoad，还支持 onShow 配置。

xml
<view
  class="expose-page"
  data-dt-pgid="xxxx"
  data-dt-params="testkey1={{asyncData}}"
  data-dt-pgasync="onLoad"
>
  <!-- 其他元素省略 -->
</view>
js
Anim.Page({
  async onLoad() {
    const data = await this.getData();
    this.setData({ asyncData: data });
  },
});

全局配置异步页面曝光

除了针对当个页面支持异步曝光，插件还支持全局配置异步曝光方式。

js
Anim.use(DatongPlugin, {
  // 小程序appKey，从灯塔官网获取。
  beacon: 'xxx',
  // 是否为开发调试模式(可查看日志)
  debug: false,
  // 静态公参设置
  publicParams: {
    openid: wx.getStorageSync('openid'),
    is_test: false,
  },
  // 异步全局配置
  pageAsync: 'onLoad',
});

元素曝光

元素曝光，是指当所在元素进入视窗时，记录一次元素的曝光事件 dt_imp。当离开视窗后，记录一次元素的结束曝光事件 dt_imp_end，并记录这一次的曝光周期时间值。

  • wxml 中需要监听的节点配置监听类名，监听类名参考配置项中传入的exposeSelector，默认为 .expose-el。
  • 上报的元素 id 取自 wxml 中取配置的data-dt-eid。
  • 上报的元素携带的私有参数取自 wxml 中配置的data-dt-params。
  • 当一个页面有重复相同 eid 元素，必须通过data-dt-params进行元素的区分，否则会导致曝光时间计算有误。
  • 需要在 page.onShow 里手动启用曝光元素监听器。

页面元素曝光

当元素在页面上时，仅需要在需要曝光的元素加入曝光选择器，曝光元素 eid 即可。

xml
<!-- page 页面 -->
<view
  class="expose-el"
  data-dt-eid="em_test_expose"
  data-dt-params="label=xxxx&type=xxx">
  曝光元素
</view>
js
// index.js
import Anim from '@ssv-lab/anim';

Anim.Page({
  onShow() {
    // 框架会在 onHide 时默认销毁监听器
    Anim.$datong.createExposeObserver(this);
  },
});

组件元素曝光

当需要曝光的元素在组件内部时，组件内部按照常规方案进行曝光标记。页面上则需要通过.expose-container来支持页面跨自定义组件获取曝光元素，一般推荐在组件上或者父容器上进行标记。

xml
<!-- test-comp.wxml -->
<view
  class="expose-el"
  data-dt-eid="em_test_expose"
  data-dt-params="label={{label}}&type=xxx">
  曝光组件元素
</view>
xml
<!-- page.wxml -->
<!-- 页面上使用了该组件 -->

<!-- 单个组件推荐标记方式 -->
<test-single-comp class="expose-container" />

<!-- 多个组件推荐标记方式，且不同的组件最终通过 label 属性进行区分 -->
<view class="expose-container">
  <test-comp label="A" />
  <test-comp label="B" />
  <test-comp label="C" />
</view>
js
// page/index.js
import Anim from '@ssv-lab/anim';

Anim.Page({
  onShow() {
    // 框架会在 onHide 时默认销毁监听器
    Anim.$datong.createExposeObserver(this);
  },
});

滚动容器内的元素曝光

请对滚动容器使用 .expose-scrollview 进行标记，当需要曝光的元素出现在滚动容器内时，触发曝光。

xml
<!-- 纵向滚动容器 -->
<scroll-view class="expose-scrollview" scroll-y style="height: 600rpx;">
  <!-- 支持组件，不再需要 expose-container -->
  <test-comp />

  <!-- 支持单元素 -->
  <image class="expose-el" data-dt-eid="qq-img" />
</scroll-view>


<!-- 横向滚动容器 -->
<scroll-view class="expose-scrollview-x" scroll-x enable-flex style="flex-direction: row;">
  <!-- 支持组件，不再需要 expose-container -->
  <test-comp />

  <!-- 支持单元素 -->
  <image class="expose-el" data-dt-eid="qq-img" />
</scroll-view>
js
// page/index.js
import Anim from '@ssv-lab/anim';

Anim.Page({
  onShow() {
    // 框架会在 onHide 时默认销毁监听器
    Anim.$datong.createExposeObserver(this, { isScrollView: true });

    // 当一个页面出现多个 scrollview，则这里需要明确区分开不同的 scrollview 元素
    Anim.$datong.createExposeObserver(this, {
      isScrollView: true,
      scrollViewSelector: '.expose-scrollview-x',
    });
  },
});

动态元素曝光

当部分元素是拿到数据之后才展示时，需要做到动态元素曝光。

注意：受限于微信机制，当 wx:if 导致销毁的元素则无法监听。建议尽量不要监听会来回切换展示销毁的元素。

xml
<image class="expose-el" data-dt-eid="em_qq-image" data-dt-params="image=qq" mode="widthFix" src="https://www.tencent.com/data/logo-pic/1.2.png" />
<view><button bindtap="changeShow">切换展示</button></view>
<view wx:if="{{showEl}}">
  <image class="expose-dynamic-el" data-dt-eid="em_qq-image-dynamic" data-dt-params="image=qq" mode="widthFix" src="https://www.tencent.com/data/logo-pic/1.2.png" />
</view>
js
import Anim from '@ssv-lab/anim';
Anim.Page({
  data: {
    showEl: false,
  },
  onShow() {
    // 这个用于自动监听静态曝光元素
    Anim.$datong.createExposeObserver(this);
  },

  changeShow() {
    wx.showLoading({
      title: '加载中',
    });
    setTimeout(() => {
      this.setData({ showEl: !this.data.showEl }, () => {
        // 区别开自动曝光的元素
        // 需要定义监听器 ID 和动态元素类，否则会产生重复多次重复元素上报。
        if (this.data.showEl) {
          Anim.$datong.createExposeObserver(this, {
            id: 'dynamic',
            parentSelector: '.expose-dynamic-container',
            selector: '.expose-dynamic-el',
          });
        } else {
          // TODO：受限于微信机制，当 wx:if 导致销毁的元素则无法监听。
          // 需要手动进行一次事件上报，或者忽略这种情况。
          // 建议尽量不要监听会来回切换展示的元素。
        }
      });
      wx.hideLoading();
    }, 1000);
  },
});

元素点击上报

SDK 默认会劫持所有的函数，并从中过滤出包含 tap/longpress/longtap 的操作并进行上报。

为了让上报的事件有业务价值，可以对拥有点击事件的元素，绑定业务参数 data-dt-eid 和 data-dt-params，进行元素事件的参数上报。若没有在 WXML 元素上配置相关 data-dt-eid 则会默认将该函数名作为 eid 进行上报。

注意：点击事件与绑定的参数，需要在同一个元素上，会通过 event.currentTarget 进行业务参数的获取。

若不想全自动上报，请在初始化参数配置 autoReport.handler 为 false，则有在 WXML 上配置 data-dt-eid 的才会自动上报。

xml
<view
  data-dt-eid="xxxx"
  data-dt-params="label=xxxx&type=xxx"
  bindtap="closeOfficial">
  点击元素
</view>

自定义手动上报事件

SDK 整合了手动上报 API，只保留了一个上报方式。

reportEv

可记录元素的点击上报，上报数据参数通过在 dataset 中进行设置。

js
import Anim from '@ssv-lab/anim';

Anim.Page({
  // 省略其他代码
  handlerTap(e) {
    Anim.$datong.reportEv({
      eid: 'em_xxx' // 配置 EID
      eventName: 'dt_clck' // 可不填，默认为 dt_clck
      params: {
        // 定义业务参数
        isVip: true
      },
    });
  },
});

Released under the MIT License.

Copyright © 2021-present @ssv-lab