QQ小程序通用框架版
QQ小程序通用框架版
QQ小程序 SDK 集成前请先下载SDK
SDK Releases包下载: Github地址(推荐):https://github.com/analysys/ans-QQ-sdk/releases Gitee地址:https://gitee.com/Analysys/ans-qq-sdk/releases Releases中含有更新说明请您阅读,接口使用请参考本文档。
js文件
功能描述
是否必须
AnalysysAgent_QQ_SDK.custom.min.js
框架版SDK
二选一
AnalysysAgent_QQ_SDK.custom.es6.min.js
框架版ES6语法SDK
二选一
AnalysysAgent_encryption.min.js
加密模块
非必须
AnalysysAgent_encryption.es6.min.js
加密模块ES6语法配合框架ES6版本使用
非必须

快速集成

如果您是第一次使用易观方舟产品,可以通过阅读本文快速了解此产品
1. 集成 SDK
在app.js文件的顶部引入SDK。
2. 设置初始化接口
通过初始化代码的配置参数配置您的AppKey。
3. 设置上传地址
通过初始化代码的配置参数uploadURL设置您上传数据的地址。
4. 配置上传地址域名
登录微信公众平台,将上传地址域名配置到request 合法域名中。
5. 设置需要采集的页面或事件
通过手动埋点,设置需要采集的页面或事件。
6. 打开 Debug 模式查看日志
通过设置Ddebug模式,开/关 log 查看日志。

7.调用小程序启动事件

在app.js文件中调用小程序启动事件
1
import AnalysysAgent from './util/sdk/AnalysysAgent_QQ_SDK.custom.es6.min.js'
2
AnalysysAgent.appkey = "/*设置为实际APPKEY*/" //APPKEY
3
AnalysysAgent.uploadURL = "/*设置为实际地址*/"
4
5
App({
6
onShow (options) {
7
AnalysysAgent.appStart(options);
8
}
9
})
10
Copied!

8.调用小程序页面事件

在每一个页面的入口js文件中调用小程序统计页面事件
1
let AnalysysAgent = my.AnalysysAgent
2
Page({
3
onShow () {
4
AnalysysAgent.pageView('首页');//页面名称可自定义。
5
}
6
})
Copied!
通过以上步骤您即可验证SDK是否已经集成成功。更多接口说明请您查看API文档。

集成配置

集成 SDK

代码引入 将 AnalysysAgent_QQ_SDK.custom.min.js或AnalysysAgent_QQ_SDK.custom.es6.min.js 文件放到小程序的目录下
在小程序的 app.js 文件中的第一行加入以下代码:
1
let AnalysysAgent = require("./build/AnalysysAgent_QQ_SDK.custom.min.js")
2
AnalysysAgent.appkey = "/*设置为实际APPKEY*/" //APPKEY
3
App({
4
onShow : function( options ){
5
//设置微信小程序启动事件,并传输UTM等参数
6
AnalysysAgent.appStart(options)
7
}
8
});
Copied!
如需要加密模块
1
let AnalysysEncryption = require("./build/AnalysysAgent_encryption.min.js")
2
AnalysysAgent.encrypt = AnalysysEncryption
Copied!
对于使用 es6 版本的
1
import AnalysysAgent from './build/AnalysysAgent_QQ_SDK.custom.es6.min.js';
2
import AnalysysEncryption from './build/AnalysysAgent_encryption.es6.min.js';
3
AnalysysAgent.encrypt = AnalysysEncryption;
4
5
//es6版本不是每个框架都能用,不能使用es6的请如下 使用
6
import AnalysysAgent from "./build/AnalysysAgent_QQ_SDK.custom.min.js"
7
AnalysysAgent.appkey = "/*设置为实际APPKEY*/" //APPKEY
Copied!
在各个 Page 内通过以下代码获取 AnalysysAgent_QQ_SDK 全局函数:
1
let AnalysysAgent = qq.AnalysysAgent;
2
Page({
3
onShow : function( options ){
4
//设置微信小程序启动事件
5
AnalysysAgent.pageView('首页')
6
}
7
})
Copied!
在组件Component 内通过以下代码获取 AnalysysAgent_QQ_SDK 全局函数:
1
let AnalysysAgent = qq.AnalysysAgent;
Copied!
注意:
1.将 appkey 的值填入您具体的项目 appkey
2.目录为您所引入QQ小程序 SDK 的具体目录

