wechat-mini-program-ga-sdk

v1.0.2

Published

2 years ago

Integrate Google Analytics with Wechat Mini Program via Measurement Protocol

Downloads

0High
0Medium
0Low

lrenz

Google Analytics WeChat mini-program Wechat Mini Program wepy mpvue taro Measurement Protocol

Wechat Mini Program GA SDK

一个基于mearsurement protocol 封装的微信小程序 SDK. 支持以下特性

Axios-like API, 支持config, transferRequest, transferReponse, Interceptor, API 灵活简单
内置 Logger 功能, 方便调试和检查数据发送状态
内置一系列工具函数,例如regex table. 参数验证等
基于 webpack 开发,易于拓展
同时支持小程序和浏览器

在使用此 SDK 前需要您对 Measurement Protocol 和 GA 有一定了解. 如果您不清楚,以下示例发送的参数代表 GA 的对应指标,请参考以下链接

Install

安装 SDK 最简单的方式是直接下载对应的 js文件并在小程序引入,例如

Const GA = require('./GA/ga.js').default;

或者通过 npm 安装

npm install wechat-mini-program-ga-sdk

手动编译

手动编译需要先安装以下library

yarn add webpack webpack-cli webpack-dev-server babel-loader @babel/core @babel/preset-env

执行 build

yarn build

特别注意, 小程序和浏览器的打包规范是不一样的.小程序需要打包成commonjs, 浏览器则需要打包成umd. 手动打包需要特别修改webpack.config.js 文件的 libraryTarget. 手动编译后再重新在项目中引入

如需在浏览器中调试,请将 webpack.config.js 文件的 libraryTarget 改写成 umd 后执行

yarn start

Getting Start

引入打包文件后, 实例会挂载在default 下.

设置config 并实例化对象,config 在同一个实例会保持一致.
将声明对象并挂载在APP下方便后续使用.
最佳做法是只在 config 中加入所有公用的数据和配置项. 对于需要在特定页面单独发送的数据,则在后续用 get 或者 post 手动添加

var GA = require('./GA/ga.js').default;

const config = {
  data: {  //common request payload
    v: 1,
    cid: 1234556,   //clientId
    tid: "UA-71412438-1",   //ga property ID
    dp: "/not_set",    // document path
    dh:'www.test.com',
    ds: "wechat",    //  data source
    t:"pageview",  //  track type
  },
  maxLogLength:10,
  enableLogger: true,
  proxyURL : "YOUR_PROXY_URL" // Wechat mini program is not allowed to send to GA server directly, you will require a middle server to forward the hits
}

const GA = new GA(config)

为了方便在小程序中使用,可以把对象挂载到 APP 对象中,或者是挂载到 wx 对象中

App({
  ...
  GA
  ...
})

// or
wx.ga = GA

Track Pageview 追踪 pageview 需要在页面出现的时候传入相应的参数.

GA.post({
  dp: '/home'
})

Track Event 追踪 Event 需要在事件触发的时候传入相应的参数.

GA.post({
  t:'event',
  dp: '/pdp',
  ec:'action',
  ea:"add to cart"
})

如果在之后 post 或者 get 中添加的参数与 config 中有重合,则config 中的相应字段会被覆盖.需要注意得是这个覆盖是一次性的.如果之后没有手动传相应得字段,则会从 config 中继续读取默认字段.

另外一种做法是声明两个对象, 一个实例专门用于追踪Pageview, 另外一个用于追踪 Event. 每个实例互不干扰.

const config = {
  data: {  //common request payload
    v: 1,
    cid: 1234556,   //clientId
    tid: "UA-71412438-1",   //ga property ID
    dp: "not_set",    // document path
    dh:'www.test.com',
    ds: "wechat",    //  data source
    t:"pageview",  //  track type
  },
  maxLogLength:10,
  enableLogger: true,
  LoggerName: 'pvLog',
  proxyURL : "YOUR_PROXY_URL" // Wechat mini program is not allowed to send to GA server directly, you will require a middle server to forward the hits
}

const GAPvTracker = new GA(config)

