钉钉小程序SDK使用说明
1.获取和引入钉钉小程序SDK
1.1 下载SDK
在CDN上下载 钉钉小程序SDK 钉钉小程序SDK为最新版本。具体每个版本特性请参照版本更新日志。
将下载的sdk文件放在小程序目录的utils下，然后再 app.js 第一行添加以下代码：
const atlas = require('./utils/ca-dingding.min.js')
atlas.init(options) // options 初始化参数 见1.2
1.2 init 方法 初始化参数配置
const options = {
app_key: 'dd_im',
app_ver: '1.0',
is_compress: false,
limit_time: 5, // 限制上传条数(Number, 可选，默认值为 5, 区间[1,100])
immediately: true, // 是否立即上传，可选，默认立即上传
server_url: 'https://cloud-atlas-collection.sdp.101.com', // 依据环境不同，请设置不同的域名地址，必填
channelId: 'default', // 渠道ID 默认为default （V1.2.0版本新增）
autoUpload: 20 // 自动上传时间，默认20s，最大30s
}
atlas.init(options)
- app_key: 当前钉钉小程序在云图注册应用返回的AppKey （必填, 暂时选择Web端，之后云图会开放钉钉小程序端）；
- app_ver: 当前钉钉小程序的版本 （必填）；
- is_compress 是否开启gzip压缩 (默认不开启)；
- limit_time: 限制上传条数(Number, 可选，默认值为 5， 最小为1条，最多为100条)；
- immediately: 是否立即上传，可选，默认值为是，不走localstorage存储，直接上传数据；
- server_url: 上传接口地址，必填。选择对应的云图分析数据接口地址；
- channelId: 渠道ID，可选，默认为default, 配置小程序进入的渠道 (v1.2.0版本新增)；
1.3云图分析数据接口地址
| 环境 | 云图分析数据接口 | 备注 |
|---|---|---|
| 预生产 | https://cloud-atlas-collection.beta.101.com/ | |
| 生产 | https://cloud-atlas-collection.sdp.101.com/ | -- |
| 伊拉克演练环境 | https://cloud-atlas-collection.iraq.101.com/ | -- |
注：
- 钉钉小程序正式环境接口地址必须为HTTPS，当前云图环境都已支持https，请正确设置环境地址；
- 预生产环境可用于用户开发、测试、集成、预生产等环境的对接开发测试工作，但需关闭小程序请求地址的校验；
2. 钉钉小程序SDK方法
小程序只有接入云图的login、logout接口才会用户数据。
2.1 login 登陆事件
const app = getApp()
/**
* openid 小程序登陆后获取openid String
* properties 自定义属性 Object 目前登陆自定义属性参数不生效，待之后扩展
*/
// 方式一：传入钉钉小程序返回的用户openid
app.atlas.login(openid)
// 方式二：当前公司钉钉小程序有接入101帐号中心的组织登录功能，也可传入101帐号中心返回的用户ID user_id
app.atlas.login(user_id)
在当前钉钉用户登陆成功返回openid后调用该方法，上报登陆采集事件。
2.2 logout 退出事件
var app = getApp();
/**
* properties 自定义属性 Object 目前退出自定义属性参数不生效，待扩展
*/
// app.atlas.logout(properties)
app.atlas.logout()
在当前钉钉用户退出登陆调用该方法，上报登陆退出采集事件。
2.3 event 自定义事件
var app = getApp();
/**
* eventName 事件代码
* properties 自定义属性 对象类型
*/
app.atlas.event(eventName, properties)
/**
* 例如 购买事件
* info为自定义属性的扩展属性
*/
var eventInfo = {
info: {
type:'水果',
from: '甘肃',
name: '苹果',
price: 10,
}
}
app.atlas.event('buy', eventInfo)
在需要进行自定义埋点的地方，添加以上代码，可进行自定义事件采集事件上报，默认立即上传自定义事件。 如果初始化 immediately 设置为false, 则当前事件数据存储到小程序的storage中，设置limit_time 实现每触发多少条事件数据，就统一上传。每次进入时，会获取storage中存储的事件数据，全部立即上传，防止出现数据未达到limit_time，一直存储不上传的问题
3.自动埋点
3.1 自动上报事件
| 事件名称 | 相应小程序生命周期函数 | 触发机制 | 说明 |
|---|---|---|---|
| login/device | App.onShow | 小程序启动，或从后台进入前台显示 | 启动小程序时 |
| logout | App.onHide | 点击小程序右上角退出按钮、钉钉进入后台、进入小程序关于页面、手机锁屏、小程序进程被杀死时 | 小程序从前台进入后台 |
| ca_pageview_enter/ca_pageview_leave | Page.onShow | 页面进入展示时 | 页面显示时 |
4. 设备属性
| 字段名称 | 类型 | 说明 |
|---|---|---|
| brand | String | 手机品牌 |
| create_time | String | 创建时间 |
| model | String | 手机型号 |
| screen_height | String | 分辨率高度 |
| screen_width | String | 分辨率宽度 |
| system_version | String | 系统版本 |
5.常见问题
5.1 小程序中服务器域名设置
- 小程序 server_url （数据接收地址）需要在钉钉公众平台 -> 应用开发 -> 安全中心 -> HTTP 安全域名和Webview 安全域名中配置；
- 小程序中服务器域名必须是https协议；
- 对应的数据接收地址 请查看接口表格；
5.2 云图小程序中设备显示为unknown问题
- 目前小程序sdk获取设备信息，是通过钉钉apigetSystemInfoSync 方法，存在当前方法对于最新机型，获取设备型号为 unknown的问题
6.更新日志
v1.0.5
2021/01/11 （正式版本）
- 增加了定时上传功能；
- 减少device信息的上报：上次上报的open_id与此次相同时不上报；
- 切换页面时立即上报数据；
- 优化数据发送规则，提高发送效率；
- 增加Taro v1.3.25和fish.mobile/taro的全埋点支持；
- 本地缓存的最大默认30条；
v1.0.4
2020/12/24 （正式版本）
- 增加全埋点的页面跳转事件采集；
v1.0.3
2020/11/18 （正式版本）
- 优化sdk，减少多余device信息的上报；
v1.0.2
2020/11/02 （正式版本）
- 支持channelId；
v1.0.0
2020/08/14 （正式版本）
- 登陆退出事件 上报记录；
- 自定义事件 上报记录；
- 设备属性 上报记录；