基于UIObserver能力的应用埋点

介绍

本示例基于UIObserver能力实现了常见的埋点行为：点击埋点、曝光埋点、页面埋点。开发者可以结合业务场景进行应用埋点，针对用户行为收集、处理和发送一些信息，以跟踪应用的使用情况，包括访问数、访客数、停留时长、页面浏览数和跳出率等。

效果预览

概述

埋点是指将信息采集程序和原本的功能代码结合起来，针对特定用户行为收集、处理和发送一些信息，用来跟踪应用使用情况。包括访问数、访客数、停留时长、页面浏览数和跳出率。以下是几种常见业务场景：

• 页面中可视区域或者组件的点击量，统计点击频率，分析用户的偏好行为。
• 监听页面中组件滑动的开始与结束，计算滑动偏移量以及曝光比例。
• 监听页面切换，统计页面的停留时间以及切换的来源页和目标页，分析页面浏览数和跳出率。
• 分析页面加载性能，计算加载过程各个节点的耗时，可针对某个关键点进行优化。

埋点分类

按照用户行为不同，埋点可以分为点击埋点、曝光埋点以及页面埋点等。

• 点击埋点：用户在任意区域的一次点击，比如一个icon或一张图片。区别于被动的用户曝光行为，点击属于主动行为。
• 曝光埋点：统计页面局部区域是否被用户有效浏览，比如瀑布流中的每一个卡片的曝光比例以及曝光时长，属于被动行为。
• 页面埋点：统计用户在固定页面的停留时间，页面加载性能以及页面跳转时的来源页和去向页信息。

方案介绍

接下来会从（1）组件动态绑定埋点数据；（2）点击埋点方案；（3）曝光埋点方案；（4）页面埋点方案四部分介绍。整体方案使用全局无感监听能力[UIObserver]和[setOnVisibleAreaApproximateChange]属性实现埋点功能。

绑定埋点数据

首先针对需要埋点的组件指定对应的ID值以及埋点数据。比如Button组件可以指定ID为“button-1”，并且通过customProperty自定义属性设置key和value，key为组件ID，value为埋点数据。为方便拿取，可以将埋点数据统一定义在DataResource中。

// entry\src\main\ets\pages\ClickPage.ets
Button($r('app.string.click_tracing_point_single_component'))
  .width('100%')
  .id('button-1')
  .fontWeight(FontWeight.Bold)
  .customProperty('button-1', DataResource['Index']['button-1'])
  .onClick(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'btn');
  })

其中DataResource在本示例中是根据Page名、组件名以及索引进行封装，以Page名作为最外层key层，以组件名+索引为里层key值。value值（埋点数据）可以根据实际业务进行配置。

// entry\src\main\ets\viewModel\DataResource.ets
export const DataResource: Record<string, Record<string, DataResourceType>> = {
  'Index': {
    'button-1': { id: 'button-1' },
    'button-2': { id: 'button-2' }
  },
  'Page2': {
    'component-1': { id: 'text-2' }
  }
}

export interface DataResourceType {
  id: string
}

点击埋点

配置完埋点数据以及成功绑定组件后，可以在EntryAbility里统一注册点击事件监听，在事件回调中获取点击的触发节点。[UIObserver]一共提供了两种监听事件：

• [on(“willClick”)]：用于监听点击事件指令下发情况，所注册回调将于点击事件触发前触发。

• [on(“didClick”)]：用于监听点击事件指令下发情况，所注册回调将于点击事件触发后触发。

这两种方式均可以实现用户点击组件时触发回调。本示例中以willClick监听为例，下面介绍具体方案实现。

实现步骤

1. 首先实现一个简单页面，并且在组件上绑定ID以及埋点数据，ID可以根据组件名-索引来命名；比如下面代码示例中有两个组件，ID值分别为“button-1”与“button-2”。

// entry\src\main\ets\pages\ClickPage.ets
Row() {
  Text($r('app.string.click_tracing_point_composite_component'))
    // ...
  Image($r('app.media.ic_public_arrow_right'))
    // ...
}
// ...
.id('button-2')
.margin({ top: 12 })
.customProperty('button-2', DataResource['Index']['button-2'])
.onClick(() => {
  hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'row');
})

Row() {
  // entry\src\main\ets\pages\ClickPage.ets
  Button($r('app.string.click_tracing_point_single_component'))
    .width('100%')
    .id('button-1')
    .fontWeight(FontWeight.Bold)
    .customProperty('button-1', DataResource['Index']['button-1'])
    .onClick(() => {
      hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'btn');
    })
}