const Eventconfig = {
  data: {  //common request payload
    v: 1,
    cid: 1234556,   //clientId
    tid: "UA-71412438-1",   //ga property ID
    dp: "not_set",    // document path
    dh:'www.test.com',
    ds: "wechat",    //  data source
    t:"event",  //  track type
  },
  maxLogLength:10,
  enableLogger: true,
  LoggerName: 'Event',  // Logger Name to store the log locally
  proxyURL : "YOUR_PROXY_URL" // Wechat mini program is not allowed to send to GA server directly, you will require a middle server to forward the hits
}

const GAEventTracker = new GA(Eventconfig)

Custom Dimension & Custom Metrics

Custom Dimension / Custom Metrics

要设置 custom dimension 最简单的方式, 就是定义在 config 中或者手动传入, 例如


const config = {
  data: {  //common request payload
    v: 1,
    cid: 1234556,   //clientId
    tid: "UA-71412438-1",   //ga property ID
    dp: "/not_set",    // document path
    dh:'www.test.com',
    ds: "wechat",    //  data source
    t:"pageview",  //  track type,
	cd1: "custom dimension 1",
	cd2: "custom dimension 2",
	cm1: "5.00"

  },
  maxLogLength:10,
  enableLogger: true,
  LoggerName: 'pvLog',
  debug:true,
}

const GAPvTracker = new GA(config)

或者是后续手动传入


GA.post({
  t:'event',
  dp: '/pdp',
  ec:'action',
  ea:"add to cart",
  cd1: "custom dimension 1",
  cd2: "custom dimension 2",
  cm1: "5.00"
})

Product Scope Custom Dimension

对于 hit 或者是 user scope 的 dimension / metric 可以用以上的方法传入. 对于 product scope 的 dimension 和 metric 则要通过以下的方式进行定义. Product Scope CD 只能通过以下的方式手动传入,不支持在 config 中提前定义.

GA.post({
    dp: "/wechat",
    t: 'event',
    ec: "test",
    ea: "wechatSDK",
    pa: "detail",

    "products": [{
        "id": "bc823",
        "name": "Fuelworks T-Shirt",
        "price": "92.00",
        "brand": "Fuelworks",
        "category": "T-Shirts",
        "position": "4"
    }, ],
    productScopeCD: {
        '3': 'custom dimension3',  // cd Index : cd Value
        '4': "custom dimension3"
    },
    productScopeCM: {
        '2': 100,  // cm Index : cm Value
    }
})

Enhance Ecommerce Tracking

Enhance Ecommerce 的功能也是遵循 Mearseurement protocol 的规范实现的. SDK 在此基础上增加了对 products/impressions/promotions 的支持, 以提高易用性. 请注意, 不要把products 相关的信息定义到 config 里, 最佳做法是在特定页面把 products/impressions/promotions 相关数据手动传入.

Details 追踪 Enhance Ecommerce details 需要定义参数 pa 和对应的 products

GA.post({
    dp: "/pdp",
    pa: "detail",
    products: [{
        id: "b55da",
        name: "Flexigen T-Shirt",
        price: "16.00",
        brand: "Flexigen",
        category: "T-Shirts",
    }]
})

Add to cart 追踪 Enhance Ecommerce Add to cart 需要定义参数 pa 和对应的 products

GA.post({
    dp: "/cart",
    pa: "add",
    products: [{
        id: "b55da",
        name: "Flexigen T-Shirt",
        price: "16.00",
        brand: "Flexigen",
        category: "T-Shirts",
    }]
})

Remove from cart

追踪 Enhance Ecommerce Remove from cart 需要定义参数 pa 和对应的 products

GA.post({
    dp: "/cart",
    pa: "remove",
    products: [{
        id: "b55da",
        name: "Flexigen T-Shirt",
        price: "16.00",
        brand: "Flexigen",
        category: "T-Shirts",
    }]
})

Checkout 追踪 Enhance Ecommerce Checkout 需要定义参数 pa 和对应的 products 以及 cos (checkout step)

GA.post({
    dp: "/cart",
    pa: "checkout",
	cos:"1", //checkout step
    products: [{
        id: "b55da",
        name: "Flexigen T-Shirt",
        price: "16.00",
        brand: "Flexigen",
        category: "T-Shirts",
    }]
})

