likes
comments
collection
share

拥有设计理念的H5埋点方案实践（上篇）

作者站长头像
站长
· 阅读数 31

本文是H5应用的埋点开发方案，基于该模式可以思路清晰的在项目中实现点击、曝光、浏览、自定义埋点。

指令式的埋点使用方式同样非常便利。很适合对埋点开发较少的小白参考，同时可作为埋点库的基础解决方案。

我在文中着重阐述了我对埋点逻辑结构的设计思想。希望它能够成为H5埋点的最佳实践。

在我的项目中代码是用ts编写，但本文的重心并不在维护ts以及文件夹结构上，只会保留关键的TS类型。本文主要讲埋点的实现方式和设计思想。尽量不要直接copy文中代码，因为可能会出现TS类型缺失。你可以选择在copy时改造为纯js，或编写适用于自己项目的TS类型。

因为完整讲解了埋点的逻辑结构和设计思想，所以篇幅较长，我会分为上下两篇，同时发表。

一. 埋点种类与使用方式

埋点的使用方式有两种：

  • 通过Vue指令自动为元素绑定埋点
  • 通过编程式的上报埋点

基础埋点通常有这四种：

  • 元素点击埋点 （当元素被点击时上报）
  • 元素曝光埋点 （当元素在屏幕可见时上报）
  • 元素浏览埋点 （当组件挂载后统计，组件销毁时上报。通常应用于承载“页面”意义的组件，作为“页面浏览埋点”）
  • 自定义埋点 （没有特定上报规则的个性化上报方式）

组合式埋点常用有一种：

  • 元素点击曝光埋点 （点击 + 曝光埋点的功能）

举个例子：

  • Eg: 为某个div元素埋入指令式的点击曝光埋点 v-click-exposure-track="{ <你的埋点参数> }"
<div 
        v-for="(item, index) in navTags" :key="index" :class="{ actived: item.name === activedTag }" 
        class="nav-button" 
        @click="handleNavClick(item.name)"
        v-click-exposure-track="{ 
          b: 'titlebar',
          c: `button`,
          d: `${index + 1}`,
          scm: `server.0.0.0.page.screen_home_${model}.0.0`,
          uri: '/index',
          params: {}
        }"
      >
</div>

二. 创建“埋点”实例——SpmStat

什么是埋点实例？

  • 埋点实例可以视为项目中一类埋点的“基” ，基于不同“基”所上报的埋点参数结构可能是不同的，以点击埋点为例，项目中可以有N种不同的点击埋点，他们上报数据平台，收集的信息可以完全不同，但���他们上报的逻辑，参数的整理方式等是一样的。所以“基”的重点是实现支持不同信息、不同上报方向的相同逻辑。
const spm1 = new SpmStat({ target: 'a.com', spmA: 'A类业务', ...<其他个性化参数> })
const spm2 = new SpmStat({ target: 'b.com', spmA: 'B类业务', ...<其他个性化参数> })

spm1.report({ a: .., b:.., c:.., userId: .. }) // A类业务上报a.com
spm2.report({ a: .., b:.., c:.., userId: .. }) // B类业务上报b.com

1. 处理埋点参数

在埋点实例中，我们首先需要处理上报的参数。

通常情况下，埋点参数，可以分为3类：

  • 永远不会改变的： 当前业务所属大类、机型信息、浏览器信息...
  • 需要实时计算的： 埋点触发时间、当前埋点id、当前用户id...
  • 默认后可覆盖的： 埋点的B/C/D位、跳转方向、等其他个性化参数

下面是我基于本文埋点方案，对H5某项目的仿真实现，可以看出对这三类参数的整理方式：

 // 默认后可覆盖的公共参数
const defaultParams: SpmParams = {
  user_id: "",
  client_time: 0,
  session_id: "",
  event_id: 0,
  event_type: "",
  utm: "",
  spm: "",
  spmref: "",
  scm: "",
  scmref: "",
  uri: "",
  uriref: "",
  params: ""
}

// 埋点id，按顺序从0递增，项目中所有埋点不重样，方便平台排查问题
let currentEventId = 0

export default class SpmStat {
  public env: SpmConfig['env']
  public requestHost: string
  public defaultParams: SpmParams
  public common: Common 
  public queueEventer: CacheQueue

  // 实例化时，可传入上报环境、当前用户user_id
  constructor(config: SpmConfig) {  
    
    this.env = config.env // 记录当前埋点所在环境（测试？预发？开发？）
    this.requestHost = getHost(config.env) // 根据环境拿到上报平台域名
    this.defaultParams = defaultParams // 此类埋点上报时默认可覆盖的参数
    
    // 上报时永远不会变的参数
    this.common = {
      spmA: config.spmA, // 当前业务在公司内的所属大类
      user_agent: getUserAgent(), // 当前用户使用的设备机型信息，按照自己所需改造
      model: getProductModel() // 其他稳定不变的信息...，按照自己所需改造
    }
  }
  