配置参数

  • appkey(必须) 在网站获取的 AppKey
  • debugMode 设置调试模式:0 - 关闭调试模式(默认);1 - 开启调试模式,数据不入库;2 - 开启调试模式,数据入库
  • uploadURL(必须) 自定义上传地址
  • autoProfile 设置是否追踪新用户的首次属性:false - 不追踪新用户的首次属性;true - 追踪新用户的首次属性(默认)
  • encryptType 设置是否对上传数据加密:0 - 对上传数据不加密(默认);1 - 对上传数据进行AES 128位ECB加密;2 对上传数据进行AES 128位CBC加密
  • allowTimeCheck 设置是否开启时间校准:false(默认) - 关闭时间校准;true - 开启时间校准
  • maxDiffTimeInterval 设置最大时间校准分为:30s(默认) ,当设置的时间差值小于他,将不开启校准。否则将会进行时间校准。假如设置成为负值,将默认为 30s。
appkey
appkey 在网站获取的 AppKey。
  • value 在网站获取的 AppKey。类型:String。取值长度 1 - 255字符。
1
// 设置key,77a52s552c892bn442v721为样例数据,请根据实际情况替换相应内容
2
AnalysysAgent.appkey = "77a52s552c892bn442v721"
Copied!
debugMode
debugMode 调试模式为接入 QQ SDK 后进行数据调试的主要手段。可实时验证 QQ SDK 数据监测的正确与否。
  • 0 关闭调试模式(默认)。类型:Number。
  • 1 开启调试模式,数据不入库。类型:Number。
  • 2 开启调试模式,数据入库。类型:Number。
1
//开启调试模式且数据不入库
2
AnalysysAgent.debugMode = 1
3
//开启调试模式且数据入库
4
AnalysysAgent.debugMode = 2
5
//关闭调试模式
6
AnalysysAgent.debugMode = 0
7
//或删除该段代码
Copied!
或删除 debugMode 参数。
uploadURL
uploadURL 为自定义上传地址,参数设置后,所有事件信息将上传到该地址。
  • value 类型:String。数据上传地址,格式为 scheme://host + :port(不包含/后的内容)。scheme 必须以 http:// 或 https:// 开头,host 只支持域名和 IP,取值长度 1 - 255字符,port 端口号必须携带
1
//设置自定义上传地址为 scheme://host + :port
2
AnalysysAgent.uploadURL = "/*设置为实际地址*/"
Copied!
autoProfile
autoProfile 为设置是否追踪新用户的首次属性。可根据自身需要进行更改。
  • true 追踪新用户的首次属性(默认)。类型:Boolean。
  • false 不追踪新用户的首次属性。类型:Boolean。
1
//不追踪新用户的首次属性,新用户首次打开网站不上传新用户的首次属性。
2
AnalysysAgent.autoProfile = false
3
//追踪新用户的首次属性,新用户首次打开网站上传新用户的首次属性。
4
AnalysysAgent.autoProfile = true//或删除该行代码。
Copied!
encryptType
encryptType 为设置数据上传时的加密方式,目前只支持 AES 加密,如不设置此参数,数据上传不加密。。可根据自身需要进行更改。
  • 0 对上传数据不加密(默认)。类型:Number。
  • 1 对上传数据 AES 加密。类型:Number。
1
//对上传数据不加密。
2
AnalysysAgent.encryptType = 0//或删除该行代码。
3
//对上传数据AES加密。
4
AnalysysAgent.encryptType = 1
Copied!
allowTimeCheck
allowTimeCheck 为设置是否开启时间校准,开启时间校准在debug 1或者 2 的情况下会有相关提示。
  • false 关闭时间校准(默认)。类型:Boolean。
  • true 开启时间校准。类型:Boolean。
1
//关闭时间校准。
2
AnalysysAgent.allowTimeCheck = false//或删除该行代码。
3
//开启时间校准。
4
AnalysysAgent.allowTimeCheck = true
Copied!
maxDiffTimeInterval
maxDiffTimeInterval 为设置不校准时间的最大时间差值。当客户端时间和服务端时间相差在此区间内,将不进行时间校准,否则将进行时间校准。
  • value:类型 Number 。默认值 30。单位:秒。
1
//设置最大允许时间
2
AnalysysAgent.maxDiffTimeInterval = 20
3
//当服务端和客户端的时间差超过 20s 将进行时间校准
Copied!

域名配置

登录微信公众平台,设置>开发设置>服务器域名>request 合法域名,加入您所配置的 https 域名:https://xxx.xxx.xxx
QQ小程序只容许https默认端口(443)进行数据访问,请注意方舟上报端口为默认端口。否则数据将无法上报。

基础模块介绍

启动事件接口

