跳转到主要内容
开发者中心
PRODUCT DOCUMENTS

快速找到所需文档，高效完成接入与排障

浏览产品文档与友盟 Skill，展开目录并阅读正文。

H5 SDK集成

支持类型：Web、H5、App内嵌H5、小程序内嵌H5、微信端网页

1

产品官网地址：https://www.umeng.com/miniprogram

H5功能介绍文档：https://developer.umeng.com/docs/147615/detail/290934

适用范围

本文档适用于 U-Mini H5 SDK 1.7.4及以上的版本。

当前集成文档常用API：

  1. （单页面应用）关闭自动PV& 手动PV事件

  2. 页面点击事件

  3. 预置元素曝光事件

当前集成文档需关注的重点、错点如下：

  1. 集成SDK，注意SDK的集成位置，为保证SDK的统计的准确性，请根据SDK集成代码注释说明，给SDK放在最高优先级的文件和位置，结合自身项目是否为单页面项目对SDK集成代码进行删减。

  2. 如果是单页面应用，为了保证页面路径统计的准确性，需要关闭自动PV，然后在路由跳转前或路由跳转后发送一条sendPV事件，以确保跳转后的url可以被SDK成功记录并上报！

  3. 若集成后发现数据量比预想中的要多，请检查第二条发送sendPV事件的时候是否关闭了自动PV，这两个API是相辅相成的，有sendPV的时候必须要关闭自动PV！

  4. 若集成后发现没有报错，没有数据，network下没有web_logs发送，请检查是否开启了关闭自动PV，没有手动发送sendPV！

  5. sendPV事件仅有发送PV的功能，无法上报自定义属性，arguments的内容在后台没有展示，请准确区分PV事件与自定义事件(页面点击事件)的区别。

  6. 页面点击事件的eventType请务必填写 'CLK' 此处为固定值，eventParams里的eventValue严格区分数值型和字符型，第一次上报的eventValue类型将决定eventName的类型，且后续无法更改！

  7. 以下保留字均不可作为属性名称使用：uid、aplus、spm-url、spm-pre、spm-cnt、pvid、dev_id、anony_id、user_id、user_nick、_session_id、id、ts、du、token、device_name、device_model 、device_brand、country、city、channel、province、appkey、app_version、access、launch、pre_app_version、terminate、no_first_pay、is_newpayer、first_pay_at、first_pay_level、first_pay_source、first_pay_user_level、first_pay_version、page、path、openid、unionid、scene

  8. 有日志上报，但是后台没有数据，请检索集成代码是否错误的配置了idtype！

一、快速集成

1.1 登录

登录

应用注册成功后，跳转到第二步SDK的安装及集成，此时会得到集成sdk所需要的appkey

1.2 集成SDK

在页面head标签内加入集成代码，确保aplus_queue不被污染。

若当前集成SDK项目使用的是单页面应用例如：React、Vue、Angular等，请将下方的SDK代码放在项目的index.html，在单页面项目中index.html的优先级是最高的，所有文件都会通过index.html呈现。

<head>
  <script>
   (function(w, d, s, q, i) {
     w[q] = w[q] || [];
     var f = d.getElementsByTagName(s)[0],j = d.createElement(s);
     j.async = true;
     j.id = 'beacon-aplus';
     j.src = 'https://d.alicdn.com/alilog/mlog/aplus/' + i + '.js';
     f.parentNode.insertBefore(j, f);
    })(window, document, 'script', 'aplus_queue', '203467608');

    //集成应用的appKey
    aplus_queue.push({
      action: 'aplus.setMetaInfo',
      arguments: ['appKey', 'xxxxxxx']
    });

    /* 如果使用的是单页面应用，例如：React、Vue、Angular等，则需要添加下面的代码 */
    /* 关闭自动PV发送，如果不是单页面应用，请删掉下方代码 */
    aplus_queue.push({
      action: 'aplus.setMetaInfo',
      arguments: ['aplus-waiting', 'MAN']
    });

		//是否开启调试模式 
    aplus_queue.push({
      action: 'aplus.setMetaInfo',
      arguments: ['DEBUG', true]
    });
  </script>