Checkout option 追踪 Enhance Ecommerce Checkout option 需要定义参数 pa 和对应的 cos 值

GA.post({
     t: "event",
	 ec: "Checkout options",
	 ea: "shipping"
    dp: "/cart",
    pa: "checkout_option",
	cos:"顺丰",
})

Transaction 追踪 Enhance Ecommerce Checkout option 需要定义参数 ti ,tt, 以及对应的结账 products

GA.post({
    dp: "/thankyou",
    pa: "purchase",
	ti: "cd2ad00b-acc9-45ab-b1e0-f4720375d2f0",
	ta: "Online Store",
	tr: 118,
	tt: 5.00,
	ts: 5.00,
    products: [{
        id: "b55da",
        name: "Flexigen T-Shirt",
        price: "16.00",
        brand: "Flexigen",
        category: "T-Shirts",
    }]
})

Refund 追踪 Enhance Ecommerce Checkout option 需要定义参数 ti ,tt, 以及对应的结账 products

GA.post({
    dp: "/refund",
    pa: "refund",
	ti: "cd2ad00b-acc9-45ab-b1e0-f4720375d2f0",
	ta: "Online Store",
	tr: 118,
	tt: 5.00,
	ts: 5.00,
})

Impression

追踪 Enhance Ecommerce Checkout option 需要传入对应的的展示商品

GA.post({
    dp: "/top10Tshirt",
    impresstions: [{
            "id": "b55da",
            "name": "Flexigen T-Shirt",
            "price": "16.00",
            "brand": "Flexigen",
            "category": "T-Shirts",
            "position": 0,
            "list": "top10"
        },
        {
            "id": "f6be8",
            "name": "Comverges T-Shirt",
            "price": "33.00",
            "brand": "Comverges",
            "category": "T-Shirts",
            "position": 1,
            "list": "top10"
        }
    ]
})

Impression click

追踪 Enhance Ecommerce Checkout 需要定义参数 pa 和对应的 products

GA.post({
    dp: "/top10Tshirt",
    pa: "click",
	pal:"top10", // 对应 impressions 中 的list
	products: [{
      "id": "b55da",
      "name": "Flexigen T-Shirt",
      "price": "16.00",
      "brand": "Flexigen",
      "category": "T-Shirts",
      "position": 1,
    }]
})

Promotion 追踪 Enhance Ecommerce Checkout 需要定义对应的 promotions

GA.post({
    dp: "/top10Tshirt",
     promotions: [{
        "id": "bts",
        "name": "Back To School",
        "creative": "PRODUCT banner",
        "position": "right sidebar"
      }]
})

Promotion click

追踪 Enhance Ecommerce Checkout 需要定义对应的被点击的 promotions 和参数 promoa

GA.post({
    dp: "/top10Tshirt",
	promoa: "click",
     promotions: [{
        "id": "bts",
        "name": "Back To School",
        "creative": "PRODUCT banner",
        "position": "right sidebar"
      }]
})

请注意, SDK 只对 products/impressions/promotions 相关进行了相应的简化处理, 其余参数依旧遵循了 Mearseurement protocol 的规范. 参数对应的值,请参阅 Mearseurement protocol 的规范. 当然你可以直接不使用以上语法糖进行products 参数的转换,手动将自行转换好的参数,传入并发送. 例如

GA.post({
    dp: "/top10Tshirt",
	promoa: "click",
   promo1id: "bts",
   promo1nm: "Back To School",
   promo1cr: "PRODUCT banner",
   promo1ps: "right sidebar",
   promoa: "click"
})

impression 和 promo 同样也可以跟着其他类型一起发送

GA.post({
    dp: "/pdp",
    pa: "detail",
    products: [{
        id: "b55da",
        name: "Flexigen T-Shirt",
        price: "16.00",
        brand: "Flexigen",
        category: "T-Shirts",
    }],
    promotions: [{
        "id": "bts",
        "name": "Back To School",
        "creative": "PRODUCT banner",
        "position": "right sidebar"
    }],
    impresstions: [{
            "id": "b55da",
            "name": "Flexigen T-Shirt",
            "price": "16.00",
            "brand": "Flexigen",
            "category": "T-Shirts",
            "position": 0,
            "list": "top10"
        },
        {
            "id": "f6be8",
            "name": "Comverges T-Shirt",
            "price": "33.00",
            "brand": "Comverges",
            "category": "T-Shirts",
            "position": 1,
            "list": "top10"
        }
    ]
})

