# 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,非必须, 要设置给自定义事件的属性;

提示

  • 手动埋点的功能通过 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 中
  },
])