  // 实时计算当前的动态参数
  autoComputedParams(): AutoComputedParams {
    return {
      session_id: '',
      user_id: config.user_id, // 当前用户id，可能已经重新登录，所以上报时需要重新获取
      client_time: Date.now(), // 埋点上报触发时间
      event_id: ++currentEventId // 埋点id，按顺序从0递增，项目中所有埋点不重样，方便平台排查问题
    }
  }
}

2. 处理上报请求

上报本质上就是ajax请求埋点对接的数据平台，需要注意的是，上报方法应暴露为接口。因为对于无法通过指令绑定元素时的上报行为，我们就需要通过调用上报接口的方式编程式的上报。

TIP：实际上，后文讲到的指令中的上报逻辑，也是调用了暴露的上报接口。

比如，我们要上报一个叫做'CUSTOM_EVENT'的自定义埋点事件：

const CUSTOM_EVENT_NAME = 'CUSTOM_EVENT'

const spm = new SpmStat(config)

spm.report(CUSTOM_EVENT_NAME, { a, b, c, ...<你的个性化上报参数> }) // 将report暴露为接口

或者只有当满足某种条件时，才触发TOUCH埋点：

const TOUCH_EVENT_NAME = 'TOUCH_EVENT'

const spm = new SpmStat(config)
const needReport = true

if (needReport) {
    spm.report(TOUCH_EVENT_NAME, { a, b, c, ...<你的个性化上报参数> })
}

对于上报接口，我们实现重心是

  • 对埋点参数的合并和转换
  • 封装ajax请求
export interface DymaicParams {
  event_type?: string
  utm?: string
  spm: string
  spmref?: string
  scm?: string
  scmref?: string
  uri?: string
  uriref?: string
  params?: string // string 是 json字符串
}

// 封装axios做法埋点上报手段。我这里就简单的包装了下axios。
function report(url: string, data: ReportParams) {
  console.log('埋点上报', { url, data })
  axios({
    url,
    method: 'POST',
    params: { format: 'json' },
    data,
    headers: {
      'Content-Type': 'application/json;charset=UTF-8'
    }
  }).catch(err => console.warn('埋点上报发生异常：', err))
}

export default class SpmStat {
  // ...省略前文已有代码
  
  report(params: DymaicParams | DymaicParams[]) {
    const { user_id, user_agent } = this.common
    
    // 在曝光(exposure)场景下，上报的参数可能是数组形式的。
    // 这里对params进行统一数组化
    if (!Array.isArray(params)) {
      params = [params]
    }
    
    // 将三类埋点参数进一步整理你在请求时需要的最终参数格式
    const events = params.map(param => ({
      ...this.defaultParams,
      ...this.autoComputedParams(),
      user_id,
      ...normalizePayload.call(this, param), // 在我的exporsure埋点触发场景下，item会携带client_time，从而覆盖autoComputedParams中计算的client_time
    }))
    
    // 整理你的上报参数格式，这里需要根据自己的需求定制。
    // 在我的仿真H5需求中，user_agent和其他参数是分开的。
    const data: ReportParams = {
      events,
      user_agent
    }
    
    // 发送请求
    report(this.requestHost, data)
  }
}

在上文中，我用了normalizePayload.call(this, param)来整理参数。原因是因为我们在开发时，数据平台要求的埋点参数格式可能对我们来说并不友好，这里做一步转换可以方便你开发时节省心智。

比如：我们的买点有 A/B/C/D 四个位置的参数，开发时，令你觉得方便的参数格式是：

{ A, B, C, D }

可实际上数据平台需要的是：

{ spm: `${A}.${B}.${C}.${D}`}

因此，我建议根据自己的实际情况，去做一层normalize参数的过程，以减少开发中对参数的整理负担。

下面是我的normalizePayload 实现，你可以在normalizePayload 中对每一个字段进一步编写normalize函数：

function normalizePayload(payload: EventParams): DymaicParams {
  const normalizeScm = (): string => {
    const { scm } = payload
    if (typeof scm === 'string') return scm // 如果scm是字符串，可能已经是json，直接返回，无需整理
    if (!isPlainObject(scm)) return '' // 如果不是纯对象，转换成埋点合法的空字符串参数
    return payload.scm = `${scm.a}.${scm.b}_${this.common.model}.${scm.c}.${scm.d}` 
  }

  const normalizeSpm = (): string => {
    const { spm } = payload
    if (typeof spm === 'string') return spm 
    if (!isPlainObject(spm)) return '' 
    return payload.spm = `${this.common.spmA}.${spm.b}_${this.common.model}.${spm.c}.${spm.d}` 
  }

  const normalizeParams = (): string => {
    const { params } = payload
    if (typeof params === 'string') return params
    if (!isPlainObject(params)) return ''
    return payload.params = JSON.stringify({ ...params, model: this.common.model })
  }

  if (!payload) return {
    spm: this.common.spmA // 如果没有参数，最终上报的spm只有A位，方便后台判断错误应用来源
  }

  normalizeSpm()
  normalizeScm()
  normalizeParams()

  return payload as DymaicParams
}