Media Tracking

对于 GA UTM tracking, 同样需要提前定义相关参数,例如以下示例.

var config = {
    data: { //common request payload
        v: 1,
        cid: 1234556,
        tid: "UA-71412438-1",
        dp: "/not_set",
        ds: "wechat",
        t: "pageview",
    },
    debug: true,
    validateHit: true, // will send to the vvalidation endpoint(optional)
    maxLogLength: 10,
    enableLogger: true,
}

App({
    onShow: function(options) {
        let utm = {
            cs: "wechat",  // utm_source
            cm: options.scene, // utm_medium
            cn: "Campaign Name", // utm_campaign
            cc: "content", // utm_campaign
        }
        config.data = {
            ...config.data,
            ...utm
        }
        var GA = new GA(config)
        GA.post({
            dp: "/App_launch"
        })
    },
})

场景值 (Scene Value) 是微信小程序提供用来描述用户进入小程序的路径. 场景值通常可用于展现不同的入口带来的流量. 以上示例将场景值放在 medium 中来区别从不同入口进入小程序的流量

对于扫描二维码进去小程序的场景,则需要将相应的 UTM 参数加入到二维码中,当用户扫描二维码进入的时候读取相应的 source/medium/campaign/content 相应值, 并发送到 GA

Best Practice

Regex Table 转换对应的参数

在真正的 tracking 项目中, 经常会需要根据条件来判断和处理对应的值. 通过 SDK 提供的 interceptor 和 regex table, 我们可以轻松完成这种处理,并使代码保持整洁示例: 根据 regex 来给对应的 dp 进行分组设置, 并设置 Content Grouping

const m = [{
        inputRegex: "index",
        outputName: "'home'"
    },
    {
        inputRegex: "T-shirt|dress|shoes",
        outputName: "'pdp'"
    },
    {
        inputRegex: "myAccount|login|signup",
        outputName: "'account'"
    },
    {
        default: "others"
    }
]
GA.interceptors.request.use(function(config) { // push a handler function before send request
    config.data.cg1 = GA.weUtils.map(m, config.data.dp) // process data before send to GA, set content gronping 1
    return config;
});

利用 logger 来重新发送失败请求

通过 SDK 提供的 interceptor 和 Logger , 也可以轻易的实现错误重试的功能. 以下示例会在每次发送请求前检查存在本地的请求是否失败,并重新发送. 请注意, 如果要加上错误重试功能,请务必加上重试次数,否则有可能造成死循环.

let conf = {
    LoggerName: "retry",
    maxLogLength: 10,
    debug: true,
    data: {
        'ua': "UA-1-1",
        "v": 1
    }
}
var retry = new GA(conf)
GA.interceptors.request.use(function(config) { // push a handler function before send request
    let t = GA.log.find(n => n.type = 'error')
    //console.log(t)
    retry.post(t.data)
    return config;
});

页面劫持自动发送 pageView

小程序有生命周期的概念,在启动过程中有不同的阶段用于不同的处理. pageview应该在 onShow 触发最为合适.

小程序的开发构架是每个页面都有独立的启动阶段,那么对应 pageview 埋点而言, 就要在手动的在每个页面的 onShow 里调用相应的 pageview 代码. 这在页面很多的时候会显得不易维护且相对麻烦. 小程序的 Page 对象是可以在每个页面共享的, 所以理论上我们可以通过劫持 Page 来实现自动埋点.

const originPage = Page;

Page = (page) => {
  const originMethod = page['onShow'];
  page['onShow'] = function () {
    GA.post({
      dp: this.route,
    })
    return originMethod();
  }
  return originPage(page);
};

以上代码会劫持每个页面的 page 函数,并在之间先执行 pageview 上报,再继续执行原来每个页面的定义的 onShow 函数. 每当每个页面的 Page 渲染的时候便可以实现自动的上报.

