image

一、前言

神策数据微信小程序 SDK，是一款用于微信小程序端的数据采集埋点 SDK。具体而言，是指开发者将 SDK 集成到开发的微信小程序项目中，通过配置或者在特定时机调用 SDK 提供的接口采集用户数据并通过网络发送到指定的服务端。

二、数据采集

对于 SDK 而言，数据采集是指在用户行为触发时（例如：小程序启动、点击了某个按钮等），按照既定的数据格式，将用户的行为进行数据化。根据采集方式的不同，可以分为代码埋点、全埋点和自定义全埋点：

• 代码埋点是指调用 SDK 提供的 track() 接口采集自定义事件；

• 全埋点是指 SDK 通过代理生命周期函数与各个事件处理函数来实现预置事件的采集；

• 自定义全埋点是指将 SDK 自动采集预置事件的功能关闭，由开发者手动调用 SDK 提供的特定接口 quick() 实现预置事件的采集。

神策数据微信小程序 SDK 还提供了全埋点版本和自定义埋点版本：

• 全埋点版本是 SDK 自动代理了微信小程序的 App、Page 和 Component 三个接口，自动采集预置事件依赖于全埋点版本的 SDK；
• 自定义埋点版本是指不采用 SDK 自动采集预置事件的功能，开发者手动调用 SDK 提供的接口完成预置事件的采集。

2.1 代码埋点

2.1.1 概要介绍

代码埋点又称为自定义埋点。具体是指 SDK 初始化之后，在相关的事件处理函数中调用 track() 接口，将采集到的数据保存到发送队列中，然后按照一定的发送策略将数据发送到指定的服务端。例如：小程序中某个 view 元素被点击，如果想采集这个 view 元素的点击事件，需要在 view 元素的事件处理函数中调用 track() 接口，通过代码埋点采集 view 元素的点击事件数据。

2.1.2 使用场景

代码埋点有很多优点：

• 精准控制埋点位置，有针对性地对需要的数据进行采集；

• 灵活的自定义事件和属性，方便采集丰富的业务相关数据；

• 可以满足精细化的分析需求。

当然，代码埋点也有相应的缺点：

• 埋点成本相对比较大，每一个控件的埋点都需要添加相应的代码；

• 更新代价比较大，每一次更新埋点方案都需要修改代码并发版；

• 对用户业务代码侵入性较大，埋点代码较为分散，不好统一管理，可维护性较差。

因此，代码埋点适用于需要精准控制埋点位置、灵活的自定义事件和属性等精细化需求的场景。

2.2 全埋点

2.2.1 概要介绍

全埋点也可以称为自动埋点，SDK 通过代理 App、Page 和 Component 的生命周期函数与各个事件处理函数来实现预置事件的采集。全埋点指集成 SDK，并且开启相应的配置项后，就可以自动采集用户的部分行为数据。微信小程序 SDK 全埋点的采集范围（预置事件）包括：小程序启动、显示、进入后台、页面浏览、分享、元素点击等，事件触发与采集规则如表 2-1 所示：

表 2-1 全埋点预置事件采集规则（点击查看高清大图）

2.2.2 使用场景

全埋点有如下优点：

• 展示宏观指标，满足基本数据分析需求。通过采集 PV、UV 等常用指标，并对这些基本数据进行数据分析，有助于企业了解用户行为，为进一步数据分析指明方向；

• 技术门槛低，使用与部署较简单。只需要嵌入 SDK，极大程度地避免了因需求变更、埋点错误等原因导致重新埋点的复杂工作；

• 降低了开发者的工作量。开启相应的配置项后，自动向服务器发送数据，避免手工埋点的失误。

同时，全埋点也有一些缺点：

• 全埋点只能采集到用户交互数据，且适合标准化的采集，自定义属性的采集需要代码埋点来辅助。每个用户的交互行为均有许多属性，全埋点无法深入到更细、更深的粒度。例如：在电商行业中，用户点击 “购物车” 是一次交互行为。全埋点会忽略用户信息、商品品类等其他维度信息，此时需要配合代码埋点来辅助数据采集；再如用户上滑屏幕时，内容瀑布流的底部载入、商品或广告的加载展示、下拉菜单中内容的数据点击等情况，这类自定义行为的采集需要代码埋点来辅助实现。由于全埋点仅适合标准的方案采集，一些数据分析平台也开始支持用户为每个事件添加自定义属性，如此能大大扩展事件分析的效能；

