数据采集JS-SDK

新手入门

什么是数据采集JS-SDK

• JS数据采集SDK是为开发者提供的，用来统一并采集服务数据的前端集成工具，实现服务数据联运

数据采集JS-SDK能做什么

• SDK可以完成常用的页面用户行为及元素的数据采集，完成数据加密上报至鼎道大数据平台
• 可以支持服务快速接入

数据应用

• 服务分析、用户分群、用户细查、转化分析、 服务推荐

产品使用指南

基础功能

只需引入SDK并初始化即可。引入方式参见下章前端快速接入中“初始化SDK”相关描述 如果只初始化SDK，则可以自动采集：应用打开、应用关闭、路由切换、进入可视区、离开可视区、浏览器滚动

拓展功能

如有产品个性化需求请使用拓展功能。引入方式参见下章前端快速接入中“拓展功能”相关描述

前端快速接入

npm安装

npm install @dingdaoos/dingcloud-sdk

项目示例

引入SDK

main.ts引用（区分vue2、vue3、react）

import DC_SDK from '@dingdaoos/dingcloud-sdk/dist/vue2'
import DC_SDK from '@dingdaoos/dingcloud-sdk/dist/vue3'
import DC_SDK from '@dingdaoos/dingcloud-sdk/dist/react'

初始化SDK

DC_SDK.track.init({
  AppKey: 'AppKey', // 应用key
  Process: 'cdt', // 环境区分
  UrlKeys: ['key1','key2','key3','key4','key5'], // 地址栏参数，数据上报会在Url中取值
  Debug: true, // 开启debug模式
  Scroll: true // 开启浏览器滚动监听
})

// vue应用挂在全局组件，方便使用，  react直接使用组件即可，无需全局注册

// vue2
Vue.component('Track', DC_SDK.TrackDomVue2) 

// vue3
const app = createApp(AppView) 
app.component('Track', DC_SDK.TrackDomVue3)

init参数说明

| key | 描述 | 是否必传 | 类型 | value | | :---: | :---: | :---: | :---: | :---: | | AppKey | 应用唯一key | 是 | String | - | | Process | 环境区分 | 是 | String | cdt测试环境cdp生产环境 | | Scroll | 开启浏览器滚动监听 | 否 | Boolean | 默认 false | | UrlKeys | 地址栏参数，最多5个 | 否 | Array | 默认 [] | | Debug | debug模式 | 否 | Boolean | 默认 false | | [props: string] | 其他自定义字段 | 否 | Any | - |

init传入的其他字段会作为全局参数，在上报数据时默认添加

post上报

post手动上报，要求传入数据的格式为json字符串或者object，转换方法：JSON.stringify(object)若传入格式有误，数据将无法正确采集，并会在控制台发出错误提示

DC_SDK.track.post({
   Event：'click',
   // ...其他字段
})
或者
DC_SDK.track.post(JSON.stringify({
   Event：'click',
   // ...其他字段
}))

post参数说明