但是这个做法也会造成一些问题. 例如, 假设我需要在一些特殊的页面多发几个 CD 呢? 自动上报的并不包含这些 cd. 一个好的解决方案是, 在 config 里定义所需全部变量, 在不同页面,如果有值返回 true, 没有则返回 false. 请求在发送前会将所有为 false 的参数 filter out


var config = {
    data: { //common request payload
        v: 1,
        cid: 1234556,
        tid: "UA-71412438-1",
        dp: getPage(),
        ds: "wechat",
        t: "pageview",
		cd1: getCD1(),
		cd2: getCD2()
    },
    debug: true,
    validateHit: true, // will send to the vvalidation endpoint(optional)
    maxLogLength: 10,
    enableLogger: true,
}

另一种方案是在 onShow 函数传递相应的参数



const originPage = Page;

Page = (page) => {
  const originMethod = page['onShow'];
  page['onShow'] = function (data) {
    GA.post({
      dp: this.route,
	  cd1: data.cd1,
	  cd2: data.cd2,
    })
    return originMethod();
  }
  return originPage(page);
};

如果在页面不多的情况下, 手动埋点依旧是最佳的方式.

API Usage

[GA].post / [GA].get

用于指定发送数据的方式. 我们在这里强烈推荐使用 post 发送数据.

GA.post({
    ua: "UA-1-234567",
    v: "1",
    cid: "123456",
    dp: "/home"
})

如果出于特殊的原因,也可以使用 get 发送请求

GA.get({
    ua: "UA-1-234567",
    v: "1",
    cid: "123456",
    dp: "/home"
})

[GA].validation

SDK 内置实现了一个简易的用于验证参数的对象. 可用于自定义检验参数的规则. Mearsurement Protocol 本身不对参数进行校验, 此模块默认不开启. 需要开启此模块,则需要在 config 设置 validateParams 为 true. 通常建议在开发调试阶段使用此模块检验请求参数,在生产环境关闭此模块.

内置默认了以下几个简单检查规则

检查 cid ua cid 是否存在
检查 ua 的格式
检查请求的长度是否超出 GA 限制的 8012KB

提供以下 API 用于自定义检验规则

[GA].validation.addRequirelist

使用以上方法可以增加需要检查的必须参数. 以下例子用于定义了对 dp 是否存在的检查

GA.validation.addRequirelist("dp")

[GA].validation.addRegexList

使用以上方法可以自定义regex 用于检查相应的参数. 以下例子定义了对 regex 对 dh 和 dl 进行检查

GA.validation.addRegexList({
    "dh":"uat|dev|qa.gatest.com",
	"dp" : "[^\/]$"
})

[GA].validation.add

自定义检验函数, 传入函数会保存在 array 中按顺序执行.可以多次使用此 API 传入多个自定义检验函数. 以下示例用于检查请求参数中是否dp 和 dh 都存在

GA.validation.add((obj) =>{
    if(obj.hasOwnProperty("dp") && obj.hasOwnProperty("dh") ){
	    return obj
	}
	return throw new Error("dp and dh is mandotory!")
	})

[GA].interceptor.request.use

interceptor 用于在请求发出去前拦截对象并做相应处理. interceptor 与 config 中的 transferReponse 的不同是 interceptor 可以设置多个拦截函数. 以下示例展现每次拦截对象并对 dp 进行相应的处理.

GA.interceptors.request.use(function(res) { // push a handler function before send request
      res.data.dp = res.data.dp == 'index'? "home": res.data.dp // process data before send to GA
      return res;
});

[GA].weUtils

内置的小程序工具函数.

-[GA].weUtils.map

内置的 regex table, 可用于对数据进行额外的 regex table 的处理

以下是一个示例, 用于输出对应的 GA property

let m = [{
        inputRegex: "au|en|fr.gatest.com",
        outputName: "UA-7689450-6"
    },
	{
	    inputRegex: "cn.gatest.com",
        outputName: "UA-7689450-6"
	},
    {
        default: "UA-1-1"
    }
]

let tid = GA.weUtils.map(m,"dl")
console.log(tid)

-[GA].weUtils.mappingSceneToCN