• 小程序 SDK 全埋点是通过代理 App、Page 和 Component 三个接口并且代理相应的生命周期函数，在相应的生命周期函数中加入我们的埋点逻辑实现的。因此，如果某天微信不允许重写 App、Page 和 Component 三个接口了，那么全埋点功能将无法使用，不过这种可能性比较小。

因此，可以知道全埋点适用于以较小的埋点代价采集尽可能多的用户行为数据的场景。

2.3 自定义埋点

2.3.1 概要介绍

有些情况下，开发者的小程序项目中不允许代理 App、Page 和 Component 这三个接口，或者预置事件中的自定义属性需要异步才能获取到，此时就需要使用自定义全埋点功能。

自定义全埋点是指集成 SDK 后，开发者关闭 SDK 自动采集的功能，并在指定的生命周期函数内手动调用 SDK 提供的 quick() 接口采集预置事件。自定义全埋点采集的范围（预置事件）包括启动、显示、进入后台，事件触发与采集规则如表 2-2 所示：

表 2-2 自定义全埋点预置事件采集规则（点击查看高清大图）

2.3.2 使用场景

自定义全埋点有如下优点：

• 展示宏观指标的同时增加一些自定义的业务分析属性。这些分析属性的值通过后端接口获取，在发送预置事件时设置，既采集了 PV、UV 又能满足一些精细化的分析需求；

• 使用自定义埋点版 SDK 进行自定义全埋点时，SDK 不会代理 App、Page 和 Component 等接口。

同时，自定义全埋点也有一些缺点：

• 需要开发者按照特定写法调用 SDK 指定接口；

• 相较于全埋点会增加开发者一些工作量。

因此，自定义全埋点适用于需要给预置事件添加异步获取自定义属性值的场景，以及不能被 SDK 代理 App、Page 等接口的小程序项目。

2.4 预置属性采集

预置属性是 SDK 预先采集小程序的某些属性，例如：页面路径（scene）、屏幕宽高（ screen_width ）等。这些属性会由 SDK 自动采集，然后和手动采集的属性一起发往指定的服务端。

这些属性是自动采集的，不需要开发者增加代码，极大地增加了数据采集的范围和便利性。采集的预置属性，是数据分析中涉及的重要分析维度，自动采集极大地降低了开发和采集的成本，是可以拿来即用的部分。

预置属性采集功能的优缺点：

优点：自动帮用户采集了很多页面上的相关属性，让数据更加全面，分析维度更加丰富。

缺点：自动采集的预置属性在 SDK 内是已经固定的，无法自动采集与用户业务相关的属性（业务相关属性可以通过自定义属性采集）。

预置属性涉及的面非常广，属性的种类也有很多，会在后续的专题中详细讲解，在此就不过多展开了。

三、数据发送

3.1 数据存储

每个微信小程序都可以有自己的本地缓存，并通过微信提供的 API 对本地缓存进行读写和清理，API 的使用如表 3-1 所示：

表 3-1 微信小程序提供的不同 API 对比（点击查看高清大图）

同一个微信用户、同一个小程序 storage 上限为 10MB，storage 以用户维度隔离：

1、同一台设备上，A 用户无法读取到 B 用户的数据；

2、不同小程序之间无法互相读写数据。

3.2 发送的顺序

SDK 采集的是客户端的数据，用户的行为数据通过网络请求发送到指定的服务端。但是，网络请求是有波动的。如果是先后连在一起触发的数据，可能会出现先发后到的情况。例如：全埋点情况下小程序启动时，会连续发送小程序启动、小程序显示、小程序页面浏览三个预置事件，不过到达服务器的顺序可能是小程序页面浏览事件先到，小程序启动事件最后到达。直观来看，用户行为会非常不合理：先触发了小程序的页面浏览事件，才触发小程序的启动与小程序显示事件。