3. 实现 view / touch 便捷上报方法

现在需要实现内置的上报种类。他们需要和report一样被SpmStat实例暴露出来，以供在指令的实现逻辑或在特殊场景下编程式调用。下面来看我的代码实现：

export default class SpmStat {
  // ...省略前文已有代码
  view(params: any) {
    // 在我的需求场景中，数据平台是根据上报参数中的event_type来区分上报的埋点类型的。
    // 你需要换成你的埋点类型区分参数。
    params.event_type = 'VIEW'
    this.report(params)
  }

  touch(params: any) {
    params.event_type = 'TOUCH'
    this.report(params)
  }
}

上面做的事情很简单，就是为params.event_type赋值。在我的需求场景中，数据平台是根据上报参数中的event_type来区分上报的埋点类型的，你需要换成你的埋点类型区分参数。但曝光埋点，我们最好不要简单的直接上报。下面来看看我的exporsure埋点在上报时有什么讲究？

4. 对exporsure埋点的优化

何为曝光(exporsure)？

当一个元素出现在窗口中，且不被遮挡的时候，就叫做曝光。

考虑到很多场景下， 曝光元素多，频繁度高，这里我用了一个“队列”的机制来为短时间内需要曝光的节点进行合并。如果没有这个机制，可想象一下，当一个很长的页面上的每一个楼层，每一个商品图片都需要曝光，当用户一股劲向下翻滚了页面很远，那会有多少曝光请求被短时间内发送，严重情况下甚至会造成接口处理阻塞，影响业务数据的请求。

机制的思路是维护一个可定期自行消化任务的“缓冲队列” ，我们先来定义这个“缓冲队列”的构造器：

export class CacheQueue {
  private queue: (DymaicParams & { client_time?: number })[] 
  private flushBehavior: (dymaicParams: DymaicParams[]) => void

  constructor(cb, duration = 1000) {
    this.queue = [] // 缓冲队列
    this.flushBehavior = cb // 缓冲队列的消化方式（在实例化时提供）
    this.duration = duration // 缓冲队列的消化时间间隔
    this.runQueue() // 开启缓冲队列的定时消化
  }
    
  // 像缓冲队列中增加任务
  push(dymaicParams: DymaicParams & { client_time?: number }) { 
    this.queue.push(dymaicParams)
  }
  // 清空缓冲队列
  clearQueue() {
    this.queue = []
  }
  // 开启定期消化能力
  runQueue() {
    const flusher = setInterval(() => {
      console.log('runQueue 执行')
      if (!this.queue.length) return false
      // 调用消化函数
      this.flushBehavior(this.queue)
      this.clearQueue()
    // 这里的1000ms可以换成你的需求，或者作为duration参数
    }, this.duration)

    return flusher;
  }
}

然后，我们就可以在constructor中实例化这个缓冲队列：

export default class SpmStat {
  // ...省略前文已有代码

  constructor(config: SpmConfig) {  
    // 内部维护一个和缓冲队列，缓冲队列的消化任务的方式是调用 report 进行上报。
    // 值得注意的事，不能忘记对this重定向，不然report中对上报参数的处理过程会出现错误。
    this.queueEventer = new CacheQueue(this.report.bind(this))
  }
  
  // 曝光埋点上报api
  exporsure(params: any) {
    params.event_type = 'EXPORSURE'
    this.queueEventer.push({ ...params, client_time: Date.now() }) // exporsure因为是合并延时上报，所以上报需要额外携带client_time保证触发时间准确，
    // 并覆盖掉report中由autoComputedParams计算的client_time
  }
  
  // 最终参数params代入的就是缓冲队列
  report(params: DymaicParams | DymaicParams[]) {
    const { user_id, user_agent } = this.common

    if (!Array.isArray(params)) {
      params = [params]
    }

    const events = params.map(param => ({
      ...this.defaultParams,
      ...this.autoComputedParams(),
      user_id,
      ...normalizePayload.call(this, param),
    }))

    const data: ReportParams = {
      events,
      user_agent
    }
    
    report(this.requestHost, data)
  }
}

三. 截止目前的全部代码

SpmStat.ts