</head>

在完成当前步骤之后，您就可以开始在应用工程开始埋点了。

二、事件埋点

重要提示：每次调用aplus_queue需先声明 const {aplus_queue} = window;

2.1 SDK设置

2.1.1 setMetaInfo

用于变更SDK的默认设置

const {aplus_queue} = window;
aplus_queue.push({
 action: 'aplus.setMetaInfo',
  arguments: [metaName, metaValue, mode]
});

其中：

  • metaName 为可配置的元数据项，可配置的 meta项见下文附表1：metaName 及 metaValue 对应表

  • metaValue 为对应的元配置项取值

  • mode 为模式，其取值为枚举值：

    • "OVERWRITE": 覆盖模式，原 meta 值将直接被覆盖，注意对于取值为单值的 meta 只有覆盖模式

      • 默认值

    • "APPEND": 追加模式，仅适用于 meta 取值为数组对象的 meta，追加模式下原取值保留

2.1.2 getMetaInfo

用于动态获取 SDK 的当前配置

aplus.getMetaInfo(metaName);

目前支持的 metaName 及 metaValue见，附表1

2.2 异步上报

有些信息如用户id、用户昵称等是异步获取的，这种情况下如果您需要等待异步信息获取成功后再上报日志，sdk这边提供了设置元配置信息_hold = BLOCK 来阻塞上报，再时机成熟时通过更新元配置信息_hold=START来开启上报

const {aplus_queue} = window;
//如采集用户信息是异步行为，需要先阻止SDK上报，设置BLOCK埋点
aplus_queue.push({
 action: 'aplus.setMetaInfo',
  arguments: ['_hold', 'BLOCK'] 
});

//异步耗时流程 (如获取user_id)
aplus_queue.push({
 action: 'aplus.setMetaInfo',
  arguments: ['_user_id', 'test_user_id'] 
});

// 因为采集用户信息是异步行为，故需要先设置BLOCK，再设置START
// 设置_hold=START后，事先被block住的日志会携带上用户信息逐条发出
aplus_queue.push({
 action: 'aplus.setMetaInfo',
  arguments: ['_hold', 'START'] 
});

2.3 页面曝光事件

sendPV

若当前项目为单页面应用时，需要在路由跳转的时候手动发送一次PV，使用下方的PV发送事件发送，此API并非是自定义事件，arguments的属性不在后台中展示，自定义事件请参考下方页面点击事件

const {aplus_queue} = window;
aplus_queue.push({
 action: 'aplus.sendPV',
 arguments: [{is_auto: false}] // 此处上报的数据暂时在后台没有展示
});

效果如： 2

警告

：sdk 默认提供自动pv的能力；但若metaInfo配置信息中aplus-waiting等于MAN时，此时pv的发送时机改为由开发者自己控制，特别是当您的H5应用是一个单页应用时，您必须通过调用sendPV来发送页面曝光事件；pv事件一定要发送，否则影响新增、活跃、分享回流等指标的计算！！

2.4 页面点击事件

record

record 用于发送一条事件日志，其 API 定义如下： 

const {aplus_queue} = window;
aplus_queue.push({
 action: 'aplus.record',
  arguments: [eventCode, eventType, eventParams]
});

其中，

  • eventCode：事件ID 或 事件编码，字符串类型

  • eventType：'CLK' ， 固定值

  • eventParams 为本次事件中上报的事件参数。其取值为一个JSON对象（平铺的简单对象，不能多层嵌套）

    • 调用 record api 上报参数时，该次赋值仅对该条事件有效

    • SDK保留属性：uid, aplus, spm-url, spm-pre, spm-cnt, pvid,dev_id,anony_id,user_id,user_nick, _session_id

const {aplus_queue} = window;
//一个简单的demo
aplus_queue.push({
 action: 'aplus.record',
  arguments: ['yourTrackerEventCode', 'CLK', {
     param1: '111',
     param2: '222',
     param3: 333
   }]
});

效果如下：

3

2.5 预制元素事件

2.5.1 手动曝光

借用record API的能力，当事件id为$$_exposure时，事件被统计为预制元素曝光事件，支持聚合上报和单独上报待曝光元素的id