为了保证发送的顺序，SDK 在数据发送之前会构建数据发送队列，保证用户行为数据按照正确的顺序入库，形成正确的行为序列。这是如何做到的呢？SDK 在发送数据队列中的数据时，默认会按照顺序发送：当前一条数据返回发送成功的状态后，依次发送下一条数据，这保证了大部分正常流程的数据发送正确。但是，万一前面的数据发送卡住了，一直没有状态返回怎么办？SDK 的解决方案是设置超时时间：

• send_timeout: 队列发送超时时间，默认值 1000 毫秒，如果数据发送时间超过 send_timeout 还未返回结果，会强制发送下一条数据；

• datasend_timeout: 数据发送超时时间，默认值 3000 毫秒，如果数据发送时间超过 datasend_timeout 还未返回结果，会强制取消该请求。

因此，构建数据发送队列可以解决客户端行为数据发送顺序错乱的问题。

3.3 发送的方式

3.3.1 实时发送

微信小程序 SDK 中的数据采集默认情况下使用的是即时采集、即时发送的策略。由于没有使用本地缓存，减少了复杂的缓存、读取和发送的控制流程。需要注意的是，线上小程序中使用的数据接收地址需要配置 request 合法域名（微信公众平台 → 开发 → 开发设置 → 服务器域名中进行配置），否则 SDK 采集的数据无法发送。

通过网络发送数据时，无法避免的是当网络情况不佳时，会有数据发送失败的问题。数据一旦发送失败，由于没有缓存的逻辑，就会造成数据丢失。因此，微信小程序 SDK 增加了批量发送的功能。

3.3.2 批量发送

批量发送方式下，当数据产生后会先将数据存储在 storage 中（存储的数据有条数限制，最大能存储 300 条），达到发送条件后才会把存储在 storage 中的数据合并发送出去。其中，发送条件包括：

• 时间间隔：每隔一定时间（默认 6 秒）发送一次数据；

• 存储数据条数：存储数据达到一定条数（默认 6 条）时发送一次数据；

• 进入后台：当小程序进入后台时发送一次数据。

上述三个发送条件满足任意一个即可发送数据。

如果数据发送不成功，会将发送的数据保存起来，满足发送条件后，与之后的数据一起尝试发送。这样，可以减少网络请求、节省服务器资源，并且有效地降低一些数据发送过程中的丢失问题。

四、调试事件信息

集成 SDK 并触发一些事件后，默认会把采集的数据实时发送至神策后台。那么我们如何得知 SDK 采集的数据是否完整，发送是否成功呢？这里我们提供了两种调试事件信息的方式：本地调试和实时数据查看。

4.1 本地调试

默认情况下，SDK 会将采集的数据信息打印在微信开发者工具的 Console 面板，如图 4-1 所示：

图 4-1 SDK 打印的数据信息

在开发工具的 Console 面板看到打印的数据信息后，表示 SDK 采集到了小程序中的数据，但是并不代表发送成功。查看数据的发送情况可以通过在微信开发者工具的 Network 面板查看 SDK 的数据请求，如图 4-2 所示：

图 4-2 SDK 发送的数据请求

如上图所示，Network 面板中有 SDK 的数据请求，并且请求状态码为 200，表示 SDK 成功地将采集的数据发送至神策后台。

4.2 实时数据查看

4.1 节中介绍了客户端 SDK 采集数据的过程，那么采集的数据会发送到哪里呢？可以在神策后台实时数据中查看。在神策分析后台 → 埋点管理 → 实时导入数据查询中，点击 “开始刷新” 按钮，可以看到有数据进入。如图 4-3 所示：

图 4-3 神策分析后台的实时导入数据查询

五、总结

本文对于微信小程序 SDK 进行了简明扼要的介绍，概述了微信小程序 SDK 的基本功能，旨在让大家对于它有一个初步的了解。关于具体使用和实现原理等相关知识，会在后续的文章中逐步向大家介绍。

本文作者

马慧青

神策数据 | 微信小程序 SDK 技术顾问

我是马慧青，神策数据微信小程序 SDK 技术顾问，主要从事小程序方面技术的研究和学习，希望通过开源社区这个平台在与大家交流的过程中共同进步。生活中喜欢听音乐、跑步，尽可能充实、完善自己。