启动事件 appStart(options),框架版本SDK启动事件需要手动调用,而且只能调用一次。
1
AnalysysAgent.appStart(options);
Copied!
  • options:options为小程序 onShow(options)获取到的参数,包括query、url等,不同框架,不同方式获取,请开发者根据使用的框架获取。
示例:
1
///taro框架示例:
2
componentDidShow () {
3
const params = this.$router.params
4
AnalysysAgent.appStart(params);
5
}
6
//mpvue框架示例:
7
onShow (options) {
8
AnalysysAgent.appStart(options);
9
}
10
Copied!

统计页面接口

页面跟踪,SDK 默认设置跟踪所有页面,支持自定义页面信息。接口如下:
1
AnalysysAgent.pageView(pageName);
2
AnalysysAgent.pageView(pageName, properties);
Copied!
  • pageName:页面标识,为字符串,取值长度 1 - 255字符
  • properties:页面信息,为K-V键值对,最多包含 100条,且key是以字母开头的字符串,必须由 字母、数字、下划线组成,字母不区分大小写,不支持 乱码、中文、空格等,长度范围1-99字符;value支持类型:String/Number/Boolean/JSON/内部元素为String的Array,若为字符串,长度范围1-255字符。
示例:
1
// 正在开展某个活动,需要统计活动页面;
2
AnalysysAgent.pageView("活动页");
3
4
......
5
6
// 访问手机活动页面,活动页面内容为优惠出售iPhone手机,手机价格为5000元
7
var properties ={
8
"commodityName": "iPhone",
9
"commodityPrice": 8000
10
}
11
12
AnalysysAgent.pageView("商品页", properties);
Copied!

统计事件接口

用户行为追踪,可以设置自定义属性。接口如下:
1
AnalysysAgent.track(eventName, eventInfo)
Copied!
  • eventName:自定义事件ID标识,以字母开头的字符串,必须由字母、数字、下划线组成,$ 开头为预置事件/属性,不支持乱码、中文、空格等,长度范围1-99字符。
  • eventInfo:自定义属性,K-V键值对,用于对事件的描述。最多包含100条,且key是以字母开头的字符串,必须由 字母、数字、下划线组成,字母不区分大小写,不支持 乱码、中文、空格等,长度范围1-99字符;value支持类型:String/Number/Boolean/JSON/内部元素为String的Array,若为字符串,长度范围1-255字符。
示例:
1
// 添加事件
2
AnalysysAgent.track("back");
3
4
......
5
6
// 用户购买手机
7
var eventInfo = {
8
"type":"Phone",
9
"name":"Apple iPhone8",
10
"money":4000,
11
"count":1
12
}
13
AnalysysAgent.track("buy", eventInfo);
Copied!

注册页面事件通用属性

注册应用中所有页面通用属性,设置后当次小程序启动后所有页面都拥有该属性,直至该小程序关闭。接口如下:
1
AnalysysAgent.appProperty(properties)
Copied!
  • properties:页面信息,K-V键值对,最多包含100条,且key是以字母开头的字符串,必须由 字母、数字、下划线组成,字母不区分大小写,不支持 乱码、中文、空格等,长度范围1-99字符;value支持类型:String/Number/Boolean/JSON/内部元素为String的Array,若为字符串,长度范围1-255字符。
示例:
1
// 设置被分享页面所属分享群ID
2
var properties ={
3
openGId:'123456789'
4
}
5
6
AnalysysAgent.appProperty(properties);
Copied!

采集分享按钮点击事件

采集分享按钮点击事件,只采集分享按钮的点击事件,不区分分享是否成功。方法返回对象(toShareProperties)。接口如下:
1
AnalysysAgent.share(toShareProperties,trackProperties);
Copied!
  • toShareProperties(可选),分享属性,包括自定义title等,不写将全部用默认。
  • trackProperties(可选),分享事件自定义属性。K-V键值对,最多包含 100条,且key是以字母开头的字符串,必须由 字母、数字、下划线组成,字母不区分大小写,不支持 乱码、中文、空格等,长度范围1-99字符;value支持类型:String/Number/Boolean/JSON/内部元素为String的Array,若为字符串,长度范围1-255字符。
示例:
1
Page({
2
onShareAppMessage:function(){
3
let toShareProperties = {
4
title: '自定义转发标题',
5
path: '/page/user?id=123'
6
}
7
let trackProperties = {
8
custom:'weChat'
9
}
10
return AnalysysAgent.share(toShareProperties,trackProperties);
11
}
12
})
Copied!

匿名ID与用户关联