import defaultParams from './defaultParams'
import CacheQueue from './CacheQueue'

function report(url: string, data: ReportParams) {
  console.log('埋点上报', { url, data })
  axios({
    url,
    method: 'POST',
    params: { format: 'json' },
    data,
    headers: {
      'Content-Type': 'application/json;charset=UTF-8'
    }
  }).catch(err => console.warn('埋点上报发生异常：', err))
}

let currentEventId = 0

function normalizePayload(payload: EventParams): DymaicParams {
  const normalizeScm = (): string => {
    const { scm } = payload
    if (typeof scm === 'string') return scm // 如果scm是字符串，可能已经是json，直接返回，无需整理
    if (!isPlainObject(scm)) return '' // 如果不是纯对象，转换成埋点合法的空字符串参数
    return payload.scm = `${scm.a}.${scm.b}_${this.common.model}.${scm.c}.${scm.d}` 
  }

  const normalizeSpm = (): string => {
    const { spm } = payload
    if (typeof spm === 'string') return spm 
    if (!isPlainObject(spm)) return '' 
    return payload.spm = `${this.common.spmA}.${spm.b}_${this.common.model}.${spm.c}.${spm.d}` 
  }

  const normalizeParams = (): string => {
    const { params } = payload
    if (typeof params === 'string') return params
    if (!isPlainObject(params)) return ''
    return payload.params = JSON.stringify({ ...params, model: this.common.model })
  }

  if (!payload) return {
    spm: this.common.spmA // 如果没有参数，最终上报的spm只有A位，方便后台判断错误应用来源
  }

  normalizeSpm()
  normalizeScm()
  normalizeParams()

  return payload as DymaicParams
}

export default class SpmStat {
  public env: SpmConfig['env']
  public requestHost: string
  public defaultParams: SpmParams
  public common: Common 
  public queueEventer: CacheQueue

  constructor(config: SpmConfig) {  
    this.env = config.env
    this.requestHost = getHost(config.env)
    this.defaultParams = defaultParams
    this.queueEventer = new CacheQueue(this.report.bind(this))

    this.common = {
      user_id: config.user_id,
      spmA: config.spmA,
      user_agent: getUserAgent(),
      model: getProductModel()
    }
  }

  autoComputedParams(): AutoComputedParams {
    return {
      session_id: '',
      client_time: Date.now(),
      event_id: ++currentEventId
    }
  }

  report(params: DymaicParams | DymaicParams[]) {
    const { user_id, user_agent } = this.common

    if (!Array.isArray(params)) {
      params = [params]
    }

    const events = params.map(param => ({
      ...this.defaultParams,
      ...this.autoComputedParams(),
      user_id,
      ...normalizePayload.call(this, param), // visible事件触发是，item会携带client_time从而覆盖autoComputedParams中计算的client_time
    }))

    const data: ReportParams = {
      events,
      user_agent
    }
    
    report(this.requestHost, data)
  }

  view(params: any) {
    params.event_type = 'VIEW'
    this.report(params)
  }

  touch(params: any) {
    params.event_type = 'TOUCH'
    this.report(params)
  }

  exporsure(params: any) {
    params.event_type = 'VISIBLE'
    this.queueEventer.push({ ...params, client_time: Date.now() }) // visible延时上报需要额外携带client_time保证触发时间准确，并覆盖掉report中由autoComputedParams计算的client_time
  }
}

defaultParams.ts

 // 设置上报时的默认公共参数，可随时被覆盖
const defaultParams: SpmParams = {
  user_id: "",
  client_time: 0,
  session_id: "",
  event_id: 0,
  event_type: "",
  utm: "",
  spm: "",
  spmref: "",
  scm: "",
  scmref: "",
  uri: "",
  uriref: "",
  params: ""
}

export { defaultParams }

CacheQueue.ts

export class CacheQueue {
  private queue: (DymaicParams & { client_time?: number })[] // visible事件的上报是延时的，而其他事件是上报是实时的，但无论如何client_time都要是触发时刻，所以visible触发push时会携带额外的clientTime
  private flushBehavior: (dymaicParams: DymaicParams[]) => void

  constructor(cb) {
    this.queue = [] // 缓冲队，主要对visible事件进行缓冲
    this.flushBehavior = cb
    this.runQueue()
  }

  push(dymaicParams: DymaicParams & { client_time?: number }) { 
    this.queue.push(dymaicParams)
  }

  clearQueue() {
    this.queue = []
  }

  runQueue() {
    const flusher = setInterval(() => {
      console.log('runQueue 执行')
      if (!this.queue.length) return false

      this.flushBehavior(this.queue)
      this.clearQueue()
    }, 1000)

    return flusher;
  }
}
转载自:https://juejin.cn/post/7371280074128637991
评论
请登录