重要

待曝光元素key为字符串类型， 取值value为字符串或Number类型，长度均限制为128位字符以内；如果聚合上报，最多支持100个key

API调用方式如下：

const {aplus_queue} = window;
//一个简单的demo
aplus_queue.push({
 action: 'aplus.record',
  arguments: ['$$_exposure', 'EXP', {
    //key为字符串类型, value为字符串或Number类型，长度均限制在128位字符以内
     id1: "testItemId1", 
     id2: "testItemId2", 
     id3: "testItemId3"
   }]
});

效果图如下：

手动曝光

2.5.2 自动曝光

通过手动曝光的方式，开发者需要自己考虑元素曝光的时机，为了方便开发者使用曝光功能，sdk增加了元素自动曝光的能力，开发者需修改DOM元素配置如下：

  • 配置待曝光元素的class

  • 配置待曝光元素需携带的自定义参数，需使用数据属性data-xxx模式

<body>
  ...
  <div class="parent">
    <div class="auto-exp-component" data-itemid="test_exp_id">
       自动曝光元素，无需点击
     </div>
  </div>
  ...
</body>

同时为了识别需要曝光的元素，sdk 需要增加如下配置：

const { aplus_queue } = window; 
aplus_queue.push({
  action: 'aplus.setMetaInfo',
  arguments: ['aplus-auto-exp', [
     {
        // 需要曝光的元素class
        cssSelector: '.auto-exp-component', 
        //如果页面模块是元素内滚动（某个区块内有滚动条）则需要增加positionSelector辅助定位曝光元素
        positionSelector: '.parent', 
        logkey: 'test_event_id',  //事件管理中的事件id
        props: ['data-itemid'], // 你要曝光的元素身上自定义属性
      },
     ...
    ],
  ],
});
重要

注意：1. 自动曝光默认规则是符合埋点选择器的模块的30%面积出现在视口内达到500ms，如果存在浮层层叠也依然会上报；2.如果页面模块是元素内滚动（某个区块内有滚动条）则需要增加positionSelector辅助定位曝光元素

效果如下：

自动曝光

三、h5分享统计

为了满足移动端H5统计分析、分享回流等业务场景，sdk同时提供了如下API以满足业务需求：

3.1 getTrackCode

用于获取记录下个分享人的trackCode，调用时机由开发者自定义

请求示例：

//query信息来源于浏览器url后面查询信息，例如：http://www.test.com?a=1&b=2&c=3
//这里query就是{a:1, b:2, c:3}这样的字典，由开发者自行解析
let data = {
  appkey: query.fromappkey,
  openid: oid || query.id, 
  unionId: query.uid || 'aTestUnionid',
  trackCode: query.tc || '',
  rootTrackCode: '',
  url: location.href || 'testurl'
};
aplus.getNextTrackCode(data, function(data){
  console.log('NextTrackCode:', data.trackCode);
});

请求参数

属性名

类型

必填

描述

默认值

示例

appkey

string

是

应用appkey

undefined

xxxxxxxxx

openid

string

是

业务域用户唯一标识

由服务端下发的cookieId

xxxxxxxx

unionid

string

是

微信场景下用户唯一标识，微信开放平台帐号下的移动应用、网站应用和公众帐号，用户的unionid是唯一的

undefined

xxxxxxxx

trackcode

string

否

上一个分享人的trackCode

undefined

baa8bdc7a40cacf120eca878701ed9ab

rootTrackCode

string

否

初始trackCode

undefined

baa8bdc7a40cacf120eca878701ed9ab

url

string

否

分享url

location.href

https://www.umeng.com

callback

function

是

请求回调函数

undefined

() => {} 或者 function(){}

返回响应：

//success
{
 trackCode,
  _um_ssrc
}

//fail
{} //空对象

3.2 trackShare

预制分享事件，底层依赖业务日志API record，独立封装方便开发者调用，调用时机由开发者自定义

请求示例：

aplus.trackShare({a: 1, b: 2}, function(){
 console.log('分享回调');
});

请求参数：

属性名

类型

必填

描述

默认值