1. 在EntryAbility中统一注册UIObserver的willClick事件监听，并且在事件回调中获取触发的组件节点FrameNode。

// entry\src\main\ets\entryability\EntryAbility.ets
uiContext.getUIObserver()?.on('willClick', (_event: ClickEvent, node?: FrameNode) => {
  const clickCallback = CallbackManager.getInstance().getClickCallback();
  clickCallback(node, uiContext);
})

1. 接着可以根据FrameNode获取当前组件所在的Page和ID值，并且通过[getCustomProperty]获取当前组件绑定的埋点数据。此外FrameNode还提供一些方法获取组件的基础属性，比如组件大小、组件位置以及是否可见等一些信息。

// entry\src\main\ets\viewModel\CallBackManager.ets
/**
 * Obtains the ClickCallback callback.
 *
 */
public getClickCallback() {
  return (node: FrameNode | undefined, uiContext: UIContext) => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `FrameNode: ${node}`);
    const uniqueId = node?.getUniqueId();
    const ID = node?.getId();
    const pageInfo = uiContext.getPageInfoByUniqueId(uniqueId);
    const trackData = node?.getCustomProperty(ID);
    let eventParams: Record<string, string | number> = {
      'component_id': ID ?? '',
      'pageInfo': JSON.stringify(pageInfo ?? {}),
      'tackData': JSON.stringify(trackData ?? {})
    };
    hiAppEvent.write({
      domain: 'test_domain',
      name: 'test_event',
      eventType: hiAppEvent.EventType.FAULT,
      params: eventParams
    }, (err: BusinessError) => {
      if (err) {
        hilog.error(0x0000, 'CallBackManager', '%{public}s', `code: ${err.code}, message: ${err.message}`);
        return;
      }
      hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `getClickCallback, success to write event`);
    });
  };
}

1. 然后通过@kit.PerformanceAnalysisKit的[write]方法将需要的数据写入当天的事件文件中。需要注意的是eventParams的参数值只能是number、string、boolean以及数组类型。

hiAppEvent.write({
  domain: 'test_domain',
  name: 'test_event',
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams
}, (err: BusinessError) => {
  if (err) {
    hilog.error(0x0000, 'CallBackManager', '%{public}s', `code: ${err.code}, message: ${err.message}`);
    return;
  }
  hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `getClickCallback, success to write event`);
});

1. 最后在onWindowStageDestroy调用UIObserver的[off]接口取消监听事件。

// entry\src\main\ets\entryability\EntryAbility.ets
onWindowStageDestroy(): void {
  const uiContext: UIContext | undefined = AppStorage.get('uiContext');
  uiContext?.getUIObserver().off('willClick');
  uiContext?.getUIObserver().off('scrollEvent');
  uiContext?.getUIObserver().off('navDestinationSwitch');
  uiContext?.getUIObserver().off('routerPageUpdate');
  // Main window is destroyed, release UI related resources
  hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'Ability onWindowStageDestroy');
}

除了点击事件外，UIObserver还可以通过[on(‘scrollEvent’)]监听组件滑动。在滑动开始与结束触发回调并得到滑动偏移量。以[瀑布流]为例，对WaterFlow和FlowItem设置组件ID。

// entry\src\main\ets\pages\WaterFlowPage.ets
TrackNode({ track: new Track().id('WaterFlow-1') }) {
  WaterFlow() {
    LazyForEach(this.dataSource, (item: number, index: number) => {
      FlowItem() {
        TrackNode({ track: new Track().id(`flowItem_${index}`) }) {
          WaterFlowCard({ item: item, index: index }).id(`flowItem_${index}`)
        }
      }
      // ...
    }, (item: number) => item.toString())
  }
  .id('WaterFlow-1')
  // ...
  .onReachStart(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'waterFlow reach start');
  })
  .onScrollStart(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'waterFlow scroll start');
  })
  .onScrollStop(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'waterFlow scroll stop');
  })
  .onScrollFrameBegin((offset: number, state: ScrollState) => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `waterFlow scrollFrameBegin offset: ${offset}`);
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s',
      `waterFlow scrollFrameBegin state: ${state.toString()}`);
    return { offsetRemain: offset };
  })
}

接着在EntryAbility里统一注册scrollEvent的事件监听，在回调中获取[ScrollEventInfo]信息，包括id、uniqueId、scrollEvent以及offset。

// entry\src\main\ets\entryability\EntryAbility.ets
uiContext.getUIObserver()
  .on('scrollEvent', (info) => CallbackManager.getInstance().getScrollEvent(info));

说明

scrollEvent监听事件中回调参数的id值只能精确到外层组件WaterFlow，无法精确到里层FlowItem。如果想要在滑动过程中获取各个Item组件的曝光比例，可以参考第三小节曝光埋点。

曝光埋点

曝光埋点需要监听页面中每个组件的出现与消失，比如用户在滑动瀑布流时某个Item出现的时长超过500ms则记为一次有效曝光。为避免在每一个页面注入冗长代码，建议使用自定义“埋点钩子”组件进行封装，以下是具体实现步骤。

实现步骤

1. 首先自定义一个TrackNode“钩子”组件，需要支持嵌套子组件、组件ID值注入以及注册监听事件等等。因此TrackNode中的build组件需由外部调用方决定，并且在onDidBuild生命周期中将组件信息注入进去，onDidBuild主要做了三件事：

   （1）调用TrackManager的addTrack将当前组件与TrackShadow对象绑定起来。

   （2）通过[setOnVisibleAreaApproximateChange]监听埋点组件的可视区域的变化；其中ratio值可以自定义设置，比如本示例设置了0.0、0.5、1.0。

   （3）根据当前组件获取它的父亲节点，并且判断父亲节点有无埋点钩子，如果没有，则继续往上追溯，直到parent节点为null；如果有，则在父节点的子组件集合中添加当前节点。

   注意在aboutToDisappear生命周期中必须调用TrackManager里的removeTrack将当前的组件信息删除。

// entry\src\main\ets\viewModel\TrackNode.ets
// onDidBuild Life Cycle.
onDidBuild(): void {
  // Construct the virtual tree of the tracing point.
  // The obtained node is the root node of the current page (row in the test case).
  let uid = this.getUniqueId();
  let node: FrameNode | null = this.getUIContext().getFrameNodeByUniqueId(uid);
  hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `Track onDidBuild node:${node?.getNodeType()}`);
  if (node === null) {
    return;
  }
  this.trackShadow.node = node;
  this.trackShadow.id = node?.getId();
  this.trackShadow.track = this.track;
  TrackManager.get().addTrack(this.trackShadow.id, this.trackShadow);
  // The setOnVisibleAreaApproximateChange monitors and records the visible area of the tracing point component.
  node?.commonEvent.setOnVisibleAreaApproximateChange(
    { ratios: [0, 0.5, 1], expectedUpdateInterval: 500 },
    (ratioInc: boolean, ratio: number) => {
      const areaChangeCb = CallbackManager.getInstance().getAreaChangeCallback();
      areaChangeCb(node, ratio);
      this.trackShadow.visibleRatio = ratio;
      hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `ratioInc: ${ratioInc}`);
      hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `ratio: ${ratio}`);
    });

  let parent: FrameNode | null = node?.getParent();
  hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `Parent getId: ${parent?.getId()}`);

  let attachTrackToParent: (parent: FrameNode | null) => boolean =
    (parent: FrameNode | null) => {
      while (parent !== null) {
        let parentTrack = TrackManager.get().getTrackById(parent?.getId());
        if (parentTrack !== undefined) {
          parentTrack.childIds.add(this.trackShadow.id);
          this.trackShadow.parentId = parentTrack.id;
          return true;
        }
        parent = parent.getParent();
      }
      return false;
    };
  let attached = attachTrackToParent(parent);

  if (!attached) {
    node?.commonEvent.setOnAppear(() => {
      let attached = attachTrackToParent(parent);
      if (attached) {
        hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `Track lazy attached: ${this.trackShadow.id}`);
      }
    });
  }
}

1. TrackManager主要封装了埋点钩子的一些操作类方法，包括绑定、删除以及导出。绑定是指将当前组件ID与TrackShadow对象存入全局Map中；导出是指以根节点开始，递归输出所有子组件的曝光比例；删除是指根据具体ID值删除Map中对应的数据。

// entry\src\main\ets\viewModel\TrackNode.ets
/**
 * Tracing point data operation class
 */
export class TrackManager {
  static instance: TrackManager;
  private trackMap: Map<string, TrackShadow> = new Map();
  private rootTrack: TrackShadow | null = null;

  static get(): TrackManager {
    if (TrackManager.instance !== undefined) {
      return TrackManager.instance;
    }
    TrackManager.instance = new TrackManager();
    return TrackManager.instance;
  }