用户 id 关联接口。将需要绑定的用户ID 和匿名ID进行关联,计算时会认为是一个用户的行为。接口如下:
1
AnalysysAgent.alias(aliasId);
Copied!
  • aliasId:需要关联的用户ID。 取值长度 1 - 255字符,支持类型:String
示例:
1
// 登陆账号时调用,只设置当前登陆账号即可和之前行为打通
2
AnalysysAgent.alias("sanbo");
Copied!

匿名ID设置

唯一匿名ID标识设置,接口如下:
1
AnalysysAgent.identify(xwho);
Copied!
  • distinctId:唯一身份标识,取值长度 1 - 255字符,支持类型:String
示例:
1
// 设置匿名ID为`fangke009901`,注意此方法需要在初始化之后优先调用
2
AnalysysAgent.identify("fangke009901");
Copied!

匿名ID获取

获取用户通过identify接口设置或自动生成的id,优先级如下: 用户设置的id > 代码自动生成的id
接口如下:
1
AnalysysAgent.getDistinctId();
Copied!
示例:
1
// 获取匿名id
2
var distinctId = AnalysysAgent.getDistinctId();
Copied!

用户属性设置

用户属性是一个标准的 K-V 结构,K 和 V 均有相应的约束条件,如不符合则丢弃该次操作。
约束条件如下:
属性名称
1
以字母开头的字符串,必须由字母、数字、下划线组成,字母不区分大小写,$ 开头为预置事件/属性,不支持乱码、中文、空格等,长度范围1-99字符。
Copied!
属性值
1
支持部分类型:String/Number/Boolean/内部元素为String的Array;若为字符串,则取值长度 1 - 255字符;若为 Array 或 JSON,则最多包含 100条,且 key 约束条件与属性名称一致,value 取值长度 1 - 255字符
Copied!

设置用户固有属性

设置用户的固有属性,只在首次设置时有效的属性。 如:应用的激活时间、首次登录时间等。如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。接口如下:
1
AnalysysAgent.profileSetOnce(propertyName, propertyValue);
2
3
AnalysysAgent.profileSetOnce(property);
Copied!
  • propertyName :属性名称,约束见属性名称
  • propertyValue :属性值,约束见属性值
  • property : 属性列表,约束见属性名称,属性值
示例:
1
// 设置用户激活时间
2
AnalysysAgent.profileSetOnce("activationTime", "2018-06-18 18:18:18.188");
3
4
// 设置用户性别和出生时间
5
var setOnceProfile = {
6
"birth": "2018-06-18 18:18:18.188",
7
"sex": "male"
8
}
9
AnalysysAgent.profileSetOnce(setOnceProfile);
Copied!

设置用户属性

给用户设置单个或多个属性,如果之前不存在,则新建,否则覆盖。接口如下:
1
//设置单个用户属性
2
AnalysysAgent.profileSet(propertyName, propertyValue);
3
//设置多个用户属性
4
AnalysysAgent.profileSet(property);
Copied!
  • propertyName :属性名称,约束见属性名称
  • propertyValue :属性值,约束见属性值
  • property :属性列表,约束见属性名称,属性值
示例:
1
//设置用户的邮箱地址为[email protected]
2
AnalysysAgent.profileSet("Email", "[email protected]");
3
4
......
5
6
// 设置用户的邮箱和微信
7
var property = {
8
"Email" : "[email protected]",
9
"WeChatID" : "weixinhao"
10
}
11
AnalysysAgent.profileSet(property);
Copied!

设置用户属性相对变化值

设置用户属性的相对变化值(相对增加,减少),只能对数值型属性进行操作,如果这个 Profile之前不存在,则初始值为0。接口如下:
1
AnalysysAgent.profileIncrement(propertyName, propertyNumber)
2
3
AnalysysAgent.profileIncrement(property);
Copied!
  • propertyName:属性名称,约束见属性名称
  • propertyValue:属性值,约束见属性值
  • property:属性列表,约束见属性名称,属性值
示例:
1
//用户增加一岁
2
AnalysysAgent.profileIncrement("age",1);
3
4
......
5
6
//用户玩某个游戏时间增加一年,游戏等级增加2
7
var incrementProfile = {
8
"gameAge":1,
9
"gameRating":2
10
}
11
AnalysysAgent.profileIncrement(incrementProfile);
Copied!

增加列表类型的属性