示例

data

object

否

用户自定义参数

undefined

{a: 1, b: 2}

callback

function

否

请求回调函数

undefined

请求响应：参照业务日志API record 调用结果

3.3 uploadUserProfile

用户信息上报接口，调用时机由开发者自定义

请求示例

var ui = {
  ak: 'testappkey',
  sdt: 'h5mp',
  aid: '',
  uin: 'testusernick',
  uia: 'testuseravatar',
  uig: 'female',
  uit: 'China',
  uip: 'Beijing',
  uic: 'Beijing',
  uil: 'Chinese',
  id: 'atestUserid',
  it: 'cnaid' //请与aplus-idtype值保持一致
};
aplus.uploadUserProfile(JSON.stringify(ui), function(res) {
  console.log('uploadUserProfile: ', res);
});

请求参数：

参数

类型

必填

描述

默认值

示例

ui

string

是

用户信息Object的json string

""

callback

funtion

否

请求回调

undefined

() => {}

属性说明

类型

是否必填

说明

ak

string

是

appkey

sdt

string

是

sdktype

aid

string

否

appid

uin

string

否

用户昵称

uia

string

否

头像url

uig

string

否

性别

uit

string

否

国家

uip

string

否

省

uic

string

否

城市

uil

string

否

语言

id

string

是

用户id

it

string

是

id_type

请求响应：

// success
{
    "msg": "成功",
    "code": 200,
    "data": "ok"
}

//fail
{} //空对象

四、 H5自定义ID代码示例

一般情况下H5 SDK对于用户的统计会使用SDK自动生成的cnaid，少数情况下可能我们会有自定义id的需求，友盟SDK提供了自定义id的API，示例如下：

// 此处文档以uuid作为示例 
const {aplus_queue} = window;
aplus_queue.push({  // 设置idtype
   action: 'aplus.setMetaInfo',
   arguments: ['aplus-idtype', 'uuid'] //取值参考见附表1
 });
  
 aplus_queue.push({  //设置userid
   action: 'aplus.setMetaInfo', 
   // uuid一般是一个32位的随机字符串，当前value仅作为示例参考
   arguments: ['uuid', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx']
 });

附表1：metaName 及 metaValue 对应表

MetaName

元配置说明

metaValue赋值说明

是否已支持

globalproperty

全局属性，设置全局属性后，此后自定义事件、PV均会携带上报

一级的key-value对象结构举例：aplus_queue.push({action: 'aplus.setMetaInfo',arguments: ['globalproperty', {a: 1, b: 2}]});

Y

aplus-rhost-v

采集上报域名

默认值 umini.shujupie.com

Y

_user_id

设置userid

业务自定义的登录账号ID

Y

_user_nick

上报用户信息需要

业务自定义的登录账号昵称

Y

_hold

发送Hold信号. 在 SDK整个生命周期内, _hold只能被设置一次

枚举类型, 可用值及说明如下:"START": 开启日志发送"BLOCK": 阻止日志发送，可以在 BLOCK状态之前，完善发送日志前的准备工作

Y

aplus-waiting

日志发送时机设置

枚举类型，可用值及说明如下："1": 等待6秒后尝试发送"N": N取值为300-3000之间的整数值 , 所有日志指令在SDK初始化完成后的N毫秒内将被hold在指令队列, 直至N毫秒等待结束."MAN": 取消自动化PV日志采集. 设置为MAN之后, 所有PV日志均需手动触发, 但其他类型的事件日志不受影响

Y

openid

微信体系下用户标识

无默认值

Y

unionid

微信体系下公众号、小程序等用户唯一标识

无默认值

Y

anouymousopenid

字节小程序用户唯一标识

无默认值

Y

alipayid

支付宝小程序用户唯一标识

无默认值

Y

swanid

百度小程序用户唯一标识

无默认值

Y

uuid

业务方自定义的随机id

无默认值

Y

aplus-idtype

指定用于生成umid的id类型

openid,unionid,alipay_id,uuid,anonymousid,cnaid

注：如果设置了idtype，必须同步设置对应平台的唯一id，如：idtype=openid, 则需要同步上报openid

Y