  addTrack(id: string, track: TrackShadow): void {
    if (this.trackMap.size === 0) {
      this.rootTrack = track;
    }
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `Track add id: ${id}`);
    this.trackMap.set(id, track);
  }

  removeTrack(id: string): void {
    let current = this.getTrackById(id);
    if (current !== undefined) {
      this.trackMap.delete(id);
      let parent = this.getTrackById(current?.parentId);
      parent?.childIds.delete(id);
    }
  }

  getTrackById(id: string): TrackShadow | undefined {
    return this.trackMap.get(id);
  }

  dump(): void {
    this.rootTrack?.dump(0);
  }
}

1. TrackShadow对象中包含FrameNode、track、childIds、parentId等等。其中FrameNode指组件节点，track包含ID值，childIds指子组件列表，parentId指父组件的ID值。

// entry\src\main\ets\viewModel\TrackNode.ets
export class Track {
  public areaPercent: number = 0;
  public trackId: string = '';

  constructor() {
  }

  id(newId: string): Track {
    this.trackId = newId;
    return this;
  }
}

/**
 * Tracing point data.
 */
export class TrackShadow {
  public node: FrameNode | null = null;
  public id: string = '';
  public track: Track | null = null;
  public childIds: Set<string> = new Set();
  public parentId: string = '';
  public visibleRect: common2D.Rect = {
    left: 0,
    top: 0,
    right: 0,
    bottom: 0
  };
  public visibleRatio: number = 0;

  // Output the information about the tracing point tree through global dump.
  dump(depth: number = 0): void {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `Track Dp: ${depth}`);
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `AreaPer: ${this.track?.areaPercent}`);
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `VisibleRatio: ${this.visibleRatio}`);
    this.childIds.forEach((value: string) => {
      TrackManager.get().getTrackById(value)?.dump(depth + 1);
    });
  }
}

1. 然后根据上述TrackNode组件改造一下瀑布流代码：用TrackNode钩子将WaterFlow和FlowItem包起来，并且传递一个track对象，id为组件的唯一标识。

// entry\src\main\ets\pages\WaterFlowPage.ets
TrackNode({ track: new Track().id('WaterFlow-1') }) {
  WaterFlow() {
    LazyForEach(this.dataSource, (item: number, index: number) => {
      FlowItem() {
        TrackNode({ track: new Track().id(`flowItem_${index}`) }) {
          WaterFlowCard({ item: item, index: index }).id(`flowItem_${index}`)
        }
      }
      // ...
    }, (item: number) => item.toString())
  }
  .id('WaterFlow-1')
  // ...
  .onReachStart(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'waterFlow reach start');
  })
  .onScrollStart(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'waterFlow scroll start');
  })
  .onScrollStop(() => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'waterFlow scroll stop');
  })
  .onScrollFrameBegin((offset: number, state: ScrollState) => {
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s', `waterFlow scrollFrameBegin offset: ${offset}`);
    hilog.info(0x0000, 'ApplicationTrack', '%{public}s',
      `waterFlow scrollFrameBegin state: ${state.toString()}`);
    return { offsetRemain: offset };
  })
}

最后滚动瀑布流时，不仅可以监听每一个Item的曝光比，也可以向上追溯到根节点，统计根节点中每一个子组件的曝光比例。

页面埋点

页面埋点本示例中分为两类，一类是监听页面切换；另一类是采集页面加载性能。以下从Navigation和Router两种路由方案来讲解。

Navigation路由：

针对Navigation方案，UIObserver提供了navDestinationSwitch事件监听页面的切换，并且支持在回调中获取当前页面的切换信息。首先在EntryAbility中统一注册UIObserver的navDestinationSwitch事件监听。

// entry\src\main\ets\entryability\EntryAbility.ets
uiContext.getUIObserver().on('navDestinationSwitch', (info) => {
  const switchCallback = CallbackManager.getInstance().getSwitchCallback();
  switchCallback(info);
});

回调函数中的info包括context、from、to以及operation，主要用于标识页面的来源和去向信息。

字段	类型	含义
context	UIContext	页面上下文信息
from	NavDestinationInfo	NavBar
to	NavDestinationInfo	NavBar
operation	[NavigationOperation]	页面操作

此外还可以通过UIObserver的[on(“navDestinationUpdate”)]事件监听页面的显示与隐藏，回调传参中包含页面名称、状态信息以及页面的唯一标识ID。

Router路由：

针对Router路由方案，UIObserver提供了[on(‘routerPageUpdate’)]监听事件，在页面切换过程中触发相应回调。