| key | 描述 | 是否必传 | 类型 | value | | :---: | :---: | :---: | :---: | :---: | | Event | 上报事件 | 是 | String | elementExposure (元素曝光)click（单击）dbclick（双击）hover（鼠标悬浮）leave（鼠标离开）onerror（服务/页面加载失败/错误）copy（内容元素复制）cut（内容元素剪贴）onselect（选中页面内容）keyboard（键盘输入）drag(拖拽）以下5个事件SDK会自动监听，无需开发者主动上报closeWeb(关闭应用)pageView(路由切换) isOnload = false pageView(打开应用) isOnload = truevisibilityChange(进入/离开可视区)scroll(浏览器滚动) 根据init参数判断是否监听 | Object | 对象（触点） | 是 | String | 对象的属性示例：button(按钮)link(链接)page（页面）operation(运营位) ...自定义 | | ObjectName | 对象名称 | 否 | String | - | | Content | 自定义内容 | 否 | String | - | | UserIdForBusiness | 用户标识 | 否 | String | - | | Source | 来源 | 否 | String | - | | ServiceId | 服务的ID该值如果在init时传，后续所有post都会带有该值，如果init不传，则post必须要传 | 否 | String | - | | ServiceVersion | 服务版本号 | 否 | String | - | | CurrentUrl | 当前url | 否 | String | - | | FromUrl | 前一个访问的url | 否 | String | - | | Title | 标题 | 否 | String | - | | ResTemp | 预留字段 | 否 | JSON格式字符串 | - | | Measure | 服务计量 | 否 | JSON格式字符串 | - |

updata更新

DC_SDK.track.updata({
   ...更新参数
   CookieId: true
})
// 更新参数updata 参数支持JSON，可更新init初始化时传入的其他参数或者新增全局参数

/*
  更新的字段中，CookieId较为特殊，它不会以传入的值覆盖原有值
  调用updata方法传入CookieId字段会重新生成一个随机id作为更新后的CookieId，不想更新则不传
  更新CookieId场景：根据对应产品需求决定退出登录是否要更新
*/

拓展功能

SDK提供的Track组件，可以自动采集元素的点击和元素的曝光事件，注册组件方法在上章“初始化SDK”中，注册后可在全局使用，使用示例如下：

// vue示例
<div class="home-page">
  <Track :commonParams="{ publicName: '公共参数' }" :clickParams="{ content: '点击事件上报的内容' }" :exposeParams="{ content: '曝光元素上报的内容' }">
    <button>提交按钮</button>
  </Track>
</div>

// react示例
import Track from '@dingdaoos/dingcloud-sdk/dist/react'

<div class="home-page">
  <Track.TrackDomReact :commonParams="{ publicName: '公共参数' }" :clickParams="{ content: '点击事件上报的内容' }" :exposeParams="{ content: '曝光元素上报的内容' }">
    <button>提交按钮</button>
  </Track.TrackDomReact>
</div>

上述示例button元素被SDK提供的Track组件包裹，当触发了点击和曝光事件，则SDK会自动上报数据

Track组件接收参数

使用该组件默认开启元素点击和曝光，如果不传任何参数则会上报init的基础字段，可根据参数关闭点击或者曝光 点击事件默认开启event.stopPropagetion,可根据参数关闭 commonParams优先级低于clickParams和exposeParams

| key | 描述 | 是否必传 | 类型 | value | | :---: | :---: | :---: | :---: | :---: | | commonParams | 点击和曝光公共参数 | 否 | Object/Function | 默认 {} | | exposeParams | 曝光参数 | 否 | Object/ Function | 默认 {} | | clickParams | 点击参数 | 否 | Object/ Function | 默认 false | | threshold | 曝光阈值(0 - 1) | 否 | Number | 默认 0.5 | | closeExpose | 关闭曝光 | 否 | Boolean | 默认 false | | closeClick | 关闭点击 | 否 | Boolean | 默认 false | | closeClickStop | 关闭事件冒泡 | 否 | Boolean | 默认 false |

commonParams、exposeParams、clickParams支持传入function，示例如下

<div class="home-page">  
  <Track 
    :commonParams="getCommonParams" 
    :clickParams="getClickParams"
    :exposeParams="getExposeParams"
    > 
  <button>提交按钮</button> 
   </Track>
</div>

<script>

function getCommonParams(){ 
  return { publicName: '公共参数' } 
} 

function getExposeParams(){ 
  return { content: '曝光元素上报的内容' }
} 

function getClickParams(){ 
  return { content: '点击事件上报的内容' }
 } 

<script>

提示：传入的函数不要执行，仅传入参数名即可

组件样式

<Track 
  class="track" 
  style="display: block;width:100px;height:100px;"
 >

 <button></button>
</Track>

<style>
.track{
  display: block;
  width:100px;
  height:100px;
}

</style>

默认的样式为display:inline，根据业务场景可修改样式 修改样式方法：定义class或者直接行内修改

SDK使用问题

Q：什么情况使用定制化埋点？

A：当元素需要收集点击或者曝光事件。

Q：使用定制化埋点时，如何关闭点击事件或者曝光事件？

A：给组件传入closeClick=true或者closeExpose=true。

Q：使用定制化埋点点击事件时，如何开启事件冒泡？

A：给组件传入closeClickStop=true。

Q：定制化埋点传入自定义参数为函数时执行多次？

A：由于Vue2编译导致的问题

exposeParams="fn()" 改成 exposeParams="fn" 
exposeParams="fn(param)" 改成 exposeParams="fn.bind(this, param)" 

function fn(param){
return {
  id: param.id
  name: param.name
 }
}