用户列表属性增加元素。接口如下:
1
//增加单个属性
2
AnalysysAgent.profileAppend(propertyName, propertyValue);
3
//增加多个属性
4
AnalysysAgent.profileAppend(propertyValue);
5
//增加多个属性
6
AnalysysAgent.profileAppend(propertyName, propertyValue);
Copied!
  • propertyName:属性名称,约束见属性名称
  • propertyValue:属性值,约束见属性值
示例:
1
// 增加用户爱好 music
2
AnalysysAgent.profileAppend("hobby", "Music");
3
4
// 增加多个用户属性
5
var map = {
6
"hobby": "PlayBasketball",
7
"sports": "Run"
8
};
9
AnalysysAgent.profileAppend(mContext, map);
10
11
//增加多个用户爱好
12
var list = ["PlayBasketball", "music"];
13
AnalysysAgent.profileAppend("hobby", list);
Copied!

删除设置的属性值

删除已设置的用户属性值。接口如下:
1
AnalysysAgent.profileUnset(propertyName);
2
AnalysysAgent.profileDelete();
Copied!
  • propertyName:属性名称,约束见属性名称
示例:
1
// 删除当前用户单个属性值
2
AnalysysAgent.profileUnset( "age");
3
4
// 删除当前用户所有属性值
5
AnalysysAgent.profileDelete();
Copied!

通用属性

通用属性是每次上传事件信息都会带有的属性,通用属性是一个标准的 K-V 结构,K 和 V 均有相应的约束条件,如不符合则丢弃该次操作。
约束条件如下:
属性名称
1
以字母开头的字符串,必须由字母、数字、下划线组成,字母不区分大小写,$ 开头为预置事件/属性,不支持乱码、中文、空格等,长度范围1-99字符。
Copied!
属性值
1
支持部分类型:String/Number/Boolean/内部元素为String的Array;若为字符串,则取值长度 1 - 255字符;若为 Array 或 JSON,则最多包含 100条,且 key 约束条件与属性名称一致,value 取值长度 1 - 255字符
Copied!

注册通用属性

某一个体,在固定范围内,持续拥有的属性,每次数据上传都会携带。接口如下:
1
AnalysysAgent.registerSuperProperty(superPropertyName , superPropertyValue );
2
3
AnalysysAgent.registerSuperProperties(superProperty);
Copied!
  • superPropertyName:属性名称,约束见属性名称
  • superPropertyValue:属性值,约束见属性值
  • superProperty:属性列表,约束见属性名称,属性值
示例:
1
// 在某视频平台,购买一年会员,该年内只需设置一次即可
2
AnalysysAgent.registerSuperProperty("member","VIP");
3
4
......
5
6
// 小明在20岁的时候,购买了一年腾讯会员
7
var property = {
8
"platform":"TX",
9
"age":"20",
10
"member":"VIP",
11
"user":"xiaoming"
12
}
13
AnalysysAgent.registerSuperProperties(property);
Copied!

删除通用属性

根据属性名称,删除已设置过的通用属性。接口如下:
1
//删除单个通用属性
2
AnalysysAgent.unRegisterSuperProperty(superPropertyName);
3
//清除所有通用属性
4
AnalysysAgent.clearSuperProperties();
Copied!
  • superPropertyName:属性名称,约束见属性名称
示例:
1
// 删除已经设置的用户年龄属性
2
AnalysysAgent.unRegisterSuperProperty("age");
3
4
......
5
6
// 清除所有已经设置的通用属性
7
AnalysysAgent.clearSuperProperties();
Copied!

获取通用属性

查询获取通用属性。接口如下:
1
// 获取单个通用属性
2
AnalysysAgent.getSuperProperty(superPropertyName);
3
// 获取所有的通用属性
4
AnalysysAgent.getSuperProperties();
Copied!
  • superPropertyName:属性名称,约束见属性名称
示例:
1
// 查看已经设置的"member"的通用属性
2
AnalysysAgent.getSuperProperty("member");
3
4
......
5
6
// 查看所有已经设置的通用属性
7
AnalysysAgent.getSuperProperties();
Copied!

获取预置属性

获取预置属性。接口如下:
1
AnalysysAgent.getPresetProperties();
Copied!
示例:获取预置属性
1
// 获取预置属性
2
var presetProperties = AnalysysAgent.getPresetProperties();
3
4
console.log('预置属性:', presetProperties)
Copied!

清除本地设置

清除本地现有的设置(包括 id 和通用属性)重新开始统计。接口如下:
1
AnalysysAgent.reset();
Copied!
示例:清除本地现有的设置,包括id和通用属性
1
// 删除设置的id和通用属性
2
AnalysysAgent.reset();
Copied!
最近更新 6mo ago