// entry\src\main\ets\entryability\EntryAbility.ets
uiContext.getUIObserver().on('routerPageUpdate', (info) => {
  const switchCallback = CallbackManager.getInstance().getSwitchCallback();
  switchCallback(info);
});

比如调用Router.pushUrl从A页面跳转到B页面时，该回调会被触发三次：第一次触发的页面名称为PageB，页面状态为[ABOUT_TO_APPEAR]即将显示；第二次触发的页面名称为PageA，页面状态为ON_PAGE_HIDE页面隐藏；第三次触发的页面名称为PageB，页面状态为ON_PAGE_SHOW页面显示。回调传参同样包含页面上下文、触发事件的页面名称等等。

字段名	类型	含义
context	UIContext	页面上下文信息
index	number	触发页面在路由栈中的位置
name	String	触发页面名称
path	String	触发页面路径
state	[RouterPageState]	页面状态
pageId	String	页面唯一标识

页面加载性能：

页面加载性能可以通过计算首帧绘制与绘制结束的时间差来判断。UIObserver同样提供了on(“willDraw”)事件和on(“didLayout”)事件，可以在首帧监听中记录初始时间，在完成绘制时记录结束时间。此事件监听需要在页面中注册，Navigation与Router路由相同，本示例以Navigation为例。在aboutToAppear注册on(“willDraw”)和on(“didLayout”)事件。

import { hilog } from '@kit.PerformanceAnalysisKit';
import { router } from '@kit.ArkUI';

@Entry
@Component
struct NavigationPage {
  // ...

  aboutToAppear(): void {
    const uiContext = this.getUIContext();
    // Registering a Listening Event
    uiContext.getUIObserver().on('willDraw', () => {
      this.startTime = Date.now();
    })
    uiContext.getUIObserver().on('didLayout', () => {
      this.endTime = Date.now();
    })
  }
  // ...
  build() {
    Navigation(this.pageInfos) {
      Column() {
        Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
          .width('100%')
          .onClick(() => {
            // Put the NavDestination page information specified by name into the stack.
            this.pageInfos.pushPath({ name: 'pageOne' });
          })
        Button('Use interception', { stateEffect: true, type: ButtonType.Capsule })
          // ...
          .onClick(() => {
            this.isUseInterception = !this.isUseInterception;
            if (this.isUseInterception) {
              // Register Interceptor.
              this.registerInterception();
            } else {
              // Do not use interceptors.
              this.pageInfos.setInterception(undefined);
            }
          })
        Button($r('app.string.back'), { stateEffect: true, type: ButtonType.Capsule })
          // ...
          .onClick(() => {
            router.back();
          })
      }
      // ...
    }
    // ...
  }
}

埋点数据上传

如果需要将埋点数据上传至服务器，可以通过[@kit.PerformanceAnalysisKit]的[addWatcher]方法添加订阅事件观察者、onTrigger回调以及回调触发条件。可以自定义设置回调触发条件，比如在示例代码中当事件size大于等于1000字节时才会触发，然后在onTrigger回调中调用http的request方法发起网络请求，将示例中的EXAMPLE_URL替换为服务器的IP地址即可。

// entry\src\main\ets\entryability\EntryAbility.ets
const onTrigger = CallbackManager.getInstance().getOnTrigger();
hiAppEvent.addWatcher({
  name: 'watcher1',
  appEventFilters: [
    {
      domain: 'test_domain',
      eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
    }
  ],
  triggerCondition: {
    row: 10,
    size: 1000,
    timeOut: 1
  },
  onTrigger: onTrigger
})
hilog.info(0x0000, 'ApplicationTrack', '%{public}s', 'Succeeded in loading the content.');

总结

本文主要从绑定埋点数据出发，介绍了三种埋点的开发实现：包括点击、曝光以及页面埋点。最后可以调用hiAppEvent的addWatcher添加订阅对象和onTrigger回调，在回调中实现数据报上传的逻辑。

• 点击埋点：使用UIObserver的on(“willClick”)跟hiAppEvent的write方法共同实现埋点操作，将埋点数据写入本地设备文件。
• 曝光埋点：使用setOnVisibleAreaApproximateChange跟hiAppEvent的write方法共同实现埋点操作，将埋点数据写入本地设备文件。
• 页面埋点：使用UIObserver的on(“navDestinationSwitch”)跟hiAppEvent的write方法共同实现埋点操作，将埋点数据写入本地设备文件。