内置工具将场景值转换成中文

以下是一个示例, 用于输出对应的 GA property


App({
    onLaunch: function() {
        console.log('App Launch')
    },
    onShow: function(options) {
        let cm = GA.weUtils.mappingSceneToCN(options.scene)
        console.log(cm)
    }
})

[GA].getLog

let log = GA.getLog()
console.log(log)

[GA].setLog

以下实例展现了增加一个 log 到本地

let log = GA.getLog()
log.push({
    type:"inset a log",
	data: "test log",
})
GA.setLog(log)
console.log(log)

config

config 用于管理实例的配置, 需要在实例化时传入,不允许为空. 默认有以下配置

data: 需要在默认配置中发送到 GA 的数据.需要以对象的格式传入

proxyURL: 微信小程序不能直接发数据到 GA 的 endpoint, 因为需要一个转发服务器用于转发相应的请求到 GA 的服务器. 这个参数在生产环境的时候是必须要设置的

debug: 参数用与决定实例是否开启调试模式. 主要用户在开发阶段验证参数是否可以直接被 GA 收到. 当没有制定 proxyURL 并且 debug 为 true 的时候, 默认发送的 endpoint 为 https://www.google-analytics.com/collect

**validateHit **: 此参数设置为true, 则发送数据的endpoint 将会设置成 https://www.google-analytics.com/debug/collect . 可用于检验发送给 GA 参数是否合规, GA 是否能正确的解析参数. 关于此 endpoint 请请参阅 Measurement Protocol debug

**enableLogger ** : 此参数用于决定是否开启 Logger 用于记录发送的请求. 发送的请求的会存在 localStorage (web) 或者是 Storage (wechat)

**LoggerName ** : 此参数用于决定存在 localStorage (web) 或者 Storage (wechat) 的键值. 如果有多个实例, 建议为每个实例设置不同 LoggerName

wxRequestTimeout : 此参数用于请求的微信小程序 timeout 间隔.

| Params | Type |defalut Value | Expected Value | Comment | |:----: |:----: | :----: |:----: |:----: | | wxRequestTimeout | Number | 2000 | 3000,4000 | 单位是毫秒 |

transaferRequest : 在发送 Request 之前进行额外的处理.

transferResponse : 在收到 Response 之后进行额外的处理.

onSuccess : 发送成功之后的回调函数

onError : 发送失败之后的回调函数.

Config 必须在创建实例时传入,以下是一个示例

const config = {
    transferRequest(config) {
        console.log('do something before sending the hit')
        //config.data.dp = "/test"
        return config
    },
    transferResponse(res) {
        console.log("do something for the response")
        return res
    },
    data: { //common request payload
        v: 1,
        cid: 1234556, //clientId
        tid: env == 'dev': "UA-5465464-2": "UA-78546532-1",
        ds: "wechat", //  data source
        t: "pageview", //  track type
        debug: true,
        validateHit: true,
    },
    maxLogLength: 10,
    enableLogger: true,
    LoggerName: 'WechatLog',
    onSuccess(config, res) {
        console.log("success") //your custom success function (options)
    },
    onError(config, res) {
        console.log("Error")
    },
}
const GA = new GA(config)

TODO

移除 web 相关功能
- 未来将在下一版本中逐渐移除 web 相关的支持, 如果需要在 web 端有相应的场景, 请直接使用官方 GA SDK 和 GTM. 这里增加 web 的支持只是为了方便调试.
整合微信小程序相关API
- 将进一步整合微信小程序内置 API, 简化部署方式
UTM 参数的自动读取
- 下一版本会支持自动从 route 中读取 UTM 参数
提高代码健壮程度, 重构代码
- 移除无用代码, 增加错误验证, 优化报错信息, 重新组织代码

Authors

LRENZ- simple is less - Linkedin

Reference

此 SDK 只是从代码层面提供了一个 API 友好并且功能完善的的解决方案. 对于一个完整的微信的小程序 tracking, 更多的时间也要花在定义需要追踪 KPI 并将这些 KPI 转化到需要发送到 GA 的参数. 因为, 非常建议在使用此 SDK 前先了解 GA 和 Measurement Protocol

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme