# H5 SDK
集成凡泰数据分析 SDK
# 引入 SDK
- 通过 npm i @finogeeks/fc-track 安装 SDK
- 在项目中通过 import 引入 SDK
import fctrack from "@finogeeks/fc-track/web/fc-track-web-sdk";
注意
- H5 数据上报 SDK 文件 fctrack-web-sdk.js 大小约为 24 KB
配置初始化参数
# setPara 参数配置
提示
- setPara 配置接口,用来调整 SDK 的基础配置。
- 首次调用初始化 SDK,再次调用覆盖之前传入的配置,可多次调用。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
server_url | string | Y | 您的数据接收地址 |
appid | string | N | 如果网页嵌套在小程序或者公众号开发,请传小程序或者公众号 APPID |
app_name | string | N | 如果网页嵌套在小程序或者公众号开发,请传小程序或者公众号名称 |
app_version | string | N | 如果网页嵌套在小程序或者公众号开发,请传小程序或者公众号名称版本号 |
autoTrack | object | N | 全埋点控制开关,默认是:全部开启 |
show_log | bool | N | 是否打印日志,默认是:true |
batch_send | bool | N | 是否把收集好的数据发送请求到服务端,默认是:true |
actionEventData | array | N | 点击事件配置表,详情请前往 点击事件配置表 指引 |
interval_timeout | number | N | 发送数据时间间隔,默认是:300000 5 分钟 单位毫秒 |
代码示例
fctrack.setPara({
appid: "如果网页嵌套在小程序或者公众号开发,请传小程序或者公众号 APPID",
app_name: "如果网页嵌套在小程序或者公众号开发,请传小程序或者公众号名称",
app_version: "打开H5页面的小程序版本",
server_url: `您的数据接收地址`,
// 全埋点控制开关-合法值 默认行为全都是true
autoTrack: {
appLaunch: true, // 默认为 true,false 则关闭 appLaunch 事件采集
appShow: true, // 默认为 true,false 则关闭页面 visibilityState 变化的事件采集
appHide: true, // 默认为 true,false 则关闭页面 visibilityState 变化的事件采集
pageLoad: true, // 默认为 true,false 则关闭进入页面的事件采集
pageHide: true, // 默认为 true,false 则关闭离开页面的事件采集
pageAction: true, // 默认为 true,false 则关闭 pageAction 事件采集
custom: true, // 默认为 true,false 则关闭自定义事件的采集
},
});
# initTrack 参数配置
// 开始数据的收集和上报
fcTrack.initTrack();
注意
- 注意:initTrack() 方法必须调用,否则不会发数据。
快速使用
# 点击事件初始化
// 调用setPara方法时候 actionEventData 参数说明
// path 为页面的路由
// methodTracks 是每个页面具体的点击事件声明
export const actionEventData = [
{
path: 'prodtest',
events: [
{
eventName: 'handleClick', // 声明需要监听的方法(手动填写)
eventTitle: '点击事件', // 方法事件中文名称
selector: '', // 唯一匹配的 selector
dataKeys: ['content'], // 声明需要获取Data下的哪些数据.
/*
dataKeys 参数
1. $APP.retailId 全局,
2. $QUERY.retailId url参数.
3. 普通的 data-fctrack-xxx 还需要添加设置全局变量的$APP方法
*/
},
],
},
];
/*
在页面中,如果需要上报某个元素的点击行为,
需要在 actionEventData 填写页面的配置,
并在需要上报的元素的位置添加 data-xxx 的声明
*/
// data-xxxx , xxxx 的内容和 methodTracks => dataKeys 的数据对应
<div class="app-test">
这是一个:产品详情页面
<button data-fctrack-content="打开购买页面" @click="openAPP">打开购买页面</button>
</div>
# 确认数据发送成功
- 集成 SDK 初始化代码,控制台 console 会打印采集的数据,json 格式;
{ "source_info": { // 日志上报者信息
"sourcer": "上报者名称"(根据此项来决定kafka topic)
"source_version": "上报者版本"
}
"app_info": { // 应用信息
"app_id": "客户id",
"app_version": "客户app版本",
"sdk_version": "sdk版本",
"sdk_type": "sdk类型",
"app_key_id": "渠道id"
},
"device_info": { // 设备信息
"device_id": "android使用aid,iphone使用key chaine id",
"imei": "设备imei号",
"mac": "设备mac号",
"os": "Android、ios或者windows",
"os_version": "os版本号",
"screen_size": "屏幕大小,比如1280-980",
"brand": "厂商名字,比如Apple",
"model": "机型名字,比如Iphone 7"
},
"network_info": { // 网络连接信息
"ns": "网络连接状态,wifi、4G等",
"ip": "ip地址",
"cr": "运营商",
"ua": "user_agent"
},
"user_info": { // 用户信息
"user_id": "用户ID"
"position": "岗位"
"params": {} //扩展用户信息
},
"events": [ // 页面事件、点击事件等
{
"event_id": "随机生成的事件ID",
"event_type": "事件类型",
"event_name": "事件名称",
"timestamp": // 时间戳,比如124234,
"referrer": "前页",
"params": {}
}
]
}
常用 API
# 初始化相关 API
setPara( args )
说明:用来配置初始化参数;
参数:args : object , 初始化参数对象,可配置的属性如下
args key | 类型 | 说明 |
---|---|---|
name | string | 无 |
appid | string | 小程序 appid |
app_name | string | '小程序名称' |
app_version | string | '小程序版本号', |
app_key_id | string | '渠道平台' // 例如微信 WeChat |
server_url | string | 数据接收地址。 |
show_log | boolean | 设置 true 后会在模拟器控制台打 logger,会显示发送的数据,设置 false 表示不显示。默认为 true |
batch_send | boolean / object | 见详细说明 |
interval_timeout | number | 发送请求循环事件时间间距 默认 5 分钟 |
# initTrack()
- 说明:用来标识小程序 SDK 初始化完成,数据可以通过网络发送;此方法不调用,采集的数据会被缓存在内存中,不能通过网络发送,;
# setUserInfo(args)
说明:设置用户信息,必填项在 SDK 初始化后调用此方法,非必填项一般在用户登录成功后,调用此方法把用户信息传入进来
参数:
args key | 含义 | 类型 | 说明 |
---|---|---|---|
user_id | 用户 fcid | string | 非必填 |
name | 名字 | string | 非必填 |
avatar | 头像 | string | 非必填 |
gender | 性别 | number | 微信数据 0 未知,1 男性,2 女性(非必填) |
country | 国家 | string | 微信信息 非必填 |
province | 省份 | string | 非必填 |
city | 城市 | string | 非必填 |
tid | domain | string | 必填,saas 机构和私有化部署截取用户 fcid 冒号后面的 domain 部分 |
app_type | 用户类型 | string | 必填,STAFF 代表员工。RETAIL 代表客户 |
注意
- gender 为数字类型, 其他为字符串类型
# setDeviceid(id)
- 设置设备 id 的接口 (用于唯一标识)
- 参数: 字符串 id
# setNetworkInfo(networkInfo)
- 说明:设置上报信息中的用户网络信息
- 参数: Object networkInfo
// 调用quick函数, 第一个参数为 'custom' 时, 第二个参数为指定的自定义事件名称, 第三个参数为对象
// 例如
const networkInfo = { // 网络连接信息
"ns": "网络连接状态,wifi、4G等",
"ip": "ip地址",
"cr": "运营商",
"ua": "user_agent"
}
fctrack.setNetworkInfo(networkInfo);
# setDeviceInfo(deviceInfo)
- 说明:设置上报信息中的用户设备信息
- 参数: Object deviceInfo
// 调用quick函数, 第一个参数为 'custom' 时, 第二个参数为指定的自定义事件名称, 第三个参数为对象
// 例如
fctrack.setDeviceInfo({ // 设备信息
"device_id": "android使用aid,iphone使用key chaine id",
"imei": "设备imei号",
"mac": "设备mac号",
"os": "Android、ios或者windows",
"os_version": "os版本号",
"screen_size": "屏幕大小,比如1280*980",
"brand": "厂商名字,比如Apple",
"model": "机型名字,比如Iphone 7"
})
# setOpenid(id)
- 说明:设置微信平台返回的 openId,方便用于标示用户
- 参数: 字符串 id
# immedRequest()
- 调用此 API 可以立即发送收集好的数据请求
# 自定义事件
# quick( ['appLaunch'|'pageShow|'custom'], [options], [properties]);
- 说明:通过给定的第一个参数,来分别实现不同的功能;
- 参数:
- appLaunch:string, 用来发送一条预置事件 enter_app 数据,项目初始化式调用;
- 第二个参数 options,必须, 需要传入返回的生命周期函数参数对象;
- 第三个参数 properties,非必须,可以传入要设置给预置事件 enter_app 事件的自定义属性;
- pageLoad:string, 用来发送一条预置事件 enter_page 数据,进入页面时调用;
- 第二个参数 options,必须, 需要传入返回的生命周期函数参数对象;
- 第三个参数 properties,非必须,要设置给预置事件 enter_page 事件的自定义属性
- custom:string, 用来发送一条自定义事件数据
- 第二个参数 options,非必须, 要设置给自定义事件的属性;
- appLaunch:string, 用来发送一条预置事件 enter_app 数据,项目初始化式调用;
提示
- 手动埋点的功能通过 quick 函数实现
// 调用quick函数, 第一个参数为 'custom' 时, 第二个参数为指定的自定义事件名称, 第三个参数为对象
// 例如
import fctrack from '@finogeeks/fc-track/web/fc-track-web-sdk';
fctrack.quick('custom', 'unlock', {
resources_id: 'test_1234',
success: true,
event_name_chinese: '立即解锁',
msg: ''
})
# setGlobalParams()
// 设置上报的全局数据
// type 的取值为 global appLaunch pageShow custom
// 使用示例
import fctrack from '@finogeeks/fc-track/web/fc-track-web-sdk';
fctrack.setGlobalParams([
{
value: 'vlaue1',
key: 'aid',
type: 'global', // 当 type 为 global, key 和 value 会作为一个字段, 添加到所有上报事件的 params 中
},
{
value: 'vlaue1',
key: 'aid',
type: 'global' // 当 type 为自定义事件类型, key 和 value 会作为一个字段, 添加到对应自定义上报事件的 params 中
},
])
← 3.1 微信小程序SDK 3.3 数据上报 →