【导入实时查看】—>【Debug 数据】 事件名选择 “$pageview” 点击【开始刷新】实时查看具
体事件及属性是否正确。在手机上，打开 App 进入到 H5 页面。看 “$pageview” 事件的属性，如果有 “$wifi” “$network_type” 、“$app_version” 、
“$carrier”等字段，说明 App 和 H5 打通成功。（或者开启 SDK 调试日志后，在开发工具的控制台，通过输出的事件日志信息来核对）
也可以在事件分析中，找到 Web浏览页面 事件，查看事件属性中是否带有 设备ID、应用版本、是否 WIFI、网络类型、运营商。.基础数据校验 v1.13
本环节由测试人员完成，需要完成的任务如下：
对事件和属性的完整性及数据类型进行校验
对用户关联情况进行校验
验证 App 与 H5 打通（做了打通的情况下）
1. 事件和属性完整性校验
进入神策分析页面，点击左下角【元事件管理】，查看元事件和属性字段，请注意此时事件和属性显示名仍是英文，后续需要统一调整为对应的中文名。检
查项如下：
1.1. 检查事件及名字是否与《事件设计文档》一致。
事件是否有遗留或新增。如有新增事件可能是开发人员测试产生的，需要开发确认相关的埋点代码已经清除。如有遗留则可能是漏埋了或者埋点了但是未传
输过数据。
1.2. 点选事件名，检查其包含的属性是否完整，名字和类型是否正确。
属性是否有遗留或新增。这块遗留的情况比较常见，可能是漏埋了。
属性值类型是否与事件设计一致。如不一致，请开发在代码里修正变量类型，然后联系技术支持同学修改变量类型，修正后的数据才可正常入库。或者另取
一个属性名，数据即可直接入库。2. 对用户关联情况进行校验
在开始本小节的校验之前，请提前阅读 第 2 步：如何准确的标识用户 并确定理解了用户关联的概念和方案。
该环节需要结合神策分析中“自定义查询”的功能来操作，校验的目的有 3 点：
1. 检查 first_id 取值是否存在异常，是否有将 second_id 写入 first_id 的错误操作；
2. 检查 second_id 取值是否异常，是否有正常关联的用户存在；
3. 检查用户 ID 关联过程是否正常。
2.1. 检查 first_id 取值
查询 users 表，检查查询结果中 first_id 是否为设备 ID，以及是否存在异常情况。以下是各端 SDK 默认取的设备 ID ，可根据 ID 格式大致判断 first_id 取
值是否正常。
sql select * from users limit 1000
SDK 类型 ID 样式
Android 端 01c23e12e10a7810（AndroidID 为 16 位 ，字母+数字组成）
iOS 端 447BAE19-7117-4D1B-81E2-7B46AA7998A4（IDFA / IDFV / UUID 为32位，8-4-4-4-12）
H5 端 15ffdb0a3f898-02045d1cb7be78-31126a5d-250125-15ffdb0a3fa40a
微信小程序 oWDMZ0WHqfsjIz7A9B2XNQOWmN3E（28 位，字母+数字组成）
上面查询结果中可能存在的常见情况有：
- first_id = second_id，这种情况可能是正常的，如果开发人员在同一台设备上登录过多个账号，则除了首个登录的账号会进行正常关联外，其余
账号均会发生自关联，即出现 first_id = second_id = 账号 ID 的情况。
first_id 的实际取值不是设备 ID，而是账号 ID，而 second_id 取值为空，这种情况代表着 second_id 误写入了 first_id，可通过下方SQL 进一步检
查。sqlSELECT u1.first_id, u1.second_id, u2.first_id, u2.second_id FROM users u1 JOIN users u2 ON u1.first_id = u2.
second_id WHERE u1.second_id IS NULL;
如果以上查询有返回结果，原因可能但不限于如下情况:
$SignUp 事件传送失败，导致没有关联成功;
后端在传 distinct_id 时没有设置 is_login_id 的参数值为 true;
调 login 时误调用了 identify，将登录 ID 替换了匿名 ID。
2.2. 检查 second_id 取值
查询 users 表，观察 second_id 取值是否是预设的 user_id 或其他用户唯一标识。注意，在测试环境中 second_id 大部分为空的情况可能是正常的，开发
人员可能仅对少量测试账号进行了 ID 关联的尝试。
检查是否有正常关联的情况存在，即 first_id 取值为设备 ID，second_id 取值为 user_id。
2.3. 检查用户 ID 关联过程是否正常
在 users 表的查询结果中，选取一个正常关联的情况的 id（users 表的 id 字段）在events 表中查询行为记录。
sqlselect * from events where user_id = "id" order by time
查询结果中主要观察的点，首次触发 $SignUp 事件前后，events 表中的数据记录的 $distinct_id 字段前后取值会由设备 ID 替换为 user_id。存在这个情况
便表示存在有正常关联的过程。如果您采取的是多对一的关联方案，请联系对应的分析师协助这部分内容的校验。
3. 验证 App 与 H5 打通
做了 App 与 H5 打通 的情况下，才需要进行本环节的验证。
如果是开发人员，进入神策分析页面，点击左下侧【埋点】—>【导入实时查看】—>【Debug 数据】 事件名选择 “$pageview” 点击【开始刷新】实时查看具
体事件及属性是否正确。在手机上，打开 App 进入到 H5 页面。看 “$pageview” 事件的属性，如果有 “$wifi” “$network_type” 、“$app_version” 、
“$carrier”等字段，说明 App 和 H5 打通成功。（或者开启 SDK 调试日志后，在开发工具的控制台，通过输出的事件日志信息来核对）
也可以在事件分析中，找到 Web浏览页面 事件，查看事件属性中是否带有 设备ID、应用版本、是否 WIFI、网络类型、运营商。产品使用指南
使用流程
使用时，我们推荐如下的使用实践：
1. 准备阶段：
在我们的技术支持下，完成数据分析需求的梳理；
根据需求完成行为事件的初步划分，以及关键用户 Profile 的设计；
完成神策分析的系统安装。
2. 试用阶段：
从已有的数据库或者历史日志中，按照我们指定的[数据格式](data_schema.md)，导出一批历史数据；
使用批量导入工具，将历史数据导入到系统中；
在已导入的这批数据上，使用产品，完成一些数据分析工作；
根据需求和使用情况，修改事件模型或者增加相应的属性；
经过迭代，能够满足需求后，确认最终的事件模型。
3. 线上使用阶段：清空试用环境数据；
通过 LogAgent 实时传入日志，或者使用我们提供的各种客户端或者后端 SDK 来实时传入数据；
结合具体的业务需求，使用抽象的各个数据分析模型，生成所关心的核心指标，可以保存核心指标为书签，还可以将书签添加到数据概览中展示；
当有业务场景需要进行具体的分析：例如转化率突然下降，希望分析是哪个渠道的问题；或者是想具体分析在转化时流失的用户的具体情况等，则
可以相应使用具体的功能。.产品使用指南 v1.13
使用流程
使用时，我们推荐如下的使用实践：
1. 准备阶段：
在我们的技术支持下，完成数据分析需求的梳理；
根据需求完成行为事件的初步划分，以及关键用户 Profile 的设计；
完成神策分析的系统安装。
2. 试用阶段：
从已有的数据库或者历史日志中，按照我们指定的数据格式，导出一批历史数据；
使用批量导入工具，将历史数据导入到系统中；
在已导入的这批数据上，使用产品，完成一些数据分析工作；
根据需求和使用情况，修改事件模型或者增加相应的属性；
经过迭代，能够满足需求后，确认最终的事件模型。
3. 线上使用阶段：清空试用环境数据；
通过 LogAgent 实时传入日志，或者使用我们提供的各种客户端或者后端 SDK 来实时传入数据；
结合具体的业务需求，使用抽象的各个数据分析模型，生成所关心的核心指标，可以保存核心指标为书签，还可以将书签添加到数据概览中展示；
当有业务场景需要进行具体的分析：例如转化率突然下降，希望分析是哪个渠道的问题；或者是想具体分析在转化时流失的用户的具体情况等，则
可以相应使用具体的功能。基本概念
本节，我们主要介绍在使用神策分析来进行用户行为分析时常用到的一些名词和一些基础指标的配置说明，目的是帮助用户更好的理解和使用神策数据的功
能来解决基本的分析需求。
行为分析常用名词
神策分析相关名词
基础指标配置说明
属性筛选条件说明.基本概念 v1.13
本节，我们主要介绍在使用神策分析来进行用户行为分析时常用到的一些名词和一些基础指标的配置说明，目的是帮助用户更好的理解和使用神策数据的功
能来解决基本的分析需求。
行为分析常用名词
神策分析相关名词
基础指标配置说明
属性筛选条件说明行为分析常用名词
维度
维度描述的是一个事物身上所具备的特征或属性。比如一个人属于什么性别，生活在哪个城市，喜欢什么颜色，这些都是这个人身上所具备的属性特征。
而在网站分析领域，维度往往用来描述和分析指标，比如单一的访问数指标并不能告诉你太多信息，一旦加上来源这个维度，就马上变得有意义了。
指标
指标，即具体的数值。比如访客、页面浏览量、停留时长都属于常见的指标。
指标一般可分为计数指标和复合指标。计数指标如访客、访问、页面浏览量、停留时长等；复合指标如跳出率、访问深度、转化率等。指标一般伴随维度来
分析才有更大的意义。
展示和点击
展示，指页面上元素的曝光次数。点击，指页面元素被用户点击的次数。
这两个指标主要适用于线上广告投放，比如评估投放在新浪首页的品牌广告，展示了多少次，点击了多少次。
访客
英文为 Visitor，通俗解释为访问网站或 App 的人。前面加上 Unique 后，即我们平常说的 UV，唯一身份访客。
对于数据统计工具而言，一般用匿名 ID 来标记访问者，网页端产品是 Cookie（网站服务器投放在用户浏览器上的一小段文本），App 端产品是设备 ID。
访问
即 Visit，网页端产品常用概念，指用户一系列连续的页面浏览行为，跟会话 Session 同义。随着移动互联网的崛起，考虑到 App 的使用，Session 慢慢代
替 Visit 成为主要用词。
业界对于 Session 内行为间的间隔设定了有效期限，网页端产品为 30 分钟，App 端产品时间较短，一般为 1 分钟。
页面浏览量
PageView，即 PV，指页面被用户浏览的次数，严格定义上指的是用户向网站发出并完成的一个下载页面的请求。
页面浏览的概念主要适用于网页端产品，对于 App 的分析，现主要使用屏幕浏览，即 ScreenView。
跳出率
BounceRate，一个衡量落地页质量好坏的重要指标。跳出的概念是指用户在一次访问中仅做了一次互动便选择了离开，单一页面和全站均有跳出率的概念。
页面跳出率的计算为该页面作为落地页跳出的访问次数占该页面作为落地页访问次数的百分比。全站跳出率则为跳出的访问次数除以总的访问次数。
停留时长
对应于用户 Session，便有了停留时长指标，主要用来衡量用户与网站、App 交互的深度。交互越深，相应停留的时长也越长。
一般有页面停留时长，会话时长以及平均停留时长等概念，其计算的核心原理在于记录下用户行为发生时的时间戳，后期再应用相应公式来计算。
转化率
任何产品都需要关注的核心指标，主要用来衡量用户从流量到发生实际目标转化的能力。
一般用目标转化的次数或人数除以进入目标转化漏斗的人数或次数，因目标行为的不同，转化率是一个非常灵活的指标，比如你可以自定义注册转化率、登
录转化率、购买转化率、搜索成功转化率等。.行为分析常用名词 v1.13
维度
维度描述的是一个事物身上所具备的特征或属性。比如一个人属于什么性别，生活在哪个城市，喜欢什么颜色，这些都是这个人身上所具备的属性特征。
而在网站分析领域，维度往往用来描述和分析指标，比如单一的访问数指标并不能告诉你太多信息，一旦加上来源这个维度，就马上变得有意义了。
指标
指标，即具体的数值。比如访客、页面浏览量、停留时长都属于常见的指标。
指标一般可分为计数指标和复合指标。计数指标如访客、访问、页面浏览量、停留时长等；复合指标如跳出率、交互深度、转化率等。指标一般伴随维度来
分析才有更大的意义。
展示和点击
展示，指页面上元素的曝光次数。点击，指页面元素被用户点击的次数。
这两个指标主要适用于线上广告投放，比如评估投放在新浪首页的品牌广告，展示了多少次，点击了多少次。
访客
英文为 Visitor，通俗解释为访问网站或 App 的人。前面加上 Unique 后，即我们平常说的 UV，唯一身份访客。
对于数据统计工具而言，一般用匿名 ID 来标记访问者，网页端产品是 Cookie（网站服务器投放在用户浏览器上的一小段文本），App 端产品是设备 ID。
访问
即 Visit，网页端产品常用概念，指用户一系列连续的页面浏览行为，跟会话 Session 同义。随着移动互联网的崛起，考虑到 App 的使用，Session 慢慢代
替 Visit 成为主要用词。
业界对于 Session 内行为间的间隔设定了有效期限，网页端产品为 30 分钟，App 端产品时间较短，一般为 1 分钟。
页面浏览量
PageView，即 PV，指页面被用户浏览的次数，严格定义上指的是用户向网站发出并完成的一个下载页面的请求。
页面浏览的概念主要适用于网页端产品，对于 App 的分析，现主要使用屏幕浏览，即 ScreenView。
停留时长
对应于用户 Session，便有了停留时长指标，主要用来衡量用户与网站、App 交互的深度。交互越深，相应停留的时长也越长。
一般有页面停留时长，会话时长以及平均停留时长等概念，其计算的核心原理在于记录下用户行为发生时的时间戳，后期再应用相应公式来计算。
跳出率
BounceRate，一个衡量落地页质量好坏的重要指标。跳出的概念是指用户在一次访问中仅做了一次互动便选择了离开，单一页面和全站均有跳出率的概念。
页面跳出率的计算为该页面作为落地页跳出的访问次数占该页面作为落地页访问次数的百分比。全站跳出率则为跳出的访问次数除以总的访问次数。
交互深度
交互深度是指用户在一次浏览网站或 App 过程中，访问了多少页面。用户在一次浏览中访问的页面越多，交互深度就越深。交互深度能够侧面反映网站或
App 对于用户的吸引力。
可以通过 Session 来计算用户的平均交互深度。转化率
任何产品都需要关注的核心指标，主要用来衡量用户从流量到发生实际目标转化的能力。
一般用目标转化的次数或人数除以进入目标转化漏斗的人数或次数，因目标行为的不同，转化率是一个非常灵活的指标，比如你可以自定义注册转化率、登
录转化率、购买转化率、搜索成功转化率等。神策分析相关名词
指标
1. 总次数
事件分析功能常用指标，指在选定的时间范围内，某一事件被触发的次数。
比如选择页面浏览事件，按总次数查看时，计算出来的值即为页面浏览量。
2. 触发用户数
事件分析功能常用指标，指在选定的时间范围内，触发某一事件的独立用户数。
比如选择注册成功事件，按独立用户数查看时，计算出来的值即为选择时间范围内的注册成功人数。
3. 人均次数
事件分析功能常用指标，指在选定的时间范围内，独立用户触发某一事件的平均次数。
比如选择页面浏览事件，按人均次数查看时，计算出来的值即为人均页面浏览深度
属性
为了帮助使用者更方便地使用我们的产品，我们目前分别为事件和用户提供了一些预置属性。
预置属性.神策分析相关名词 v1.13
指标
1. 总次数
事件分析功能常用指标，指在选定的时间范围内，某一事件被触发的次数。
比如选择页面浏览事件，按总次数查看时，计算出来的值即为页面浏览量。
2. 触发用户数
事件分析功能常用指标，指在选定的时间范围内，触发某一事件的独立用户数。
比如选择注册成功事件，按独立用户数查看时，计算出来的值即为选择时间范围内的注册成功人数。
3. 人均次数
事件分析功能常用指标，指在选定的时间范围内，独立用户触发某一事件的平均次数。
比如选择页面浏览事件，按人均次数查看时，计算出来的值即为人均页面浏览深度
属性
为了帮助使用者更方便地使用我们的产品，我们目前分别为事件和用户提供了一些预置属性。
点击查看预置属性的详细介绍。基础指标配置说明
Web 端日活跃用户数（UV）
> 定义：1天（00:00-24:00）之内，访问网站的不重复用户数，一天内同一访客多次访问网站只被计算1次。
1. 选择“行为事件分析”功能
2. 选择事件：浏览页面
3. 选择指标：触发用户数
App 端日活跃用户数（UV）
> 定义：1天（00:00-24:00）之内，访问App的不重复用户数，一天内同一访客多次访问 App 只被计算1次。
1. 选择“行为事件分析”功能
2. 选择事件：启动 App
3. 选择指标：触发用户数
页面浏览量（PV）
> 定义：网页浏览是指浏览器加载（或重新加载）网页的实例。页面浏览量可以定义为网页浏览总次数的指标。1. 选择“行为事件分析”功能
2. 选择事件：浏览页面
3. 选择指标：总次数
新增注册用户数
> 定义：当天注册用户数
1. 选择“行为事件分析”功能
2. 选择事件：注册
3. 选择指标：触发用户数
Web 端新用户数
> 定义：当日的独立访客中，历史上首日访问网站的访客定义为新用户。
1. 选择“行为事件分析”功能
2. 选择事件：浏览页面
3. 选择指标：触发用户数
4. 添加筛选条件：是否首日访问为真
App 端新用户数
> 定义：当日启动 App 的用户中，历史上首日启动 App 的用户为新用户数。1. 选择“行为事件分析”功能
2. 选择事件：启动 App
3. 选择指标：触发用户数
4. 添加筛选条件：是否首日访问为真
Web 端新用户比例
> 定义：当日的访客中，新用户在所有访客中占的比例。
* 首先创建虚拟事件：【Web】新用户访问
1. 点击页面左下角“元数据”，找到虚拟事件窗口
2. 创建虚拟事件1. 设置虚拟事件名和显示名，如上图所示。
2. 虚拟事件的组成，选择事件：浏览页面
3. 添加限制条件：是否首日访问为真
接下来我们来计算新用户比例这个指标
切换自定义指标
1. 点击左侧的行为事件分析功能
2. 点击切换按钮，输入公式：【Web】新用户访问.触发用户数/浏览页面.触发用户数
3. 命名为“新用户比例”
4. 最后点击保存即可App 端新用户比例
> 当日启动 App 的用户中，新用户在所有启动 App 的用户中所占的比例。
首先创建虚拟事件：【App】新用户访问
1. 点击页面左下角“元数据”，找到虚拟事件窗口
2. 创建虚拟事件1. 设置虚拟事件名和显示名，如上图所示。
2. 虚拟事件的组成，选择事件：启动 App
3. 添加限制条件：是否首日访问为真
接下来我们来计算新用户比例这个指标
切换自定义指标1. 点击左侧的行为事件分析功能
2. 点击切换按钮，输入公式：【App】新用户访问.触发用户数/启动App.触发用户数
3. 命名为“新用户比例”
4. 最后点击保存即可
启动次数
> 定义：启动 App 的次数
1. 选择“行为事件分析”功能
2. 选择事件：启动 App
3. 选择指标：总次数
Web 端新用户留存率
> 定义：在互联网行业中，用户在某段时间内开始使用应用，经过一段时间后，仍然继续使用该应用的用户，被认作是留存用户。这部分用户占当时新增用
户的比例即是留存率，会按照每隔1单位时间（例日、周、月）来进行统计。顾名思义，留存指的就是“有多少用户留下来了”。
1. 选择留存分析功能
2. 初始行为：选择浏览页面
3. 添加筛选条件：是否首日访问为真
4. 后续行为：选择任意事件
5. 选择日留存、周留存、月留存
App 端新用户留存率
> 定义：在互联网行业中，用户在某段时间内开始使用应用，经过一段时间后，仍然继续使用该应用的用户，被认作是留存用户。这部分用户占当时新增用
户的比例即是留存率，会按照每隔1单位时间（例日、周、月）来进行统计。顾名思义，留存指的就是“有多少用户留下来了”。1. 选择留存分析功能
2. 初始行为：选择启动 App
3. 添加筛选条件：是否首日访问为真
4. 后续行为：选择任意事件
5. 选择日留存、周留存、月留存
购买转化率
> 定义：当日访客中，有多少比例的客户购买。
1. 点击左侧的行为事件分析功能
2. 点击切换按钮，输入公式：支付订单.触发用户数/浏览页面.触发用户数
3. 命名为“付费率”
4. 最后点击保存即可
以下指标“访问次数、平均交互深度、平均使用时长、页面平均停留时长、跳出率、页面退出率”需引入 Session 才能分析。
Session 即会话，是指在指定的时间段内在您的网站上发生的一系列互动。例如，一次会话可以包含多个网页或屏幕浏览、事件、社交互动和电子商务交
易。
我们需要先创建一个 Session1. 点击左下角的“元数据”
2. 点击 Session 管理
3. 点击创建 Session1. 输入 Session 名：session
2. 输入 Session 显示名：全站 Session
3. 选择事件：选择 Session 包含的事件，如全选
4. 设置切割规则：30分钟
5. 点击保存，即创建成功。
一般 Web 端产品建议切割时间为30分钟，App 端产品建议切割时间为1分钟*
1. 回到行为事件分析功能
2. 切换分析规则为 Session至此，可以进行 Session 分析，计算上述指标。
访问次数
> 定义：访客从进入网站/App 到离开网站/App 的一系列活动记为一次访问，也称会话（Session）。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：Session 总次数
平均交互深度
> 定义：等于所有 Session 内事件数之和除以总的 Session 数。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：Session 深度的均值
平均使用时长
> 定义：等于所有用户的 Session 时长之和除以 Session 数。1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：Session 时长的均值
页面平均停留时长
> 定义：等于页面停留时长的总和除以页面被浏览的触发数。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 内事件：浏览页面
4. 选择指标：Session 内事件时长的均值
跳出率
> 定义：当一个 Session 仅有一个事件时，即视为跳出，一般情况这个事件以浏览页面居多。所以 Session 整体跳出率等于跳出的 Session 数除以
Session 总数，而具体事件或页面的跳出率，可以按属性查看或筛选得出。1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：跳出率
5. 按“总体查看”即为网站整体跳出率，按“网页URL”查看，即页面跳出率。
页面退出率
> 定义：当用户在某个页面结束了该 Session 时即视为退出，所以页面退出率等于退出的页面数除以该页面的总浏览次数。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 内具体事件：浏览页面
4. 选择指标：退出率
5. 选择属性分组：网页 URL
如何创建购买转化漏斗
> 可以假设这样一种场景，用户从看到某一个促销活动到最终购买，可能会经历这样一个过程“浏览活动页—浏览商品列表页—浏览商品详情页—加入购物
车—提交订单—支付订单”，我们可以对这样一个过程建立一个购买转化漏斗，来帮助你分析一个多步骤过程中每一步的转化与流失情况。
创建漏斗1. 点击左侧的漏斗分析功能
2. 点击右上角的创建漏斗1. 填写漏斗名称。给你的漏斗取一个具有代表性的友好名称。同一项目内，漏斗不可重名。
2. 选择漏斗窗口期。整个漏斗流程的完成所需要的时间。
3. 增加漏斗步骤。一个漏斗中至少包含2个步骤，每个步骤对应一个事件，可附带一个或多个筛选条件，如第1、2、3步对网页 Title 和网页 URL 的筛选，
以便找到满足我们需求的页面。
4. 如有需求，可以继续给漏斗增加步骤
5. 最后保存漏斗即可
分析漏斗
1. 选择查看漏斗的方式。先按总体查看总体转化率。
2. 从漏斗图可以看到每一步的转化率
3. 如果想看某一步的流失用户数，找到流失用户列表，即可看到有多少用户流失了。点击流失用户数“7422”，即可看到该批流失用户的详细信息。
点击用户的 distinct\_id，即可看到该用户在流失前详细的用户行为路径优化好漏斗后，我们就可以定期观察总体以及每一步漏斗转化率变化趋势了。那么不同细分维度的漏斗表现怎么样呢？
1. 按第一步广告系列来源查看
2. 切换对比，勾选要对比的两个渠道，就能看到两个渠道对比的总转化率和每一步转化率的区别。
3. 如想看某个广告系列下这两个渠道的对比数据，则增加筛选条件：广告系列名称等于spring2017.基础指标配置说明 v1.13
1. Web 端日活跃用户数（UV）
定义：1天（00:00-24:00）之内，访问网站的不重复用户数，一天内同一访客多次访问网站只被计算1次。
1. 选择“行为事件分析”功能
2. 选择事件：浏览页面
3. 选择指标：触发用户数
2. App 端日活跃用户数（UV）
定义：1天（00:00-24:00）之内，访问App的不重复用户数，一天内同一访客多次访问 App 只被计算1次。
1. 选择“行为事件分析”功能
2. 选择事件：启动 App
3. 选择指标：触发用户数
3. 页面浏览量（PV）
> 定义：网页浏览是指浏览器加载（或重新加载）网页的实例。页面浏览量可以定义为网页浏览总次数的指标。1. 选择“行为事件分析”功能
2. 选择事件：浏览页面
3. 选择指标：总次数
4. 新增注册用户数
定义：当天注册用户数
1. 选择“行为事件分析”功能
2. 选择事件：注册
3. 选择指标：触发用户数
5. Web 端新用户数
定义：当日的独立访客中，历史上首日访问网站的访客定义为新用户。1. 选择“行为事件分析”功能
2. 选择事件：浏览页面
3. 选择指标：触发用户数
4. 添加筛选条件：是否首日访问为真
6. App 端新用户数
定义：当日启动 App 的用户中，历史上首日启动 App 的用户为新用户数。
1. 选择“行为事件分析”功能
2. 选择事件：启动 App
3. 选择指标：触发用户数
4. 添加筛选条件：是否首日访问为真
7. Web 端新用户比例
定义：当日的访客中，新用户在所有访客中占的比例。
* 首先创建虚拟事件：【Web】新用户访问1. 点击页面左下角“元数据”，找到虚拟事件窗口
2. 创建虚拟事件
1. 设置虚拟事件名和显示名，如上图所示。
2. 虚拟事件的组成，选择事件：浏览页面
3. 添加限制条件：是否首日访问为真
接下来我们来计算新用户比例这个指标
7.1. 切换自定义指标1. 点击左侧的行为事件分析功能
2. 点击切换按钮，输入公式：【Web】新用户访问.触发用户数/浏览页面.触发用户数
3. 命名为“新用户比例”
4. 最后点击保存即可
8. App 端新用户比例
当日启动 App 的用户中，新用户在所有启动 App 的用户中所占的比例。
8.1. 首先创建虚拟事件：【App】新用户访问
1. 点击页面左下角“元数据”，找到虚拟事件窗口
2. 创建虚拟事件1. 设置虚拟事件名和显示名，如上图所示。
2. 虚拟事件的组成，选择事件：启动 App
3. 添加限制条件：是否首日访问为真
接下来我们来计算新用户比例这个指标
8.2. 切换自定义指标1. 点击左侧的行为事件分析功能
2. 点击切换按钮，输入公式：【App】新用户访问.触发用户数/启动App.触发用户数
3. 命名为“新用户比例”
4. 最后点击保存即可
9. 启动次数
定义：启动 App 的次数
1. 选择“行为事件分析”功能
2. 选择事件：启动 App
3. 选择指标：总次数
10. Web 端新用户留存率
定义：在互联网行业中，用户在某段时间内开始使用应用，经过一段时间后，仍然继续使用该应用的用户，被认作是留存用户。这部
分用户占当时新增用户的比例即是留存率，会按照每隔1单位时间（例日、周、月）来进行统计。顾名思义，留存指的就是“有多少用
户留下来了”。
1. 选择留存分析功能
2. 初始行为：选择浏览页面
3. 添加筛选条件：是否首日访问为真
4. 后续行为：选择任意事件
5. 选择日留存、周留存、月留存11. App 端新用户留存率
定义：在互联网行业中，用户在某段时间内开始使用应用，经过一段时间后，仍然继续使用该应用的用户，被认作是留存用户。这部
分用户占当时新增用户的比例即是留存率，会按照每隔1单位时间（例日、周、月）来进行统计。顾名思义，留存指的就是“有多少用
户留下来了”。
1. 选择留存分析功能
2. 初始行为：选择启动 App
3. 添加筛选条件：是否首日访问为真
4. 后续行为：选择任意事件
5. 选择日留存、周留存、月留存
12. 购买转化率
定义：当日访客中，有多少比例的客户购买。
1. 点击左侧的行为事件分析功能
2. 点击切换按钮，输入公式：支付订单.触发用户数/浏览页面.触发用户数
3. 命名为“付费率”
4. 最后点击保存即可
以下指标“访问次数、平均交互深度、平均使用时长、页面平均停留时长、跳出率、页面退出率”需引入 Session 才能分析。
Session 即会话，是指在指定的时间段内在您的网站上发生的一系列互动。例如，一次会话可以包含多个网页或屏幕浏览、事件、社交互动和电子商务交
易。
我们需要先创建一个 Session1. 点击左下角的“元数据”
2. 点击 Session 管理
3. 点击创建 Session1. 输入 Session 名：session
2. 输入 Session 显示名：全站 Session
3. 选择事件：选择 Session 包含的事件，如全选
4. 设置切割规则：30分钟
5. 点击保存，即创建成功。
一般 Web 端产品建议切割时间为30分钟，App 端产品建议切割时间为1分钟
1. 回到行为事件分析功能
2. 切换分析规则为 Session
至此，可以进行 Session 分析，计算上述指标。13. 访问次数
定义：访客从进入网站/App 到离开网站/App 的一系列活动记为一次访问，也称会话（Session）。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：Session 总次数
14. 平均交互深度
定义：等于所有 Session 内事件数之和除以总的 Session 数。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：Session 深度的均值
15. 平均使用时长
定义：等于所有用户的 Session 时长之和除以 Session 数。1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：Session 时长的均值
16. 页面平均停留时长
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 内事件：浏览页面
4. 选择指标：Session 内事件时长的均值
17. 跳出率
定义：当一个 Session 仅有一个事件时，即视为跳出，一般情况这个事件以浏览页面居多。所以 Session 整体跳出率等于跳出的
Session 数除以 Session 总数，而具体事件或页面的跳出率，可以按属性查看或筛选得出。1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 总体
4. 选择指标：跳出率
5. 按“总体查看”即为网站整体跳出率，按“网页URL”查看，即页面跳出率。
18. 页面退出率
定义：当用户在某个页面结束了该 Session 时即视为退出，所以页面退出率等于退出的页面数除以该页面的总浏览次数。
1. 选择“行为事件分析”功能
2. 选择 Session：全站 Session
3. 选择 Session 内具体事件：浏览页面
4. 选择指标：退出率
5. 选择属性分组：网页 URL
19. 如何创建购买转化漏斗
可以假设这样一种场景，用户从看到某一个促销活动到最终购买，可能会经历这样一个过程“浏览活动页—浏览商品列表页—浏览商品
详情页—加入购物车—提交订单—支付订单”，我们可以对这样一个过程建立一个购买转化漏斗，来帮助你分析一个多步骤过程中每一
步的转化与流失情况。
创建漏斗1. 点击左侧的漏斗分析功能
2. 点击右上角的创建漏斗1. 填写漏斗名称。给你的漏斗取一个具有代表性的友好名称。同一项目内，漏斗不可重名。
2. 选择漏斗窗口期。整个漏斗流程的完成所需要的时间。
3. 增加漏斗步骤。一个漏斗中至少包含2个步骤，每个步骤对应一个事件，可附带一个或多个筛选条件，如第1、2、3步对网页 Title 和网页 URL 的筛选，
以便找到满足我们需求的页面。
4. 如有需求，可以继续给漏斗增加步骤
5. 最后保存漏斗即可
分析漏斗
1. 选择查看漏斗的方式。先按总体查看总体转化率。
2. 从漏斗图可以看到每一步的转化率
3. 如果想看某一步的流失用户数，找到流失用户列表，即可看到有多少用户流失了。点击流失用户数“7422”，即可看到该批流失用户的详细信息。
点击用户的 distinct\_id，即可看到该用户在流失前详细的用户行为路径优化好漏斗后，我们就可以定期观察总体以及每一步漏斗转化率变化趋势了。那么不同细分维度的漏斗表现怎么样呢？
1. 按第一步广告系列来源查看
2. 切换对比，勾选要对比的两个渠道，就能看到两个渠道对比的总转化率和每一步转化率的区别
3. 如想看某个广告系列下这两个渠道的对比数据，则增加筛选条件：广告系列名称等于spring2017属性筛选条件说明
1. 什么是筛选条件
筛选条件是为了在我们取到的数据集中，通过设置一个条件进行过滤，获取我们最终想得到的子数据集进行分析。神策所有的分析功能中都有筛选条件的选
项，均可以实现根据事件的属性进行筛选或根据用户的属性进行筛选。
> 筛选条件可类比于 SQL 中的 where 条件语句
> 当使用用户筛选条件时， where 条件作用于 users 表；当使用事件筛选条件时， where 条件作用于 events 表
2. 使用流程
在神策所有的分析功能中，我们可以看到`筛选条件`、`触发限制条件`等按钮时，代表此处可以对用户或事件进行筛选，参考上图中的标识，具体配置流程如
下：
1. 点击弹出筛选条件输入框，可以同时添加一个或多个筛选条件
2. 在 B 中选择筛选事件或用户的属性
3. 在 C 中选择属性的 判断类型 ，不同的属性类型拥有不同的 判断类型，不同 判断类型 的使用方法可参考第 3 部分
4. 在 D 选项中输入 判断值 后，分析结果即会根据输入条件进行筛选
3. 筛选条件分类
3.1 按目标
筛选用户：筛选条件作用于用户表，只看符合筛选条件的那些用户；一般在用户属性上进行条件设置，或者选择用户分群获取符合分析条件的用户。
筛选事件：筛选条件作用于事件，只看符合筛选条件的事件；一般在事件属性上进行条件设置。
3.2 按数据类型
不管是为了筛选出不同用户或筛选不同事件，具体的每一个筛选条件的设置，都可以按其数据类型来了解。
3.2.1 字符串类型属性筛选当筛选的属性为字符串类型时，可以看到如上图中标识的判断类型，具体每个判断类型的使用可参考下表：
判断 类比 SQL 描述说明
类型
等于 = 精确判断，只有选择的事件属性等于输入的判断值时，该事件才会才会进入分析过程；当判断值存在多个时，事件属性值等于
任意一个，该事件都会进入分析的数据集
不等于 != 精确判断，只有选择的事件属性不等于输入的判断值时，该事件才会才会进入分析过程；当判断值存在多个时，事件属性值等
于任意一个，该事件就不会进入分析过程
包含 LIKE "%$%" 匹配判断，当属性字段中包含判断值，该事件或用户就会进入分析过程
不包含 NOT LIKE 匹配判断，与“包含”相反，当属性字段中包含判断值，该事件不会进入分析过程
"%$%"
不为空 Length($)>0 当属性字段中有值(字符串长度大于 0 )时，事件或用户才会进入分析过程
为空 ="" 当属性字段中值为空字符串时，事件或用户才会进入分析过程
没值 IS NULL 只有属性字段中值为 NULL 时，事件或用户才会进入分析过程
有值 IS NOT 只有属性字段中值不为 NULL 时，事件或用户才会进入分析过程
NULL
正则匹 匹配判断，符合条件的数据进入分析过程，具体请参考：正则表达式
配
正则不 匹配判断，只有不符合正则条件的数据进入分析过程，具体请参考：正则表达式
匹配
3.2.2 数值类型属性筛选当筛选的属性为数字类型时，可以看到如上图中标识的判断类型，具体每个判断类型的使用可参考下表：
判断类 类比表达式 描述说明
型
等于 = 类同于字符串类型
不等于 != 类同于字符串类型
小于 < 所选属性值小于判断值的事件才会进入分析过程
大于 > 所选属性值大于判断值的事件才会进入分析过程
区间 between . 所选属性值处于设置的判断值所形成的闭区间时，事件才会进入分析流程；如判断值设置为 10 和 100 时，所选属性值需要
and . 满足 [10,100] 区间
有值 IS NOT 类同于字符串类型
NULL
没值 IS NULL 类同于字符串类型
3.2.3 时间类型属性筛选
名词解释
绝对时间：有明确开始和截止时间的一个固定时间范围
相对时间：相对于某个时间点，确定一个开始时间和截止时间的时间范围
相对当前时间点：相对于当前之前的一段时间范围，比如之前 1 小时
相对当前时间区间：相对当前的时间点，确定一个开始时间和截止时间当筛选的属性为时间类型时，可以看到如上图所示的判断类型，具体每个判断类型使用可参考如下：
绝对时间
> 如设置绝对时间在 2017-07-04 00:00 至 2017-07-11 00:00，则所选属性时间范围在此区间（包含区间端点）的数据会进入分析过程
相对当前时间点
> 如相对当前时间点在 1 天之内，则表示当前时间点减一天为起点，当前时间点为终点的时间区间。即 [当前时间点 - 1 天, 当前时间点]
> 如相对当前时间点 1 天之前，则表示当前时间点减一天为终点之前的时间区间。即 ( 无穷小时间, 当前时间点 - 1 天]
相对当前时间区间
> 如设置相对当前时间的过去 5 天到过去 3 天之内，则表示以当前时间点 - 5 天为起点，以当天时间点 - 3 天为终点的时间区间，即 [当前时间点 - 5 天,
当天时间点 - 3 天]
相对事件发生时间
此处以事件发生的时间锚点去设置时间区间的起点和终点，所以对于每一条需要判断的事件或用户数据，所对应判断的时间区间是不一样的。
> 比如我们想要看到购买事件发生前 5 分钟进行注册事件的用户数量时，可设置 注册时间 相对事件发生时间 在之前 5 分钟内。基于“用户注册后，立马购买
的商品是吸引用户注册的原因”这样一个假设，我们可以查看那类型商品比较容易吸引用户注册来购买。或者替换成优惠券，可查看那类型优惠券更容易吸 引
用户。
有值 & 没值
请参考字符串类型中，有值 & 没值的描述
3.2.4 布尔类型属性筛选当筛选的属性为布尔类型时，可以看到如上图所示的判断类型，具体每个判断类型使用如下：
为真
表示当选择属性值为 TURE 时，数据才会进入分析过程。
为假
表示当选择属性值为 FALSE 时，数据才会进入分析过程。
有值&没值
请参考字符串中，有值 & 没值的描述
3.2.5 带字典类型属性的筛选
在神策分析的元数据管理中，可以对设置 维度字典，对于已经设置 维度字典 的字段，筛选条件如下图，具体的判断字段使用可参考字符串类型中相应类
型。3.2.6 用户分群的筛选
用户分群分为普通分群和预测分群，在进行条件筛选时，对于选择普通分群，则判断条件选择跟布尔类型相同，表示用户是否在该分群之内。对于选择预测
分群，则判断条件与字典类型属性字段的筛选相同，这是因为判断一个用户是否属于预测分群并非 100% 确定的，而是分成几种可能性表述的。.属性筛选条件说明 v1.15
1. 什么是筛选条件
筛选条件是为了在我们取到的数据集中，通过设置一个条件进行过滤，获取我们最终想得到的子数据集进行分析。神策所有的分析功能中都有筛选条件的选
项，均可以实现根据事件的属性进行筛选或根据用户的属性进行筛选。
筛选条件可类比于 SQL 中的 where 条件语句
当使用用户筛选条件时， where 条件作用于 users 表；当使用事件筛选条件时， where 条件作用于 events 表
2. 使用流程
在神策所有的分析功能中，我们可以看到「筛选条件」、「触发限制条件`」等按钮时，代表此处可以对用户或事件进行筛选，参考上图中的标识，具体配置
流程如下：
1. 点击弹出筛选条件输入框，可以同时添加一个或多个筛选条件
2. 在 B 中选择筛选事件或用户的属性
3. 在 C 中选择属性的 判断类型 ，不同的属性类型拥有不同的 判断类型，不同 判断类型 的使用方法可参考第 3 部分
4. 在 D 选项中输入 判断值 后，分析结果即会根据输入条件进行筛选
3. 筛选条件分类
3.1. 按目标
筛选用户：筛选条件作用于用户表，只看符合筛选条件的那些用户；一般在用户属性上进行条件设置，或者选择用户分群获取符合分析条件的用户。
筛选事件：筛选条件作用于事件，只看符合筛选条件的事件；一般在事件属性上进行条件设置。3.2. 按数据类型
不管是为了筛选出不同用户或筛选不同事件，具体的每一个筛选条件的设置，都可以按其数据类型来了解。
3.2.1. 字符串类型属性筛选
当筛选的属性为字符串类型时，可以看到如上图中标识的判断类型，具体每个判断类型的使用可参考下表：
判断类型 类比 SQL 描述说明
等于 = 精确判断，只有选择的事件属性等于输入的判断值时，该事件才会才会进入分析过程；当判断值存
在多个时，事件属性值等于任意一个，该事件都会进入分析的数据集
不等于 != 精确判断，只有选择的事件属性不等于输入的判断值时，该事件才会才会进入分析过程；当判断值
存在多个时，事件属性值等于任意一个，该事件就不会进入分析过程
包含 LIKE "%$%" 匹配判断，当属性字段中包含判断值，该事件或用户就会进入分析过程
不包含 NOT LIKE "%$%" 匹配判断，与“包含”相反，当属性字段中包含判断值，该事件不会进入分析过程
不为空 Length($)>0 当属性字段中有值(字符串长度大于 0 )时，事件或用户才会进入分析过程
为空 ="" 当属性字段中值为空字符串时，事件或用户才会进入分析过程
没值 IS NULL 只有属性字段中值为 NULL 时，事件或用户才会进入分析过程
有值 IS NOT NULL 只有属性字段中值不为 NULL 时，事件或用户才会进入分析过程
正则匹配 匹配判断，符合条件的数据进入分析过程，具体请参考：正则表达式
正则不匹配 匹配判断，只有不符合正则条件的数据进入分析过程，具体请参考：正则表达式
3.2.2. 数值类型属性筛选当筛选的属性为数字类型时，可以看到如上图中标识的判断类型，具体每个判断类型的使用可参考下表：
判断类 类比表达式 描述说明
型
等于 = 类同于字符串类型
不等于 != 类同于字符串类型
小于 < 所选属性值小于判断值的事件才会进入分析过程
大于 > 所选属性值大于判断值的事件才会进入分析过程
区间 between . 所选属性值处于设置的判断值所形成的闭区间时，事件才会进入分析流程；如判断值设置为 10 和 100 时，所选属性值需要
and . 满足 [10,100] 区间
有值 IS NOT 类同于字符串类型
NULL
没值 IS NULL 类同于字符串类型
3.2.3. 时间类型属性筛选
名词解释
绝对时间：有明确开始和截止时间的一个固定时间范围
相对时间：相对于某个时间点，确定一个开始时间和截止时间的时间范围
相对当前时间点：相对于当前之前的一段时间范围，比如之前 1 小时
相对当前时间区间：相对当前的时间点，确定一个开始时间和截止时间当筛选的属性为时间类型时，可以看到如上图所示的判断类型，具体每个判断类型使用可参考如下：
绝对时间
如设置绝对时间在 2017-07-04 00:00 至 2017-07-11 00:00，则所选属性时间范围在此区间（包含区间端点）的数据会进入分析过
程
相对当前时间点
如相对当前时间点在 1 天之内，则表示当前时间点减一天为起点，当前时间点为终点的时间区间。即 [当前时间点 - 1 天, 当前时间
点]
如相对当前时间点 1 天之前，则表示当前时间点减一天为终点之前的时间区间。即 ( 无穷小时间, 当前时间点 - 1 天]
相对当前时间区间
如设置相对当前时间的过去 5 天到过去 3 天之内，则表示以当前时间点 - 5 天为起点，以当天时间点 - 3 天为终点的时间区间，即
[当前时间点 - 5 天, 当天时间点 - 3 天]
相对事件发生时间
此处以事件发生的时间锚点去设置时间区间的起点和终点，所以对于每一条需要判断的事件或用户数据，所对应判断的时间区间是不
一样的。
比如我们想要看到购买事件发生前 5 分钟进行注册事件的用户数量时，可设置 注册时间 相对事件发生时间 在之前 5 分钟内。基于
“用户注册后，立马购买的商品是吸引用户注册的原因”这样一个假设，我们可以查看那类型商品比较容易吸引用户注册来购买。或者
替换成优惠券，可查看那类型优惠券更容易吸引用户。
有值 & 没值
请参考字符串类型中，有值 & 没值的描述
3.2.4. 布尔类型属性筛选当筛选的属性为布尔类型时，可以看到如上图所示的判断类型，具体每个判断类型使用如下：
为真
表示当选择属性值为 TURE 时，数据才会进入分析过程。
为假
表示当选择属性值为 FALSE 时，数据才会进入分析过程。
有值&没值
请参考字符串中，有值 & 没值的描述
3.2.5. 带字典类型属性的筛选
在神策分析的元数据管理中，可以对设置 维度字典，对于已经设置 维度字典 的字段，筛选条件如下图，具体的判断字段使用可参考字符串类型中相应类
型。3.2.6. 用户分群的筛选
用户分群分为普通分群和预测分群，在进行条件筛选时，对于选择普通分群，则判断条件选择跟布尔类型相同，表示用户是否在该分群之内。对于选择预测
分群，则判断条件与字典类型属性字段的筛选相同，这是因为判断一个用户是否属于预测分群并非 100% 确定的，而是分成几种可能性表述的。书签及数据概览
每一个书签是一个的数据报表。一个概览是由多个书签组成。概览包含我的数据概览、预置概览两部分。本章主要介绍书签、数据概览、预置概览的功能。
2019-12-03_15-04-01_书签：每个书签都是通过分析模型建立的一个数据报表，可以根据需求添加到任意一个概览中。
我的概览：是根据业务需求，用户自己创建的概览。每个概览中可以添加多个书签。
基础数据概览：是根据神策数据全埋点，和用户的关键业务事件生成的多个概览。公共概览.公共概览 v1.16
概览中新增公共概览，「我的概览」的功能与 1.15 版本一致。
公共概览
原来预置概览的位置，更换为新增的「公共概览」，公共概览主要用于管理企业级需要共同关注的重要概览，打造企业的数据公共空间，由具有「管理公共
概览」权限的成员共同维护。原「预置概览」更名为「基础数据概览」可在「公共概览」中查看。
在公共概览可以进行创建、复制、排序等基础操作，为了使用的顺畅性，所有的功能操作方式和「我的概览」一致。同时，为了确保公共概览共享更加灵
活，在 1.16 版本中的共享设置里除了对某个成员授权查看外，还增加了对某个角色、某个职务的动态授权。
1、创建公共概览
当需要监测新的数据时，可以在左侧导航的「公共概览的基本操作设置入口」点击「+」按钮，创建一个全新的概览。如果有分组的需要，也可以在此创建新
的分组。新概览创建成功后，可以概览详情页的右上角，点击「+」按钮，添加已有的内容或使用分析模型新建一个分析板块。在 1.16 版本中，我们特别新增了「添
加描述」的组件，便于你将整个概览做分区，或者添加解读描述，让其他查阅者更好的理解你想传递的分析结果。
选择「从公共书签添加」，选择将已有的公共书签添加到概览中；
选择「新建组件」通过分析模型创建新的书签，随后可保存到公共概览中，从此入口创建的分析内容，仅可添加到「公共概览」中。
如有「公共概览管理」权限的成员，在各个分析模型中分析后进行保存时，可选择此分析结果保存为书签后，添加到「公共概览」或「我的概览」中。2、停止更新
当你的项目中概览数量较多时，影响性能导致查询缓慢时，可以将不再需要每日更新关注的概览「停止更新」，这样概览每日就不会再更新数据，占用计算
性能了。如业务变化，需要继续监测数据时，可在停止「停止更新」的操作位置，点击「自动更新」恢复每日的自动计算并缓存概览数据的功能，让用户查
看到最新的数据。
3、复制概览
为了企业能快速将已有的概览添加到「公共概览」，或让使用者可以快速使用他人的概览配置完成自己的相关分析工作。在 1.16 版本中，我们提供了「复制
概览」的功能，此功能适用于「我的概览」和「公共概览」。请注意：
场景库的「基础数据概览」是特殊的概览类型，目前暂不支持进行快速复制。
只有具有「公共概览管理权限」的成员方可复制已有概览后添加到「公共概览」中。
4、调整概览、概览组的排序，管理概览组
在左侧导航的「公共概览的基本操作设置入口」点击中间的「排序按钮」后可进行当前概览的排序。
为了你能便捷的排版概览，可多选概览后进行批量移动的操作。
在此弹窗中，支持鼠标按住「概览」或「分组」可直接进行排序拖动。
此外，鼠标 hover住具体「概览」或「分组」还可进行概览、分组的重命名等快捷操作。5、管理公共概览
在左侧导航的「公共概览的基本操作设置入口」的「最右侧的按钮」点击后可进入「公共概览管理」页面。在此列表中全面了解公共概览的共享设置、创建
信息。
支持搜索概览名称关键字进行检索
支持进行「分享设置」，通过此配置设置当前概览的可见范围：「仅有管理公共概览权限的成员可见」、「全体成员」、「指定成员」；在「指定
成员」中可以设置某些成员，或某些角色动态配置，或某些职务的动态配置。注：如果当前项目没有「职务信息」此处将不显示。你可以前往「成
员与角色」-「成员管理」-「职务管理」中添加符合需要的。随后是此职务的成员，均可按照此配置查看到对应的概览。
编辑操作，支持在此修改概览的名称、与分组设置
删除操作，请慎重使用。删除后，以前可查看此概览的成员，将不可查看；没有归属的书签可在「公共概览」-「从公共书签中添加」重新恢复使
用。
停止分享，操作后「仅有管理公共概览权限」的成员方可查看。
在「管理公共概览」的页面，支持勾选多个概览进行「批量设置」。
如果对当前选中概览需要批量增加新的可访问的成员，那么可使用「增加可访问成员」
如果你需要对当前选中的概览批量重新设置可访问成员的范围，那么可使用「重置分享设置」
批量删除，操作请慎重操作。注：如某位成员，对一个分组中所有概览都没有访问权限的话，那么该成员在查看公共概览时这个分组将不显示。
例如：运营数据概览组中有 3 张概览，每个概览的分享设置中都没有涵盖小明，那么当小明查看公共概览模块时，将无法查看到「运营数据概览组」。.公共概览 v1.17
1. 概述
公共概览主要用于管理企业级需要共同关注的重要概览，打造企业的数据公共空间，由具有「管理公共概览」权限的成员共同维护。（原 1.13 - 1.15 版本
中的「预置概览」更名为「基础数据概览」仅可在「公共概览」中查看。）
在公共概览可以进行创建、复制、排序等基础操作，为了使用的顺畅性，所有的功能操作方式和「我的概览」一致，使用说明请参考「我的概览」中的明细
介绍。
2. 如何使用公共概览
「公共概览」中的基本操作与「我的概览」中的均一致，如需了解请查看上一节「如何使用概览」的明细介绍。接下来主要介绍一下「公共概览」中区别于
「我的概览」的功能。
查看基础功能使用说明 >
点击切换到「公共概览」后，底部的操作将仅与公共概览有关，具有「管理公共概览」权限的成员方可看到此管理功能。
2.1. 创建公共概览
当需要监测新的数据时，可以在左侧导航的「公共概览的基本操作设置入口」点击「+」按钮，创建一个全新的概览。如果有分组的需要，也可以在此创建新
的分组。2.2. 调整概览、概览组的排序，管理概览组
在左侧导航的「公共概览的基本操作设置入口」点击中间的「排序按钮」后可进行当前概览的排序。
为了你能便捷的排版概览，可多选概览后进行批量移动的操作。
在此弹窗中，支持鼠标按住「概览」或「分组」可直接进行排序拖动。
此外，鼠标 hover住具体「概览」或「分组」还可进行概览、分组的重命名等快捷操作。2.3. 管理公共概览
在左侧导航的「公共概览的基本操作设置入口」的「最右侧的按钮」点击后可进入「公共概览管理」页面。在此列表中全面了解公共概览的共享设置、创建
信息。
支持搜索概览名称关键字进行检索
支持进行「分享设置」，通过此配置设置当前概览的可见范围：「仅有管理公共概览权限的成员可见」、「全体成员」、「指定成员」；在「指定
成员」中可以设置某些成员，或某些角色动态配置，或某些职务的动态配置。注：如果当前项目没有「职务信息」此处将不显示。你可以前往「成
员与角色」-「成员管理」-「职务管理」中添加符合需要的。随后是此职务的成员，均可按照此配置查看到对应的概览。
编辑操作，支持在此修改概览的名称、与分组设置
删除操作，请慎重使用。删除后，以前可查看此概览的成员，将不可查看；没有归属的书签可在「公共概览」-「从公共书签中添加」重新恢复使
用。
停止分享，操作后「仅有管理公共概览权限」的成员方可查看。在「管理公共概览」的页面，支持勾选多个概览进行「批量设置」。
如果对当前选中概览需要批量增加新的可访问的成员，那么可使用「增加可访问成员」
如果你需要对当前选中的概览批量重新设置可访问成员的范围，那么可使用「重置分享设置」
批量删除，操作请慎重操作。
注：如某位成员，对一个分组中所有概览都没有访问权限的话，那么该成员在查看公共概览时这个分组将不显示。
例如：运营数据概览组中有 3 张概览，每个概览的分享设置中都没有涵盖小明，那么当小明查看公共概览模块时，将无法查看到「运营数据概览组」。新建一个概览.新建一个概览 v1.13
1. 组件的创建流程
1.1. 新建组件
在A 处或B 处点击“新建组件”，选择需要添加到概览的分析模型（事件分析、漏斗分析、留存分析、分布分析和属性分析），进入对应的分析页面，配置好
分析条件后，点击 C 处“保存”，在设置框中选择需要展现的图表和尺寸，点击 D 处完成新建。
1.12 版本，在概览中新增了渠道对比组件，点击渠道对比组件使用说明查看1.1.1. 2.2 从书签添加
点击 A 处，可在列表中选择需要添加到概览的书签（需要在分析页面先保存为书签），设置后，完成添加。2. 如何修改组件？
2.1. 在设置页面修改
鼠标悬浮于自己创建的组件上，右上角现会出现“更多”按钮，点击“更多”下拉框中的“设置”，出现设置弹窗。
在 A 处修改书签/组件名称，B 处选择时间范围，C 处选择聚合时间单位（合计、按分钟、按小时、按天、按周和按月），D 处选择显示的指标，1.11 版本
最多支持展示 3 个指标，E 处选择要显示的分组，F 处可填写备注信息，比如创建该组件的原因、对相关指标的解释或者需要同事注意的地方等，G 处是组
件展现的类型：线图、柱图、环图、累计图、表格和数值，根据实际场景选择不同的图表展示类型。比如每日活跃用户数、新增用户数或今日销售金额等关
键指标，适合数值类型的展示。H 处选择组件的尺寸，小尺寸、中尺寸和大尺寸。需要注意的是，在设置页面更新的属性会同步存在于其他概览的书签/组
件，尺寸除外。2.2. 在分析页面修改
从组件或书签处进入分析页面，修改配置后，可点击 A 处保存当前修改，点击 B 处可以复制当前分析条件并另存为新的书签，C 处可将书签快速添加到不同
的概览中（取消勾选可将书签/组件从概览中删除）。对于他人创建的组件，不可修改其分析条件，但可以通过另存为的方式创建新的书签。2.3. 在概览页面修改
在 A 处可快速调整组件的尺寸，该尺寸只在当前概览中生效，不影响在其他概览中的同一书签/组件。若分析条件或图表类型不支持某类尺寸，则其置灰不
可点击。
3. 如何全局查看概览组件的时间？
书签/组件本身拥有时间属性，可在 A 处选择临时时间范围查看概览中所有的组件，关闭后，各组件展现本身时间。4. 概览分组
1.10 及其以后版本，提供了概览分组功能，当前概览较多时，可以对概览进行分组、排序，以便更快的找到自己想看的概览。A. 自创概览默认出现在概览列表顶部。
B. 他人分享的概览默认出现在“分享给我的概览”分组中。
C. 点击“创建新的概览”按钮可以创建新的概览。
D. 点击“创建新的分组”按钮可以创建新的分组。
E. 鼠标移到分组上会出现“编辑分组”按钮，点击后会弹出编辑分组面板。点击“删除”按钮会弹出删除分组面板。
点击“删除分组和概览”按钮，将删除分组，并且删除分组下的所有自创概览，他人分享的概览将转移到“分享给我的概览”分组内。
点击“删除分组，保留概览”按钮，将删除分组，自创概览将转移到概览列表顶部、他人分享的概览将转移到“分享给我的概览”分组内。
F. 点击“展开收起”按钮可以将分组展开或收起。
拖拽分组可以调整分组的顺序，拖拽概览可以调整概览在分组内的顺序或将概览从一个分组移动到另一个分组内。5. 环比同比规则
环比同比规则如下：
时间粒度 环比 同比
按分钟 对比上分钟 对比上一小时同期
按小时 对比上小时 对比昨天同期
按天 对比昨天 对比上周同期
按周 对比上周 无同比按月 对比上月 对比去年同期
如果选择过去的时间段，比如时间选择 2017 年 3 月 1 日至 2017 年 3 月 10 日，按月查看，环比为 2017 年 3 月整月的数据对比上月整月 2017 年 2 月
的数据，同比为 2017 年 3 月对比去年同期 2016 年 3 月的数据。
6. 概览性能设置
1.12 支持在界面调整概览性能，选择合适的配置以提高概览的展现效率。
6.1. 典型场景
接入数据量（每天更新 10 亿条以上）较大的客户，若想优化查询性能，可将更关心趋势呈现的指标统一放到某概览中，调整其概览性能，减少查
询时间。
机器配置与数据接收量不匹配的客户，例如数据量为 10 万日活，配置为单机高配（单机高配的标准为 6 万日活），此时查询通常较慢。可调整概
览性能以减少查询时间。当然，最好的建议是将机器配置调整为与数据量匹配的状态。
6.2. 具体操作点击概览右上角设置按钮，选择 A 处“概览性能”，弹出性能设置页面（只有自己创建的概览有该入口）。
B 处选择计算精度，默认选择“完全精确”。
完全精确：概览中所有数据完全精确计算；
仅合计值精确：对概览中所有去重数的合计值近似计算，其他数据精确计算；
全部近似：对概览中所有去重数近似计算，其他数据精确计算。
C 处选择数据更新时间，默认选择实时。
实时：数据实时更新；
每日固定时间更新：一般为每日凌晨 3 点，具体以后端设定的时间为准。
D 处调整抽样系数：默认为对全量数据计算。可拖拽或点击横滑杆调整抽样系数。
点击 E 处确定按钮生效，设置只对本概览有效。若概览性能为非默认配置，设置按钮会呈现激活状态，以作提示。
7. 邮件发送设置
1.8 及其以后版本，支持在系统界面配置邮件发送。只能给自己创建的数据概览配置邮件发送。
首先选择一个自己创建的数据概览，然后如上图点击右上方的“邮件图标”，会弹出一个对话框，在对话框中可以完成邮件配置。
7.1. 设置发件邮箱
数据概览会从这个邮箱发出，因为私有部署以及数据安全等原因，神策分析不提供默认的发送邮箱。设置成功后，同一个账号下所有数据概览的发送都使用
这个邮箱。首次使用此功能，点击“+ 设置发件邮箱”，在弹出的对话框中完成配置。填写“邮箱地址”后，点击“自动识别 SMTP 地址”，系统会尝试探测“邮箱 SMTP 地址”、“端口”、“SSL 连接”，并自动填充。如果探测失败，请咨询贵司的邮
件服务提供商。
如果是第一次配置“发件邮箱”，保存成功后，请点击“测试发送”进行测试，确保邮件可以正常发送。
7.2. 设置发送时间
邮件发送任务在设置的“发送时间”点例行启动，但最终发送时间可能会延迟 2 分钟 至 15 分钟，因为获取数据、渲染数据的时间无法确定。如果 10 分钟无
法获取完整的数据概览数据，邮件会发送失败。7.3. 设置报告生成时间举例说明：数据概览里时间选择“昨天”，邮件配置里“发送时间”设置“每天 09:00”。当前是 2017年7月24日，邮件会在 2017年7月24日9点发出，站在这
一天来看不同的“报告生成时间”对数据的影响。
实时生成：数据概览里设置的“昨天”为 2017年7月23日，与现实中的感觉一致。数据概览里数据也是 2017年7月23日的数据。
发送前 10 小时：数据概览里设置的“昨天”为 2017年7月22日，数据概览里数据也是 2017年7月22日的数据。发送邮件时“当前时间”不再是当时的时间， 而
是从 2017年7月24日9点向前退 10 小时，“当前时间”变为 2017年7月23日23时。
7.4. 测试发送
配置完成后，可以点击“测试发送”，确保邮件可以正常发送，确保数据概览内容正确。.新建一个概览 v1.17.书签及数据概览 v1.13
快速了解数据概览
对于一些常用的、周期性指标、数据，可以保存为书签，便于查询。同时可以将指标作为可视化组件，添加到数据概览中。
1. 书签
书签是帮助您管理常用查询的工具。书签会保存当前视图中的具体查询，包含相应的分组和筛选条件，但是不会保存查询时间范围。1.6 版本之前保存书签时
需要选择“默认显示时间范围”，在 1.6 及其以后版本中不再需要选择“默认显示时间范围”，时间范围设置移到数据概览界面。
1.1. 保存书签
在每种分析视图的顶部，可以找到报表的工具栏，包括：
1. 保存为书签；
2. 刷新数据；
3. 将当期查询结果导出为 CSV 文件。
点击“保存为书签”，可以将当前查询条件（除时间范围）保存为一个书签。
1.1.1. A. 书签名
您的书签会有一个默认生成的名字。请根据使用需要给书签起一个友好的名称。
1.1.2. B. 同时添加到数据概览
一个书签可以添加到一个或多个「数据概览」中，以可视化组件的方式方便浏览。详情请见下文2. 数据概览。
1.2. 打开书签
保存过的书签，可以通过侧边栏的「书签」列表打开或管理。1.3. 编辑书签
编辑书签有两个方面的含义：
1. 编辑书签的名称、默认查询时间范围或添加到哪个数据概览；
2. 编辑书签所保存的查询条件。
通过左侧书签列表，可以快捷地编辑#1。
而通过打开书签，你可以修改某些查询条件，并点击左上角的当前书签名，保存#1和#2两方面的修改。
1.4. 删除书签
点击「编辑书签」弹出框左下角的「删除书签」按钮，可以删除某个书签。如果该书签属于某个数据概览，则会一并从数据概览中移除。
1.5. 将当前查询另存为新书签
如果当前视图已经存为某个书签，而您希望将当期查询保存为新书签的时候，可以在「编辑书签」弹出框中选择“保存为新书签”，并配置新相应选项。当前
查询和选项将会被保存为一个新书签。.书签及数据概览 v1.15
概览包含预置概览、我的概览两部分，而书签是组成概览的数据报表。
预置概览：是根据神策数据全埋点，和用户的关键业务事件生成的多个概览。 主要包含产品整体使用情况；用户在不同渠道、版本方向的流量、转
化；用户的活跃、留存；用户地址位置、性别、操作系统等特征分布；您定义的关键事件的发生次数、人数、分布等情况五个方面
我的概览：是根据业务需求，用户自己创建的概览。每个概览中可以添加多个书签。
书签：每个书签都是通过分析模型建立的一个数据报表，可以根据需求添加到任意一个概览中。
1. 预置概览
神策分析 1.13 版本的预置概览，请参考这篇文档基础数据概览。 神策分析 1.15 版本中，新增按渠道设置预置概览使用的事件、新增「用户生命周期」概
览；
预置概览是根据神策数据全埋点，和用户的关键业务事件生成的多个概览。可以分为以下五类：
整体概览： 从产品整体的使用情况出发，自动生成基础的数据指标；可以对产品整体的使用情况有基础了解。
用户分析： 从用户的访问和粘性出发，可以观察出产品在用户访问、回访等方面的趋势变化，清楚地了解用户对产品的粘性和沉浸程度。
终端数据： 从获客渠道和版本的方向出发，根据不同渠道、不同的版本生成一些可以了解渠道优劣的指标，可以清晰的观察每个渠道的流量、转化
等情况。
渠道分析 根据地址位置、性别、操作系统等一些基础属性，将用户进行分组，方便您更加了解用户的分布占比情况。
关键事件： 根据选择的事件和属性，为您生成该事件的发生次数、人数、分布等数据指标，可以了解整体的用户转化以及收益相关的数据情况。
1.1. 如果是admin：可以设置预置概览
点击预置概览模块下方的「生成预置概览」按钮，开始设置预置概览
1. 设置共包含「通用」、「事件转化」两部分， 1）设置新增通用模块 设置通用模块可以查看「整体概览」、「用户分析」、「终端数据」、「渠道分析」
等神策为您内置的多角度概览；
采用全埋点的用户，默认采用全埋点的事件，可以根据业务调整事件；
未采用全埋点的事件，需要手动选择使用时长、浏览、点击、浏览深度、激活、崩溃等事件当设置「用户生命周期」中的用户活跃、新用户标识时，预置概览-整体概览中将新增「用户生命周期」概览。计算新用户、连续活跃用户、回流用户、沉默
用户、流失用户、流入流出比等指标。
您也可以点击右上角的「过去3天」，切换查看过去3、7、15天的数据
如果需要修改生命周期概览数据的更新周期，点击右上角的「…」，可以选择按天、周、月进行更新，也可以自定义更新时间。
2）设置事件转化模块 设置选择关键转化的事件，神策会根据您选择的事件，自动生成与该指标相关的一些数据指标，帮助您分析该事件的发生情况 选择
「事件转化」，添加关键事件，支持添加全部的事件；可以不添加属性，若添加，需要添加数值类型的属性，神策会使用该属性，进行总计，人均等指标的
计算。
1.2. 如果是分析师角色：可以查看预置概览
如需重新设置预置概览，请联系admin修改。
2. 我的概览
「我的概览」模块是根据业务需求，您自己创建的概览。在「我的概览」模块，可以根据需求对您创建的概览进行管理。
2.1. 创建概览
当需要监测新的数据时，可以创建一个新的概览。点击我的概览模块下方的「+」按钮，填写概览名称，并选择概览所在的分组，点击确定即创建了一个新的
空白概览。可以点击右上角的「+」按钮，选择「从书签添加」，选择将已有的书签添加到概览中； 也可以选择「新建组件」通过分析模型重新创建书签，保存到概览
中。
2.2. 复制概览
当需要的概览与已有概览内容相似时，为了更便捷的创建概览，神策支持复制概览。2.3. 管理我的概览
点击我的概览模块下方的「分享」按钮，进入管理我的概览页。可以查看到概览所属的分组、概览分享给哪些用户、概览的创建人，还可以操作删除概览、
分享概览。2.3.1. 删除概览：
当概览中的数据不再需要关注时，点击「删除」，删除对应概览。
2.3.2. 分享概览：您创建的概览可以分享给其他团队成员使用。
选中概览后，点击「分享设置」 ，选择分享给「全部成员」、「指定团队成员」。分享成功后，其他成员会在概览模块「分享给我的概览」中查
看。也可以勾选多个概览，批量分享给其他成员。当自己创建的概览，已经分享给别人后，因业务调整不再需要分享时，点击停止分享，概览就只有自己可见了。
2.4. 调整概览、概览组的排序，管理概览组
点击我的概览模块下方的「 」按钮，即可进入排序管理，调整概览、概览组的顺序，管理概览组了。2.4.1. 概览
当重要的概览排序靠后时，可以直接拖动到靠前的位置；勾选多个概览时，也可以批量添加概览到同一概览组中哦。
2.4.2. 概览组
当概览数量较多时，将概览移动到不同的概览组中，更加方便查看需要的概览。
添加概览组：点击添加分 组，就可以添加一个概览组了。例如「用户转化」，就可以作为一个分组。
修改概览组名称：已经创建好的概览组，可以点击「重命名」修改组的名称
调整概览组顺序：当最想看的概览组不在靠前的位置时，可以直接拖动「概览组」到想放到顺序
删除概览组：当不需要某个概览组时，可以点击「删除」，删除对应概览组。组中的概览将移入「数据概览组」中2.5. 管理别人「分享给自己」的概览
当别人分享的概览，你并不需要关注时，你可以将概览挪到「隐藏概览组」中，隐藏概览组中的概览默认收起，让你更加方便的只查看需要关注的概览。
3. 书签
书签是帮助您管理常用查询的工具。书签模块包含您通过分析模型建立的所有数据报表，可以根据需求添加到任意一个概览中，也可以直接在书签模块查看
您创建的书签。 书签模块的入口原来在神策系统左下角，1.15 版本移动到顶部导航栏。在书签模块可以对所有书签进行新建、查看、编辑、删除等管理：
3.1. 新建书签
当想创建新的书签时，点击右上角的「新建书签」，然后选择你要通过哪个分析模型。
进入分析模型并设置筛选条件后，点击「存为书签」，就成功创建一个书签了。
3.2. 查看书签
当您想查看书签的具体筛选条件或数据时，点击书签列表中对应书签，就会进入到分析模型，就可以查看筛选条件和具体的数据结果了。如果修改了书签的筛选条件查看数据，点击「另存为」可以保存为新的书签；点击「保存修改」可以更新当前书签。
3.3. 编辑书签
当想修改书签的名称，点击「编辑」修改书签的名称即可。3.4. 删除书签
当不需要某个书签时，点击「删除」就可以删除书签了。书签一经删除后无法恢复，请谨慎操作。预置概览.基础数据概览 v1.16
1. 基础数据里都有哪些信息？
基础数据概览是基于神策数据全埋点和少量用户自定义，自动生成的数据概览群。 大体上可以分为以下五类：
整体概况：从产品整体的使用情况出发，自动生成基础的数据指标；可以对产品整体的使用情况有基础了解。
用户获取：从获客渠道和版本的方向出发，根据不同渠道、不同的版本生成一些可以了解渠道优劣的指标，可以清晰的观察每个渠道的流量、转化
等情况。
活跃与留存：从用户的访问和粘性出发，可以观察出产品在用户访问、回访等方面的趋势变化，清楚地了解用户对产品的粘性和沉浸程度。
事件转化：根据选择的事件和属性，为您生成该事件的发生次数、人数、分布等数据指标，可以了解整体的用户转化以及收益相关的数据情况。
用户特征：根据地址位置、性别、操作系统等一些基础属性，将用户进行分组，方便您更加了解用户的分布占比情况。
2. 如何添加和设置基础数据概览？
角色权限中，具有「管理公共概览」权限角色的成员均可从场景库添加「基础数据概览」到「公共概览」中。
无「管理公共概览」权限的成员仅可查看此场景库的介绍，如需使用可以联系有权限的成员进行添加。
基础数据概览，由多组概览组成，在公共概览中仅可进行整体排序，且暂不支持复制和共享设置。
在场景库的使用介绍中查看如何添加并设置「基础数据概览」。
3. 指标详细解析
3.1. 类别1 : 整体概况
实时数据
每个小时的产品实时数据，帮助您了解产品目前的实时情况
实时访问人数
产品的实时访问人数，按小时更新
实时新用户人数
产品的实时新用户访问人数，按小时更新
实时收益事件的发生次数
产品的实时收益事件的发生次数，按小时更新
若您想新增监测的事件，请联系管理员进行设置添加
概况
产品整体的使用情况，包括用户量、访问情况、留存等，帮助您对产品整体指标有一个大致的了解
累计用户量
产品上线至今的累计用户量
昨日新增用户量
昨日的全部访问人数/次数
昨日的全部访问的人均次数/时长/深度
Web 端指标，使用 session (session_default) 进行计算
App 端指标使用 $退出App 事件进行计算
新老用户访问占比
每日新老用户的分布情况
新用户/全部用户的7日留存
起始和后续事件都为用户进行页面访问
各页面的访问次数分布
基于 全埋点的 $App 浏览页面 和 $Web 浏览页面 中的页面标题属性进行分组
访问终端分布
按照访问的操作系统分组
3.2. 类别2 : 用户获取
渠道访问
每个渠道的用户的使用情况，包括渠道中新用户的占比、留存等，帮助您了解产品在获客层面上的优势与不足；其中 App 的渠道数据，会根据
iOS，Android 进行细分
新增用户量
全部新用户数量，包括自然流量和渠道流量
渠道新增用户量
仅计算渠道流量新增用户数人均访问时长
Web 端指标，使用 session (session_default) 进行计算
App 端指标使用 $退出App 事件进行计算
异常流量
App 异常流量，定义为打开5秒内即进行关闭操作的访问行为
版本数据
App 每个版本的使用情况，帮助您了解在产品升级的过程中，是否在活跃和留存方面有所改善
版本访问流量
人均访问时长
各版本留存
各版本的用户7日留存
3.3. 类别3 : 活跃与留存
访问流量
产品的每日访问数据，指标集中在在新老用户的访问行为上，提供访问次数、时长、次数分布、访问时段高峰等指标，帮助了解新老用户在使用产
品时的一些行为特征
访问用户数
新老用户访问占比
新老用户人均使用时长
新老用户启动/访问次数
每日/每周启动时段
用户每日访问产品的时段分布
用户每周访问产品的星期分布
用户留存
提供用户7日，次日，次周，次月留存的数据，帮助您了解新老用户的使用粘性
7日留存/流失
次日留存/流失
次周留存/流失
次月留存/流失
3.4. 类别4 : 事件转化
事件转化
用户自定义关键事件，神策会自动生成该事件的发生次数、人数以及分布情况
新老用户事件发生次数/人数/人均次数
事件次数的分布
收益类事件转化
用户自定义收益类事件，神策会自动生成该事件的发生次数、人数以及分布情况，会根据您选择的数值类型属性，计算该数值的总值、人均值以及
次均值
新老用户收益事件发生次数/人数/人均次数
新老用户收益事件
3.5. 类别5 : 用户特征
用户特征
访问省份分布
访问城市分布
访问性别分布
访问操作系统分布
新老用户占比
4. 常用问题解答
Q: 什么权限的用户可以设置预置概览？
A: 管理员账户可以进行预置概览的设置。
Q: 如何修改管理看板里的指标信息？
A: 若您想在事件转化中增加新的事件，可以通知管理员进行添加设置。若您想在其他的模块中添加指标，神策分析目前不支持这种操作。
Q: 有些模块内的指标不准确怎么修正？
A: 目前大部分的指标神策分析都是使用全埋点数据进行计算统计的，暂时不支持用户自定义的修正，当然，您可以联系开发人员进行代码配置的修
改。Q: 如何复制指标？
A: 您可以点击该指标进入分析模型中，点击保存即可保存到自己的书签中，在自己创建的概览中添加该书签即可。
Q: 如何关闭预置概览？
A: 需要管理员账号在公开共享中，设置为关闭即可；关闭后，非管理员账号都不会展示预置概览模块。
Q: 预置概览能帮助我解决什么问题？
A: 预置概览中的指标按照获客 - 流量 - 转化进行分类，可以帮助您系统全面的了解产品整体的健康情况。若您想在此基础上进行一些自定义的指
标，可以以某个指标为模板进行自定义加工。
5. 基础计算事件
计算活跃类
App 会使用：$AppViewScreen ，$AppStart，$AppEnd 等全埋点事件进行计算
Web 会使用：$pageview 等全埋点事件进行计算
计算会话时长类
App 会使用：session_default_1 该 session 进行计算
Web 会使用：session_default 该 session 进行计算
若您的项目中没有以上该事件，可以开启全埋点进行采集
session 类的事件可以手动构建session，保证名称和 session_default_1 / session_default 一致即可。.预置概览 v1.13
1. 预置概览里都有哪些信息？
预置概览是基于神策数据全埋点和少量用户自定义，自动生成的数据概览群。 大体上可以分为以下五类：
整体概况：
从产品整体的使用情况出发，自动生成基础的数据指标；可以对产品整体的使用情况有基础了解。
用户获取：
从获客渠道和版本的方向出发，根据不同渠道、不同的版本生成一些可以了解渠道优劣的指标，可以清晰的观察每个渠道的流量、转化等
情况。
活跃与留存：
从用户的访问和粘性出发，可以观察出产品在用户访问、回访等方面的趋势变化，清楚地了解用户对产品的粘性和沉浸程度。
事件转化：
根据选择的事件和属性，为您生成该事件的发生次数、人数、分布等数据指标，可以了解整体的用户转化以及收益相关的数据情况。
用户特征
根据地址位置、性别、操作系统等一些基础属性，将用户进行分组，方便您更加了解用户的分布占比情况。
2. 如何添加和设置预置概览？
2.1. 非管理员账号
非管理员账号只有查看权限，若您的看板没有内容，可以联系管理员进行设置
未添加 ''预置概览''
该状态为管理员未配置预置概览，或管理员未开启预置概览的分享权限已添加 ''预置概览''
该状态为预置概览已配置完成的状态添加新的关键事件
若您想添加新的关键事件，请联系管理员进行设置添加
浏览看板内容
点击看板名称，即可浏览看板的数据指标。
数据指标不支持修改和删除，若您想进行修改，可以先将该指标保存到自己的书签中，再进行修改，加入到自己的概览中查
看。
2.2. 管理员账号
Step1 : 设置预置概览信息
点击 ''生成预置概览'' 进行预置概览生成Step2 : 预置概览设置引导
引导页 - 1
点击开始使用，进入下一步
引导页 - 2
点击生成模板，进入下一步引导页 - 3
设置选择关键事件，神策会根据您选择的事件，自动生成与该指标相关的一些数据指标，帮助您分析该事件的发生情况
添加事件
支持添加全部的事件
添加属性
可以不添加属性
若添加属性，需要添加数值类型的属性，神策会使用该属性，进行总计，人均等指标的计算。
全部可见
关闭，该项目中的其他用户将不展示预置概览模块
开启，该项目中的全部用户都会同步您的设置结果
Step3 : 修改预置概览预置概览的设置
管理员账户可以在导航中，看到设置按钮，点击设置按钮即可进入设置页面修改关键事件
目前支持修改、添加、删除关键事件
修改是否全部可见
关闭，全部用户都会关闭预置概览模块
开启，全部用户同步您设置的预置概览指标3. 指标详细解析
3.1. 类别1 : 整体概况
实时数据
每个小时的产品实时数据，帮助您了解产品目前的实时情况
实时访问人数
产品的实时访问人数，按小时更新
实时新用户人数
产品的实时新用户访问人数，按小时更新
实时收益事件的发生次数
产品的实时收益事件的发生次数，按小时更新
若您想新增监测的事件，请联系管理员进行设置添加
概况
产品整体的使用情况，包括用户量、访问情况、留存等，帮助您对产品整体指标有一个大致的了解
累计用户量
产品上线至今的累计用户量
昨日新增用户量
昨日的全部访问人数/次数
昨日的全部访问的人均次数/时长/深度
Web 端指标，使用 session (session_default) 进行计算
App 端指标使用 $退出App 事件进行计算
新老用户访问占比
每日新老用户的分布情况
新用户/全部用户的7日留存
起始和后续事件都为用户进行页面访问
各页面的访问次数分布
基于 全埋点的 $App 浏览页面 和 $Web 浏览页面 中的页面标题属性进行分组
访问终端分布
按照访问的操作系统分组
3.2. 类别2 : 用户获取
渠道访问
每个渠道的用户的使用情况，包括渠道中新用户的占比、留存等，帮助您了解产品在获客层面上的优势与不足；其中 App 的
渠道数据，会根据 iOS，Android 进行细分
新增用户量
全部新用户数量，包括自然流量和渠道流量
渠道新增用户量
仅计算渠道流量新增用户数
人均访问时长
Web 端指标，使用 session (session_default) 进行计算
App 端指标使用 $退出App 事件进行计算
异常流量
App 异常流量，定义为打开5秒内即进行关闭操作的访问行为
版本数据
App 每个版本的使用情况，帮助您了解在产品升级的过程中，是否在活跃和留存方面有所改善
版本访问流量
人均访问时长
各版本留存
各版本的用户7日留存
3.3. 类别3 : 活跃与留存
访问流量产品的每日访问数据，指标集中在在新老用户的访问行为上，提供访问次数、时长、次数分布、访问时段高峰等指标，帮助
了解新老用户在使用产品时的一些行为特征
访问用户数
新老用户访问占比
新老用户人均使用时长
新老用户启动/访问次数
每日/每周启动时段
用户每日访问产品的时段分布
用户每周访问产品的星期分布
用户留存
提供用户7日，次日，次周，次月留存的数据，帮助您了解新老用户的使用粘性
7日留存/流失
次日留存/流失
次周留存/流失
次月留存/流失
3.4. 类别4 : 事件转化
事件转化
用户自定义关键事件，神策会自动生成该事件的发生次数、人数以及分布情况
新老用户事件发生次数/人数/人均次数
事件次数的分布
收益类事件转化
用户自定义收益类事件，神策会自动生成该事件的发生次数、人数以及分布情况，会根据您选择的数值类型属性，计算该数
值的总值、人均值以及次均值
新老用户收益事件发生次数/人数/人均次数
新老用户收益事件
3.5. 类别5 : 用户特征
用户特征
访问省份分布
访问城市分布
访问性别分布
访问操作系统分布
新老用户占比
4. 常用问题解答
Q: 什么权限的用户可以设置预置概览？
A: 管理员账户可以进行预置概览的设置。
Q: 如何修改管理看板里的指标信息？
A: 若您想在事件转化中增加新的事件，可以通知管理员进行添加设置。若您想在其他的模块中添加指标，神策分析目前不支持这种操作。
Q: 有些模块内的指标不准确怎么修正？
A: 目前大部分的指标神策分析都是使用全埋点数据进行计算统计的，暂时不支持用户自定义的修正，当然，您可以联系开发人员进行代码配置的修
改。
Q: 如何复制指标？
A: 您可以点击该指标进入分析模型中，点击保存即可保存到自己的书签中，在自己创建的概览中添加该书签即可。
Q: 如何关闭预置概览？
A: 需要管理员账号在公开共享中，设置为关闭即可；关闭后，非管理员账号都不会展示预置概览模块。
Q: 预置概览能帮助我解决什么问题？
A: 预置概览中的指标按照获客 - 流量 - 转化进行分类，可以帮助您系统全面的了解产品整体的健康情况。若您想在此基础上进行一些自定义的指
标，可以以某个指标为模板进行自定义加工。
5. 基础计算事件
计算活跃类App 会使用：$AppViewScreen ，$AppStart，$AppEnd 等全埋点事件进行计算
Web 会使用：$pageview 等全埋点事件进行计算
计算会话时长类
App 会使用：session_default_1 该 session 进行计算
Web 会使用：session_default 该 session 进行计算
若您的项目中没有以上该事件，可以开启全埋点进行采集
session 类的事件可以手动构建session，保证名称和 session_default_1 / session_default 一致即可。渠道对比组件使用说明.渠道对比组件使用说明 v1.13
快速了解渠道对比组件
1. 渠道对比组件可以提供的信息
渠道对比组件可以帮助您自动生成以下指标：
网页类渠道指标
不同渠道网站每日的访问次数、人数
不同渠道网站每日的新用户访问次数、人数
不同渠道网站每日的新用户次日留存
App 类渠道指标
不同渠道 App 的每日激活量
不同渠道 App 的每日人均使用次数、人均使用时长
不同渠道 App 的每日的新用户次日留存
通用指标
不同渠道指定事件的发生次数、触发用户数、收益金额等自定义指标
2. 渠道对比组件的作用
渠道对比组件可以快速提供以下信息：
根据访问用户量，新用户占比等指标，可以判断出哪个渠道的流量大，新用户占比高
配合收益相关的事件，可以快速计算出每个渠道的投资回报率（ ROI ）
根据留存，使用时长等指标，可以比较出哪个渠道的用户粘性好，产品贴合度高
通过以上指标的对比，可以对接入的渠道有较为具体的认知，清晰的判断出哪些渠道是明星渠道，需要增加投放力度；哪些渠道是需要减少投放的决定。
例子：渠道对比组件示例（数据都为模拟数据）
信息1：
从图中数据可以看出，该产品每日的访问来源主要由36kr，今日头条，地推，微信，百度和总体。
信息2：
其中百度的流量最大，为332人；36kr和今日头条渠道的新用户占比最多，为100%。 若您关注流量的大小，那么百度就是您最优秀
的渠道；若您关注拉新能力，那么36kr和今日头条都是不错的选择。
信息3：
我们可以从新用户的次日留存，来得知用户在使用后对产品的整体感受，同时也可以侧面反映出推广的用户贴合度。 如果留存率很高
的话，则证明该渠道推广的用户更符合您推广的产品定位，用户质量更为优质。
信息4：
目标事件，示例中选择支付订单作为目标事件，可以观察出每个渠道新用户发生支付订单的人数，支付产生的金额。 若您的公司比较
关注用户的粘性，那么这里可以设置为一些与粘性相关的事件（比如：发帖，收藏等）；若您的公司关注营收，那么这里可以设置为
一些收益相关事件（比如：支付，成单等）3. 配置渠道组件
3.1. 添加渠道组件
Step1 ：在概览中选择 新建组件
Step2 ：在弹出的窗口中，选择渠道对比组件
Step3 ：系统会根据您的埋点情况，自动为您生成渠道对比组件3.2. 设置渠道组件
3.2.1. 设置入口
点击渠道对比组件右上角的更多按钮，可以进行组件的设置和删除
3.2.2. 基础设置
支持切换 App 和 Web 的渠道统计
支持自定义切换渠道标识属性3.2.3. 高级设置
目标转化事件开关，可以控制整个组件中是否展示目标事件模块
选择目标转化事件，建议选择与收益相关的事件
支持添加目标转化事件的属性，建议选择收益金额，可以直观的观察出每个渠道的盈利能力4. 渠道组件的指标解释及计算规则
渠道组件的数据是基于全埋点的采集数据进行生成的，需要产品接入神策的全埋点（参考说明：Web 全埋点，Android 全埋点，iOS 全埋点）。
web 的数据基于 $Web浏览页面（$pageview）进行每日访问人数，访问次数的计算；
app 的数据基于 $APP浏览页面（$AppViewScreen）进行每日访问人数，访问次数的计算
是否为新用户，基于事件属性中的是否首日访问（$is_first_day）进行判断
用户的注册渠道，默认为用户属性中的 广告系列来源（$utm_source）作为标识，进行用户标记
4.1. web 类指标
全部用户的访问次数/人数：
$Web浏览页面的发生次数/人数，按照用户属性的广告系列来源（$utm_source）进行分组
新用户的访问次数/人数：
$Web浏览页面的发生次数/人数，并且是否首日访问（$is_first_day）为真，按照用户属性的广告系列来源（$utm_source）进行分组
新用户的次日留存：
初始事件 $Web浏览页面的用户次日进行 $Web浏览页面 的占比
4.2. app 类指标全部用户的访问次数/人数：
$APP浏览页面 的发生次数/人数，按照用户属性的广告系列来源（$utm_source）进行分组
新用户的访问次数/人数：
$APP浏览页面 的发生次数/人数，并且是否首日访问（$is_first_day）为真，按照用户属性的广告系列来源（$utm_source）进行分组
用户使用时长：
$退出App（$AppEnd）的 $启动时长（event_duration）的人均值，按照用户属性的 广告系列来源（$utm_source）进行分组新
用户的次日留存：
初始事件 $APP浏览页面 的用户次日进行$APP浏览页面 的占比
4.3. 通用指标
新用户完成自定义事件的次数/人数：
自定义事件的发生次数/人数，并且 是否首日访问 （$is_first_day）为真，按照用户属性的 广告系列来源 （$utm_source）进行分组
新用户目标事件自定义指标：
自定义指标的数值，并且 是否首日访问（ $is_first_day）为真，按照用户属性的 广告系列来源（$utm_source）进行分组
5. 数据偏差
由于渠道来源使用的是用户的属性（默认为注册来源），那么一个用户通过 A 渠道访问注册后，以后无论是通过任何其他渠道访问，只要没进行过手动的渠
道更新，该用户都会被标记为 A 渠道用户,所以每个渠道的分组可能会存在一定的数据偏差。 但是，由于渠道对比组件主要功能是帮助筛选对比出优质渠
道，所以该渠道分流的偏差属于可接受范围内。 若您想精确的得到每个渠道的每日访问量，可以在事件分析中手动进行配置分析。.概览 v1.17
为了更好地的满足企业的数据管理与个人数据分析的场景，概览分为「公共概览」和「我的概览」两类。两类概览的使用方式与功能点一致，仅在管理上因
权限不同而提供了不同的操作，下文将逐一进行讲解。
1. 我的概览
我的概览主要用于使用成员，自己将常用的分析结果保存起来，形成便于查看的数据概览。同时用户可以将自己的概览共享给团队其他成员，来分享分析结
果。需要注意的是，数据结果将按照对方自己的数据权限范围来显示结果。
2. 公共概览
公共概览主要用于管理企业级需要共同关注的重要概览，打造企业的数据公共空间，由具有「管理公共概览」权限的成员共同维护。（原 1.13 - 1.15 版本
中的「预置概览」更名为「基础数据概览」仅可在「公共概览」中查看。）
在公共概览可以进行创建、复制、排序等基础操作，为了使用的顺畅性，所有的功能操作方式和「我的概览」一致，使用说明请参考「如何使用概览」中的
明细介绍。
3. 如何使用概览
在此模块将以「我的概览」为例进行基本操作使用的介绍。
1. 新建概览分组与概览
2. 概览排序管理：支持修改分组名称
3. 概览批量共享设置、删除的管理入口
4. 修改当前概览名称
5. 全局筛选时间窗
6. 全局筛选事件属性和用户属性
7. 刷新当前的计算数据（仅刷新失效数据，或刷新全量数据）
8. 概览邮件发送设置
9. 共享设置
10. 更多操作：性能设置、全屏模式、停止更新、复制概览、删除概览
11. 在概览中添加数据信息：从书签添加已有内容、新建组件、新建描述3.1. 新建「概览分组」与「概览」
在公共概览和我的概览的底部操作，点击「+」可以在当前分类下创建新的概览或者分组。新概览创建成功后，可以在概览详情页的右上角，点击「+」按钮，添加已有的内容或使用分析模型新建一个分析板块。另外我们特别新增了「添加描述」的
组件，便于你将整个概览做分区，或者添加解读描述，让其他查阅者更好的理解你想传递的分析结果。
选择「从公共书签添加」，选择将已有的公共书签添加到概览中；
选择「新建组件」通过分析模型创建新的书签，随后可保存到公共概览中，从此入口创建的分析内容，仅可添加到「公共概览」中。
如有「公共概览管理」权限的成员，在各个分析模型中分析后进行保存时，可选择此分析结果保存为书签后，添加到「公共概览」或「我的概览」中。3.2. 概览排序管理：支持修改分组名称
在左侧导航的底部点击中间的「排序按钮」后可进行当前概览的排序。
为了你能便捷的排版概览，可多选概览后进行批量移动的操作。
在此弹窗中，支持鼠标按住「概览」或「分组」可直接进行排序拖动。
此外，鼠标 hover 住具体「概览」或「分组」还可进行概览、分组的重命名等快捷操作。
3.3. 概览批量共享设置、删除的管理入口
选择「公共概览」或「我的概览」，在其左侧导航的「最右侧的按钮」点击后可分别进入对应的「概览管理」页面。在此列表中全面了解公共概览的共享设
置、创建信息。支持搜索概览名称关键字进行检索
支持进行「分享设置」，通过此配置设置当前概览的可见范围：「仅有管理公共概览权限的成员可见」、「全体成员」、「指定成员」；在「指定
成员」中可以设置某些成员，或某些角色动态配置，或某些职务的动态配置。注：如果当前项目没有「职务信息」此处将不显示。你可以前往「成
员与角色」-「成员管理」-「职务管理」中添加符合需要的。随后是此职务的成员，均可按照此配置查看到对应的概览。
编辑操作，支持在此修改概览的名称、与分组设置
删除操作，请慎重使用。删除后，以前可查看此概览的成员，将不可查看；没有归属的书签可在「公共概览」-「从公共书签中添加」重新恢复使
用。
停止分享，操作后「仅有管理公共概览权限」的成员方可查看。
在「管理公共概览」的页面，支持勾选多个概览进行「批量设置」。
如果对当前选中概览需要批量增加新的可访问的成员，那么可使用「增加可访问成员」
如果你需要对当前选中的概览批量重新设置可访问成员的范围，那么可使用「重置分享设置」
批量删除，操作请慎重操作。
注：如某位成员，对一个分组中所有概览都没有访问权限的话，那么该成员在查看公共概览时这个分组将不显示。
例如：运营数据概览组中有 3 张概览，每个概览的分享设置中都没有涵盖小明，那么当小明查看公共概览模块时，将无法查看到「运营数据概览组」。3.4. 修改当前概览名称
点击编辑按钮后，可直接修改概览名称，随后按 Enter 键或点击非输入区域将完成重命名的保存。
3.5. 全局筛选时间窗
修改时间后，将对此概览内的所有分析结果生效。当切换概览或页面后，此时间条件不支持保留，请悉知。
3.6. 全局筛选事件属性和用户属性
点击筛选按钮后，可在弹窗内进行筛选条件的配置。支持仅筛选「事件属性」或「用户属性」，当即设置了「事件属性」又设置了「用户属性」的筛选条件
后两类属性的查询关系为【且】。特别说明，目前全局筛选仅对部分分析模型的分析结果生效。目前全局筛选可对「用户分析」、「事件分析」、「留存分
析」、「分布分析」和「Session 分析」的分析结果进行筛选。在事件属性中我们特别标识出所选属性的分类，以便你更加有效的使用当前的筛选项。
公有属性：指概览涵盖的事件均有的「事件属性」，使用此类属性进行筛选时，可对所有分析生效。
非公有属性：指概览中仅在个别事件中存在的「事件属性」，使用此类属性进行筛选时，对于不包含此属性的事件，其筛选查询将自动失效。
注：事件属性目前不包含虚拟属性；用户属性目前不包含虚拟属性、用户分群和用户标签。
筛选条件提交后，在概览中会出现以下三类情况。
结果 A：所有筛选条件均生效
结果 B：所筛选的条件中，is Demo 不是此分析中所有所用事件的公有事件属性，所以此条件未生效。但用户依旧可以点击「查看生效的查询结
果」去查看其他生效的筛选条件，筛出的数据结果。
结果 C：所有筛选条件与此分析中所用事件的公有事件属性均不匹配，那么查询失败。但用户依旧可以点击「查看原始结果」来查看原本的分析结
果。3.7. 刷新当前的计算数据（仅刷新失效数据，或刷新全量数据）
刷新失效的数据：为了提升查询效率，神策分析查询的结果都是缓存的数据，且缓存的数据是按天缓存。缓存失效的机制是：
（1） 查询时间范围内，当天入库的事件数据总量小于 10 万条，有新数据入库，则缓存的数据就会失效。点击刷新失效数据按钮，会重新查询最新的数据。
（2） 查询时间范围内，当天入库的事件数据总量大于 10 万条，有新数据入库，且新入库的数据量小于上一次查询总量的 5% 时，则之前查询的缓存数据不
失效。点击刷新失效数据按钮，不会重新查询最新的数据。
（3） 查询时间范围内，当天入库的事件数据总量大于 10 万条，有新数据入库，且新入库的数据量大于等于上一次查询总量的 5% 时，则之前查询的缓存数
据失效。点击刷新失效数据按钮，会重新查询最新的数据。
刷新全量数据：只要有新数据入库，点击刷新全量数据按钮，就会查询最新的数据。
3.8. 概览邮件发送设置支持在系统界面配置邮件发送。只能给自己创建的数据概览配置邮件发送。首先选择一个自己创建的数据概览，然后如上图点击右上方的“邮件图标”，会弹
出一个对话框，在对话框中可以完成邮件配置。
第一步：设置发件箱
数据概览会从这个邮箱发出，因为私有部署以及数据安全等原因，神策分析不提供默认的发送邮箱。设置成功后，同一个账号下所有数据概览的发送都使用
这个邮箱。首次使用此功能，点击“+ 设置发件邮箱”，在弹出的对话框中完成配置。
填写“邮箱地址”后，点击“自动识别 SMTP 地址”，系统会尝试探测“邮箱 SMTP 地址”、“端口”、“SSL 连接”，并自动填充。如果探测失败，请咨询贵司的邮
件服务提供商。
如果是第一次配置“发件邮箱”，保存成功后，请点击“测试发送”进行测试，确保邮件可以正常发送。第二步：设置发送时间
邮件发送任务在设置的“发送时间”点例行启动，但最终发送时间可能会延迟 2 分钟 至 15 分钟，因为获取数据、渲染数据的时间无法确定。如果 10 分钟无
法获取完整的数据概览数据，邮件会发送失败。第三步：设置报告生成时间
举例说明：数据概览里时间选择“昨天”，邮件配置里“发送时间”设置“每天 09:00”。当前是 2017年7月24日，邮件会在 2017年7月24日9点发出，站在这
一天来看不同的“报告生成时间”对数据的影响。
实时生成：数据概览里设置的“昨天”为 2017年7月23日，与现实中的感觉一致。数据概览里数据也是 2017年7月23日的数据。
发送前 10 小时：数据概览里设置的“昨天”为 2017年7月22日，数据概览里数据也是 2017年7月22日的数据。发送邮件时“当前时间”不再是当时的时间， 而
是从 2017年7月24日9点向前退 10 小时，“当前时间”变为 2017年7月23日23时。第四步：测试发送
配置完成后，可以点击“测试发送”，确保邮件可以正常发送，确保数据概览内容正确。3.9. 共享设置
可将自己的概览共享给其他成员查看，共享成功后将在通知助手中通知对方，并自动添加到对方的「我的概览」-「分享给我的概览」中。当你修改了此概览
内容，对方查看时将同步更新。
可将自己的概览共享给全部成员，或指定的角色、职务、或具体成员。3.10. 更多操作：性能设置、全屏模式、停止更新、复制概览、删除概览
性能设置
支持在界面调整概览性能，选择合适的配置以提高概览的展现效率，从而也可保证查询资源的有效使用。
A.典型场景
接入数据量（每天更新 10 亿条以上）较大的客户，若想优化查询性能，可将更关心趋势呈现的指标统一放到某概览中，调整其概览性能，减少查
询时间。
机器配置与数据接收量不匹配的客户，例如数据量为 10 万日活，配置为单机高配（单机高配的标准为 6 万日活），此时查询通常较慢。可调整概
览性能以减少查询时间。当然，最好的建议是将机器配置调整为与数据量匹配的状态。
B.具体操作
第一步：点击概览右上角设置按钮，选择 A 处“概览性能”，弹出性能设置页面（只有自己创建的概览有该入口）。第二步：进行设置
B 处选择计算精度，默认选择“完全精确”。
完全精确：概览中所有数据完全精确计算；
仅合计值精确：对概览中所有去重数的合计值近似计算，其他数据精确计算；
全部近似：对概览中所有去重数近似计算，其他数据精确计算。
C 处选择数据更新时间，默认选择实时。
实时：数据实时更新；
每日固定时间更新：一般为每日凌晨 3 点，具体以后端设定的时间为准。
D 处调整抽样系数：默认为对全量数据计算。可拖拽或点击横滑杆调整抽样系数。
点击 E 处确定按钮生效，设置只对本概览有效。第三步：若概览性能为非默认配置，设置按钮会呈现激活状态，以作提示。全屏模式
使用全屏模式后，可设置数据自动刷新的间隔时长，在全屏模式下，导航栏均被隐藏，但依旧可以使用概览的全局筛选功能。点击右上角最右侧的第一个按
钮或按 ESC 键可直接退出全屏模式。
停止更新
当你的项目中概览数量较多时，影响性能导致查询缓慢时，可以将不再需要每日更新关注的概览「停止更新」，这样概览每日就不会再更新数据，占用计算
性能了。如业务变化，需要继续监测数据时，可在停止「停止更新」的操作位置，点击「自动更新」恢复每日的自动计算并缓存概览数据的功能，让用户查
看到最新的数据。
3.10.1. 复制概览
为了企业能快速将已有的概览添加到「公共概览」，或让使用者可以快速使用他人的概览配置完成自己的相关分析工作。在 1.16 版本中，我们提供了「复制
概览」的功能，此功能适用于「我的概览」和「公共概览」。复制后，可对每个分析内容进行自定义调整。请注意：
场景库的「基础数据概览」是特殊的概览类型，目前暂不支持进行快速复制。只有具有「公共概览管理权限」的成员方可复制已有概览后添加到「公共概览」中。
3.10.2. 删除概览
删除概览的时候，因为书签有可能添加在多个概览中使用，所以系统不会连同删除对应的书签。请悉知。如果是共享概览，被删除后则会通知到目前被分享
的成员。
3.11. 在概览中添加数据信息：从书签添加已有内容、新建组件、新建描述
A.从书签添加
仅可添加当前用户自己创建的书签。
B.新建组件
第一步：点击「新建组件」后，选择需要使用的分析模型（目前「路径分析」和「间隔分析」暂时以小卡片的形式订阅到概览中，后续我们将持续迭代可视
化相关的功能。）
第二步：进入对应分析模型后，进行配置随后点击「保存」第三步：进行可视化信息的设置，点击确定后，此分析内容将被成功添加到所在概览中。
C.新建描述
点击「新建描述」后在弹窗内填写描述内容。标题和详情至少填写一项即可保存。一个概览中可以添加多个描述，以便于解释说明当前分析的内容，或进行
概览内分析板块的分隔。4. 如何使用公共概览
「公共概览」中的基本操作与「我的概览」中的均一致，如需了解请查看上一节「如何使用概览」的明细介绍。接下来主要介绍一下「公共概览」中区别于
「我的概览」的功能。
点击切换到「公共概览」后，底部的操作将仅与公共概览有关，具有「管理公共概览」权限的成员方可看到此管理功能。
4.1. 创建公共概览
当需要监测新的数据时，可以在左侧导航的「公共概览的基本操作设置入口」点击「+」按钮，创建一个全新的概览。如果有分组的需要，也可以在此创建新
的分组。4.2. 调整概览、概览组的排序，管理概览组
在左侧导航的「公共概览的基本操作设置入口」点击中间的「排序按钮」后可进行当前概览的排序。
为了你能便捷的排版概览，可多选概览后进行批量移动的操作。
在此弹窗中，支持鼠标按住「概览」或「分组」可直接进行排序拖动。
此外，鼠标 hover住具体「概览」或「分组」还可进行概览、分组的重命名等快捷操作。4.3. 管理公共概览
在左侧导航的「公共概览的基本操作设置入口」的「最右侧的按钮」点击后可进入「公共概览管理」页面。在此列表中全面了解公共概览的共享设置、创建
信息。
支持搜索概览名称关键字进行检索
支持进行「分享设置」，通过此配置设置当前概览的可见范围：「仅有管理公共概览权限的成员可见」、「全体成员」、「指定成员」；在「指定
成员」中可以设置某些成员，或某些角色动态配置，或某些职务的动态配置。注：如果当前项目没有「职务信息」此处将不显示。你可以前往「成
员与角色」-「成员管理」-「职务管理」中添加符合需要的。随后是此职务的成员，均可按照此配置查看到对应的概览。
编辑操作，支持在此修改概览的名称、与分组设置
删除操作，请慎重使用。删除后，以前可查看此概览的成员，将不可查看；没有归属的书签可在「公共概览」-「从公共书签中添加」重新恢复使
用。
停止分享，操作后「仅有管理公共概览权限」的成员方可查看。在「管理公共概览」的页面，支持勾选多个概览进行「批量设置」。
如果对当前选中概览需要批量增加新的可访问的成员，那么可使用「增加可访问成员」
如果你需要对当前选中的概览批量重新设置可访问成员的范围，那么可使用「重置分享设置」
批量删除，操作请慎重操作。
注：如某位成员，对一个分组中所有概览都没有访问权限的话，那么该成员在查看公共概览时这个分组将不显示。
例如：运营数据概览组中有 3 张概览，每个概览的分享设置中都没有涵盖小明，那么当小明查看公共概览模块时，将无法查看到「运营数据概览组」。
5. 环比同比规则
时间粒度 环比 同比按分钟 对比上分钟 对比上一小时同期
按小时 对比上小时 对比昨天同期
按天 对比昨天 对比上周同期
按周 对比上周 无同比
按月 对比上月 对比去年同期
例如：选择过去的时间段，比如时间选择 2017 年 3 月 1 日至 2017 年 3 月 10 日，按月查看，环比为 2017 年 3 月整月的数据对比上月整月 2017 年 2
月的数据，同比为 2017 年 3 月对比去年同期 2016 年 3 月的数据。书签.书签 v1.17
1. 概述
书签是帮助您管理常用查询的工具。书签模块包含您通过分析模型建立的所有数据报表，可以根据需求添加到任意一个概览中，也可以直接在书签模块查看
您创建的书签。
在书签模块可以对所有书签进行新建、查看、编辑、删除等管理：
2. 新建书签
A.当想创建新的书签时，点击右上角的「新建书签」，然后选择你要通过哪个分析模型。
B.进入分析模型并设置筛选条件后，点击「存为书签」，就成功创建一个书签了。3. 查看书签
A.当您想查看书签的具体筛选条件或数据时，点击书签列表中对应书签，就会进入到分析模型，就可以查看筛选条件和具体的数据结果了。
B.如果修改了书签的筛选条件查看数据，点击「另存为」可以保存为新的书签；点击「保存修改」可以更新当前书签。4. 编辑书签
当想修改书签的名称，点击「编辑」修改书签的名称即可。
5. 删除书签
当不需要某个书签时，点击「删除」就可以删除书签了。书签一经删除后无法恢复，请谨慎操作。分析模块.分析模块 v1.13
事件分析
Session 分析
漏斗分析
留存分析
分布分析
归因分析
用户路径分析
网页热力分析
App 点击分析
间隔分析
用 户 分 析
自定义查询事件分析.事件分析 v1.13
1. 事件分析概述
事件，是追踪或记录的用户行为或业务过程。举例来说，一个电商产品可能包含如下事件：用户注册、浏览商品、添加购物车、支付订单等。
事件分析，是指基于事件的指标统计、属性分组、条件筛选等功能的查询分析。借助于神策分析强大的筛选、分组和聚合能力，事件分析可以帮助回答以下
问题：
最近三个月来自哪个渠道的用户注册量最高？变化趋势如何？
各个时段的人均充值金额是分别多少？
上周来自北京的，发生过购买行为的独立用户数，按照年龄段的分布情况？
每天的独立 Session 数是多少？
根据您的产品特性合理配置追踪事件和属性，可以激发出事件分析的强大潜能，回答关于变化趋势、维度对比的各种细分问题。
查看事件分析功能应用示例
2. 事件分析界面功能简介
可以对一个指标进行分析，比如对『支付订单』的『触发用户数』。也可以再添加一个指标，同时对多个指标进行分析。
对事件的『触发用户数』进行分析，还可以下载行为相关的用户详情，见下图。2.1. 选择分析方式
2.2. 选择指标在第一个下拉框中选择事件，在第二个下拉框中选择要分析的指标，点击右边的加号可以添加多个指标。
对于所有事件，都可以分析如下指标：
1. 总次数： 在选定时间范围内，该事件触发的次数。
2. 触发用户数： 在选定时间范围内，触发该事件的独立用户数。
3. 人均次数： 在选定时间范围内，独立用户触发该事件的平均次数。
对于所有类型的属性，都可以将如下值作为分析指标：
1. 去重数：在选定时间范围内，该属性出现的独立去重个数。
对于有数值型属性的事件，还可以将数值型属性作为分析指标：
1. 总和： 在选定时间范围内，该属性的取值求和。
2. 均值： 在选定时间范围内，该属性取值的算术平均值。
3. 最大值： 在选定时间范围内，该属性取值的最大值。
4. 最小值： 在选定时间范围内，该属性取值的最小值。
特别的，在神策分析 1.5 版本里面，我们推出了“自定义指标”功能，通过点击指标前面的切换按钮：即能进入自定义指标的编辑界面：
在这里，可以做如下的一些操作：
1. 在输入框 A 里面，可以输入自定义指标的描绘公式，支持常规指标、常数之间的四则运算；
2. 在输入框 B 里面，可以对自定义指标进行命名；
3. 在下拉框 C 里面，可以选择“百分比”、“两位小数”、“取整”三种展现样式；
4. 点击按钮 D，可以保存这个自定义指标。 说明：如果选择的事件是虚拟事件，表达式中的虚拟事件名需要添加英文单引号引入；
2.3. 添加事件
如果要对多个事件的指标进行分析，点击左侧的加号可以添加事件。1.6.5版本中增加了事件标签功能。事件非常多时，可以通过“标签选择”来筛选事件，以便快速找到事件。在使用事件的标签之前，需要“元数据”中给事件打
标签。
在 Sensors Analytics 中任何选择事件的地方，都可以通过这种方式来选择事件。
2.4. 按分组（维度）查看
按维度查看数据，可以进行更加精细化的分析。这里支持通过多个维度分析数据。
用法举例：
某产品近期通过不同渠道进行了推广，新用户量大增。通过查询“注册”事件的“触发用户数”，并“按照渠道分组”，可以对比不同渠道
带来的增长效果。
当分组数大于 10 个时，图表会默认展示在最近一个时间单位内数值最大的 10 个分组。同时查看多个指标时，默认优先展示指标。如果这里选择的属性是数字类型，可以自定义分组区间。如果这里选择的是时间类型，可以选择不聚合，按照时间单位分钟/天/小时等进行分组查看，也可以选择按照时间段汇总，例如，以『按天（日期）』汇
总，查询会将当前时间段内的每月第几天的数据汇总到一起，会得到每月 1 号到每月 31 号的汇总数据。
如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在书签中也生效。
2.5. 增加筛选条件
通过添加筛选条件，可以精细化查看符合某些具体条件的事件数据。
点击“+筛选条件”，从下拉属性列表中选择需要针对其筛选的属性。
你可以通过3个类型的属性来进行筛选：
1. 事件的通用属性： 当使用 Sensors Analytics SDK 时，这些是默认会被记录的事件属性。
2. 事件的自定义属性： 在追踪事件时，你所自定义的有关该事件的特定属性。
3. 用户属性： 代表用户自身特质的一些属性。包括预定义属性和自定义属性。
根据不同的属性的数据类型（文本、数值、日期时间、布尔、集合等），提供不同的筛选逻辑操作，如下图所示：当添加了多条筛选条件时，用户可以点击下图中[a]，切换筛选条件之间的关系：
选择“且”，代表查询结果要符合每条筛选条件
选择“或”，代表查询结果只需要符合一条或多条筛选条件
点击[b]可以删除相应的筛选条件。
查询结果的相应变动，会实时地反映在下方的图表和表格中。
2.6. 选择时间范围选择查询的时间范围。点击『对比时间』可以选择对比时间段，绿色的是对比时间段，此时在图形和表格中会展示两个时间段的对比数据。
2.7. 切换图表类型
可选择的图表类型：
1. 线图
2. 柱状图
3. 饼图
4. 累积图
1.8 版本中新增了对部分可累加的指标的累积图类型展示，包括总次数和数值属性总和，当前只支持单指标，不支持多指标和对比时间区间下的累积图。
在多个指标的情况下，可以人工选择要展示哪些指标的哪些分组，如下图所示：2.8. 选择聚合时间单位
可选择的数据聚合时间单位：
1. 按分钟
2. 按小时
3. 按天
4. 按周
5. 按月
其中，选择『按分钟』聚合时，最多可展示1天的数据;选择『按小时』聚合时，最多可展示30天的数据。
2.9. 数据表格
1.6.5版本提供了两种表格展示方式，点击 I 处的转置按钮以1.6.5之前的方式查看数据。点击 J 处的百分号，可以在表格内展示两个时间点的数据变化百分
比。百分比公式（以12月28号表格内百分比的计算为例）：12月28号减12月27号数据之差，除以12月27号的数据。
2.9.1. 默认表格展示方式
以有分组、多指标、有对比的场景来介绍表格的展示方式。1. A 列展示分组，多个分组时每个分组单独一列。无分组不展示此列。点击此列表头可以对分组进行排序。
2. B 列展示指标，一个指标时不展示此列。每个指标单独一行，同一个分组值从上到下依次展示指标。
3. C 列展示对比时间段，没有选择时间对比时不展示此列。同一个指标内，从上到下依次展示主时间点数据、对比时间点数据、对比时间点相对主时
间点的变化率。
4. D 列展示合计值，此列数据不是简单相加，如果是触发用户数，会做去重。点击此列表头内的折叠按钮，可以将右侧的详细时间点数据隐藏。
5. E 列展示每个时间点的数据。
2.9.2. 老版本（1.6.5 版本）之前表格展示方式
单个指标查询的表格展示：
1. A 点击展示合计数据。
2. B 为日期列，可以排序，合计行不参与排序。维度展示在表头行，如[b]所示。
3. C 列中包含绝对数据，和相对上一个相邻时间单位的变化百分比。
多个指标查询的表格展示：
1. A 为日期列，按照日期排序后，时间内按照第一个指标倒序排列。
2. B 为维度列，多个维度用逗号分割展示，排序功能仅在日期内进行排序。
3. C 为指标列，展示指标数据。
有时间对比查询的表格展示：2.10. 浏览用户详情
找到『触发用户数』对应的单元格，点击分析结果的数字，则可以浏览这些用户的具体情况，以及单个用户的详细行为序列。
2.11. 切换计算精度
在 1.8 版本中，“事件分析“新增了计算精度的选择，可选择 “精确计算“和“近似计算”。近似计算只对和触发用户数相关的指标生效，包括触发用户数，人均次
数和属性人均值，以及由以上三个指标组成的自定义查询。近似计算使用 HyperLogLog 算法，和精确计算比有2％的误差。使用近似计算能够加速查询。
3. FAQ
3.1. 查看 App 端数据，为什么今天查看昨天的数据和昨天查看当天的数据不同
答：App 端有缓存机制。
3.2. 分组过多，数据显示不完整
答：可以通过查询 API 获取完整数据。
3.3. 事件分析里和漏斗里查看的用户数不一致
答 ：事件分析和漏斗分析逻辑不太一致。3.4. 为什么分组和按总体查看的用户数不一致
答：以城市为例，同一个用户，在北京和上海两个城市浏览过同一个网页，如果按总体查看，数量为 1，如果按城市查看，北京和上海的用户中都会有这个
用户。
3.5. 为什么合计值和每天相加的用户不一致
答：用户数有去重机制。
3.6. 为什么按天查看和按周查看数据不一致
答：按周查看，查看的是自然周的数据。事件分类.事件分类 v1.13
1.10 及其以后版本，提供了事件分类功能，当事件较多时，可以对事件进行分类、排序，以便在使用分析功能时更快的找到自己想要的事件。
1. 打开事件分类管理页面
在事件下拉框中点击右上角的“设置”按钮，会进入事件分类管理页面。
2. 查看分类
打开事件分类管理页面后，会显示当前应用的事件分类。A. 点击“基于当前新建”按钮，会基于当前分类创建一个新的分类。
B. 点击“编辑”按钮，会进入编辑页面，系统默认分类只有 admin 用户有权限编辑，默认分类编辑后会同步给系统所有成员。
3. 新建分类
在查看分类页面点击“新建”按钮后，会进入新建分类页面。A. 点击分类名称可以对分类名称进行编辑。
B. 点击“新建分组”按钮可以在当前分类下创建新的分组。
C. 点击分组名称可以对分组名称进行编辑。
D. 鼠标移到分组顶部可以对分组进行拖拽，调整各分组的顺序。
E. 鼠标移到事件上可以对事件进行拖拽，调整分组内事件的顺序或将事件从一个分组拖拽到另一个分组内。
F. 点击事件右侧的“显示隐藏按钮”可以隐藏或显示事件，隐藏后的事件将不会出现在事件下拉框中，不影响元数据。
G. 点击分组右上角的“显示隐藏按钮”可以隐藏或显示分组，隐藏后的分组将不会出现在事件下拉框中。
H. 点击分组右上角的“删除按钮”可以将分组删除，分组内的事件会被自动转移到默认分组内。
I. 点击“确定”按钮会保存当前分类。
J. 点击“保存并应用”按钮会保存当前分类，并将分类应用到事件下拉框中。
4. 应用分类
分类保存后，会回到查看分类页面。A. 点击分类名称会在下拉菜单中看到所有分类列表，点击菜单项可以切换分类。
B. 点击“应用”按钮后，分类会应用到事件下拉框中。
5. 使用事件下拉框A. 在搜索框中可以输入关键字来搜索相关的事件。
B. 点击右上角的“筛选”按钮可以打开事件筛选下拉框。
C. 可以只查看元事件或虚拟事件。
D. 可以根据事件标签对事件进一步筛选。
E. 点击“重置筛选”可以重置已经选择的筛选项，回到默认状态。.事件分组 v1.17
1. 概述
在使用神策事件分析，留存分析，分布分析等功能的时候，部分用户对事件的分组和排序方式会有不同的需求，为满足不同账号自定义下拉面板的展现效果
的需求，神策提供的个性化事件分组的功能。
在事件分析中，点击切换事件入口后，可查看到选择事件的面板。在此面板的右上角，点击「齿轮设置按钮」后可打开事件分组配置管理侧拉窗。
2. 默认看板
在保证个性化的排序使用的同时，神策同样提供了「默认」看板作为企业所有成员初始化的看板，便于企业标准化一套统一的事件分组归类。对于「默认」
分组，仅有「管理元数据」权限的成员方可进行修改，修改后对全企业成员均立即生效。3. 自定义看板
每个成员均可创建自己的看板，用户可点击「默认」呼出下拉气泡后，点击「新建面板」开始自定义的设置。
4. 管理看板内容
点击右下角的「编辑」按钮后，可激活对当前面板的所有操作。 A.
修改自定义面板名称； B.
修改面板内分组名称，需要注意的是「默认分组」不可修改其名称。
C.批量操作，在多选跨组的事件后，可对此批事件进行「批量移动到指定分组」或标记为「显示」、「隐藏」；如果多选的事件为同组事件，那么可使用
「组内移动」快速将事件移动到指定事件「之前」或「之后」。
D.对当前 Hover 的分组可进行「置顶」、「置底」、「整组隐藏」、「删除当前组」的操作。如删除的组内有事件，那么会提供一键转移当前组内的所有事件
到「指定分组」中。
E.批量勾选要操作的事件 F.
如果当前分组或事件为隐藏状态，则以此状态标识显示。隐藏的内容在分析模型中选择事件的面板中将不再显示。 G.
默认分组，系统默认存在的分组，且不可删除，完成分组管理后，后续持续新增的元事件和虚拟事件将自动添加到此分组中。H.
添加分组，点击后可以添加自己的新的分组。
注：当然对于每个单独的事件，支持直接进行隐藏操作。组内的事件可直接拖动排序，同时分组同样可直接拖动进行排序。个性化事件分组.个性化事件分组 v1.13
1. 功能作用
在使用神策事件分析，留存分析，分布分析等功能的时候，部分用户可能对事件的分组和排序方式有不同的需求，为满足不同账号自定义下拉面板的展现效
果的需求，神策提供的个性化事件分组的功能。
2. 操作方式
2.1. 编辑入口
在事件分析，留存分析，分布分析页面，点击事件选择框，并点击弹出的列表右上角的齿轮按钮，即可弹出编辑页面：
2.2. 新增和选择展现效果
在事件分析，留存分析，分布分析页面，点击事件选择框，并点击弹出的列表右上角的齿轮按钮，即可弹出展现效果页面：点击1处的下拉三角图标，显示本账号创建的所有展现效果，如需切换，点击下拉框中的某个展现效果后，点击4处的应用即可。
点击2处的“新建”按钮，创建新的展现效果，点击3处的“编辑”按钮，编辑现在选中的展现效果
2.3. 编辑展现效果
点击上图中的“新建”或者“编辑”按钮后，即可弹出编辑页面：点击1处的笔图标，可更改展现效果的名称（“默认”展现效果无法更改名称）。
点击2处的“新建文件夹”按钮，创建新的事件分组，最新创建的分组默认列在最下。
分组和事件均可以自由拖动排序，事件可在多个分组间拖动完成分组。
点击3处的“+”“—”符号可以展开或者折叠分组。
点击4处的眼睛按钮，可在此展示效果中隐藏该事件。
点击5中的“取消”按钮取消编辑，点击“保存”按钮，保存编辑并不切换展示效果，点击“保存并应用”按钮，保存编辑并立即切换到这个展示效果。点
击6中的“X”符号，可以删除某个事件分组。
注意：
在某个展示效果中隐藏某事件，不影响该事件在“元数据”中的可见或隐藏状态。
只有管理员才可以编辑“默认”展示效果，且编辑结果会对全部账号生效，非管理员账号，只能编辑自己创建的展示效果，且
不会影响到其他账号。.个性化事件分组 v1.17Session 分析.Session 分析 v1.15
1. Session 分析概述
1.1. 在事件分析中选择分析方式
在 1.6 版本增加了 Session 分析功能，第一次进行 Session 分析之前，首先需要在“元数据”的“Session管理”里创建 Session。这里对 Session 的相关概念
进行说明，见下图：在 a 处选择已经创建的 Session。在 b 处选择此 Session 中的事件，选择“Session总体”可以对 Session 整体情况进行分析。在 b 处选择事件，则 c 中对
应的指标也会发生变化。在 c 中选择具体指标，除一些通用指标外，还包含 b 处所选事件的属性的指标。d 处圈红的是 “Session 属性”，每个 Session 内
首次触发事件的属性的并集。下边对几个主要概念进行说明：
1. 跳出率： Session 中只发生一个事件的 Session 个数除以总 Session 数。比如有三个 Session，第一个 Session 事件序列为 A,B；第二个
Session 事件序列为 A；第三个 Session 事件序列为 A,C,B；则 Session 总体的跳出率为 1/3。
2. 退出率： Session 的退出率包括 Session 中某个事件的退出率 和 Session中任意事件的退出率。某个事件的退出率指该事件作为 Session 的结束
事件的次数除以该事件发生次数，任意事件退出率指 Session 数除以 Session 中所有事件发生次数。比如有三个 Session，第一个 Session 事件序
列为A,B；第二个 Session 事件序列为A；第三个 Session 事件序列为A,C,A；则 Session 中A事件的退出率为 2/4, 任意事件的退出率为 3/6。
3. Session 时长： Session 内最后一个事件触发的时间减去 Session 内第一个事件触发的时间。
4. Session 深度： Session 内触发事件的次数。
5. Session 内事件时长： 假如某 Session 内事件触发顺序为 a > b > c > d，则事件 a 的时长为 b 减去 a，事件 d 的时长未知。
6. Session 初始事件： Session 内第一次触发的事件。
7. Session 属性： d 处的 Session 属性是指一个 Session 中初始事件的属性。比如一个 Session 的事件序列为 A,B,C；A 事件的操作系统为 iOS，
B 事件的操作系统为 Android，C 事件的操作系统为空，则这个 Session 中的 Session 属性操作系统应该是 iOS，是第一个事件对应的操作系统属
性值。
如果您想了解 Session 的定义、使用等内容，可阅读神策博客文章《如何应用 Sensors Analytics 进行 Session 分析》。.Session 分析 v1.16
1. Session 分析概述
1.1. 在事件分析中选择分析方式
在 1.6 版本增加了 Session 分析功能，第一次进行 Session 分析之前，首先需要在“元数据”的“Session管理”里创建 Session。这里对 Session 的相关概念
进行说明，见下图：在 a 处选择已经创建的 Session。在 b 处选择此 Session 中的事件，选择“Session总体”可以对 Session 整体情况进行分析。在 b 处选择事件，则 c 中对
应的指标也会发生变化。在 c 中选择具体指标，除一些通用指标外，还包含 b 处所选事件的属性的指标。d 处圈红的是 “Session 属性”，每个 Session 内
首次触发事件的属性的并集。下边对几个主要概念进行说明：
1. 跳出率： Session 中只发生一个事件的 Session 个数除以总 Session 数。比如有三个 Session，第一个 Session 事件序列为 A,B；第二个
Session 事件序列为 A；第三个 Session 事件序列为 A,C,B；则 Session 总体的跳出率为 1/3。
2. 退出率： Session 的退出率包括 Session 中某个事件的退出率 和 Session中任意事件的退出率。某个事件的退出率指该事件作为 Session 的结束
事件的次数除以该事件发生次数，任意事件退出率指 Session 数除以 Session 中所有事件发生次数。比如有三个 Session，第一个 Session 事件序
列为A,B；第二个 Session 事件序列为A；第三个 Session 事件序列为A,C,A；则 Session 中A事件的退出率为 2/4, 任意事件的退出率为 3/6。
3. Session 时长： Session 内最后一个事件触发的时间减去 Session 内第一个事件触发的时间。
4. Session 深度： Session 内触发事件的次数。
5. Session 内事件时长： 假如某 Session 内事件触发顺序为 a > b > c > d，则事件 a 的时长为 b 减去 a，事件 d 的时长未知。
6. Session 初始事件： Session 内第一次触发的事件。
7. Session 属性： d 处的 Session 属性是指一个 Session 中初始事件的属性。比如一个 Session 的事件序列为 A,B,C；A 事件的操作系统为 iOS，
B 事件的操作系统为 Android，C 事件的操作系统为空，则这个 Session 中的 Session 属性操作系统应该是 iOS，是第一个事件对应的操作系统属
性值。
如果您想了解 Session 的定义、使用等内容，可阅读神策博客文章《如何应用 Sensors Analytics 进行 Session 分析》。
2. 新增了会话（session）的切割方法
在原有的根据间隔时间切割的基础上，我们支持使用指定的「开始事件」和「结束事件」进行会话切割
2.1. 分析会话（session）整体时，新增了一个「同时并发人数」的指标
选择分析 session 总体时，可以使用 session 同时并发人数来计算该时间点同时会在的会话数2.2. 计算口径说明
2.2.1. 新的 session 切割是如何实现的？
步骤 1：将用户的行为序列，按照发生时间远到进进行排序
步骤 2：以第一个行为作为起点，向后进行匹配。
若匹配到的是一个「开始事件」：那么会自动切断会话；以这个「开始事件」作为起点，进行第二个 session 的匹配
若匹配到的是一个「结束事件」：那么会将这个「结束事件」划入到当前会话中；以「结束事件」的下一个事件作为起点，进行第二
个 session 的匹配
若在切割时间内没有匹配到任何事件：那么就会自动切断会话；以下个事件作为起点，进行第二个 session 的匹配
2.2.2. 同时并发人数是如何实现的？
我们认为一个会话是一个持续的时段，那么在计算同时并发人数的时候，就判断该时间点有多少个会话同时在线即可。如图所示：
时间点 1 的同时在线人数为 3
时间点 2 的同时在线人数为 2
时间点 3 的同时在线人数为 1
2.3. 使用场景
2.3.1. 什么时候使用开始和结束事件？
当我们对我们的会话有明确的开始和结束事件的定义时，可以使用开始和结束来让我们切割出来的会话更加符合预期。
比如：
在视频行业中有明确的「开始播放」和「结束播放」
在移动端有明确的「APP 启动」和「APP 退出」
一次转化路径中，会认为「首页」算做一个开始的点，「支付」的发生是一个结束的标志
2.3.2. 同时并发人数可以分析什么？
在事件是存在持续行为的场景中，同时并发人数相对事件的发生次数更加有代表意义。
我们来举个例子：
一个视频类的 APP，每个时段都有用户不断地进入和退出。
当我们做一些线上的活动时，希望在用户在线时间最密集的那一刻进行活动的推送
那么我们如何判断出哪个时段是在线的用户最多的时段呢？
我们来看一下模拟数据的结论：
用户 启动时间 退出时间 启动时间查看指标 同时在线查看指标
A 19:01 20:14 19:00-19:30 —— 3人 19:00-19:30 —— 3人
B 19:14 20:14 19:30-20:00 —— 1人 19:30-20:00 —— 4人
C 19:29 20:14 20:00-20:30 —— 2人 20:00-20:30 —— 6人
D 19:59 20:14 20:30-21:00 —— 0人 20:30-21:00 —— 2人
E 20:14 21:01
F 20:29 22:01 最后结论得出，我们在 19:00-19:30 期间进行投放效果最好 最后结论得出，我们在 20:00-20:30 期间进行投放效果最好
实际上，我们的用户在 20:00 至 20:30 之间是在线人数最多的，在这个时间段进行运营活动效果最好.Session 分析 v1.17
Session 分析概述
在事件分析中选择分析方式
在 1.6 版本增加了 Session 分析功能，第一次进行 Session 分析之前，首先需要在“元数据”的“Session管理”里创建 Session。这里对 Session 的相关概念
进行说明，见下图：在 a 处选择已经创建的 Session。在 b 处选择此 Session 中的事件，选择“Session总体”可以对 Session 整体情况进行分析。在 b 处选择事件，则 c 中对
应的指标也会发生变化。在 c 中选择具体指标，除一些通用指标外，还包含 b 处所选事件的属性的指标。d 处圈红的是 “Session 属性”，每个 Session 内
首次触发事件的属性的并集。下边对几个主要概念进行说明：
1. 跳出率： Session 中只发生一个事件的 Session 个数除以总 Session 数。比如有三个 Session，第一个 Session 事件序列为 A,B；第二个
Session 事件序列为 A；第三个 Session 事件序列为 A,C,B；则 Session 总体的跳出率为 1/3。
2. 退出率： Session 的退出率包括 Session 中某个事件的退出率 和 Session中任意事件的退出率。某个事件的退出率指该事件作为 Session 的结束
事件的次数除以该事件发生次数，任意事件退出率指 Session 数除以 Session 中所有事件发生次数。比如有三个 Session，第一个 Session 事件序
列为A,B；第二个 Session 事件序列为A；第三个 Session 事件序列为A,C,A；则 Session 中A事件的退出率为 2/4, 任意事件的退出率为 3/6。
3. Session 时长： Session 内最后一个事件触发的时间减去 Session 内第一个事件触发的时间。
4. Session 深度： Session 内触发事件的次数。
5. Session 内事件时长： 假如某 Session 内事件触发顺序为 a > b > c > d，则事件 a 的时长为 b 减去 a，事件 d 的时长未知。
6. Session 初始事件： Session 内第一次触发的事件。
7. Session 属性： d 处的 Session 属性是指一个 Session 中初始事件的属性。比如一个 Session 的事件序列为 A,B,C；A 事件的操作系统为 iOS，
B 事件的操作系统为 Android，C 事件的操作系统为空，则这个 Session 中的 Session 属性操作系统应该是 iOS，是第一个事件对应的操作系统属
性值。
如果您想了解 Session 的定义、使用等内容，可阅读神策博客文章《如何应用 Sensors Analytics 进行 Session 分析》。
新增了会话（session）的切割方法
在原有的根据间隔时间切割的基础上，我们支持使用指定的「开始事件」和「结束事件」进行会话切割
分析会话（session）整体时，新增了一个「同时并发人数」的指标
选择分析 session 总体时，可以使用 session 同时并发人数来计算该时间点同时会在的会话数计算口径说明
新的 session 切割是如何实现的？
步骤 1：将用户的行为序列，按照发生时间远到进进行排序
步骤 2：以第一个行为作为起点，向后进行匹配。
若匹配到的是一个「开始事件」：那么会自动切断会话；以这个「开始事件」作为起点，进行第二个 session 的匹配
若匹配到的是一个「结束事件」：那么会将这个「结束事件」划入到当前会话中；以「结束事件」的下一个事件作为起点，进行第二
个 session 的匹配
若在切割时间内没有匹配到任何事件：那么就会自动切断会话；以下个事件作为起点，进行第二个 session 的匹配
同时并发人数是如何实现的？
我们认为一个会话是一个持续的时段，那么在计算同时并发人数的时候，就判断该时间点有多少个会话同时在线即可。如图所示：
时间点 1 的同时在线人数为 3
时间点 2 的同时在线人数为 2
时间点 3 的同时在线人数为 1
使用场景
什么时候使用开始和结束事件？
当我们对我们的会话有明确的开始和结束事件的定义时，可以使用开始和结束来让我们切割出来的会话更加符合预期。
比如：
在视频行业中有明确的「开始播放」和「结束播放」
在移动端有明确的「APP 启动」和「APP 退出」
一次转化路径中，会认为「首页」算做一个开始的点，「支付」的发生是一个结束的标志
同时并发人数可以分析什么？
在事件是存在持续行为的场景中，同时并发人数相对事件的发生次数更加有代表意义。
我们来举个例子：
一个视频类的 APP，每个时段都有用户不断地进入和退出。
当我们做一些线上的活动时，希望在用户在线时间最密集的那一刻进行活动的推送
那么我们如何判断出哪个时段是在线的用户最多的时段呢？
我们来看一下模拟数据的结论：
用户 启动时间 退出时间 启动时间查看指标 同时在线查看指标
A 19:01 20:14 19:00-19:30 —— 3人 19:00-19:30 —— 3人
B 19:14 20:14 19:30-20:00 —— 1人 19:30-20:00 —— 4人
C 19:29 20:14 20:00-20:30 —— 2人 20:00-20:30 —— 6人
D 19:59 20:14 20:30-21:00 —— 0人 20:30-21:00 —— 2人
E 20:14 21:01
F 20:29 22:01 最后结论得出，我们在 19:00-19:30 期间进行投放效果最好 最后结论得出，我们在 20:00-20:30 期间进行投放效果最好
实际上，我们的用户在 20:00 至 20:30 之间是在线人数最多的，在这个时间段进行运营活动效果最好漏斗分析.漏斗分析 v1.13
在介绍漏斗分析之前，需要有一些基本概念进行介绍：
1. 步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
2. 时间范围：在界面上选择的时间范围，是指漏斗的第一个步骤发生的时间范围；
3. 窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化；
1. 漏斗分析概述
漏斗模型主要用于分析一个多步骤过程中每一步的转化与流失情况。
举例来说，用户购买商品的完整流程可能包含以下步骤：
1. 浏览商品
2. 将商品添加进购物车
3. 结算购物车中的商品
4. 选择送货地址、支付方式
5. 点击付款
6. 完成付款
可以将如上流程设置为一个漏斗，分析整体的转化情况，以及每一步具体的转化率和转化中位时间。同时也可以借助神策强大的筛选和分组功能进行深度分
析。
查看漏斗分析功能应用示例
2. 漏斗界面功能简介
2.1. 创建漏斗
点击界面右侧顶部的“创建漏斗”按钮，会滑出“创建漏斗”面板。2.1.1. 漏斗名称
必填项。给你的漏斗取一个具有代表性的友好名称。同一项目内，漏斗不可重名。你创建的漏斗对同一项目中的其他用户也可见。
2.1.2. 漏斗窗口期
窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化。
你需要在这里根据漏斗的性质选择合理的有效期。默认漏斗有效期为 30 天。1.4 及以后的版本中，除了下拉框中提供的有限选项以外，窗口期也可以由使用
者自定义，最短 1 分钟，最长 3650 天。
2.1.3. 漏斗步骤
步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
一个漏斗中至少包含 2 个步骤，每个步骤对应一个事件（可附带一个或多个筛选条件）。
举例来说，某个步骤可以是触发“注册”且“使用了邀请码”。或者，“购买”且“品类”等于“女装”等。拖动步骤前的序号可以改变步骤顺序。
1.4 及以后的版本，支持给漏斗步骤增加别名，在显示时更加方便易读。
2.1.4. 增加步骤
给漏斗增加更多步骤。
2.1.5. 漏斗属性关联
支持设置漏斗任意几步的属性进行关联，假设需要精确了解用户浏览了某个商品，并完成此商品购买的情况，创建的漏斗为 浏览商品详情页 -> 提交订单 -
> 支付订单，并且在每个事件中设置了商品 ID 的属性，此时就可以将该属性作为关联 ID，以保证用户浏览商品详细页到支付订单的商品都是同一个。如果
不设置商品 ID 为关联属性，则用户浏览商品详细页与支付订单的商品不是同一个，也会被算作转化成功。
漏斗不同步骤关联的属性可以是相同属性，也可以是不同属性，但是要求属性的类型必须一致。例如在浏览商品详情页事件中用商品 ID 标识某个商品，但在
支付订单事件中用产品 ID 标识某个商品，此时就可以分别使用商品 ID 与产品 ID 来设置关联属性。
2.1.6. 保存漏斗
点击该按钮，保存新漏斗。
2.2. 分析漏斗2.2.1. 切换漏斗，按分组查看，筛选
在这个区域，你可以切换需要展示的漏斗数据，或者对现有漏斗查询进行分组和筛选。
分组和筛选条件为三类字段，包括任意步骤的公共属性，每一步的事件属性以及用户属性 。
分组规则
XX 步骤的 YY 属性：按照每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行分组 ，一个用户只会出现在一个分组中，如果用户没有转
化到该步骤则分到未知组
用户属性：按照用户属性筛选
筛选规则
XX 步骤的 YY 属性：以每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行筛选
用户属性：按照用户属性值筛选如果这里选择的属性是数字类型，可以自定义分组区间。如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在
书签中也生效。
2.2.2. 选择查询的时间范围，展示漏斗图表
设置的时间区间默认为漏斗首事件发生的时间范围。如果选中”限制窗口期在时间区间内”，漏斗中各步骤的发生时间在满足窗口期的同时，均被限定在所选
时间区间内。
以电商的限时抢购为例，在 9 月 1 日至 7 日设置的限时抢购，用户该时段内完成交易享受特价优惠，超过限定时间商品恢复原价。该场景下需要精确了解
用户在限订时段完成交易的情况，则需要设置该选项。例如，上图漏斗设置窗口期为 4 天，用户在 9 月 6 日发生了浏览， 9 月 8 日完成了交易，未设定该
选择的漏斗则会把该交易也算为一次该漏斗的转化。设定该选择后，则不会被计算在内。2.2.3. 查看漏斗总体，或每个步骤的转化详情
当选择“趋势”，点击某个具体步骤，可以详细地查看两个步骤之间的流失用户数、转化用户数、转化时间中位数和转化率。当点击“总转化率”节点时，可以
查看总体以及单步的转化率变化趋势，当点击单个步骤时，可以在表格中查看当前步骤的两个事件的触发用户数，流失用户数，转化率以及转化时间中位
数。
当选择“对比”时，可以在“显示设置”中设置对比的两个指标，在下方的漏斗图中直观地对 比两个分组的转化情况，表格中会展示全部的分组，展示漏斗的每一
步事件的转化率和总体转化率。
2.2.4. 漏斗图展示
选择“总览”时，漏斗图每个步骤可以点击，下方表格中可以详细查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。点击分组值前一单
元格的箭头可以对当前分组值展开，详细按天查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。
选择“对比”时，漏斗图为不可点击的，当存在分组时，可以在设置两个分组进行对比。下方表格中可以详细按照当前对比分组查看当前漏斗的每个事件的用
户数和转化率。点击分组值前一单元格中的箭头可以对当前分组值展开，详细按天查看漏斗中每个事件的用户数和转化率。
2.2.5. 浏览用户详情
表格的单元格内的对应数字是可以点击的，点击则会浏览这些用户的用户列表，并进一步 浏览其中某个特定用户的用户行为序列。
2.2.6. 显示设置
当选择“趋势”时，点击“显示设置”可以设置当前折线图的显示指标，点击左侧“总转化率” 节点”，可以设置总转化率以及漏斗的每一步的转化率，点击左侧
单个步骤节点，可以设置 当前步骤的转化率，两个事件流失用户数，以及转化时间中位数。
当选择“对比”时，点击“显示设置”可以设置显示分组，用来对比两个分组值下的漏斗转化 情况。
2.3. 修改、删除漏斗
点击漏斗下拉列表中的“铅笔”图标，可以在滑出的“编辑漏斗”面板中编辑该漏斗。
点击左下角的“删除漏斗”按钮，可以删除当前漏斗。
2.4. 另存为新漏斗进入编辑漏斗页面，修改漏斗名称后点击右下角“另存为新漏斗”按钮，可以保存为一个新的漏斗。
3. 漏斗是如何计算的
在这个文档里面，我们将会详细描述漏斗分析的计算规则，特别是在有筛选和分组情况下的计算规则，以便使用者更好地解读漏斗分析的结果。同时，我们
也会针对一些常见的分析场景，给出漏斗分析的使用案例，帮助使用者更好地使用这一功能。
3.1. 基本计算规则
假设一个漏斗中包含了 A、B、C、D、E 五个步骤，选择的时间范围是 2015 年 1 月 1 日到 2015 年 1 月 3 日，窗口期是 1 天，那么，如果用户在2015
年1月1日到2015年1月3日触发了步骤 A，并且在步骤 A 发生的 1 天内，依顺序依次触发了 B、C、D、E，则视作该用户完成了一次成功的漏斗转化。
在这个过程中，如果穿插了一些其它的步骤或者行为，例如在满足时间限制的情况下，用户的行为顺序是 A > X > B > X > C > D > X > E，X 代表任意一个
事件，则该用户依然视作完成了一次成功的漏斗转化。
如果该用户在这个时间限制范围内，依次触发了 A > B > C > E，则该用户没有完成该漏斗的转化，并且会被记作步骤 C 的流失用户。考虑一个更复杂的情况，如果一个用户在所选时段内有多个事件都符合某个转化步骤的定义，那么会优先选择更靠近最终转化目标的事件作为转化事件，并
在第一次达到最终转化目标时停止转化的计算。假设一个漏斗的步骤定义是：访问首页、选择支付方式、支付成功，那么不同用户的行为序列及实际转化步
骤（标红部分）见如下例子：
1. 例 1：访问首页 -> 选择支付方式（支付宝） -> 选择支付方式（微信）-> 支付成功。
2. 例 2：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功。
3. 例 3：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功 -> 选择支付方式（微信）-> 支付成功。
3.2. 漏斗中展示的数字代表什么
漏斗分析中展示的数字代表转化/流失的独立用户数，而非触发的事件次数。在该时间范围内，即使一个用户多次完成漏斗，也仅计数一次。
3.3. 筛选条件的含义
和其它分析功能一样，漏斗分析也提供了筛选功能，需要特别强调的是，漏斗分析的筛选，都是对完成转化/确认流失的用户，再进行二次挑选。
漏斗分析的筛选，包括三种不同的筛选类型：
1. 用户属性的筛选：这个筛选类型比较好理解，是在完成转化/确认流失的用户的基础上，根据这个用户的属性，再来进行更进一步的筛选。例如，我
们添加的筛选条件是“性别”为“男”，则只有用户属性中“性别”为“男”的用户，才满足这个筛选条件，并且出现在筛选后的漏斗分析结果中；
2. 任意步骤属性的筛选：假设，我们选择了一个筛选条件是任意步骤的属性“省份”为“湖北”，这个筛选表示，在完成转化/确认流失的用户中，找到那
些在所选时间及窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值为“湖北”的那些用户；
3. 指定步骤的属性的筛选：假设，我们选择了一个筛选条件是步骤 2 的属性“支付方式”为“支付宝”，这个筛选表示，在完成转化/确认流失的用户中，
转化到步骤 2 时的“支付方式”的值为“支付宝”的那些用户；如果有多次可能的转化，请参考基本计算规则中的说明。
3.4. 分组的含义
和其它分析功能一样，漏斗分析也提供了分组功能，需要特别强调的是，漏斗分析的分组，都是对完成转化/确认流失的用户的集合上进行分组。
漏斗分析的分组，包括三种不同的分组类型：
1. 用户属性的分组：这个分组比较好理解，是在完成转化/确认流失的用户的集合，根据这个用户的属性，在来进行更进一步的分组。例如，我们添加
的分组条件是“性别”，那么，就会分别对漏斗分析的结果按照“男”、“女”来进行分组；
2. 任意步骤属性的分组：假设，我们选择了的分组属性是任意步骤的属性“省份”，这个表示，在完成转化/确认流失的用户中，根据他们在所选时间及
窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值来进行分组；
3. 指定步骤的属性的分组：假设，我们选择了一个分组属性是步骤 2 的属性“支付方式”，这个筛选表示，在完成转化/确认流失的用户中，按照转化到
步骤 2 时的“支付方式”的值来进行分组；如果有多次可能的转化，请参考基本计算规则中的说明；如果用户没有转化到步骤 2，则分到未知组。
4. FAQ
4.1. 漏斗内的筛选条件和漏斗外的筛选条件的区别
例 1： 漏斗内设置的筛选条件是根据设置的条件得到漏斗，漏斗外设置的筛选条件是根据得到的漏斗筛选出满足筛选条件的漏斗。一般业务上的使用场景是
在漏斗内设置筛选条件，建议直接在漏斗内设置条件得到满足条件的漏斗。 比如漏斗选取的漏斗步骤为 A->B->C->D ，某用户甲的序列是 F->A2->A1-
>A1->B->C->A1->B，事件 A 包含了一个操作系统的属性，其中 A1 的操作系统为 Android， A2 的操作系统为 iOS。如果在漏斗内添加筛选条件操作系
统为 iOS ，那么系统筛选到的序列为 A2->B->C，筛选的原则是沿着该用户的行为序列顺序查找，直到找到属性为 iOS 的 A 事件；如果在漏斗外添加筛选
条件操作系统为 iOS 因为漏斗外筛选是在用户漏斗成功转换后的二次筛选，不加任何筛选条件时，该用户正常的漏斗转化为 A1->B->C,其中 A1 为第二个
A1 ，因此在漏斗外添加筛选条件时该用户筛选不出来。
4.2. 漏斗强制刷新人数会变化
答：（1）若仅第一次刷新时，数据有变化，多次刷新后人数不再变化，则是因为神策查询的缓存机制导致，以刷新后的数据为准。
（2）若多次刷新人数都会变化，通常是因为漏斗相邻事件时间一样，导致的排序不稳定。可以让对应事件的埋点同学调整下事件上报时机，保证两个事件时
间不同即可。如果非上述原因导致可联系神策值班同学。
4.3. 漏斗内某事件的人数和事件分析的触发用户数不一致
答：（1）漏斗内第一步对应的人数与事件分析查询的触发用户数不一致：可能是漏斗查询时，在漏斗外添加了筛选条件，导致和事件分析中对应筛选条件下
人数不一样。可以将筛选条件添加在漏斗内，再对比下查询的数据。如果筛选条件放在漏斗内之后，查询的结果和事件分析一致，则说明查询结果正常。具
体原因可参考问题 1 的漏斗内和漏斗外筛选条件的区别。
（2）漏斗内非第一步事件与事件分析的触发用户数不一致：属于正常数据，因为漏斗内的某事件人数是满足漏斗规则后筛选出的人数，比如漏斗规则为 A-
>B->C，事件分析中 B 事件用户数为 100，漏斗分析中先触发 A 事件再触发 B 事件的用户数为 20。
4.4. 漏斗按天转化率没有总体转化率高答：举个例子，比如 11.01-11.03 这 3 天里有 3 个人，漏斗规则为 A->B->C， 11.01 三个人都触发事件 A ，但只有第一个人在窗口期内完成 B->C 转
化；11.02 三个人都触发事件 A 但只有第二个人在窗口期内完成 B->C 转化 ； 11.03 三个人都触发事件 A 但只有第三个人在窗口期内完成 B->C 转化。
按天分布的话，11.01 的转化率为 33%，11.02 的转化率为 33%。11.03 的转化率为 33%。按总体看，11.01-11.10 这 10 天的转化率为 100%。
4.5. 总体转化率没有漏斗按天转化率高
答：举个例子：，比如 11.01-11.02 这 2 天，漏斗规则为 A->B->C，第一天，a b c 三个人触发了事件 A ，b c 两个人在规定窗口期内完成 B->C 转化，
转化率 66.6%。
第二天，b c d e 四个人触发了事件 A，b c 两个人在规定窗口期内完成 B->C 转化，转化率 50%。
总体，abcde五个人访问，bc下单，转化率 40%。.漏斗分析 v1.14
在介绍漏斗分析之前，需要有一些基本概念进行介绍：
1. 步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
2. 时间范围：在界面上选择的时间范围，是指漏斗的第一个步骤发生的时间范围；
3. 窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化；
漏斗分析概述
漏斗模型主要用于分析一个多步骤过程中每一步的转化与流失情况。
举例来说，用户购买商品的完整流程可能包含以下步骤：
1. 浏览商品
2. 将商品添加进购物车
3. 结算购物车中的商品
4. 选择送货地址、支付方式
5. 点击付款
6. 完成付款
可以将如上流程设置为一个漏斗，分析整体的转化情况，以及每一步具体的转化率和转化中位时间。同时也可以借助神策强大的筛选和分组功能进行深度分
析。
查看漏斗分析功能应用示例
漏斗界面功能简介
创建漏斗
点击界面右侧顶部的“创建漏斗”按钮，会滑出“创建漏斗”面板。漏斗名称
必填项。给你的漏斗取一个具有代表性的友好名称。同一项目内，漏斗不可重名。你创建的漏斗对同一项目中的其他用户也可见。
漏斗窗口期
窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化。
你需要在这里根据漏斗的性质选择合理的有效期。默认漏斗有效期为 30 天。1.4 及以后的版本中，除了下拉框中提供的有限选项以外，窗口期也可以由使用
者自定义，最短 1 分钟，最长 3650 天。
漏斗步骤
步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
一个漏斗中至少包含 2 个步骤，每个步骤对应一个事件（可附带一个或多个筛选条件）。
举例来说，某个步骤可以是触发“注册”且“使用了邀请码”。或者，“购买”且“品类”等于“女装”等。拖动步骤前的序号可以改变步骤顺序。
1.4 及以后的版本，支持给漏斗步骤增加别名，在显示时更加方便易读。
增加步骤
给漏斗增加更多步骤。
漏斗属性关联
支持设置漏斗任意几步的属性进行关联，假设需要精确了解用户浏览了某个商品，并完成此商品购买的情况，创建的漏斗为 浏览商品详情页 -> 提交订单 -
> 支付订单，并且在每个事件中设置了商品 ID 的属性，此时就可以将该属性作为关联 ID，以保证用户浏览商品详细页到支付订单的商品都是同一个。如果
不设置商品 ID 为关联属性，则用户浏览商品详细页与支付订单的商品不是同一个，也会被算作转化成功。
漏斗不同步骤关联的属性可以是相同属性，也可以是不同属性，但是要求属性的类型必须一致。例如在浏览商品详情页事件中用商品 ID 标识某个商品，但在
支付订单事件中用产品 ID 标识某个商品，此时就可以分别使用商品 ID 与产品 ID 来设置关联属性。
保存漏斗
点击该按钮，保存新漏斗。
分析漏斗切换漏斗，按分组查看，筛选
在这个区域，你可以切换需要展示的漏斗数据，或者对现有漏斗查询进行分组和筛选。
分组和筛选条件为三类字段，包括任意步骤的公共属性，每一步的事件属性以及用户属性 。
分组规则
任意步骤的公共属性：按照每个用户该属性的首次有效值进行分组，一个用户只会出 现在一个分组中
XX 步骤的 YY 属性：按照每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行分组 ，一个用户只会出现在一个分组中，如果用
户没有转化到该步骤则分到未知组
用户属性：按照用户属性筛选
筛选规则
任意步骤的公共属性：以每个用户YY属性的首次有效值进行筛选
XX 步骤的 YY 属性：以每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行筛选
用户属性：按照用户属性值筛选如果这里选择的属性是数字类型，可以自定义分组区间。如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在
书签中也生效。
选择查询的时间范围，展示漏斗图表
设置的时间区间默认为漏斗首事件发生的时间范围。如果选中”限制窗口期在时间区间内”，漏斗中各步骤的发生时间在满足窗口期的同时，均被限定在所选
时间区间内。
以电商的限时抢购为例，在 9 月 1 日至 7 日设置的限时抢购，用户该时段内完成交易享受特价优惠，超过限定时间商品恢复原价。该场景下需要精确了解
用户在限订时段完成交易的情况，则需要设置该选项。例如，上图漏斗设置窗口期为 4 天，用户在 9 月 6 日发生了浏览， 9 月 8 日完成了交易，未设定该
选择的漏斗则会把该交易也算为一次该漏斗的转化。设定该选择后，则不会被计算在内。查看漏斗总体，或每个步骤的转化详情
当选择“趋势”，点击某个具体步骤，可以详细地查看两个步骤之间的流失用户数、转化用户数、转化时间中位数和转化率。当点击“总转化率”节点时，可以
查看总体以及单步的转化率变化趋势，当点击单个步骤时，可以在表格中查看当前步骤的两个事件的触发用户数，流失用户数，转化率以及转化时间中位
数。
当选择“对比”时，可以在“显示设置”中设置对比的两个指标，在下方的漏斗图中直观地对 比两个分组的转化情况，表格中会展示全部的分组，展示漏斗的每一
步事件的转化率和总体转化率。
漏斗图展示
选择“总览”时，漏斗图每个步骤可以点击，下方表格中可以详细查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。点击分组值前一单
元格的箭头可以对当前分组值展开，详细按天查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。
选择“对比”时，漏斗图为不可点击的，当存在分组时，可以在设置两个分组进行对比。下方表格中可以详细按照当前对比分组查看当前漏斗的每个事件的用
户数和转化率。点击分组值前一单元格中的箭头可以对当前分组值展开，详细按天查看漏斗中每个事件的用户数和转化率。
浏览用户详情
表格的单元格内的对应数字是可以点击的，点击则会浏览这些用户的用户列表，并进一步 浏览其中某个特定用户的用户行为序列。
显示设置
当选择“趋势”时，点击“显示设置”可以设置当前折线图的显示指标，点击左侧“总转化率” 节点”，可以设置总转化率以及漏斗的每一步的转化率，点击左侧
单个步骤节点，可以设置 当前步骤的转化率，两个事件流失用户数，以及转化时间中位数。
当选择“对比”时，点击“显示设置”可以设置显示分组，用来对比两个分组值下的漏斗转化 情况。
修改、删除漏斗
点击漏斗下拉列表中的“铅笔”图标，可以在滑出的“编辑漏斗”面板中编辑该漏斗。
点击左下角的“删除漏斗”按钮，可以删除当前漏斗。
另存为新漏斗进入编辑漏斗页面，修改漏斗名称后点击右下角“另存为新漏斗”按钮，可以保存为一个新的漏斗。
漏斗是如何计算的
在这个文档里面，我们将会详细描述漏斗分析的计算规则，特别是在有筛选和分组情况下的计算规则，以便使用者更好地解读漏斗分析的结果。同时，我们
也会针对一些常见的分析场景，给出漏斗分析的使用案例，帮助使用者更好地使用这一功能。
基本计算规则
假设一个漏斗中包含了 A、B、C、D、E 五个步骤，选择的时间范围是 2015 年 1 月 1 日到 2015 年 1 月 3 日，窗口期是 1 天，那么，如果用户在2015
年1月1日到2015年1月3日触发了步骤 A，并且在步骤 A 发生的 1 天内，依顺序依次触发了 B、C、D、E，则视作该用户完成了一次成功的漏斗转化。
在这个过程中，如果穿插了一些其它的步骤或者行为，例如在满足时间限制的情况下，用户的行为顺序是 A > X > B > X > C > D > X > E，X 代表任意一个
事件，则该用户依然视作完成了一次成功的漏斗转化。
如果该用户在这个时间限制范围内，依次触发了 A > B > C > E，则该用户没有完成该漏斗的转化，并且会被记作步骤 C 的流失用户。考虑一个更复杂的情况，如果一个用户在所选时段内有多个事件都符合某个转化步骤的定义，那么会优先选择更靠近最终转化目标的事件作为转化事件，并
在第一次达到最终转化目标时停止转化的计算。假设一个漏斗的步骤定义是：访问首页、选择支付方式、支付成功，那么不同用户的行为序列及实际转化步
骤（标红部分）见如下例子：
1. 例 1：访问首页 -> 选择支付方式（支付宝） -> 选择支付方式（微信）-> 支付成功。
2. 例 2：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功。
3. 例 3：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功 -> 选择支付方式（微信）-> 支付成功。
漏斗中展示的数字代表什么
漏斗分析中展示的数字代表转化/流失的独立用户数，而非触发的事件次数。在该时间范围内，即使一个用户多次完成漏斗，也仅计数一次。
筛选条件的含义
和其它分析功能一样，漏斗分析也提供了筛选功能，需要特别强调的是，漏斗分析的筛选，都是对完成转化/确认流失的用户，再进行二次挑选。
漏斗分析的筛选，包括三种不同的筛选类型：
1. 用户属性的筛选：这个筛选类型比较好理解，是在完成转化/确认流失的用户的基础上，根据这个用户的属性，再来进行更进一步的筛选。例如，我
们添加的筛选条件是“性别”为“男”，则只有用户属性中“性别”为“男”的用户，才满足这个筛选条件，并且出现在筛选后的漏斗分析结果中；
2. 任意步骤属性的筛选：假设，我们选择了一个筛选条件是任意步骤的属性“省份”为“湖北”，这个筛选表示，在完成转化/确认流失的用户中，找到那
些在所选时间及窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值为“湖北”的那些用户；
3. 指定步骤的属性的筛选：假设，我们选择了一个筛选条件是步骤 2 的属性“支付方式”为“支付宝”，这个筛选表示，在完成转化/确认流失的用户中，
转化到步骤 2 时的“支付方式”的值为“支付宝”的那些用户；如果有多次可能的转化，请参考基本计算规则中的说明。
分组的含义
和其它分析功能一样，漏斗分析也提供了分组功能，需要特别强调的是，漏斗分析的分组，都是对完成转化/确认流失的用户的集合上进行分组。
漏斗分析的分组，包括三种不同的分组类型：
1. 用户属性的分组：这个分组比较好理解，是在完成转化/确认流失的用户的集合，根据这个用户的属性，在来进行更进一步的分组。例如，我们添加
的分组条件是“性别”，那么，就会分别对漏斗分析的结果按照“男”、“女”来进行分组；
2. 任意步骤属性的分组：假设，我们选择了的分组属性是任意步骤的属性“省份”，这个表示，在完成转化/确认流失的用户中，根据他们在所选时间及
窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值来进行分组；
3. 指定步骤的属性的分组：假设，我们选择了一个分组属性是步骤 2 的属性“支付方式”，这个筛选表示，在完成转化/确认流失的用户中，按照转化到
步骤 2 时的“支付方式”的值来进行分组；如果有多次可能的转化，请参考基本计算规则中的说明；如果用户没有转化到步骤 2，则分到未知组。
FAQ
漏斗内的筛选条件和漏斗外的筛选条件的区别
例 1： 漏斗内设置的筛选条件是根据设置的条件得到漏斗，漏斗外设置的筛选条件是根据得到的漏斗筛选出满足筛选条件的漏斗。一般业务上的使用场景是
在漏斗内设置筛选条件，建议直接在漏斗内设置条件得到满足条件的漏斗。 比如漏斗选取的漏斗步骤为 A->B->C->D ，某用户甲的序列是 F->A2->A1-
>A1->B->C->A1->B，事件 A 包含了一个操作系统的属性，其中 A1 的操作系统为 Android， A2 的操作系统为 iOS。如果在漏斗内添加筛选条件操作系
统为 iOS ，那么系统筛选到的序列为 A2->B->C，筛选的原则是沿着该用户的行为序列顺序查找，直到找到属性为 iOS 的 A 事件；如果在漏斗外添加筛选
条件操作系统为 iOS 因为漏斗外筛选是在用户漏斗成功转换后的二次筛选，不加任何筛选条件时，该用户正常的漏斗转化为 A1->B->C,其中 A1 为第二个
A1 ，因此在漏斗外添加筛选条件时该用户筛选不出来。
漏斗强制刷新人数会变化
答：（1）若仅第一次刷新时，数据有变化，多次刷新后人数不再变化，则是因为神策查询的缓存机制导致，以刷新后的数据为准。
（2）若多次刷新人数都会变化，通常是因为漏斗相邻事件时间一样，导致的排序不稳定。可以让对应事件的埋点同学调整下事件上报时机，保证两个事件时
间不同即可。如果非上述原因导致可联系神策值班同学。
漏斗内某事件的人数和事件分析的触发用户数不一致
答：（1）漏斗内第一步对应的人数与事件分析查询的触发用户数不一致：可能是漏斗查询时，在漏斗外添加了筛选条件，导致和事件分析中对应筛选条件下
人数不一样。可以将筛选条件添加在漏斗内，再对比下查询的数据。如果筛选条件放在漏斗内之后，查询的结果和事件分析一致，则说明查询结果正常。具
体原因可参考问题 1 的漏斗内和漏斗外筛选条件的区别。
（2） 漏斗内非第一步事件与事件分析的触发用户数不一致：属于正常数据，因为漏斗内的某事件人数是满足漏斗规则后筛选出的人数，比如漏斗规则为 A-
>B->C，事件分析中 B 事件用户数为 100，漏斗分析中先触发 A 事件再触发 B 事件的用户数为 20。
漏斗按天转化率没有总体转化率高答：举个例子，比如 11.01-11.03 这 3 天里有 3 个人，漏斗规则为 A->B->C， 11.01 三个人都触发事件 A ，但只有第一个人在窗口期内完成 B->C 转
化；11.02 三个人都触发事件 A 但只有第二个人在窗口期内完成 B->C 转化 ； 11.03 三个人都触发事件 A 但只有第三个人在窗口期内完成 B->C 转化。
按天分布的话，11.01 的转化率为 33%，11.02 的转化率为 33%。11.03 的转化率为 33%。按总体看，11.01-11.10 这 10 天的转化率为 100%。
总体转化率没有漏斗按天转化率高
答：举个例子：，比如 11.01-11.02 这 2 天，漏斗规则为 A->B->C，第一天，a b c 三个人触发了事件 A ，b c 两个人在规定窗口期内完成 B->C 转化，
转化率 66.6%。
第二天，b c d e 四个人触发了事件 A，b c 两个人在规定窗口期内完成 B->C 转化，转化率 50%。
总体，abcde五个人访问，bc下单，转化率 40%。.漏斗分析 v1.16
在介绍漏斗分析之前，需要有一些基本概念进行介绍：
1. 步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
2. 时间范围：在界面上选择的时间范围，是指漏斗的第一个步骤发生的时间范围；
3. 窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化；
漏斗分析概述
漏斗模型主要用于分析一个多步骤过程中每一步的转化与流失情况。
举例来说，用户购买商品的完整流程可能包含以下步骤：
1. 浏览商品
2. 将商品添加进购物车
3. 结算购物车中的商品
4. 选择送货地址、支付方式
5. 点击付款
6. 完成付款
可以将如上流程设置为一个漏斗，分析整体的转化情况，以及每一步具体的转化率和转化中位时间。同时也可以借助神策强大的筛选和分组功能进行深度分
析。
查看漏斗分析功能应用示例
漏斗界面功能简介
创建漏斗
点击界面右侧顶部的“创建漏斗”按钮，会滑出“创建漏斗”面板。漏斗名称
必填项。给你的漏斗取一个具有代表性的友好名称。同一项目内，漏斗不可重名。你创建的漏斗对同一项目中的其他用户也可见。
漏斗窗口期
窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化。
你需要在这里根据漏斗的性质选择合理的有效期。默认漏斗有效期为 30 天。1.4 及以后的版本中，除了下拉框中提供的有限选项以外，窗口期也可以由使用
者自定义，最短 1 分钟，最长 3650 天。
漏斗步骤
步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
一个漏斗中至少包含 2 个步骤，每个步骤对应一个事件（可附带一个或多个筛选条件）。
举例来说，某个步骤可以是触发“注册”且“使用了邀请码”。或者，“购买”且“品类”等于“女装”等。拖动步骤前的序号可以改变步骤顺序。
1.4 及以后的版本，支持给漏斗步骤增加别名，在显示时更加方便易读。
增加步骤
给漏斗增加更多步骤。
漏斗属性关联
支持设置漏斗任意几步的属性进行关联，假设需要精确了解用户浏览了某个商品，并完成此商品购买的情况，创建的漏斗为 浏览商品详情页 -> 提交订单 -
> 支付订单，并且在每个事件中设置了商品 ID 的属性，此时就可以将该属性作为关联 ID，以保证用户浏览商品详细页到支付订单的商品都是同一个。如果
不设置商品 ID 为关联属性，则用户浏览商品详细页与支付订单的商品不是同一个，也会被算作转化成功。
漏斗不同步骤关联的属性可以是相同属性，也可以是不同属性，但是要求属性的类型必须一致。例如在浏览商品详情页事件中用商品 ID 标识某个商品，但在
支付订单事件中用产品 ID 标识某个商品，此时就可以分别使用商品 ID 与产品 ID 来设置关联属性。
保存漏斗
点击该按钮，保存新漏斗。
分析漏斗切换漏斗，按分组查看，筛选
在这个区域，你可以切换需要展示的漏斗数据，或者对现有漏斗查询进行分组和筛选。
分组和筛选条件为三类字段，包括任意步骤的公共属性，每一步的事件属性以及用户属性 。
分组规则
任意步骤的公共属性：按照每个用户该属性的首次有效值进行分组，一个用户只会出 现在一个分组中
XX 步骤的 YY 属性：按照每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行分组 ，一个用户只会出现在一个分组中，如果用
户没有转化到该步骤则分到未知组
用户属性：按照用户属性筛选
筛选规则
任意步骤的公共属性：以每个用户YY属性的首次有效值进行筛选
XX 步骤的 YY 属性：以每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行筛选
用户属性：按照用户属性值筛选如果这里选择的属性是数字类型，可以自定义分组区间。如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在
书签中也生效。
选择查询的时间范围，展示漏斗图表
设置的时间区间默认为漏斗首事件发生的时间范围。如果选中”限制窗口期在时间区间内”，漏斗中各步骤的发生时间在满足窗口期的同时，均被限定在所选
时间区间内。
以电商的限时抢购为例，在 9 月 1 日至 7 日设置的限时抢购，用户该时段内完成交易享受特价优惠，超过限定时间商品恢复原价。该场景下需要精确了解
用户在限订时段完成交易的情况，则需要设置该选项。例如，上图漏斗设置窗口期为 4 天，用户在 9 月 6 日发生了浏览， 9 月 8 日完成了交易，未设定该
选择的漏斗则会把该交易也算为一次该漏斗的转化。设定该选择后，则不会被计算在内。查看漏斗总体，或每个步骤的转化详情
当选择“趋势”，点击某个具体步骤，可以详细地查看两个步骤之间的流失用户数、转化用户数、转化时间中位数和转化率。当点击“总转化率”节点时，可以
查看总体以及单步的转化率变化趋势，当点击单个步骤时，可以在表格中查看当前步骤的两个事件的触发用户数，流失用户数，转化率以及转化时间中位
数。
当选择“对比”时，可以在“显示设置”中设置对比的两个指标，在下方的漏斗图中直观地对 比两个分组的转化情况，表格中会展示全部的分组，展示漏斗的每一
步事件的转化率和总体转化率。
漏斗图展示
选择“总览”时，漏斗图每个步骤可以点击，下方表格中可以详细查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。点击分组值前一单
元格的箭头可以对当前分组值展开，详细按天查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。
选择“对比”时，漏斗图为不可点击的，当存在分组时，可以在设置两个分组进行对比。下方表格中可以详细按照当前对比分组查看当前漏斗的每个事件的用
户数和转化率。点击分组值前一单元格中的箭头可以对当前分组值展开，详细按天查看漏斗中每个事件的用户数和转化率。
浏览用户详情
表格的单元格内的对应数字是可以点击的，点击则会浏览这些用户的用户列表，并进一步 浏览其中某个特定用户的用户行为序列。
显示设置
当选择“趋势”时，点击“显示设置”可以设置当前折线图的显示指标，点击左侧“总转化率” 节点”，可以设置总转化率以及漏斗的每一步的转化率，点击左侧
单个步骤节点，可以设置 当前步骤的转化率，两个事件流失用户数，以及转化时间中位数。
当选择“对比”时，点击“显示设置”可以设置显示分组，用来对比两个分组值下的漏斗转化 情况。
修改、删除漏斗
点击漏斗下拉列表中的“铅笔”图标，可以在滑出的“编辑漏斗”面板中编辑该漏斗。
点击左下角的“删除漏斗”按钮，可以删除当前漏斗。
另存为新漏斗进入编辑漏斗页面，修改漏斗名称后点击右下角“另存为新漏斗”按钮，可以保存为一个新的漏斗。
漏斗是如何计算的
在这个文档里面，我们将会详细描述漏斗分析的计算规则，特别是在有筛选和分组情况下的计算规则，以便使用者更好地解读漏斗分析的结果。同时，我们
也会针对一些常见的分析场景，给出漏斗分析的使用案例，帮助使用者更好地使用这一功能。
基本计算规则
假设一个漏斗中包含了 A、B、C、D、E 五个步骤，选择的时间范围是 2015 年 1 月 1 日到 2015 年 1 月 3 日，窗口期是 1 天，那么，如果用户在2015
年1月1日到2015年1月3日触发了步骤 A，并且在步骤 A 发生的 1 天内，依顺序依次触发了 B、C、D、E，则视作该用户完成了一次成功的漏斗转化。
在这个过程中，如果穿插了一些其它的步骤或者行为，例如在满足时间限制的情况下，用户的行为顺序是 A > X > B > X > C > D > X > E，X 代表任意一个
事件，则该用户依然视作完成了一次成功的漏斗转化。
如果该用户在这个时间限制范围内，依次触发了 A > B > C > E，则该用户没有完成该漏斗的转化，并且会被记作步骤 C 的流失用户。考虑一个更复杂的情况，如果一个用户在所选时段内有多个事件都符合某个转化步骤的定义，那么会优先选择更靠近最终转化目标的事件作为转化事件，并
在第一次达到最终转化目标时停止转化的计算。假设一个漏斗的步骤定义是：访问首页、选择支付方式、支付成功，那么不同用户的行为序列及实际转化步
骤（标红部分）见如下例子：
1. 例 1：访问首页 -> 选择支付方式（支付宝） -> 选择支付方式（微信）-> 支付成功。
2. 例 2：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功。
3. 例 3：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功 -> 选择支付方式（微信）-> 支付成功。
漏斗中展示的数字代表什么
漏斗分析中展示的数字代表转化/流失的独立用户数，而非触发的事件次数。在该时间范围内，即使一个用户多次完成漏斗，也仅计数一次。
筛选条件的含义
和其它分析功能一样，漏斗分析也提供了筛选功能，需要特别强调的是，漏斗分析的筛选，都是对完成转化/确认流失的用户，再进行二次挑选。
漏斗分析的筛选，包括三种不同的筛选类型：
1. 用户属性的筛选：这个筛选类型比较好理解，是在完成转化/确认流失的用户的基础上，根据这个用户的属性，再来进行更进一步的筛选。例如，我
们添加的筛选条件是“性别”为“男”，则只有用户属性中“性别”为“男”的用户，才满足这个筛选条件，并且出现在筛选后的漏斗分析结果中；
2. 任意步骤属性的筛选：假设，我们选择了一个筛选条件是任意步骤的属性“省份”为“湖北”，这个筛选表示，在完成转化/确认流失的用户中，找到那
些在所选时间及窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值为“湖北”的那些用户；
3. 指定步骤的属性的筛选：假设，我们选择了一个筛选条件是步骤 2 的属性“支付方式”为“支付宝”，这个筛选表示，在完成转化/确认流失的用户中，
转化到步骤 2 时的“支付方式”的值为“支付宝”的那些用户；如果有多次可能的转化，请参考基本计算规则中的说明。
分组的含义
和其它分析功能一样，漏斗分析也提供了分组功能，需要特别强调的是，漏斗分析的分组，都是对完成转化/确认流失的用户的集合上进行分组。
漏斗分析的分组，包括三种不同的分组类型：
1. 用户属性的分组：这个分组比较好理解，是在完成转化/确认流失的用户的集合，根据这个用户的属性，在来进行更进一步的分组。例如，我们添加
的分组条件是“性别”，那么，就会分别对漏斗分析的结果按照“男”、“女”来进行分组；
2. 任意步骤属性的分组：假设，我们选择了的分组属性是任意步骤的属性“省份”，这个表示，在完成转化/确认流失的用户中，根据他们在所选时间及
窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值来进行分组；
3. 指定步骤的属性的分组：假设，我们选择了一个分组属性是步骤 2 的属性“支付方式”，这个筛选表示，在完成转化/确认流失的用户中，按照转化到
步骤 2 时的“支付方式”的值来进行分组；如果有多次可能的转化，请参考基本计算规则中的说明；如果用户没有转化到步骤 2，则分到未知组。
FAQ
漏斗内的筛选条件和漏斗外的筛选条件的区别
例 1： 漏斗内设置的筛选条件是根据设置的条件得到漏斗，漏斗外设置的筛选条件是根据得到的漏斗筛选出满足筛选条件的漏斗。一般业务上的使用场景是
在漏斗内设置筛选条件，建议直接在漏斗内设置条件得到满足条件的漏斗。 比如漏斗选取的漏斗步骤为 A->B->C->D ，某用户甲的序列是 F->A2->A1-
>A1->B->C->A1->B，事件 A 包含了一个操作系统的属性，其中 A1 的操作系统为 Android， A2 的操作系统为 iOS。如果在漏斗内添加筛选条件操作系
统为 iOS ，那么系统筛选到的序列为 A2->B->C，筛选的原则是沿着该用户的行为序列顺序查找，直到找到属性为 iOS 的 A 事件；如果在漏斗外添加筛选
条件操作系统为 iOS 因为漏斗外筛选是在用户漏斗成功转换后的二次筛选，不加任何筛选条件时，该用户正常的漏斗转化为 A1->B->C,其中 A1 为第二个
A1 ，因此在漏斗外添加筛选条件时该用户筛选不出来。
漏斗强制刷新人数会变化
答：（1）若仅第一次刷新时，数据有变化，多次刷新后人数不再变化，则是因为神策查询的缓存机制导致，以刷新后的数据为准。
（2）若多次刷新人数都会变化，通常是因为漏斗相邻事件时间一样，导致的排序不稳定。可以让对应事件的埋点同学调整下事件上报时机，保证两个事件时
间不同即可。如果非上述原因导致可联系神策值班同学。
漏斗内某事件的人数和事件分析的触发用户数不一致
答：（1）漏斗内第一步对应的人数与事件分析查询的触发用户数不一致：可能是漏斗查询时，在漏斗外添加了筛选条件，导致和事件分析中对应筛选条件下
人数不一样。可以将筛选条件添加在漏斗内，再对比下查询的数据。如果筛选条件放在漏斗内之后，查询的结果和事件分析一致，则说明查询结果正常。具
体原因可参考问题 1 的漏斗内和漏斗外筛选条件的区别。
（2） 漏斗内非第一步事件与事件分析的触发用户数不一致：属于正常数据，因为漏斗内的某事件人数是满足漏斗规则后筛选出的人数，比如漏斗规则为 A-
>B->C，事件分析中 B 事件用户数为 100，漏斗分析中先触发 A 事件再触发 B 事件的用户数为 20。
漏斗按天转化率没有总体转化率高答：举个例子，比如 11.01-11.03 这 3 天里有 3 个人，漏斗规则为 A->B->C， 11.01 三个人都触发事件 A ，但只有第一个人在窗口期内完成 B->C 转
化；11.02 三个人都触发事件 A 但只有第二个人在窗口期内完成 B->C 转化 ； 11.03 三个人都触发事件 A 但只有第三个人在窗口期内完成 B->C 转化。
按天分布的话，11.01 的转化率为 33%，11.02 的转化率为 33%。11.03 的转化率为 33%。按总体看，11.01-11.10 这 10 天的转化率为 100%。
总体转化率没有漏斗按天转化率高
答：举个例子：，比如 11.01-11.02 这 2 天，漏斗规则为 A->B->C，第一天，a b c 三个人触发了事件 A ，b c 两个人在规定窗口期内完成 B->C 转化，
转化率 66.6%。
第二天，b c d e 四个人触发了事件 A，b c 两个人在规定窗口期内完成 B->C 转化，转化率 50%。
总体，abcde五个人访问，bc下单，转化率 40%。.漏斗分析 v1.17
在介绍漏斗分析之前，需要有一些基本概念进行介绍：
1. 步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
2. 时间范围：在界面上选择的时间范围，是指漏斗的第一个步骤发生的时间范围；
3. 窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化；
漏斗分析概述
漏斗模型主要用于分析一个多步骤过程中每一步的转化与流失情况。
举例来说，用户购买商品的完整流程可能包含以下步骤：
1. 浏览商品
2. 将商品添加进购物车
3. 结算购物车中的商品
4. 选择送货地址、支付方式
5. 点击付款
6. 完成付款
可以将如上流程设置为一个漏斗，分析整体的转化情况，以及每一步具体的转化率和转化中位时间。同时也可以借助神策强大的筛选和分组功能进行深度分
析。
查看漏斗分析功能应用示例
漏斗界面功能简介
创建漏斗
点击界面右侧顶部的“创建漏斗”按钮，会滑出“创建漏斗”面板。漏斗名称
必填项。给你的漏斗取一个具有代表性的友好名称。同一项目内，漏斗不可重名。你创建的漏斗对同一项目中的其他用户也可见。
漏斗窗口期
窗口期：用户完成漏斗的时间限制，也即只有在这个时间范围内，用户从第一个步骤，行进到最后一个步骤，才能被视为一次成功的转化。
你需要在这里根据漏斗的性质选择合理的有效期。默认漏斗有效期为 30 天。1.4 及以后的版本中，除了下拉框中提供的有限选项以外，窗口期也可以由使用
者自定义，最短 1 分钟，最长 3650 天。
漏斗步骤
步骤：由一个 元事件/虚拟事件 加一个或者多个筛选条件组成，表示一个转化流程中的一个关键性的步骤；
一个漏斗中至少包含 2 个步骤，每个步骤对应一个事件（可附带一个或多个筛选条件）。
举例来说，某个步骤可以是触发“注册”且“使用了邀请码”。或者，“购买”且“品类”等于“女装”等。拖动步骤前的序号可以改变步骤顺序。
1.4 及以后的版本，支持给漏斗步骤增加别名，在显示时更加方便易读。
增加步骤
给漏斗增加更多步骤。
漏斗属性关联
支持设置漏斗任意几步的属性进行关联，假设需要精确了解用户浏览了某个商品，并完成此商品购买的情况，创建的漏斗为 浏览商品详情页 -> 提交订单 -
> 支付订单，并且在每个事件中设置了商品 ID 的属性，此时就可以将该属性作为关联 ID，以保证用户浏览商品详细页到支付订单的商品都是同一个。如果
不设置商品 ID 为关联属性，则用户浏览商品详细页与支付订单的商品不是同一个，也会被算作转化成功。
漏斗不同步骤关联的属性可以是相同属性，也可以是不同属性，但是要求属性的类型必须一致。例如在浏览商品详情页事件中用商品 ID 标识某个商品，但在
支付订单事件中用产品 ID 标识某个商品，此时就可以分别使用商品 ID 与产品 ID 来设置关联属性。
保存漏斗
点击该按钮，保存新漏斗。
分析漏斗切换漏斗，按分组查看，筛选
在这个区域，你可以切换需要展示的漏斗数据，或者对现有漏斗查询进行分组和筛选。
分组和筛选条件为三类字段，包括任意步骤的公共属性，每一步的事件属性以及用户属性 。
分组规则
任意步骤的公共属性：按照每个用户该属性的首次有效值进行分组，一个用户只会出 现在一个分组中
XX 步骤的 YY 属性：按照每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行分组 ，一个用户只会出现在一个分组中，如果用
户没有转化到该步骤则分到未知组
用户属性：按照用户属性筛选
筛选规则
任意步骤的公共属性：以每个用户YY属性的首次有效值进行筛选
XX 步骤的 YY 属性：以每个用户首次最长转化状态中的第 XX 步骤的 YY 属性值进行筛选
用户属性：按照用户属性值筛选如果这里选择的属性是数字类型，可以自定义分组区间。如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在
书签中也生效。
选择查询的时间范围，展示漏斗图表
设置的时间区间默认为漏斗首事件发生的时间范围。如果选中”限制窗口期在时间区间内”，漏斗中各步骤的发生时间在满足窗口期的同时，均被限定在所选
时间区间内。
以电商的限时抢购为例，在 9 月 1 日至 7 日设置的限时抢购，用户该时段内完成交易享受特价优惠，超过限定时间商品恢复原价。该场景下需要精确了解
用户在限订时段完成交易的情况，则需要设置该选项。例如，上图漏斗设置窗口期为 4 天，用户在 9 月 6 日发生了浏览， 9 月 8 日完成了交易，未设定该
选择的漏斗则会把该交易也算为一次该漏斗的转化。设定该选择后，则不会被计算在内。查看漏斗总体，或每个步骤的转化详情
当选择“趋势”，点击某个具体步骤，可以详细地查看两个步骤之间的流失用户数、转化用户数、转化时间中位数和转化率。当点击“总转化率”节点时，可以
查看总体以及单步的转化率变化趋势，当点击单个步骤时，可以在表格中查看当前步骤的两个事件的触发用户数，流失用户数，转化率以及转化时间中位
数。
当选择“对比”时，可以在“显示设置”中设置对比的两个指标，在下方的漏斗图中直观地对 比两个分组的转化情况，表格中会展示全部的分组，展示漏斗的每一
步事件的转化率和总体转化率。
漏斗图展示
选择“总览”时，漏斗图每个步骤可以点击，下方表格中可以详细查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。点击分组值前一单
元格的箭头可以对当前分组值展开，详细按天查看当前步骤的事件用户数，转化率，流失用户，以及转化时间中位数。
选择“对比”时，漏斗图为不可点击的，当存在分组时，可以在设置两个分组进行对比。下方表格中可以详细按照当前对比分组查看当前漏斗的每个事件的用
户数和转化率。点击分组值前一单元格中的箭头可以对当前分组值展开，详细按天查看漏斗中每个事件的用户数和转化率。
浏览用户详情
表格的单元格内的对应数字是可以点击的，点击则会浏览这些用户的用户列表，并进一步 浏览其中某个特定用户的用户行为序列。
显示设置
当选择“趋势”时，点击“显示设置”可以设置当前折线图的显示指标，点击左侧“总转化率” 节点”，可以设置总转化率以及漏斗的每一步的转化率，点击左侧
单个步骤节点，可以设置 当前步骤的转化率，两个事件流失用户数，以及转化时间中位数。
当选择“对比”时，点击“显示设置”可以设置显示分组，用来对比两个分组值下的漏斗转化 情况。
修改、删除漏斗
点击漏斗下拉列表中的“铅笔”图标，可以在滑出的“编辑漏斗”面板中编辑该漏斗。
点击左下角的“删除漏斗”按钮，可以删除当前漏斗。
另存为新漏斗进入编辑漏斗页面，修改漏斗名称后点击右下角“另存为新漏斗”按钮，可以保存为一个新的漏斗。
漏斗是如何计算的
在这个文档里面，我们将会详细描述漏斗分析的计算规则，特别是在有筛选和分组情况下的计算规则，以便使用者更好地解读漏斗分析的结果。同时，我们
也会针对一些常见的分析场景，给出漏斗分析的使用案例，帮助使用者更好地使用这一功能。
基本计算规则
假设一个漏斗中包含了 A、B、C、D、E 五个步骤，选择的时间范围是 2015 年 1 月 1 日到 2015 年 1 月 3 日，窗口期是 1 天，那么，如果用户在2015
年1月1日到2015年1月3日触发了步骤 A，并且在步骤 A 发生的 1 天内，依顺序依次触发了 B、C、D、E，则视作该用户完成了一次成功的漏斗转化。
在这个过程中，如果穿插了一些其它的步骤或者行为，例如在满足时间限制的情况下，用户的行为顺序是 A > X > B > X > C > D > X > E，X 代表任意一个
事件，则该用户依然视作完成了一次成功的漏斗转化。
如果该用户在这个时间限制范围内，依次触发了 A > B > C > E，则该用户没有完成该漏斗的转化，并且会被记作步骤 C 的流失用户。考虑一个更复杂的情况，如果一个用户在所选时段内有多个事件都符合某个转化步骤的定义，那么会优先选择更靠近最终转化目标的事件作为转化事件，并
在第一次达到最终转化目标时停止转化的计算。假设一个漏斗的步骤定义是：访问首页、选择支付方式、支付成功，那么不同用户的行为序列及实际转化步
骤（标红部分）见如下例子：
1. 例 1：访问首页 -> 选择支付方式（支付宝） -> 选择支付方式（微信）-> 支付成功。
2. 例 2：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功。
3. 例 3：访问首页 -> 选择支付方式（支付宝） -> 访问首页 -> 选择支付方式（微信）-> 支付成功 -> 选择支付方式（微信）-> 支付成功。
漏斗中展示的数字代表什么
漏斗分析中展示的数字代表转化/流失的独立用户数，而非触发的事件次数。在该时间范围内，即使一个用户多次完成漏斗，也仅计数一次。
筛选条件的含义
和其它分析功能一样，漏斗分析也提供了筛选功能，需要特别强调的是，漏斗分析的筛选，都是对完成转化/确认流失的用户，再进行二次挑选。
漏斗分析的筛选，包括三种不同的筛选类型：
1. 用户属性的筛选：这个筛选类型比较好理解，是在完成转化/确认流失的用户的基础上，根据这个用户的属性，再来进行更进一步的筛选。例如，我
们添加的筛选条件是“性别”为“男”，则只有用户属性中“性别”为“男”的用户，才满足这个筛选条件，并且出现在筛选后的漏斗分析结果中；
2. 任意步骤属性的筛选：假设，我们选择了一个筛选条件是任意步骤的属性“省份”为“湖北”，这个筛选表示，在完成转化/确认流失的用户中，找到那
些在所选时间及窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值为“湖北”的那些用户；
3. 指定步骤的属性的筛选：假设，我们选择了一个筛选条件是步骤 2 的属性“支付方式”为“支付宝”，这个筛选表示，在完成转化/确认流失的用户中，
转化到步骤 2 时的“支付方式”的值为“支付宝”的那些用户；如果有多次可能的转化，请参考基本计算规则中的说明。
分组的含义
和其它分析功能一样，漏斗分析也提供了分组功能，需要特别强调的是，漏斗分析的分组，都是对完成转化/确认流失的用户的集合上进行分组。
漏斗分析的分组，包括三种不同的分组类型：
1. 用户属性的分组：这个分组比较好理解，是在完成转化/确认流失的用户的集合，根据这个用户的属性，在来进行更进一步的分组。例如，我们添加
的分组条件是“性别”，那么，就会分别对漏斗分析的结果按照“男”、“女”来进行分组；
2. 任意步骤属性的分组：假设，我们选择了的分组属性是任意步骤的属性“省份”，这个表示，在完成转化/确认流失的用户中，根据他们在所选时间及
窗口期范围内，A、B、C 三个步骤中任意一个第一次触发时，“省份”的值来进行分组；
3. 指定步骤的属性的分组：假设，我们选择了一个分组属性是步骤 2 的属性“支付方式”，这个筛选表示，在完成转化/确认流失的用户中，按照转化到
步骤 2 时的“支付方式”的值来进行分组；如果有多次可能的转化，请参考基本计算规则中的说明；如果用户没有转化到步骤 2，则分到未知组。
FAQ
漏斗内的筛选条件和漏斗外的筛选条件的区别
例 1： 漏斗内设置的筛选条件是根据设置的条件得到漏斗，漏斗外设置的筛选条件是根据得到的漏斗筛选出满足筛选条件的漏斗。一般业务上的使用场景是
在漏斗内设置筛选条件，建议直接在漏斗内设置条件得到满足条件的漏斗。 比如漏斗选取的漏斗步骤为 A->B->C->D ，某用户甲的序列是 F->A2->A1-
>A1->B->C->A1->B，事件 A 包含了一个操作系统的属性，其中 A1 的操作系统为 Android， A2 的操作系统为 iOS。如果在漏斗内添加筛选条件操作系
统为 iOS ，那么系统筛选到的序列为 A2->B->C，筛选的原则是沿着该用户的行为序列顺序查找，直到找到属性为 iOS 的 A 事件；如果在漏斗外添加筛选
条件操作系统为 iOS 因为漏斗外筛选是在用户漏斗成功转换后的二次筛选，不加任何筛选条件时，该用户正常的漏斗转化为 A1->B->C,其中 A1 为第二个
A1 ，因此在漏斗外添加筛选条件时该用户筛选不出来。
漏斗强制刷新人数会变化
答：（1）若仅第一次刷新时，数据有变化，多次刷新后人数不再变化，则是因为神策查询的缓存机制导致，以刷新后的数据为准。
（2）若多次刷新人数都会变化，通常是因为漏斗相邻事件时间一样，导致的排序不稳定。可以让对应事件的埋点同学调整下事件上报时机，保证两个事件时
间不同即可。如果非上述原因导致可联系神策值班同学。
漏斗内某事件的人数和事件分析的触发用户数不一致
答：（1）漏斗内第一步对应的人数与事件分析查询的触发用户数不一致：可能是漏斗查询时，在漏斗外添加了筛选条件，导致和事件分析中对应筛选条件下
人数不一样。可以将筛选条件添加在漏斗内，再对比下查询的数据。如果筛选条件放在漏斗内之后，查询的结果和事件分析一致，则说明查询结果正常。具
体原因可参考问题 1 的漏斗内和漏斗外筛选条件的区别。
（2）漏斗内非第一步事件与事件分析的触发用户数不一致：属于正常数据，因为漏斗内的某事件人数是满足漏斗规则后筛选出的人数，比如漏斗规则为 A-
>B->C，事件分析中 B 事件用户数为 100，漏斗分析中先触发 A 事件再触发 B 事件的用户数为 20。
漏斗按天转化率没有总体转化率高答：举个例子，比如 11.01-11.03 这 3 天里有 3 个人，漏斗规则为 A->B->C， 11.01 三个人都触发事件 A ，但只有第一个人在窗口期内完成 B->C 转
化；11.02 三个人都触发事件 A 但只有第二个人在窗口期内完成 B->C 转化 ； 11.03 三个人都触发事件 A 但只有第三个人在窗口期内完成 B->C 转化。
按天分布的话，11.01 的转化率为 33%，11.02 的转化率为 33%。11.03 的转化率为 33%。按总体看，11.01-11.10 这 10 天的转化率为 100%。
总体转化率没有漏斗按天转化率高
答：举个例子：，比如 11.01-11.02 这 2 天，漏斗规则为 A->B->C，第一天，a b c 三个人触发了事件 A ，b c 两个人在规定窗口期内完成 B->C 转化，
转化率 66.6%。
第二天，b c d e 四个人触发了事件 A，b c 两个人在规定窗口期内完成 B->C 转化，转化率 50%。
总体，abcde五个人访问，bc下单，转化率 40%。留存分析.留存分析 v1.13
1. 留存分析概述
留存分析是一种用来分析用户参与情况/活跃程度的分析模型，考查进行初始行为后的用户中，有多少人会进行后续行为。这是衡量产品对用户价值高低的重
要指标。
留存分析可以帮助回答以下问题：
一个新客户在未来的一段时间内是否完成了您期许用户完成的行为？如支付订单
某个社交产品改进了新注册用户的引导流程，期待改善用户注册后的参与程度，如何验证？
想判断某项产品改动是否奏效，如新增了一个邀请好友的功能，观察是否有人因新增功能而多使用产品几个月？
查看留存分析功能应用示例
2. 留存分析界面功能简介
2.1. 选择初始行为和后续行为
初始行为和后续行为的选择有两种策略：
1. 初始行为选择用户只触发一次的事件，比如“注册”、“上传头像”、“激活设备”等，后续行为选择你期望用户重复触发的事件，比如“阅读文章”、
“发帖”、“购买”等。这种留存用于对比分析不同阶段开始使用产品的新用户的参与情况，从而评估产品迭代或运营策略调整的得失。
2. 初始行为和后续行为选择相同的，期待用户重复触发的事件。这种留存用于分析忠实用户的使用模式。
2.2. 设置初始行为和后续行为筛选条件
针对事件的属性，可以根据具体需求筛选初始行为或后续行为的细分维度。比如，我们想分析北京地区的用户注册后，后续购买手机的留存情况，那么可以
定 义初 始 行为 是“ 注 册 ”， 同时 添 加筛 选 条 件 “城 市等 于 北京 ”， 后续 行 为是 “支 付订 单 的商 品 细 节” ， 同时 添 加筛 选 条 件“ 商 品类 型 等于 手 机” ， 即可 满 足分 析 需
求。
2.3. 设置用户筛选条件
针对用户属性，筛选合适的分析对象。比如，只查看女性用户的留存情况。2.4. 选择考查的时间段
这里选择的时间范围是初始行为事件发生的时间范围，如上图选择“7 天留存”，后续事件发生时间范围的截止日期会被延展到 2017 年 1 月 4 日（ 2016
年 12 月 28 日向后延展 7 天）。
可以按照日、周、月查看不同时间体量下的留存/流失情况。1.6.5 版提供了查看流失用户的功能，在上图圈红处点击可以选择流失时间。
留存分析中流失用户的定义是连续多“天”(不包含当天，即从触发初始行为事件之后，从第 1 天开始计算，连续多“天”)没有发生后续事件才认为是流失用
户，如上图“第2天”流失是指 103,582 人进行初始事件后持续 2 天没有进行后续事件（不考虑用户在 6-6 号当天是否触发过后续事件）。
2.5. 设置关联属性
支持设置初始行为事件和后续行为事件的属性进行关联。不同事件关联的属性可以是相同属性，也可以是不同属性，但是要求属性的类型必须一致。 举例：
某内容类网站想要知道各页面的七日留存，因此需要在初始行为事件App 和后续行为事件 App 中添加关联属性页面标题，此时就会按照该属性进行关
联，以保证用户严格按照该模式配对。2.6. 留存表格
留存表格默认按照初始行为日期分组。每行的第一列代表了初始行为日期；第二列是在该日期触发了初始行为的总人数（独立用户数）；后面各列，分别是
在相应时间后触发后续行为的用户数，以及占初始行为人数的百分比。
除了可以按照初始行为日期进行分组查看外，还可以分别按照初始行为事件属性或后续行为事件属性进行分组查看。如选择初始行为事件属性按注册渠道进
行分组，我们则可以看到不同注册渠道的后续留存情况。
需要注意的是，当开启设置关联属性后，仅支持按照初始事件的关联属性进行分组查看。如选择初始行为事件和后续行为事件的关联属性为页面标题，则可
以看到不同页面的后续留存情况。
觉得有点复杂？没关系，鼠标悬浮到每个单元格上，会有文字提示告诉你这个单元格的具体含义。同时，单元格的背景颜色也能直观反映留存情况。如果这里选择的属性是数字类型，可以自定义分组区间。如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在
书签中也生效。
2.7. 浏览用户详情
表格的单元格内的数字是可以点击的，点击可以浏览这些用户的详细信息，并且进一步浏览其中单个用户的详细行为序列。
2.8. 留存变化趋势曲线
用另一种可视化方式，体现不同分组的留存情况对比。
3. 留存是如何计算的
留存分析中展示的数字代表独立用户数。表示在选定时间范围内进行了初始行为的用户，有多少人在随后的第 n 天/周/月进行了后续行为。
3.1. 基本计算规则
假设定义的初始行为是 A 事件，后续行为是 B 事件，筛选时间段为 2015 年 1 月 1 日到 2015 年 1 月 8 日，注意这个时间范围是事件 A 发生的时间范
围，事件 B 发生的时间范围是 2015 年 1 月 1日到 1 月 15 日（1 月 8 日加上 7 天）。
3.2. 未设置关联属性
下表为某用户2015 年 1 月 1 日到 2015 年 1 月 8 日的真实行为序列和纳入计算的行为序列（保留用户当日首个初始行为事件或后续行为事件）。表格
中，字母 A 和 B 为事件，数字 1，2，3 为该用户某个属性的属性值。
日期 真实行为序列 纳入计算的行为序列
01-01 A1,A2,A2 A1
01-02 B2,B1,B1 B2
01-03 A3,A1,A1 A3
01-04 A1,A3,A3 A1
01-05 A1,A3,A3 A1
01-06 B1,B2,B1 B1
01-07 A1,A2 A101-08 B2,B1,B3 B2
1. 不加分组，如果指定初始行为日期为 2015 年 1 月 1 日，则该用户分别是第 1 天，第 5 天，第 7 天的留存用户。
2. 按初始行为事件 A 的属性分组，如果用户完成事件 A 的属性值各不相同，该用户只会被归到 1 月 1 日 发生的首个 A 事件的属性值 1 中。去重后，该用
户分别是属性值 1 的第 1 天，第 2 天，第 3 天，第 4 天，第 5 天，第 7 天的留存用户。
3. 按后续行为事件 B 的属性分组，如果用户完成事件 B 的属性值各不相同，该用户只会被归到 1 月 2 日 发生的首个 B 事件的属性值 2 中。去重后，该用
户分别是属性值 2 的第 1 天，第 2 天，第 3 天，第 4 天，第 5 天，第 7 天的留存用户。
4. 按用户属性分组，比如按性别分组，若用户为女性，则该用户分别是属性值女性的第 1 天，第 2 天，第 3 天，第 4 天，第 5 天，第 7 天的留存用户。
3.2.1. 设置关联属性
下表为某用户 2015 年 1 月 1 日到 2015 年 1 月 8 日的真实行为序列和纳入计算的行为序列（同一天内初始行为事件或后续行为事件不同属性值各保留一
个，且保留首个）。表格中，字母 A 和 B 为事件，数字 1，2，3 为该用户某个属性的属性值。
日期 真实行为序列 纳入计算的行为序列（属性值1） 纳入计算的行为序列（属性值 2）
01-01 A1,A2,A2 A1 A2
01-02 B2,B1,B1 B1 B2
01-03 A3,A1,A1 A1
01-04 A1,A3,A3 A1
01-05 A1,A3,A3 A1
01-06 B1,B2,B1 B1 B2
01-07 A1,A2 A1 A2
01-08 B2,B1,B3 B1 B2
按初始行为事件 A 的属性分组，如果按属性值 1 分组，则关联属性值为 1 的初始行为事件或后续行为事件才会纳入计算，该用户分别是属性值 1 的第 1
天，第 2 天，第 3 天，第 4 天，第 5 天，第 7 天的留存用户。如果按属性值 2 分组，则关联属性值为 2 的初始行为事件或后续行为事件才会纳入计算，
该用户分别是属性值 2 的第 1 天，第 5 天，第 7 天的留存用户。同理，该用户分别是属性值 3 的第 3 天，第 4 天，第 5 天的留存用户。
3.3. 筛选条件的含义
和其他分析功能一样，留存分析也提供了筛选功能。留存分析的筛选提供了两种不同的筛选类型。
1. 用户属性上的筛选：例如，我们添加的筛选条件是“性别”为“男”，则只有属性中“性别”为“男”的用户，才满足这个筛选条件，并且出现在筛选后的
留存分析结果中；
2. 事件属性的筛选：和漏斗的触发限制条件含义相同，指定事件满足指定属性的过滤。
3.4. 分组的含义
留存分析提供了两种不同的分组类型。我们以一个初始行为是 A，后续行为是 B，时间范围是 2015 年 1 月 1 日到 1 月 8 日的 7 天留存来进行详细说明：
1. 用户属性上的分组：根据用户属性来进行更进一步的分组。例如我们添加的分组条件是“性别”，那么，就会分别对留存分析的结果按照“男”、“女”
来进行分组；
2. 事件属性的分组：例如，我们选择的分组设置是初始行为的属性“屏幕高度”，则这个分组表示，在 2015 年 1 月 1 日到 1 月 15 日这个时间范围
内，按初始行为的“屏幕高度”这个属性的值来对他们进行分组；下面是几个具体的例子的描述:
a. 某个用户在这个时间段内的行为序列是 A、B、C、A、B，第一次出现的 A 的“屏幕高度”值为“320”，第二次出现的 A 的“屏幕高度”值为
“1080”，因为按照首次出现的 A 事件的“屏幕高度”来分组，所以这个用户会被划分到“320”这个分组的统计结果中;
b. 某个用户在这个时间段内的行为序列是 A、A，这个用户在初始行为 A 事件后没有后续行为。第一次出现的 A 的“屏幕高度”值为
“1080”，第二次出现的 A 的“屏幕高度”值为“320”，因为按照首次出现的 A 事件的“屏幕高度”来分组，所以这个用户会被划分到“1080” 这
个分组的统计结果中；
4. FAQ
4.1. 为什么要做留存分析？看活跃用户百分比不够吗？
按初始行为时间分组的留存分析可以消除用户增长对用户参与数据带来的影响。如果产品目前处于快速增长阶段，很有可能新用户中的活跃用户数增长掩盖
了老用户活跃度的变化。通过留存分析，你可以将用户按照注册时间分段查看，得出类似如下结论：“三月份改版前，该月注册的用户 7 天留存只有 15%；
但是四月份改版后，该月注册的用户 7 天留存提高到了 20%。” 同理，按照非时间维度的留存分析具有类似价值，比如，可以查看新功能上线之后，对不同性
别用户的留存是否带来不同效果。我们在分析用户的留存时，一定要根据实际的业务需求，找到有价值的后续行为，对用户的价值留存进行分析，才能对产
品的优化和改进提供实质性指导建议。分布分析.分布分析 v1.15
1. 分布分析概述
在 1.6 版本将“回访分析”升级为“分布分析”，分布分析不但可以告诉你用户有多依赖你的产品，还可以告诉你某个事件指标的用户分布情况。比如，查看订单
金额在 100 元以下、100 元至 200 元、200 元以上三个区间的用户分布情况。
指定一个用户行为事件，然后选择事件的指标。分布分析可以帮助揭示以下问题：
通知策略调整前后，用户每天使用产品次数是否增加？
用户首次购买后是否会重复购买？
假设每天使用 3 次以上某关键功能的用户算作核心用户，那么核心用户的成分变化趋势如何？
查看分布分析功能应用示例
2. 分布分析按时间统计
2.1. 选择用户行为
选择某个事件作为考查的行为。这里可以选择『客户付费』。
2.2. 选择指标
在这里选择分布分析的指标，可以选择“小时数”或“天数”等时间单位，以下以“小时数”为例。
2.3. 选择时间单位
选择行为发生的统计时间单位（在图 c 处选择按时间段还是次数进行分析）。可以选择：
一天内： 用户在 0:00-23:59 这 24 小时中的行为分布。
一周内： 用户在周一到周日这 7 天内的行为分布。
一个月内： 用户在不同月份的第一天到最后一天的行为分布。2.4. 设置所选事件的筛选条件
比如，只查看 iOS 版本的行为分布。
2.5. 设置用户筛选条件
针对用户属性，筛选合适的分析对象。比如，只查看女性用户的行为分布。
2.6. 行为分布表格
第一列是用户选定的查询时间段，按照事件发生时间单位（天/周/月）划分。第二列是在相应时间范围发生行为的总用户数。后面各列，分别是发生行为相
应频率的用户数和比例。
鼠标悬停在单元格上，可以查看每个单元格数字代表的具体含义。
点击这个数字，则可以看到这些用户的详细信息，并且更进一步看到其中单个用户的详细行为序列。
2.7. 自定义分组区间如果这里选择的属性是数字类型，可以自定义分组区间。如果没有设置，查询引擎会动态计算分组区间。此设置仅在当前查询生效，将查询保存为书签后在
书签中也生效。
鼠标浮动在表格的单元格内时，会出现下载连接，点击即可下载用户详情。
3. 分布分析按次数统计3.1. 选择『次数』
选择次数统计按照实际发生次数不去重。 也可以设置自定义分组区间。
3.2. 行为分布表格
以 b 在表格进行说明，在 9-1(四)这一天内进行过『客户付费』的用户有 12 人，其中有 12 人进行了 1 次 ~ 3 次（不含 3 次）。
4. 分布分析按事件指标统计
指标选择“合同金额的总和”，在 8-29 当周有 63 人进行了付费，付费金额在 50000 ~ 100000 (不包含)之间的用户有 5 人。
5. 分布分析是如何计算的分布分析有三种统计方法，按时间段统计、按次数统计和按事件属性的统计指标。选择次数和事件的指标时可以自定义区间。
5.1. 按时间段统计
统计用户在一天/周/月中，有多少个自然时间段（小时/天）进行了某项操作。
以『一天内』进行『点击广告』的『小时数』分析为例来说明。如果某用户在 15:00 到 16:00 间进行了『点击广告』3 次，17:00 到 18:00 间进行了『点
击广告』1 次，则统计为『一天至少在 2 个时段进行点击广告』, 用户在某小时内进行『点击广告』一次或多次，都记 1 次。
对于查看用户一周/一月内某事件的天数，则是统计用户在一周/月中触发过某事件的天数。
5.2. 按次数统计
统计用户在一天/周/月中，进行某项操作的次数，发生一次就记录一次。
5.3. 按事件属性的统计指标统计
统计用户在一天/周/月中，发生事件的某属性的统计指标值。属性的统计指标与事件分析一致，有总和、均值、最大值、最小值、去重数。
6. FAQ
6.1. 分布分析比单看日活（DAU）优越在哪里？
日活只能告诉你用户数的变化，分布分析却能揭示单个用户对产品依赖程度的变化。比如某产品虽然三月和四月期间活跃用户量没有明显增长，但是用户关
键行为（比如下单，或发布内容）的频率却显著增加，说明产品对于用户的价值增加了。反之，如果虽然日活增长很快，但是行为发生频率却在相比之前较
低的水平，很有可能新增加的活跃用户并未真正感受到产品价值。归因分析.归因分析 v1.15
1. 功能概述
业务上需要分析某个广告位、推广位对目标事件的转化贡献时，可以使用归因分析模型进行分析。在归因分析模型中，广告位的点击、推广位的点击被称为
「待归因事件」，支付订单等目标类事件被称为「目标转化事件」。
2. 使用说明
归因分析模块由两个大部分组成，分别为：
归因事件与模型选择区
归因结果表格展示区
2.1. 归因事件与模型选择目标转化事件：
选择产品的目标事件，一般为与收益相关的事件，如：提交订单详情、支付...
支持选择全部的元事件
目标转化事件的高级设置：
前向关键事件
选择目标转化事件的前向事件，主要是为了提升归因模型的计算精度。一般选择与目标事件有强关联的事件，类似商品
曝光，如：查看商品详情、加入购物车...
关联属性：将目标转化事件和前向关键事件进行关联的属性
待归因事件
选择待归因事件，一般为与广告曝光、推荐曝光等运营相关事件，如：点击广告位、点击推荐位...
支持选择全部的元事件
归因模型
首次触点模型：多个「待归因事件」对同一个「目标转化事件」作出贡献时，认为第一个「待归因事件」功劳为 100%
末次触点归因：多个「待归因事件」对同一个「目标转化事件」作出贡献时，认为最后一个「待归因事件」功劳为 100%
线性归因：多个「待归因事件」对同一个「目标转化事件」作出贡献时，认为每个「待归因事件」平均分配此次功劳
位置归因：多个「待归因事件」对同一个「目标转化事件」作出贡献时，认为第一个和最后一个「待归因事件」各占 40% 功劳，其余
「待归因事件」平分剩余的 20% 功劳
时间衰减归因：多个「待归因事件」对同一个「目标转化事件」作出贡献时，认为越靠近「目标转化事件」做出的贡献越大
2.2. 归因结果表格展示区使用表格展示每个「待归因事件」与「目标转化事件」的贡献次数、贡献度。
「待归因事件」的分组与「目标转化事件」的指标切换
点击「待归因事件」的分组
使用多个「待归因事件」的共同属性进行分组
点击「目标转化事件」的指标切换若事件包含数值类属性，则次数可以选择「数值类属性的总和」作为指标
指标解释说明：
总点击数：在选择的时间范围内（额外增加上窗口期），该广告位的总点击数量
有效转化点击率：在选择的时间范围内（额外增加上窗口期），与本次的目标转化有关联的广告点击。
比如：设置目标为支付订单，回溯时长为 1 天，若 3 日前点击了广告，则不会被判定为有效转化。用户路径分析.用户路径分析 v1.15
1. 用户路径分析概述
用户路径分析主要用于分析用户在使用产品时的路径分布情况。
例如，在访问了某个电商产品首页的用户后，有多大比例的用户进行了搜索，有多大比例的用户访问了分类页，有多大比例的用户直接访问的商品详情页。
2. 用户路径分析界面功能简介
点击左侧功能栏“用户路径”可以进入用户路径分析界面。
2.1. 设置查询条件
2.1.1. 添加分析事件
点击下拉按钮可以选择要分析的事件，点击右侧“＋事件分组”可以为每个事件添加分组，当前只支持一个事件最多一个分组。
2.1.2. 设置起始或者结束事件
可以设置选择的事件组中某个事件为分析的起始事件或者结束事件。点击右侧“+筛选条件”可以给该事件添加筛选条件。点击下方“+筛选条件”可以给用户添
加筛选条件。2.1.3. 设置session间隔
必填项。可选单位为“分钟”“小时”。
2.1.4. 设置时间区间
设置要分析的时间区间，意味着要分析的事件都发生在该时间区间内，选定后再对用户和事件进行分析。支持相对时间和绝对时间。
2.2. 查询
用户设置好以上查询条件，点击“查询”按钮即可。
2.3. 查看分析结果如上图所示，分析结果以桑基图形式展现，以目标事件为起点／终点，详细查看后续／前置路径，可以详细查看某个节点事件的流向，基于性能考虑，初始
时只最大展示四级路径。
点击右下角可以逐层添加展示层数。
2.4. 高亮显示当前路径如上图所示，点击要查看的节点，选择高亮当前路径，即可查看经过该事件的 session 。
2.5. 查看节点详情对于每个事件节点，可以点击该节点，选择 ，即可查看当前节点事件的相关信息，包括 ，（如果有分组的话），，， ，。其中 中会详细列出当前事件的会
话数和分组值（如果有分组的话）。更进一步，可以点击每一行末尾的图标查看对应的用户列表，进而查看每个用户的行为序列。值得注意的是，在详细信
息中展示的是会话数，并不是用户数， 所以会话数和用户列表中的用户数不一定一致。
2.6. 起始/结束事件支持分组展示这里并没有为起始／结束事件单独设置添加分组的选项，而是在设置查询条件时统一添加。
3. FAQ
3.1. 为什么选用不同的 Session 间隔，展示的结果会不一样？
答：选取不同的 Session 间隔，会按照不同的时间来对事件进行切割处理，所以结果会有不同。.用户路径分析 v1.17
1. 用户路径分析概述
用户路径分析主要用于分析用户在使用产品时的路径分布情况。
例如，在访问了某个电商产品首页的用户后，有多大比例的用户进行了搜索，有多大比例的用户访问了分类页，有多大比例的用户直接访问的商品详情页。
2. 用户路径分析界面功能简介
点击左侧功能栏“用户路径”可以进入用户路径分析界面。
2.1. 设置查询条件
2.1.1. 添加分析事件
点击下拉按钮可以选择要分析的事件，点击右侧“＋事件分组”可以为每个事件添加分组，当前只支持一个事件最多一个分组。如果所选内容包含虚拟事件，
则分析结果虚拟事件会以一个整体进行分流计算。
所选分析事件中可能包含某些「虚拟事件」与已选「元事件」部分条件重叠或完全包含，也有可能会出现多个「虚拟事件」用到相同的元事件。那么我们将
采用此策略进行优先分流计算的依据。
若参与事件选择了虚拟事件，则会直接展示为虚拟事件。
若虚拟事件和其包含的元事件都在参与事件中，则该元事件按照（起止事件、虚拟事件、元事件）优先级进行归属。
若多个虚拟事件包含相同的元事件，则该元事件按照事件筛选列表顺序归属于第一个虚拟事件。
2.1.2. 设置起始或者结束事件
可以设置选择的事件组中某个事件为分析的起始事件或者结束事件。点击右侧“+筛选条件”可以给该事件添加筛选条件。点击下方“+筛选条件”可以给用户添
加筛选条件。
2.1.3. 设置session间隔必填项。可选单位为“分钟”“小时”。
2.1.4. 设置时间区间
设置要分析的时间区间，意味着要分析的事件都发生在该时间区间内，选定后再对用户和事件进行分析。支持相对时间和绝对时间。
2.2. 查询
用户设置好以上查询条件，点击“查询”按钮即可。
2.3. 支持按虚拟事件为主体进行结果分流
若参与事件选择了虚拟事件，则会直接展示为虚拟事件。
若虚拟事件和其包含的元事件都在参与事件中，则该元事件按照（起止事件、虚拟事件、元事件）优先级进行归属。
若多个虚拟事件包含相同的元事件，则该元事件按照事件筛选列表顺序归属于第一个虚拟事件。2.4. 可视化分析结果
如图所示，分析结果以桑基图形式展现，以目标事件为起点／终点，详细查看后续／前置路径，可以详细查看某个节点事件的流向，基于性能考虑，初始时
只最大展示四级路径。
点击右下角可以逐层添加展示层数。同时支持一键导出「桑基图分析结果图片」便于用户汇报应用。
2.5. 高亮显示当前路径如上图所示，点击要查看的节点，选择高亮当前路径，即可查看经过该事件的 session 。
2.6. 查看节点详情对于每个事件节点，可以点击该节点，选择 ，即可查看当前节点事件的相关信息，包括 ，（如果有分组的话），，， ，。其中 中会详细列出当前事件的会
话数和分组值（如果有分组的话）。更进一步，可以点击每一行末尾的图标查看对应的用户列表，进而查看每个用户的行为序列。值得注意的是，在详细信
息中展示的是会话数，并不是用户数， 所以会话数和用户列表中的用户数不一定一致。
2.7. 起始/结束事件支持分组展示这里并没有为起始／结束事件单独设置添加分组的选项，而是在设置查询条件时统一添加。
3. FAQ
3.1. 为什么选用不同的 Session 间隔，展示的结果会不一样？
答：选取不同的 Session 间隔，会按照不同的时间来对事件进行切割处理，所以结果会有不同。网页热力分析.网页热力分析 v1.13
1. 登录网页热力分析概述
网页热力分析主要用来分析用户在网页上的点击、触达深度等情况，并以直观的效果展示给使用者。 关于点击图分析的应用，可参考：如何运用点击分析优
化产品体验
2. 网页热力分析功能简介
2.1. 原始页面
对这个页面的说明如下，对于点击图：
1. 显示内容：分为和两类。是用来分析单个页面的点击情况，而则用来分析一系列界面结构相似的网页整体的浏览和点击情况（例如京东的商品详情
页，可以整体作为一个来进行分析）。
2. 事件筛选条件：与神策分析所有其它分析功能一样，网页热力分析也可以根据事件的属性进行筛选，只看符合筛选条件的事件，需要说明的是，点
击分析的筛选条件是事件 Web 和 Web 的公共属性。
3. 用户符合：神策分析所有其它分析功能一样，网页热力分析也可以按照用户属性来做筛选。
4. 选择事件Web的发生时间，只分析这个时间内的用户点击情况。
5. 这块区域默认是按照页面浏览量来排序的，也可以按照浏览用户数和元素点击次数来进行排序。页面名指的是我们采集到的页面标题。
6. 浏览量，这个页面的浏览 PV，也即事件 Web 的总次数。
7. 用户数，这个页面的上各个交互元素的点击 UV，也即事件Web 的触发用户数。
8. 点击次数，这个页面上各个交互元素的被点击次数，也即事件 Web 的总次数。
2.2. 页面组对这个页面的说明如下：
1. 给页面组定义一个名称。
2. 背景页面，指定一个具体的页面地址，作为点击图展示的模版页面。
3. 选择要添加的页面地址，可以使用包含和正则来匹配。
4. 可以选择多个筛选条件。
5. 保存这个页面组。
3. 点击图使用说明这里以神策官网作为模版页面（点击数据是模拟的），来介绍点击分析功能的具体使用：
1. 表示被点击过的交互元素，这里显示的 0.81% 是点击率。鼠标悬浮上这些被点击过的按钮上时，会显示点击详情信息框。而如果鼠标点击这个交互
元素，则会按照原页面的逻辑进行相应的交互；
2. 当前元素内容，指这个交互元素里面的文本内容；
3. 点击次数，这个按钮点击了多少次；
4. 点击率，这个元素的点击次数／整个页面的浏览次数（PV）；
5. 点击占比，这个元素点击次数／整个页面内所有可见元素的总点击次数；
6. 历史内容，表示取这个按钮历史最常出现的值。例如如果是新闻的话，头条位置的新闻每天是不同的；
7. 点击用户列表，查看点击过这个按钮的具体用户是哪些人；
8. 在新窗口打开，直接在原始页面里展示点击图，这种方式看数据更加自然；
9. 下拉切换点击图和触达率图；
10. 点击率对应的图例；
11. 刷新当前页面的数据；
12. 收起工具栏。
4. 点击图不同版本切换（1.12.1以上版本支持）
4.1. (一)两版点击图区别
4.1.1. 第一版点击图
在点击元素本身上进行样式修改，通过添加after和before的伪元素来给元素添加样式，并且会将所有a标签变为inline-block的样式。
如果页面上的点击元素本来就设置了after和before的样式，可能会产生样式冲突的问题，导致页面上的某些元素没有点击图，或者页面结构发生变化。
4.1.2. 第二版点击图
根据点击元素在屏幕上的相对位置在页面最顶层生成一层点击图，每次滚动滚动条，或者改变页面大小时会重新渲染点击图。
第二版点击图不会修改点击元素原本的样式，可以有效避免样式冲突的问题。
第二版点击图不会渲染隐藏的元素，但对于某些通过父元素overflow:hidden等方式来隐藏的元素，无法判断是隐藏的还是显示的，也会将其渲染出来。4.2. (二)切换点击图方法
1.通过左上角的第一版/第二版按钮进行切换
2.通过键盘上的快捷键进行切换
''z''键：第一版点击图
''x''键：第二版点击图
4.3. 刷新点击图方法
第二版点击图根据屏幕的相对位置进行点击元素的渲染，所以每次滚动滚动条和更改窗口大小都会重新渲染点击图。修改渲染的延时可以参考 JS SDK 文档
的相关参数 renderRefreshTime
第二版点击图只会渲染没有隐藏的元素，部分手动控制隐藏/显示的元素（例如下拉菜单等）需要在元素显示时手动刷新点击图。
1.通过右上角的刷新按钮刷新页面，重新渲染点击图数据。
2.通过键盘上的''r''键来刷新点击图数据。
4.4. 注意事项
第二版点击图可以解决第一版点击图样式冲突的问题（例如after,before伪类的冲突，inline-block导致的样式异常等）
第二版点击图无法判断某些元素是否显示/隐藏，例如通过父元素overflow:hidden，改变子元素位置来产生显示/隐藏的效果，还有通过改变父元素高度来控
制子元素的显示/隐藏等，第二版点击图会将所有判断为显示的元素在页面中渲染出来，所以如果第二版点击图影响了您的页面显示，请切换到第一版点击图
使用。
4.4.1. 分享按钮
目前预置的 $WebClick 点击事件是在用户的各种设备的各种屏幕大小下采集的数据，但是点击分析的展示是在一个屏幕下显示的（一般是 PC 端）
方案一:点击分享按钮，用手机扫描二维码，在移动端设备上查看点击分析，后期我们会开发基于多个屏幕大小下的显示方案，敬请期待。5. 触达率图使用说明
有效停留：关注网页区域不滚动，期间鼠标可以移动，可以点击等操作。
有效停留时间：停留时间超过规定的时间，javascript sdk 中默认为 4 秒, 这个参数可以设置。
如果发生页面滚动时候，之前的页面停留是有效停留，也就是超过默认的 4 秒或者自定义的时间，javascript sdk 就会发送一次 页面停留事件。
触达率是指在当前筛选条件下，最终到达网页中某个位置的用户的比例。神策分析通过统计用户退出页面前最终到达的位置，计算页面的触达深度，生成触
达率图。 触达率图可用于分析如详情页、着陆页等类型页面中用户的浏览深度，帮助优化页面的内容、结构的设计。
这里以神策官网博客作为模板页面（为模拟数据），来介绍触达率分析：
1. 表示在当前筛选条件下，到达当前位置的用户的比例（以百分比表示）。
2. 为当前页面触达率基准线。
3. 刷新当前页面的数据。
4. 收起（下拉）操作工具栏。
触达图中的数据，是按照 uv 算的，是以一个人针对这个网页触达的最大高度作为他的数据来计算的。
6. FAQ待补充App 点击分析.App 点击分析 v1.13
1. APP 点击图概述
APP 点击分析主要用来分析用户在 APP 上的点击情况，并以直观的效果展示给使用者。
2. APP 点击分析功能简介
2.1. 连接 APP
通过手机扫描二维码可连接 APP，连接成功后对 APP 的数据进行分析。
对这个页面的描述如下：
1. 筛选条件在未连接状态下为不可操作状态。
2. 使用手机扫描页面上的二维码进行连接（要求手机已安装相应的 APP，且正确集成 SDK）。
Android 点击图配置方案
iOS 点击图配置方案
2.2. 分析使用说明对这个页面的描述如下：
1. 事件的筛选条件在连接成功后自动填充当前手机 APP 显示的页面名称、APP 的版本即应用版本、以及手机操作系统，每次 APP 页面变化的时候会
更新筛选条件到默认状态。您可根据自己的需要更改筛选条件，筛选条件改变后会导致热力图数据匹配不准确。
2. 您可根据自己的需求，添加针对用户的筛选条件。
3. APP 元素点击分析添加了默认分组，在此基础上，您可继续添加分组，包括默认分组在内，最多可以有四个分组。
4. APP 点击热力图。鼠标移到热力图对应的点上，会出现悬浮框，展示对应元素的具体数据。
5. 通过图表对 APP 点击事件进行分析，提供线图、柱图、饼图三种分析方式，可分析 APP 元素点击的总次数、触发用户数、点击率、点击比四个指
标。(==/=/)
6. 点击断开连接后手机 APP 不再上报信息，网页显示一张二维码，扫码可重新连接 APP 。
7. 点击同步按钮切换状态，开启时可以同步手机状态到页面上，关闭后不能同步。
8. 分析结果通过表格展示，点击页面右上角的下载按钮可下载表格。3. FAQ
3.1. 为什么热力图与图表数据不能完全匹配？
答：APP 点击热力图上的元素是按照 $element_selector 来唯一标记的，所以可能会出现热力图与图表数据不能完全匹配的情况。.App 点击分析 v1.17
APP 点击图概述
APP 点击分析主要用来分析用户在 APP 上的点击情况，并以直观的效果展示给使用者。
APP 点击分析功能简介
连接 APP
通过手机扫描二维码可连接 APP，连接成功后对 APP 的数据进行分析。
对这个页面的描述如下：
1. 筛选条件在未连接状态下为不可操作状态。
2. 使用手机扫描页面上的二维码进行连接（要求手机已安装相应的 APP，且正确集成 SDK）。
Android 点击图配置方案
iOS 点击图配置方案
分析使用说明对这个页面的描述如下：
1. 事件的筛选条件在连接成功后自动填充当前手机 APP 显示的页面名称、APP 的版本即应用版本、以及手机操作系统，每次 APP 页面变化的时候会
更新筛选条件到默认状态。您可根据自己的需要更改筛选条件，筛选条件改变后会导致热力图数据匹配不准确。
2. 您可根据自己的需求，添加针对用户的筛选条件。
3. APP 元素点击分析添加了默认分组，在此基础上，您可继续添加分组，包括默认分组在内，最多可以有四个分组。
4. APP 点击热力图。鼠标移到热力图对应的点上，会出现悬浮框，展示对应元素的具体数据。
5. 通过图表对 APP 点击事件进行分析，提供线图、柱图、饼图三种分析方式，可分析 APP 元素点击的总次数、触发用户数、点击率、点击比四个指
标。(==/=/)
6. 点击断开连接后手机 APP 不再上报信息，网页显示一张二维码，扫码可重新连接 APP 。
7. 点击同步按钮切换状态，开启时可以同步手机状态到页面上，关闭后不能同步。
8. 分析结果通过表格展示，点击页面右上角的下载按钮可下载表格。FAQ
为什么热力图与图表数据不能完全匹配？
答：APP 点击热力图上的元素是按照 $element_selector 来唯一标记的，所以可能会出现热力图与图表数据不能完全匹配的情况。间隔分析.间隔分析 v1.13
快速了解间隔分析
1. 间隔分析概述
在 1.11 及之后的版本，神策分析提供了“间隔分析”。
产品，运营，市场等人员的日常工作都需要观察某某业务的转化情况。如何衡量转化，除了用漏斗看转化率，还需要看转化时长的分布情况，间隔分析即是
解决这类问题和需求的。通过计算用户行为序列中两个事件的时间间隔，得到业务转化环节的转化时长分布。
间隔分析可以帮助你回答以下问题：
包含了实名认证等复杂操作的注册流程，想知道用户从开始注册到注册结束，整个过程花费的时长分布。
电商类产品分析用户首次打开 app 或完成注册，到完成首次下单所花费的时长分布。
投资理财类产品分析新用户完成绑卡到完成首次投资的时间间隔分布。
查看间隔分析功能应用示例
2. 间隔分析功能简介
2.1. 选择初始行为和后续行为
初始行为和后续行为存在两种情况：
1. 初始行为和后续行为是不同的事件。例如，互联网金融产品分别选择“注册成功”和“投资成功”，电商产品选择“添加购物车”和“提交订单”。用于分
析业务流程中用户转化花费的时长，侧面反应转化意愿，从而针对性的优化产品体验及运营策略。
2. 初始行为和后续行为是相同的事件。例如，在线教育类产品分析用户 2 次上课之间的时间间隔，分析用户对学习的积极性。电商类产品分析用户重
复购买生活用品的时间间隔，从而预测下一次购买的时间点，精准推荐。
2.2. 设置初始行为和后续行为筛选条件根据实际的分析需求，可以对初始行为或后续行为添加筛选条件。以奢侈品电商为例，我们想分析上一次订单金额超过 1 万元的用户，是否短时间就会进行
下一次的下单行为。
提出这条分析的基础假设是，下单金额更高的用户，对平台的信任度更高；其次这样的用户比较有钱。通过分析来验证我们的假设，
如果成立，则可以说明用户完成一次高金额的订单之后，仍有较强的购买意愿，可以赠送优惠券，引导用户尽快完成复购。
此时初始行为和后续行为都选择“支付订单”，同时对初始行为添加筛选条件“订单金额大于 10 000 ”，即可满足分析需求。
2.3. 设置用户筛选条件
根据用户属性，筛选出想要的分析对象。比如，只查看浙江省女性用户的行为时间间隔情况。
2.4. 按属性分组查看
间隔分析含如下 3 种分组方式
1. 按初始行为属性分组
2. 按后续行为属性分组
3. 按用户属性分组
如果选择按初始行为分组查看，如 的 ， 则按照每个用户触发时带有的的属性值进行分组，一个用户只会出现在一个分组中；
2.5. 选择聚合时间单位
可选择的数据聚合时间单位：
1. 按天
2. 按周
3. 按月
值得注意的是，间隔分析不支持「按小时」聚合。因为「按小时」即要求用户的初始和后续行为发生在同一个自然小时内，否则行为无法关联，造成分析结
果不准确。详见下文 初始行为和后续行为配对的计算规则。
2.6. 设置关联属性
支持设置前后两个事件的属性进行关联。不同事件关联的属性可以是相同属性，也可以是不同属性，但是要求属性的类型必须一致。 举例：某电商开展了一
个营销活动，除了监测用户从商品详情页到完成商品购买的行为流向，还需要精确定位该用户的行为是和本次营销活动相关。因此需要在和事件中添加营销
活动 ID 的属性，此时就可以将该属性作为关联 ID ，以保证用户严格按照该模式配对。
2.7. 查看分析结果
间隔分析的分析结果以箱线图的形式展示。箱形图提供了一种只用 5 个点对数据集做简单总结的方式。它能显示出一组数据的最大值、最小值、中位数、及
上下四分位数。
可以看到整个时间段 A → B 的总体情况的最大、最小、中位、平均间隔时间；
分析结果中各指标的计算规则：
1. 间隔数：在选定时间范围内，按照间隔分析计算规则完成间隔转化的配对数（下载数据中的字段）。
2. 转化用户数：共有多少人在选定的时间内完成了间隔转化，可能一个人会完成多次间隔转化。3. 人均间隔数：间隔数 / 转化用户数（下载数据中的字段）。
4. 间隔转化时长：在选定时间范围内，按照间隔分析计算规则，计算完成间隔转化的配对之后，统计的每个配对的间隔转化时长。
5. 最大值：间隔转化时长的最大值。
6. 最小值：间隔转化时长的最小值。
7. 中位数：将间隔转化时长按从大到小排期，取中间值。
8. 上四分位：将间隔转化时长按从大到小排期，取 1/4 处的值。
9. 下四分位：将间隔转化时长按从大到小排期，取 3/4 处的值。
10. 平均值：间隔转化时长的总和 / 转化用户数。
11. 人均转化时间：每个人的平均间隔时长总和 / 转化用户数。
展开表格中查看细项，了解每个分组的间隔时间明细。
3. 初始和后续行为是如何配对的
假设用户在过去某个时间段内行为序列是：A → C → A → B → B → A → B → B → A → A → C → D → A → B
此时我们分析用户做了 A 和 B 的时间间隔，会按如下的计算规则：
在发生 A 后，找到离 A 最近的 B ，即为第一个间隔。从间隔向后继续找 A 和 B 的配对，间隔与间隔不交叉，依次类推；
选择聚合时间单位，按天、周、月聚合，则会限定配对的 A 和 B 发生在同一天、周、月；例如：如果按天聚合，用户发生A 的时间是 23:50 ，
发生 B 的时间是次日 00:10 。这两个事件无法完成配对。
此时如果不考虑聚合时间单位，则间隔配对结果是：A → C → A → B → B → A → B → B → A → A → C → D → A → B
4. 典型使用场景实例
以金融投资类产品为例，用户是否发生投资行为是业务的关键。因此在产品运营策略上，会给新用户发红包吸引用户投资。这时可以选取新用户和
2 个事件，得到用户首次投资成功花费的时长分布，同时对事件属性配置筛选条件分析各项策略对转化时长的影响。
详细见下图：
以短视频类产品为例，这类产品提供了非常丰富的视频内容供用户查看。内容就是短视频 App 提供给用户的核心价值。如何衡量用户是否感受到这
一价值。这里我们选择用户完整看过一个短视频作为判断依据，同时选择新用户从 App到所花费的时长情况作为分析对象。如果用户普遍需要较长
的时长才能完成转化，说明用户需要付出的视频筛选的成本较高，用户极有可能流失。因此我们选取新用户从 App到的时间间隔作为优化的目标。
详细见下图：间隔分析通常是业务情况的反应，时间间隔多数情况下也并不能作为优化的指标，但是可以帮助我们探索可能存在的问题。如提交订单到支付订单间隔时长
中位数是 5 分钟，说明一半的用户支付订单需要花费 5 分钟以上。这时应该主动思考其中可能存在的问题，是支付功能的 Bug ，还是其他问题导致支付失
败，需要结合事件分析，漏斗分析等功能定位问题。
4.1. 5.FAQ
4.1.1.1. 5.1 可否用间隔分析的功能分析页面停留时长，时间间隔和页面停留时长有什么区别？
答：不能。假设注册流程包括，， 3 个事件。 与 的时间间隔并不是用户在基本信息页的停留时长。因为用户在发生和 2 个行为之间，可能含有其他操作。
而一旦触发了和，即可利用「间隔分析」来计算。用户.用户分析 v1.15
用户列表
用户行为序列用户属性分析.用户列表 v1.17
从分析模型按「用户数」的分析结果，和用户分群的列表详情页均可查看明细的「用户列表」。
A.在用户列表中对于「加密显示」的「用户属性」将会以脱敏显示。
B.「列目显示」指的是可自定义用户列表中常用的用户信息。左侧蓝框内容为可被订阅显示到用户列表上的用户属性，右侧红色框内为选中项，鼠标 hover
到已选项上（例如：企业分组）可将此属性固定在列表的左侧栏。设备 ID 为固定第一列，除此之外用户可根据需求添加额外两个属性。固定区域的三个属性
之间可以直接按住拖动排序；非固定区域的所有已选属性之间同样可按住对应项直接进行拖动排序。
C.「刷新」可以便捷的将在此查询条件下新入库的用户信息刷新加载出来。
D.如果你是从分析模型查看用户数的结果点击查看用户明细，或从用户分群详情页查看某日的分群用户，而进入达到用户列表页面。那么可通过「保存分
群」快速将当前的用户群体保存为一个分群，随后在分析中直接使用。
E.点击「下载」则会按照当前所选取的用户属性将此批用户的信息下载下来。如果是「加密显示」的用户属性，下载结果同样加密。.用户属性分析 v1.13
1. 用户属性分析概述
根据用户的属性做统计分析，比如查看用户数量在注册时间上的变化趋势、查看用户按省份的分布情况。
注: 此功能分析的是用户表（users）中的用户。如果在 sdk 中仅仅 track 了事件数据，而没有为这个用户设置任何 profile 信息，则此用户不会出现在“用户属
性分析”功能中。所以在“行为事件分析”模块中查看“任意事件”的触发用户数，与此处数据可能不一致。
2. 用户属性分析功能简介
2.1. 选择指标对于所有类型的属性都可以将“去重数”作为分析指标，对于数值类型的属性可以将“总和”“均值”“最大值”“最小值”作为分析指标。
1. 用户数： 所有用户数。
2. 去重数：在所有用户中，该属性出现的独立去重个数。
3. 总和： 在所有用户中，该属性的取值求和。
4. 均值： 在所有用户中，该属性取值的算术平均值。
5. 最大值： 在所有用户中，该属性取值的最大值。
6. 最小值： 在所有用户中，该属性取值的最小值。
2.2. 按分组（维度）查看按维度查看数据，可以进行更加精细化的分析。可以添加多个维度，没有维度时无法展示图形。数字类型的维度可以自定义区间，如上图所示。
2.3. 添加筛选条件通过筛选条件可以查看某些符合具体条件的用户。点击上图 a 处的“+筛选条件”，可以从下拉列表中选择一个需要筛选的用户属性。根据不同的属性的数据类
型（文本、数值、日期时间、布尔、集合等），提供不同的筛选逻辑操作，如下图：
2.4. 显示设置
1. a 处选择分组 当分组值比较多时，选择需要在图形中展示的分组，默认展示前 10 个分组。
2. b 处选择图形 可以选择线图、柱图、饼图。
3. c 处选择 x 坐标 当分组数多于 1 个，且用线图、柱图展示时，需要选择一个维度作为 x 轴。
2.5. 表格展示第一列是 x 轴数据，第一行是分组（维度）值。点击表格内的数字，可以查看详细用户列表。
3. FAQ
3.1. 可否按照用户接入的时间顺序筛选用户？
答：用户属性中，默认情况下不会有时间属性，如果需要按接入时间查看，需要在埋点时，记录下时间类属性，然后依据该属性进行分析。用户行为序列.用户行为序列 v1.13
1. 用户行为序列概述
行为事件分析、漏斗分析、留存分析和分布分析这4个分析模型若分析结果为人群，点击分析结果可显示出用户详细信息列表。通过用户分群产生的用户数，
同样可以点击获取用户详细信息列表。点击列表中任意单个用户可获取其中单个用户的历史行为记录，即用户行为序列。
需要注意的是，根据功能入口的不同，会以不同的方式确立当前行为序列的锚点，其规则如下：
1. 通过“行为事件分析”进入时，锚点是满足筛选和分组条件下，分析目标的那个事件。
2. 通过“漏斗分析”进入时，如果是选择的转化用户，则锚点是完成转化的那一系列关键事件；如果选择的是流失用户，则锚点是上一步转化的那一系
列关键事件。
3. 通过“留存分析”进入时，锚点是留存分析中满足筛选和分组的后续行为。
4. 通过“分布分析”进入时，锚点是选定的时间区间内，满足筛选和分组的事件。
左侧分为两个区域，上侧为当前时间区间内的行为概览，支持对事件和时间区间的设置。下侧为该用户的行为列表，点击各个事件还可以看到相应事件的属
性，点击上下箭头可以调整时间轴显示时间和事件，如下图。时间轴上方为属性筛选控件，支持对展示的行为属性进行自定义，另外是全部展开展示/全部折叠展示方便操作。点击,可以查看在当前时间区间内，可以看到该用户行为的比重，以饼图形式展示。2. 典型应用场景
以电商网站为例，我们需要分析其核心转化流程中用户流失的原因。电商网站中一个典型的用户购买转化流程由如下几个事件构成：浏览页面、浏览商品、
提交订单、支付订单，创建漏斗如下图。
我们发现用户在浏览商品后流失的比例较大，那么点击 a 处箭头可查看流失用户数，点击 b 处用户数可提取具体的用户列表信息，如下图。
进入用户列表，点击某个用户的id，查看当前用户的行为序列，可快速验证流失原因，如下图。我们发现大量用户在反复浏览商品中，而没有产生购物行为，这说明用户没有找到真正满意的商品。这时可以根据用户历史行为进行商品的个性化推荐或者
发放优惠券刺激其消费。
3. 功能应用示例
用户行为序列.用户分析 v1.17
1. 概述
根据用户的属性做统计分析，比如查看用户数量在注册时间上的变化趋势、查看用户按省份的分布情况。
注: 此功能分析的是用户表（users）中的用户。如果在 sdk 中仅仅 track 了事件数据，而没有为这个用户设置任何 profile 信息，则此用户不会出现在“用户属
性分析”功能中。所以在“行为事件分析”模块中查看“任意事件”的触发用户数，与此处数据可能不一致。
2. 用户属性分析功能简介
3. 选择指标对于所有类型的属性都可以将“去重数”作为分析指标，对于数值类型的属性可以将“总和”“均值”“最大值”“最小值”作为分析指标。
1. 用户数： 所有用户数。
2. 去重数：在所有用户中，该属性出现的独立去重个数。
3. 总和： 在所有用户中，该属性的取值求和。
4. 均值： 在所有用户中，该属性取值的算术平均值。
5. 最大值： 在所有用户中，该属性取值的最大值。
6. 最小值： 在所有用户中，该属性取值的最小值。
4. 按分组（维度）查看按维度查看数据，可以进行更加精细化的分析。可以添加多个维度，没有维度时无法展示图形。数字类型的维度可以自定义区间，如上图所示。
5. 添加筛选条件通过筛选条件可以查看某些符合具体条件的用户。点击上图 a 处的“+筛选条件”，可以从下拉列表中选择一个需要筛选的用户属性。根据不同的属性的数据类
型（文本、数值、日期时间、布尔、集合等），提供不同的筛选逻辑操作，如下图：
6. 显示设置
1. a 处选择分组 当分组值比较多时，选择需要在图形中展示的分组，默认展示前 10 个分组。
2. b 处选择图形 可以选择线图、柱图、饼图。
3. c 处选择 x 坐标 当分组数多于 1 个，且用线图、柱图展示时，需要选择一个维度作为 x 轴。
7. 表格展示第一列是 x 轴数据，第一行是分组（维度）值。点击表格内的数字，可以查看详细用户列表。
8. FAQ
8.1. 可否按照用户接入的时间顺序筛选用户？
答：用户属性中，默认情况下不会有时间属性，如果需要按接入时间查看，需要在埋点时，记录下时间类属性，然后依据该属性进行分析。自定义查询.自定义查询 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
对于使用现有的 UI 功能暂时无法满足的高级数据需求，我们提供了更加自由的自定义查询功能。该功能支持使用标准 SQL 来对神策分析的所有数据进行查
询，同时也包含对查询结果的简单可视化。
注: 当前版本的自定义查询工具基于 HUE 项目构建。
1. 数据表
目前，神策分析的所有数据映射到 事件 和 用户 这两张数据表，在 SQL 里使用这两张数据表即可完成所有查询。同时支持将客户创建的所有 session 映射
成 sessions_${session_name} 命名的表。以下列举字段都为特殊字段，其他未列举且带 "$" 的属性都为神策预置属性，具体含义可参考文档 预置事件与预
置属性，不带 "$" 的属性都为自定义属性，具体含义需跟对应埋点人员确认。
1.1. 事件表 (events)
事件表包含了所有事件的详细信息（不包括虚拟事件），该表的每一行代表一个 track 的 Event。事件表的字段分为特殊字段和 Event 本身的 Property 两
大类。其中特殊字段如下：
字段 说明 示例
event 事件的名称 BuyGold
user_id 神策分析为该用户分配的内部 ID，与 user 表的 id 字段相关联 1234
distinct_ 用户的原始 ID，track 时传入，可能是一个匿名 ID 或 登录 ID wahaha
id
date 事件发生的日期,属于特殊字段，上传数据时无需上传 date 字段 2015-09-21
time 事件发生的具体时间 2015-09-21
11:11:11
$receive 服务器接收到事件时的具体时间戳。该字段可以在自定义查询中显示，在前端的分析模块中，所有事件都无法使用该字段分 15702305860
_time 析数据，因为 $receive_time 默认不会与任何事件绑定。 48
需要特别注意的是，事件表的 user_id 字段并不是 track 时传入的 distinct_id，而是由神策分析为该用户分配的内部 ID，具体的机制见如何准确的标识用户
1.2. 用户表 (users)
用户表的每一行代表一个 User，类似于事件表，用户表的字段也分为特殊字段和 User 的其它 Profile 两大类，其中特殊字段的说明如下：
字 说明 示例
段
id 神策分析为该用户分配的内部 ID，与 events 表的 user_id 相关联 1234567
first_id 该用户的匿名 ID，与 events 表登录前行为的 distinct_id 相关联。需要特别注意，如果 0c476090a0b2940a
某个用户 first_id 的值等于 second_id，说明该用户没有成功关联到匿名 ID，相当于未
知
secon 该用户的登录 ID，与 events 表登录后行为的 distinct_id 相关联 wahaha
d_id
$upd 该用户最近一次更新用户表信息的时间戳 1570230586048
ate_ti
me
$devi 开启多对一关联机制时，会记录与登录 ID 关联的匿名 ID 列表，以及关联时的时间戳 1570230586048:0c476090a0b2940a；
ce_id 1570230591000:65A71299-7139-4B4C-9B71-
_list 23A0AC9AAF7D
1.3. Session 表每张 Session 表都对应一个 Session 的配置，命名规则为：sessions_${session_name}。
Session 表是对 events 表做了扩展，除了包含 events 表包含的字段，还包含 session 属性和 session 相关的特殊字段，session 属性的命名规则是原始的
属性名加上后缀 $session，表示 session 中初始事件的属性。其中特殊字段说明如下：
字段 说明 示例
$session_id 标示一个 session 的唯一 id 2036149433
405577601
$session_po 标示一个 session 中事件的索引，从 0 开始，依次递增。1.14 及之前版本 session 中最后一个事件的索引是-1，如果 0
sition session 中只有1个事件，则索引值是-2 。1.15 及之后版本，不再有特殊的 -1、-2 索引值。
$session_ev session 内事件时长，表示session相邻两个事件发生的时间间隔，单位是秒，最后一个事件的事件时长是 null 354
ent_duration
$session_du session 内最后一个事件触发的时间减去 session 内第一个事件触发的时间，单位是秒 234
ration
$session_de session 深度，表示 session 内触发事件的次数 4
pth
$event_id$s Session 内第一次触发的事件 Signup
ession
因为 session 表的计算量较大，所以必须加上时间注解进行使用，比如：
SELECT event, user_id, distinct_id, date FROM sessions_default/*SESSION_TABLE_DATE_RANGE=[2018-01-01,2018-01-05]
*/
注意：由于 SESSION 表查询比较耗时，为了提升查询效率，1.14 及之后的神策分析版本不支持使用 select * 查询 SESSION 表，需要选择具体的字段名查
询。
1.4. 用户分群/标签表
这些表为系统中分群/标签结果的存储表，表中存储的用户为此分群/标签筛选出来的用户。不同版本的表命名规则有所不同，见下表：
系统版本 类型 表名规则 示例
<=1.13 分群 segmenter_${segmenter_name} segmenter_abc
>=1.14 分群 user_group_${user_group_name} user_group_abc
>=1.14 标签 user_tag_${user_tag_name} user_tag_abc
关于表中具体字段的说明如下:
字段 说明 示例
user_id 用户 id -9220214159525537212
distinct_id 与事件表中的 distinct_id 相关联 3f840957485db9a9
values 用户分群/标签值 1
base_time 用户分群/标签计算的基准时间，1.14 及之后版本之后新增 1547015611000
其中 base_time 是以毫秒形式进行的存储，所以在查询的时候，用户可以通过 unix_timestamp_ms 函数将日期转化成毫秒数进行查询，例子如下：
SELECT * FROM user_group_fenqun9 WHERE base_time=unix_timestamp_ms(''2019-01-17 00:00:00'')
1.5. Items 表
字段名称 说明 示例
$item_type item 表的类型 apple$item_id 表示 item 的 id 123
$is_valid 该 item 是否有效，不传入默认为 true 1
$receive_time 该 item 到达时间 1575604527772
$update_time 该 item 的更新时间，不传入默认为写入时间 1575604527772
2. 数据类型
出于查询效率的考虑，自定义查询功能对不同的数据类型有不同处理，同时某些数据类型有一些使用上的限制，具体说明如下：
2.1.1. Number
数值类型，不区分浮点数与整数，输出的时候会根据是否有小数位自动转换输出格式。
2.1.2. String
字符串类型。
2.1.3. Date
注意：time 字段特殊，不需要经过转换即可直接使用。
日期类型，在自定义查询中表现为 毫秒级的 Timestamp，例如：1442937600000。
如果有需要，可以使用 EPOCH_TO_TIMESTAMP 函数转换为 Timestamp 类型，例如：
SELECT EPOCH_TO_TIMESTAMP($signup_time / 1000) FROM users LIMIT 100;
用于条件过滤的例子如下：
SELECT COUNT(*) AS cnt FROM users WHERE EPOCH_TO_TIMESTAMP($signup_time / 1000) > ''2017-01-01'';
2.1.4. Datetime
日期时间类型，和 Date 类型一样，也使用毫秒级的 Timestamp表示，例如：1442592138000。 同样也可以使用 EPOCH_TO_TIMESTAMP 类型进行类
型转换。
2.1.5. Bool
布尔类型，使用 0/1 表示 False/True。
2.1.6. List
列表类型，支持在 Where 条件里使用 CONTAINS 函数或者 LIKE 函数来进行过滤操作。例如：
SELECT FavoriteFruits from users where CONTAINS('''', FavoriteFruits);
同样也可以使用 /*EXPLODE_LIST_COLUMN=${table.columnName}*/ 注解来将 List 类型数据打散成多行 string 类型数据。例如：
SELECT list_property FROM events /*EXPLODE_LIST_COLUMN=events.list_property*/
3. 功能使用
3.1. 基本功能
在输入框中输入要查询的 SQL，例如查询每天的事件总数：SELECT date, COUNT(*) from events GROUP BY 1 ORDER BY 1
然后点击查询即可看到表格展现的结果，同时还有下方还有简单的图表展示，也可以使用 CSV 格式把结果下载下来进行进一步的分析。
出于性能的考虑，前端展示的结果最大只有 1k 条，而 CSV 下载的结果最大是 100w 条，如果需要下载更多数据请使用查询 API。
3.2. 日期过滤
date 字段表示事件发生时的日期，精确到天，可以用于快速过滤数据。需要特别注意，任何时候都应当尽量使用 date 字段进行过滤，而不是 time 字段。
由于 date 字段的特殊性，对 SQL 操作和函数的支持有一些限制，目前支持使用的函数和表达式有:
CURRENT_DATE() 函数，返回当天，例如 2016-08-23。
CURRENT_WEEK() 函数，返回当周的周一，例如 2016-08-22。
CURRENT_MONTH() 函数，返回当月的一号，例如 2016-08-01。
INTERVAL 表达式，例如 CURRENT_DATE() - INTERVAL ''1'' DAY 表示昨天。
以下是一些具体的例子：
精确过滤某一天的数据
SELECT COUNT(*) FROM events WHERE date = ''2016-01-01''
查询当天的数据
SELECT COUNT(*) FROM events WHERE date = CURRENT_DATE()
查询最近 3 天的数据
SELECT COUNT(*) FROM events WHERE date BETWEEN CURRENT_DATE() - INTERVAL ''2'' DAY AND CURRENT_DATE()
查询上个自然月的数据
SELECT COUNT(*) FROM events WHERE date BETWEEN CURRENT_MONTH() - INTERVAL ''1'' MONTH AND CURRENT_MONTH() -
INTERVAL ''1'' DAY
由于 date 是专门为快速的数据过滤设计的特殊字段，不支持绝大多数的时间函数。因此，如果希望使用其它时间函数，请使用 time 字段代替，例
如：
SELECT datediff(now(), trunc(time, ''DD'')), COUNT(*) FROM events WHERE date >= CURRENT_DATE() - INTERVAL ''100''
day GROUP BY 1
按照月份聚合 2018-09-01 之后的事件数
SELECT date_sub(date,dayofmonth(date)-1) the_month,count(*) event_qty
FROM events WHERE date>''2018-09-01''
GROUP BY the_month ORDER BY the_month;
按照星期聚合 2018-09-01 之后的事件数
SELECT date_sub(date,mod(dayofweek(date)+5,7)) the_week,count(*) event_qty
FROM events WHERE date>''2018-09-01''
GROUP BY the_week ORDER BY the_week;
3.3. 常用函数说明
使用自定义查询经常能用到如下几种函数：时间日期函数
字符串函数
数学函数
其他更多Impala函数，请参考：
Impala 函数参考文档
3.3.1. 时间日期函数
自定义查询中和时间日期函数相关的字段分为以下三种：
一、events 表中的 time 字段
time 是毫秒级的 Timestamp 类型，可以直接使用所有的时间日期函数。
二、events 表中的 date 字段
date 是天级别的 Timestamp 类型，如果不需要时分秒的信息，使用这个字段效率会更高。date 同时也是索引字段，所以应该尽量使用此字段进行日期范围
的过滤，具体请参考 "日期过滤" 中的说明。
注：1.10 版本之前，date 字段不支持使用自定义函数，可以使用 time 替代。
三、其它自定义的 Date/Datetime 类型的属性
这类属性在自定义查询中表现为毫秒级的 Unix 时间戳， 使用时间日期函数时需要先使用 EPOCH_TO_TIMESTAMP 函数转换为 Timestamp 类型，请参考
"数据类型" 中的说明。
3.3.1.1. adddate(timestamp startdate, int days), adddate(timestamp startdate, bigint days)
用途：在一个TIMESTAMP（时间戳）值上加一个给定的天数
参数：
startdate：timestamp 类 型 的 开 始 时 间 戳 days：
需要加上的天数，正数表示几天之后，负数表示几天之前
返回值：加上天数之后的时间戳，timestamp类型
3.3.1.2. datediff(timestamp enddate, timestamp startdate)
用途：返回两个时间戳间隔天数,例如：
参数：
enddate：结束时间
startdate：开始时间
返回值：结束时间减去开始时间的天数，int类型。如果第一个参数时间的日期晚于第二个参数时间的日期，返回正数；相反，如果第一个参数时间的日期早
于第二个参数时间的日期，返回负数
3.3.1.3. extract(unit FROM timestamp), extract(timestamp, string unit)
用途：从TIMESTAMP值中截取数值型的时间域，例如年度，月份，日期，小时，分钟，秒/微秒
参数：
unit：时间单位unit字符串可取的值有：year，month，day，hour，minute，second，millisecond。
返回值：时间域的整型值
例如：目前为止所有的支付订单次数按照年度和月份查询
SELECT extract(Year from time) AS Year, extract(Month from time) AS Month, COUNT(*) FROM events
WHERE event = ''payOrder''
GROUP BY Year, Month
ORDER BY Year, Month
3.3.1.4. trunc(timestamp, string unit)
用途：从给定的timestamp时间戳截取时间域
参数：unit：时间单位
SYYYY, YYYY, YEAR, SYEAR, YYY, YY, Y：年度
Q：季度
MONTH, MON, MM, RM: 月 份
WW, W: 相应周第一天的日期
DDD, DD, J: 日期
DAY, DY, D: 相应周第一天的日期
HH, HH12, HH24: 小时
MI: 分钟
返回值：截取时间域之后的日期
例如：最近100天内每天发生的事件数和事件发生时间与当前日期的间隔天
SELECT datediff(now(), trunc(time, ''DD'')), COUNT(*) FROM events
WHERE date >= CURRENT_DATE() - INTERVAL ''100'' day
GROUP BY 1
3.3.2. 字符串函数
3.3.2.1. concat(string a, string b…)
用途：把所有string类型的参数连接成一个string类型
参数：
string(不限个数)：要连接的字符串
返回值：一个整体的字符串
例如：查询00后用户地址，地址为省份和地区拼接
SELECT concat($province, $city) As Address
FROM users
WHERE yearofbirth > 2000
3.3.2.2. regexp_like(string source, string pattern[, string options])
用途：判断source字符串中是否包含以pattern为正则表达式的内容
参数：
source：要检查的字符串
pattern：正则表达式
option（选填）：选项
c：区分大小写i：
不区分大小写
m：匹配多行，^和$操作符对于每一行都会匹配，而不是对多行为整体的开头和结束。 n：
新行匹配，点（.）操作符会匹配新行。重复操作符如 . 可以匹配source字符串中的多行（可以通过. 跳过几行）
返回值：匹配与否，boolean类型
例如：使用QQ邮箱为邮件的用户数
SELECT COUNT(*) FROM users
WHERE regexp_like(email, ''@qq.com$'')
3.3.2.3. parse_url(string urlString, string partToExtract [, string keyToExtract])
用途：通过指定URL中的特定部分返回截取值
参数：
urlString：URL
partToExtract：要截取的部分。可指定的值为''PROTOCOL'', ''HOST'', ''PATH'', ''REF'', ''AUTHORITY'', ''FILE'', ‘USERINFO'', ‘QUERY''
PROTOCOL：协议，如HTTP，HTTPS，FTP等
HOST：主机名
PATH：路径
REF：锚点（“又称引用”），即URL中#后面的字符串AUTHORITY：授权
FILE：文件名
USERINFO：用户信息
QUERY： 查 询 参 数 ， 即 URL 中 ？ 后 面 的 字 符 串 keyToExtract
（选填）：当partToExtract为’QUERY’时，可以指定query键值对中的key，获取指定参数值
返回值：URL中指定部分的截取值
例如：当天页面浏览事件中各个路径的访问分布情况
SELECT parse_url(url, ''PATH''), COUNT(*) FROM events
WHERE date = CURRENT_DATE() AND event = ''$pageview''
GROUP BY 1
3.3.3. 数学函数
数学函数用于一些数值的操作。 特别的，在做去幂运算时，请使用pow()函数取代幂运算符 ‘**’。
3.3.3.1. pow(double a, double p), power(double a, double p), dpow(double a, double p), fpow(double a, double p)
用途：取幂，例如：
参数：
a：底数
b：指数
返回值：a的b次幂
例如：查询理财产品到期后本息总额超过10万的用户数
SELECT count(distinct(user_id)) FROM events
WHERE event = ''buyProduct'' AND (capital + capital * pow(rateofinterest,duration)) > 100000
3.3.3.2. round(double a), round(double a, int d), round(decimal a, int_type d), dround(double a), dround(double a, int d)
用途：返回四舍五入值，例如：
参数：
a：要四舍五入的数值 d
（可选）：小数保留位数，若无此参数，保留到整数部分
返回值：四舍五入值
例如：查询理财产品收益率超过0.45百分点的用户数
SELECT count(distinct(user_id)) FROM events
WHERE event = ''buyProduct'' AND round((income/capital),4) * 100 > 0.45
3.3.3.3. truncate(double_or_decimal a[, digits_to_leave]), dtrunc(double_or_decimal a[, digits_to_leave])
用途：去除小数部分的数值，例如：
参数：
a： 被 截 取 的 数 值 digits_to_leave
（可选）：小数点保留位数，若无此参数，保留到整数部分
返回值：被截取的值
3.4. 高级选项
开启快速 Distinct 算法，可以大大加速类似 COUNT(DISTINCT user_id) 的计算，并且支持多个 COUNT(DISTINCT) 表达式，缺点是会得到不完全
精确的结果。例如：SELECT COUNT(DISTINCT user_id) FROM events
WHERE date = CURRENT_DATE() /*ENABLE_APPROX_DISTINCT*/
开启维度字典映射和维度表关联，默认关闭。例如：
SELECT $model FROM events
WHERE date = CURRENT_DATE() /*ENABLE_DIMENSION_DICT_MAPPING*/
如果 SQL 是查询某个指定 Distinct Id 的数据，可以用此选项来进行查询查询。例如：
SELECT event, time FROM events
WHERE date = CURRENT_DATE() AND distinct_id=''abcdef'' /*DISTINCT_ID_FILTER=abcdef*/
SQL 默认在执行 10 分钟之后会被系统强制杀死，如果希望增大超时时间可以使用如下方式：
SELECT * FROM events WHERE date = CURRENT_DATE() LIMIT 1000 /*MAX_QUERY_EXECUTION_TIME=1800*/
对于 JOIN 类查询，可以使用 Join Hint 来指定 Join 的执行方式，可以是 SHUFFLE 或者 BROADCAST。尤其是在执行过程中如果遇到内存不足
的错误，可以考虑强制指定为 SHUFFLE 模式：
SELECT COUNT(*) AS cnt FROM events
JOIN /* +SHUFFLE */ users ON events.user_id = users.id
WHERE date = CURRENT_DATE()
4. 常见案例
4.1. 根据用户的 distinct_id 查询某个用户在某天的具体行为
直接使用 distinct_id 查询即可:
SELECT * FROM events WHERE distinct_id = ''wahaha'' AND date = ''2015-09-10'' LIMIT 100
4.1.1. 查询每天上午 10 点至 11 点的下单用户数
使用标准的 SQL 日期函数 EXTRACT 来取出小时信息。
SELECT date, COUNT(*) FROM events
WHERE EXTRACT(HOUR FROM time) IN (10, 11) AND event = ''SubmitOrder''
GROUP BY 1
4.1.2. 查询一段时间内的用户下单次数分布情况
首先计算每个用户的下单次数，然后使用 CASE..WHEN 语法来分组。SELECT
CASE
WHEN c < 10 THEN ''<10''
WHEN c < 20 THEN ''<20''
WHEN c < 100 THEN ''<100''
ELSE ''>100''
END,
COUNT(*)
FROM (
SELECT user_id, COUNT(*) AS c FROM events
WHERE date BETWEEN ''2015-09-01'' AND ''2015-09-20'' AND event = ''SubmitOrder''
GROUP BY 1
)a
GROUP BY 1
4.1.3. 查询做了行为 A 而没有做行为 B 的用户数
使用 LEFT OUTER JOIN 计算差集。
SELECT a.user_id FROM (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''BuyGold''
) a
LEFT OUTER JOIN (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''SaleGold''
) b
ON a.user_id = b.user_id
WHERE b.user_id IS NULL
4.1.4. 计算用户的使用时长
使用分析函数，根据每个用户相邻的两个事件的间隔估算累计使用时长，如果两次使用间隔超出10分钟则不计算。
SELECT
user_id,
SUM(
CASE WHEN
end_time - begin_time < 600
THEN
end_time - begin_time
ELSE
0
END
) FROM (
SELECT
user_id,
EXTRACT(EPOCH FROM time) AS end_time,
LAG(EXTRACT(EPOCH FROM time), 1, NULL) OVER (PARTITION BY user_id ORDER BY time asc) AS begin_time
FROM events
WHERE date=''2015-5-1''
) a
GROUP BY 1
4.1.5. 获取用户的首次行为属性
使用 first_time_value(time, 其他属性) 聚合函数来获取第一次发生某行为时的相关属性-- 1 URL
SELECT user_id, first_time_value(time, $url) FROM events WHERE event = ''$pageview'' GROUP BY user_id
-- 2
SELECT user_id, first_time_value(time, order_amount) first_order_amount FROM events WHERE event = ''payOrder''
GROUP BY user_id.自定义查询 v1.15
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
对于使用现有的 UI 功能暂时无法满足的高级数据需求，我们提供了更加自由的自定义查询功能。该功能支持使用标准 SQL 来对神策分析的所有数据进行查
询，同时也包含对查询结果的简单可视化。
注: 当前版本的自定义查询工具基于 HUE 项目构建。
数据表
目前，神策分析的所有数据映射到 事件 和 用户 这两张数据表，在 SQL 里使用这两张数据表即可完成所有查询。同时支持将客户创建的所有 session 映射
成 sessions_${session_name} 命名的表。以下列举字段都为特殊字段，其他未列举且带 "$" 的属性都为神策预置属性，具体含义可参考文档 预置事件与预
置属性，不带 "$" 的属性都为自定义属性，具体含义需跟对应埋点人员确认。
事件表 (events)
事件表包含了所有事件的详细信息（不包括虚拟事件），该表的每一行代表一个 track 的 Event。事件表的字段分为特殊字段和 Event 本身的 Property 两
大类。其中特殊字段如下：
字段 说明 示例
event 事件的名称 BuyGold
user_id 神策分析为该用户分配的内部 ID，与 user 表的 id 字段相关联 1234
distinct_ 用户的原始 ID，track 时传入，可能是一个匿名 ID 或 登录 ID wahaha
id
date 事件发生的日期,属于特殊字段，上传数据时无需上传 date 字段 2015-09-21
time 事件发生的具体时间 2015-09-21
11:11:11
$receive 服务器接收到事件时的具体时间戳。该字段可以在自定义查询中显示，在前端的分析模块中，所有事件都无法使用该字段分 15702305860
_time 析数据，因为 $receive_time 默认不会与任何事件绑定。 48
需要特别注意的是，事件表的 user_id 字段并不是 track 时传入的 distinct_id，而是由神策分析为该用户分配的内部 ID，具体的机制见如何准确的标识用户
用户表 (users)
用户表的每一行代表一个 User，类似于事件表，用户表的字段也分为特殊字段和 User 的其它 Profile 两大类，其中特殊字段的说明如下：
字 说明 示例
段
id 神策分析为该用户分配的内部 ID，与 events 表的 user_id 相关联 1234567
first_id 该用户的匿名 ID，与 events 表登录前行为的 distinct_id 相关联。需要特别注意，如果 0c476090a0b2940a
某个用户 first_id 的值等于 second_id，说明该用户没有成功关联到匿名 ID，相当于未
知
secon 该用户的登录 ID，与 events 表登录后行为的 distinct_id 相关联 wahaha
d_id
$upd 该用户最近一次更新用户表信息的时间戳 1570230586048
ate_ti
me
$devi 开启多对一关联机制时，会记录与登录 ID 关联的匿名 ID 列表，以及关联时的时间戳 1570230586048:0c476090a0b2940a；
ce_id 1570230591000:65A71299-7139-4B4C-9B71-
_list 23A0AC9AAF7D
Session 表每张 Session 表都对应一个 Session 的配置，命名规则为：sessions_${session_name}。
Session 表是对 events 表做了扩展，除了包含 events 表包含的字段，还包含 session 属性和 session 相关的特殊字段，session 属性的命名规则是原始的
属性名加上后缀 $session，表示 session 中初始事件的属性。其中特殊字段说明如下：
字段 说明 示例
$session_id 标示一个 session 的唯一 id 2036149433
405577601
$session_po 标示一个 session 中事件的索引，从 0 开始，依次递增。1.14 及之前版本 session 中最后一个事件的索引是-1，如果 0
sition session 中只有1个事件，则索引值是-2 。1.15 及之后版本，不再有特殊的 -1、-2 索引值。
$session_ev session 内事件时长，表示session相邻两个事件发生的时间间隔，单位是秒，最后一个事件的事件时长是 null 354
ent_duration
$session_du session 内最后一个事件触发的时间减去 session 内第一个事件触发的时间，单位是秒 234
ration
$session_de session 深度，表示 session 内触发事件的次数 4
pth
$event_id$s Session 内第一次触发的事件 Signup
ession
因为 session 表的计算量较大，所以必须加上时间注解进行使用，比如：
SELECT event, user_id, distinct_id, date FROM sessions_default/*SESSION_TABLE_DATE_RANGE=[2018-01-01,2018-01-05]
*/
注意：由于 SESSION 表查询比较耗时，为了提升查询效率，目前不支持使用 select * 查询 SESSION 表，需要选择具体的字段名查询。
用户分群/标签表
这些表为系统中分群/标签结果的存储表，表中存储的用户为此分群/标签筛选出来的用户。不同版本的表命名规则有所不同，见下表：
系统版本 类型 表名规则 示例
<=1.13 分群 segmenter_${segmenter_name} segmenter_abc
>=1.14 分群 user_group_${user_group_name} user_group_abc
>=1.14 标签 user_tag_${user_tag_name} user_tag_abc
关于表中具体字段的说明如下:
字段 说明 示例
user_id 用户 id -9220214159525537212
distinct_id 与事件表中的 distinct_id 相关联 3f840957485db9a9
values 用户分群/标签值 1
base_time 用户分群/标签计算的基准时间，1.14 及之后版本之后新增 1547015611000
其中 base_time 是以毫秒形式进行的存储，所以在查询的时候，用户可以通过 unix_timestamp_ms 函数将日期转化成毫秒数进行查询，例子如下：
SELECT * FROM user_group_fenqun9 WHERE base_time=unix_timestamp_ms(''2019-01-17 00:00:00'')
Items 表
字段名称 说明 示例
$item_type item 表的类型 apple
$item_id 表示 item 的 id 123$is_valid 该 item 是否有效，不传入默认为 true 1
$receive_time 该 item 到达时间 1575604527772
$update_time 该 item 的更新时间，不传入默认为写入时间 1575604527772
数据类型
出于查询效率的考虑，自定义查询功能对不同的数据类型有不同处理，同时某些数据类型有一些使用上的限制，具体说明如下：
Number
数值类型，不区分浮点数与整数，输出的时候会根据是否有小数位自动转换输出格式。
String
字符串类型。
Date
注意：time 字段特殊，不需要经过转换即可直接使用。
日期类型，在自定义查询中表现为 毫秒级的 Timestamp，例如：1442937600000。
如果有需要，可以使用 EPOCH_TO_TIMESTAMP 函数转换为 Timestamp 类型，例如：
SELECT EPOCH_TO_TIMESTAMP($signup_time / 1000) FROM users LIMIT 100;
用于条件过滤的例子如下：
SELECT COUNT(*) AS cnt FROM users WHERE EPOCH_TO_TIMESTAMP($signup_time / 1000) > ''2017-01-01'';
Datetime
日期时间类型，和 Date 类型一样，也使用毫秒级的 Timestamp表示，例如：1442592138000。 同样也可以使用 EPOCH_TO_TIMESTAMP 类型进行类
型转换。
Bool
布尔类型，使用 0/1 表示 False/True。
List
列表类型，支持在 Where 条件里使用 CONTAINS 函数或者 LIKE 函数来进行过滤操作。例如：
SELECT FavoriteFruits from users where CONTAINS('''', FavoriteFruits);
同样也可以使用 /*EXPLODE_LIST_COLUMN=${table.columnName}*/ 注解来将 List 类型数据打散成多行 string 类型数据。例如：
SELECT list_property FROM events /*EXPLODE_LIST_COLUMN=events.list_property*/
功能使用
基本功能
在输入框中输入要查询的 SQL，例如查询每天的事件总数：SELECT date, COUNT(*) from events GROUP BY 1 ORDER BY 1
然后点击查询即可看到表格展现的结果，同时还有下方还有简单的图表展示，也可以使用 CSV 格式把结果下载下来进行进一步的分析。
出于性能的考虑，前端展示的结果最大只有 1k 条，而 CSV 下载的结果最大是 100w 条，如果需要下载更多数据请使用查询 API。
日期过滤
date 字段表示事件发生时的日期，精确到天，可以用于快速过滤数据。需要特别注意，任何时候都应当尽量使用 date 字段进行过滤，而不是 time 字段。
由于 date 字段的特殊性，对 SQL 操作和函数的支持有一些限制，目前支持使用的函数和表达式有:
CURRENT_DATE() 函数，返回当天，例如 2016-08-23。
CURRENT_WEEK() 函数，返回当周的周一，例如 2016-08-22。
CURRENT_MONTH() 函数，返回当月的一号，例如 2016-08-01。
INTERVAL 表达式，例如 CURRENT_DATE() - INTERVAL ''1'' DAY 表示昨天。
以下是一些具体的例子：
精确过滤某一天的数据
SELECT COUNT(*) FROM events WHERE date = ''2016-01-01''
查询当天的数据
SELECT COUNT(*) FROM events WHERE date = CURRENT_DATE()
查询最近 3 天的数据
SELECT COUNT(*) FROM events WHERE date BETWEEN CURRENT_DATE() - INTERVAL ''2'' DAY AND CURRENT_DATE()
查询上个自然月的数据
SELECT COUNT(*) FROM events WHERE date BETWEEN CURRENT_MONTH() - INTERVAL ''1'' MONTH AND CURRENT_MONTH() -
INTERVAL ''1'' DAY
由于 date 是专门为快速的数据过滤设计的特殊字段，不支持绝大多数的时间函数。因此，如果希望使用其它时间函数，请使用 time 字段代替，例
如：
SELECT datediff(now(), trunc(time, ''DD'')), COUNT(*) FROM events WHERE date >= CURRENT_DATE() - INTERVAL ''100''
day GROUP BY 1
按照月份聚合 2018-09-01 之后的事件数
SELECT date_sub(date,dayofmonth(date)-1) the_month,count(*) event_qty
FROM events WHERE date>''2018-09-01''
GROUP BY the_month ORDER BY the_month;
按照星期聚合 2018-09-01 之后的事件数
SELECT date_sub(date,mod(dayofweek(date)+5,7)) the_week,count(*) event_qty
FROM events WHERE date>''2018-09-01''
GROUP BY the_week ORDER BY the_week;
常用函数说明
使用自定义查询经常能用到如下几种函数：时间日期函数
字符串函数
数学函数
其他更多Impala函数，请参考：
Impala 函数参考文档
时间日期函数
自定义查询中和时间日期函数相关的字段分为以下三种：
一、events 表中的 time 字段
time 是毫秒级的 Timestamp 类型，可以直接使用所有的时间日期函数。
二、events 表中的 date 字段
date 是天级别的 Timestamp 类型，如果不需要时分秒的信息，使用这个字段效率会更高。date 同时也是索引字段，所以应该尽量使用此字段进行日期范围
的过滤，具体请参考 "日期过滤" 中的说明。
注：1.10 版本之前，date 字段不支持使用自定义函数，可以使用 time 替代。
三、其它自定义的 Date/Datetime 类型的属性
这类属性在自定义查询中表现为毫秒级的 Unix 时间戳， 使用时间日期函数时需要先使用 EPOCH_TO_TIMESTAMP 函数转换为 Timestamp 类型，请参考
"数据类型" 中的说明。
adddate(timestamp startdate, int days), adddate(timestamp startdate, bigint days)
用途：在一个TIMESTAMP（时间戳）值上加一个给定的天数
参数：
startdate：timestamp 类 型 的 开 始 时 间 戳 days：
需要加上的天数，正数表示几天之后，负数表示几天之前
返回值：加上天数之后的时间戳，timestamp类型
datediff(timestamp enddate, timestamp startdate)
用途：返回两个时间戳间隔天数,例如：
参数：
enddate：结束时间
startdate：开始时间
返回值：结束时间减去开始时间的天数，int类型。如果第一个参数时间的日期晚于第二个参数时间的日期，返回正数；相反，如果第一个参数时间的日期早
于第二个参数时间的日期，返回负数
extract(unit FROM timestamp), extract(timestamp, string unit)
用途：从TIMESTAMP值中截取数值型的时间域，例如年度，月份，日期，小时，分钟，秒/微秒
参数：
unit：时间单位unit字符串可取的值有：year，month，day，hour，minute，second，millisecond。
返回值：时间域的整型值
例如：目前为止所有的支付订单次数按照年度和月份查询
SELECT extract(Year from time) AS Year, extract(Month from time) AS Month, COUNT(*) FROM events
WHERE event = ''payOrder''
GROUP BY Year, Month
ORDER BY Year, Month
trunc(timestamp, string unit)
用途：从给定的timestamp时间戳截取时间域
参数：unit：时间单位
SYYYY, YYYY, YEAR, SYEAR, YYY, YY, Y：年度
Q：季度
MONTH, MON, MM, RM: 月 份
WW, W: 相应周第一天的日期
DDD, DD, J: 日期
DAY, DY, D: 相应周第一天的日期
HH, HH12, HH24: 小时
MI: 分钟
返回值：截取时间域之后的日期
例如：最近100天内每天发生的事件数和事件发生时间与当前日期的间隔天
SELECT datediff(now(), trunc(time, ''DD'')), COUNT(*) FROM events
WHERE date >= CURRENT_DATE() - INTERVAL ''100'' day
GROUP BY 1
字符串函数
concat(string a, string b…)
用途：把所有string类型的参数连接成一个string类型
参数：
string(不限个数)：要连接的字符串
返回值：一个整体的字符串
例如：查询00后用户地址，地址为省份和地区拼接
SELECT concat($province, $city) As Address
FROM users
WHERE yearofbirth > 2000
regexp_like(string source, string pattern[, string options])
用途：判断source字符串中是否包含以pattern为正则表达式的内容
参数：
source：要检查的字符串
pattern：正则表达式
option（选填）：选项
c：区分大小写i：
不区分大小写
m：匹配多行，^和$操作符对于每一行都会匹配，而不是对多行为整体的开头和结束。 n：
新行匹配，点（.）操作符会匹配新行。重复操作符如 . 可以匹配source字符串中的多行（可以通过. 跳过几行）
返回值：匹配与否，boolean类型
例如：使用QQ邮箱为邮件的用户数
SELECT COUNT(*) FROM users
WHERE regexp_like(email, ''@qq.com$'')
parse_url(string urlString, string partToExtract [, string keyToExtract])
用途：通过指定URL中的特定部分返回截取值
参数：
urlString：URL
partToExtract：要截取的部分。可指定的值为''PROTOCOL'', ''HOST'', ''PATH'', ''REF'', ''AUTHORITY'', ''FILE'', ‘USERINFO'', ‘QUERY''
PROTOCOL：协议，如HTTP，HTTPS，FTP等
HOST：主机名
PATH：路径
REF：锚点（“又称引用”），即URL中#后面的字符串AUTHORITY：授权
FILE：文件名
USERINFO：用户信息
QUERY： 查 询 参 数 ， 即 URL 中 ？ 后 面 的 字 符 串 keyToExtract
（选填）：当partToExtract为’QUERY’时，可以指定query键值对中的key，获取指定参数值
返回值：URL中指定部分的截取值
例如：当天页面浏览事件中各个路径的访问分布情况
SELECT parse_url(url, ''PATH''), COUNT(*) FROM events
WHERE date = CURRENT_DATE() AND event = ''$pageview''
GROUP BY 1
数学函数
数学函数用于一些数值的操作。 特别的，在做去幂运算时，请使用pow()函数取代幂运算符 ‘**’。
pow(double a, double p), power(double a, double p), dpow(double a, double p), fpow(double a, double p)
用途：取幂，例如：
参数：
a：底数
b：指数
返回值：a的b次幂
例如：查询理财产品到期后本息总额超过10万的用户数
SELECT count(distinct(user_id)) FROM events
WHERE event = ''buyProduct'' AND (capital + capital * pow(rateofinterest,duration)) > 100000
round(double a), round(double a, int d), round(decimal a, int_type d), dround(double a), dround(double a, int d)
用途：返回四舍五入值，例如：
参数：
a：要四舍五入的数值 d
（可选）：小数保留位数，若无此参数，保留到整数部分
返回值：四舍五入值
例如：查询理财产品收益率超过0.45百分点的用户数
SELECT count(distinct(user_id)) FROM events
WHERE event = ''buyProduct'' AND round((income/capital),4) * 100 > 0.45
truncate(double_or_decimal a[, digits_to_leave]), dtrunc(double_or_decimal a[, digits_to_leave])
用途：去除小数部分的数值，例如：
参数：
a： 被 截 取 的 数 值 digits_to_leave
（可选）：小数点保留位数，若无此参数，保留到整数部分
返回值：被截取的值
高级选项
开启快速 Distinct 算法，可以大大加速类似 COUNT(DISTINCT user_id) 的计算，并且支持多个 COUNT(DISTINCT) 表达式，缺点是会得到不完全
精确的结果。例如：SELECT COUNT(DISTINCT user_id) FROM events
WHERE date = CURRENT_DATE() /*ENABLE_APPROX_DISTINCT*/
开启维度字典映射和维度表关联，默认关闭。例如：
SELECT $model FROM events
WHERE date = CURRENT_DATE() /*ENABLE_DIMENSION_DICT_MAPPING*/
如果 SQL 是查询某个指定 Distinct Id 的数据，可以用此选项来进行查询查询。例如：
SELECT event, time FROM events
WHERE date = CURRENT_DATE() AND distinct_id=''abcdef'' /*DISTINCT_ID_FILTER=abcdef*/
SQL 默认在执行 10 分钟之后会被系统强制杀死，如果希望增大超时时间可以使用如下方式：
SELECT * FROM events WHERE date = CURRENT_DATE() LIMIT 1000 /*MAX_QUERY_EXECUTION_TIME=1800*/
对于 JOIN 类查询，可以使用 Join Hint 来指定 Join 的执行方式，可以是 SHUFFLE 或者 BROADCAST。尤其是在执行过程中如果遇到内存不足
的错误，可以考虑强制指定为 SHUFFLE 模式：
SELECT COUNT(*) AS cnt FROM events
JOIN /* +SHUFFLE */ users ON events.user_id = users.id
WHERE date = CURRENT_DATE()
常见案例
根据用户的 distinct_id 查询某个用户在某天的具体行为
直接使用 distinct_id 查询即可:
SELECT * FROM events WHERE distinct_id = ''wahaha'' AND date = ''2015-09-10'' LIMIT 100
查询每天上午 10 点至 11 点的下单用户数
使用标准的 SQL 日期函数 EXTRACT 来取出小时信息。
SELECT date, COUNT(*) FROM events
WHERE EXTRACT(HOUR FROM time) IN (10, 11) AND event = ''SubmitOrder''
GROUP BY 1
查询一段时间内的用户下单次数分布情况
首先计算每个用户的下单次数，然后使用 CASE..WHEN 语法来分组。SELECT
CASE
WHEN c < 10 THEN ''<10''
WHEN c < 20 THEN ''<20''
WHEN c < 100 THEN ''<100''
ELSE ''>100''
END,
COUNT(*)
FROM (
SELECT user_id, COUNT(*) AS c FROM events
WHERE date BETWEEN ''2015-09-01'' AND ''2015-09-20'' AND event = ''SubmitOrder''
GROUP BY 1
)a
GROUP BY 1
查询做了行为 A 而没有做行为 B 的用户数
使用 LEFT OUTER JOIN 计算差集。
SELECT a.user_id FROM (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''BuyGold''
) a
LEFT OUTER JOIN (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''SaleGold''
) b
ON a.user_id = b.user_id
WHERE b.user_id IS NULL
计算用户的使用时长
使用分析函数，根据每个用户相邻的两个事件的间隔估算累计使用时长，如果两次使用间隔超出10分钟则不计算。
SELECT
user_id,
SUM(
CASE WHEN
end_time - begin_time < 600
THEN
end_time - begin_time
ELSE
0
END
) FROM (
SELECT
user_id,
EXTRACT(EPOCH FROM time) AS end_time,
LAG(EXTRACT(EPOCH FROM time), 1, NULL) OVER (PARTITION BY user_id ORDER BY time asc) AS begin_time
FROM events
WHERE date=''2015-5-1''
) a
GROUP BY 1
获取用户的首次行为属性
使用 first_time_value(time, 其他属性) 聚合函数来获取第一次发生某行为时的相关属性-- 1 URL
SELECT user_id, first_time_value(time, $url) FROM events WHERE event = ''$pageview'' GROUP BY user_id
-- 2
SELECT user_id, first_time_value(time, order_amount) first_order_amount FROM events WHERE event = ''payOrder''
GROUP BY user_id.自定义查询 v1.17
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
对于使用现有的 UI 功能暂时无法满足的高级数据需求，我们提供了更加自由的自定义查询功能。该功能支持使用标准 SQL 来对神策分析的所有数据进行查
询，同时也包含对查询结果的简单可视化。
注: 当前版本的自定义查询工具基于 HUE 项目构建。
数据表
目前，神策分析的所有数据映射到 事件 和 用户 这两张数据表，在 SQL 里使用这两张数据表即可完成所有查询。同时支持将客户创建的所有 session 映射
成 sessions_${session_name} 命名的表。以下列举字段都为特殊字段，其他未列举且带 "$" 的属性都为神策预置属性，具体含义可参考文档 预置事件与预
置属性，不带 "$" 的属性都为自定义属性，具体含义需跟对应埋点人员确认。
事件表 (events)
事件表包含了所有事件的详细信息（不包括虚拟事件），该表的每一行代表一个 track 的 Event。事件表的字段分为特殊字段和 Event 本身的 Property 两
大类。其中特殊字段如下：
字段 说明 示例
event 事件的名称 BuyGold
user_id 神策分析为该用户分配的内部 ID，与 user 表的 id 字段相关联 1234
distinct_ 用户的原始 ID，track 时传入，可能是一个匿名 ID 或 登录 ID wahaha
id
date 事件发生的日期,属于特殊字段，上传数据时无需上传 date 字段 2015-09-21
time 事件发生的具体时间 2015-09-21
11:11:11
$receive 服务器接收到事件时的具体时间戳。该字段可以在自定义查询中显示，在前端的分析模块中，所有事件都无法使用该字段分 15702305860
_time 析数据，因为 $receive_time 默认不会与任何事件绑定。 48
需要特别注意的是，事件表的 user_id 字段并不是 track 时传入的 distinct_id，而是由神策分析为该用户分配的内部 ID，具体的机制见如何准确的标识用户
用户表 (users)
用户表的每一行代表一个 User，类似于事件表，用户表的字段也分为特殊字段和 User 的其它 Profile 两大类，其中特殊字段的说明如下：
字 说明 示例
段
id 神策分析为该用户分配的内部 ID，与 events 表的 user_id 相关联 1234567
first_id 该用户的匿名 ID，与 events 表登录前行为的 distinct_id 相关联。需要特别注意，如果 0c476090a0b2940a
某个用户 first_id 的值等于 second_id，说明该用户没有成功关联到匿名 ID，相当于未
知
secon 该用户的登录 ID，与 events 表登录后行为的 distinct_id 相关联 wahaha
d_id
$upd 该用户最近一次更新用户表信息的时间戳 1570230586048
ate_ti
me
$devi 开启多对一关联机制时，会记录与登录 ID 关联的匿名 ID 列表，以及关联时的时间戳 1570230586048:0c476090a0b2940a；
ce_id 1570230591000:65A71299-7139-4B4C-9B71-
_list 23A0AC9AAF7D
Session 表每张 Session 表都对应一个 Session 的配置，命名规则为：sessions_${session_name}。
Session 表是对 events 表做了扩展，除了包含 events 表包含的字段，还包含 session 属性和 session 相关的特殊字段，session 属性的命名规则是原始的
属性名加上后缀 $session，表示 session 中初始事件的属性。其中特殊字段说明如下：
字段 说明 示例
$session_id 标示一个 session 的唯一 id 2036149433
405577601
$session_po 标示一个 session 中事件的索引，从 0 开始，依次递增。1.14 及之前版本 session 中最后一个事件的索引是-1，如果 0
sition session 中只有1个事件，则索引值是-2 。1.15 及之后版本，不再有特殊的 -1、-2 索引值。
$session_ev session 内事件时长，表示session相邻两个事件发生的时间间隔，单位是秒，最后一个事件的事件时长是 null 354
ent_duration
$session_du session 内最后一个事件触发的时间减去 session 内第一个事件触发的时间，单位是秒 234
ration
$session_de session 深度，表示 session 内触发事件的次数 4
pth
$event_id$s Session 内第一次触发的事件 Signup
ession
因为 session 表的计算量较大，所以必须加上时间注解进行使用，比如：
SELECT event, user_id, distinct_id, date FROM sessions_default/*SESSION_TABLE_DATE_RANGE=[2018-01-01,2018-01-05]
*/
注意：由于 SESSION 表查询比较耗时，为了提升查询效率，目前不支持使用 select * 查询 SESSION 表，需要选择具体的字段名查询。
用户分群/标签表
这些表为系统中分群/标签结果的存储表，表中存储的用户为此分群/标签筛选出来的用户。不同版本的表命名规则有所不同，见下表：
系统版本 类型 表名规则 示例
<=1.13 分群 segmenter_${segmenter_name} segmenter_abc
>=1.14 分群 user_group_${user_group_name} user_group_abc
>=1.14 标签 user_tag_${user_tag_name} user_tag_abc
关于表中具体字段的说明如下:
字段 说明 示例
user_id 用户 id -9220214159525537212
distinct_id 与事件表中的 distinct_id 相关联 3f840957485db9a9
values 用户分群/标签值 1
base_time 用户分群/标签计算的基准时间，1.14 及之后版本之后新增 1547015611000
其中 base_time 是以毫秒形式进行的存储，所以在查询的时候，用户可以通过 unix_timestamp_ms 函数将日期转化成毫秒数进行查询，例子如下：
SELECT * FROM user_group_fenqun9 WHERE base_time=unix_timestamp_ms(''2019-01-17 00:00:00'')
Items 表
字段名称 说明 示例
$item_type item 表的类型 apple
$item_id 表示 item 的 id 123$is_valid 该 item 是否有效，不传入默认为 true 1
$receive_time 该 item 到达时间 1575604527772
$update_time 该 item 的更新时间，不传入默认为写入时间 1575604527772
数据类型
出于查询效率的考虑，自定义查询功能对不同的数据类型有不同处理，同时某些数据类型有一些使用上的限制，具体说明如下：
Number
数值类型，不区分浮点数与整数，输出的时候会根据是否有小数位自动转换输出格式。
String
字符串类型。
Date
注意：time 字段特殊，不需要经过转换即可直接使用。
日期类型，在自定义查询中表现为 毫秒级的 Timestamp，例如：1442937600000。
如果有需要，可以使用 EPOCH_TO_TIMESTAMP 函数转换为 Timestamp 类型，例如：
SELECT EPOCH_TO_TIMESTAMP($signup_time / 1000) FROM users LIMIT 100;
用于条件过滤的例子如下：
SELECT COUNT(*) AS cnt FROM users WHERE EPOCH_TO_TIMESTAMP($signup_time / 1000) > ''2017-01-01'';
Datetime
日期时间类型，和 Date 类型一样，也使用毫秒级的 Timestamp表示，例如：1442592138000。 同样也可以使用 EPOCH_TO_TIMESTAMP 类型进行类
型转换。
Bool
布尔类型，使用 0/1 表示 False/True。
List
列表类型，支持在 Where 条件里使用 CONTAINS 函数或者 LIKE 函数来进行过滤操作。例如：
SELECT FavoriteFruits from users where CONTAINS('''', FavoriteFruits);
同样也可以使用 /*EXPLODE_LIST_COLUMN=${table.columnName}*/ 注解来将 List 类型数据打散成多行 string 类型数据。例如：
SELECT list_property FROM events /*EXPLODE_LIST_COLUMN=events.list_property*/
功能使用
基本功能
在输入框中输入要查询的 SQL，例如查询每天的事件总数：SELECT date, COUNT(*) from events GROUP BY 1 ORDER BY 1
然后点击查询即可看到表格展现的结果，同时还有下方还有简单的图表展示，也可以使用 CSV 格式把结果下载下来进行进一步的分析。
出于性能的考虑，前端展示的结果最大只有 1k 条，而 CSV 下载的结果最大是 100w 条，如果需要下载更多数据请使用查询 API。
日期过滤
date 字段表示事件发生时的日期，精确到天，可以用于快速过滤数据。需要特别注意，任何时候都应当尽量使用 date 字段进行过滤，而不是 time 字段。
由于 date 字段的特殊性，对 SQL 操作和函数的支持有一些限制，目前支持使用的函数和表达式有:
CURRENT_DATE() 函数，返回当天，例如 2016-08-23。
CURRENT_WEEK() 函数，返回当周的周一，例如 2016-08-22。
CURRENT_MONTH() 函数，返回当月的一号，例如 2016-08-01。
INTERVAL 表达式，例如 CURRENT_DATE() - INTERVAL ''1'' DAY 表示昨天。
以下是一些具体的例子：
精确过滤某一天的数据
SELECT COUNT(*) FROM events WHERE date = ''2016-01-01''
查询当天的数据
SELECT COUNT(*) FROM events WHERE date = CURRENT_DATE()
查询最近 3 天的数据
SELECT COUNT(*) FROM events WHERE date BETWEEN CURRENT_DATE() - INTERVAL ''2'' DAY AND CURRENT_DATE()
查询上个自然月的数据
SELECT COUNT(*) FROM events WHERE date BETWEEN CURRENT_MONTH() - INTERVAL ''1'' MONTH AND CURRENT_MONTH() -
INTERVAL ''1'' DAY
由于 date 是专门为快速的数据过滤设计的特殊字段，不支持绝大多数的时间函数。因此，如果希望使用其它时间函数，请使用 time 字段代替，例
如：
SELECT datediff(now(), trunc(time, ''DD'')), COUNT(*) FROM events WHERE date >= CURRENT_DATE() - INTERVAL ''100''
day GROUP BY 1
按照月份聚合 2018-09-01 之后的事件数
SELECT date_sub(date,dayofmonth(date)-1) the_month,count(*) event_qty
FROM events WHERE date>''2018-09-01''
GROUP BY the_month ORDER BY the_month;
按照星期聚合 2018-09-01 之后的事件数
SELECT date_sub(date,mod(dayofweek(date)+5,7)) the_week,count(*) event_qty
FROM events WHERE date>''2018-09-01''
GROUP BY the_week ORDER BY the_week;
常用函数说明
使用自定义查询经常能用到如下几种函数：时间日期函数
字符串函数
数学函数
其他更多Impala函数，请参考：
Impala 函数参考文档
时间日期函数
自定义查询中和时间日期函数相关的字段分为以下三种：
一、events 表中的 time 字段
time 是毫秒级的 Timestamp 类型，可以直接使用所有的时间日期函数。
二、events 表中的 date 字段
date 是天级别的 Timestamp 类型，如果不需要时分秒的信息，使用这个字段效率会更高。date 同时也是索引字段，所以应该尽量使用此字段进行日期范围
的过滤，具体请参考 "日期过滤" 中的说明。
注：1.10 版本之前，date 字段不支持使用自定义函数，可以使用 time 替代。
三、其它自定义的 Date/Datetime 类型的属性
这类属性在自定义查询中表现为毫秒级的 Unix 时间戳， 使用时间日期函数时需要先使用 EPOCH_TO_TIMESTAMP 函数转换为 Timestamp 类型，请参考
"数据类型" 中的说明。
adddate(timestamp startdate, int days), adddate(timestamp startdate, bigint days)
用途：在一个TIMESTAMP（时间戳）值上加一个给定的天数
参数：
startdate：timestamp 类 型 的 开 始 时 间 戳 days：
需要加上的天数，正数表示几天之后，负数表示几天之前
返回值：加上天数之后的时间戳，timestamp类型
datediff(timestamp enddate, timestamp startdate)
用途：返回两个时间戳间隔天数,例如：
参数：
enddate：结束时间
startdate：开始时间
返回值：结束时间减去开始时间的天数，int类型。如果第一个参数时间的日期晚于第二个参数时间的日期，返回正数；相反，如果第一个参数时间的日期早
于第二个参数时间的日期，返回负数
extract(unit FROM timestamp), extract(timestamp, string unit)
用途：从TIMESTAMP值中截取数值型的时间域，例如年度，月份，日期，小时，分钟，秒/微秒
参数：
unit：时间单位unit字符串可取的值有：year，month，day，hour，minute，second，millisecond。
返回值：时间域的整型值
例如：目前为止所有的支付订单次数按照年度和月份查询
SELECT extract(Year from time) AS Year, extract(Month from time) AS Month, COUNT(*) FROM events
WHERE event = ''payOrder''
GROUP BY Year, Month
ORDER BY Year, Month
trunc(timestamp, string unit)
用途：从给定的timestamp时间戳截取时间域
参数：unit：时间单位
SYYYY, YYYY, YEAR, SYEAR, YYY, YY, Y：年度
Q：季度
MONTH, MON, MM, RM: 月 份
WW, W: 相应周第一天的日期
DDD, DD, J: 日期
DAY, DY, D: 相应周第一天的日期
HH, HH12, HH24: 小时
MI: 分钟
返回值：截取时间域之后的日期
例如：最近100天内每天发生的事件数和事件发生时间与当前日期的间隔天
SELECT datediff(now(), trunc(time, ''DD'')), COUNT(*) FROM events
WHERE date >= CURRENT_DATE() - INTERVAL ''100'' day
GROUP BY 1
字符串函数
concat(string a, string b…)
用途：把所有string类型的参数连接成一个string类型
参数：
string(不限个数)：要连接的字符串
返回值：一个整体的字符串
例如：查询00后用户地址，地址为省份和地区拼接
SELECT concat($province, $city) As Address
FROM users
WHERE yearofbirth > 2000
regexp_like(string source, string pattern[, string options])
用途：判断source字符串中是否包含以pattern为正则表达式的内容
参数：
source：要检查的字符串
pattern：正则表达式
option（选填）：选项
c：区分大小写i：
不区分大小写
m：匹配多行，^和$操作符对于每一行都会匹配，而不是对多行为整体的开头和结束。 n：
新行匹配，点（.）操作符会匹配新行。重复操作符如 . 可以匹配source字符串中的多行（可以通过. 跳过几行）
返回值：匹配与否，boolean类型
例如：使用QQ邮箱为邮件的用户数
SELECT COUNT(*) FROM users
WHERE regexp_like(email, ''@qq.com$'')
parse_url(string urlString, string partToExtract [, string keyToExtract])
用途：通过指定URL中的特定部分返回截取值
参数：
urlString：URL
partToExtract：要截取的部分。可指定的值为''PROTOCOL'', ''HOST'', ''PATH'', ''REF'', ''AUTHORITY'', ''FILE'', ‘USERINFO'', ‘QUERY''
PROTOCOL：协议，如HTTP，HTTPS，FTP等
HOST：主机名
PATH：路径
REF：锚点（“又称引用”），即URL中#后面的字符串AUTHORITY：授权
FILE：文件名
USERINFO：用户信息
QUERY： 查 询 参 数 ， 即 URL 中 ？ 后 面 的 字 符 串 keyToExtract
（选填）：当partToExtract为’QUERY’时，可以指定query键值对中的key，获取指定参数值
返回值：URL中指定部分的截取值
例如：当天页面浏览事件中各个路径的访问分布情况
SELECT parse_url(url, ''PATH''), COUNT(*) FROM events
WHERE date = CURRENT_DATE() AND event = ''$pageview''
GROUP BY 1
数学函数
数学函数用于一些数值的操作。 特别的，在做去幂运算时，请使用pow()函数取代幂运算符 ‘**’。
pow(double a, double p), power(double a, double p), dpow(double a, double p), fpow(double a, double p)
用途：取幂，例如：
参数：
a：底数
b：指数
返回值：a的b次幂
例如：查询理财产品到期后本息总额超过10万的用户数
SELECT count(distinct(user_id)) FROM events
WHERE event = ''buyProduct'' AND (capital + capital * pow(rateofinterest,duration)) > 100000
round(double a), round(double a, int d), round(decimal a, int_type d), dround(double a), dround(double a, int d)
用途：返回四舍五入值，例如：
参数：
a：要四舍五入的数值 d
（可选）：小数保留位数，若无此参数，保留到整数部分
返回值：四舍五入值
例如：查询理财产品收益率超过0.45百分点的用户数
SELECT count(distinct(user_id)) FROM events
WHERE event = ''buyProduct'' AND round((income/capital),4) * 100 > 0.45
truncate(double_or_decimal a[, digits_to_leave]), dtrunc(double_or_decimal a[, digits_to_leave])
用途：去除小数部分的数值，例如：
参数：
a： 被 截 取 的 数 值 digits_to_leave
（可选）：小数点保留位数，若无此参数，保留到整数部分
返回值：被截取的值
高级选项
开启快速 Distinct 算法，可以大大加速类似 COUNT(DISTINCT user_id) 的计算，并且支持多个 COUNT(DISTINCT) 表达式（1.17+版本，不加此
注释，也可以支持多个 COUNT(DISTINCT) ，但是 1.16 及之前版本，必须加此注释才能支持多个 COUNT(DISTINCT) ），缺点是会得到不完全精
确的结果。例如：SELECT COUNT(DISTINCT user_id) FROM events
WHERE date = CURRENT_DATE() /*ENABLE_APPROX_DISTINCT*/
开启维度字典映射和维度表关联，默认关闭。例如：
SELECT $model FROM events
WHERE date = CURRENT_DATE() /*ENABLE_DIMENSION_DICT_MAPPING*/
如果 SQL 是查询某个指定 Distinct Id 的数据，可以用此选项来进行查询查询。例如：
SELECT event, time FROM events
WHERE date = CURRENT_DATE() AND distinct_id=''abcdef'' /*DISTINCT_ID_FILTER=abcdef*/
SQL 默认在执行 10 分钟之后会被系统强制杀死，如果希望增大超时时间可以使用如下方式：
SELECT * FROM events WHERE date = CURRENT_DATE() LIMIT 1000 /*MAX_QUERY_EXECUTION_TIME=1800*/
对于 JOIN 类查询，可以使用 Join Hint 来指定 Join 的执行方式，可以是 SHUFFLE 或者 BROADCAST。尤其是在执行过程中如果遇到内存不足
的错误，可以考虑强制指定为 SHUFFLE 模式：
SELECT COUNT(*) AS cnt FROM events
JOIN /* +SHUFFLE */ users ON events.user_id = users.id
WHERE date = CURRENT_DATE()
常见案例
根据用户的 distinct_id 查询某个用户在某天的具体行为
直接使用 distinct_id 查询即可:
SELECT * FROM events WHERE distinct_id = ''wahaha'' AND date = ''2015-09-10'' LIMIT 100
查询每天上午 10 点至 11 点的下单用户数
使用标准的 SQL 日期函数 EXTRACT 来取出小时信息。
SELECT date, COUNT(*) FROM events
WHERE EXTRACT(HOUR FROM time) IN (10, 11) AND event = ''SubmitOrder''
GROUP BY 1
查询一段时间内的用户下单次数分布情况
首先计算每个用户的下单次数，然后使用 CASE..WHEN 语法来分组。SELECT
CASE
WHEN c < 10 THEN ''<10''
WHEN c < 20 THEN ''<20''
WHEN c < 100 THEN ''<100''
ELSE ''>100''
END,
COUNT(*)
FROM (
SELECT user_id, COUNT(*) AS c FROM events
WHERE date BETWEEN ''2015-09-01'' AND ''2015-09-20'' AND event = ''SubmitOrder''
GROUP BY 1
)a
GROUP BY 1
查询做了行为 A 而没有做行为 B 的用户数
使用 LEFT OUTER JOIN 计算差集。
SELECT a.user_id FROM (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''BuyGold''
) a
LEFT OUTER JOIN (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''SaleGold''
) b
ON a.user_id = b.user_id
WHERE b.user_id IS NULL
计算用户的使用时长
使用分析函数，根据每个用户相邻的两个事件的间隔估算累计使用时长，如果两次使用间隔超出10分钟则不计算。
SELECT
user_id,
SUM(
CASE WHEN
end_time - begin_time < 600
THEN
end_time - begin_time
ELSE
0
END
) FROM (
SELECT
user_id,
EXTRACT(EPOCH FROM time) AS end_time,
LAG(EXTRACT(EPOCH FROM time), 1, NULL) OVER (PARTITION BY user_id ORDER BY time asc) AS begin_time
FROM events
WHERE date=''2015-5-1''
) a
GROUP BY 1
获取用户的首次行为属性
使用 first_time_value(time, 其他属性) 聚合函数来获取第一次发生某行为时的相关属性-- 1 URL
SELECT user_id, first_time_value(time, $url) FROM events WHERE event = ''$pageview'' GROUP BY user_id
-- 2
SELECT user_id, first_time_value(time, order_amount) first_order_amount FROM events WHERE event = ''payOrder''
GROUP BY user_id
版本变更
Impala 从 2.12 版本升级到 3.2，有少量的不兼容语法变化。
GROUP BY、HAVING、ORDER BY 中的别名替换逻辑与标准 SQL 行为更一致，即别名仅在顶级表达式有效，而在子表达式中无效。例如：
/* */
SELECT NOT bool_col AS nb
FROM t
GROUP BY nb
HAVING nb;
/* */
SELECT int_col / 2 AS x
FROM t
GROUP BY x
HAVING x > 3;
新增了一系列的保留字段，这些字段是不能直接用作标识符的。如果需要将其用作标识符，则必须用反引号引起来，例如：
/* */
SELECT `position` FROM events
/* */
SELECT position FROM events
新增的保留字段包括：
allocate、any、api_version、are、array_agg、array_max_cardinality、asensitive、asymmetric、at、atomic、authorization、begin_frame、
begin_partition、blob、block_size、both、called、cardinality、cascaded、character、clob、close_fn、collate、collect、commit、condition、
connect、constraint、contains、convert、copy、corr、corresponding、covar_pop、covar_samp、cube、current_date、
current_default_transform_group、current_path、current_role、current_row、current_schema、current_time、
current_transform_group_for_type、cursor、cycle、deallocate、dec、decfloat、declare、define、deref、deterministic、disconnect、dynamic、
each、element、empty、end-exec、end_frame、end_partition、equals、escape、every、except、exec、execute、fetch、filter、finalize_fn、
foreign、frame_row、free、fusion、get、global、grouping、groups、hold、indicator、init_fn、initial、inout、insensitive、intersect、
intersection、json_array、json_arrayagg、jso、n_exists、json_object、json_objectagg、json_query、json_table、json_table_primitive、
json_value、large、lateral、leading、like_regex、listagg、local、localtimestamp、log10、match、match_number、match_recognize、matches、
merge、merge_fn、method、modifies、multiset、national、natural、nchar、nclob、no、none、normalize、nth_value、nth_value、
occurrences_regex、octet_length、of、off、omit、one、only、out、overlaps、overlay、pattern、per、percent、percentile_cont、
percentile_disc、portion、position、position_regex、precedes、prepare、prepare_fn、procedure、ptf、reads、recursive、ref、references、
regr_avgx、regr_avgy、regr_count、regr_intercept、regr_r2、regr_slope、regr_sxx、regr_sxy、regr_syy、release、rollback、rollup、running、
savepoint、scope、scroll、search、seek、serialize_fn、similar、skip、some、specific、specifictype、sqlexception、sqlexception、sqlwarning、
static、straight_join、submultiset、subset、substring_regex、succeeds、symmetric、system_time、system_user、timezone_hour、
timezone_minute、trailing、translate_regex、translation、treat、trigger、trim_array、uescape、unique、unnest、update_fn、value_of、
varbinary、varying、versioning、whenever、width_bucket、window、within、without
Impala 保留字段参考文档用户分群.用户分群 v1.13
快速了解用户分群
1. 用户分群概述
分群是依据用户的属性特征和行为特征将用户群体进行分类，对其进行观察和分析的方式。
2. 如何创建用户分群？
我们可以通过 3 种方式创建用户分群：
1. 通过选择用户的行为规则条件创建；
2. 通过上传 ID 列表创建；
3. 通过保存分析结果的用户列表创建。
2.1. 通过选择用户的行为规则条件创建
用户分群主页右上角为创建入口。点击 A 处，进入创建步骤，依次填写基本信息和设置用户行为与属性等规则条件。在 B 处填写分群名称，创建后可修改。
C 处会根据分群名称自动填充拼音形式的分群 ID，用于推送识别，创建后作为唯一标识不可修改。
在 D 处选择计算周期，分为例行和单次。例行：每日凌晨更新计算。单次：每次手动更新计算。
在 E 处进行推送设置，设置后可在推送平台选择分群用于推送。（需要在“推送管理”中添加好配置才可在此处选择）。在
F 处选择用户属性和行为规则，点击 G 处完成分群的创建。行为规则条件描述能力的强化
2.2. 通过上传 ID 列表创建
支持通过上传用户 ID 列表创建静态用户分群。上传文本的内容和格式
点击 A 处进入上传创建的步骤。点击 C 处下载文件格式参考模板，待上传的 ID 列表准备完成后，点击 B 处，选择 txt 格式的 ID 列表文件，上传完成后点击 D 处进行创建。
2.3. 通过保存分析结果的用户列表创建
通过分析模型得出人群结果后，点击带有下划线的人数，在提示框中点击 A 处可将该群用户保存为结果分群。
3. 用户分群的管理和查看3.1. 管理用户分群
用户分群通过以上方式创建后，可在分群模块的主页进行查看、监控和管理。用户分群默认按照最新创建时间，以列表的形式由上往下排列。可通过表头的
筛选和右侧搜索快速查找分群。
A 处显示当前筛选条件下的分群各状态的数量分布。
B 处为搜索框，输入分群名称进行搜索。
C 处显示用户分群状态：已启用和暂停。已启用表示用户分群正常运行未被暂停，例行分群按设置定时更新。暂停指例行的用户分群暂停例行计算。若分群
较多，可暂停不需要使用的例行分群，节省计算资源。如需启用可再次开启。
D 处显示分群名称。规则创建的分群点击名称后进入分群详情页面，上传创建和结果创建的分群，点击名称直接查看用户列表。
E 处显示最新一次计算结果的人数。
F 处显示计算周期，分为单次和例行（按天）。
G 处显示分群的类型，按照创建形式分为：规则创建（通过选择用户的行为规则条件创建）、上传创建（通过上传 ID 列表创建）和结果创建（通过保存分析
结果的用户列表创建）。
H 处显示最后计算的状态（成功或失败）和时间。
I 处显示创建者信息。
J 处显示可进行操作的按钮。可查看和删除分群。
3.2. 查看用户分群详情
在用户分群列表中点击规则创建的用户分群的名称，可查看详情信息，包括基本信息（分群人数、计算周期、创建者等）、历史计算结果趋势和列表。右上角为操作区域，点击 A 处，进入编辑页面。可编辑名称、查看行为规则条件或复制规则创建新的用户分群。
B 处修改分群名称，C 处为分群 ID，不可修改，光标全选后可复制粘贴使用。D 处修改推送设置。计算周期和规则不可修改。若需要修改规则可点击 E 处，
通过复制规则，创建新的用户分群来实现。点击 F 处更新最近一次用户分群的计算结果（根据最新数据重新计算分群）。点击 G 处暂停该用户分群的例行计算，其他功能不受影响，可再次点击开启例
行计算。点击 H 处下载历次分群的用户数列表。点击 I 处删除分群。点击对应的柱图，会弹出面板，可查看、下载用户列表和更新分群（按照当次结果的原基准时间重新计算）。在下方列表区域可进行同样的操作。用户分群计算时，需要等待计算结束后才能下载此次分群的结果。3.3. 查看用户列表和用户行为序列
点击结果创建和上传创建分群的名称或者在分群详情点击带有下划线的人数可查看用户列表。
点击列表首列的 ID 名称可查看具体的 用户行为序列。4. 如何使用用户分群？
4.1. 在分析模型中使用
用户分群创建后，可在分析模型中对该用户群进行分析。例如，我们通过定义“每月充值金额大于等于 1000 元人民币”的用户为，并将其创建为用户分群。创
建完成后，可在事件分析模型中筛选出，观察其在某活动期间游戏充值金额的变化，衡量活动的运营效果。4.1.1. 在概览中使用
根据特定的业务创建分群后，可将其添加到概览中持续观察。例如，按照企业实际的业务场景，在分群模块按用户阶段筛选出新用户、忠诚用户、成熟用户
和流失用户四类人群。
在属性分析模型中，显示“用户数按总体查看”，筛选条件选择对应类别“为真”后，将其添加到概览用作精细化运营的观察数据。5. 名称解释和注意事项
5.1. 什么是基准时间？基准时间，英文 "base_time"，有两层含义：
是 “相对时间” 的 “计算基准”
是一个 “历史版本” 的标识
如 “2018-09-12 00:00:00” 可作为一个版本的标识，同时也是这个版本分群的 base_time
举例说明，在 11 月 13 日（今天）上午 10:30 创建一个规则为“最近 7 天支付订单的金额大于等于 1000 元”的例行分群，该分群应以今天的 00:00 为基
准时间，计算 11 月 7 号 00:00 至 11 月 14 号 00:00 日期范围的数据。由于今天并未过完，分群创建时会先以有完备数据的最近一天的凌晨为基准时间计
算一次，所以，首次计算的基准时间为 11 月 12 号 00:00，最近 7 天的数据范围为 11 月 6 号 00:00 至 13 号 00：00（最近 7 天）。第二次计算的基准
时间为 11 月 13 号的 00:00，数据范围为 11 月 7 号 00:00 至 11 月 14 号 00:00。5.2. 什么是计算周期？
计算周期是分群计算的时间间隔，分为单次和例行。
单次：每次手动执行产生最新结果，进行一次数据的计算。例行：分群以每日凌晨为基准时间计算结果（需要等待完备的数据，启动时间会比基准时间晚 1 小时左右。首次创建时，会以最近一次有完备数据的日期为
基准时间计算），目前支持按天为周期计算，后续更新将支持到小时、周、月级别。
5.3. 上传文本的内容和格式
上传的文件是一个文本文件，每行包含一个 distinct_id（这里 distinct_id 的选择，应当与埋点、数据导入时的选择一致。如有疑虑，请咨询神策数据技术支
持）。
user1
asdf2
mike98
aaa,bbb
注意，文件并不是 CSV 格式，例如 "aaa,bbb" 会被当做 “一个”ID 处理，而非两个。
这里的准则是：每行数据（\n分割），都会被当作一个 ID 处理。
5.4. 行为规则条件描述能力的强化
对比 1.12 及之前版本，1.13 版本对行为规则条件描述能力进行了如下强化：
支持规则之间、筛选条件的任意嵌套事件发生次数的匹配规则和数值类型属性的匹配方式补全为：等于、不等于、小于、小于等于、大于、大于等于、区间时间和日期类型属性的匹配方式支持绝对时间、相对当前时间点、相对当前时间区间和相对事件发生时间
支持事件属性的统计值作为分群指标，可选择：总和、均值、最大值、最小值
支持选择虚拟事件
5.5. 创建的个数限制
标准版本的例行用户分群上限 100 个，单次分群上限 200 个。
5.6. 失败和计算中的使用
单次分群若计算失败，在分析页面选择时不可见。例行分群计算失败，在分析页面将使用其最新一次可用的分群计算结果。6. 用户分群权限
角色 创建 删除 编辑 复制 更新重跑 概览查看 分群查看 分析使用 下载 暂停
admin 自己创建
admin 他人创建 -
管理员 自己创建
管理员 他人创建 -
分析师 自己创建 X X X X X X
分析师 他人创建 - X X X X X
普通用户 自己创建 X X X X X X X X X X
普通用户 他人创建 - X X X X X X X X
用户查看分群模块时，无权限的功能入口隐藏或不可点击。对于分析师“编辑”入口一直存在，编辑页面中无修改权限的部分置灰显
示。场景库.场景库 v1.16
神策致力于帮助企业将数据发挥更大的价值，自 1.16 版本，神策分析中新增「场景库」功能，其中包含神策分析师针对具体分析场景，沉淀的场景分析方法
论。每个场景不但介绍了场景的应用价值，还介绍了如何结合这个场景进行深入的分析，同时也提供了完整的配置和数据采集所需的事件设计。
注：只有拥有「管理公共概览权限」的成员，才有权在「场景库」中添加每个「场景概览」到当前项目的「公共概览」中。
1. 如何使用场景库的分析方法
第一步：在每个场景的详情页，点击页面右上角的「下载《事件设计》」可直接将为了进行当前场景分析的埋点方案下载到本地。从而快速让研发同学进行
对应的事件埋点。如果在通过查阅每个场景的「如何配置」后，你发现你已经有相关的埋点事件，不过命名不一样的时候，可直接点击 2 进行当前场景的添
加。
第二步：如果当埋点完成后，点击「添加场景概览」-「下一步」进入设置页。第三步：神策分析会根据场景默认的事件设计中事件、属性的名称进行自动的模糊匹配，并显示为「已埋点」，如未匹配到则显示为「待埋点」。当然，你
依然可以根据实际的埋点情况调整对应的事件与属性。
例如：Push 通知送达事件神策默认的「事件设计」中为「PushReceived」，但是研发埋点时，所用的事件名称为「pushreceived」此时，你可以用已埋的
「pushreceived」 替换显示为「待埋点」的 「PushReceived」
当所有事件、属性均替换为已埋点事件时，保存按钮被激活，可进行下一步，即输入概览名称与分组，完成场景概览的添加。.场景库 v1.17
神策致力于帮助企业将数据发挥更大的价值，自 1.16 版本，神策分析中新增「场景库」功能，其中包含神策分析师针对具体分析场景，沉淀的场景分析方法
论。每个场景不但介绍了场景的应用价值，还介绍了如何结合这个场景进行深入的分析，同时也提供了完整的配置和数据采集所需的采集方案设计文档。
注：只有拥有「管理公共概览权限」的成员，才有权在「场景库」中添加每个「场景概览」到当前项目的「公共概览」中。
如何使用场景库的分析方法
第一步：在每个场景的详情页，点击页面右上角的「下载《事件设计》」可直接将为了进行当前场景分析的埋点方案下载到本地。从而快速让研发同学进行
对应的事件埋点。如果在通过查阅每个场景的「如何配置」后，你发现你已经有相关的埋点事件，不过命名不一样的时候，可直接点击 2 进行当前场景的添
加。
第二步：如果当埋点完成后，点击「添加场景概览」-「下一步」进入设置页。第三步：神策分析会根据场景默认的事件设计中事件、属性的名称进行自动的模糊匹配，并显示为「已埋点」，如未匹配到则显示为「待埋点」。当然，你
依然可以根据实际的埋点情况调整对应的事件与属性。
例如：Push 通知送达事件神策默认的「事件设计」中为「PushReceived」，但是研发埋点时，所用的事件名称为「pushreceived」此时，你可以用已埋的
「pushreceived」 替换显示为「待埋点」的 「PushReceived」
当所有事件、属性均替换为已埋点事件时，保存按钮被激活，可进行下一步，即输入概览名称与分组，完成场景概览的添加。预警管理.预警管理 v1.13
1.9 及其以后版本，提供了监控预警功能，使用神策分析时，可以监控一些重点分析的核心指标，达到设定的阈值后可以发送邮件通知责任人。
1. 新建监控预警
在事件分析页面选择要监控的指标和筛选条件，点击“新建预警”（管理员权限可见）。
进入“新建指标预警”页面。A. 设置预警名称，如：DAU 预警。
B. 在事件分析页面选择的监控指标和筛选条件。
C. 设置分析日志的查询时段单位，按天查看或按小时查看。
D. 设置监控条件：
上一小时，与上一小时的指标值进行对比。
昨日同期，与昨日同一小时的指标值进行对比。
特定值，与特定值进行对比。
E. 设置接收通知的邮件地址。
F. 设置发送预警的邮箱。
G. 启用或关闭监控预警。
H. 点击”保存并应用“按钮即可开始监控。
2. 监控预警管理
在页面右上角点击用户名，弹出下拉菜单，点击“预警管理”（管理员权限可见）。
进入预警管理页面。
A. 点击预警名称可进入预警设置页面。
B. 预警指标的当前值、监控条件中设置的对比方式、相比于对比值的浮动。
C. 最近一次发送预警的时间。
D. 启用或关闭预警。
3. 删除预警进入预警设置页面，点击“删除”按钮即可删除预警。渠道追踪.渠道追踪 v1.13
1. 问题背景
对于互联网产品，每天的新增用户的数量是个非常受关注的指标。同时，围绕着新增用户这个指标，还可以有很多更加深入的分析，例如：
分析不同渠道带来的新增用户的数量，从而优化后续的投放策略；
分析不同渠道带来的新增用户的留存以及转化，从而考察不同渠道带来的用户的质量；
分析每天的销量或者收入，由不同渠道带来的贡献的比例。
接下来，我们详细地介绍如何在 iOS 和 Android 中使用神策分析进行新增用户渠道追踪。
2. 渠道追踪
2.1. 2.1 App 渠道追踪
从 Sensors Analytics 1.5 版本开始，我们正式发布了 App 渠道效果追踪功能，帮助客户了解渠道质量和 App 的实际推广情况。对于 Android 和 iOS 版本，
支持基于 IP、Date、User Agent 构建的模糊匹配；对于 Android，我们也提供 API 允许开发者在 App 中设置渠道信息，同时我们也建议 Android 使用这
种方式（渠道包）。
更详细的文档请参考 App 渠道追踪
2.2. Web 渠道追踪
详细文档请参考 Web 渠道追踪
3. 新增用户与渠道效果分析
在这里，我们对一些常见的新增用户与渠道效果分析，做一些简单的介绍。新增用户及首日首次标记
3.1. 统计每天的新增用户数
统计每天的新增用户数，有如下方案：
1. 可以直接在事件分析中，统计首次访问的触发用户数，如果需要按照渠道进行统计，则可以按照渠道进行分组。需要注意，如果同一个设备卸载后
再安装，有可能会重复计算首次访问。
2. 可以在 1.6 版本后的用户分析功能中，按照首次激活时间分组，来统计相关用户数。这种方式只要用户标识不变，是不会重复统计的，因此相当于
方式 1 会更准确。
3.2. 察看新增用户的转化
想察看某一段时间内的新增用户的转化，可以在核心转化漏斗中，在最开始，增加第一个步骤为首次访问行为，则可以察看新增用户的后续转化了。
3.3. 察看新增用户的留存
想察看某一段时间内的新增用户的留存，可以在留存分析中，把初始行为设置为首次访问，后续行为设置成“任意事件”，或者某个关心的核心行为，则可以
分析新增用户的留存。
3.4. 统计不同渠道带来的用户的销量
想察看不同渠道带来的用户，在一段时间内的销量，可以在事件分析中，统计“支付订单”事件中金额的总数，然后按照用户 Profile 中的首次访问渠道进行分组
即可。.渠道追踪 v1.14
问题背景
对于互联网产品，每天的新增用户的数量是个非常受关注的指标。同时，围绕着新增用户这个指标，还可以有很多更加深入的分析，例如：
分析不同渠道带来的新增用户的数量，从而优化后续的投放策略；
分析不同渠道带来的新增用户的留存以及转化，从而考察不同渠道带来的用户的质量；
分析每天的销量或者收入，由不同渠道带来的贡献的比例。
接下来，我们详细地介绍如何在 iOS 和 Android 中使用神策分析进行新增用户渠道追踪。
渠道追踪
2.1 App 渠道追踪
从 Sensors Analytics 1.5 版本开始，我们正式发布了 App 渠道效果追踪功能，帮助客户了解渠道质量和 App 的实际推广情况。对于 Android 和 iOS 版本，
支持基于 IP、Date、User Agent 构建的模糊匹配；对于 Android，我们也提供 API 允许开发者在 App 中设置渠道信息，同时我们也建议 Android 使用这
种方式（渠道包）。
更详细的文档请参考 App 渠道追踪
Web 渠道追踪
详细文档请参考 Web 渠道追踪
新增用户与渠道效果分析
在这里，我们对一些常见的新增用户与渠道效果分析，做一些简单的介绍。新增用户及首日首次标记
统计每天的新增用户数
统计每天的新增用户数，有如下方案：
1. 可以直接在事件分析中，统计首次访问的触发用户数，如果需要按照渠道进行统计，则可以按照渠道进行分组。需要注意，如果同一个设备卸载后
再安装，有可能会重复计算首次访问。
2. 可以在 1.6 版本后的用户分析功能中，按照首次激活时间分组，来统计相关用户数。这种方式只要用户标识不变，是不会重复统计的，因此相当于
方式 1 会更准确。
察看新增用户的转化
想察看某一段时间内的新增用户的转化，可以在核心转化漏斗中，在最开始，增加第一个步骤为首次访问行为，则可以察看新增用户的后续转化了。
察看新增用户的留存
想察看某一段时间内的新增用户的留存，可以在留存分析中，把初始行为设置为首次访问，后续行为设置成“任意事件”，或者某个关心的核心行为，则可以
分析新增用户的留存。
统计不同渠道带来的用户的销量
想察看不同渠道带来的用户，在一段时间内的销量，可以在事件分析中，统计“支付订单”事件中金额的总数，然后按照用户 Profile 中的首次访问渠道进行分组
即可。App 渠道追踪.App 渠道追踪 v1.13
用 trackInstallation
1. App 通用渠道推广
1.1. 构建渠道追踪链接
1.2. iOS App 调用 trackInstallation:
1.3. 定制 Android 下载商店渠道包（下载渠道）
1.4. 动态添加自定义参数
2. 微信推广
3. App 内推广
3.1.1. 今日头条配置
3.1.2. 广点通配置
3.1.3. 百度信息流的配置
3.1.4. 3.1.4 Apps Flyer 用 csv 导入渠道追踪数据
3.2. iOS App 开启 IDFA 作为 distinct_id
3.3. iOS App 调用 trackInstallation:
3.4. Android App 调用 trackInstallation
4. 短信推广
5. 如何查看渠道追踪
5.1. 获取链接点击次数
5.1.1. 5.2 App 激活用户数
神策分析 1.13 版本使用全新渠道管理功能，若您系统为 1.13 及以上版本，点击查看新版渠道管理功能使用说明
目前，常见的 App 推广主要有下面四种场景：
.App 渠道追踪 v1.13#App 通用渠道推广
.App 渠道追踪 v1.13#微信推广
.App 渠道追踪 v1.13#App 内推广
.App 渠道追踪 v1.13#短信推广
下面以这四种常见的场景为例，分别介绍一下神策具体的方案。
1. App 通用渠道推广
对于 iOS 来说，由于 iOS10 的限制，App 通用渠道推广目前只能是模糊匹配，主要是基于 IP、Date、User Agent 构建的模糊匹配，匹配成功率在75%左
右。而 Android 本身有渠道包的概念，我们建议直接使用渠道包，可以达到精准匹配。如果不使用渠道包， Android 也会跟 iOS 一样进行模糊匹配。
1.1. 构建渠道追踪链接
首先，开发者需要使用神策分析渠道链接生成工具(点击神策分析右上角‘创建渠道链接’进入) ，填入渠道信息及跳转目标，构建渠道追踪链接。在该工具中，开发者请根据页面中的信息，输入相关渠道信息和跳转链接，例如：
神策分析采集数据的 URL - 假设开发者的神策分析采集数据的地址为：http://${service_name}.cloud.sensorsdata.cn/sa?token=${token}，即初始
化 SDK 时的 SERVER_URL
跳转目标 URL - Android 或 iOS 的下载地址，也可以是应用宝的微下载地址，或某个落地页的 URL
广告系列来源 - XX
广告系列媒介 - Banner
广告系列名称 - Keynote App
在工具中填入的“广告系列来源”等渠道信息，在后续的渠道激活事件中会作为事件属性写入，当用户需要在链接中添加更多属性时，可以点击页面中“增加自
定义属性”按钮，并在下方输入属性名称和属性值。如果开发者对我们提供的渠道信息有疑惑，请阅读文章 《如何对付费广告流量进行标记》。那么，如上图，在页面下方会自动生成渠道链接。
根据上面描述的方法，可以分别给 iOS 和 Android 生成渠道链接。开发者可以将该链接提交给渠道商。
提示：
Android 如果使用了渠道包，可以不使用该工具生成 Android 渠道链接，直接给渠道商提供 apk 的下载链接地址即可。如
果客户使用了应用宝的微下载功能，也可以直接使用微下载的地址生成一个渠道链接。
1.2. iOS App 调用 trackInstallation:
在 iOS App 中集成并初始化 SDK 后， 当 App 启动时，调用 trackInstallation: 接口（SDK 内部已添加只有 App 安装后的首次调用有效的逻辑），
传入代表 App 激活的事件名称及相关事件属性，iOS SDK 会发送追踪事件。如果神策分析根据本次追踪事件的 IP 地址、User Agent 生成的设备指纹，成
功匹配服务端的设备信息，则会将设备信息中的渠道信息写入事件属性中；否则，认为匹配渠道信息失败。
//
[[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"];
对于前文中生成的渠道追踪链接，其中渠道信息会被写入事件属性和用户 Profile 中：
广告系列来源 - {{$utm_source}} 属性，String 类型
广告系列媒介 - $utm_medium 属性，String 类型
广告系列字词 - $utm_term 属性，String 类型
广告系列内容 - $utm_content 属性，String 类型
广告系列名称 - $utm_campaign 属性，String 类型
用户调用 trackInstallation: 接口等价于同时调用 track: 发送包含上述属性的事件，并调用 profileSetOnce: 设置用户的上述 Profile。1.3. 定制 Android 下载商店渠道包（下载渠道）
对于 Android 可以给应用商店上传带有标记的渠道包（ apk 包），便于区分每个渠道的下载量。可以使用 DownloadChannel 来记录下载商店的渠道。这
里 DownloadChannel 只是一个示例，如果需要多个字段来标记渠道包，请按业务实际需要添加。
AndroidManifest.xml 中：
初始化 SDK 后，调用 trackInstallation 记录激活事件、渠道追踪：
try {
String downloadChannel = null;
//
downloadChannel = SensorsDataUtils.getApplicationMetaData(this, "YOUR_DOWNLOAD_CHANNEL");
JSONObject properties = new JSONObject();
// DownloadChannel ()
properties.put("DownloadChannel", downloadChannel);
// AppInstall
SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
} catch (Exception e)
{ e.printStackTrace(
);
}
注意： 一定不要在调用 trackInstallation: 接口时传入 $utm_ 相关的属性。如果要追踪推广渠道，需要用 App 渠道链接来追踪（推广的渠道链接一
般由产品运营人员创建），具体请参考 构建渠道追踪链接。
下载渠道：在 apk 代码内的标记，一般用于区分不同的应用商店（例如：应用宝、小米商店）。
推广渠道：渠道链接 URL 中的 utm 信息，一般用于区分不同的推广投放。
1.4. 动态添加自定义参数
特别的，如果需要在生成的渠道追踪链接上动态添加自定义参数，可在链接最后手动拼接自定义参数。神策在进行渠道匹配时，匹配成功后会自动将自定义
参数添加到激活事件中。若没有特殊需求可忽略该设置。
例如：给不同的用户分配不同的渠道链接，用户使用该链接邀请其他用户下载 App，通过链接参数记录不同用户邀请的其他用户量。
https://${service_name}.datasink.sensorsdata.cn/r/A
https://${service_name}.datasink.sensorsdata.cn/r/A?indexid=12345
其中 indexid 为自定义参数，可根据需求自行设置。
2. 微信推广
微信推广，常见的有两种方式：
在朋友圈分享落地页
扫描二维码打开落地页
微信推广，与 App 通用渠道推广一样，iOS 也是属于模糊匹配。
微信推广与 App 通用渠道推广基本一致，唯一的区别就是在微信中无法直接跳转到 App Store 的下载地址页面（目前微信只对应用宝的微下载功能开放了该
功能）。所以在构建渠道追踪链接时，建议填写应用宝的微下载地址，这样 iOS 用户不仅可以直接跳转到 App Store 的下载地址页面，而且中间落地页也无
需自己判断用户手机系统类型跳转不同的下载页面。iOS 和 Android 端的处理方式与 App 通用渠道推广中的 iOS App 调用 trackInstallation、Android
App 调用 trackInstallation 一致。
如果需要二维码，将相应的链接生成二维码即可。
3. App 内推广App 内推广，会稍微复杂一点，因为各个推广平台的做法可能不太一样，下面以在 今日头条 和 广点通 推广为例介绍神策的做法，其他推广平台可参考此文
档 渠道对接。
对于 iOS 由于今日头条和广点通会获取用户的 IDFA 并通过回调通知客户，所以要求 App 必须有获取 IDFA 的权限才能匹配上。 对于 Android 由于要追踪渠
道链接中投放的推广渠道，所以 Manifest 中不能按照神策 `meta-data` 方式定制渠道信息，代码中也不能传入 `$utm_` 开头的渠道字段。Android 端会使
用 IMEI 做渠道信息的匹配，动态申请 `android.permission.READ_PHONE_STATE` 权限后再调用 `trackInstallation` 。
在启动页 Activity 的 onCreate 方法中申请权限：
// READ_PHONE_STATE
if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.
PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
}
} else {
// 6.0 trackInstallation ,
trackInstallation();
}
在 onRequestPermissionsResult 方法中，调用 trackInstallation
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[]
grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
if (requestCode == 100) {
// trackInstallation ,
trackInstallation();
}
}
/**
*
*/
private void trackInstallation()
{ try {
JSONObject properties = new JSONObject();
properties.put("DownloadChannel", "");// DownloadChannel
// AppInstall
// Manifest $utm_
SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
} catch (Exception e)
{ e.printStackTrace(
);
}
}
3.1.1. 今日头条配置
Step1：填写相关追踪信息
在渠道管理后台选择"今日头条渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
进入今日头条后台广告监测页面
按照 iOS 和 Android 分别配置相应的监测地址以及安装包的下载地址
3.1.2. 广点通配置
Step1：获取广点通的 6 个参数，给神策运维同学，让神策运维在后台配置；
参数名 参数的参考值
account_id 8683590
client_id 110787531
client_secret 9IPQ0VP7INuYY6SAuser_action_set_id（ iOS 的） 110781921
user_action_set_id（ Android 的） 1107817601
refresh_token b8b393938dc3a4ddfc0b7e8abb721e92
每个参数值的含义以及获取方法，可参考此文档 https://developers.e.qq.com/docs/apilist/auth/oauth2#a2
Step2： 在广点通后台填写渠道链接
1.打开并登录 http://e.qq.com/ ； 2.左侧点击工具箱； 3.点击 “转化辅助” 打开页面； 4.点击 “创建新转化” 填写信息：设置步骤中，“转化方案” 请选择
“API方案一”，“Feedback URL” 请参考样例：
http(s):///cb/installation_track?project=&channel_name=ngdt_track
神策数据监测地址 为神策数据接收地址中的域名；
project 为项目名，token 为项目对应的数据接收地址中的 TOKEN（若有）；
可指定 utm 参数 utm_source、utm_medium、utm_term、utm_content、utm_campaign；
广点通要求 Feedback URL 的端口需要为 80 端口，神策默认为 8006 或 8106，故需要配置 80 端口转发，具体配置可参考服务转发配置文档
Step3： 联调测试
1.点击 “联调测试” 任意填写一个 ID，例如 AAAA，提示 “联调成功” 则配置完成； 2.在 “转化状态” 栏启用；
3.1.3. 百度信息流的配置
Step1：进入百度信息流账号后台，按照图片的步骤进入最后的页面,将 akey 提供给神策运维同学，由神策运维同学在服务端配置 akey 值Step2：手动拼接渠道监测地址
百度监测地址拼接规则如下
iOShttp(s):///cb/installation_track?utm_source=&project=&channel_name=baidu_track&callback_url={{CALLBACK_URL}}
&click_time={{TS}}&idfa={{IDFA}}&ip={{IP}}&sign={{SIGN}}&ua={{UA}}&hash_key=account_1&utm_campaign={{PLAN_ID}}
&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
Android
http(s):///cb/installation_track?utm_source=&project=&channel_name=baidu_track&callback_url={{CALLBACK_URL}}
&click_time={{TS}}&ip={{IP}}&sign={{SIGN}}&imei={{IMEI_MD5}}&ua={{UA}}&hash_key=account_1&utm_campaign=
{{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
只有“”和“”需要替换，“utm ”对应的参数值都可以自定义修改，比如可以把 utm_source 的值设置为 utm_source=baiduxxl。其他参数名和参
数值均不可修改。 、、和 三个宏参数是可以获取百度信息流的计划 ID ，媒体 ID 等信息。如不需要这些信息，可自定义修改和删除相应的 utm 参
数值。
“” 是指神策数据接收地址的域名
“”是指神策数据接收地址中的项目名
hash_key是用来标记不同百度信息流渠道的参数，具体的参数值由神策运维同学在服务端配置完 akey 值之后提供，此处 account_1 仅
为举例。
如果数据接收地址后面有 token（云版环境数据接收地址默认会带有 token） ，需要在链接的 project 参数后面用 & 拼接符，拼接一个
token 参数。
配置多个百度渠道
1:如果有多个账号，则通过 hash_key 配置不同的 key,且在监测链接中，添加 hash_key 参数区分不同的 key ,hash_key 的参数值由神策
运维同学配置完 akey 值之后提供（老客户使用 utm_term 参考区分不同的链接，比如 utm_term=utm_term1）
2:配置多个 akey
1 http(s):///cb/installation_track?hash_key=account_1&utm_source=&project=
&channel_name=baidu_track&callback_url={{CALLBACK_URL}}&click_time={{TS}}&ip={{IP}}&sign={{SIGN}}&imei=
{{IMEI_MD5}}&ua={{UA}}&utm_campaign={{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
2 http(s):///cb/installation_track?hash_key=account_2&utm_source=&project=
&channel_name=baidu_track&callback_url={{CALLBACK_URL}}&click_time={{TS}}&ip={{IP}}&sign={{SIGN}}&imei=
{{IMEI_MD5}}&ua={{UA}}&utm_campaign={{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
Step3: 进行投放
在百度信息流后台将监测地址填入
联系神策运维 ，在服务端配置 akey 参数，重新生成 nginx 的配置
Step4：联调设置
联调成功后，开始进行广告的投放
3.1.4. 3.1.4 Apps Flyer 用 csv 导入渠道追踪数据
1. 下载 FormatImporter FormatImporter下载方法。 对于渠道追踪的数据导入，既需要导入事件信息，又需要导入用户信息。
2. 由于csv中的列的名称不符合我们的数据导入规范，需要修改csv中列的名称(您可以自己编写脚本辅助修改)。其中必须将 IP 修改为 $ip；对于 Me
dia Source,Adset,Ad 等相应的列可以通过您的理解修改为相应的 $utm_source,$utm_term,$utm_content,$utm_medium, $utm_campaig
, 这些具体的含义参见 神策分析渠道链接生成工具 页面的最下方。
3. 首先导入事件信息，使用命令
python3 format_importer.py csv_event \
--url ''import_url'' \ #
--filename ''csv_file_path'' \ # csv
--project ''project_name'' \ #
--distinct_id_from ''IDFA'' \ # distinct Id IOS IDFAAndroid IMEI
Android Id
--event_default ''$AppChannelMatching'' \ #
--timestamp_from ''Attributed Touch Time'' \
--timestamp_format ''%Y/%m/%d %H:%M'' \ #
--property_list ''$ip,$utm_source,$utm_content,$utm_term'' \ # ''$ip'',
--csv_delimiter '' '' # csv '','',
4. 接着是导入用户信息， 使用命令python3 format_importer.py csv_profile \
--url ''import_url'' \ #
--filename ''csv_file_path'' \ # csv
--project ''project_name'' \ #
--distinct_id_from ''IDFA'' \ # distinct Id IOS IDFAAndroid IMEI
Android Id
--property_list ''$ip,$utm_source,$utm_content,$utm_term'' \ # ''$ip'',
--csv_delimiter '' '' # csv '','',
5. 至此已将 csv 中所有的渠道追踪数据导入完成，可以在埋点管理中查看是否导入成功。
3.2. iOS App 开启 IDFA 作为 distinct_id
具体操作方法请参考 识别用户。
3.3. iOS App 调用 trackInstallation:
SDK 版本需要大于等于 1.6.31，请参考 iOS App 调用 trackInstallation:。
3.4. Android App 调用 trackInstallation
SDK 版本需要大于等于 1.6.33，请参考 Android App 调用 trackInstallation。
4. 短信推广
短信推广，一般是在短信里有一个短链接，当用户在浏览器里打开该链接时，会打开一个落地页，然后再根据手机操作系统类型，分别跳转到不同的下载地
址页面。剩下的就跟 App 通用渠道推广一致了。具体可以参考App 通用渠道推广。
5. 如何查看渠道追踪
5.1. 获取链接点击次数
当用户点击用我们的链接生成工具生成的链接时，会触发 $AppChannelMatching 事件，可通过查询该事件的总次数获取链接的点击次数。
注意： 该事件默认是隐藏的，需要在"元数据"中的“元事件”里勾选“显示所有隐藏事件”，然后将该事件设置为可见。该事件中的 匿名 ID 与 App 中的 匿名ID
是不相同的，主要是用来统计链接的点击次数，而不能基于 匿名 ID 统计具体某个用户的转化。该事件中的 distinct_id 取值方式与真实用户的 distinct_id 是不相同的，由 IP 、操作系统版本拼接而成，主要用于统计链接的点击次数，而不能基于该 ID
统计具体某个用户的转化，且不会被写入用户表。5.1.1. 5.2 App 激活用户数
A. 选择“行为事件分析”功能
B. 选择事件：trackInstallation: 接口对应的事件名
C. 选择指标：触发用户数
D. 添加分组：广告系列来源Web 渠道追踪.Web 渠道追踪 v1.13
神策分析 1.13 版本使用全新渠道管理功能，若您系统为 1.13 及以上版本，点击查看新版渠道管理功能使用说明
网页端，流量来源类型说明
Web 渠道追踪，是通过给网站 URL 后面加上 utm 相关参数，然后网站里加载了 SDK 后，会自动把 utm 相关属性加到 $pageview 这个事件的属性中。
1. 在网站中集成神策分析 JavaScript SDK
参考 神策分析 JavaScript SDK 引入 SDK ，其中的 sensors.quick(''autoTrack'') 的作用就是在每个页面打开后，都发送一个 $pageview 也就是页
面访问事件，同时如果这个用户是首次打开网站，会给这个用户设置用户属性，包含 ， ， 。
$pageview 中包含如下属性
1. 广告系列属性。
2. 前向地址，前向域名属性。也就是 referrer。
3. 页面地址，页面路径，页面 title 用来表示网页。
4. 是否首次访问。
2. 构建渠道追踪链接
网站中已经集成了 SDK 后，可以对你们网站的某个页面，使用神策分析渠道链接生成工具(点击神策分析右上角‘创建渠道链接’进入)来对广告投放链接进行标
记。
下面是某电商网站的一次春节促销活动为例。运营同学在百度投放了 SEM，购买了 年货 这个关键词，投放的链接为 https://www.sensorsdata.cn/index.
html 。如上，运营同学就可以将生成的链接交给渠道商作为最终的投放链接。
通过以上的准备工作，当用户点击打开标记好的链接后，集成的 SDK 便会默认采集 $pageview 页面浏览事件，并且包含 $utm_ 属性。
3. 获取链接点击次数
当用户点击用神策渠道链接管理生成的短链时，会触发 $ShortUrlRedirect 事件（该事件默认隐藏，需在神策分析界面元数据元事件由隐藏更改为可
见），可通过查询该事件的总次数获取短链被点击的次数。
该事件中的 distinct_id 与真实用户的 distinct_id 是不相同的，神策分析 1.13 旧版本及其之前的版本 distinct_id 统一为固定值
“track_short_url_fake_id”，神策分析 1.13 新版本及其之后的版本 distinct_id 为 IP， 主要用于统计链接的点击次数，而不能基于该 ID 统计具体某个用户的
转化，且不会被写入用户表。小程序渠道追踪.微信小程序渠道追踪 v1.13
神策分析 1.13 版本使用全新渠道管理功能，若您系统为 1.13 及以上版本，点击查看新版渠道管理功能使用说明
小程序的打开主要有三种方式： 扫描二维码，转发分享，跳转。
扫描二维码：普通链接二维码，小程序码，小程序二维码。
转发分享： 分为转发到群，转发到个人等。
跳转： app 跳转到小程序，小程序跳转小程序， 公众号跳小程序， 广告跳转等。
1. 扫描二维码
1.1. 扫描普通链接二维码
1.进入微信小程序后台，主体必须是企业非个人，点击设置 -> 开发设置 -> 扫普通链接二维码打开小程序2.
添加二维码规则，(注意最后必须带 / ) 比如把这个目录 https://sensorsdata.cn/weixin/ec1/ 作为小程序 ec1 的地址3.
依据示例设置参数就可以标志来源。示例: https://sensorsdata.cn/weixin/ec1/?utm_source=wang
下面我们拿电商小程序 ec1 来演示，标志来自于王同学的推广
打开渠道生成工具 https://sensorsdata.cn/tools/url_create.html
在上图中，首先根据上面的方式，生成网站地址，例如https://sensorsdata.cn/weixin/ec1/
给''广告系列来源''填入 wang
把生成的二维码，右键复制，就可以拿去推广了
小程序 ec1 加载 0.9 版本以上的小程序 SDK 后，会自动采集 $MPLaunch $MPShow 等事件，这个事件中会有 $utm_source 广告系列来源的属性来查看
是来自王同学。
注意：普通链接二维码地址需要在微信公众平台进行配置，需上传校验文件。相关规则可查看此网址 https://developers.weixin.qq.com/miniprogram
/introduction/qrcode.html1.2. 小程序码
微信公众平台提供两个接口生成小程序码
1.2.1. 小程序码接口 A
1. 登录微信公众平台，通过网址 https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/qr-code/wxacode.get.html 找到获取小程
序码 API
2. 获取 access_token ，使用 A 接口，在 path 中加入 utm 相关参数（如："path":"pages/index/index?utm_source=demo2345"），生成小程序码3.
在小程序冷启动或热启动时，会自动采集 $MPLaunch $MPShow 等事件，小程序 SDK 封装的 appLaunch 和 appShow 会根据 query 来解析 utm 相关参
数。
1.2.2. 小程序码接口 B
注意：不建议使用此接口，因为 scene 值最大只能传 32 个字符
1. 登录微信公众平台，通过网址 https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/qr-code/wxacode.getUnlimited.html 找
到获取小程序码 API
2. 获取 access_token ，使用 B 接口，在 scene 中加入 utm 相关参数（如："scene":"utm_source=bd&utm_content=demo"，建议 scene 值中不要出现
？等特殊符号），设置其他必填参数，生成小程序码
3. 在小程序冷启动或热启动时，会自动采集 $MPLaunch $MPShow 等事件，小程序 SDK 封装的 appLaunch 和 appShow 会根据 query 中的 scene 值来
解析 utm 相关参数。
1.3. 小程序二维码
1. 登录微信公众平台，通过网址 https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/qr-code/wxacode.createQRCode.html
找到获取小程序二维码 API
2. 获取 access_token ，在 path 中加入 utm 相关参数（如："path":"pages/index/index?utm_source=baidu2345"），生成小程序二维码3.
在小程序冷启动或热启动时，会自动采集 $MPLaunch $MPShow 等事件，小程序 SDK 封装的 appLaunch 和 appShow 会根据 query 来解析 utm 相关参
数。
2. 转发分享我们知道小程序的转发分享，通过定义 Page.onShareAppMessage 来实现，其中 path 属性用来指定跳转的路径。 现在有两种方案来修改 path 路径的值达
到追踪渠道的目的
2.1. 自定义 utm 参数
在 path 后面带上 ?utm_source=wang&utm_content=beizi 这样来标志当前这个分享的人是 wang 分享的内容是 beizi ， 我们会在 App.onLaunch App.
onShow 里自动解析出 utm 的信息
2.2. 自动采集分享
1. 上面这种方式是自定义的方案，小程序 1.9 开始如果配置 allow_amend_share_path 为 true 的话，我们会自动给 path 后面增加 distinct_id ，，属
性
2. 我们会在 App.onLaunch App.onShow 里自动解析这些信息为 $share_distinct_id, $share_depth, $share_url_path
2.3. 获取微信群 id
首先在小程序分享时的页面中，需要设置开启 share_id , 参考微信文档 https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability
/share.html
wx.showShareMenu({ with
ShareTicket: true
})
然后在小程序打开时, 调用如下方法来获取群 id ，参考微信文档 https://developers.weixin.qq.com/miniprogram/dev/api/share/wx.getShareInfo.html
if (opt.shareTicket)
{ wx.getShareInfo(
{
shareTicket: opt.shareTicket;
success: function(res){
console.log(res.encryptedData);
}
})
}
如果想要把这个群 id 作为一个公共属性，可以使用代码 sensors.registerApp({latest_share_group_id : group_id});
3. 跳转
3.1. 小程序跳转小程序
自公共库2.4.0起，新发布的小程序可以跳转至任意其他小程序，无需任何关联或绑定，可以通过在 path 后面添加 utm 相关参数传递渠道参数，举例如下：
假定小程序 A 和小程序 B，从 A 跳转至小程序 B。那么在小程序 B 给小程序 A 提供的 path 的结尾可以增加 utm 参数来标明来源，小程序 A 在实现代码
的时候，可以直接使用小程序 B 提供的 path，这样集成了神策 SDK 的小程序 B 就能实现来源的追踪。
wx.navigateToMiniProgram({
appId: '''',
path: ''page/index/index?utm_source=bar''
})
我们会在 App.onLaunch App.onShow 里自动解析出 utm 的信息
现在可以通过，公众号文章中间和底部的广告，朋友圈的广告，小程序里的广告等方式，点击直接跳转到小程序。
对于这些通过微信广告的投放，可以在配置广告中小程序的页面路径时，后面加 utm 参数，类似于 path: ''page/index/index?utm_source=bar''。
我们会自动记录这些 utm 参数
朋友圈广告跳转小程序可以参考此链接进行配置：https://ad.weixin.qq.com/landing-page-guide.html#/387.微信小程序渠道追踪 v1.17
小程序的打开主要有三种方式： 扫描二维码，转发分享，跳转。
投放跳转：app 跳转到小程序，小程序跳转小程序， 公众号跳小程序， 广告跳转等。
扫码：普通链接二维码，小程序码，小程序二维码。
转发分享： 分为转发到群，转发到个人等。
1. 小程序跳转链接的生成
Step1：填写相关追踪信息
在渠道管理后台选择 "小程序渠道追踪"
填入想要推广的网站地址、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制追踪链接或短链，在希望推广的页面或媒介，进行推广投放即可
公众号文章中间和底部的广告，朋友圈的广告，小程序里的广告，投放的链接也可以用上面产生的链接直接进行投放。
朋友圈广告跳转小程序可以参考此链接进行配置：https://ad.weixin.qq.com/landing-page-guide.html#/387
1.1. 如何获取推广地址
在推广小程序时，我们需要在推广地址填写小程序的页面地址路径，以生成对应的推广链接。
第一步、登录微信小程序管理的后台（mp.weixin.qq.com）
第二步、进入生成小程序码工具，点击后进入
第三步、输入需要获取路径的小程序的完整准确名称（不支持模糊搜索），搜到之后，点击下一步。第四步、单击「获取更多页面路径」的按钮第五步、在「① 开启入口」下方的文本框内填写当前操作人员本人的微信号，点击开启，开启成功后，界面会提示「开启入口成功」。第六步、打开微信移动客户端，确保已经登录了刚刚在第五步填写的微信号，打开想要获取对应页面路径的小程序。
第七步、在小程序内进行访问，找到需要推广的页面，点击右上角的「···」按钮，会弹出菜单，菜单内有一个按钮名为「」，单击该按钮，即可获得当前页面
的小程序页面路径。1.2. 小程序跳转小程序
自公共库2.4.0起，新发布的小程序可以跳转至任意其他小程序，无需任何关联或绑定，可以通过在 path 后面添加 utm 相关参数传递渠道参数，举例如下：
假定小程序 A 和小程序 B，从 A 跳转至小程序 B。那么在小程序 B 给小程序 A 提供的 path 的结尾可以增加 utm 参数来标明来源，小程序 A 在实现代码
的时候，可以直接使用小程序 B 提供的 path，这样集成了神策 SDK 的小程序 B 就能实现来源的追踪。
wx.navigateToMiniProgram({
appId: '''',
path: ''page/index/index?utm_source=miniapp_A''
})
我们会在 App.onLaunch App.onShow 里自动解析出 utm 的信息
2. 小程序码的获取
神策分析平台支持生成小程序码，生成小程序码需要填写 Appid 和 Secret，或者直接填写 Access_token 的值，请询问贵方研发索要任意一种值。2.1. 两种小程序码的区别
神策分析目前在生成小程序码的时候，提供两种生成模式，如下：
产生两种模式的原因是微信提供了两种接口，两种接口的介绍如下：
wxacode.get100,000URL 128
https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/qr-code/wxacode.get.html
wxacode.getUnlimitedURL 32
https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/qr-code/wxacode.getUnlimited.html
神策系统在生成小程序码的时候，会将神策的「utm_xxx」系列参数全部做压缩处理，节省 url 参数的长度，但是不会压缩客户 url 中原有的参数，防止出现
因为神策系统响应较慢导致的主流程阻断。所以提供了两种请求接口，如果涉及到 url 的参数长度较长的情况，可以使用超长码。3. 转发分享
我们知道小程序的转发分享，通过定义 Page.onShareAppMessage 来实现，其中 path 属性用来指定跳转的路径。 现在有两种方案来修改 path 路径的值达
到追踪渠道的目的
3.1. 自定义 utm 参数
在 path 后面带上 ?utm_source=wang&utm_content=beizi 这样来标志当前这个分享的人是 wang 分享的内容是 beizi ， 我们会在 App.onLaunch App.
onShow 里自动解析出 utm 的信息
3.2. 自动采集分享
1. 上面这种方式是自定义的方案，小程序 1.9 开始如果配置 allow_amend_share_path 为 true 的话，我们会自动给 path 后面增加 distinct_id ，，属
性
2. 我们会在 App.onLaunch App.onShow 里自动解析这些信息为 $share_distinct_id, $share_depth, $share_url_path
3.3. 获取微信群 id
首先在小程序分享时的页面中，需要设置开启 share_id , 参考微信文档 https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability
/share.html
wx.showShareMenu({ with
ShareTicket: true
})
然后在小程序打开时, 调用如下方法来获取群 id ，参考微信文档 https://developers.weixin.qq.com/miniprogram/dev/api/share/wx.getShareInfo.html
if (opt.shareTicket)
{ wx.getShareInfo(
{
shareTicket: opt.shareTicket;
success: function(res){
console.log(res.encryptedData);
}
})
}
如果想要把这个群 id 作为一个公共属性，可以使用代码 sensors.registerApp({latest_share_group_id : group_id});渠道对接.渠道对接 v1.13
1. 网页通用渠道
Step1：填写相关追踪信息
在渠道管理后台选择“网页通用渠道”
填入想要推广的网站地址、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称
同时会自动生成该推广渠道的推广地址和短链接Step3：进行投放
复制推广地址或短链，在需要推广的页面或媒介上，进行推广投放即可
2. APP 通用渠道
Step1：填写相关追踪信息
在渠道管理后台选择"APP 通用渠道"
填入想要推广的安装包下载地址、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制监测地址或短链，在希望推广的页面或媒介，进行推广投放即可
3. 小程序通用渠道
Step1：填写相关追踪信息
在渠道管理后台选择 "小程序渠道追踪"
填入想要推广的网站地址、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称3.1.1.1. Step3：进行投放
复制追踪链接或短链，在希望推广的页面或媒介，进行推广投放即可
4. 今日头条/抖音
Step1：填写相关追踪信息
在渠道管理后台选择"今日头条渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
进入今日头条后台广告监测页面
按照 iOS 和 Android 分别配置相应的监测地址以及安装包的下载地址
5. 广点通
Step1：获取广点通的 6 个参数，给神策运维同学，让神策运维在后台配置；
参数名 参数的参考值
account_id 8683590
client_id 110787531
client_secret 9IPQ0VP7INuYY6SAuser_action_set_id（ iOS 的） 110781921
user_action_set_id（ Android 的） 1107817601
refresh_token b8b393938dc3a4ddfc0b7e8abb721e92
每个参数值的含义以及获取方法，可参考此文档 https://developers.e.qq.com/docs/apilist/auth/oauth2#a2
Step2： 在广点通后台填写渠道链接
1.打开并登录 http://e.qq.com/ ； 2.左侧点击工具箱； 3.点击 “转化辅助” 打开页面； 4.点击 “创建新转化” 填写信息：设置步骤中，“转化方案” 请选择
“API方案一”，“Feedback URL” 请参考样例：
http(s):///cb/installation_track?project=&channel_name=ngdt_track
为神策数据接收地址中的域名；
project 为项目名，token 为项目对应的数据接收地址中的 TOKEN（若有）；
可指定 utm 参数 utm_source、utm_medium、utm_term、utm_content、utm_campaign；
广点通要求 Feedback URL 的端口需要为 80 端口，神策默认为 8006 或 8106，故需要配置 80 端口转发，具体配置可参考服务转发配置文档
Step3： 联调测试
1.点击 “联调测试” 任意填写一个 ID，例如 AAAA，提示 “联调成功” 则配置完成； 2.在 “转化状态” 栏启用；
6. 百度信息流/百度搜索（ocpc)
Step1：进入百度信息流账号后台，按照图片的步骤进入最后的页面,将 akey 提供给神策运维同学，由神策运维同学在服务端配置 akey 值
Step2：手动拼接渠道监测地址百度监测地址拼接规则如下
iOS
http(s):///cb/installation_track?utm_source=&project=&channel_name=baidu_track&callback_url={{CALLBACK_URL}}
&click_time={{TS}}&idfa={{IDFA}}&ip={{IP}}&sign={{SIGN}}&ua={{UA}}&mac= MAC &hash_key=account_1&utm_campaign=
{{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
Android
http(s):///cb/installation_track?utm_source=&project=&channel_name=baidu_track&callback_url={{CALLBACK_URL}}
&click_time={{TS}}&ip={{IP}}&sign={{SIGN}}&imei={{IMEI_MD5}}&ua={{UA}}
&oaid= OAID_MD5 &mac= MAC &hash_key=account_1&utm_campaign={{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content=
{{UNIT_ID}}
只有“”和“”需要替换，“utm ”对应的参数值都可以自定义修改，比如可以把 utm_source 的值设置为 utm_source=baiduxxl。其他参数名和参
数值均不可修改。 、、和 三个宏参数是可以获取百度信息流的计划 ID ，媒体 ID 等信息。如不需要这些信息，可自定义修改和删除相应的 utm 参
数值。
“” 是指神策数据接收地址的域名
“”是指神策数据接收地址中的项目名
hash_key是用来标记不同百度信息流渠道的参数，具体的参数值由神策运维同学在服务端配置完 akey 值之后提供，此处 account_1 仅
为举例。
如果数据接收地址后面有 token（云版环境数据接收地址默认会带有 token） ，需要在链接的 project 参数后面用 & 拼接符，拼接一个
token 参数。
配置多个百度渠道
1:如果有多个账号，则通过 hash_key 配置不同的 key,且在监测链接中，添加 hash_key 参数区分不同的 key ,hash_key 的参数值由神策
运维同学配置完 akey 值之后提供（老客户使用 utm_term 参考区分不同的链接，比如 utm_term=utm_term1）
2:配置多个 akey
1
http(s):///cb/installation_track?hash_key=account_1&utm_source=&project=&channel_name=baidu_track&callback_url=
{{CALLBACK_URL}}&click_time={{TS}}&ip={{IP}}&sign={{SIGN}}&imei={{IMEI_MD5}}&ua={{UA}}
&oaid= OAID_MD5 &mac= MAC &utm_campaign={{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
2
http(s):///cb/installation_track?hash_key=account_2&utm_source=&project=&channel_name=baidu_track&callback_url=
{{CALLBACK_URL}}&click_time={{TS}}&ip={{IP}}&sign={{SIGN}}&imei={{IMEI_MD5}}&ua={{UA}}
&oaid= OAID_MD5 &mac= MAC &utm_campaign={{PLAN_ID}}&utm_medium={{IDEA_ID}}&utm_content={{UNIT_ID}}
Step3: 进行投放
在百度信息流后台将监测地址填入
联系神策运维 ，在服务端配置 akey 参数，重新生成 nginx 的配置
Step4：联调设置
联调成功后，开始进行广告的投放
7. InMobi
Step1：填写相关追踪信息
在渠道管理后台选择“InMobi 渠道追踪”
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称
Step3：进行投放
复制应用下载地址和监测地址进入 InMobi 的设置后台
在点击接收地址中填入系统生成的监测地址
Step4：联调和设置
联系神策运维配置 InMobi_GPMID 联调成功后，开始创建广告
8. 微博粉丝通
Step1：手动拼接渠道监测地址
Android:
http://channeltrack.sensorsdata.cn/cb/installation_track?server_url=urlencode&project=&imei={imei_MD5}&ip=
{ip}&click_time={clicktime}&utm_source=&callback_key={IMP}&channel_name=weibo_track&hash_key=default
iOS:
http://channeltrack.sensorsdata.cn/cb/installation_track?server_url=urlencode&project=&idfa={idfa_MD5}&ip=
{ip}&click_time={clicktime}&utm_source=&callback_key={IMP}&channel_name=weibo_track&hash_key=default
其中 与 应以实际情况填写。 就是该渠道来源的名称。
hash_key 对应神策后端配置的公司名称，通过它的值来区分不同公司账号。如果只有一个账号，链接最后括号中的东西可不填。
Step2：修改服务配置
配置好渠道监测地址链接后，联系神策运维同事，进行后台的配置，需要提供在微博粉丝通后台的公司名称。
Step3: 进行投放
微博监测界面里进入到配置监测链接的界面
Step4：联调设置
联调成功后，开始投放广告
9. 阿里汇川
Step1：填写相关追踪信息
在渠道管理后台选择"阿里汇川渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
进入阿里汇川后台监测界面
按照 iOS 和 Android 分别配置相应的监测地址
Step4：联调和设置
联调成功后，开始创建广告
10. 壁合
Step1：填写相关追踪信息
在渠道管理后台选择“壁合广告渠道追踪”
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
目前壁合广告渠道追踪只支持 iOS 追踪
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
进入壁合广告界面
配置相应的监测地址
Step4：联调和设置
联调成功后，开始创建广告
11. 陌陌
Step1：填写相关追踪信息
在渠道管理后台选择“陌陌渠道追踪”
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在陌陌界面里进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
Step4：联调和设置
联调成功后，开始创建广告
12. 网易有道
Step1：填写相关追踪信息
在渠道管理后台选择‘网易有道渠道追踪对接’
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在网易有道界面里进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
Step4：联调和设置
联调成功后，开始创建广告
13. 一点资讯
Step1：填写相关追踪信息
在渠道管理后台选择"一点资讯渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在一点资讯界面里进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
Step4：联调和设置
联调成功后，开始创建广告
14. Bilibili
Step1：填写相关追踪信息生成链接（神策版本 1.14 及之后版本）
- 在渠道管理后台选择 "Bilibili"
- 填入想要推广的安装包下载地址、安装包类型、渠道相关信息
- 系统会根据规则自动生成链接的名称手动拼接渠道监测地址（神策版本 1.13 及之前版本）
iOS App
http(s):///cb/installation_track?utm_campaign=&utm_source=&project=
&channel_name=bilibili_track&tp_os= OS &tp_track_id= TRACKID &click_time= TS &idfa= IDFA &ip= IP &ua=_
_UA
Android App
http(s):///cb/installation_track?utm_campaign=&utm_source=&project=
&channel_name=bilibili_track&tp_os= OS &tp_track_id= TRACKID &click_time= TS &ip= IP &imei= IMEI &andr
oid_id= ANDROIDID &ua= UA
- 其中 神策地址 与 项目名 应以实际情况填写。广告系列来源 就是该渠道来源的名称。
Step2: 进行投放
- 在B站界面里进入到配置监测链接的界面
Step3：联调设置
- 联调成功后，进行广告的投放15. Mobvista
Step1：填写相关追踪信息
在渠道管理后台选择" Mobvista 渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在 Mobvista 里进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
Step4：联调和设置
联调成功后，开始创建广告
16. 博瑞赛思
Step1：手动拼接渠道监测地址
iOS:
http(s):///cb/installation_track?project=&idfa={ios_idfa}&utm_term={aff_id}&ip={ip}&callback_url={urlencode(
)}&utm_source=&channel_name=offs_track
其中 与 应以实际情况填写。urlencode()应该讲渠道方提供的回调地址 urlencode 之后进行填写。 就是该渠道来源的名称。
目前博瑞赛思提供的回调地址是 http://tra.nativeadscn.com/advBack.php?click_id={click_id}
注意在urlencode时，click_id前后的两个大括号不要变化。
例如，此次结果为：http%3A%2F%2Ftra.nativeadscn.com%2FadvBack.php%3Fclick_id%3D{click_id}
Step2: 进行投放
在 offerslook 界面里进入到配置监测链接的界面17. Vido
Step1：填写相关追踪信息
在渠道管理后台选择"Vido 渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
目前 Vido 渠道追踪只支持 iOS 追踪
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在 Vido 界面里进入到配置监测链接的界面
配置相应的监测地址
18. 知乎
Step1：填写相关追踪信息
在渠道管理后台选择"知乎渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在知乎后台，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
19. 爱奇艺
Step1：填写相关追踪信息
在渠道管理后台选择"爱奇艺渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在爱奇艺后台，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
20. 讯飞
Step1：填写相关追踪信息
在渠道管理后台选择"讯飞渠道追踪"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在讯飞后台系统，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
21. 360广告推送
Step1：填写相关追踪信息
在渠道管理后台选择"360广告推送"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在360广告推送后台系统，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
22. 波波视频
Step1：填写相关追踪信息
在渠道管理后台选择"波波视频"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在波波视频后台系统，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
23. 快手
Step1：填写相关追踪信息
在渠道管理后台选择"快手"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在快手后台系统，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
24. Adbright
Step1：填写相关追踪信息
在渠道管理后台选择"Adbright"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息
Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在 Adbright 后台系统，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
25. 凤羽
Step1：填写相关追踪信息
在渠道管理后台选择"凤羽"
填入想要推广的安装包下载地址、安装包类型、渠道相关信息Step2：生成链接地址
系统会根据规则自动生成链接的名称Step3：进行投放
复制应用下载地址和监测地址
在凤羽后台系统，进入到配置监测链接的界面
按照 iOS 和 Android 分别配置相应的监测地址
26. 网易云音乐
Step1：生成监测地址
如果是 1.15 版本的神策分析，可在神策分析后台的渠道页面中直接生成网易云音乐的渠道链接
如果是 1.14 及之前的神策分析版本，需按如下规则拼接对应链接
Android:
http://channeltrack.sensorsdata.cn/cb/installation_track?server_url=(urlencode)&project=
&imei= IMEI &ip= IP &click_time= CLICKTIME &utm_source=
&ua= UA &callback_key= CLICKID &adid= ADID &channel_name=ntes_music_track
iOS:
http://channeltrack.sensorsdata.cn/cb/installation_track?server_url=(urlencode)&project=
&idfa= IDFA &ip= IP &click_time= CLICKTIME &utm_source=
&ua= UA &callback_key= CLICKID &adid= ADID &channel_name=ntes_music_track
其中 与 应以实际情况填写。 就是该渠道来源的名称。其他渠道属性可以自定义参数的形式拼接在链接里。
Step2：联系神策运维
让神策运维在后台配置相应的 appkey 与 secretkey 参数（此参数无需客户提供，神策有默认的参数值）
Step2：将渠道监测链接填写到网易云音乐后台
在网易云音乐界面里进入到配置监测链接的界面，填写相应的监测链接渠道链接管理.渠道链接管理 v1.13
注意：此文档适用于神策分析系统 1.13 及以上版本。 快速了解渠道链接管理
1. 渠道管理提供的功能
创建渠道链接
支持单个、批量进行创建渠道追踪、监测 url
保存渠道链接
保存全部创建的 url ，支持通过搜索和筛选，查找出指定的已创建渠道 url
管理渠道链接
提供渠道链接的修改、删除及导出功能，同时提供将短链解析为长链的工具
推广效果分析
支持快速跳转到该推广链接相应的事件分析模型中，观察该渠道链接的访问人数、次数等指标
2. 创建渠道追踪链接
2.1. 进入渠道管理界面
2.2. 选择单个新建或者批量创建2.2.1. 新建链接（单个）
1.选择基础信息
广告类型
神策支持基础的 “网页通用渠道”、“ APP 通用渠道” 和 “小程序通用渠道”，同时也支持丰富的第三方对接渠道
第三方渠道包括：今日头条，百度信息流，InMobi ，广点通，阿里汇川，微博粉丝通，一点资讯，Bilibili ，网易有道，
Mobvista ，Vido ，壁合，陌陌，博瑞赛思，知乎，爱奇艺和讯飞等
推广地址
网页和小程序通用渠道：填写推广网页的落地页地址
APP 通用渠道：提供 APP 的下载中间跳转 url
第三方渠道：提供 APP 的安装包下载地址
2.输入渠道信息
活动名称：广告系列名称（ utm_campaign ），用来标记广告或运营活动的整体的名称
广告来源：广告系列来源（ utm_source ），用来标记网站、邮箱、应用等来源
广告媒介：广告系列媒介（ utm_medium ），用来标记Banner、CPC等广告形式
关键词：广告系列字词（ utm_term ），用来标记广告关键词，主要用于SEM投放
广告内容：广告系列内容（ utm_content ），主要用于A/B测试，标记同一广告间细微差别自定义属性：不能与以上 5 个渠道信息名称重复，且命名需为英文
3.点击生成
- utm_
-
-
2.2.2. 新建链接（批量）1.选择基础信息
广告类型：目前仅支持 “网页通用渠道”、“ APP 通用渠道” 和 “小程序通用渠道” 三个广告类型进行批量创建
创建方式：
批量上传创建：通过 excel 文件，将本地需要生成的链接批量导入系统中线
上批量创建：在线写入需要生成的链接地址，提交后进行追踪链接的构建
2.输入渠道信息
2.1 批量上传创建
通过下载模板进行批量上传 url ，适合需要创建的追踪链接数量较大的情况下载数据模板
在本地填写完成后，将模板上传至服务器；上传成功后，点击 “点击生成” 按钮，进行追踪链接的批量生成生
成成功后，界面上会展示生成的渠道链接结果
下载批量生成的链接结果
2.2 线上批量创建
直接在页面中填写需要创建的 utm 参数，进行追踪链接的创建
-
-
- utm_ “ ”
- “”
3.点击生成系统会根据您填入的各个 utm 值、选择的广告类型以及访问地址（应用地址），为您生成渠道追踪链接以及对应的短链（或下载地址和监
测地址）
若您之前创建过相同的链接，本次创建会覆盖旧的链接（不会影响数据的统计和链接的追踪）
系统会根据规则自动生成链接名称，同时，您也可以后期修改这个名称
若您选择的是 “批量上传创建” ，则会在该页面为您生成 “批量创建结果” 的 excel 文件，您可以点击该文件进行下载
3. 如何进行渠道链接的管理？
3.1. 查看链接
操作链接
点击链接 icon ，会出现该链接的追踪链接、短链、app 下载地址以及监测地址，可以快速进行复制点击链接 操作中的 分析 , 可以快速进入事件分析，查看该链接的具体访问量
点击链接 操作中的 删除 ,可以删除该链接，删除后不会影响链接的数据接收和分析，只是在渠道管理中不再展示该链接
点击链接 选中 ,可以选中该链接，选中后可以进行批量的删除操作
点击链接 修改名称 ,可以进行链接的名称修改
3.2. 查询和排序
默认查询
默认排序为按照更新时间的降序进行排序
为了提高整体的查询速度，系统会默认返回渠道链接中的更新时间最近的10,000条数据
搜索
支持输入中文/英文，根据您的输入关键词进行匹配，匹配范围包括链接名称、 全部 utm_ 值
排序
支持按照创建时间排序 和 按照修改时间排序
筛选 当一个链接被重复创建时，其创建时间和修改时间都会被更新；当一个链接修改了链接名称时，其修改时间会被更新
支持广告类型的筛选
支持所属活动（ 广告系列名称， utm_campaign ）的筛选
3.3. 导出
导出为后端导出，导出符合筛选条件的全部渠道链接
导出的文件格式为 xls
3.4. 活动管理
渠道链接按照所属活动进行归类，方便统一观察活动组的推广效果点击 分析 ，会进入事件分析模型，观察该活动组整体的推广效果
4. 如何接进行链接的推广和渠道的对接？
现在在神策分析平台配置好推广的 url
如果是“网页通用渠道追踪”、 “ App 通用渠道追踪”或者“小程序渠道追踪”，那么您可以将该 url 复制出来，放在指定的页面进行推广。
如果您对接的是第三方的渠道推广商，那么需要您将我们生成的监测地址、下载地址等信息提供给第三方。在第三方平台联调通过后，您就可以在神策后台
观察推广的数据了。
每个第三方的渠道商的接入，在渠道管理中提供了详细的接入方式
点击渠道图标，会进入每个渠道的具体的对接教程5. 数据偏差和部分原理说明
5.1. 如何对接第三方渠道商?
神策提供了丰富的第三方渠道商对接方案，若您有新的渠道商，请联系客户成功同事安排对接
登录第三方渠道商的后台系统，按照系统的要求提供响应的地址或参数，联调成功后即可以在神策进行广告点击的收集了。
5.2. 每个渠道的对接实现原理？
App 渠道追踪
从 Sensors Analytics 1.5 版本开始，我们正式发布了 App 渠道效果追踪功能，帮助客户了解渠道质量和 App 的实际推广情况。
对于 Android 和 iOS 版本，支持基于 IP、Date、User Agent 构建的模糊匹配；对于 Android，我们也提供 API 允许开发者在 App 中设置渠道信
息，同时我们也建议 Android 使用这种方式（渠道包）。
详细的文档请参考 App渠道追踪
Web 渠道追踪
详细的文档请参考 Web渠道追踪
小程序渠道追踪
详细的文档请参考 小程序渠道追踪
5.3. 删除渠道 url 链接，对效果的追踪有什么影响？
删除 url 链接后，不会影响该链接的数据获取和数据分析，仅仅是从界面上进行了隐藏，您可以通过再次创建将该链接重新创建
5.4. 渠道标识每个标识名称的作用是什么？
活动名称：原广告系列名称（ utm_campaign ），用来标记广告或运营活动的整体的名称。
广告来源：广告系列来源（ utm_source ），用来标记网站、邮箱、应用等来源
广告媒介：广告系列媒介（ utm_medium ），用来标记Banner、CPC等广告形式
关键词：广告系列字词（ utm_term ），用来标记广告关键词，主要用于SEM投放
广告内容：广告系列内容（ utm_content ），主要用于A/B测试，标记同一广告间细微差别
自定义属性：不能与以上 5 个渠道信息名称重复，且命名需为英文
例如，您希望在百度推广中推广自己的网站，您的产品是和“教育“这个关键词相关的，目前正值开学季，准备做一些推广宣传，那么 您
可以这样进行设置： 广告类型：选择“百度渠道追踪“ 活动名称：新建“开学季推广“ 广告来源：填入 “baidu“ 广告媒介：填入
“CPC“（CPC 为 每次点击付费广告） 关键词 ：填入 “教育“ 广告内容：填入 “开学季购买课程优惠“ 自定义属性：若以上 5 个渠道
信息无法帮助您区分出广告，那么您可以通过添加自定义属性，来区分广告来源。
5.5. 关于短链接 /t 和 /r 的区别说明
每个目标地址支持生成两种短链地址，分别是 /t 和 /r 类型，其中 /r 会向神策数据发送一个$AppChannelMatching 事件，用来标记链接被访问。
当您只想监控网站的来源流量时，使用简单的 /t 地址即可。.渠道链接管理 v1.15
注意：此文档适用于神策分析系统 1.13 及以上版本。 快速了解渠道链接管理
渠道管理提供的功能
创建渠道链接
支持单个、批量进行创建渠道追踪、监测 url
保存渠道链接
保存全部创建的 url ，支持通过搜索和筛选，查找出指定的已创建渠道 url
管理渠道链接
提供渠道链接的修改、删除及导出功能，同时提供将短链解析为长链的工具
推广效果分析
支持快速跳转到该推广链接相应的事件分析模型中，观察该渠道链接的访问人数、次数等指标
创建渠道追踪链接
进入渠道管理界面
选择单个新建或者批量创建
新建链接（单个）1.选择基础信息
广告类型
神策支持基础的 “网页通用渠道”、“ APP 通用渠道” 和 “小程序通用渠道”，同时也支持丰富的第三方对接渠道
第三方渠道包括：今日头条，百度信息流，InMobi ，广点通，阿里汇川，微博粉丝通，一点资讯，Bilibili ，网易有道，
Mobvista ，Vido ，壁合，陌陌，博瑞赛思，知乎，爱奇艺和讯飞等
推广地址
网页和小程序通用渠道：填写推广网页的落地页地址
APP 通用渠道：提供 APP 的下载中间跳转 url
第三方渠道：提供 APP 的安装包下载地址
2.输入渠道信息
活动名称：广告系列名称（ utm_campaign ），用来标记广告或运营活动的整体的名称
广告来源：广告系列来源（ utm_source ），用来标记网站、邮箱、应用等来源
广告媒介：广告系列媒介（ utm_medium ），用来标记Banner、CPC等广告形式
关键词：广告系列字词（ utm_term ），用来标记广告关键词，主要用于SEM投放
广告内容：广告系列内容（ utm_content ），主要用于A/B测试，标记同一广告间细微差别
自定义属性：不能与以上 5 个渠道信息名称重复，且命名需为英文
3.点击生成- utm_
-
-
新建链接（批量）1.选择基础信息
广告类型：目前仅支持 “网页通用渠道”、“ APP 通用渠道” 和 “小程序通用渠道” 三个广告类型进行批量创建
创建方式：
批量上传创建：通过 excel 文件，将本地需要生成的链接批量导入系统中线
上批量创建：在线写入需要生成的链接地址，提交后进行追踪链接的构建
2.输入渠道信息
2.1 批量上传创建
通过下载模板进行批量上传 url ，适合需要创建的追踪链接数量较大的情况下载数据模板
在本地填写完成后，将模板上传至服务器；上传成功后，点击 “点击生成” 按钮，进行追踪链接的批量生成生
成成功后，界面上会展示生成的渠道链接结果
下载批量生成的链接结果
2.2 线上批量创建
直接在页面中填写需要创建的 utm 参数，进行追踪链接的创建
-
-
- utm_ “ ”
- “”
3.点击生成系统会根据您填入的各个 utm 值、选择的广告类型以及访问地址（应用地址），为您生成渠道追踪链接以及对应的短链（或下载地址和监
测地址）
若您之前创建过相同的链接，本次创建会覆盖旧的链接（不会影响数据的统计和链接的追踪）
系统会根据规则自动生成链接名称，同时，您也可以后期修改这个名称
若您选择的是 “批量上传创建” ，则会在该页面为您生成 “批量创建结果” 的 excel 文件，您可以点击该文件进行下载
如何进行渠道链接的管理？
查看链接
操作链接
点击链接 icon ，会出现该链接的追踪链接、短链、app 下载地址以及监测地址，可以快速进行复制点击链接 操作中的 分析 , 可以快速进入事件分析，查看该链接的具体访问量
点击链接 操作中的 删除 ,可以删除该链接，删除后不会影响链接的数据接收和分析，只是在渠道管理中不再展示该链接
点击链接 选中 ,可以选中该链接，选中后可以进行批量的删除操作
点击链接 修改名称 ,可以进行链接的名称修改
查询和排序
默认查询
默认排序为按照更新时间的降序进行排序
为了提高整体的查询速度，系统会默认返回渠道链接中的更新时间最近的10,000条数据
搜索
支持输入中文/英文，根据您的输入关键词进行匹配，匹配范围包括链接名称、 全部 utm_ 值
排序
支持按照创建时间排序 和 按照修改时间排序
当一个链接被重复创建时，其创建时间和修改时间都会被更新；当一个链接修改了链接名称时，其修改时间会被更新
筛选
支持广告类型的筛选
支持所属活动（ 广告系列名称， utm_campaign ）的筛选
导出
导出为后端导出，导出符合筛选条件的全部渠道链接
导出的文件格式为 xls
活动管理
渠道链接按照所属活动进行归类，方便统一观察活动组的推广效果点击 分析 ，会进入事件分析模型，观察该活动组整体的推广效果
如何接进行链接的推广和渠道的对接？
现在在神策分析平台配置好推广的 url
如果是“网页通用渠道追踪”、 “ App 通用渠道追踪”或者“小程序渠道追踪”，那么您可以将该 url 复制出来，放在指定的页面进行推广。
如果您对接的是第三方的渠道推广商，那么需要您将我们生成的监测地址、下载地址等信息提供给第三方。在第三方平台联调通过后，您就可以在神策后台
观察推广的数据了。
每个第三方的渠道商的接入，在渠道管理中提供了详细的接入方式
点击渠道图标，会进入每个渠道的具体的对接教程数据偏差和部分原理说明
如何对接第三方渠道商?
神策提供了丰富的第三方渠道商对接方案，若您有新的渠道商，请联系客户成功同事安排对接
登录第三方渠道商的后台系统，按照系统的要求提供响应的地址或参数，联调成功后即可以在神策进行广告点击的收集了。
每个渠道的对接实现原理？
App 渠道追踪
从 Sensors Analytics 1.5 版本开始，我们正式发布了 App 渠道效果追踪功能，帮助客户了解渠道质量和 App 的实际推广情况。
对于 Android 和 iOS 版本，支持基于 IP、Date、User Agent 构建的模糊匹配；对于 Android，我们也提供 API 允许开发者在 App 中设置渠道信
息，同时我们也建议 Android 使用这种方式（渠道包）。
详细的文档请参考 App渠道追踪
Web 渠道追踪
详细的文档请参考 Web渠道追踪
小程序渠道追踪
详细的文档请参考 小程序渠道追踪
删除渠道 url 链接，对效果的追踪有什么影响？
删除 url 链接后，不会影响该链接的数据获取和数据分析，仅仅是从界面上进行了隐藏，您可以通过再次创建将该链接重新创建
渠道标识每个标识名称的作用是什么？
活动名称：原广告系列名称（ utm_campaign ），用来标记广告或运营活动的整体的名称。
广告来源：广告系列来源（ utm_source ），用来标记网站、邮箱、应用等来源
广告媒介：广告系列媒介（ utm_medium ），用来标记Banner、CPC等广告形式
关键词：广告系列字词（ utm_term ），用来标记广告关键词，主要用于SEM投放
广告内容：广告系列内容（ utm_content ），主要用于A/B测试，标记同一广告间细微差别
自定义属性：不能与以上 5 个渠道信息名称重复，且命名需为英文
例如，您希望在百度推广中推广自己的网站，您的产品是和“教育“这个关键词相关的，目前正值开学季，准备做一些推广宣传，那么 您
可以这样进行设置： 广告类型：选择“百度渠道追踪“ 活动名称：新建“开学季推广“ 广告来源：填入 “baidu“ 广告媒介：填入
“CPC“（CPC 为 每次点击付费广告） 关键词 ：填入 “教育“ 广告内容：填入 “开学季购买课程优惠“ 自定义属性：若以上 5 个渠道
信息无法帮助您区分出广告，那么您可以通过添加自定义属性，来区分广告来源。
关于短链接 /t 和 /r 的区别说明
每个目标地址支持生成两种短链地址，分别是 /t 和 /r 类型，其中 /r 会向神策数据发送一个$AppChannelMatching 事件，用来标记链接被访问。
当您只想监控网站的来源流量时，使用简单的 /t 地址即可。元数据管理.元数据管理 v1.13
统一管理 Sensors Analytics 所追踪数据元信息的地方。比如，修改事件的显示名、修改事件属性的显示名、修改事件属性的单位、修改用户属性的显示名
等。
注意：属性的名称是全局唯一的，且类型是一致的。
如果有两个事件，比如注册和登录中，都有属性 username 的话，必须保证这个 username 的类型是一致的。
1. 元事件
1.1. 编辑元事件
点击 A 进入元数据管理界面
1. 点击 B 进入相应事件，如couponOperation的对应管理页面，可以看到属于此事件的属性。属性是全局唯一的，与事件并没有隶属关系。在这个地方显示的是与事件有关联关系的属性，并且可以修改其中自定义属性的信息，禁止修改预置属性的信
息。对自定义属性的任何修改，都是全局有效的，即在所有事件中都有效。
1. 在 A 处修改事件的显示名称。
2. 在 B 处选择事件属于哪个标签。
3. 在 C 处选择事件的显示状态，可见或隐藏。隐藏事件并不会删除该事件的实际数据，是可逆的。而被隐藏的事件，在任意事件中并不会被包含。
4. 在 D 处增加事件的备注。
5. 在 E 处修改属性的显示名称。
6. 在 F 处修改属性的单位，只有数值类型的属性可以添加单位，单位会在数据概览、事件分析等地方展示。
7. 在 G 处选择属性是否隐藏。
1.2. 查找元事件1. 在 A 和 B 处可对事件名和显示名进行升序和降序排列。
2. 在 C 处可以筛选全部事件、显示的事件或隐藏的事件。
3. 在 D 处点击按钮，可以筛选出只属于此标签的事件，可多选。
4. 在 E 可以直接搜索事件名称或显示名查找事件。
1.3. 批量操作
批量勾选事件后（也可单选），可对事件批量操作。
1. 在 A 处可对事件添加标签，多选。
2. 在 B 处点击按钮，所选事件设为隐藏。
3. 在 C 处点击按钮，所选事件设为可见。1.4. 管理事件标签
鼠标 hover 标签栏时，会出现“编辑”按钮 A，点击进入标签编辑状态，可以修改标签名称、颜色和删除标签。 点击 B 处，可新建标签。
2. 虚拟事件
虚拟事件由多个元事件组合而来，且可以为虚拟事件的每个元事件设置过滤条件，当然也可以为单个元事件设置过滤条件后形成虚拟事件。删除虚拟事件，
不会删除相关数据。
点击 A 创建虚拟事件，点击 B 处编辑对应的虚拟事件。新建和编辑虚拟事件界面功能基本一致，此处以新建为例介绍，详细见下图。1. 在 A 处填写虚拟事件的基本信息（事件名和事件显示名）。
2. 点击 B 处“添加事件”可以增加元事件。
3. 点击 C 处“触发限制条件”可以为对应元事件设置过滤条件。
3. 用户属性
1. 点击 A 处编辑按钮，可编辑自定义属性的显示名。
2. 在 B 处可选择属性显示状态，可见或隐藏。
4. 事件属性这里不展示属性所属的事件，直接展示所有属性，可以全局搜索您需要管理的属性。
1. 点击 A 处编辑按钮，可编辑自定义属性的显示名。
2. 点击 B 处编辑按钮，可编辑属性单位。
3. 点击 C 处上传按钮，可上传维度字典。
4. 在 D 处可选择属性显示状态，可见或隐藏。
5. Session 管理
第一次进行 Session 分析之前需要在这里创建 Session。
1. 点击 A 处“创建 Session”按钮可以创建一个 Session。2. 点击 B 处编辑已经存在的 Session。
创建 Session
1. 在 A 处输入 Session 的名字，必须是合法的变量名。
2. 在 B 处输入显示名。
3. 在 C 处可以选择多个事件，在这里选择事件参与此 Session 分析。
4. 在 D 处输入 Session 的切割时间。.元数据管理 v1.17
统一管理 Sensors Analytics 所追踪数据元信息的地方。比如，修改事件的显示名、修改事件属性的显示名、修改事件属性的单位、修改用户属性的显示名
等。
为了确保用户的灵活使用及满足不同的数据采集的诉求，神策提供了「自由数据上报模式」和「数据强校验模式」。通过「数据强校验模式」可以有效的提
升数据的准确性，从根源解决错误数据上报入库的问题。开启此模式后，将需要采集的事件与属性更新到项目中后，后续所有上报入库的数据均需要比对已
配置的事件与属性类型进行校验。符合要求的数据方可入库，不符合要求的数据将无法入库。
使用「自由数据上报模式」则可以让企业快速完成数据采集的工作，但是数据质量需要完全依赖研发者的埋点代码的准确性。在此模式下，可以随时上报任
何事件与属性。后续持续上报的属性相关数据，将以首次入库的属性类型和属性名进行对比校验。如未匹配到库里已有的信息，那么将视为一个全新的「事
件」、「事件属性」、「用户属性」入库到当前项目中。
注意：属性的名称是全局唯一的，且类型是一致的。如果有两个事件，比如注册和登录中，都有属性 username 的话，必须保证这个 username 的类型是一
致的。入库校验规则设置.入库校验规则设置 v1.17
在此板块中，我们对事件、事件属性、用户属性的入库规则提供了明细说明。为了减少用户在数据上报错误后的修正成本，对于部分类型的属性，神策系统
在入库时，如果发现与要求的属性类型不一致的时候，会采取自动转换的功能。
点击查看自动转换对照关系 >
为了确保有效用户数据的上报，你可以在此模块对「设备 ID」和「登录 ID」用户信息格式规则进行自定义。无论你的项目是否开启了「数据强校验模式」均
可使用此功能。
注：强烈建议修改时，务必联系神策同学协助确认规则，从而确保规则的准确性，避免数据无法入库。
用户信息格式规则需要以正则表达式的方式进行设置，神策为用户提供了各端「设备 ID」正则表达式的常用规则。在设置的时候可以直接勾选使用，如果存
在此规则无法覆盖的情况，请自定义调整。如果某些端不需要采集，那么依然可以选择为「不设置」。
对于「登录 ID」因各家产品的 ID 规则不同，此处需要你自己使用正则表达式来定义「格式规则」，可参考此文档进行正则表达式的编写，确定规则后，请联
系神策同学协助你确认正则表达式的正确性。如当前项目中存在多个产品，其「登录 ID」格式规则各不相同，请务必在正则表达式中以「或」的关系写入，
如果只描述了一个组规则，有可能造成其他产品的用户数据无法正常入库。
用户 ID 规则描述 >元事件.元事件 v1.17
1. 概述
为了帮助大家更好地对元事件进行有效的管理，在 1.17 版本中我们增加了更多的辅助功能。
可直接通过搜索「事件名」和「显示名」关键字，或筛选「显示状态」、「标签」、「应埋点平台」快速找到你需要的事件。
支持对「显示」、「隐藏」、「添加标签」、「修改标签」的批量操作。
对于「已入库」的不再需要接收数据的事件，神策提供了对整个事件的「停止入库」功能。点击停止入库后，后续产生的数据均不再入库
（Extractor 不导入，Nginx 正常接收）；如业务需求发生变化，又需要继续获取此事件的现今上报数据，点击「允许接收」即可，操作后的上报数
据将正常入库，历史未入库的数据不会被恢复。
管理元事件的时候，点击 icon 后可直接在事件分析中查看此事件近期数据上报的情况。
提供一键下载当前项目中已有的「数据埋点采集方案文档」，文档中将包括此项目中所有的事件、事件属性与用户属性。
可通过上传 Excel 文件，对项目中的事件进行显示名的重命名。
在「数据强校验模式」下，有数据上报的事件才可在分析模型和权限中使用，且不可被删除。对于无数据上报的事件，可直接进行删除操作。
事件的管理功能 数据强校验模式 自由数据上报模式
创建事件 手动创建 Y N
上传 Excel 批量创建 Y N
编辑事件 显示名（必填） Y Y
事件名（必填） Y 有数据上报的事件，不可修改其事件名称。 N
应埋点平台 Y Y
标签 Y Y触发时机（必填） Y Y
备注 Y Y
事件属性 Y 有数据上报的属性，不可删除。 N
公共事件属性 Y 有数据上报的属性，不可删除。 N
预置事件属性 Y 有数据上报的属性，不可删除。 N
虚拟属性 不可以编辑 不可以编辑
需前往对应虚拟属性详情进行编辑 需前往对应虚拟属性详情进行编辑
删除事件 - Y 对于没有数据上报的事件可以进行删除 N
设置显示状态 - Y 没有数据上报的事件，默认隐藏，不可设置为可见 Y 没有数据上报的事件，默认隐藏，不可设置为可见
设置是否接受 - Y 没有数据上报的事件，无法设置 Y 没有数据上报的事件，无法设置
批量重命名 - Y Y
下载当前项目的 - Y Y
数据埋点采集方案文档
2. 创建事件（仅在「数据强校验模式」下可使用此功能）
2.1. 手动线上创建一个事件
填写事件基本信息后，将此事件需要上报的属性选择添加到此事件中，或直接新建所需的属性。对于公共事件属性，可选择性的使用部分内容或使用全部内
容，系统默认显示当前项目中所有的公共事件属性。
对于预置事件属性，可提前选择所需的内容，因为预置事件属性是在 SDK 中完成采集的，所以如果后续有当前未选择的预置属性，进行了上报，那么系统将
自动补充到此事件中。信息 说明
事件显示名 事件在使用过程中的显示名称
事件名称 仅可命名为英文，是事件在系统内的唯一标示，不能以数值、符号开头。
注：校验时，事件名称大小写敏感。
应埋点平台 表明此事件需要埋点上报的端，可多选。
iOS、Android、JS、后台、其他
标签 非必填项，可自定义。
设置后可通过标签进行事件使用的动态授权，便于管理和筛选。
触发时机 描述什么时候触发这个事件的数据上报。便于研发理解，确保上报数据的时机是正确的。
例如：是在点击按钮的时候上报，还是已进入页面后即上报。
备注 帮助业务同学更好理解的信息
事件属性 在这个事件中需要采集的具体信息。
可选择项目中已有的，也可直接添加新的属性。
对于从项目中选择的属性，仅可修改其「显示名」
对于新建的暂无数据上报的属性，可修改其类型、属性名和显示名。
公共事件属性 公共事件属性是通过配置后进行统一上报的，无需在每个事件的埋点中进行。
在此可选择当前事件需要的公共事件属性。预置事件属性 预置事件属性，是神策提前在 SDK 中预置好的。
如果需要请在埋点设置的时候进行配置。
可手动从神策的预置事件属性中选择你需要的。
2.2. 批量创建
需要使用神策的「数据埋点采集方案文档」将要采集的事件、事件属性、用户属性按照模板要求整理好，然后进行上传。如果你没有当前最新版本的模板，
可点击「下载数据埋点采集方案文件」进行下载。
模板中包括明细的使用说明，如遇到疑问，可随时联系神策同学进行咨询。
当你的「数据埋点采集方案文档」准备好后，就可以点击「批量上传」上传你的文件进行事件的批量创建。
上传成功后，请点击「开始校验」。系统将自动与目前项目中已存在的事件设计、事件属性、用户属性进行比对校验，如出现对应错误和相似事件或属性将
直接在此页面显示，并提供一键下载校验文件。
如果上传文件的校验全部通过，则自动完成创建，如果校验发现异常问题，系统会将错误内容生成「校验文档」，请下载并修正，随后再次上传。为避免相
似事件和属性的重复创建，神策也基于事件和属性的命名进行相似性识别提醒，可直接点击数值部分可直接查看具体的相似内容。
随后点击「提交更新」，可基于需求决定选择是否使用「文件中的显示名」更新项目中已有属性的显示名信息。最后点击「立即提交」将完成后续通过修正
的事件、事件属性、用户属性。
2.3. 事件详情
点击具体的事件可查看到，此事件的基本信息，以及所有关联属性的数据上报状态和显示状态。点击对应的属性，可直接查看其详情信息。2.4. 常见问题
Q1：如果不需要目前不需要的事件显示在日常分析的选项中需要如何操作？
批量选中不需要使用的事件，设置为「隐藏」即可。隐藏后不影响数据的正常入库。如果此事件被应用在已有概览中时，隐藏后概览中对对应的分析将不可
用。为了确保虚拟事件的正常使用，对于被正在应用在「虚拟事件」中的事件将不允许被隐藏。
Q2：事件已经创建好，为什么在分析模型（例如：事件分析）的选择事件中找不到？
首先，请确认此事件是否有数据上报，没有数据上报的事件无法在分析中查看到。如有数据，请检查此事件是否被隐藏，如果被隐藏，请设置为显示状态。
如此事件的显示状态为显示，但依旧无法在事件分析中使用，那么请在「事件分析」的选择事件的下拉菜单的「事件分组」中，查看是否此事件在分组中被
设置为可见。
Q3：如何开启「数据强校验」模式？
联系你的客户成功经理进行确认，在升级或新部署安装后，由神策运维同学通过后台命令打开此模式。
Q4：谁可以进行将需要采集的事件与属性更新到项目中？
具有「元数据管理权限」的成员，可前往「元数据」的「元事件」、「事件属性」和「用户属性」中分别创建好需要采集的信息。事件属性.事件属性 v1.17
1. 概述
在事件属性的管理上，我们提供了更多线上管理的功能。
线上创建事件属性的功能，并支持通过上传文件批量修改事件属性的显示名。
支持直接搜索「属性名」和「显示名」关键字，或筛选「显示状态」、「数据类型」、「上报数据的状态」和「仅查看公共属性」快速找到你需要
的事件。
支持对选中属性的「显示」和「隐藏」进行批量操作。
在「数据强校验模式」下，有数据上报的事件属性才可在分析模型和权限中使用，且不可被删除。对于无数据上报的事件属性，可直接删除。
事件属性的管理功能 数据强校验模式 自由数据上报模式
创建事件属性 手动创建 Y N
上传 Excel 批量创建 Y N
编辑事件属性 属性显示名 Y Y
属性名 Y 可修改没有数据上报的事件属性名 N
设置为公共属性 Y Y
将应用到…事件 N 仅新建的时候可使用 N
数据类型 Y N
应埋点平台 Y Y设置时机 Y Y
单位 / 格式 Y Y
字典 Y 有数据上报的属性，可进行字典的配置 Y 有数据上报的属性，可进行字典的配置
属性值示例或说明 Y Y
删除事件属性 - Y 对于没有数据上报的事件属性可以进行删除 N
设置显示状态 - Y 没有数据上报的事件属性，默认隐藏，不可设置为可见 Y
批量重命名 - Y Y
2. 新建事件属性
除了在元事件中创建新的事件属性外，当发现某些属性是需要单独添加到多个已有事件中进行埋点上报的时候，也可通过手动在线上创建一个事件属性来完
成。
点击「创建」打开新建页面，选择需要关联的事件后，完成此事件属性的基本信息补充后方可创建成功。
如果此属性被设置为一个「公共属性」那么将默认关联到所有的事件中，包括未来新创建的事件也将自动包括此属性。信息 说明
属性显示名 属性在使用过程中的显示名称，100 字符以内。
属性名 仅可命名为英文，是事件在系统内的唯一标示。
不能以数值、$ 符号开头，100 字符以内。
注：校验时，属性名大小写不敏感。
设置为公共属性 公共事件属性是通过配置后进行统一上报的，无需在每个事件的埋点中进行。
将应用到…事件 如果当前属性不是公共属性，那么需要选择此属性关联的事件有哪些。
如果是公共属性，那么不需要进行关联设置，系统会默认为后续新建的所有事件都关联此属性。
数据类型 必填单选
NUMBER、BOOL、STRING、DATETIME、LIST
应埋点平台 设置此属性为公共属性后，需填写此信息。用来表明此属性需要配置的端，可多选。
iOS、Android、JS、后台、其他
设置时机 设置此属性为公共属性后，需填写此信息。用来描述什么时候需要设置，便于研发理解。
单位 / 格式 统计值的单位，设置后会在分析详情和概览中显示。
字典 当此属性有数据上报后，可在事件属性列表中上传、管理对应的维度字典。
属性值示例或说明 非必填，便于验证埋点时的研发自测对照。
3. 事件属性详情
点击具体的事件属性，也可查看到，此属性目前关联的事件明细列表及其显示状态。关联的事件信息将有助于在对此属性重命名时，定义一个最符合业务场
景的显示名。
需要注意的是，在编辑事件属性的时候仅可编辑事件属性的基本信息。用户属性.用户属性 v1.17
1. 概述
在用户属性的管理上，我们同样提供了全面的管理的功能。
线上创建用户属性的功能，并支持通过上传文件批量修改事件属性的显示名。
支持直接搜索「属性名」和「显示名」关键字，或筛选「显示状态」、「数据类型」和「上报数据的状态」快速找到你需要的用户属性。
支持对选中属性的「显示」和「隐藏」进行批量操作。
在「数据强校验模式」下，有数据上报的用户属性才可在分析模型和权限中使用，且不可被删除。对于无数据上报的用户属性，可直接删除。
用户属性的管理功能 数据强校验模式 自由数据上报模式
创建用户属性 手动创建 Y N
上传 Excel 批量创建 Y N
编辑用户属性 属性显示名 Y Y
属性名 Y N
可修改没有数据上报的用户属性名
数据类型 Y N
应埋点平台 Y Y
设置时机 Y Y
单位 / 格式 Y Y
字典 有数据上报的属性，可进行字典的配置 有数据上报的属性，可进行字典的配置
属性值示例或说明 Y Y
删除用户属性 - Y 对于没有数据上报的用户可以进行删除 N
设置显示状态 - Y 没有数据上报的用户属性，默认隐藏，不可设置为可见 Y
批量重命名 - Y Y
2. 新建用户属性
除了在元事件中通过上传 Excel 文件创建新的用户属性外，如需要单独添一个新的用户属性时，可通过手动在线完成创建。点击「创建」打开新建页面，填
写相关信息后方可创建成功。随后埋点采集的用户属性将比对此设置信息进行校验。信息 说明
属性显示名 属性在使用过程中的显示名称，100 字符以内。
属性名 仅可命名为英文，是事件在系统内的唯一标示。
不能以数值、$ 符号开头，100 字符以内。
注：校验时，属性名大小写不敏感。
数据类型 必填单选
NUMBER、BOOL、STRING、DATETIME、LIST
应埋点平台 设置此属性为公共属性后，需填写此信息。用来表明此属性需要配置的端，可多选。
iOS、Android、JS、后台、其他
设置时机 设置此属性为公共属性后，需填写此信息。用来描述什么时候需要设置，便于研发理解。
单位 / 格式 统计值的单位，设置后会在分析详情和概览中显示。
字典 当此属性有数据上报后，可在事件属性列表中上传、管理对应的维度字典。
属性值示例或说明 非必填，便于验证埋点时的研发自测对照。
3. 用户属性详情
点击具体的用户属性，也可查看到，此属性埋点上报的具体信息明细。维度表.维度表 v1.17
1. 概述
除了基于已经埋点的属性来直接创建虚拟属性之外，我们还可以结合第三方维度表来创建更复杂的虚拟属性应用。
假设我们在神策分析中有一个 pay_order 事件，同时该事件有 product_id、product_name 等属性。现在我们希望在分析的时候使用 product 的更多其它维
度来进行分析（例如 product_manufacturer），但是这些维度并没有在埋点的时候打入神策系统中，这个时候就可以引入维度表来满足这个需求。
目前你可在「元数据」-「维度表」中查看你已经在后台自定义的维度表和 items 表中已有的属性信息。如需使用 items 表的属性创建的虚拟属性，那么需
要先在后台建立 items 和 events 表的关联。
2. 使用 items 表作为维度表
如果希望启用 items 表，首先需要通过 SDK 提供的 itemSet 接口进行 Item 信息的上报。以 Java SDK 为例：
Map
properties = new LinkedHashMap<>();
properties.put("product_name", "iPhone 8");
properties.put("product_manufacturer", "Apple");
properties.put("price", 998.88);
// item_typeitem_id
sensorsAnalytics.itemSet("product", "T12345", properties);
注意：item_type 可以用于区分不同的 item 类型，比如 movie、muisic 等，item_id 区分同一个 item 类型下面的不同的 Item。
然后，我们就可以在自定义查询功能中使用这个表：
SELECT * FROM items LIMIT 10
接下来我们建立 items 和 events 表的关联：
spadmin external_view external_dimension_table add \
-p default \
-t items \
-e "events.product_id = items.item_id AND items.item_type = ''product''"
注意：这里是使用 product_id 字段进行关联，同时限定了 item_type。如果同时存在多种 item_type，那么需要建立多次不同的关联，具体请参
考 2.3 中的例子。
最后，使用 items 表中的 product_manufacturer 来创建虚拟属性即可：
spadmin external_view external_property add \
-p default \
-n product_manufacturer \
-c '''' \
-e items.product_manufacturer \
-t STRING
至此，我们已经可以在神策系统的所有分析功能中使用 pay_order 进行分析的时候，看到 product_manufacturer 属性，并使用这个属性进行任意的分析工
作。
如果需要对维度表和虚拟属性进行删除、更新等管理操作，可以直接执行不带参数的命令查看相关的帮助：
spadmin external_view external_property
3. 自定义维度表除了引用 items 表之外，我们也可以手动创建维度表。在这个例子中，我们使用一张 product_info 的维度表来作为例子。首先我们需要在 impala 中创建这样
一张表：
注意：这里的维度表必须使用 Kudu 或者 HDFS 的 Parquet 文件格式来存储，否则无法支持全部特性。
CREATE DATABASE dimensions;
CREATE TABLE dimensions.product_info
( product_id STRING NOT NULL,
product_manufacturer STRING NULL,
PRIMARY KEY (product_id)
)
PARTITION BY HASH (product_id) PARTITIONS 3
STORED AS KUDU TBLPROPERTIES (''kudu.master_addresses''=''${kudu_master_host}:7051'');
可以通过此命令获取 kudu master 的地址。
# master_address value
spadmin config get client -m kudu
然后，我们需要准备好这张维度表的数据，通常应该是从其它业务数据库或者数据仓库中导入进来。具体可以使用 impala-shell 导入 SQL 文件，或者
JDBC 等多种方式来进行，例如我们可以直接插入几条数据：
INSERT INTO dimensions.product_info VALUES (''124'', ''Xiaomi''), (''123'', ''Apple'');
如果需要插入的数据量比较大，建议使用批量文件导入的方式。首先需要创建一个文本格式的表，并指定分隔符:
CREATE TABLE dimensions.raw_csv_product_info
( product_id STRING,
product_manufacturer STRING
) ROW FORMAT DELIMITED FIELDS TERMINATED by '','' LOCATION ''/tmp/raw_csv_product_info/'';
然后上传已经准备好的逗号分隔的文本数据文件：
hdfs dfs -put data.csv /tmp/raw_csv_product_info/
刷新 CSV 表，并执行 INSERT 把数据导入 Kudu 即可。
REFRESH dimensions.raw_csv_product_info;
INSERT INTO dimensions.product_info SELECT * FROM dimensions.raw_csv_product_info;
在准备好维度表数据之后，我们用 sa_view_tools 工具来把该维度表加入神策系统中：
spadmin external_view external_dimension_table add \
-p default \
-t dimensions.product_info \
-e ''events.product_id = dimensions.product_info.product_id''
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称， -e 参数表示该维度表和事件表（events）的关联关系，即 SQL 中进行 JOIN 的条件。
在定义了维度表之后，我们就可以把该维度表（即 product_info）中的具体字段作为一个虚拟属性加入神策系统中：spadmin external_view external_property add \
-p default \
-n product_manufacturer \
-c '''' \
-e dimensions.product_info.product_manufacturer \
-t STRING
至此，我们已经可以在神策系统的所有分析功能中使用 pay_order 进行分析的时候，看到 product_manufacturer 属性，并使用这个属性进行任意的分析工
作。
4. 一张维度表使用不同的关联条件
如果同一张维度表需要使用不同的关联条件，那么需要在新增维度表的时候使用别名。具体的方式为在原有的表面后面加上 #1 或者其它标识符。例如：
spadmin external_view external_dimension_table add \
-p default \
-t dimensions.product_info#1 \
-e ''events.item_id = dimensions.product_info#1.item_id''
添加完成之后，后面在其它命令引用这张表时也需要使用 dimensions.product_info#1。
5. 限制与约束
5.1. 查询性能
由于关联维度表需要使用 JOIN，虽然神策的查询引擎已经对这个类型的 JOIN 做了一定程度的优化，但是相比直接使用原始的事件属性依然会有比较显著的
性能降低，具体的性能和维度表的大小、JOIN 的条件等都有关系。因此，我们建议在直接使用事件属性可以满足需求的情况下，不要使用维度表；同时，应当
保证维度表的行数在百万以内，以尽量降低 JOIN 带来的额外性能损耗。
5.2. 缓存一致性
目前为止，神策系统的缓存机制依然是基于事件数据的变更来实现的，这个机制中暂时没有考虑到维度表的数据变化带来的影响。因此，如果维度表的数据
发生了变更（例如进行 Update 或者 Insert），查询结果可能还会使用旧的缓存数据，这个时候需要强制刷新才能得到正确的结果。
6. 测试维度表的关联条件
对于比较复杂的关联条件，建议先使用 impala-shell 执行 SQL 来进行测试，以保证结果的正确性。可以直接使用 JOIN 语法进行，例如：
/*sa(test_project)*/
SELECT dimensions.product_info.product_manufacturer FROM
events
LEFT JOIN dimensions.product_info
ON events.product_id = dimensions.product_info.product_id
WHERE date = CURRENT_DATE()
LIMIT 100虚拟属性.虚拟属性 v1.17
1. 概述
所谓虚拟属性，是指在数据入库之后通过 SQL 表达式对已有的事件属性和用户属性进行二次加工，产生一个新的属性值。
虚拟属性根据表达式中引用到的属性类型分为用户虚拟属性和事件虚拟属性，需要注意的是确定了虚拟属性的类型之后只能引用同类型的属性，即事件虚拟
属性不能引用用户属性，用户虚拟属性不能引用事件属性，所以虚拟属性类型的选择应该根据所引用的属性的类型来决定。
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请统一咨询客户群
内的神策值班同学。
如何使用维度表 >
2. 创建虚拟属性
进入「元数据」-「虚拟属性」后点击「新建」按钮。选择此虚拟属性的分类并完成相关基本信息的填写后。在「SQL 表达式」中填写的 expression 实际上
只需要填写对属性的加工的 sql 表达式片段即可快速完成一个虚拟属性的创建，而不需要一个完整的 sql 表达式。
虚拟属性分为两种类型，事件虚拟属性和用户虚拟属性，顾名思义。分别含义请见如下说明：
信息 说明
属性分类 事件虚拟属性：指使用现有的 Event 事件表内的属性进行加工，也可使用 Event 与 Items 表或维度表（在后端通过命令完成关联配
置后）后基于此创建新的事件虚拟属性。
用户虚拟属性：指使用现有的 User 用户表中的属性进行二次加工，已完成新的属性与属性值的创建。
属性显示名 属性在使用过程中的显示名称，100 字符以内。
属性名 仅可命名为英文，是事件在系统内的唯一标示。
不能以数值、$ 符号开头，100 字符以内。
注：校验时，属性名大小写不敏感。
数据类型 必填单选：NUMBER、BOOL、STRING、DATETIME
字典 如果此属性使用了字典，编辑时修改虚拟属性的 SQL 规则，则需要对该虚拟属性重新上传维度字典。，需要在虚拟属性列表上重新
上传所需的字典文件。SQL 表达式 必填，只需要填写对属性的加工的 sql 表达式片段即可，示例可见下文
可用此属性的事 此设置只在选择了属性分类是「事件虚拟属性」后需要设置。（如果是「用户虚拟属性」那么在分析时将所有的事件均可使用此属性
件要求 进行分析。）
涵盖 SQL 表达式涉及的所有属性的事件，方可使用此虚拟属性。
涵盖至少一个 SQL 表达式中涉及的属性的事件，方可使用此虚拟属性。
3. 以下我们提供了集中常见的使用场景：
3.1. 数学函数
当需要对已有的数值型属性进行数学函数操作的二次加工时, 我们选用数学函数.
加减乘除运算：例如，我们有两个事件属性商品标价。commodity_price, 成交的最终价格 final_price当我们想判断商品标价
与最终价格的差值时我们可以直接
SQL 表达式：events.commodity_price - events.final_price
高精度小数: 默认情况下，神策分析的 NUMBER 类型只支持小数点之后 3 位，如果需要支持高精度类型，可将属性已字符
串类型上报给神策，再创建 NUMBER 类型的高精度小数虚拟属性
SQL 表达式：cast(events.big_number as decimal(38,16))
幂次函数: 例如，查询理财产品的本息总和。
SQL 表达式：events.capital + events.capital * pow(events.rate_of_interest, events.duration)
3.2. 时间日期函数
在用到时间日期函数前需要注意的是, 只有 Timestamp 类型可以直接使用 impala 的时间日期函数, 所以如果当 Date/Datetime 类型的属性作为时间日期函数
的参数时, 我们需要先使用 EPOCH_TO_TIMESTAMP 函数将属性转换为 Timestamp 类型.
adddate: 在一个 TIMESTAMP 值上加一个给定的天数
SQL 表达式：adddate(EPOCH_TO_TIMESTAMP(users.birthday), INT/BIGINT days)
datediff : 返回两个时间戳间隔天数
SQL 表达式：datediff(EPOCH_TO_TIMESTAMP(events.enddata), EPOCH_TO_TIMESTAMP(events.startdate))
extract: 从TIMESTAMP值中截取数值型的时间域，例如年度，月份，日期，小时，分钟，秒/微秒(year，month，day， hour，minute，second，
millisecond), 返回时间域的整数值.
SQL 表达式：extract(Year/Month/Day/Hour from EPOCH_TO_TIMESTAMP(users.birthdays))
dayofweek: 返回当前时间戳是周几(当然了也有 dayofmonth, dayofyear...)
SQL 表达式：dayofweek(EPOCH_TO_TIMESTAMP(events.register_time))
3.3. 字符串函数
concat: 联合去重, 把所有string类型的参数连接成一个string类型.
SQL 表达式：concat(events.$province, events.&city)
regexp_like(string source, string pattern[, string options]) : 判断source字符串中是否包含以pattern为正则表达式的内容SQL 表达式：regexp_like(users.user_name, ''[a-zA-Z0-9._ //-//[//](){}]{1,15}'')
parse_url: 属性抽取, 通过指定URL中的特定部分返回截取值. 可指定要截取的值为''PROTOCOL'', ''HOST'', ''PATH'', ''REF'',
''AUTHORITY'', ''FILE'', ‘USERINFO'', ‘QUERY''. 正常我们只需要输入指定的 url 以及需要截取的部分两个参数, 特殊的当要截
取的部分为 ‘QUERY'' 时, 我们可以输入第三个参数指定 QUERY 键值对中的 key，获取指定参数值.
SQL 表达式：parse_url(events.$url, ''QUERY'', ''q'')
3.4. 条件函数
caolesce: 属性合并, 这个函数会返回参数中第一个有值的参数的值. 假设我们在埋点的时候埋了两个属性：item_id 和
item_id_1，但实际上它们是一个含义，希望在使用的时候进行合并，也可以使用虚拟属性功能来定义。
SQL 表达式：coalesce(events.item_id, events.iten_id_1)
4. 校验规则与常见错误
1. 表达式中引用的属性必须存在且已经上报数据
2. 涉及到两个属性的数值计算时必须保证两个属性数据类型相同
3. 虚拟事件属性不能引用用户属性
4. 虚拟用户属性不能引用事件属性
5. number类型的虚拟属性运算符号两边必须是数字运算数字
6. 有维度字典的虚拟属性表达式返回值也必须为 bigint, string
7. 数据类型与返回值必须保持一致
8. 若创建虚拟属性后,又上报了相同名字的属性, 虚拟属性会失效.虚拟事件.虚拟事件 v1.17
1. 概述
为了更方便灵活的分析，可以使用虚拟事件，将元事件进行拆解或者组合形成新的「虚拟事件」，从而减少每次在分析过程中反复对固定常用的事件进行筛
选配置。
2. 创建虚拟事件
虚拟事件由多个元事件组合而来，且可以为虚拟事件的每个元事件设置过滤条件，当然也可以为单个元事件设置过滤条件后形成虚拟事件。删除虚拟事件，
不会删除相关数据。
点击 A 创建虚拟事件，点击 B 处编辑对应的虚拟事件。新建和编辑虚拟事件界面功能基本一致，此处以新建为例介绍，详细见下图。1. 在 A 处填写虚拟事件的基本信息（事件名和事件显示名）。
2. 点 击 B 处“触发限制条件”可以为对应元事件设置过滤条件。
3. 点击 C 处“添加事件”可以增加元事件。Session 管理.Session 管理 v1.17
1. 概述
第一次进行 Session 分析之前需要在这里创建 Session。
1. 点击 A 处“创建 Session”按钮可以创建一个 Session。
2. 点击 B 处编辑已经存在的 Session。
2. 创建 Session1. 在 A 处输入 Session 的名字，必须是合法的变量名。
2. 在 B 处输入显示名。
3. 在 C 处可以选择多个事件，在这里选择事件参与此 Session 分析。
4. 在 D 处输入 Session 的切割时间。
5. 在 E 处可开启事件切割，在原有的根据间隔时间切割的基础上，我们支持使用指定的「开始事件」和「结束事件」进行会话切割
3. 计算口径说明
3.1. 新的 session 切割是如何实现的？
步骤 1：将用户的行为序列，按照发生时间远到进进行排序
步骤 2：以第一个行为作为起点，向后进行匹配。
若匹配到的是一个「开始事件」：那么会自动切断会话；以这个「开始事件」作为起点，进行第二个 session 的匹配
若匹配到的是一个「结束事件」：那么会将这个「结束事件」划入到当前会话中；以「结束事件」的下一个事件作为起点，进行第二
个 session 的匹配若在切割时间内没有匹配到任何事件：那么就会自动切断会话；以下个事件作为起点，进行第二个 session 的匹配
3.2. 同时并发人数是如何实现的？
我们认为一个会话是一个持续的时段，那么在计算同时并发人数的时候，就判断该时间点有多少个会话同时在线即可。
如图所示：
时间点 1 的同时在线人数为 3
时间点 2 的同时在线人数为 2
时间点 3 的同时在线人数为 1
4. 使用场景
4.1. 什么时候使用开始和结束事件？
当我们对我们的会话有明确的开始和结束事件的定义时，可以使用开始和结束来让我们切割出来的会话更加符合预期。
比如：
在视频行业中有明确的「开始播放」和「结束播放」
在移动端有明确的「APP 启动」和「APP 退出」
一次转化路径中，会认为「首页」算做一个开始的点，「支付」的发生是一个结束的标志
4.2. 同时并发人数可以分析什么？
在事件是存在持续行为的场景中，同时并发人数相对事件的发生次数更加有代表意义。
我们来举个例子：
一个视频类的 APP，每个时段都有用户不断地进入和退出。
当我们做一些线上的活动时，希望在用户在线时间最密集的那一刻进行活动的推送
那么我们如何判断出哪个时段是在线的用户最多的时段呢？
我们来看一下模拟数据的结论：
用户 启动时间 退出时间 启动时间查看指标 同时在线查看指标
A 19:01 20:14 19:00-19:30 —— 3人 19:00-19:30 —— 3人
B 19:14 20:14 19:30-20:00 —— 1人 19:30-20:00 —— 4人
C 19:29 20:14 20:00-20:30 —— 2人 20:00-20:30 —— 6人D 19:59 20:14 20:30-21:00 —— 0人 20:30-21:00 —— 2人
E 20:14 21:01
F 20:29 22:01 最后结论得出，我们在 19:00-19:30 期间进行投放效果最好 最后结论得出，我们在 20:00-20:30 期间进行投放效果最好
实际上，我们的用户在 20:00 至 20:30 之间是在线人数最多的，在这个时间段进行运营活动效果最好可视化全埋点.可视化全埋点 v1.13
可视化全埋点为神策分析 1.14 版本新增功能
1. 接入说明
1.1. iOS 接入说明
iOS SDk 版本 v1.11.0+ 支持可视化全埋点
1.1.1. 获取scheme
使用 admin 账号，登录到神策分析相应的项目，点击右上角的账号，从「数据接入」页面获取 scheme 的值。
1.1.2. 配置 scheme
点击项目 target 选择选项卡Info，添加 URL Types，将第一步获取到的 scheme 配置到 URL Scheme 中。1.1.3. 开启可视化全埋点
在初始化 SDK 之后调用 enableVisualizedAutoTrack 方法开启可视化全埋点:
// SDK
[[SensorsAnalyticsSDK sharedInstance] enableVisualizedAutoTrack];
并 在 AppDelegate.m 中 的 - (BOOL)application:(UIApplication )app openURL:(NSURL )url options:(NSDictionary *)options 方法中 调用 handleSchemeUrl: 函数接收 URL
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:
(NSDictionary *)options {
if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url])
{ return YES;
}
return NO;
}
注意：只有开启了可视化全埋点功能，在采集 $AppClick 事件时才会记录 View 的 ViewPath。
1.1.4. 开启部分页面的可视化全埋点
如果只想查看部分页面的可视化全埋点，可以通过 addVisualizedAutoTrackViewControllers: 方法开启。
例如，开启 MainController 页面的可视化全埋点：
// MainController
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"
MainController"]];
设置后，只会采集 MainController 上的 View 的 ViewPath（$AppClick 事件）。
1.2. Android 接入说明
Android SDk 版本 v 3.1.0 + 支持可视化全埋点
1.2.1. 获取 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值。
1.2.2. 配置 scheme在 AndroidManifest.xml 中 MainActivity 的标签内，配置 scheme ：
1.2.3. 开启可视化全埋点
在初始化 SDK 之后调用 enableVisualizedAutoTrack 方法开启可视化全埋点:
// SDK , $AppClick View ViewPath
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrack();
1.2.4. 开启部分页面的可视化全埋点
如果只想开启部分页面的可视化全埋点，可以通过 addVisualizedAutoTrackActivities 或 addVisualizedAutoTrackActivity 方法开启。
例如，开启 MainActivity 页面的可视化全埋点：
// MainActivity
SensorsDataAPI.sharedInstance().addVisualizedAutoTrackActivity(MainActivity.class);
注意：开启了可视化全埋点功能后，扫描二维码打开 App 时（使用手机自带浏览器扫描），默认情况下会弹出 AlertDialog 提示框，来提示用户是否继续
连接进行可视化全埋点。
如果想关闭此提示框，可以调用 enableVisualizedAutoTrackConfirmDialog 关闭，关闭提示后，扫描二维码打开 App 时，会自动连接进行可视化
全埋点。
//
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrackConfirmDialog(false);
2. 功能使用说明
数据的查看
元素组件的操作
新增
删除
编辑
数据的使用
2.1. 可视化全埋点数据的查看在该页面展示全部已埋点的数据，包含：
事件名：自定义埋点的事件名
显示名：自定义埋点的事件中文名
操作系统：Android、iOS
最后修改版本：最后一次进行埋点修改所在的 App 版本
在该页面可以进行埋点数据的编辑和修改
编辑：可以修改事件的显示名
删除：点击可以删除已进行埋点的点位
2.2. 操作可视化全埋点组件元素添加可视化全埋点点位数据
红色表示该元素未被定义，绿色表示该元素已被定义。点击元素组件，可以设定元素组件的显示名、事件名；
需要保证显示名和事件名与其他事件不重复；
设置完成后点击保存，进行埋点点位设置的保存。
删除自定义元素组件
- ;
-
-编辑自定义元素组件
点击已经配置过的元素组件，可以查看元素组件的配置信息；
最初创建版本为该点位的最早进行配置的 App 版本；
用户可以修改元素组件的显示名。
2.3. 埋点数据的使用
分析模型中使用
在分析中，通过可视化全埋点选中的事件，使用方法与虚拟事件一致。2.4. 可视化全埋点的原理
可视化埋点的实现原理与创建虚拟事件基本类似，是基于 $AppClick 事件创建虚拟事件；若该事件删除后再次被添加，则历史数据也会生效。.可视化全埋点 v1.14
可视化全埋点为神策分析 1.14 版本新增功能
1. 接入说明
1.1. iOS 接入说明
iOS SDk 版本 v1.11.0+ 支持可视化全埋点
1.1.1. 获取 scheme
使用 admin 账号，登录到神策分析相应的项目，点击右上角的账号，从「数据接入」页面获取 scheme 的值。
1.1.2. 配置 scheme
点击项目 target 选择选项卡Info，添加 URL Types，将第一步获取到的 scheme 配置到 URL Scheme 中。1.1.3. 开启可视化全埋点
在初始化 SDK 之后调用 enableVisualizedAutoTrack 方法开启可视化全埋点:
// SDK
[[SensorsAnalyticsSDK sharedInstance] enableVisualizedAutoTrack];
并 在 AppDelegate.m 中 的 - (BOOL)application:(UIApplication )app openURL:(NSURL )url options:(NSDictionary *)options 方法中 调用 handleSchemeUrl: 函数接收 URL
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:
(NSDictionary *)options {
if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url])
{ return YES;
}
return NO;
}
注意：只有开启了可视化全埋点功能，在采集 $AppClick 事件时才会记录 View 的 ViewPath。
1.1.4. 开启部分页面的可视化全埋点
如果只想查看部分页面的可视化全埋点，可以通过 addVisualizedAutoTrackViewControllers: 方法开启。
例如，开启 MainController 页面的可视化全埋点：
// MainController
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"
MainController"]];
设置后，只会采集 MainController 上的 View 的 ViewPath（$AppClick 事件）。
1.2. Android 接入说明
Android SDk 版本 v 3.1.0 + 支持可视化全埋点
1.2.1. 获取 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值。
1.2.2. 配置 scheme在 AndroidManifest.xml 中 MainActivity 的标签内，配置 scheme ：
在 配 置 SDK Google
1.2.3. 开启可视化全埋点
在初始化 SDK 之后调用 enableVisualizedAutoTrack 方法开启可视化全埋点:
// SDK , $AppClick View ViewPath
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrack();
1.2.4. 开启部分页面的可视化全埋点
如果只想开启部分页面的可视化全埋点，可以通过 addVisualizedAutoTrackActivities 或 addVisualizedAutoTrackActivity 方法开启。
例如，开启 MainActivity 页面的可视化全埋点：
// MainActivity
SensorsDataAPI.sharedInstance().addVisualizedAutoTrackActivity(MainActivity.class);
注意：开启了可视化全埋点功能后，扫描二维码打开 App 时（使用手机自带浏览器扫描），默认情况下会弹出 AlertDialog 提示框，来提示用户是否继续
连接进行可视化全埋点。
如果想关闭此提示框，可以调用 enableVisualizedAutoTrackConfirmDialog 关闭，关闭提示后，扫描二维码打开 App 时，会自动连接进行可视化
全埋点。
//
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrackConfirmDialog(false);
2. 功能使用说明
数据的查看
元素组件的操作
新增
删除
编辑
数据的使用
2.1. 可视化全埋点数据的查看在该页面展示全部已埋点的数据，包含：
事件名：自定义埋点的事件名
显示名：自定义埋点的事件中文名
操作系统：Android、iOS
最后修改版本：最后一次进行埋点修改所在的 App 版本
在该页面可以进行埋点数据的编辑和修改
编辑：可以修改事件的显示名
删除：点击可以删除已进行埋点的点位
2.2. 操作可视化全埋点组件元素添加可视化全埋点点位数据
红色表示该元素未被定义，绿色表示该元素已被定义。点击元素组件，可以设定元素组件的显示名、事件名；
需要保证显示名和事件名与其他事件不重复；
设置完成后点击保存，进行埋点点位设置的保存。
删除自定义元素组件
- ;
-
-编辑自定义元素组件
点击已经配置过的元素组件，可以查看元素组件的配置信息；
最初创建版本为该点位的最早进行配置的 App 版本；
用户可以修改元素组件的显示名。
2.3. 埋点数据的使用
分析模型中使用
在分析中，通过可视化全埋点选中的事件，使用方法与虚拟事件一致。2.4. 可视化全埋点的原理
可视化埋点的实现原理与创建虚拟事件基本类似，是基于 $AppClick 事件创建虚拟事件；若该事件删除后再次被添加，则历史数据也会生效。.可视化全埋点 v1.17
1. 概述
神策分析的 SDK 提供全埋点的功能，全埋点会将全部的页面浏览事件和大部分常见控件的点击事件自动采集起来，通常事件量会比较大，控件难以区分。全
埋点已经采集的数据结合可视化全埋点则能够让没有代码能力的分析人员根据业务需求，将需要分析的关键事件通过可视化的方式在产品界面中筛选出来，
形成可视化全埋点事件。
神策提供了丰富的数据定义方式，可以对iOS App、Android App 进行可视化全埋点。进入埋点模式后，需要点击相应的元素并根据界面提示做相应的选择进
行保存，就能在事件分析中对其进行使用，其分析的效力等同于神策分析现有的虚拟事件，可以在绝大部分分析场景下正常使用。
例如： 你关心首页九宫格按钮浏览/点击情况，那你就需要对首页九宫格按钮这几个元素进行通过可视化全埋点的方式进行定义，下图是一个常见的可视化
全埋点的使用流程：
如果需要使用本功能，请先确保你的 SDK 和神策分析已经升级至对应保本，并且进行了集成，集成文档如下：
iOS：iOS 集成文档
Android：Android 集成文档
1.1. 版本兼容
1.17 版本的可视化全埋点提供了较大的升级，所以对 SDK 和神策分析都有版本的要求，要求如下：
Android SDK：v4.0.0 及其以上
iOS SDK：v2.0.0 及其以上
神策分析：v1.17.2517 及其以上
升级不会影响升级之前创建的可视化全埋点事件的统计效果。
2. 适用范围
神策分析支持通过对用户行为数据的采集和分析，帮助企业的策略制定者探索新的产品机会，分析用户转化或留存的原因。而正确的数据采集是实现上述场
景的必要条件。
在多年的实践中，神策团队发现只用一种数据采集方式无法解决日益复杂的数据分析需求，无法适应高速迭代的产品开发节奏。神策提供了代码埋点和可视
化全埋点两种采集方式来适应针对不同场景下的数据采集需求。使用者需要充分了解这两种埋点方式的特性和边界，才能扬长避短，在合适的场景下使用对应的数据采集方法，达成数据采集工作灵活与准确的平衡。
更多关于两种埋点方法的优劣，详情可以查看：代码埋点与可视化全埋点分别的适用场景
3. 如何定义可视化全埋点事件
详细见：App 可视化全埋点使用指南
4. 可视化全埋点事件命名规范
由于可视化全埋点的定义成本很低，无需代码就可以直接进行事件的定义，所以容易出现定义混乱，不便于管理的情况，一个好的事件名至关重要。
神策的可视化全埋点系统会自动生成一个预置的事件名，使用者可以根据自己的系统进行修正，增加前缀或者后缀。
推荐的格式为：
行为类型_页面名称_按钮名称_平台_版本
行为类型：指的是这个事件是点击行为，还是页面浏览行为
页面名称：指的是这个行为发生在哪个页面，起名的原则主要是要保证绝大部分使用这个事件的人能够根据名字回忆起对应的页面
按钮名称：指的是这个行为发生在哪个按钮上，只有点击行为才有这个值，起名的原则主要是要保证绝大部分使用这个事件的人能够根据名字回忆
起对应的页面
平台：主要是指对应的运行平台，是 Android，iOS 还是 Web
版本：由于可视化全埋点的技术特性，可能在 App 版本升级之后，部分事件定义就会失效，不再统计数据，所以版本对于我们在排查问题时起到了
很关键的作用
神策分析系统的默认显示名生成规则如下，供大家参考：
事件类型 对应规则 示例
App 元素点击 点击_{页面名称}_{按钮内容}_{平台}_{版本} 点击_登录页_登录_iOS_v2.0.1
如果页面名称取不到，则为空
如果按钮没有内容，则默认写作「控件」
平台枚举值：Android，iOS
版本：埋点时 App 的版本
App 页面访问 浏览_{页面名称}_{平台}_{版本} 浏览_登录页_iOS_v2.0.1
如果页面名称取不到，则为空
平台枚举值：Android，iOS
版本：埋点时 App 的版本App 可视化全埋点使用指南.App 可视化全埋点使用指南 v1.17
1. 功能介绍
App 可视化全埋点功能提供了通过电脑与手机画面同步，定义事件的功能，具体的功能列表如下：
1. 定义多种类型的控件，支持根据其在 Listview 中的位置和内容进行筛选；
2. 在电脑端便捷操作，右侧界面动态展示当前定义的元素的准确定义；
3. 支持多种设备：手机、平板电脑以及对应的横竖屏。
2. 准备工作
2.1. 正确集成对应的 SDK
版本要求：
Android SDK：v4.0.0 及其以上
iOS SDK：v2.0.0 及其以上
集成方法，详细见：
iOS：iOS 集成文档Android：
Android 集成文档
2.2. 如何进入埋点页面
通过上述步骤，进入扫描二维码的页面。在扫描二维码的页面，使用手机浏览器的扫一扫功能或者是微信扫一扫的功能进行扫码，根据浏览器弹窗提示的操作打开对应的 App，如果遇到扫码后无响
应，无法正确地唤起 App 的问题，可以下载「掌上神策」，利用「掌上神策」的扫一扫功能扫描二维码。
2.3. 查看连接状态与 App 基本信息
2.3.1. 基本信息
可以通过在 App 界面上方的信息查看当前埋点应用的平台，应用版本和设备连接情况。
2.3.2. 界面暂停同步当电脑界面正处在定义元素的时候，界面同步会暂定，避免出现两端一边正在定义元素，一边界面产生变化的情况，定义完成会界面会自动同步。
3. 定义事件
3.1. 定义元素点击事件
3.1.1. 元素埋点与限定条件
3.1.1.1. 定义某个特定位置的元素点击事件
单击某一个元素，可以看到限定条件的限定内容如下：
不限定内容（文本）
限定顺序为第四位
上面两个条件意味着，当前定义的是发生在当前页面的，同类元素内，在列表中顺序位置为第「4」位的元素点击事件。若元素的内容（文本）变化，埋点仍
然有效。
事件显示名可以修改，确认内容无误后，可以点击保存。
3.1.1.2. 定义某个特定内容的元素点击事件变化一下条件，可以看到限定条件内容如下：
限定内容（文本）
不限定顺序位置
上面两个条件意味着，当前定义的是发生在「当前页面」下，同类元素内，内容（文本）为「生活旅行」的元素点击事件。元素顺序变化，埋点仍然有效。
元素内容（文本）变化，埋点失效。
3.1.1.3. 定义某个特定内容，特定位置的元素
变化一下条件，可以看到限定条件内容如下：
限定内容（文本）
限定顺序位置
上面两个条件意味着，当前定义的是发生在「当前页面」下，同类元素内，内容（文本）为「生活旅行」，在列表中顺序为第「4」位的元素点击事件。若元
素的内容或在列表中的顺序发生改变，埋点将会失效。
3.1.1.4. 定义整个列表按钮变化一下条件，可以看到限定条件内容如下：
不要限定内容（文本）
不要限定顺序位置
上面两个条件意味着，当前定义的是发生在「当前页面」下，截图中被选中的一系列元素的点击事件。
3.1.2. 定义某个在可点击的卡片上层的独立按钮当多个元素共用一个点击区域时，神策的系统会将其标识为一个点击元素，但是当卡片上点击功能独立于其他元素的元素时，这个元素可以被单独标记，如
上图所示。
3.1.3. 对已埋点的元素再次进行定义以图中元素为例，假如已经标定了一个元素限定条件为限定内容，限定顺序位置，这个时候还想针对同一个元素标定不限定内容的点击事件，就需要先把
「高亮已埋点元素」关闭，然后就可以进入定义事件的界面，后续将会对本功能做持续的交互优化，敬请期待。
3.2. 定义页面浏览事件
3.3. 管理可视化埋点事件
3.3.1. 查看事件
查看事件详情的方法有两种，一种是在定义过程中，可以直接在左侧的栏目中查看事件详情。另一种是在最外层的可视化埋点事件管理的列表查看埋点详情。
3.3.2. 删除事件
删除事件有两个方法，一个是在定义过程中，发现定义产生错误，可以直接在左侧的栏目中删除事件。
或者可以在最外层的可视化埋点事件管理的列表进行删除。代码埋点与可视化全埋点分别的适用场景.代码埋点与可视化全埋点分别的适用场景 v1.14
神策分析支持通过对用户行为数据的采集和分析，帮助企业的策略制定者探索新的产品机会，分析用户转化或留存的原因。而正确的数据采集是实现上述场
景的必要条件。
在多年的实践中，神策团队发现只用一种数据采集方式无法解决日益复杂的数据分析需求，无法适应高速迭代的产品开发节奏。神策提供了代码埋点和可视
化全埋点两种采集方式来适应针对不同场景下的数据采集需求。
使用者需要充分了解这两种埋点方式的特性和边界，才能扬长避短，在合适的场景下使用对应的数据采集方法，达成数据采集工作灵活与准确的平衡。
两种埋点的比较
比较 代码埋点 可视化全埋点
项
准确度 准确度极高，但是可能会出现由于埋点需求沟通不准确导 准确度忽高忽低，主要取决于被埋点的代码的规范程度，代码越规范，准确度越
致数据产生偏差的情况。 高。
兼容性 兼容性极佳，因为是代码埋点，可以针对各种定义控件和 兼容性比较好，可以正对大部分常见的控件和页面进行定义，但是定义行为比较
自定义交互进行定义。 单一，只支持点击和页面浏览。
稳定性 代码埋点，较为稳定，版本升级只要不改动埋点的代码， 不稳定，版本升级，调整样式，都有可能对埋点的准确性造成影响。
埋点就一直生效。
自定义 支持，可以在任何的事件中添加自定义的属性，包括输入 不支持自定义属性。
数据属 框中的值，订单金额等业务数据。
性
管理成 管理成本比较低，因为是代码埋点，通常事件量较少，而 管理成本高，时间久了不维护，数量越来越多，数据体系容易混乱。
本 且会经过专人专门设计，所以便于管理。
埋点成 比较高，需要成熟的团队协作机制，神策分析有强大的交 非常低，只需要很简单的学习成本就可以进行埋点。
本 付团队会对客户初次埋点的过程进行支持。
回溯历 不能支持回溯历史，如果上线前忘记埋点，那就有一部分 支持历史回溯，只要对应的版本集成了神策 SDK 并且开启了可视化全埋点功能，
史 数据永远「丢失」了。 后续版本的数据都可以随时查阅，无需上线前集中埋点。
两种埋点，如何选择？
数据采集方式的选择是基于业务场景的，那么，不同的业务场景下应该选取什么样的数据采集方式呢？
代码埋点适合的典型场景
典型场景：
核心的业务数据，比如当天的交易额，当月交易中商品的分布；
分析整年度的核心业务数据，比如一整年的单用户获取成本波动；
对于业务进行深度分析，分析不同的拳头商品对应的客户的转化率；
进行归因分析等更复杂的业务分析。
这类场景具有如下属性：
需要数据稳定准确，反应真实业务运作情况；
需要长期监控，甚至会出现按年分析的情况，需要持续追踪数据，并且保证统计口径的稳定性；
业务属性丰富，可以做深度业务分析；
监控核心 KPI，指标需要少而精。
可视化埋点适合的典型场景
典型场景：
做了一场运营活动，但没有埋点的产研资源；
想衡量交互细节，而需要查看的交互细节非常多；
当新功能上线，准备做数据分析时，你突然发现有一个重要的元素忘了埋点。
这类场景具有如下属性：
业务属性弱，交互属性强；需求及时性强，要快速落地得出结论；
数据使用周期短，不需要长期监控；
不要追求数据 100%准确，只需要看趋势就可以得出有价值的结论；
非核心数据。
结论
两种场景并不互斥，大家平时会经常同时遇到这两种场景。
一个用可视化埋点就能解决的问题，若使用代码埋点，非但不能立即看到数据，也会浪费公司工程资源；一个用代码埋点才能解决的问题，如果用可视化全
埋点，就会导致分析的时候数据缺斤少两，并且线上的业务数据由于埋点的缺失，正在源源不断地「流失」。
代码埋点和可视化埋点各自有自己的优势和劣势，因此有着不同的适用场景。面对不同的场景，我们需要明确目的是什么，只有选择合适的埋点方式，才能
把事情做得又快又好。
“不积跬步，无以至千里;不积小流，无以成江海”，数据采集正是数据驱动的根基。通过代码埋点和可视化埋点优势相结合，配合神策分析交付团队强大的支
持，“精准”和“敏捷”可以兼得，让更多企业在数据增长体系搭建初期就能够打下坚实的基础，在神策成熟的交付流程下锻炼企业自身的数据采集和分析能
力，进而通过数据获得分析和洞察，指导实际的产品问题和商业业务发展问题，真正地实现数据驱动。.代码埋点与可视化全埋点分别的适用场景 v1.17
神策分析支持通过对用户行为数据的采集和分析，帮助企业的策略制定者探索新的产品机会，分析用户转化或留存的原因。而正确的数据采集是实现上述场
景的必要条件。
在多年的实践中，神策团队发现只用一种数据采集方式无法解决日益复杂的数据分析需求，无法适应高速迭代的产品开发节奏。神策提供了代码埋点和可视
化全埋点两种采集方式来适应针对不同场景下的数据采集需求。
使用者需要充分了解这两种埋点方式的特性和边界，才能扬长避短，在合适的场景下使用对应的数据采集方法，达成数据采集工作灵活与准确的平衡。
1. 两种埋点的比较
比较 代码埋点 可视化全埋点
项
准确度 准确度极高，但是可能会出现由于埋点需求沟通不准确导 准确度忽高忽低，主要取决于被埋点的代码的规范程度，代码越规范，准确度越
致数据产生偏差的情况。 高。
兼容性 兼容性极佳，因为是代码埋点，可以针对各种定义控件和 兼容性比较好，可以正对大部分常见的控件和页面进行定义，但是定义行为比较
自定义交互进行定义。 单一，只支持点击和页面浏览。
稳定性 代码埋点，较为稳定，版本升级只要不改动埋点的代码， 不稳定，版本升级，调整样式，都有可能对埋点的准确性造成影响。
埋点就一直生效。
自定义 支持，可以在任何的事件中添加自定义的属性，包括输入 不支持自定义属性。
数据属 框中的值，订单金额等业务数据。
性
管理成 管理成本比较低，因为是代码埋点，通常事件量较少，而 管理成本高，时间久了不维护，数量越来越多，数据体系容易混乱。
本 且会经过专人专门设计，所以便于管理。
埋点成 比较高，需要成熟的团队协作机制，神策分析有强大的交 非常低，只需要很简单的学习成本就可以进行埋点。
本 付团队会对客户初次埋点的过程进行支持。
回溯历 不能支持回溯历史，如果上线前忘记埋点，那就有一部分 支持历史回溯，只要对应的版本集成了神策 SDK 并且开启了可视化全埋点功能，
史 数据永远「丢失」了。 后续版本的数据都可以随时查阅，无需上线前集中埋点。
2. 两种埋点，如何选择？
数据采集方式的选择是基于业务场景的，那么，不同的业务场景下应该选取什么样的数据采集方式呢？
2.1. 代码埋点适合的典型场景
典型场景：
核心的业务数据，比如当天的交易额，当月交易中商品的分布；
分析整年度的核心业务数据，比如一整年的单用户获取成本波动；
对于业务进行深度分析，分析不同的拳头商品对应的客户的转化率；
进行归因分析等更复杂的业务分析。
这类场景具有如下属性：
需要数据稳定准确，反应真实业务运作情况；
需要长期监控，甚至会出现按年分析的情况，需要持续追踪数据，并且保证统计口径的稳定性；
业务属性丰富，可以做深度业务分析；
监控核心 KPI，指标需要少而精。
2.2. 可视化埋点适合的典型场景
典型场景：
做了一场运营活动，但没有埋点的产研资源；
想衡量交互细节，而需要查看的交互细节非常多；
当新功能上线，准备做数据分析时，你突然发现有一个重要的元素忘了埋点。
这类场景具有如下属性：
业务属性弱，交互属性强；需求及时性强，要快速落地得出结论；
数据使用周期短，不需要长期监控；
不要追求数据 100%准确，只需要看趋势就可以得出有价值的结论；
非核心数据。
3. 结论
两种场景并不互斥，大家平时会经常同时遇到这两种场景。
一个用可视化埋点就能解决的问题，若使用代码埋点，非但不能立即看到数据，也会浪费公司工程资源；一个用代码埋点才能解决的问题，如果用可视化全
埋点，就会导致分析的时候数据缺斤少两，并且线上的业务数据由于埋点的缺失，正在源源不断地「流失」。
代码埋点和可视化埋点各自有自己的优势和劣势，因此有着不同的适用场景。面对不同的场景，我们需要明确目的是什么，只有选择合适的埋点方式，才能
把事情做得又快又好。
“不积跬步，无以至千里;不积小流，无以成江海”，数据采集正是数据驱动的根基。通过代码埋点和可视化埋点优势相结合，配合神策分析交付团队强大的支
持，“精准”和“敏捷”可以兼得，让更多企业在数据增长体系搭建初期就能够打下坚实的基础，在神策成熟的交付流程下锻炼企业自身的数据采集和分析能
力，进而通过数据获得分析和洞察，指导实际的产品问题和商业业务发展问题，真正地实现数据驱动。权限管理.成员与角色 v1.17
1. 成员管理登录
管理员添加到神策系统中的每个用户，都是一个项目中的成员。成员管理即原右上角身份信息（例如：分析师）下拉列表中「账号管理」，挪到顶部导航栏
更多中的「成员与角色」中更名为「成员管理」。
在成员管理模块，您可以查看通过列表查看成员的姓名、登录账号、帐号类型、角色、手机号、职务等信息，也可以操作添加成员、转交工作、重置成员账
号密码、编辑成员信息、删除成员等。
1.1. 添加成员
神策支持两种账号类型：项目账号与平台成员，可根据企业情况决定使用哪种类型。如果情况比较复杂，两种类型支持并存。
「项目成员」只能存在于单独的一个项目之中
例如：小王可以使用「项目 A」，如果管理员为其创建的账号类型是「项目账号」，那么他只能在登录页面选择「项目账号」并选择「项目A」
后，同时输入账号密码，方可登录。如果小王现在需要使用「项目 B」，那么则需要管理员为他在「项目 B」中创建一个新的账号。随后需要
分别在不同的项目中登录对应的账号。
「平台成员」可以使用同一个组账号密码，访问多个授权项目
例如：小王可以使用「项目 A」，如果管理员为其创建的账号类型是「平台账号」，那么他需要在登录了页面使用「平台账号」直接输入账号
密码进行登录。如果小王现在需要使用「项目 B」，那么则需要管理员在「项目 B」中邀请他进入。随后小王在登录后则可查看到「项目 A」
和「项目 B」两个项目，在使用的过程中也可随时切换。
1.1.1. 添加「项目账号」
「项目账号」是指可以登录当前项目的成员账号。 只需在成员管理列表页点击「新建账号」，选择「项目帐号」，填写成员的登录账号、登录密码、员工姓
名、角色等信息即可成功添加一个成员。将账号和密码给对应成员，就可以登录使用神策系统了。1.1.2. 添加「平台账号」
新增「平台账号」是全网唯一的帐号，可以被邀请登录企业任意项目。 只需在成员管理列表页点击「添加成员」，选择「平台帐号」，填写成员的登录账号、
登录密码、员工姓名、角色等信息即可成功添加一个成员。将账号和密码给对应成员，就可以登录使用神策系统了。 也可以点击「邀请」，将平台账号成员
直接邀请到当前项目中1.2. 邀请平台成员
新增「邀请平台成员」，点击成员管理列表上方的「邀请平台成员」，进入「授权平台帐号使用当前项目」列表，展示可以添加到当前项目的一网通成员，
点击「授权访问」，选择成员角色后，平台成员即可登录项目，进行数据监控，分析等操作。
授权平台账号访问当前项目时，可以选择在当前项目的角色。如平台账号成员使用过程中，，因为业务原因，权限需要调整，将成员添加到另一个角色中就可以了。
1.3. 查看成员明细信息
1.3.1. 基本信息与权限明细
后可查看个人的帐号名、手机号、登录账号、角色、邮箱等基础信息
也可以查看自己在数据权限、数据分析、用户群、自定义查询、企业管理、概览、预置概览模块的权限明细。 当不能查看某些数据、或不能使用某个功能
时，可以查看个人中心的权限明细，确认是否有查看、使用权限。
1.3.2. 操作日志
操作日志则记录了所有成员在神策平台上近 90 天的所有登录、查询、浏览、权限变更等明细日志。同时支持按照操作事件、操作类型、涉及模块进行快捷
筛选。1.4. 转交工作
当成员离职、或不负责现在的工作时，点击列表中的「转交工作」，将成员创建的书签、概览批量转交给其他成员。
1.5. 重置成员账号密码
当成员密码遗失时，admin可以点击「重置密码」重新设置密码，同步给成员后，可继续使用神策分析系统。1.6. 编辑成员信息
当成员信息有变动时，可以点击「编辑」，编辑员工姓名、手机号、邮箱地址、职务、角色等信息。 请注意，如果在项目中修改平台成员的角色，只在当前
项目生效。
1.7. 删除成员
当成员离职等需要删除成员时，点击「删除」，即可立即删除成员。 请注意，若成员创建了书签、概览，需选择将书签、概览转交个其他成员后，才可以删
除帐号。1.8. 职务管理
在「成员管理」中新增「职务管理」，可以填写使用神策分析的成员的职务，当创建成员时就可以直接选择具体职务了。
职务管理中可以选择创建成员时，职务是否需要必填；因为不同成员使用神策分析，需要关注的业务细节不同，建议创建成员时填写好职务，这样就可以在
分享概览设置时，按职务进行动态分享了。
2. 角色管理
一个角色，就相当于一个权限包。管理员给每个成员创建帐号时，都需要选择成员的角色。我们支持根据需求自定义角色，并赋予他不同的权限。 例如管理
员角色，可以设置系统的基础信息，分析师角色仅可使用、查看系统。 「角色管理」原来在右上角身份信息（例如：分析师）下拉列表中，现挪到顶部导航
栏更多中的「成员与角色」中。2.1. 多角色授权模型
神策产品均支持「多角色权限授权」模型，让分级授权，按需组合分发不同角色来快捷满足不同的授权需求。当一个成员被授予了多个角色时，该成员所用
的权限是多个角色授权的最大集合。举个例子：
小周被赋予了 A 和 B 两个角色，那么当小周登录神策平台后，可以看见的数据范围，实际上是全部用户的全部数据，及时 B 角色中仅授权可使用部分用户
的全部数据，那么也会应为多角色权限按照并集进行最大集合权限的授权而使 B 角色对于小周的限制是无效的。
角色 授权模块 权限配置
A 数据范围 可查看全部用户的全部数据
B 数据范围 可查看部分用户的全部数据；其中部分用户的条件为「常驻地区」等于「北京」
为了让权限分配者可以更加有效的管理每个成员的权限，并且在授权后快捷的验证每个成员是否正确，我们提供了「个人资料页」来汇总此信息，支持有
「成员管理权限」的成员可以直接查看到每个成员的角色分配情况，以及最终授权结果和每个模块的授权来源。每个成员也可从导航栏点击个人名称 (A) 呼出下拉面板中查看自己的「个人资料」。在 B 区域可查看到当前成员授权的角色。当授权了多角色后，在「权限
明细」鼠标移动到每行上，会显示 C 查看此模块的授权明细，点击后即可查询到具体的角色授权关系。
2.2. 新建角色
神策也支持根据业务需求自定义角色。点击「新建角色」，填写角色名称、适用范围、勾选需要的权限即可。2.3. 权限功能的灵活授权能力更加强大，可对概览、分析、元数据、预警管理、成员与角色等功
能模块的权限全面细分。
2.3.1. 数据分析模块权限
「可用事件」的权限 选择自定义授权时，新增「按标签动态授权」事件使用权限。例如：角色A的事件权限可以查看标签为app的所有事件，当新增
「app 注册」事件，「标签为app」，那么角色A可以查看「app 注册」事件相关的数据。 注：无论是元事件还是虚拟事件，都在此模块中进行授权。
例如：虚拟事件 A ，包括 a,b,c 三个元事件，当授权某个角色「虚拟事件 A 」时，在各个分析模型中可使用「虚拟事件 A 」，但 a,b,c 三个元事件
是不能使用的。
「可用事件属性」 在分析模型中，不可使用未授权的属性进行筛选、查看、group by。用户行为序列详情页均不显示未授权的信息。 「可用用户属
性」「可用用户群」 在分析模型中，不可使用未授权的属性进行筛选、查看、group by。用户列表和详情页均不显示此信息
2.3.2. 用户群模块权限
「查看用户群」权限，自定义授权时，支持设置指定可见/指定不可见的用户群的同时，新增设置「指定角色创建的用户群」是否可见，动态授权用
户群查看权限
2.3.3. 概览拆分为：查看我的概览、管理我的概览、查看公共概览、管理公共概览四个部分。
新增管理公共概览，可以将场景库中的场景创建为公共概览，也可以自己创建公共概览。
2.3.4. 漏斗权限细分：根据用户的使用，将漏斗权限拆分为：可用漏斗、管理漏斗两种。
可用漏斗：可以按「全部可用」、「admin创建」、「指定成员」三种情况，选择分析时可以使用哪些漏斗。
管理漏斗：用户可以在漏斗分析中，编辑、删除自己可以使用的漏斗。
只要有漏斗分析权限的用户，都可以自己创建、管理自己的漏斗。2.3.5. 指定加密信息
在角色管理中，可以对每个角色配置对应的加密用户属性和加密事件属性。可有效地在不影响分析的前提下，进行重要信息的脱敏。
勾选后，可看到对应的编辑入口（绿色圈选处）以用户属性加密的设置为例，加密信息仅可对非 BOOL 和 DATATIME 类型的属性进行加密设置。加密方式分为两种：
加密显示：在用户列表、行为序列中以加密显示，导出文件中同样会加密显示。加密内容在分析中可正常进行统计计算。
禁止分组与筛选：在分析模型中不可使用此信息进行数据的分组查看，也不可使用此信息在筛选条件中进行查询。在对所有分析模型和自定义查询
均生效。
此加密方式可二选其一。如果既不想用户查看到此属性对应的具体信息，也不希望对方在分析模型中使用，那么可前往「可用事件属性」和「可用用户属
性」的配置用进行完整的禁用配置。
2.4. 默认增加「开发者」系统角色当研发接入数据或者埋点时，需要使用埋点管理、元数据等功能查看埋点完成情况，但不需要使用其他业务功能时，可为其分配「开发者」的角色，如果此
系统角色不满足需要，也可新建一个「自定义角色」进行灵活授权。
2.5. 如果企业购买了「用户标签产品」、「智能推荐产品」则可配置对应的权限
2.5.1. 用户标签模块权限
新增用户标签模块权限，如果买用户画像系统，可以设置「用户标签」的查看、新建、管理、审核、标签结构管理权限
查看权限：点击编辑，可以设置允许查看的标签范围，支持选择全部标签、我创建的标签、自定义授权三种方式。其中自定义授权，支持设置指定
可见/指定不可见的用户群的；设置「指定角色创建的用户标签」是否可见，动态授权用户标签查看权限。
新建权限：是指可进行新建，并编辑、删除自己创建的数据。
管理权限：管理查看范围内的所有用户标签，包括「编辑」、「删除」、「重新计算」、「启停用」操作。当角色授权了「新建」权限后，管理权
限可根据业务，选择「查看范围内的所有」、「我创建的」标签两种权限范围。
审核权限：标签创建后，可以审核标签是否允许使用
标签结构管理权限：对所有的「标签树结构」和「标签的所属分类」进行分组排序管理。
2.5.2. 个性化推荐模块权限
如购买神策个性化推荐，尚未支持自定义权限配置的模块，新增「个性化推荐」的查看和管理权限。 方案一：支持查看所有推荐相关的数据；管理个性化推
荐的「内容库」「内容规则」「推荐规则」 方案二、三：支持查看所有推荐相关的数据；.成员与角色管理 v1.15
1. 成员管理
管理员添加到神策系统中的每个用户，都是一个项目中的成员。成员管理即原右上角身份信息（例如：分析师）下拉列表中「账号管理」，挪到顶部导航栏
更多中的「成员与角色」中更名为「成员管理」。
在成员管理模块，您可以查看通过列表查看成员的姓名、登录账号、帐号类型、角色、手机号、职务等信息，也可以操作添加成员、转交工作、重置成员账
号密码、编辑成员信息、删除成员等。
1.1. 添加成员
可以添加成员到神策系统中，一起进行数据监控、分析。
1.1.1. 添加「项目成员」
「项目成员」是指可以登录当前项目的成员账号。 只需在成员管理列表页点击「新建账号」，选择「项目帐号」，填写成员的登录账号、登录密码、员工姓
名、角色等信息即可成功添加一个成员。将账号和密码给对应成员，就可以登录使用神策系统了。
1.1.2. 添加「平台成员」
新增「平台成员」是全网唯一的帐号，可以被邀请登录企业任意项目。 只需在成员管理列表页点击「添加成员」，选择「平台帐号」，填写成员的登录账号、
登录密码、员工姓名、角色等信息即可成功添加一个成员。将账号和密码给对应成员，就可以登录使用神策系统了。 也可以点击「邀请」，将平台账号成员
直接邀请到当前项目中1.2. 邀请平台成员
新增「邀请平台成员」，点击成员管理列表上方的「邀请平台成员」，进入「授权平台帐号使用当前项目」列表，展示可以添加到当前项目的一网通成员，
点击「授权访问」，选择成员角色后，平台成员即可登录项目，进行数据监控，分析等操作。
授权平台账号访问当前项目时，可以选择在当前项目的角色。如平台账号成员使用过程中，，因为业务原因，权限需要调整，将成员添加到另一个角色中就可以了。
1.3. 转交工作
当成员离职、或不负责现在的工作时，点击列表中的「转交工作」，将成员创建的书签、概览批量转交给其他成员。
1.4. 重置成员账号密码
当成员密码遗失时，admin可以点击「重置密码」重新设置密码，同步给成员后，可继续使用神策分析系统。
1.5. 编辑成员信息
当成员信息有变动时，可以点击「编辑」，编辑员工姓名、手机号、邮箱地址、职务、角色等信息。 请注意，如果在项目中修改平台成员的角色，只在当前
项目生效。1.6. 删除成员
当成员离职等需要删除成员时，点击「删除」，即可立即删除成员。 请注意，若成员创建了书签、概览，需选择将书签、概览转交个其他成员后，才可以删
除帐号。
2. 角色管理
一个角色，就相当于一个权限包。管理员给每个成员创建帐号时，都需要选择成员的角色。我们支持根据需求自定义角色，并赋予他不同的权限。 例如管理
员角色，可以设置系统的基础信息，分析师角色仅可使用、查看系统。 「角色管理」原来在右上角身份信息（例如：分析师）下拉列表中，现挪到顶部导航
栏更多中的「成员与角色」中。神策也支持根据业务需求自定义角色。点击「新建角色」，填写角色名称、适用范围、勾选需要的权限即可。
2.1. 增加了更多权限设置的细节
2.1.1. 数据分析模块权限「可用事件」的权限 选择自定义授权时，新增「按标签动态授权」事件使用权限。例如：角色A的事件权限可以查看标签为app的所有事件，当新增
「app 注册」事件，「标签为app」，那么角色A可以查看「app 注册」事件相关的数据。 注：无论是元事件还是虚拟事件，都在此模块中进行授权。
例如：虚拟事件 A ，包括 a,b,c 三个元事件，当授权某个角色「虚拟事件 A 」时，在各个分析模型中可使用「虚拟事件 A 」，但 a,b,c 三个元事件
是不能使用的。
「可用事件属性」 在分析模型中，不可使用未授权的属性进行筛选、查看、group by。用户行为序列详情页均不显示未授权的信息。 「可用用户属
性」「可用用户群」 在分析模型中，不可使用未授权的属性进行筛选、查看、group by。用户列表和详情页均不显示此信息
2.1.2. 用户群模块权限
「查看用户群」权限，自定义授权时，支持设置指定可见/指定不可见的用户群的同时，新增设置「指定角色创建的用户群」是否可见，动态授权用
户群查看权限
2.2. 如果企业购买了「用户标签产品」、「智能推荐产品」则可配置对应的权限
2.2.1. 用户标签模块权限
新增用户标签模块权限，如果买用户画像系统，可以设置「用户标签」的查看、新建、管理、审核、标签结构管理权限
查看权限：点击编辑，可以设置允许查看的标签范围，支持选择全部标签、我创建的标签、自定义授权三种方式。其中自定义授权，支持设置指定
可见/指定不可见的用户群的；设置「指定角色创建的用户标签」是否可见，动态授权用户标签查看权限。
新建权限：是指可进行新建，并编辑、删除自己创建的数据。
管理权限：管理查看范围内的所有用户标签，包括「编辑」、「删除」、「重新计算」、「启停用」操作。当角色授权了「新建」权限后，管理权
限可根据业务，选择「查看范围内的所有」、「我创建的」标签两种权限范围。
审核权限：标签创建后，可以审核标签是否允许使用
标签结构管理权限：对所有的「标签树结构」和「标签的所属分类」进行分组排序管理。
2.2.2. 个性化推荐模块权限
如购买神策个性化推荐，尚未支持自定义权限配置的模块，新增「个性化推荐」的查看和管理权限。 方案一：支持查看所有推荐相关的数据；管理个性化推
荐的「内容库」「内容规则」「推荐规则」 方案二、三：支持查看所有推荐相关的数据；.成员与角色管理 v1.16
1. 成员管理
管理员添加到神策系统中的每个用户，都是一个项目中的成员。成员管理即原右上角身份信息（例如：分析师）下拉列表中「账号管理」，挪到顶部导航栏
更多中的「成员与角色」中更名为「成员管理」。
在成员管理模块，您可以查看通过列表查看成员的姓名、登录账号、帐号类型、角色、手机号、职务等信息，也可以操作添加成员、转交工作、重置成员账
号密码、编辑成员信息、删除成员等。
1.1. 添加成员
可以添加成员到神策系统中，一起进行数据监控、分析。
1.1.1. 添加「项目成员」
「项目成员」是指可以登录当前项目的成员账号。 只需在成员管理列表页点击「新建账号」，选择「项目帐号」，填写成员的登录账号、登录密码、员工姓
名、角色等信息即可成功添加一个成员。将账号和密码给对应成员，就可以登录使用神策系统了。
1.1.2. 添加「平台成员」
新增「平台成员」是全网唯一的帐号，可以被邀请登录企业任意项目。 只需在成员管理列表页点击「添加成员」，选择「平台帐号」，填写成员的登录账号、
登录密码、员工姓名、角色等信息即可成功添加一个成员。将账号和密码给对应成员，就可以登录使用神策系统了。 也可以点击「邀请」，将平台账号成员
直接邀请到当前项目中1.2. 邀请平台成员
新增「邀请平台成员」，点击成员管理列表上方的「邀请平台成员」，进入「授权平台帐号使用当前项目」列表，展示可以添加到当前项目的一网通成员，
点击「授权访问」，选择成员角色后，平台成员即可登录项目，进行数据监控，分析等操作。
授权平台账号访问当前项目时，可以选择在当前项目的角色。如平台账号成员使用过程中，，因为业务原因，权限需要调整，将成员添加到另一个角色中就可以了。
1.3. 转交工作
当成员离职、或不负责现在的工作时，点击列表中的「转交工作」，将成员创建的书签、概览批量转交给其他成员。
1.4. 重置成员账号密码
当成员密码遗失时，admin可以点击「重置密码」重新设置密码，同步给成员后，可继续使用神策分析系统。
1.5. 编辑成员信息
当成员信息有变动时，可以点击「编辑」，编辑员工姓名、手机号、邮箱地址、职务、角色等信息。 请注意，如果在项目中修改平台成员的角色，只在当前
项目生效。1.6. 删除成员
当成员离职等需要删除成员时，点击「删除」，即可立即删除成员。 请注意，若成员创建了书签、概览，需选择将书签、概览转交个其他成员后，才可以删
除帐号。
1.6. 职务管理
在「成员管理」中新增「职务管理」，可以填写使用神策分析的成员的职务，当创建成员时就可以直接选择具体职务了。
职务管理中可以选择创建成员时，职务是否需要必填；因为不同成员使用神策分析，需要关注的业务细节不同，建议创建成员时填写好职务，这样就可以在
分享概览设置时，按职务进行动态分享了。2. 角色管理
一个角色，就相当于一个权限包。管理员给每个成员创建帐号时，都需要选择成员的角色。我们支持根据需求自定义角色，并赋予他不同的权限。 例如管理
员角色，可以设置系统的基础信息，分析师角色仅可使用、查看系统。 「角色管理」原来在右上角身份信息（例如：分析师）下拉列表中，现挪到顶部导航
栏更多中的「成员与角色」中。
神策也支持根据业务需求自定义角色。点击「新建角色」，填写角色名称、适用范围、勾选需要的权限即可。2.1. 权限功能的灵活授权能力更加强大，可对概览、分析、元数据、预警管理、成员与角色等功
能模块的权限全面细分。
2.1.1. 数据分析模块权限
「可用事件」的权限 选择自定义授权时，新增「按标签动态授权」事件使用权限。例如：角色A的事件权限可以查看标签为app的所有事件，当新增
「app 注册」事件，「标签为app」，那么角色A可以查看「app 注册」事件相关的数据。 注：无论是元事件还是虚拟事件，都在此模块中进行授权。
例如：虚拟事件 A ，包括 a,b,c 三个元事件，当授权某个角色「虚拟事件 A 」时，在各个分析模型中可使用「虚拟事件 A 」，但 a,b,c 三个元事件
是不能使用的。
「可用事件属性」 在分析模型中，不可使用未授权的属性进行筛选、查看、group by。用户行为序列详情页均不显示未授权的信息。 「可用用户属
性」「可用用户群」 在分析模型中，不可使用未授权的属性进行筛选、查看、group by。用户列表和详情页均不显示此信息
2.1.2. 用户群模块权限
「查看用户群」权限，自定义授权时，支持设置指定可见/指定不可见的用户群的同时，新增设置「指定角色创建的用户群」是否可见，动态授权用
户群查看权限
2.1.2. 概览拆分为：查看我的概览、管理我的概览、查看公共概览、管理公共概览四个部分。
新增管理公共概览，可以将场景库中的场景创建为公共概览，也可以自己创建公共概览。
2.1.3. 漏斗权限细分：根据用户的使用，将漏斗权限拆分为：可用漏斗、管理漏斗两种。
可用漏斗：可以按「全部可用」、「admin创建」、「指定成员」三种情况，选择分析时可以使用哪些漏斗。
管理漏斗：用户可以在漏斗分析中，编辑、删除自己可以使用的漏斗。
只要有漏斗分析权限的用户，都可以自己创建、管理自己的漏斗。2.2. 默认增加「开发者」系统角色
当研发接入数据或者埋点时，需要使用埋点管理、元数据等功能查看埋点完成情况，但不需要使用其他业务功能时，可为其分配「开发者」的角色，如果此
系统角色不满足需要，也可新建一个「自定义角色」进行灵活授权。
3.2. 如果企业购买了「用户标签产品」、「智能推荐产品」则可配置对应的权限
3.2.1. 用户标签模块权限
新增用户标签模块权限，如果买用户画像系统，可以设置「用户标签」的查看、新建、管理、审核、标签结构管理权限
查看权限：点击编辑，可以设置允许查看的标签范围，支持选择全部标签、我创建的标签、自定义授权三种方式。其中自定义授权，支持设置指定
可见/指定不可见的用户群的；设置「指定角色创建的用户标签」是否可见，动态授权用户标签查看权限。
新建权限：是指可进行新建，并编辑、删除自己创建的数据。
管理权限：管理查看范围内的所有用户标签，包括「编辑」、「删除」、「重新计算」、「启停用」操作。当角色授权了「新建」权限后，管理权
限可根据业务，选择「查看范围内的所有」、「我创建的」标签两种权限范围。
审核权限：标签创建后，可以审核标签是否允许使用
标签结构管理权限：对所有的「标签树结构」和「标签的所属分类」进行分组排序管理。
3.2.2. 个性化推荐模块权限
如购买神策个性化推荐，尚未支持自定义权限配置的模块，新增「个性化推荐」的查看和管理权限。 方案一：支持查看所有推荐相关的数据；管理个性化推
荐的「内容库」「内容规则」「推荐规则」 方案二、三：支持查看所有推荐相关的数据；.权限管理 v1.13
神策分析提供了较为丰富的权限管理功能，在这里，我们对此做进一步的描述。
1. 账号体系
神策分析的账号一共可以分为三种不同的类型，分别是管理员、分析师和普通账号。在 1.7 版本以后，这三类账号各自具有如下的权限：
账 概览 概览查看权限 使用数据 可访问的 漏斗的限制 用户分群 事件和 账号管理 预 推 渠道
户 管理 分析功能 数据范围 用户属 警 送 链接
类 权限 性 管 管 管理
型 理 理
管理员 可以编 可以查看自己创建 可以 全部数据 允许新建、可查看/编辑所有漏斗 可以创建、 可以查看和 可以创建和删除账 可以 可以 可以
辑 、 和他人分享给自己 编辑和查看 编辑 号，
分享 的概览 可以分配分析师的可
访问数据范围
分析师 可以编 可以查看自己创建 可以 被授权的事 允许新建、可查看自己和管理员创建 可以查看 可以查看 无权限 无权限 无权限 无权限
辑 、 和他人分享给自己 件 的、仅可编辑自己创建的
分享 的概览
普通用 无权限 可以查看他人分享 不可以 不可直接访 不可新建、可查看TA人通过分享概览 无权限 无权限 无权限 无权限 无权限 无权限
户 给自己的概览 问数据 而来的漏斗分析
注：神策分析大于等于 1.10 的版本可以开启分析师角色“创建虚拟事件”、“创建分群”、“创建 Session”的权限，详情请咨询技术支
持；
注：如用户从Ta人分享的概览中查看某漏斗分析时，该用户可见详情。仅当此漏斗中包含的事件不在当前用户的使用权限范围内或被
隐藏时，系统将提示无法查看。
2. 账号管理
管理员账号在界面右上角，可以进入到“权限管理”功能：进入后的界面如下图所示：
在个界面，我们可以完成如下一些功能：
1. 创建一个新的账号；
2. 修改一个账号类型；
3. 修改一个账号的密码；
4. 删除一个账号。
3. 概览授权
管理员账号界面右上角，可以进入到“概览授权”功能，这个功能的界面如下图所示：在这里，管理员可以将自己创建的概览，授权给任意账号察看，可以选择授权给全部，可以选择只有自己可察看，也可以选择授权给具体的账号，如下图：
4. 分析师事件权限
管理员账号界面右上角，可以进入到“分析师权限”功能，这个功能：
在界面上可以完成如下操作：
1. 选择分析师可见的事件(可以多选)；
2. 点击保存完成选择；5. 修改密码
任何帐号点击右上角，选择修改密码，进入“修改密码”功能，这个功能的界面如下图所示：.权限管理 v1.14
为了更好的满足企业灵活的授权的业务场景，在SA1.14版本中增加了「角色管理」，并升级了「账号管理」模块。
Admin账号与授于「管理员」角色的成员，可点击顶部导航栏的个人头像，查看此菜单进行后续的操作。
1. 角色管理
点击进入角色管理后可见如下页面，1.14 版本中，提供两种类型的角色「系统角色」和「自定义角色」
在「系统角色中」是与以前版本一致的三种默认角色：「管理员」、「分析师」、「普通用户」。此类角色仅可复制，不允许编辑、删除。
「系统角色-管理员」的角色「系统角色-分析师」的角色「系统角色-普通用户」的角色
为了确保老用户可以平滑升级，如在老版本中，对不同分析师角色的成员额外设置可用事件的权限，那么在升级中，此类成员将分别自动转化成为一个自定
义角色存在。如果多个分析师角色的成员，设置的可用事件的权限是一样的，那么系统将默认将此类成员，转化到一个自定义角色中。
在「自定义角色」是允许企业创建新的角色，以便满足企业各种不同职务成员的工作诉求。更加专注自己的工作，并进一步保证企业数据的安全。点击每个
角色，可在右侧查看对应角色的具体授权内容，和被授予此角色的成员。
点击右上角的「新建角色」就可以开始「自定义角色」之旅。因为 SA1.14 版本中的角色权限，仅支持核心功能与数据的权限管控功能，所以剩余的尚未支持全自定义授权的模块，我们为大家提供了三种固定的授权方案。
在此特别说明。具体可授权的功能模块，将在下文中介绍。
从下图可见，新建角色一共分为三个部分，设置后点击保存即可。注：每个用户仅可分配一个角色。 第一部分【蓝框】 第二部分【红框】 第三部分【绿
框】 基本信息 自定义授权的模块与功能 尚未支持灵活授权的模块 角色名称：必填，不能重名
第一部分【蓝框】 第二部分【红框】 第三部分【绿框】
基本信息 自定义授权的模块与功能 尚未支持灵活授权的模块
角色名称：必填，不 数据权限：限制当前角色可查看的数据有哪些 需要为此部分的功能模块，选择我们提供的三
能重名 种固定「方案」
数据分析：在分析过程中是否可以使用「用户属性分析模型」、「查看用户列
说明 表」、「导出CSV」 具体功能请见下图。新建角色时，系统会默认
选择「方案一」
适用范围：使用此角 可以使用哪些事件进行分析（可用事件）、可以查看/禁止查看哪些属性（事件
色的成员有哪些 属性、用户属性、用户群、用户标签） 点击切换方案后，可查看对应的授权内容。
用户群：是否可使用「用户分群」这个模块，与此同时可授权用户是否有「新 通过以下方案，可满足管理者、分析师、普通
建」、「管理」的操作权限 成员的三种权限配置的诉求。
用户标签：是否可使用「用户标签」这个模块，并且可对「新建」、「管理」、
「审核」、「标签结构管理」进行分别授权。
自定义查询：是否允许使用「自定义查询功能」。注：此功能将可使用SQL查询
全部数据。
企业管理：是否可使用「虚拟事件管理」、「Session 管理」、「埋点管理」的
操作。注：管理包括新建、编辑、删除等功能。2. 账号管理
1.14版本中的账号管理，增加了「姓名」、「手机号」、「职务」的信息录入，让每个成员的信息更加丰富。
系统默认 Admin 账号和具有管理员角色的成员，可进行重置密码的操作，为了确保 Admin 账号的安全，如需重置密码，需要输入原密码后进行修改。登录后
在账号管理列表中进行对应成员的重置密码操作。基础管理.基础管理 v1.13
1.15版本，新增「基础设置」模块，展示项目的成员数量、核数限额、已用数据量额度、当前内存、部署事件、到期时间、停止时间、连续服务时间等项目
基础信息。在这里，您可以操作修改项目名称等操作。
1. 编辑项目名称
点击「 」，可以根据您的业务修改项目名称。例如公司内部有两个完全独立的产品时，可以使用产品名作为项目名称，进行区分。2. 更新授权
当服务器「未开通」外网权限的用户使用到期后，神策工作人员会将新的 licence 文件发送给用户，用户在更新授权中上传文件即可继续使用神策 原右上角
点击账号名称，下拉列表中「关于」中的「授权更新」，已挪到基本设置中。3. 在线升级
神策分析为了提升用户体验，会迭代发布小版本，微调功能细节。小版本升级可以由神策系统用户在前端进行操作（但如无必要，不需要经常性进行小版本
升级）。原右上角点击账号名称，下拉列表中「关于」中的「在线升级」，已挪到基本设置中。 服务器「开通」外网权限的客户，可通过一键升级功能升级
神策系统。 点击「升级神策系统」进行升级，预计等待5分钟的时间，即可升级完成。服务器「未开通」外网权限的客户，需联系神策技术支持获取安装包和升级命令，然后在更新授权中上传升级包进行升级。 注意：升级过程中可能会对分析
页面查询短暂影响。 如遇查询报错，请稍后重试；升级操作中如遇问题，请联系神策技术支持协助您进行处理。
4. 重置项目
重置项目可以清空项目中 所有数据，包括所有行为事件、用户属性、书签、概览以及除 admin 外所有用户帐号。仅admin 可操作。原来需要在页面右上角
「用户名」的下拉菜单中点击进入「关于」页面里，点击「重置项目」，现在挪到了「基本设置」中。 点击并确认重置项目确定后，有大约 30 秒的处理时
间，处理结束后将跳转至登录界面。
重置后请使用 admin 账户登录，密码与重置前相同；
重置将清除 project 的所有数据，包括 admin 之外的其他所有用户；
当重置或删除项目达到一定次数，需要手动回收资源才能再次进行重置，回收资源请参考文档多项目管理工具使用说明；注意：该操作不可逆，请谨慎操作！！
5. 接入数据
接入数据页展示了各端埋点文档的入口，可以根据业务需求，查看对应端的接入文档。 上报数据给神策时，神策的数据接收地址需要点击「复制 http 数据
接收地址」进行获取
6. 管理推送App 消息推送是一种常用的运营手段，国内已有多家公司向 Android 和 iOS 开发者提供推送服务。神策分析 1.6 版本中提供了如下的方案，以便使用极光推
送和小米推送等第三方推送服务的开发者，能够将神策分析的分析结果同步到推送服务中，以便向定向的人群推送特定的消息，从而将用户行为分析能力与推
送服务结合，提高 App 的运营效果。
在神策分析中使用推送服务(以极光推送为例) 1）填写推送配置 开发在第三方推送平台注册了 App 后，使用管理员账户进入神策分析的推送服务管理界面。
新建推送服务，并选择第三方推送服务商，填入 App Key、Secret Key 等配置信息，特别地，开发者需要填写保存设备推送 ID 的 Profile 名称，如前文的
例子中，我们在 jgId 中保存极光推送 Android App 的设备推送 ID。
成功添加推送服务后，将可以使用该推送配置，在用户分群、留存用户分析等分析功能中使用消息推送功能。 2） 用户分群 在神策分析中，可以按照用户的
事件所体现的过往的行为特征和用户的 Profile 所体现的用户自然属性特征，来对整个用户群体进行分群。开发者可以根据分群结果，对群体中的用户推送消
息。如图，当用户编辑用户分群规则时，勾选推送渠道：当用户分群执行成功后，会自动在第三方推送渠道中为满足分群条件的用户标记 Tag，Tag 名称为用户分群的英文名。特别地，当开发者拥有多款 App 的多
个推送渠道时，可以同时将推送结果同步到多个推送渠道的 Tag 中。 3）第三方推送平台进行消息推送 开发者可以在第三方推送系统的后台，使用用户分群
的英文名对应的 Tag 进行消息推送，例如在极光推送中：更多关于如何使用神策分析用户分群，可以参考文档《用户分群》。 4）用户列表 在神策分析的各种数据分析功能中，都可以根据分析结果获取对应的用户
列表，如留存分析中，开发者可以获得第一天留存的用户列表：
在用户列表中，可以根据用户列表的生成规则创建用户分群，此时我们也可以为该分群配置消息推送：
进而，在用户分群执行成功后，开发者可以在第三方推送系统的后台使用用户分群的英文名对应的 Tag 进行消息推送。 5） 推送效果追踪 如前文所述，开
发者在 App 中集成第三方消息推送服务后，可以使用神策分析追踪推送效果。我们对一些常用的推送效果分析，做简单的介绍。 统计推送成功的用户数 可
以直接在事件分析中，统计 App 消息推送成功 事件的触发用户数，并筛选对应的消息唯一 ID 属性。 分析推送成功的用户的转化 想查看某一段时间内，推
送成功的用户的转化，可以在漏斗分析中新建漏斗，第一个步骤为 App 消息推送成功，第二个步骤为下订单等行为。 *分析推送成功的用户的留存 想查看某
一段时间内，推送成功的用户的留存，可以在留存分析中，把初始行为设置为 App 消息推送成功，后续行为设置为 任意事件，或者某个表示用户留存的核
心行为。
7. API_SECRET
$API_SECRET 用于认证，使用 admin 账户登录系统之后，由原来的右上角点击用户名，点击「权限管理」界面获取（如果是 1.11 及之前的旧版本没有这
个界面，请联系技术支持人员获取），挪到了「基础设置」中，修改 admin 帐号的密码会使 API Secret 发生改变。
1.11 以及之前的系统版本，默认项目的 API Secret 可以访问任意项目的数据；非默认项目的 API Secret 仅能访问该项目的数据； 1.12 版本以及
之后的版本，所有项目的 API Secret 仅能访问该项目的数据。
API Secret 和导入数据使用的 Token 没有任何关联。.基本设置 v1.16
「基本设置」模块，展示项目的成员数量、核数限额、已用数据量额度、当前内存、部署事件、到期时间、停止时间、连续服务时间等项目基础信息。在这
里，您可以操作修改项目名称等操作。
1. 编辑项目名称
点击「 」，可以根据您的业务修改项目名称。例如公司内部有两个完全独立的产品时，可以使用产品名作为项目名称，进行区分。2. 更新授权
当服务器「未开通」外网权限的用户使用到期后，神策工作人员会将新的 licence 文件发送给用户，用户在更新授权中上传文件即可继续使用神策 原右上角
点击账号名称，下拉列表中「关于」中的「授权更新」，已挪到基本设置中。3. 在线升级
神策分析为了提升用户体验，会迭代发布小版本，微调功能细节。小版本升级可以由神策系统用户在前端进行操作（但如无必要，不需要经常性进行小版本
升级）。原右上角点击账号名称，下拉列表中「关于」中的「在线升级」，已挪到基本设置中。 服务器「开通」外网权限的客户，可通过一键升级功能升级
神策系统。 点击「升级神策系统」进行升级，预计等待5分钟的时间，即可升级完成。服务器「未开通」外网权限的客户，需联系神策技术支持获取安装包和升级命令，然后在更新授权中上传升级包进行升级。 注意：升级过程中可能会对分析
页面查询短暂影响。 如遇查询报错，请稍后重试；升级操作中如遇问题，请联系神策技术支持协助您进行处理。
4. 重置项目
重置项目可以清空项目中 所有数据，包括所有行为事件、用户属性、书签、概览以及除 admin 外所有用户帐号。仅admin 可操作。原来需要在页面右上角
「用户名」的下拉菜单中点击进入「关于」页面里，点击「重置项目」，现在挪到了「基本设置」中。 点击并确认重置项目确定后，有大约 30 秒的处理时
间，处理结束后将跳转至登录界面。
重置后请使用 admin 账户登录，密码与重置前相同；
重置将清除 project 的所有数据，包括 admin 之外的其他所有用户；
当重置或删除项目达到一定次数，需要手动回收资源才能再次进行重置，回收资源请参考文档多项目管理工具使用说明；注意：该操作不可逆，请谨慎操作！！
5. 接入数据
接入数据页展示了各端埋点文档的入口，可以根据业务需求，查看对应端的接入文档。 上报数据给神策时，神策的数据接收地址需要点击「复制 http 数据
接收地址」进行获取
6. 管理推送App 消息推送是一种常用的运营手段，国内已有多家公司向 Android 和 iOS 开发者提供推送服务。神策分析 1.6 版本中提供了如下的方案，以便使用极光推
送和小米推送等第三方推送服务的开发者，能够将神策分析的分析结果同步到推送服务中，以便向定向的人群推送特定的消息，从而将用户行为分析能力与推
送服务结合，提高 App 的运营效果。
在神策分析中使用推送服务(以极光推送为例) 1）填写推送配置 开发在第三方推送平台注册了 App 后，使用管理员账户进入神策分析的推送服务管理界面。
新建推送服务，并选择第三方推送服务商，填入 App Key、Secret Key 等配置信息，特别地，开发者需要填写保存设备推送 ID 的 Profile 名称，如前文的
例子中，我们在 jgId 中保存极光推送 Android App 的设备推送 ID。
成功添加推送服务后，将可以使用该推送配置，在用户分群、留存用户分析等分析功能中使用消息推送功能。 2） 用户分群 在神策分析中，可以按照用户的
事件所体现的过往的行为特征和用户的 Profile 所体现的用户自然属性特征，来对整个用户群体进行分群。开发者可以根据分群结果，对群体中的用户推送消
息。如图，当用户编辑用户分群规则时，勾选推送渠道：当用户分群执行成功后，会自动在第三方推送渠道中为满足分群条件的用户标记 Tag，Tag 名称为用户分群的英文名。特别地，当开发者拥有多款 App 的多
个推送渠道时，可以同时将推送结果同步到多个推送渠道的 Tag 中。 3）第三方推送平台进行消息推送 开发者可以在第三方推送系统的后台，使用用户分群
的英文名对应的 Tag 进行消息推送，例如在极光推送中：更多关于如何使用神策分析用户分群，可以参考文档《用户分群》。 4）用户列表 在神策分析的各种数据分析功能中，都可以根据分析结果获取对应的用户
列表，如留存分析中，开发者可以获得第一天留存的用户列表：
在用户列表中，可以根据用户列表的生成规则创建用户分群，此时我们也可以为该分群配置消息推送：
进而，在用户分群执行成功后，开发者可以在第三方推送系统的后台使用用户分群的英文名对应的 Tag 进行消息推送。 5） 推送效果追踪 如前文所述，开
发者在 App 中集成第三方消息推送服务后，可以使用神策分析追踪推送效果。我们对一些常用的推送效果分析，做简单的介绍。 统计推送成功的用户数 可
以直接在事件分析中，统计 App 消息推送成功 事件的触发用户数，并筛选对应的消息唯一 ID 属性。 分析推送成功的用户的转化 想查看某一段时间内，推
送成功的用户的转化，可以在漏斗分析中新建漏斗，第一个步骤为 App 消息推送成功，第二个步骤为下订单等行为。 *分析推送成功的用户的留存 想查看某
一段时间内，推送成功的用户的留存，可以在留存分析中，把初始行为设置为 App 消息推送成功，后续行为设置为 任意事件，或者某个表示用户留存的核
心行为。
7. API_SECRET
$API_SECRET 用于认证，使用 admin 账户登录系统之后，由原来的右上角点击用户名，点击「权限管理」界面获取（如果是 1.11 及之前的旧版本没有这
个界面，请联系技术支持人员获取），挪到了「基础设置」中，修改 admin 帐号的密码会使 API Secret 发生改变。
1.11 以及之前的系统版本，默认项目的 API Secret 可以访问任意项目的数据；非默认项目的 API Secret 仅能访问该项目的数据； 1.12 版本以及
之后的版本，所有项目的 API Secret 仅能访问该项目的数据。
API Secret 和导入数据使用的 Token 没有任何关联。
8. 数据校验
当全部埋点都开发完成并有数据上报后，你可以上传《事件设计》，校验研发埋点的数据质量。
可校验《事件设计》完整度，以及上报的属性值空值率、未上报率两个维度。
可校验《事件设计》完整度支持按 sdk 类型 校验事件、事件属性、用户属性是否有新增、或缺失；事件属性、用户属性属性类型是否正确；
上报的属性值空值率、未上报率包含：统计时间内，按 sdk 类型抽样校验，事件属性、用户属性的属性值空值率、未上报率是多少，当大于60%时
建议查看是否有异常情况。9. 资源使用报告
资源使用报告中包含企业使用神策的基础数据，比如导入了多少数据、有多少人在使用神策分析等，帮助企业了解自己成员在神策分析上的使用情况。仅管
理员角色的成员可见此功能，每日在概览计算后，会定时计算过去30天（不含今日）的统计数据。
10. 平台安全设置
可自定义账号被锁定的激发次数、新建账号时是否须为邮箱格式，满足企业个性化安全需求 。小版本升级.小版本升级 v1.13
1. 登录环境
admin“”
2. 点击关于
“”3. 选择在线升级
“”
4. 升级神策系统
“”5. 等待升级完成
5.小版本升级 v1.17
登录环境
admin“”
点击基本设置
升级神策系统
“”等待升级完成
5.基本设置 v1.17
1. 概述
「基本设置」模块，展示项目的成员数量、核数限额、已用数据量额度、当前内存、部署事件、到期时间、停止时间、连续服务时间等项目基础信息。在这
里，您可以操作修改项目名称等操作。
2. 编辑项目名称
点击「 」，可以根据您的业务修改项目名称。例如公司内部有两个完全独立的产品时，可以使用产品名作为项目名称，进行区分。3. 更新授权
当服务器「未开通」外网权限的用户使用到期后，神策工作人员会将新的 licence 文件发送给用户，用户在更新授权中上传文件即可继续使用神策 原右上角
点击账号名称，下拉列表中「关于」中的「授权更新」，已挪到基本设置中。4. 在线升级
神策分析为了提升用户体验，会迭代发布小版本，微调功能细节。小版本升级可以由神策系统用户在前端进行操作（但如无必要，不需要经常性进行小版本
升级）。原右上角点击账号名称，下拉列表中「关于」中的「在线升级」，已挪到基本设置中。 服务器「开通」外网权限的客户，可通过一键升级功能升级
神策系统。 点击「升级神策系统」进行升级，预计等待5分钟的时间，即可升级完成。服务器「未开通」外网权限的客户，需联系神策技术支持获取安装包和升级命令，然后在更新授权中上传升级包进行升级。 注意：升级过程中可能会对分析
页面查询短暂影响。 如遇查询报错，请稍后重试；升级操作中如遇问题，请联系神策技术支持协助您进行处理。
5. 重置项目
重置项目可以清空项目中 所有数据，包括所有行为事件、用户属性、书签、概览以及除 admin 外所有用户帐号。仅admin 可操作。原来需要在页面右上角
「用户名」的下拉菜单中点击进入「关于」页面里，点击「重置项目」，现在挪到了「基本设置」中。 点击并确认重置项目确定后，有大约 30 秒的处理时
间，处理结束后将跳转至登录界面。
重置后请使用 admin 账户登录，密码与重置前相同；
重置将清除 project 的所有数据，包括 admin 之外的其他所有用户；
当重置或删除项目达到一定次数，需要手动回收资源才能再次进行重置，回收资源请参考文档多项目管理工具使用说明；注意：该操作不可逆，请谨慎操作！！
6. 接入数据
接入数据页展示了各端埋点文档的入口，可以根据业务需求，查看对应端的接入文档。 上报数据给神策时，神策的数据接收地址需要点击「复制 http 数据
接收地址」进行获取
7. 管理推送
App 消息推送是一种常用的运营手段，国内已有多家公司向 Android 和 iOS 开发者提供推送服务。神策分析 1.6 版本中提供了如下的方案，以便使用极光推
送和小米推送等第三方推送服务的开发者，能够将神策分析的分析结果同步到推送服务中，以便向定向的人群推送特定的消息，从而将用户行为分析能力与推
送服务结合，提高 App 的运营效果。在神策分析中使用推送服务(以极光推送为例) 1）填写推送配置 开发在第三方推送平台注册了 App 后，使用管理员账户进入神策分析的推送服务管理界面。
新建推送服务，并选择第三方推送服务商，填入 App Key、Secret Key 等配置信息，特别地，开发者需要填写保存设备推送 ID 的 Profile 名称，如前文的
例子中，我们在 jgId 中保存极光推送 Android App 的设备推送 ID。
成功添加推送服务后，将可以使用该推送配置，在用户分群、留存用户分析等分析功能中使用消息推送功能。 2） 用户分群 在神策分析中，可以按照用户的
事件所体现的过往的行为特征和用户的 Profile 所体现的用户自然属性特征，来对整个用户群体进行分群。开发者可以根据分群结果，对群体中的用户推送消
息。如图，当用户编辑用户分群规则时，勾选推送渠道：当用户分群执行成功后，会自动在第三方推送渠道中为满足分群条件的用户标记 Tag，Tag 名称为用户分群的英文名。特别地，当开发者拥有多款 App 的多
个推送渠道时，可以同时将推送结果同步到多个推送渠道的 Tag 中。 3）第三方推送平台进行消息推送 开发者可以在第三方推送系统的后台，使用用户分群
的英文名对应的 Tag 进行消息推送，例如在极光推送中：更多关于如何使用神策分析用户分群，可以参考文档《用户分群》。 4）用户列表 在神策分析的各种数据分析功能中，都可以根据分析结果获取对应的用户
列表，如留存分析中，开发者可以获得第一天留存的用户列表：
在用户列表中，可以根据用户列表的生成规则创建用户分群，此时我们也可以为该分群配置消息推送：
进而，在用户分群执行成功后，开发者可以在第三方推送系统的后台使用用户分群的英文名对应的 Tag 进行消息推送。 5） 推送效果追踪 如前文所述，开
发者在 App 中集成第三方消息推送服务后，可以使用神策分析追踪推送效果。我们对一些常用的推送效果分析，做简单的介绍。 统计推送成功的用户数 可
以直接在事件分析中，统计 App 消息推送成功 事件的触发用户数，并筛选对应的消息唯一 ID 属性。 分析推送成功的用户的转化 想查看某一段时间内，推
送成功的用户的转化，可以在漏斗分析中新建漏斗，第一个步骤为 App 消息推送成功，第二个步骤为下订单等行为。 *分析推送成功的用户的留存 想查看某
一段时间内，推送成功的用户的留存，可以在留存分析中，把初始行为设置为 App 消息推送成功，后续行为设置为 任意事件，或者某个表示用户留存的核
心行为。
8. API_SECRET
$API_SECRET 用于认证，使用 admin 账户登录系统之后，由原来的右上角点击用户名，点击「权限管理」界面获取（如果是 1.11 及之前的旧版本没有这
个界面，请联系技术支持人员获取），挪到了「基础设置」中，修改 admin 帐号的密码会使 API Secret 发生改变。
1.11 以及之前的系统版本，默认项目的 API Secret 可以访问任意项目的数据；非默认项目的 API Secret 仅能访问该项目的数据； 1.12 版本以及
之后的版本，所有项目的 API Secret 仅能访问该项目的数据。
API Secret 和导入数据使用的 Token 没有任何关联。
9. 数据校验
当全部埋点都开发完成并有数据上报后，你可以上传《数据采集方案》，校验研发埋点的数据质量。
可校验《数据采集方案》完整度，以及上报的属性值空值率、未上报率两个维度。
可校验《数据采集方案》完整度支持按 sdk 类型 校验事件、事件属性、用户属性是否有新增、或缺失；事件属性、用户属性属性类型是否正确；
上报的属性值空值率、未上报率包含：统计时间内，按 sdk 类型抽样校验，事件属性、用户属性的属性值空值率、未上报率是多少，当大于60%时
建议查看是否有异常情况。
10. 资源使用报告
资源使用报告中包含企业使用神策的基础数据，比如导入了多少数据、有多少人在使用神策分析等，帮助企业了解自己成员在神策分析上的使用情况。仅管
理员角色的成员可见此功能，每日在概览计算后，会定时计算过去30天（不含今日）的统计数据。11. 平台安全设置
可自定义账号被锁定的激发次数、新建账号时是否须为邮箱格式，满足企业个性化安全需求 。.基础管理 v1.14.基本设置 v1.15
1.15版本，新增「基本设置」模块，展示项目的成员数量、核数限额、已用数据量额度、当前内存、部署事件、到期时间、停止时间、连续服务时间等项目
基础信息。在这里，您可以操作修改项目名称等操作。
1. 编辑项目名称
点击「 」，可以根据您的业务修改项目名称。例如公司内部有两个完全独立的产品时，可以使用产品名作为项目名称，进行区分。2. 更新授权
当服务器「未开通」外网权限的用户使用到期后，神策工作人员会将新的 licence 文件发送给用户，用户在更新授权中上传文件即可继续使用神策 原右上角
点击账号名称，下拉列表中「关于」中的「授权更新」，已挪到基本设置中。3. 在线升级
神策分析为了提升用户体验，会迭代发布小版本，微调功能细节。小版本升级可以由神策系统用户在前端进行操作（但如无必要，不需要经常性进行小版本
升级）。原右上角点击账号名称，下拉列表中「关于」中的「在线升级」，已挪到基本设置中。 服务器「开通」外网权限的客户，可通过一键升级功能升级
神策系统。 点击「升级神策系统」进行升级，预计等待5分钟的时间，即可升级完成。服务器「未开通」外网权限的客户，需联系神策技术支持获取安装包和升级命令，然后在更新授权中上传升级包进行升级。 注意：升级过程中可能会对分析
页面查询短暂影响。 如遇查询报错，请稍后重试；升级操作中如遇问题，请联系神策技术支持协助您进行处理。
4. 重置项目
重置项目可以清空项目中 所有数据，包括所有行为事件、用户属性、书签、概览以及除 admin 外所有用户帐号。仅admin 可操作。原来需要在页面右上角
「用户名」的下拉菜单中点击进入「关于」页面里，点击「重置项目」，现在挪到了「基本设置」中。 点击并确认重置项目确定后，有大约 30 秒的处理时
间，处理结束后将跳转至登录界面。
重置后请使用 admin 账户登录，密码与重置前相同；
重置将清除 project 的所有数据，包括 admin 之外的其他所有用户；
当重置或删除项目达到一定次数，需要手动回收资源才能再次进行重置，回收资源请参考文档多项目管理工具使用说明；注意：该操作不可逆，请谨慎操作！！
5. 接入数据
接入数据页展示了各端埋点文档的入口，可以根据业务需求，查看对应端的接入文档。 上报数据给神策时，神策的数据接收地址需要点击「复制 http 数据
接收地址」进行获取
6. 管理推送App 消息推送是一种常用的运营手段，国内已有多家公司向 Android 和 iOS 开发者提供推送服务。神策分析 1.6 版本中提供了如下的方案，以便使用极光推
送和小米推送等第三方推送服务的开发者，能够将神策分析的分析结果同步到推送服务中，以便向定向的人群推送特定的消息，从而将用户行为分析能力与推
送服务结合，提高 App 的运营效果。
在神策分析中使用推送服务(以极光推送为例) 1）填写推送配置 开发在第三方推送平台注册了 App 后，使用管理员账户进入神策分析的推送服务管理界面。
新建推送服务，并选择第三方推送服务商，填入 App Key、Secret Key 等配置信息，特别地，开发者需要填写保存设备推送 ID 的 Profile 名称，如前文的
例子中，我们在 jgId 中保存极光推送 Android App 的设备推送 ID。
成功添加推送服务后，将可以使用该推送配置，在用户分群、留存用户分析等分析功能中使用消息推送功能。 2） 用户分群 在神策分析中，可以按照用户的
事件所体现的过往的行为特征和用户的 Profile 所体现的用户自然属性特征，来对整个用户群体进行分群。开发者可以根据分群结果，对群体中的用户推送消
息。如图，当用户编辑用户分群规则时，勾选推送渠道：当用户分群执行成功后，会自动在第三方推送渠道中为满足分群条件的用户标记 Tag，Tag 名称为用户分群的英文名。特别地，当开发者拥有多款 App 的多
个推送渠道时，可以同时将推送结果同步到多个推送渠道的 Tag 中。 3）第三方推送平台进行消息推送 开发者可以在第三方推送系统的后台，使用用户分群
的英文名对应的 Tag 进行消息推送，例如在极光推送中：更多关于如何使用神策分析用户分群，可以参考文档《用户分群》。 4）用户列表 在神策分析的各种数据分析功能中，都可以根据分析结果获取对应的用户
列表，如留存分析中，开发者可以获得第一天留存的用户列表：
在用户列表中，可以根据用户列表的生成规则创建用户分群，此时我们也可以为该分群配置消息推送：
进而，在用户分群执行成功后，开发者可以在第三方推送系统的后台使用用户分群的英文名对应的 Tag 进行消息推送。 5） 推送效果追踪 如前文所述，开
发者在 App 中集成第三方消息推送服务后，可以使用神策分析追踪推送效果。我们对一些常用的推送效果分析，做简单的介绍。 统计推送成功的用户数 可
以直接在事件分析中，统计 App 消息推送成功 事件的触发用户数，并筛选对应的消息唯一 ID 属性。 分析推送成功的用户的转化 想查看某一段时间内，推
送成功的用户的转化，可以在漏斗分析中新建漏斗，第一个步骤为 App 消息推送成功，第二个步骤为下订单等行为。 *分析推送成功的用户的留存 想查看某
一段时间内，推送成功的用户的留存，可以在留存分析中，把初始行为设置为 App 消息推送成功，后续行为设置为 任意事件，或者某个表示用户留存的核
心行为。
7. API_SECRET
$API_SECRET 用于认证，使用 admin 账户登录系统之后，由原来的右上角点击用户名，点击「权限管理」界面获取（如果是 1.11 及之前的旧版本没有这
个界面，请联系技术支持人员获取），挪到了「基础设置」中，修改 admin 帐号的密码会使 API Secret 发生改变。
1.11 以及之前的系统版本，默认项目的 API Secret 可以访问任意项目的数据；非默认项目的 API Secret 仅能访问该项目的数据； 1.12 版本以及
之后的版本，所有项目的 API Secret 仅能访问该项目的数据。
API Secret 和导入数据使用的 Token 没有任何关联。个人中心.个人中心 v1.13
1.15版本新增「个人中心」 点击右上角账号名称处，可以查看个人的帐号名、手机号、登录账号、角色、邮箱等基础信息，也可以查看自己在数据权限、数
据分析、用户群、自定义查询、企业管理、概览、预置概览模块的权限明细。 当不能查看某些数据、或不能使用某个功能时，可以查看个人中心的权限明细，
确认是否有查看、使用权限。.个人中心 v1.17
在导航的最右侧点击账号名称后打开下拉气泡，点击「个人中心」进入当前用户自己的信息中心。
1. 查看入口
2. 基本信息与权限明细
后可查看个人的帐号名、手机号、登录账号、角色、邮箱等基础信息
也可以查看自己在数据权限、数据分析、用户群、自定义查询、企业管理、概览、预置概览模块的权限明细。 当不能查看某些数据、或不能使用某个功能
时，可以查看个人中心的权限明细，确认是否有查看、使用权限。
3. 操作日志
操作日志则记录了所有成员在神策平台上近 90 天的所有登录、查询、浏览、权限变更等明细日志。同时支持按照操作事件、操作类型、涉及模块进行快捷
筛选。通知助手.通知助手 v1.17
为了让用户在「概览协作」、「文件下载」、「查询结果」三个方面有更及时的信息通知，我们提供了「通知助手」的功能。
通知主 通知内容
题
概览协 共享给我的概览通知
作
共享给我的概览停止共享
分析查 在分析查询中，对于超过 10 s 的大数据量查询可添加到「查询队列」中，后台查询完成后，用户在「通知助手」收到通知并可点击查看计算
询 结果。
生成文 大数据量的文件生成类型的查询将按照异步进行，保证文件生成的完整性，并不阻碍用户使用。
件
文件生成完成后，用户在「通知助手」收到通知，可直接点击下载 Excel 文件。辅助功能.辅助功能 v1.13
搜索用户
掌上神策分析
维度字典
查 询 抽 样
正则表达式
推荐分享
使用 SQL 创建用户标签搜索用户.搜索用户 v1.15
1.11 及其以后版本，提供了搜索用户功能，支持直接输入用户 ID、属性值等搜索用户并查看列表，可以更便捷地找到特定用户，查看用户行为序列。
快捷键：
进入搜索：Ctrl (Command )-K；
退出搜索：Esc；
搜索用户功能简介
点击主界面中右上角的“搜索用户”（或通过快捷键），进入搜索：
点击 A 处，可按用户属性搜索用户，例如可以按省份搜索用户，输入“河北”，可以搜索出“省份”属性值为“河北省”的用户，默认展示 20 个用户；
点击 B 处，可以查看具体某一个用户的用户行为序列（显示为匿名 ID）；
点击 C 处，可以查看所有按“河北”搜索的用户；支持精确搜索和模糊搜索。只支持精确搜索的属性，输入框中会提示：“请输入完整的...”；
模糊搜索无需输入完整结果，如下图，按“城市”搜索用户，输入“北”，可搜索出的用户属性“城市”名都含“北”字；
搜索的属性数据类型为数值型时，仅支持精确搜索，不支持模糊搜索；掌上神策分析.掌上神策分析 v1.13
掌上神策分析是神策数据推出的神策分析移动版，主要提供数据指标的展示和数据异常的报告功能。
1. 登录
1.1. 应用下载和安装
Android 在应用宝搜索"掌上神策"进行下载安装；
iOS 用户在 App Store 搜索"掌上神策"进行下载安装。
点击下载
1.2. 注册和登录
使用账号密码登录
在掌上神策 app 内，使用账号密码进行登录使用扫描二维码登录
在电脑端登录神策分析平台，在顶部导航区域，点击“掌上神策”按钮，使用掌上神策 app 扫描二维码进行登录登录成功后即可进入 app ，进行数据的浏览和分析报告的查看。
登录异常
请尝试以下几种方案后再进行尝试
检查手机的网络环境，是否与电脑端在同一环境中，若您的网站是内网，那么是需要手机连接的网络可以访问内网
重新点击“掌上神策”按钮，生成新的二维码后，使用 app 进行扫码登录
1.3. 退出登录
在个人中心中，点击退出可进行账号的退出。2. 概览
2.1. 浏览概览
概览中的数据内容是与网页端账户同步的，若需要修改查看的数据指标，请在网页端进行配置修改；
暂时不支持时间范围的修改。切换概览
点击左上角更多按钮，可以进行概览的切换。
刷新概览
下拉整个概览页面，可以进行概览的刷新。2.2. 关注概览
概览的订阅
点击关注按钮，进行概览的订阅。 订阅成功后，次日会生成分析报告，并推送到您的手机上。3. 策报
策报的内容主要是使用自然语言，解读您配置的数据指标，目前支持事件分析类的指标。
指标的计算
如果配置的指标是按照合计进行查看，则会计算出指标的同环比数据变化，将变化幅度较大的指标排在前面进行展示；
如果配置的指标时按照某个维度进行分组的，则会计算出该维度下每个属性的值的变化幅度，将变化幅度最大的分组展示出来。
3.1. 策报列表
每日 9:00 系统会进行策报的推送，推送的内容为您关注的概览。3.2. 策报详情
每份关注的概览会生成一份报告。
报告中暂时只支持对事件分析的指标进行指标解读，系统会依照配置的指标，按照规则进行计算，给出数据的波动结果。
基础的计算规则为：
当配置的指标不存在分组时，计算指标整体的环比、同比波动数值
当配置的指标存在分组时，计算指标中每个分组的环比、同比波动数值，以及根据每个分组的占比，判断出波动最为明显的分组
策报会根据指标的整体波动大小进行排序，当波动值超过10%时，会被认为是明显波动；波动值在5%至10%之间会被认为是轻微波动；
低于5%则是平稳。详细信息 有分组的指标可以进行每个分组的详细信息展示
求分析 点击求分析后会引用该条数据的解读内容进行评论，在底部的评论区会以留言的形式展示，方便概览的配置者关注该概览中的问题点赞： 点击点赞按钮会对该指标进行点赞
评论： 在报告底部有评论的按钮，可以行评论留言维度字典.维度字典 v1.13
1. 什么是“维度字典”
针对已经存在的事件属性和用户属性，可以上传属性值的自定义映射关联。 在过滤，分组中可以使用带有维度字典的属性。如下图所示，维度字典的属性右
侧会有字典标示，屏幕宽度，操作系统版本，性别都是有维度字典的属性。2. 使用示例2.1. 界面上传维度字典
点击页面左下角的元数据，可以在用户属性页面和事件属性页面上传属性的维度字典。
首先建立维度字典，字典命名加上 .txt 后缀。
支持上图所示的分隔方式，选择的分隔符样式必须和维度字典中分隔符一致。分隔符左边是原始值，右边是替换的值。注意：字典中的分隔符样式
都要使用英文的分隔符。同时字典每一行分隔符左边不要出现和分隔符相同的字符。这里因为维度字典每一行用","分隔，所以分隔符样式选择","。
640,a
1080,b
1920,c
2048,d
1.浏览属性页面
如下图所示，只有文本类型和数值类型的属性可以上传维度字典，点击按钮可上传。
2.上传维度字典上传可以选择新增上传，现有的字典会保留。覆盖会清空之前的字典再上传。点击确认开始上传。
注意：维度字典
（神策分析 1.12 版本之前）是一对一映射，即逗号的左边列和右边列的取值都必须是唯一的。
（神策分析 1.12 及版本之后）维度字典支持多对一，针对已经存在的事件属性和用户属性，可以上传属性值的自定义多对一映射关系。
3.清空维度字典所有有维度字典的属性右侧会出现删除按钮，表示可以清除维度字典。
2.2. 上传维度字典api
通过发送 http post 请求［/property/dict/upload］，可以上传字符串类型或数值类型属性的维度字典。
Parameters
propertyName: 上传的属性名，必须是已有属性的属性名，比如 $os_version, Gender
type: 上传的属性类型，property 或者 profile，表示是事件属性还是用户属性。
isIncrement: bool 类型，表示是否增量上传。false表示全量上传，会清空之前对应属性的字典再上传。true表示增量上传。
file: 上传一个属性的维度字典，最大不超过 100M。维度字典每行用逗号分隔，逗号左边是属性值，逗号右边是用户定义的属性值对应的
映射后的值。文件必须是 UTF-8 编码。
split: 可选参数，默认是逗号分隔。比如自定义字典使用“|“分割，则 split 值为“|“。
Response 200
比如用户要上传事件属性 $os_version 的维度字典，发送如下指令：
curl ''http://$WEB_URL/api/property/dict/upload?
project=$PROJECT_NAME&propertyName=$os_version&type=property&isIncrement=true&token=$API_SECRET'' -X POST -F
"file=@$PATH"替换 $WEB_URL, $PROJECT_NAME, $API_SECRET, $PATH 四个参数。$WEB_URL 是网站的 URL；$PROJECT_NAME 是 project名；
$API_SECRET 可以使用 admin 账号登录系统后，在账户管理界面获取；$PATH 是属性维度字典在本地的路径。
file:
8.1,
8.2,
8.0,
注意：维度字典
1.12
1.12
2.2.1. 2.3 下载维度字典
对于有维度字典的属性，可以下载已有的数据字典，默认保存为 txt 文件。
2.2.2. 2.4 筛选表达式
对于有维度字典的属性，不管是字符串类型还是数值类型，筛选条件都只有四类：
equal to/ does not equal to，表示等于/不等于
has value / has not value，表示有值/没值
2.2.3. 2.5 结果展示
以事件分析为例，获取2015-10-18至2015-10-20买入黄金的总次数，其中操作系统是第一版。因为操作系统版本是有维度字典的属性，过滤条件和结果
分组列表中，都是显示的用户定义后的值。对于字典中没有覆盖的值，会显示原来的值。在漏斗分析，留存分析等功能中，有维度字典的属性使用情况类
似。2.2.4. 2.6 清空维度字典
参数含义和上传维度字典类似，比如要清空刚才上传的$os_version的维度字典，则执行下面的指令。
curl ''http://$WEB_URL/api/property/dict/empty?propertyName=$os_version&type=property&token=$AP查询抽样.查询抽样 v1.13
在神策分析 1.2 版本中，我们推出了查询抽样功能，用于在数据量较大时，可以抽取少量用户的数据来快速获取查询结果，快速验证猜想。
1. 使用方法
行为事件分析、漏斗分析、留存分析和分布分析都提供了查询抽样功能，如下图所示：
目前提供了从全量查询到对全量数据的1/64进行抽样的粒度，可以在实际查询时动态进行调整。
2. 抽样原理
抽样是按照神策分析系统内部的 user_id 来进行抽样的，在没有 track_signup 的情况下，它是对 distinct_id 取 hash 的结果，在有 track_signup 的情况
下，是以较早的 distinct_id 为准进行计算的。
在进行 1/8 抽样的情况下，就是对根据 user_id 取模的结果，从所有用户中抽出 1/8 的用户的数据来进行查询，并根据这个查询结果反推出展现给使用者的
值。例如，假设某个产品，目前一共有 100 万个用户，某一天某个事件的全量查询 PV 是 123456，而在进行 1/8 抽样时，我们是从这 100 万个用户中根据
user_id值来取出大约 1/8 的用户的数据，然后发现这些用户里面在这一天这个事件的 PV 是 13500，因此，实际展现给使用值的最终的查询结果就是13500
* 8 = 108000，与真实的全量查询是略有出入的。
查询如下几个指标时，不会对查询结果乘以抽样比例的倒数（例如，1/8 抽样时，结果不会乘以 8）：
人均次数（某个事件的人均触发次数）
人均值（某个数字类型属性的人均值）
最大值（某个数字类型属性的最大值）
最小值（某个数字类型属性的最小值）
人均 Session 次数
3. 使用场景正如前面所描述的那样，查询抽样反推出来的结果和真实的全量查询结果会有出入，而且用户规模越大，数据分布越均匀，这个出入就会越小。当然，如果
只是关注数据趋势，则在少部分用户群上做查询抽样，则查询抽样带来的误差通常就没那么重要了。
所以说，查询抽样主要是在数据量很大的情况下，单次查询速度很慢，则通过查询抽样来选择少部分用户的数据来快速验证猜想，观察趋势。在最终确定要
关注和考核的具体指标时，则可以选择全量查询来获取精确的数值。正则表达式.正则表达式 v1.13
神策分析各项功能均支持正则表达式，用户可以利用正则表达式进行灵活的属性筛选。
正则表达式是对字符串进行操作的一种逻辑公式，就是用事先定义好的一些特定字符、及这些特定字符的组合，组成一个“规则字符串”，这个“规则字符串”
用来表达对字符串的一种过滤逻辑。
例子
神策官网设有 文档 频道，该频道下的页面地址示例如下：
介绍页面：https://www.sensorsdata.cn/manual/
功能介绍：https://www.sensorsdata.cn/manual/features.html
事件分析：https://www.sensorsdata.cn/manual/event_ana.html
可以看到，文档频道下的页面地址有个规律，即均以https://www.sensorsdata.cn/manual/ 开头。
所以，当我们想要看文档频道下的整体页面浏览数时，可用如下用正则表达式进行匹配:
/manual/.*
正则表达式语法
上述表达式中的.和*是正则表达式中所使用的特殊字符中的两个。其他正则表达式字符释义如下：
通配符
字符 含义 示例
. 匹配任何单个字符 sens.ors 与 sensoors、sens8ors 匹配
* 匹配0个或多个先前项 默认的先前项是前一个字符。sens*ors与 senors、senssors 匹配
+ 与星号的用法一样，只不过加号至少必须匹配一个先前项 sens+ors 与 senssors 匹配，但是与 senors 不匹配
? 匹配0个或1个先前项 labou?r 与 labor 和 labour 匹配
执行“或”匹配 ab 匹配 a 或 b
定位符
字符 含义 示例
^ 要求您的数据位于字段开头 ^sensors 与 sensors 匹配，与 mysensors 不匹配
$ 要求您的数据位于字段末尾 sensors$ 与 sensors 匹配，与 sensorscan 不匹配
分组
字符 含义 示例
() 使用圆括号创建项，而不使用默认项 Thank(syou) 与 Thanks 和 Thankyou 都匹配
[] 使用方括号创建要匹配的项列表 [abc] 匹配a、b 和 c
- 使用方括号和短划线来扩展您的列表 [A-Z] 表示英语大写字母的列表
转义
字符 含义 示例\ 将正则表达式字符转换为普通字符 sensorsdata\.cn 这一表达式中的.不再是通配符.正则表达式 v1.17
神策分析各项功能均支持正则表达式，用户可以利用正则表达式进行灵活的属性筛选。
正则表达式是对字符串进行操作的一种逻辑公式，就是用事先定义好的一些特定字符、及这些特定字符的组合，组成一个“规则字符串”，这个“规则字符串”
用来表达对字符串的一种过滤逻辑。
例子
神策官网设有 文档 频道，该频道下的页面地址示例如下：
介绍页面：https://www.sensorsdata.cn/manual/
功能介绍：https://www.sensorsdata.cn/manual/features.html
事件分析：https://www.sensorsdata.cn/manual/event_ana.html
可以看到，文档频道下的页面地址有个规律，即均以https://www.sensorsdata.cn/manual/ 开头。
所以，当我们想要看文档频道下的整体页面浏览数时，可用如下用正则表达式进行匹配:
/manual/.*
正则表达式语法
上述表达式中的.和*是正则表达式中所使用的特殊字符中的两个。其他正则表达式字符释义如下：
通配符
字符 含义 示例
. 匹配任何单个字符 sens.ors 与 sensoors、sens8ors 匹配
* 匹配0个或多个先前项 默认的先前项是前一个字符。sens*ors与 senors、senssors 匹配
+ 与星号的用法一样，只不过加号至少必须匹配一个先前项 sens+ors 与 senssors 匹配，但是与 senors 不匹配
? 匹配0个或1个先前项 labou?r 与 labor 和 labour 匹配
执行“或”匹配 ab 匹配 a 或 b
定位符
字符 含义 示例
^ 要求您的数据位于字段开头 ^sensors 与 sensors 匹配，与 mysensors 不匹配
$ 要求您的数据位于字段末尾 sensors$ 与 sensors 匹配，与 sensorscan 不匹配
分组
字符 含义 示例
() 使用圆括号创建项，而不使用默认项 Thank(syou) 与 Thanks 和 Thankyou 都匹配
[] 使用方括号创建要匹配的项列表 [abc] 匹配a、b 和 c
- 使用方括号和短划线来扩展您的列表 [A-Z] 表示英语大写字母的列表
转义
字符 含义 示例\ 将正则表达式字符转换为普通字符 sensorsdata\.cn 这一表达式中的.不再是通配符
用户 ID 正则表达式
作用
在神策分析 1.17 及之后版本中，神策提供了可以通过设定上传数据时的 distinct_id 的值是否符合特定规则，限制上报的数据是否可以正常入库。该功能可
以有效的提升数据准确性，从根源解决错误数据上报入库的问题。
distinct_id 是神策数据上报时，标识用户的必要字段，distinct_id 取值规则分为「设备 ID」和「登录 ID」，具体取值规则可参考神策的用户标识文档。
注意：如果设置 distinct_id 的正则表达式规则错误，与实际上传数据的 distinct_id 值不符合，会导致数据无法入库。因此使用该功能时需谨慎操作。在使
用该功能之前，务必要和神策值班同学确认使用场景。
使用说明
神策支持多种数据导入来源，包含客户端 SDK、服务端 SDK、神策提供的各种导入工具导入数据。目前仅可以对客户端 SDK（包含 Android SDK、iOS
SDK、JS SDK、各种小程序 SDK) 以「设备 ID」标记的数据，和所有导入数据来源端以「登录 ID」标记的数据设置 distinct_id 的入库规则。
通常情况下，服务端 SDK 和神策提供的各种导入工具上传的数据，一般是以「登录 ID」上报的。对于没有设置「设备 ID」或「登录 ID」校验规则的来源端
数据，则可以直接入库。比如服务端 SDK 以一个「设备 ID」上传数据时，由于对服务端 SDK 没有设置「设备 ID」校验规则，则在满足其他数据检验格式
的情况下，数据可以直接入库。
常见的「设备 ID」和「登录 ID」正则表达式举例
下表根据神策客户端 SDK 常用的「设备 ID」样式和常见的「登录 ID」样式，举例写出对应的正则表达式。更多 ID 样式的正则表达式，请参考正则表达式
的规则介绍，自行实现。
客户端类型 ID ID 规则 ID 样式 ID 取值时机 ID 对应的正 各端 SDK 设备 ID/
分 则表达式 登录 ID正则表达式
类
Andr 正常是 16 位字符（0~9，a~f）(不排 774d56d682e549c Android SDK 默认的匿名 ^([0-9a-z]
oid 除少量手机供应商产生 15，14，13 ID {1,16})$
Android SDK ID 位的 Android ID ，因此本例中，暂定 ^([0-9a-z]{1,16})$|^
Android ID 字符个数为 1~16 位) ([0-9a-z]{8})(([/\s-]
[0-9a-z]{4}){3})([
UUID 8-4-4-4-12 每一位都是十六进制的数 550e8400-e29b- Android SDK ，在获取不 ^([0-9a-z]{8}) /\s-][0-9a-z]{12})$
字（0~9，a~f），只有小写字母 41d4-a716- 到 Android ID ，或者 (([/\s-][0-9a-
446655440000 Android SDK 在 1.10.5 z]{4}){3})([/\s-]
版本之前时，默认获取的匿 [0-9a-z]{12})$
名 ID
IDFA 8-4-4-4-12 每一位都是十六进制的数 DA067C52-8D48- iOS SDK 默认获取的匿名
字（0~9，A~F），只有大写字母 49CE-9500- ID
5A01368B8859 ^([0-9A-Z]{8})
(([/\s-][0-9A-
iOS SDK IDFV 8-4-4-4-12 每一位都是十六进制的数 DA067C52-8D48- iOS SDK ，在取不到 Z]{4}){3})([/\s-] ^([0-9A-Z]{8})(([/\s-
字（0~9，A~F），只有大写字母 49CE-9500- IDFA 时，尝试取 IDFV 作 [0-9A-Z]{12})$ ][0-9A-Z]{4}){3})([
5A01368B8859 为匿名 ID /\s-][0-9A-Z]{12})$
UUID 8-4-4-4-12 每一位都是十六进制的数 DA067C52-8D48- iOS SDK，在取不到
字（0~9，A~F），只有大写字母 49CE-9500- IDFA、IDFV 时，分配一个
5A01368B8859 UUID 作为匿名 ID
cooki n-n-n-n-n 共 5 段，每一位都是十 16e39c2c8b999e- 网页端默认的匿名 ID ^([0-9a-z]{5,})
e id 六进制的数字（0~9，a~f），n 的个 05ae1754c671f3- (([/\s-][0-9a-
JS SDK 数不固定（预计在 5~25 个） 38607701- z]{5,}){4})$ ^([0-9a-z]{5,})(([
2073600- /\s-][0-9a-z]{5,})
16e39c2c8ba85c {4})$
uuid 13-n-n-n （第一段是 13 位的时间 1558509239724- 所有小程序默认的匿名 ID ^([0-9]{13})(([
戳，后面 3 端位数不固定，均是数字 9278730- 为 uuid /\s-][0-9a-z]
小程序（各种小程序 和小写字母组成） 00c1875d5f63f8-
SDK ） {1,}){3})$
41373096 ^([0-9]{13})(([/\s-]
openid 小写字母 o 开头，由数字，大小写字 oB4nYjnoHhuWrPV 微信小程序可以设置使用 ^o[0-9a-zA- [0-9a-z]{1,}){3})$|^o
母，下划线，横杠组成，共 28 个字 i2pYLuPjnCaU0 openid 为匿名 ID [0-9a-zA-Z_-]
Z_-]{27}$
微信小程序 符 oB4nYjhJHQVaD0 {27}$|^o[0-9a-zA-
PL7qs0W1kL-_ls Z_-]{28}$
oB4nYjvY13SVtaW
C-AFztM2f3TlUunion 小写字母 o 开头，由数字，字母，下 oJeaRw70h8MKiI3I 用户可以获取 unionid 作为 ^o[0-9a-zA-
id 划线，横杠组成，共 29 个字符 QuFPJlsZzvTEF 微信小程序的匿名 ID 或者 Z_-]{28}$
微信小程序 登录 ID
纯 数 纯数字，由 0 递增（0~6666666） 12345 客户自定义的登录 ID 规则 ^\d+$ ( 验 证 纯 ^\d+$
字 登 数字字符串)
录 ID
^[0-9]*$ ( 验证
登录 ID（本文仅举例说明 纯数字字符串)
一些登录 ID 样式，具体
的规则请以业务中实际使 ^\d{n}$ ( 验 证
用的登录 ID 规则为准） n 位数字，n 输
入具体的值)
字母 数字+字母自由组合 u123f56 客户自定义的登录 ID 规则 ^[0-9a-zA-Z] ^[0-9a-zA-Z]{n,m}$
+ 数 {n,m}$
字 登
录 ID (n ~m 个数字、
字母组成的字符
串)
纯字 纯字母 qazwsx 客户自定义的登录 ID 规则 ^[a-zA-Z]{n, ^[a-zA-Z]{n,m}$
母的 m}$
登录
ID (n ~m 个字母组
成的字符串)
邮箱 邮箱（不包含中文字符的邮箱） shence@sensorsda 邮箱格式包含【（数字、大 ^([A-Za-z0- ^([A-Za-z0-9_\-\.])
作为 ta.cn 小写、下划线、横杠、点） 9_\-\.])+\@[a- +\@[a-zA-Z0-9_\-]
登录 @（数字、大小写、下划 zA-Z0-9_\-]+ +([a-zA-Z0-9_\-\.])
ID test123@ss.ss.ss 线、横杠、点）】长度不限 ([a-zA-Z0- +$
9_\-\.])+$
test1-23@s-_s.ss.
ss
针对以上部分正则表达式含义解释如下
表达式 含义
[0-9a-zA-Z_-]{27} 27 个字符，每个字符由 0~9 、a~z 26 个小写字母、A~Z 26 个大写字母、下划线 _ 、横杠 - 组成
$ 标识以这个字符结尾
^ 表示以某个字符开头
注意：
（1） 如果某客户端 SDK 的「设备 ID」取值有多种可能，请务必在正则表达式中以「或」的关系写入。
（2） 对于「登录 ID」因各家产品的 ID 规则不同，此处需要你自己使用正则表达式来定义「格式规则」，可参考此文档进行正则表达式的编写，确定规则后，
请联系神策同学协助你确认正则表达式的正确性。如当前项目中存在多个产品，其「登录 ID」格式规则各不相同，请务必在正则表达式中以「或」的关系写
入，如果只描述了一个组规则，有可能造成其他产品的用户数据无法正常入库。推荐分享.推荐分享 v1.13
推荐分享功能，用户可以将神策分析推荐给你的朋友，成为神策数据大使。您和您的朋友都可以享受专属优惠。
1. 使用流程
1. 点击右上角下拉框，可以进入推荐分享页面。
2. 首先进入的是推荐分享的介绍及优惠策略。
3. 点击"向好友推荐"按钮，进入"分享"页面。我们有两种分享方式。
可以打开微信，扫描页面左侧的二维码，将进入我们的官网，可以分享到朋友圈等社交平台。
还可以在页面右侧直接填写被推荐人的信息，包括公司名称、联系人、联系电话以及邮箱。其中邮箱是非必需填写的。提交成功后，我们将会给被
推荐人发送一条短信，包括试用 demo 地址、帐号及密码，后续我们的资讯顾问将会与其取得联系。提交成功后的页面如下：
2. 详细的优惠策略
优惠策略：
1. 被推荐客户经审核为新项目并成功签单付费，视为成功推荐。
2. 被推荐成功客户，可获赠 1 个月产品使用时长。
3. 神策数据大使，每成功推荐 1 名客户，可获赠 1 个月使用时长，可累计，上不封顶。
神策数据大使权益：
1. 有机会参与神策数据组织的定制活动，与行业专家面对面交流。
2. 有机会参与到神策客户答谢活动。3. 神策数据大使可获得神策数据文化体恤衫 1 件。使用 SQL 创建用户标签.使用 SQL 创建用户标签 v1.13
1. SQL 的结果要求
需严格返回 3 列数据，每列分别表示：神策id, 用户id, 标签值
示例：
/* event */
SELECT DISTINCT user_id AS id, distinct_id AS distinct_id, 1 AS value
FROM events
WHERE date BETWEEN ''[baseTime]'' AND ''[baseTime]''
AND event = ''login''
/* id "id" distinct_id "id""id"value "" */
2. SQL 语句语法说明
2.1. 使用动态时间
标签的每次计算都存在一个计算的“基准时间”。
若您的数据范围是动态变化的，例如：每天标签更新时，都会使用相对时间是“昨日”的数据进行计算；这时就需要使用动态时间来表示数据的时间范围。
示例：
/* event */
SELECT DISTINCT user_id AS id, distinct_id AS distinct_id, ''1'' AS value
FROM events
WHERE date BETWEEN ''[baseTime]'' AND ''[baseTime]''
AND event = ''login''
/* 2019-06-20 2019-06-19 [baseTime] 2019-06-19 */
/* */
注意：SQL 创建标签时，暂时不支持使用当前日期作为 baseTime。
''[baseTime]'' 实际上表示的为“昨日”
''[baseTime]'' - INTERVAL ''6'' DAY 表示为“过去第 7 天”
2.2. 其他查询语法
参考神策分析官网文档《自定义查询》
SQL 创建标签 与神策分析自定义查询的描述能力相同
点击查看
3. SQL 创建标签示例
3.1. 创建「最近 7 天消费次数」/* 2019-06-19 */
/* */
SELECT user_id AS id, MAX(distinct_id) AS distinct_id, COUNT(*) AS value
FROM events
WHERE date BETWEEN ''[baseTime]'' - INTERVAL ''6'' DAY AND ''[baseTime]''
AND event = ''BuyProduct''
GROUP BY 1
/* count() */
3.2. 创建「最近 7 天浏览偏好的商品类型（前 3）」
/* 2019-06-19 */
/* */
SELECT id, MAX(distinct_id) AS distinct_id,
GROUP_CONCAT(product_type, ''\n'') AS value
FROM (
SELECT id, distinct_id, product_type,
RANK() OVER (PARTITION BY id ORDER BY cnt DESC) AS rank_num
FROM (
SELECT user_id AS id, product_type,
MAX(distinct_id) AS distinct_id, COUNT(*) AS cnt
FROM events
WHERE date BETWEEN ''[baseTime]'' - INTERVAL ''6'' DAY AND ''[baseTime]''
AND event = ''productdetails''
GROUP BY 1, 2
) a
) b
WHERE rank_num <= 3
GROUP BY 1
/* group_concat(product_type, ''\n'') */
/* list */
3.3. 创建「用户最近一次访问距今时间（天）」
/* 2019-06-19 */
/* */
SELECT id, distinct_id, DATEDIFF(now(), time) AS value
FROM (
SELECT user_id AS id, MAX(distinct_id) AS distinct_id, MAX(time) AS time
FROM events
WHERE date BETWEEN ''[baseTime]'' - INTERVAL ''6'' DAY AND ''[baseTime]''
AND event = ''View''
GROUP BY 1
) a
/* View datediff(now(), time) as value */
3.4. 创建「最近7天最近一次支付事件发生的时间」/* */
SELECT user_id AS id, MAX(distinct_id) AS distinct_id,
UNIX_TIMESTAMP(MAX(time)) * 1000 AS value
FROM events
WHERE date BETWEEN ''[baseTime]'' - INTERVAL ''6'' DAY AND ''[baseTime]''
AND event = ''View''
GROUP BY 1
3.5. 创建「最近7天浏览最多的商品类型」
/* */
SELECT id, distinct_id, platform
FROM (
SELECT id, distinct_id, platform,
ROW_NUMBER() OVER (PARTITION BY id ORDER BY cnt DESC) AS row_num
FROM (
SELECT user_id AS id, platform, MAX(distinct_id) AS distinct_id, COUNT(*) AS cnt
FROM events
WHERE date BETWEEN ''[baseTime]'' - INTERVAL ''6'' DAY AND ''[baseTime]''
AND event = ''match''
GROUP BY 1, 2
) a
) b
WHERE row_num <= 1
3.6. 创建「昨日进行了登录的用户」
/* bool */
SELECT DISTINCT user_id AS id, distinct_id AS distinct_id, 1 AS value
FROM events
WHERE date BETWEEN ''[baseTime]'' - INTERVAL ''6'' DAY AND ''[baseTime]''
AND event = ''match''技术指南.技术指南 v1.13
基础知识
SDK
数据导入
数据校验
数据导出
辅助工具
高级功能基础知识.基础知识 v1.13
客户端 SDK
服务端 SDK
数据导入
1. 总体流程
神策分析提供了非常完备的数据接入方案，无论您的产品采用哪种技术架构，都可以非常容易的接入神策系统。
一般情况下，进行一次完整数据接入的流程如下：
1. 理解神策分析的基本概念，了解神策是干什么的，尤其是需要重点阅读 数据模型 的说明。
2. 如果有对应的神策数据分析师协助，请确认已经拿到对应的事件设计方案，其中应当包含了所有的事件及属性的设计建议。
3. 如果是使用私有部署的方案，请和相关运维同事确认已经配置好正确的数据接入地址。如果对这一点不确定，请联系神策技术支持。
4. 测试数据和正式数据应该接入到不同的项目中，具体概念请参考 多项目。
5. 根据事件设计和相关需求，按需要进行具体的接入工作，例如在客户端实施埋点或者导入历史数据，详情参考第二节。
6. 进行数据测试和验证，完成验证之后再上线到正式的环境。
以上流程仅供参考，如有任何疑问请联系您的神策咨询顾问。
2. 接入步骤
要点说明
1. 无论使用哪种接入方式，建议先阅读 数据格式，更好的理解神策数据接入的原理。
2. 建议开发的时候使用 调试模式 测试数据采集的正确性和追查问题。
注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用
Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
3. 经常使用 埋点管理 查看接入的详细情况。
4. 严格按照事件设计的定义来进行埋点，尤其注意不同来源（例如安卓/iOS，或者历史数据等）的事件、属性需要统一考虑，以免出现定义的冲突，
尤其是数据类型的定义。例如以下是一些典型的错误用法：
a. Android 支付事件叫 pay_order，iOS 的支付事件叫 PayOrder，这样会造成使用和理解上的困难。
b. Android 端的金额属性叫 money，类型是数字，而 iOS 端使用的是字符串类型，会导致数据无法导入。
5. 一个属性的类型由首次导入时的类型决定，后续导入只接受相同类型的输入， 类型不一致的输入数据会被整条拒绝。
6. 事件名称、属性名称、属性类型在一般情况下是不能修改的，请务必确认事件属性设计之后再进行数据接入。如果是测试阶段中有事件、属性的变
更，可以使用项目重置功能来重新初始化测试环境：多项目管理工具使用说明。
2.1. 如何标识用户
所谓标识用户，是指选择一个合适的标识符（例如设备 ID 或者注册 ID）作为 distinct_id 来发送数据到神策。是否选择了合适的 distinct_id 对数据分析的准
确性会有很大影响，因此，在进行任何数据接入之前，都应当先确认您的用户标识方式。神策分析提供了灵活、强大的用户标识能力，您可以根据自己的需
求来选择合适的方案，具体请阅读文档 标识用户。如果您依然不确定如何进行用户标识，请联系神策的数据分析师。
2.2. 客户端埋点
如果您不需要从客户端接入数据，可以跳过此段。
客户端接入目前有以下几类方案：
1. 直接使用神策客户端 SDK（.客户端 SDK v1.13）。这个方案相对简单、易用，并且神策 SDK 提供了更多内置的功能（例如 渠道追踪 等）和可靠
性保证（例如网络不好的情况下延迟发送）。同时神策的所有 SDK 都是完全开源的，不用担心有后门之类的安全问题。一般情况下，我们建议采用
此方案。
2. 使用已有的业务 API，把埋点需要的数据同步传到业务服务器，然后在服务端再使用神策的服务端 SDK（Java SDK） 进行接入。这个方案本质上
其实是服务端埋点，优点是对于业务统计可能会更加准确（因为和业务调用是同步的），安全性比较高（可以进行一定的客户端加密来增大伪造数
据的难度），缺点是实施难度较大。我们一般建议对于关键的业务事件（例如购买、支付等）采用这种方案。
3. 使用自己的埋点 SDK。如果您已经使用了自己的埋点 SDK，并且已经比较完善了，那么可以继续使用此方案，然后和方案 2 一样通过服务端接
入。
4. 如果您使用的是神策暂时不支持的客户端（例如 PC / Mac 软件），那么可以使用方案 2 或者方案 3，当然 也可以在客户端直接使用神策的 数据
接入 API 进行接入。
2.3. 服务端埋点
如果您不需要从服务端接入数据，可以跳过此段。
不管是客户端的埋点数据通过 API 发送给服务端之后，还是直接在服务端的已有业务逻辑里直接埋点，都属于服务端接入。服务端接入可以使用 服务端
SDK 等 SDK，每个 SDK 均有不同类型的发送方案（即 Consumer）可以选择，有两大类方案：1. 使用直接发送数据的 Consumer（例如 Java 的 AsyncBatchConsumer），实时的发数据给神策的服务。优点是方便简单，缺点是在机器故障或者
超大流量的极端情况下可能会丢失一小部分数据，并且可能对业务造成一定影响。如果数据量不大可以使用此方案。
2. 使用写入本地日志的 Consumer（例如 Java 的 LoggingConsumer），配合 LogAgent 进行导入。优点是因为有本地持久化，可靠性会更高，缺点
是代码会稍微复杂，同时还需要自己负责本地日志的存储和删除等运维操作。建议在大数据量或者对数据准确性有高要求的时候使用此方案。
在一般情况下，我们都建议在服务的入口处（例如 MVC 的 Controller 层）进行埋点，这样既能获取到大部分埋点所需要的数据，又方便统一管理：如果有
埋点额外需要的客户端数据（例如设备信息），可以通过 API 参数传入；对于埋点需要的业务数据（例如下单事件的优惠信息），则可以通过业务处理模块
返回给 Controller 层。
2.4. 工具导入（历史数据导入）
如果您没有历史数据需要接入，可以跳过此段。
对于已经存在的历史数据，无论是事件还是用户属性，我们都建议使用 Java SDK／PHP SDK SDK 生成特定格式的数据，然后使用 LogAgent（SaaS
版）、BatchImporter小数据量/私有部署） 或者HdfsImporter（大数据量/私有部署/集群版）等工具进行导入。也可以不使用 SDK，直接按照数据格式里
的说明生成数据并导入。
一般情况下，历史数据即可以先导入，也可以等实时数据正式接入之后再导入，不影响最终的分析结果。但是如果使用了login / track_signup，则请务必阅
这里的 标识用户，避免导入数据顺序不对导致的用户 ID 关联错误。
2.5. 用户属性的接入
用户属性（Profile）是可选的，如果您的业务里并不需要接入用户属性，可以跳过此段。
事件（Event）总是在事件发生的时候进行 track，而用户属性（Profile）则不是那么固定，而是根据不同属性会有所不同，主要还是取决于具体属性的获取
方式，一般来说主要有以下几种方式：
1. 伴随事件的发生：例如神策提供的客户端 SDK 会默认在用户首次访问的时候，设置用户的 首次访问时间 等属性。类似的，您也可以主动在用户首
次购买的时候调用 profile_set_once 设置一个 首次购买时间 的属性。
2. 在属性修改时接入：即在某个用户属性被修改的时候（例如修改用户资料的接口）同时调用 profile_set 系列接口。
3. 定时同步导入：即定时从业务数据库或者其它数据源中导出数据，然后用 LogAgent／BatchImporter 导入神策系统。这里应该尽量用最后更新时间
之类的字段来实现增量导入，否则每次全量导入可能会影响性能。
4. 实时同步导入：例如 MySQL 可以使用 Applier 来对数据的 Binlog 进行实时解析和同步，其它数据库也可以使用类似的工具。此方案的优点是不用
修改已有业务代码，耦合性较低，但是需要根据具体数据库类型进行额外的开发。
由于用户属性的导入效率会低于事件，因此应该尽量避免非必要的 profile 操作，例如在数据没有变化的情况下重复更新某一个 profile。数据模型.数据模型 v1.13
1. 数据模型简介
在神策分析中，我们使用事件模型（Event 模型）来描述用户在产品上的各种行为，这也是神策分析所有的接口和功能设计的核心依据。
简单来说，事件模型包括事件（Event）和用户（User）两个核心实体，在神策分析中，分别提供了接口供使用者上传和修改这两类相应的数据，在使用产品
的各个功能时，这两类数据也可以分别或者贯通起来参与具体的分析和查询。对这两个概念，我们会在后文做具体的描述。
1.1. Event Model Vs. Page View
在传统的 Web 时代，通常使用 PV（Page View 的简写，也即页面访问量）来衡量和分析一个产品的好坏，然后，到了移动互联网以及 O2O 电商时代，
PV 已经远远不能满足产品和运营人员的分析需求了。
在这个年代，每个产品都有着独一无二的核心指标用来衡量产品是否成功，这个指标可能是发帖数量、视频播放数量、订单量或者其它的可以体现产品核心
价值的指标，这些都是一个简单的 PV 无法衡量的。
除此之外，PV 模型也无法满足一些更加细节的、更加精细化的分析。例如，我们想分析哪类产品销量最好，访问网站的用户的年龄和性别构成，每个渠道过
来的用户的转化率、留存和重复购买率分别如何，新老用户的客单价、流水、补贴比例分别是多少等等。这些问题，都是以 PV 为核心的传统统计分析没办
法解答的问题。
因此，神策分析采用事件模型作为基本的数据模型。事件模型可以给我们更多的信息，让我们知道用户用我们的产品具体做了什么事情。事件模型给予我们
更全面且更具体的视野，指导我们做出更好的决策。
当然，采用神策分析的事件模型，依然是可以完成 PV 统计的，并且实现起来也很简单，使用 SDK 或者导入工具上传一个类似的接口即可：
{
"distinct_id": "2b0a6f51a3cd6775",
"time": 1434556935000,
"type": "track",
"event": "PageView",
"properties": {
"$ip" : "180.79.35.65",
"user_agent" : "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.",
"page_name" : "",
"url" : "www.demo.com",
"referer" : "www.referer.com"
}
}
1.2. Event 实体
1.2.1. Event 的五要素
简单来说，一个 Event 就是描述了：一个用户在某个时间点、某个地方，以某种方式完成了某个具体的事情。从这可以看出，一个完整的 Event，包含如下
的几个关键因素：
Who：即参与这个事件的用户是谁。在我们的数据接口中，使用 distinct_id 来设置用户的唯一 ID：对于未登录用户，这个 ID 可以是 cookie_id、
设备 ID 等匿名 ID；对于登录用户，则建议使用后台分配的实际用户 ID。同时，我们也提供了 track_signup 这个接口，在用户注册的时候调用，用
来将同一个用户注册之前的匿名 ID 和注册之后的实际 ID 贯通起来进行分析。
When：即这个事件发生的实际时间。在我们的数据接口中，使用 time 字段来记录精确到毫秒的事件发生时间。如果调用者不主动设置，则各个
SDK 会自动获取当前时间作为 time 字段的取值。
Where：即事件发生的地点。使用者可以设置 properties 中的 $ip 属性，这样系统会自动根据 ip 来解析相应的省份和城市，当然，使用者也可以
根据应用的 GPS 定位结果，或者其它方式来获取地理位置信息，然后手动设置 $city 和 $province。除了 $city 和 $province 这两个预置字段以
外，也可以自己设置一些其它地域相关的字段。例如，某个从事社区 O2O 的产品，可能需要关心每个小区的情况，则可以添加自定义字段
“HousingEstate”；或者某个从事跨国业务的产品，需要关心不同国家的情况，则可以添加自定义字段 “Country”。How：
即用户从事这个事件的方式。这个概念就比较广了，包括用户使用的设备、使用的浏览器、使用的 App 版本、操作系统版本、进入的渠
道、跳转过来时的 referer 等，目前，神策分析预置了如下字段用来描述这类信息，使用者也可以根据自己的需要来增加相应的自定义字段。$app_version
$city
$manufacturer "Apple"
$model "iphone6"
$os "iOS"
$os_version "8.1.1"
$screen_height 1920
$screen_width 1080
$wifi WIFIBOOLtrue
What：描述用户所做的这个事件的具体内容。在我们的数据接口中，首先是使用 event 这个事件名称，来对用户所做的内容做初步的分类。event
的划分和设计也有一定的指导原则，我们会在后文详细描述。除了 event 这个至关重要的字段以外，我们并没有设置太多预置字段，而是请使用者
根据每个产品以及每个事件的实际情况和分析的需求，来进行具体的设置，下面给出一些典型的例子：
- 对于一个“购买”类型的事件，则可能需要记录的字段有：商品名称、商品类型、购买数量、购买金额、 付款方式等；
- 对于一个“搜索”类型的事件，则可能需要记录的字段有：搜索关键词、搜索类型等；
- 对于一个“点击”类型的事件，则可能需要记录的字段有：点击 URL、点击 title、点击位置等；
- 对于一个“用户注册”类型的事件，则可能需要记录的字段有：注册渠道、注册邀请码等；
- 对于一个“用户投诉”类型的事件，则可能需要记录的字段有：投诉内容、投诉对象、投诉渠道、投诉方式等；
- 对于一个“申请退货”类型的事件，则可能需要记录的字段有：退货金额、退货原因、退货方式等。
1.2.2. Event 的划分和字段设计原则
为了更好地使用神策分析提供的强大、便捷的分析功能，我们强烈建议使用者花费一定的时间，梳理自己的数据使用需求，并据此做好 Event 的划分和字段
设计。
在 Event 的划分和设计过程中，神策分析团队也会提供相应的技术支持和服务，除此之外，我们将一些基本的原则也在这里整理出来，期望对使用者有所帮
助。
1.2.2.1. 客户端埋点 Vs. 在后端记录 Event
友盟、百度统计等传统分析工具，都是在客户端嵌入 SDK 进行埋点，但是，我们强烈推荐 在后端记录 Event，这是出于以下一些考虑：
1. 很多行为，如下单等，他们的很多字段在前端（App 和 Web 界面）是拿不到的。甚至有些行为，如用户线下消费等，前端根本就没有提供相应的
功能，就更拿不到对应的数据。
2. 后端修改程序更加方便便捷，如果是在 App 端记录数据，则每次修改都需要等待 App 的发版和用户更新；
3. App 端收集数据会有丢失的风险，并且上传数据也不及时。App 端为了避免浪费用户的流量，一般情况下，都是将多条数据打包，并且等待网络状况
良好以及应用处于前台时才压缩上传，因此，自然会造成上传数据不及时，很有可能某一天的数据会等待好几天才传到服务器端，这自然会导致每
天的指标都计算有偏差。同时，由于 App 端可以缓存的内容有限，用户设备的网络连接等问题，App 端收集的数据目前也没有太好的手段保证
100% 不丢失。
基于以上几点考虑，除非某个行为只在前端发生，对后端没有任何请求，否则，我们建议永远只在后端收集数据。
1.2.2.2. Event 的划分原则
对产品划分 Event，我们有如下的一些建议：
1. 为了节约使用成本，应该从需求出发，只记录那些会分析到的 Event，这一点是与传统的 PV 分析产品一个很大的不同。记录 Event 是为了详细地
了解用户是如何使用产品的，对于暂时不会分析到的那些使用情况，可以暂时先不记录。
2. Event 的数量不应过多，对于一个典型的用户产品，Event 的数量以不超过 20 个为宜。当然，这个只是我们对事件设计的一些原则性的建议，系
统本身并没有这方面的限制。一些类似的用户操作，可以合并成一个 Event。例如，假设某个产品比较关心对一系列商品分类页的访问情况，那么，
并不意味着每个商品分类页点击就应该划分成一个单独的 Event，而是可以划分出一个单独的商品分类页访问 Event，然后再将不同的分类以字段
的形式进行记录。
3. Event 不仅局限于用户在 App、Web 界面等前端的操作和使用，一些其它类型的用户行为，例如用户的电话投诉、用户在线下接收服务、用户在线下
商家进行消费等，如果能够获取到相应的数据，并且数据分析也会用到，则也可以作为相应的 Event。
1.2.2.3. 字段设计原则
为每个 Event 进行字段设计，我们有如下的一些建议：
1. 先根据需求梳理分析的指标和维度，然后再从指标和维度倒推需要在每个 Event 记录的字段。
2. 神策分析是一个数据分析工具，并不是一个日志存储和备份系统，所以，一些用不到的字段，例如 Cookie 的完整内容、后端请求返回码等，就没
有必要作为一个 Event 的字段来进行记录和收集了。
3. 预置字段中已经有的字段，则建议尽量复用预置字段。对所有预置字段的说明，可以参看 数据格式 中的相应说明。
4. 某个 Event 的某个字段的设计一旦确定，则不要再修改它的类型和取值含义。例如，一开始对于"Buy"这个 Event，我们设计了一个数值类型的字
段 Money，描述这个购买行为对应的购买金额是多少元，然而后面我们期望把它改成分，那么我们建议不如废弃掉 Money 字段并且增加一个新的
字段叫 MoneyByCents，而不是去改变 Money的含义。
1.3. User 实体1.3.1. 记录和收集 User Profile
每个 User 实体对应一个真实的用户，用 distinct_id 进行标识，描述用户的长期属性（也即 Profile），并且通过 distinct_id 与这个用户所从事的行为，也
即 Event 进行关联。
神策分析提供了一系列 profile_xxx 类型的接口，用来对某个 user 的 Profile 进行记录和修改。
一般记录 User Profile 的场所，是用户进行注册、完善个人资料、修改个人资料等几种有限的场合，与 Event 类似，我们也强烈建议 在后端记录和收集
User Profile。
应该收集哪些字段作为 User Profile，也完全取决于产品形态以及分析需求。简单来说，就是在能够拿到的那些用户属性中，哪些对于分析有帮助，则作为
Profile 进行收集。
1.3.2. 字段记录在 Profile 还是 Event 的取舍
有些时候，我们可能会纠结，某个与用户相关的字段是应该记录在 Profile 还是记录在 Event，一个基本的原则就是，Profile 记录的是用户的基本固定不变
的属性，例如性别、出生年份（请注意，记录的不是年龄而是出生年份）、注册时间、注册地域、注册渠道等。而还有一些字段，例如用户级别、设备类
型、地域、是否是 Vip 等，虽然也是用户相关的字段，但是可能是会经常变化的，则应该在用户的某个 Event 发生的时候，作为 Event 的一个字段来进行记
录。
1.4. Item 实体
神策 1.14 开始支持 Item 实体。
在 Event-User 模型中，出于性能和可解释性等各方面的考虑，Event 是被设计为不可变的。从逻辑上看似乎没有问题，因为 Event 代表的是历史上已经发
生过的事件，一般来说不应该需要进行更新。
但是，在实际的应用过程中，并不一定是这么理想的状态。
如，在采集和分析中会发现：
Event 实体中一些基本信息中会有许多是不断变化的
埋点采集中，发现某些 Event 在最初的阶段采集到的数据不完善。
这时，可通过 Item 实体对 Event-User 模型进行补充。
这里的所谓 Item，在严格意义上是指一个和用户行为相关联的实体，可能是一个商品、一个视频剧集、一部小说等等。Item 的应用场景有很多，下面介绍两
个最常见的应用场景。
1.4.1. 神策分析系统中的 Item 应用
Item 模型的一个典型场景是用作神策分析的维度表，具体的使用请参考文档 虚拟属性和维度表
1.4.2. 神策推荐系统中的 Item 应用
想了解神策推荐服务的更多细节，请联系神策技术支持。
神策推荐核心价值是计算用户最有可能消费的物品（即 Item），并以推荐结果返回到产品前端供用户消费。神策推荐系统会以 Item 数据为基础构建推荐物
品的画像（高维向量），计算用户最有可能消费的物品或者相似物品。
在对接神策推荐系统时，开发者需要通过 SDK 的 itemSet 系列接口来上传数据，同时神策也提供了管理后台对 Item 表进行直接的管理，例如管理员可以对
某条待推荐的 Item 进行封禁或者调权以优化推荐效果。数据格式.数据格式 v1.13
b神策分析支持多种不同语言的 SDK，这些 SDK 虽然在外部提供的接口上有所不同，但是在内部实现上都使用统一的数据格式，并且 数据导入 都支持直接
导入以文件形式存储的符合要求格式的数据，在这里，我们对数据格式进行一个更加细致的描述。
注意：这里描述的是底层数据传输格式的定义，和具体 SDK 的调用接口无关
注意：$is_login_id 参数说明
1. 数据整体格式
日志文件是一行一个 JSON，物理上对应一条数据，逻辑上对应一个描述了用户行为的事件，或是描述一个或多个用户属性的 Profile 操作。
1.1. track：
记录一个 Event 及关联的 Properties。
数据样例：
{
"distinct_id": "123456",
"time": 1434556935000,
"type": "track",
"event": "ViewProduct",
"project": "ebiz_test",
"time_free": true, //SDK
"properties": {
"$is_login_id":true, // 8.1 $is_login_id
"$app_version":"1.3",
"$wifi":true,
"$ip":"180.79.35.65",
"$province":"",
"$city":"",
"$user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_2 like Mac OS X) AppleWebKit/602.1.50
(KHTML, like Gecko) CriOS/58.0.3029.113 Mobile/14F89 Safari/602.1",
"$screen_width":320,
"$screen_height":640,
"product_id":12345,
"product_name":"",
"product_classify":"",
"product_price":14.0
}
}
对于上述字段的说明如下：
distinct_id：类型是字符串，对用户的标识，对未登录用户，可以填充设备标识、CookieID 等，对于登录用户，则应该填充注册账号；这里的例
子，我们假设是一个未注册用户，所以填充的是一个设备编号；
time：类型是数值，事件发生的实际时间戳，精确到毫秒；
type：track 表 明 是 记 录 一 个 Event ， 这 里 我 们 假 设 是 一 个 商 品 浏 览 行 为 ； event：
事件名，需是合法的变量名，即不能以数字开头，且只包含：大小写字母、数字、下划线和 $，其中以 $ 开头的表明是系统的保留字段，自定义事
件名请不要以 $ 开头，且 event 字段长度最大为 100；
project：这条数据所属项目名，若不指定该参数，则需要使用该字段时取值 default，即默认项目。指定的项目必须是系统中已经存在的项目，否则
这条数据将无效，更多项目相关请参见多项目；
time_free：可选字段，表示不根据事件发生时间过滤该事件。只要出现 time_free 这个 key 且value 不为 null，将不再校验 time 是否在允许导入
的时间范围内。导入历史数据时可能会用到该字段；
properties：这个 Event 的具体属性，以 dict 的形式存在。其中以$开头的表明是系统的保留字段，它的类型和中文名已经预先定义好了。自定义
属性名需要是合法的变量名，不能以数字开头，且只包含：大小写字母、数字、下划线，自定义属性不能以 $ 开头；同一个名称的 property，在不
同 event 中，必须保持一致的定义和类型；同一个名称的 property 大小写不可以相同，如果已经存在小写属性就不可再导入对应大写属性（比如元数
据中有 abc 属性名，不能再传 ABC,Abc 等属性名），否则数据会校验失败不入库。
$is_login_id：distinct_id 对应的是否是一个注册 ID；
$app_version：用户所使用的 App 的版本；
$wifi：这条事件发生时，用户是否在使用 wifi；
$ip：用户使用设备的 IP。若数据中出现 $ip，且数据中没有 $province 或 $city 字段，将使用该 IP 解析出省市信息填入缺失字段；
$province、$city：省、市，在没有填充这两个字段的时候，会根据 IP 进行解析；$user_agent：可选参数。如果传入该参数，则解析 User-Agent，解析结果包括：设备制造商、设备型号、操作系统、操作系统版本、浏
览器、浏览器版本、爬虫名称（如果是爬虫）；目前是神策是通过 UA 判断并有一个默认的属性 $bot_name （爬虫名称），但是有两种
情况无法判断，第一种：如果 UA 里没有标明、且会触发 JS 脚本的非法爬虫。第二种：如果爬虫没有触发 JS 脚本，那么也不会触发我们
的 SDK ，所以本身就不会被统计到。对于爬虫种类，不能提前把所有的种类都加进去，主流的神策都加了，其它的属于不太常见的，量较
少。
$screen_width 、 $screen_height： 屏 幕 的 宽 和 高 ；
product_id、product_name、product_classify、product_price：跟商品相关的一些具体属性。
1.2. track_signup：
这个接口是一个较为复杂的功能，请在使用前先阅读 标识用户，并在必要时联系我们的技术支持人员。
数据样例：
{
"distinct_id":"12345",
"original_id":"2b0a6f51a3cd6775",
"time": 1434557935000,
"type": "track_signup",
"event": "$SignUp",
"project": "ebiz_test",
"properties": {
"$manufacturer":"Apple",
"$model": "iPhone 5",
"$os":"iOS",
"$os_version":"7.0",
"$app_version":"1.3",
"$wifi":true,
"$ip":"180.79.35.65",
"$province":"",
"$city":"",
"$screen_width":320,
"$screen_height":640
}
}
这条数据表示，一个匿名 ID 为 2b0a6f51a3cd6775 的用户，成功完成了注册，注册后的注册 ID 是 12345。并且系统后台，会将 original_id 为
2b0a6f51a3cd6775 的用户和 distinct_id 为 12345 的用户，当做同一个用户对待。需要注意的是，此接口中的 original_id 为必须字段，表示与注册 ID 进
行关联的匿名 ID。
1.3. Profile 相关操作
Profile 相关操作，主要是用来设置用户的 Profile 的，提供了如下一系列接口：
1.3.1. profile_set：
直接设置一个用户的 Profile，如果用户或者 Profile 的字段已存在，则覆盖，不存在则自动创建。
数据样例：
{
"distinct_id": "12345",
"type": "profile_set",
"time": 1435290195610,
"project": "ebiz_test",
"properties": {
"$province":"",
"FavoriteFruits": ["","",""],
"Age":33,
"$city":"",
"IncomeLevel": "3000~5000",
"$name": "",
"Gender":"",
"$signup_time": "2015-06-26 11:43:15.610"
}
}1.3.2. profile_set_once
直接设置一个用户的 Profile。与 profile_set 接口不同的是，如果用户或者 Profile 的字段已存在，则这条记录会被忽略而不会覆盖已有数据，如果 Profile
不存在则会自动创建。因此，profile_set_once 比较适用于为用户设置首次激活时间、首次注册时间等只在首次设置时有效的属性。
数据样例：
{
"distinct_id": "12345",
"type": "profile_set_once",
"time": 1435290195610,
"project": "ebiz_test",
"properties": {
"$province":"",
"FavoriteFruits": ["","",""],
"Age":33,
"$city":"",
"IncomeLevel": "3000~5000",
"$name": "",
"Gender":"",
"$signup_time": "2015-06-26 11:43:15.610"
}
}
}
1.3.3. profile_increment：
增加或减少一个用户的某个 NUMBER 类型的 Profile 值，比如给用户属性 Age 的值加 1 或者减 1 。如果用户表（ users 表）中不存在这个用户，则会在
用户表中自动创建该用户的 id 记录，并给该用户设置相应的 Profile 属性值，会在默认值 0 的基础上增加上传的 Profile 值。
数据样例：
{
"distinct_id": "12345",
"type": "profile_increment",
"time": 1435290200354,
"project": "ebiz_test",
"properties": {
"Age": 1
}
}
1.3.4. profile_delete：
删除一个用户的整个 Profile。
数据样例：
{
"distinct_id": "12345",
"type": "profile_delete",
"time": 1437290200354,
"project": "ebiz_test",
"properties":{
}
}
1.3.5. profile_append：
向某个用户的某个数组类型的 Profile 添加一个或者多个值。如果本次上传的值，与系统中已存在的值有重复，默认是不会去重的。如果本次上传的值，有重
复项，也不会去重的。
数据样例：{
"distinct_id": "12345",
"type": "profile_append",
"time": 1437280200354,
"project": "ebiz_test",
"properties": {
"FavoriteFruits": ["",""]
}
}
1.3.6. profile_unset：
将某个用户的某些属性值设置为空。另外，为了与其它接口保持一致，在提交的数据上，属性的值请设置为非 null 的任何值，例如 true。
数据样例：
{
"distinct_id":"12345",
"type":"profile_unset",
"time":1437280200354,
"project": "ebiz_test",
"properties":{
"Age":true,
"FavoriteFruits":true
}
}
1.4. Item 相关操作
Item 相关操作，主要是用来设置 Item 的具体内容，提供了如下一系列接口：
1.4.1. item_set：
直接设置一个 Item，如果 Item 的字段已存在，则覆盖，不存在则自动创建。
数据样例：
{
"type":"item_set",
"item_id":"12",
"item_type":"dub",
"project": "ebiz_test",
"properties":{
"title":"because of u",
"sub_title":"st",
"xxx":"xxx"
}
}
对上述字段的解释如下：
type：item_set 表明是设置一个 item；
item_id：表示 item 的 id
item_type：item 表的类型，区分不同的 item 表。需是合法的变量名，即不能以数字开头，且只包含：大小写字母、数字、下划线和 $，且
item_type 字段长度最大为 100；
project：这条数据所属项目名，若不指定该参数，则需要使用该字段时取值 default，即默认项目。指定的项目必须是系统中已经存在的项目，否则
这条数据将无效，更多项目相关请参见 多项目；
properties：这个 item 的具体属性，以 dict 的形式存在。属性名需要是合法的变量名，不能以数字开头，且只包含：大小写字母、数字、下划线；
1.4.2. item_delete：
删除整个 Item 内容。
数据样例：{
"type":"item_delete",
"item_id":"16",
"item_type":"dub",
"project": "ebiz_test"
}
1.5. 属性数据类型
1.5.1. 注意问题
发送端使用 JSON 作为数据传输格式，本系统以 JSON 数据类型为基础再加以额外限制，定义了若干种数据类型，但 不与 JSON 类型完全等价，详见后文
属性类型说明。
(table_name, property_name) 二元组唯一确定一个属性，table_name 为数据表的表名，如 users、events，可在自定义 SQL 查询中看到。这意味着同表
同名属性类型必须相同，而不同表的同名属性类型可以不同。消息类型与所写入的数据表的关系如下表：
消息类型 目标数据表
track events
profile_* users
track_signup 事件信息被写入 events 表，users 表中会记录 first_id 和 second_id
一个属性的类型由首次导入时的类型决定，元数据-事件属性/用户属性页面展示的属性类型即为首次导入时的类型，后续导入数据时若类型和元数据中展示
的类型不符，则尝试对数据进行类型转换，若无法转换或转换失败则 输入数据会被整条拒绝 。尝试进行的类型转换如下（空格不进行转换）：
目标类型\原始类 数值型 布尔值 字符串 字符串集合 日期时间
型
数值型 true -> 1; false -> 空字符串 "" 抛弃该属性; 其他按数值解
0 析
布尔值 0 -> false; 非 0 值 -> true 字符串"true"、"false"转换为布尔类型
字符串 原值作为字符串 原值作为字符串 原值作为字符 原值作为字符
串 串
字符串集合
日期时间 在一定区间内的按 UNIX 时间戳的秒或毫秒转 多种日期时间格式模式串解析
换
上述表格左侧的列对应目标类型，上方的行对应原始类型。目标类型对应元数据中的数据类型，原始类型是数据上传时的属性值类型
什么时候该使用数值类型的属性：
需要进行聚合运算（例如求和、均值）或者按区间分组的值，典型的比如价格、时长、年龄等。
除非有特殊需求，否则各类 ID（例如订单 ID）不建议作为数值类型存储。
1.5.2. 神策分析属性数据类型定义
神 中 基础 额外限制 示 说明
策 文 JSON 例
分 名 类型
析
数
据
类
型
NUM 数值 number -9E15 到 9E15 小数点后最多保留3位 12 或
BER 型 12.0
BOOL 布尔 bool 无 true
值 或
false
STRI 字符 string 使用 UTF-8 编码后最大长度 1024 字节，如需调整最大长度可以联系我们 "Sens
NG 串 orsDa
ta"
LIST 字符 list 1.12 版本之后默认是字符串元素的数组（传入的字符串不会去重），最大元素个数为 500，其 ["橘
串数 中每个元素使用 UTF-8 编码后最大长度 255 字节；注意：1.12 之前的版本，List 是集合，即 子","
组 在入库时会进行重排序和去重。如果需要调整 List 具体是数组还是集合，请联系神策技术支 西瓜"]
持。若 append 导致超过最大元素个数时，新入库的元素会淘汰最早入库的元素。DATE 日期 string yyyy-MM-dd HH:mm:ss.SSS 或 "2015 有些语言的时间格式化库不直接提供
TIME 时间 yyyy-MM-dd HH:mm:ss 或 -06- 毫秒格式化，如 Python 提供 us 而
yyyy-mm-dd （时分秒按00:00:00处理）， 建议使用第一种，其中 SSS 为毫秒；年取值范围 19 不提供 ms，如需自行编写程序生成
是 [1900, 2099] 17: 数据请注意这点。
51:
21.23
4"
"2015
-06-
19
17:
51:
21"
"2015
-06-
19"
DATE 日期 string 格式为 yyyy-mm-dd，年取值范围是 [1900, 2099] "2015 自 1.11 版本起，DATE 类型将作为
（仅 -06- DATETIME 的一种格式存在（既时
<= 19" 分秒为 00:00:00 的 DATETIME，
1.10 且时分秒可省略），不再单设类型。
版
本）
1.6. 预置属性
为了帮助使用者更方便地使用我们的产品，我们目前分别为 Event 和 Profile 提供了一些预置字段。
注意：JavaScript SDK 预置属性较多，这里没有全部列出，详细说明请参考相关文档 Web 预置属性
Event 的预置字段有：
字段名称 类 说明 JS SDK 自动采 iOS SDK 自动采 Android SDK 自动采 小程序 SDK 自动采 服务端 SDK 自动采
型 集 集 集 集 集
$app_version 字符串 应用的版本 N Y Y N N
$ip 字符串 ip Y Y Y Y Y
$country 字符串 国家 Y Y Y Y N
$city 字符串 城市 Y Y Y Y N
$province 字符串 省份 Y Y Y Y N
$lib 字符串 SDK类型，例如python、iOS Y Y Y Y Y
等
$lib_version 字符串 SDK版本 Y Y Y Y Y
$manufacturer 字符串 设备制造商，例如Apple Y Y Y N N
$model 字符串 设备型号，例如iphone 8,4 Y Y Y Y N
$os 字符串 操作系统，例如iOS Y Y Y Y N
$os_version 字符串 操作系统版本，例如8.1.1 Y Y Y Y N
$screen_height 数值 屏幕高度，例如1920 Y Y Y Y N
$screen_width 数值 屏幕宽度，例如1080 Y Y Y Y N
$wifi 布尔值 是否使用wifi，例如true N Y Y N N
$browser 字符串 浏览器名，例如Chrome Y N Y N N
$browser_version 字符串 浏览器版本，例如Chrome Y N N N N
45
$carrier 字符串 运营商名称，例如ChinaNet N Y Y N N
$network_type 字符串 网络类型，例如4G N Y Y Y N
$utm_matching_type 字符串 渠道追踪匹配模式 N Y1 Y1 N N
$latest_referrer 字符串 站外前向地址 Y N N N N
$latest_referrer_host 字符串 站外前向域名 Y N N N N
$latest_utm_source 字符串 最近广告系列来源 Y N N Y5 N
$latest_utm_medium 字符串 最近广告系列媒介 Y N N Y5 N
$latest_utm_term 字符串 最近广告系列字词 Y N N Y5 N
$latest_utm_content 字符串 最近广告系列内容 Y N N Y5 N
$latest_utm_campaign 字符串 最近广告系列名称 Y N N Y5 N
$latest_search_keyword 字符串 最近一次搜索引擎关键词 Y N N N N
$latest_traffic_source_ty 字符串 最近一次流量来源类型 Y N N N N
pe$is_first_day 布尔值 是否首日访问 Y Y Y Y N
$device_id 字符串 设备ID Y6 Y Y N N
Profile 的预置字段有：
字段名称 类型 说明 JS SDK 自动采 iOS SDK 自动采 Android SDK 自动采 小程序 SDK 自动采 服务端 SDK 自动采
集 集 集 集 集
$city 字符串 用户所在的城市 N N N N N
$province 字符串 用户所在的省份 N N N N N
$name 字符串 用户名 N N N N N
$signup_time Datetime 注册时间 N N N N N
$utm_matching_type 字符串 渠道追踪匹配模式 N Y1 Y1 N N
$first_visit_time Datetime 首次访问时间 Y3 Y4 Y4 N N
$first_referrer 字符串 首次前向地址 Y3 N N N N
$first_referrer_host 字符串 首次前向域名 Y3 N N N N
$first_browser_language 字符串 首次使用的浏览器语言 Y3 N N N N
$first_browser_charset 字符串 首次浏览器字符类型（1.8支 Y3 N N N N
持）
$first_search_keyword 字符串 首次搜索引擎关键词（1.8支 Y3 N N N N
持）
$first_traffic_source_ty 字符串 首次流量来源类型（1.8支 Y3 N N N N
pe 持）
$utm_source 字符串 首次广告系列来源 Y2 Y1 Y1 Y N
$utm_medium 字符串 首次广告系列媒介 Y2 Y1 Y1 Y N
$utm_term 字符串 首次广告系列字词 Y2 Y1 Y1 Y N
$utm_content 字符串 首次广告系列内容 Y2 Y1 Y1 Y N
$utm_campaign 字符串 首次广告系列名称 Y2 Y1 Y1 Y N
Item 的预置字段有：
字段名称 类型 说明 SDK 自动采集
$is_valid 布尔值 该 item 是否有效，不传入默认为 true N
$receive_time 数值型 该 item 到达时间 Y
$update_time 数值型 该 item 的更新时间，不传入默认为写入时间 N
上述 Y 上标含义如下:
1. $utm_ 开头的相关属性，由 App 渠道追踪功能自动采集，请参考相关文档 渠道追踪。
2. 新用户首次访问时，需要开启 autoTrack 且 URL 中带有 UTM 参数，才会收集，请参考相关文档 Web JS SDK 。
3. 新用户首次访问时，开启 autoTrack 才会收集，请参考相关文档 Web JS SDK。
4. 新用户首次启动 App，如果调用了 trackInstallation 接口会自动给这个属性赋值。
5. 小程序 SDK 1.3 版本支持。
6. 如果 SDK 初始化时候配置了 is_track_device_id:true, 就会采集。
1.6.1. 预置属性采集方式
iOS 中，预置属性的采集方式大致如下：
NSMutableDictionary *p = [NSMutableDictionary dictionary];
UIDevice *device = [UIDevice currentDevice];
NSString *deviceModel = [self deviceModel];
struct CGSize size = [UIScreen mainScreen].bounds.size;
CTCarrier *carrier = [[[CTTelephonyNetworkInfo alloc] init] subscriberCellularProvider];
// Use setValue semantics to avoid adding keys where value can be nil.
[p setValue:[[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"] forKey:@"$app_version"];
[p setValue:carrier.carrierName forKey:@"$carrier"];
[p addEntriesFromDictionary:@{
@"$lib": @"iOS",
@"$lib_version": [self libVersion],
@"$manufacturer": @"Apple",
@"$os": [device systemName],@"$os_version": [device systemVersion],
@"$model": deviceModel,
@"$screen_height": @((NSInteger)size.height),
@"$screen_width": @((NSInteger)size.width),
}];
Android 中，预置属性的采集方式大致如下：
{
deviceInfo.put("$lib", "Android");
deviceInfo.put("$lib_version", VERSION);
deviceInfo.put("$os", "Android");
deviceInfo.put("$os_version",
Build.VERSION.RELEASE == null ? "UNKNOWN" : Build.VERSION.RELEASE);
deviceInfo
.put("$manufacturer", Build.MANUFACTURER == null ? "UNKNOWN" : Build.MANUFACTURER);
deviceInfo.put("$model", Build.MODEL == null ? "UNKNOWN" : Build.MODEL);
try {
final PackageManager manager = mContext.getPackageManager();
final PackageInfo info = manager.getPackageInfo(mContext.getPackageName(), 0);
deviceInfo.put("$app_version", info.versionName);
} catch (final PackageManager.NameNotFoundException e)
{ Log.e(LOGTAG, "Exception getting app version name",
e);
}
final DisplayMetrics displayMetrics = context.getResources().getDisplayMetrics();
deviceInfo.put("$screen_height", displayMetrics.heightPixels);
deviceInfo.put("$screen_width", displayMetrics.widthPixels);
TelephonyManager telephonyManager = (TelephonyManager) mContext.getSystemService(Context
.TELEPHONY_SERVICE);
String operatorString = telephonyManager.getSimOperator();
if (operatorString == null) {
// DO NOTHING
} else if (operatorString.equals("46000") || operatorString.equals("46002"))
{ deviceInfo.put("$carrier", "");
} else if (operatorString.equals("46001"))
{ deviceInfo.put("$carrier", "");
} else if (operatorString.equals("46003"))
{ deviceInfo.put("$carrier", "");
} else
{ deviceInfo.put("$carrier",
"");
}
}
1.7. 限制
1.7.1. 一般限制
1. 事件名（event 的值）和 属性名（properties 中 key 取值）都需是合法的变量名，即不能以数字开头，且只包含：大小写字母、数字、下划线和
$，且事件名和属性名最大长度都为 100；
2. 类型 type 字段的取值只能是上文列出几种（track, profile_set 等），并且大小写敏感；
3. 属性 properties 字段必须存在，可以为空（ {} ）；
4. 事件 time 字段允许的范围是 1000000000000(2001-09-09 09:46:40) ~ 10000000000000(2286-11-21 01:46:40);
5. 本节 1.7.6 列出了保留属性名；
1.7.2. 事件时间限制
导入不合理时间的用户事件将影响数据的准确性（如客户端时间错误导致导入未来的数据），故默认情况下对导入的事件时间进行了限制：
1. 使用客户端 SDK （iOS、Android）导入的数据，服务端默认只接收事件发生时间在接收时间向前 10 天内和未来向后 1 小时内的数据；
2. 使用后端语言 SDK （如 Java、Python 等）或导入工具（如 LogAgent、BatchImporter、HdfsImporter），默认只能导入事件时间当前向前 2 年
内和未来向后 1 小时内的数据；
注意：如果希望导入上述默认时间窗口之外的数据，可以联系值班同学修改窗口限制，或在数据中添加 `time_free` 字段（见本文档 2. track 样例）。添
加 `time_free` 字段也要保证 time 的格式满足 8.1 节的第 4 点。
因为 App 端只能使用客户端的时间作为事件发生的时间，如果客户端时间不准确，会导致采集端数据有异常，因此神策默认开启时间修正机制：
APP 端发生事件时的时间 time 的值为 t1，发送数据时的时间_flush_time 的值为 t2 （客户端时间，且 _flush_time 不入库），服务端接收到数据
的时间 $recive_time 时间为 t3 （服务端时间），如果 |t3-t2|>60s,则认为客户端的时间不准确，会对事件触发时间进行修正，修正后事件时间 t1
‘=t1+(t3-t2) 。
以下两种场景不会修正事件发生的时间：
如果采集事件时客户端时间不准确（即 t1 不准确，比如手机刚开机时间不准），而发送数据时客户端时间是准确的（_flush_time 时间准
确，比如开启网络校正时间功能），此时发送到服务端时，由于 |t3-t2|<60s，因此不会对 t1 进行修正。
如果数据是延迟上报（比如数据在发送之前用户强杀 App，导致部分数据未及时发送，会先缓存在本地，待下次打开 App，网络正常时会
重新尝试发送本地的缓存数据），发送数据时的 _flush_time 时间是准确的，也不会修复事件触发的时间。
1.7.3. 同名属性同类型
对 Event 属性，一个属性名，只能具有一种类型（不同的具体事件，同名属性类型也必须相同）；
对 Profile 属性，一个属性名，只能具有一种类型；
对于一个属性名，在 Event 和 Profile 中可以具有不同的类型；
1.7.4. 属性长度限制
属性的数据类型，及特殊字段长度限制如下：
项目 限制
数据类型 NUMBER -9E15 到 9E15 小数点后最多保留3位
数据类型 STRING 最大长度 1024 字节
数据类型 LIST 每个 LIST 中最多包含 500 个不大于 255 字节的字符串
用户 distinct_id 最大长度 255 字节
用户 original_id 最大长度 255 字节
1.7.5. 属性数上限
Event / Profile 的属性建议合理设置，过多影响导入和查询性能，达到上限则导致导入异常。
建议值 硬上限
300 以内 2000
1.7.6. 保留字段
为了保证查询时属性名不与系统变量名冲突，设置如下保留字段，请避免其作为事件名和属性名（properties 中的 key）使用：
date
datetime
distinct_id
event
events
first_id
id
original_id
device_id
properties
second_id
time
user_id
users
1.8. 常见问题
1.8.1. $is_login_id 参数说明
常见使用场景：历史数据导入的 events 或者 users 数据，服务端 SDK 的 track 或 profile 接口。属性值含义：true ，表示这条数据中的 distinct_id 字段的值为一个真实的 ID（例如客户的业务 ID），如果在这条数据进入数据库之前，此真实 ID 未和设备
ID 绑定，（绑定操作，前端可参考 login 方法，以 JavaScript SDK 为例，在登录和注册成功后，调用 sensor.login(userid); 来标识真实用户。服务端可参
考 tracksignup 方法，以 Java SDK 为例，历史数据导入可参考本文档的 tracksignup 接口。），那么这个真实 ID 会自关联，导致之后不能再和设备 ID 绑
定。
属性值含义：false，表示这条数据中的 distinct_id 字段的值为一个设备 ID（即客户注册登录之前的标识用户的 ID），之后此设备 ID 还可以和一个真实 ID
绑定。标识用户.标识用户 v1.13
选取合适的用户标识对于提高用户行为分析的准确性有非常大的影响，尤其是漏斗、留存、Session 等用户相关的分析功能。因此，我们在进行任何数据接
入之前，都应当先确定如何来标识用户。下面会介绍神策分析用户标识的原理，以及几种典型情况下的用户标识方案。
注意：不要在线上页面直接切换不同项目的数据接收地址，会导致首日首次，ID 异常。建议在线下测试时数据发到测试项目，没问题的话，线上采集的数据
直接发往正式项目。
1. 基本概念
神策分析使用 神策 ID (即 events 表里的 user_id 和 users 表里的 id )来对每个产品的用户进行唯一的标识，而 神策 ID 是基于 distinct_id 按照一定规则生
成的。一般来说，典型的 distinct_id 有以下两种：
1.1. 设备 ID
需要注意的是，设备 ID 并不一定是设备的唯一标识。例如 Web 端的 Cookies 有可能被清空（例如各种安全卫士），而 iOS 端的 IDFV 在不同厂商的 App
间是不同的。不过神策的客户端 SDK 已经做了各种处理。
SDK 规则
类型
Android 1.10.5 之前版本，默认使用 UUID（例如：550e8400-e29b-41d4-a716-446655440000），App 卸载重装 UUID 会变，为了保证设备 ID
不变，可以通过配置使用 AndroidId（例如：774d56d682e549c）；1.10.5 及之后的版本 SDK 默认使用 AndroidId 作为设备 ID，如果
AndroidId 获取不到则获取随机的 UUID。
iOS 1.10.18 及之后版本，如果 App 引入了 AdSupport 库，SDK 默认使用 IDFA 作为匿名 ID。1.10.18 之前版本，神策 SDK 会优先使用 IDFV
（例如：1E2DFA10-236A-47UD-6641-AB1FC4E6483F），如果 IDFV 获取失败，则使用随机的 UUID（例如：550e8400-e29b-41d4-
a716-446655440000），一般情况下都能够获取到 IDFV。如果使用 IDFV 或 UUID ，当用户卸载重装 App 时设备 ID 会变。也可以通过配置
使用 IDFA（例如：1E2DFA89-496A-47FD-9941-DF1FC4E6484A），如果开启 IDFA ，神策 SDK 会优先获取 IDFA，如果获取失败再尝试
获取 IDFV。使用 IDFA 能避免用户在重装 App 后设备 ID 发生变化的情况。
JavaSc 默认情况下使用 cookie_id（例如：15ffdb0a3f898-02045d1cb7be78-31126a5d-250125-15ffdb0a3fa40a），cookie_id 为神策
ript JavaScript SDK 默认生成的，存贮在浏览器的 cookie 中，规则为五段不同含义的字段拼接而成来保证唯一性，其中包括两段时间戳，一段屏
幕宽高，一段随机数，一段 UA 值。
微信小 默认情况下使用 UUID（例如：1558509239724-9278730-00c1875d5f63f8-41373096），但是删除小程序，UUID 会变。为了保证设备
程序 ID 不变，建议获取并使用 openid（例如：oWDMZ0WHqfsjIz7A9B2XNQOWmN3E）。 如果选择使用 openid 的话，请注意【操作暂存】，由
于获取 openid 是一个异步的操作，但是冷启动事件等会先发生，这时候这个冷启动事件的 distinct_id 就不对了。所以我们会把先发生的操作，
暂存起来，等获取到 openid 等后调用 sa.init() 后才会发送数据。 openid 的获取和操作暂存的方法，请参考此文档 微信小程序 API 1.3 及 1.4
的介绍
1.2. 登录 ID
登录 ID 通常是业务数据库里的主键或其它唯一标识。所以 登录 ID，相对来说更精确更持久。但是，用户在使用时不一定注册或者登录，而这个时候是没有
登录 ID 的。
登录 ID 会存在 users 表里的 second_id 字段
登录 ID 一旦确定尽量不要修改，如果需要修改请联系神策值班同学。
需要特别说明的是，神策分析里的用户是发生事件的主体，不一定是终端用户，也可以是一个企业、商家甚至是一辆汽车，需要根据具体的分析需求灵活决
定。
1.3. 方案详解
请注意，以下各方案之间互不兼容，请务必在正式接入之前选择一个最合适的方案
1.3.1. 方案一：只使用设备 ID
1.3.1.1. 适用场景
适合没有用户注册体系，或者极少数用户会进行多设备登录的产品，如工具类产品、搜索引擎、部分电商等。这也是绝大多数其它数据分析产品唯一提供的
方案。
1.3.1.2. 局限性
同一用户在不同设备使用会被认为不同的用户（神策 ID 不同，跟设备 ID 关联），对后续的分析统计有影响。
不同用户在相同设备使用会被认为是一个用户（神策 ID 相同，因为设备 ID 相同），也对后续的分析统计有影响。
但如果用户跨设备使用或者多用户共用设备不是产品的常见场景的话，可以忽略上述问题。1.3.1.3. 实施方法
直接使用客户端 SDK 产生的 设备 ID 作为 distinct_id 即可，不需要进行特殊处理。如果不希望使用神策 SDK 默认的 设备 ID 生成规则，可以直接
调用 identify 接口来传入自定义的 设备 ID ，该方法建议在 SDK 初始化完成之后立即调用。
如果是有用户注册体系的产品，可以额外在所有 Event 里加入 login_user_id 属性标识用户的正式 ID，这样也可以筛选出某个用户的具体行为，或
者单独看登录前/登录后的用户行为。
1.3.1.4. 案例
注意：X，Y 均有用户属性，所以即使 second_id 没值，也可以以 first_id 的形式写进用户表。
详细步骤说明如下：
1. 某用户在小米手机上新安装了 App，并进行了一系列操作，SDK 生成的设备 ID 为 X，发送的 distinct_id 为 X，对应分配的神策 ID 为 1，若客户端
SDK 调用接口 profile_set ，则将神策 ID 1 、设备 ID X 存入 users 表的 id, first_id 字段。
2. 该用户进行了注册并登录，设备未变，发送的 distinct_id 仍为 X，所以神策 ID 仍为 1。
3. 该用户登录之后继续进行一系列操作，发送的 distinct_id 仍 为 X，所以神策 ID 仍为 1。
4. 该用户退出登录并进行了一系列操作，发送的 distinct_id 仍为 X，所以神策 ID 仍为 1。
5. 该用户把手机送给朋友了，朋友用自己的账号登录（已注册但未接入神策系统）设备 X，但发送的 distinct_id 仍为 X，所以神策 ID 仍为 1。
6. 之后，该用户的朋友一直使用账号 B 在设备 X 上进行了一系列操作，由于设备未变，所以神策 ID 仍为 1。
7. 该用户更换了一个新的苹果手机，并进行一系列操作，由于设备 ID 变为 Y，发送的 distinct_id 为 Y，分配的神策 ID 为 2，若客户端 SDK 调用接口
profile_set ，则将神策 ID 2 、设备 ID Y 存入 users 表的 id, first_id 字段。
8. 该用户在苹果手机上使用账号 A 进行登录，发送的 distinct_id 为 Y，所以神策 ID 仍为 2。
9. 该用户登录之后的后续操作，都以神策 ID 2 标识，只要不更换设备。
在上述案例中，仅使用设备 ID 识别用户的好处就是逻辑很简单，当然局限性也很明显：
当用户换手机后，用户换手机前后的行为无法关联上。
当用户把手机送给朋友后，朋友的行为却仍记在该用户下。
1.3.2. 方案二：关联设备 ID 和登录 ID（一对一）
仅使用 设备 ID 标识用户虽然简单，但是对于某些应用场景这种方式不够准确，因此神策分析提供了另一种关联 设备 ID 和 登录 ID 的方案，在一定程度上
融合 设备 ID 和 登录 ID，从而实现更准确的用户追踪。
1.3.2.1. 适用场景
成功关联设备 ID 和登录 ID 之后，用户在该设备 ID 上或该登录 ID 下的行为就会贯通，被认为是一个神策 ID 发生的。在进行事件、漏斗、留存等用户相关分
析时也会算作一个用户。
关联设备 ID 和登录 ID 的方法虽然实现了更准确的用户追踪，但是也会增加埋点接入的复杂度。所以一般来说，我们建议只有当同时满足以下条件时，才考虑
进行 ID 关联：
1. 需要贯通一个用户在一个设备上注册前后的行为。
2. 需要贯通一个注册用户在不同设备上登录之后的行为。
1.3.2.2. 局限性
一个设备 ID 只能和一个登录 ID 关联，而事实上一台设备可能有多个用户使用。
一个登录 ID 只能和一个设备 ID 关联，而事实上一个用户可能用一个登录 ID 在多台设备上登录。
如果不遵循神策接口调用顺序，可能会导致部分用户标识异常（例如历史数据导入时），影响数据统计的准确性。1.3.2.3. 客户端接入实施方法
客户端接入是指使用 iOS / Android / JavaScript 等 SDK 进行埋点，具体调用流程如下：
1. 在 SDK 初始化完成之后，神策的 SDK 会自动生成一个设备 ID 作为用户标识。
2. 在用户注册成功、登录成功 、初始化 SDK（如果能获取到登录 ID）的时候，客户端主动调用 login(登录 ID) 接口。
3. 在用户注销的时候，有几种选择：
a. 不做任何操作，这样的话相当于神策会继续使用之前的用户标识来进行追踪。如果没有特殊情况，一般建议选择该方式。
b. 主动调用 logout() 方法，这样会清空登录 ID，重新使用设备 ID 作为用户标识，一般情况没有必要选择此方式。
c. 对于 JavaScript SDK，还可以调用 logout(true) 方法，该方法除了清空 登录 ID 之外，还会重新初始化设备 ID。
备注一：
SDK 前端获取前端缓存中 ID 的方法
类型
安卓 通过 getAnonymousId 方法 获取神策分析 SDK 分配的 匿名 ID，String AnonymousId=SensorsDataAPI.sharedInstance().getAnonymousId();
iOS 通过 anonymousId 方法可获取神策分析 iOS SDK 分配的 匿名 ID，获取当前用户的匿名id NSString anonymousId =
[[SensorsAnalyticsSDK sharedInstance] anonymousId];（swift 代 码 示 例 ：let anonymousId:String = SensorsAnalyticsSDK.
sharedInstance().anonymousId()）。
JavaSc 获取匿名 ID 的方法 sensors.quick(''getAnonymousID''); 返回匿名 id （SDK 版本 1.13.4 及以上支持）
ript
微信小 sensors.store.getDistinctId();
程序
1.3.2.4. 服务端接入实施方法
服务端接入包括使用 Java / Python / PHP 等 SDK，以及直接使用 BatchImporter / LogAgent / FormatImporter 等工具进行导入的情况，具体流程如
下：
在进行服务端埋点或者历史数据导入时，如果当前在 track 或者 profile_set 等接口里传入的 distinct_id 是一个 登录 ID，那么 is_login_id 的参数
值必须为 true，来告诉神策这是一个 登录 ID 产生的行为，以 Java SDK 为例：
如果是 登录 ID 产生的行为：sa.track(registerId, true, "SubmitOrderDetail", properties);
如果是 匿名 ID 产生的行为：sa.track(deviceId, false, "SubmitOrderDetail", properties);
对于任意一个 登录 ID ，只要导入过任意数据，那么该 登录 ID 后面将不能和任何 设备 ID 进行关联。因此在进行历史数据（即接入神策之前产生
的数据）的导入时，建议按照下面的方式操作：
先进行正常的 SDK 接入，并且保证所有用户都正常的通过了 login/track_signup 接口进行用户关联，在运行一段时间之后再导入历史数
据，因为这个时候大部分活跃用户都应该已经成功进行了关联。
如果历史数据中存在 登录 ID 和其对应 设备 ID 的对应关系，那么也可以先把这批数据构造 track_signup 请求进行导入，然后再导入具
体的用户行为或者用户属性数据即可。
由于客户端埋点存在一定的数据丢失概率，我们建议开发者也在服务端的注册接口里调用 track_signup 方法，将新用户的 设备 ID 和 登
录 ID 进行关联，以实现更准确的用户识别。
1.3.2.5. 案例
注意：Y 有用户属性，所以即使 second_id 没值，也可以以 first_id 的形式写进用户表。
详细步骤说明如下：1. 某用户在小米手机上新安装了 App，并进行了一系列操作，SDK 生成的设备 ID 为 X，发送的 distinct_id 为 X，对应分配的神策 ID 为 1，若客户端
SDK 调用接口 profile_set ，则将神策 ID 1 、设备 ID X 存入 users 表的 id, first_id 字段。
2. 该用户进行了注册并登录，其登录 ID 为 A，这里会调用 SDK 的 login（客户端）或 track_signup 接口（服务端），设备 ID X 和登录 ID A 关联成功，
并将登录 ID A 存入 users 表的 second_id 字段，神策 ID 仍为 1。
3. 该用户登录之后继续进行一系列操作，发送的 distinct_id 为 A，神策 ID 仍为 1。
4. 该用户退出登录并进行了一系列操作，发送的 distinct_id 为 A，SDK 不调用任何方法，仍使用神策 ID 1 来标识当前用户（因为登录 ID A 已与神策 ID 1
绑定）。
5. 该用户把手机送给朋友了，朋友用自己的账号（已注册但未接入神策系统）登录设备 X，登录 ID 为 B，此时神策 SDK 尝试将设备 ID X 与登录 ID B 进行
关联，由于 X 已与 A 关联，所以此次关联失败，同时会分配一个新的神策 ID 2 来标识此用户，并将登录 ID B 同时存入 users 表的 first_id 和 second_id
字段（用户的朋友账号上之前未关联过别的设备，且首次登录设备关联失败，则将登录 ID 同时记录到 first_id 上）。
6. 之后，该用户的朋友一直使用账号 B 在设备 X 上进行了一系列操作，发送的 distinct_id 为 B，神策都使用神策 ID 2 来标识此用户（因为登录 ID B 已与
神策 ID 2 绑定）。
7. 该用户更换了一个新的苹果手机，并进行一系列操作，由于尚未登录，此时神策使用全新的设备 ID Y 来标识此设备，发送的 distinct_id 为 Y，对应分配
的神策 ID 为 3，若客户端 SDK 调用接口 profile_set ，则将神策 ID 3 、设备 ID Y 存入 users 表的 id, first_id 字段。
8. 该用户在苹果手机上使用账号 A 进行登录，此时神策将尝试将设备 ID Y 与登录 ID A 进行关联，由于 A 已经与 X 关联，因此会关联失败，但是依然会切
换到以 A 为登录 ID 的用户，其对应的神策 ID 依然为 1。
9. 该用户登录之后的后续操作，发送的 distinct_id 为 A，所以仍以神策 ID 1 标识。
在上述案例中，很大程度上已经实现了跨设备的用户贯通，但仍存在局限性：
当用户换手机后，虽然登录账号之后的行为与换手机之前的行为贯通了，但是在新设备上首次登录之前的行为仍没法贯通，仍被识别为新的用户的
行为。
当用户把旧手机送给朋友之后，由于旧手机已被关联到自己的登录 ID 了，无法再与朋友的登录 ID 关联。后续使用这台旧手机的用户们，若不登录
就操作，则都会被识别为同一个用户（旧手机成功关联的登录 ID ）。
1.3.3. 方案三：关联设备 ID 和登录 ID（多对一）
关联设备 ID 和登录 ID（一对一）虽然已经实现了跨设备的用户贯通，但是对于某些应用场景还是不够准确，因此神策分析提供了新的关联方案，支持一个
登录 ID 绑定多个设备 ID 的方案，从而实现更准确的用户追踪。
1.3.3.1. 适用场景
一个用户在多个设备上进行登录是一种比较常见的场景，比如 Web 端和 App 端可能都需要进行登录。支持一个登录 ID 下关联多设备 ID 之后，用户在多设
备下的行为就会贯通，被认为是一个神策 ID 发生的。
1.3.3.2. 局限性
一个设备 ID 只能和一个登录 ID 关联，而事实上一台设备可能有多个用户使用。
一个设备 ID 一旦跟某个登录 ID 关联或者一个登录 ID 和一个设备 ID 关联，就不能解除（自动解除）。而事实上，设备 ID 和登录 ID 的动态关联才
应该是更合理的。
1.3.3.3. 实施方法
客户端和服务端的实施方法与方案二完全相同，神策服务端的处理行为会不一样：
对于已经关联过设备的登录 ID，仍然可以和新的设备 ID 进行关联，并存入users 表新增字段 $device_id_list （关联用户 id 列表） 中。
例行任务每天读取 users 表中需要修复的 id 列表，即 $device_id_list。读取过去 2 天的所有 events 数据，找到需要修复的数据。修改其中的
user_id 字段与 profile 表中对应的 id 字段保持一致。
1.3.3.4. 案例详细步骤说明如下：
1. 某用户在小米手机上新安装了 App，并进行了一系列操作，SDK 生成的设备 ID 为 X，发送的 distinct_id 为 X，对应分配的神策 ID 为 1，若客户端
SDK 调用接口 profile_set ，则将神策 ID 1 、设备 ID X 存入 users 表的 id, first_id 字段。
2. 该用户进行了注册并登录，其登录 ID 为 A，这里会调用 SDK 的 login（客户端）或 track_signup 接口（服务端），设备 ID X 和登录 ID A 关联成功，
并将登录 ID A 存入 users 表的 second_id 字段，神策 ID 仍为 1。
3. 该用户登录之后继续进行一系列操作，发送的 distinct_id 为 A，神策 ID 仍为 1。
4. 该用户退出登录并进行了一系列操作，发送的 distinct_id 为 A，SDK 不调用任何方法，仍使用神策 ID 1 来标识当前用户（因为登录 ID A 已与神策 ID 1
绑定）。
5. 该用户把手机送给朋友了，朋友用自己的账号（已注册但未接入神策系统）登录设备 X，登录 ID 为 B，此时神策 SDK 尝试将设备 ID X 与登录 ID B 进行
关联，由于 X 已与 A 关联，所以此次关联失败，同时会分配一个新的神策 ID 2 来标识此用户，并将登录 ID B 同时存入 users 表的 first_id 和 second_id
字段（用户的朋友账号上之前未关联过别的设备，且首次登录设备关联失败，则将登录 ID 同时记录到 first_id 上）。
6. 之后，该用户的朋友一直使用账号 B 在设备 X 上进行了一系列操作，发送的 distinct_id 为 B，神策都使用神策 ID 2 来标识此用户（因为登录 ID B 已与
神策 ID 2 绑定）。
7. 该用户更换了一个新的苹果手机，并进行一系列操作，由于尚未登录，此时神策使用全新的设备 ID Y 来标识此设备，发送的 distinct_id 为 Y，对应分配
的神策 ID 为 3，若客户端 SDK 调用接口 profile_set ，则将神策 ID 3 、设备 ID Y 存入 users 表的 id, first_id 字段。
8. 该用户在苹果手机上使用账号 A 进行登录，此时神策将设备 ID Y 与登录 ID A 进行关联，关联成功，对应的神策 ID 依然为 1，同时将设备 ID Y 添加到
users 表中神策 ID 1 的 $device_id_list 字段。
9. 该用户登录之后的后续操作，发送的 distinct_id 为 A，所以仍以神策 ID 1 标识。
后续修复如下：
由于设备 Y 被关联到登录 ID A 下，修复设备 Y 上登录之前的数据：神策 ID 3 ->神策 ID 1。需要注意的是，对于要修复的数据，使用新的
user_id 生成新的 parquet 文件。对于被修复的文件暂时不进行修改，只在索引中进行标记哪些数据已经在源文件中失效。
同时将 users 表中神策 ID 3 的用户属性合并到神策 ID 1 上，并删除users 表中神策 ID 3 这条数据。
在上述案例中，真正实现了跨设备的用户贯通，通过修复解决了方案二中换手机登录之前的行为贯通问题，但仍存在局限性：
一个设备只能关联到一个登录 ID 下，当用户把旧手机送给朋友之后，由于旧手机已被关联到自己的登录 ID 了，无法再与朋友的登录 ID 关联。后续
使用这台旧手机的用户们，若不登录就操作，则都会被识别为同一个用户（旧手机成功关联的登录 ID）。
而事实上，旧手机上后续的匿名登录很难识别到底是谁，可能归为匿名登录之前最近一次登录的用户会更合理一些。
1.4. 方案对比
将上述三个方案放到一起，可以明显看到三种方案的区别，如下表所示：
事件序号 事件 神策 ID_方案一 神策 ID_方案二 神策 ID_方案三
1 安装 App 1 1 1
2 登录 App 1 1 1
3 使用 App 1 1 1
4 使用 App 1 1 1
5 登录 App 1 2 2
6 使用 App 1 2 2
7 使用 App 2 3 3->1
8 使用 App 2 1 1
9 使用 App 2 1 1
方案一：仅使用设备 ID，不管用户是谁，只要设备未变（设备 ID 未变），神策 ID 不变。
方案二：关联设备 ID 和登录 ID（一对一），
当用户换手机后，登录账号之后的行为与换手机之前的行为贯通了，但是在新设备上首次登录之前的行为仍没法贯通，仍被识别为新的用
户的行为。
当用户把旧手机送给朋友之后，由于旧手机已被关联到自己的登录 ID 了，无法再与朋友的登录 ID 关联。后续使用这台旧手机的用户们，
若不登录就操作，则都会被识别为同一个用户。
方案三：关联设备 ID 和登录 ID（多对一）
当用户把旧手机送给朋友之后，由于旧手机已被关联到自己的登录 ID 了，无法再与朋友的登录 ID 关联。后续使用这台旧手机的用户们，
若不登录就操作，则都会被识别为同一个用户）。
而事实上，旧手机上后续的匿名登录很难识别到底是谁，可能归为匿名登录之前最近一次登录的用户会更合理一些。
其实，三种方案没有对与错，建议客户结合产品的应用场景以及埋点复杂度来选择合适的方案。
准确的标识用户其实是一个很复杂的问题，神策一直致力于寻求更合理、更准确的方法，满足各种应用场景。新增用户及首日首次标记.新增用户及首日首次标记 v1.13
注意：不要在线上页面直接切换不同项目的数据接收地址，会导致首日首次，id 关联异常。建议在线下测试时数据发到测试项目，没问题的话，线上采集的
数据直接发往正式项目。
1. 新增用户
一般我们对新增用户的定义是第一次使用产品的用户，或者是一些关键行为（比如注册、购买）的首次触发。在神策分析中，可以结合 是否首日访问(
$is_first_day ) 属性来得到每天访问的新增用户，以及结合 是否首次触发事件( $is_first_time )属性来得到首次触发关键事件的用户。
1.1. 新增用户指标配置
Web 端新增用户定义：当日的独立访客中，历史上首日访问网站的访客定义为新用户。
App 端新增用户定义：当日启动 App 的用户中，历史上首日启动 App 的用户为新用户数。
小程序端新增用户定义：当日启动小程序的用户中，历史上首日启动小程序的用户为新用户数。用户首次访问时间分布：用户第一次使用 Web/App/小程序 的时间分布
首次触发事件定义：第一次触发 APP 启动/Web 浏览/小程序启动的新用户1.1.1. 新增用户标记采集
新用户的标记主要是在客户端完成，神策 SDK 默认会采集的区分新增用户的字段有
前端事件公共属性：是否首日访问（$is_first_day）
字段名称 类型 说明 JS SDK 自动采集 iOS SDK 自动采集 Android SDK 自动采集 小程序 SDK 自动采集 服务端 SDK 自动采集
$is_first_day 布尔值 是否首日访问 Y Y Y Y N
实现逻辑：
1. Web 端：用户第一次访问埋入神策 SDK 页面的当天（即第一天），JS SDK 会在网页的 cookie 中设置一个首日访问的标记，并设置第一天 24 点之前，
该标记记为首日为 true，即第一天触发的网页端所有事件中，$is_first_day=true。第一天之后，该标记则为 首日为 false，即第一天之后触发的网页端所有
事件中，$is_first_day= false；
2. 小程序端：用户第一天访问埋入神策 SDK 的页面时，小程序 SDK 会在 storage 缓存中创建一个首日为 true 的标记，并且设置第一天 24 点之前，该标
记均为 true。即第一天触发的小程序端所有事件中，$is_first_day=true。第一天之后，该标记则为 首日为 false，即第一天之后触发的小程序端所有事件
中，$is_first_day= false；
3. APP 端：用户安装 App 后，第一次打开埋入神策 SDK 的 App 的当天，Android/iOS SDK 会在手机本地缓存内，创建一个首日为 true 的标记，并且设
置第一天 24 点之前，该标记均为 true。即第一天触发的 APP 端所有事件中，$is_first_day=true。第一天之后，该标记则为 首日为 false，即第一天之后
触发的 APP 端所有事件中，$is_first_day= false；
前端事件属性：是否首次触发事件（$is_first_time）
字段名称 类型 说明 JS SDK 自动采集 iOS SDK 自动采集 Android SDK 自动采集 小程序 SDK 自动采集 服务端 SDK 自动采集
$is_first_time 布尔值 是否首次触发事件 Y Y Y Y N
实现逻辑：
本地针对 $pageview／$AppStart／$MPLaunch 事件存储一个标记。标记默认是 no，首次为把 no 修改为 yes，之后都是 no。
用户属性：首次访问时间（$first_visit_time）
字段名称 类型 说明 JS SDK 自动采集 iOS SDK 自动采集 Android SDK 自动采集 小程序 SDK 自动采集 服务端 SDK 自动采集
$first_visit_time Datetime 首次访问时间 Y Y Y Y N
实现逻辑：
1. Web 端、小程序端：集成神策 Js、MiniProgram SDK 后，设置 autotrack 开启全埋点，SDK 会默认在用户第一次浏览页面/启动小程序时，调用
profile_set_once 接口给用户设置首次访问时间属性。
2. APP 端：集成神策 iOS、Android SDK 后调用 trackInstallation 接口，调用此接口之后会在用户首次使用 app 的时候设置首次访问时间属性。如果没有
调用 trackInstallation 接口，不会主动设置首日访问时间。
1.2. 首次首日标记修正
如果用户的 App 缓存被清理或者用户卸载重装后，如果匿名 ID 不变的话都会造成 App 端目前的首日首次判断逻辑失效，虽然是老用户，但是首日首次属性却
为 true。为了避免此种情况造成的新增用户不准的问题，神策服务端增加了首日首次的修正功能。1.2.1. 首日访问在服务端的修正
从神策分析 1.8 版开始，所有的单机版用户和集群版用户已经默认开启了“是否首日访问”标记在服务端的修正，即以一个专用的数据库记录用户首日访问的时
间。当上报的事件包含 $is_first_day （是否首日访问）属性并且取值为 true 时，服务端导入这条事件时会先在数据库中以触发的 Distinct Id 对应的神策内
部 Id 进行查询，若没有查到，那么在数据库中记录该 Distinct Id 首日访问的时间；如果可以查到那么判断本次事件触发时间与之前记录的是否是同一
天，若不是同一天（无论是之前的时间还是之后的时间）那么修改 $is_first_day 为 false。
这在一定程度上解决了 App 卸载重装被算作新用户的问题，例如 App 重装后设备里存的 "首日标记"被删除，那么客户端向服务端上报时 $is_first_day 的值
为 true，服务端可以根据数据库中的记录判断该值是否应该被修正为 false 。
在判断新增用户时，神策是选择【App 启动是否首日为真】判断的。如果客户在接入神策之前有一批历史用户，正常接入神策后，由于神策没有保存这些历史
用户的首日访问时间，会将这批老用户标记为新增用户。如果想将这批历史用户正确标记为老用户,需要在他们的数据上报之前就将他们的首日访问时间导入到
该数据库。导入步骤如下：
1. 生成一个文件，每行为一个用户的 Distinct Id 和首日访问时间（以 unix 时间戳表示）：
6D92078A-8246-4BA4-AE5B-76104861E7DC 1513577063
5D3169E2-16BC-316C-12AB-1E2EC1A79E2B 1512057600
注意：
该文件上传之后，只对上传日期之后入库的数据有效。早于首日访问时间文件上传时间的入库的数据无法修改；
服务端会根据上传的首日访问时间，对实时导入的事件属性 $is_first_day（是否首日访问）取值为 true 修正，修正规则是仅对 $is_first_day 为
true 的属性值进行修复，且只要导入的事件的 time 和服务端记录的首次访问时间不是同一天就会修正为 false（包含 time 早于服务端的时间也会
修正 ）。不会修复 $is_first_day 为 false 的属性值。
$first_visit_time $first_visit_time
服务端上传的首日访问时间，不会 对 $is_first_time 的属性进行修正。目前不支持提前在服务端上传首次访问时间，对 $is_first_time = true 的属
性进行修正。只有在导入过 $is_first_time = true 事件数据之后，服务端才能记录该事件的首次访问时间。
2. 如果文件中的 Distinct Id 是设备 ID（参考标识用户），继续下一步。若 Distinct Id 是登录 ID，则需要通过 SDK 或导入工具对每个 ID 导入一条
profile_set，设置 is_login_id 为 true，properties 可以为空。例如 Java SDK 可以调用：
sensorsAnalytics.profileSet("123456789", true, Collections.emptyMap());
3. 登录神策服务器，使用 sa_cluster 用户执行：
java -cp ''/home/sa_cluster/sa/extractor/lib/extractor-1.0-SNAPSHOT.jar:/home/sa_cluster/sa/commonjars/*'' com.
sensorsdata.analytics.extractor.utils.ImportFirstTimeUtils --project --file --is_login_id distinct_id ID
yes no
1.2.2. 首次触发事件在服务端的修正
目前神策预制采集的“是否首次触发事件” 只针对 $pageview/$AppStart/$MPLaunch 事件才会采集，并不是所有事件都会有这个属性。如果需要对自定义事
件添加 $is_first_time 属性，可参考 1.2.2.2 。
在一些分析场景中，我们希望可以通过一个事件属性判断该事件（自定义事件，前端和后端事件皆可）是否是某个用户首次触发，例如 App 启动中的这个属
性可以判断用户是否首次启动 App，加入购物车事件中的这个属性可以判断用户是否首次将商品加入购物车。这就需要我们针对“启动”，“购物”事件来增加
$is_first_time 属性来判断是否是触发关键事件的新用户。
1.2.2.1. 导入时添加字段
在导入事件时，若认为这次事件 可能 是该用户（distinct_id）首次触发，设置 $is_first_time 的值为 true 即可。其原理是神策后端导入模块在数据导入过
程中会在遇到 $is_first_time 的值为 true 时判断和 修正 该值，具体来说，若遇到 $is_first_time 的值为 true 的事件数据，神策后端会在数据库查询该用户
在该事件是否有首次访问记录，若已记录的触发时间与本次不同，那么将修改 $is_first_time 的值为 false，否则将记录该用户首次触发事件时间并保持
$is_first_time 值为 true。
1.2.2.2. 自定义事件设置首次触发事件属性示例
以 Java SDK 为例：
// "BuyGold""$is_first_time" true true
properties.put("$is_first_time", true);
sa.track("user1", false, "BuyGold", properties);
// do something else ...
// "BuyGold""$is_first_time" true falseproperties.put("$is_first_time", true);
sa.track("user1", false, "BuyGold", properties);
虽然两次都设置了 $is_first_time 为 true，但实际导入后仅第一次导入的值为 true。
1.2.2.3. 注意事项
仅当 $is_first_time 值为 true 时会触发上述逻辑；
若之前导入数据没有设置过 $is_first_time 值为 true，那么第一次出现时才会记录首次触发时间，并且以后以这次时间判断；
该逻辑里判断是否首次触发是以事件触发时间（精确到毫秒）是否与数据库里的值相等作为条件，若两次触发事件时间相同且都设置了
$is_first_time 值为 true 将不会进行修正；一般情况下不会发生这种情况，例如 App 连续发送两次事件，若第二次已经明确知道不是首次时，不应
该设置 $is_first_time 值为 true；
该逻辑受数据导入顺序影响，例如先导入 6 日数据并标记了首次，再导入 3 日的数据并标记了首次，最终 6 日的数据首次被标记为 true，而 3 日
的将被标记为 false；
本功能在 1.8 及以后的版本中支持，且构建时间（可在后端的关于页面查看）在 2017-11-26 之后，否则需要先进行升级。多项目.多项目 v1.13
1. 使用场景
神策分析的多个项目之间，数据、元数据、账号、权限、token、数据概览和书签都是完全隔离的，仅共享机器资源。
它适用于如下的一些使用场景：
1. 有多个完全没有关系的产品，都需要使用神策分析，并且它们之间的数据并不需要关联在一起分析。在这种情况下，可以给每一个产品创建一个单
独的项目，每个产品的数据分别导入对应的项目，然后再在每个项目里面，分别进行账号创建、权限设置、概览创建和分配等工作；
2. 创建一个项目用于开发和测试。神策分析已经在正常接入数据和使用了，而还需要一个环境用于开发和调试，则可以新创建一个项目，例如叫做 测
试环境 ，来用于开发和调试；
3. 有多个不同的分析角度，例如一个租车产品，分别从车和人的角度来进行分析。在这种情况下，可以考虑用两个项目，分别解决车的分析需求和人
的分析需求，然后将以车为“用户ID”的事件和 profile 相关操作，发给车所对应的项目，将以人为用户ID”的事件和 profile 相关操作，发给人所对应的
项目。
对于下述场景，则不适合使用多项目：
虽然是不同的产品，但是用户体系是统一的，并且也期望能够将这些产品的用户行为在一起进行分析，例如，想分析不同产品之间总的 PV 和 UV 等，则并
不适宜于创建多个不同的项目，而依然是需要将这些产品的数据导入到同一个项目中。
1.1. 创建和管理多项目
我们目前提供了工具来用于创建和管理多项目，这个工具的使用方法请参见 多项目管理工具使用说明。
1.2. 登录时选择不同的项目
在登录某个具有多项目的神策分析实例时，会让用户选择登录哪个项目，如下图所示：
特别提醒，不同项目之间账号是完全隔离的。
在登录成功后，可以从左上角察看当前是哪一个项目的环境，如下图所示：而之前在这里显示的神策分析的版本信息，则移动到了右上角的如图位置。
1.3. 数据导入
使用各种 SDK、导入工具或者直接使用导入 API 来导入数据都支持多项目了，具体导入方法可以察看相应的文档。
每个项目的导入地址，依然是按照如下的方式获取：
1.4. 自定义查询 API
使用自定义查询 API 从系统中获取数据，可以察看 查询 API 相关的文档。1.5. 重置项目
重置项目可以清空项目中 所有数据，包括所有行为事件、用户属性、书签、概览以及除 admin 外所有用户帐号。该操作不可逆，请谨慎操作！！
点击神策分析 页面右上角的用户名，在下拉菜单中点击 关于，点击“重置项目”，在弹出的窗口中输入确认信息：
确定后需要大约 30 秒进行处理，处理结束后将跳转至登录界面。
重置后请使用 admin 账户登录，密码与重置前相同；
重置将清除 project 的所有数据，包括 admin 之外的其他所有用户；
当重置或删除项目达到一定次数，需要手动回收资源才能再次进行重置，回收资源请参考文档 多项目管理工具使用说明。.基础知识 v1.17
客户端 SDK
服务端 SDK
数据导入
总体流程
神策分析提供了非常完备的数据接入方案，无论您的产品采用哪种技术架构，都可以非常容易的接入神策系统。
一般情况下，进行一次完整数据接入的流程如下：
1. 理解神策分析的基本概念，了解神策是干什么的，尤其是需要重点阅读 数据模型 的说明。
2. 如果有对应的神策数据分析师协助，请确认已经拿到对应的数据采集方案，其中应当包含了所有的事件及属性的设计建议。
3. 如果是使用私有部署的方案，请和相关运维同事确认已经配置好正确的数据接入地址。如果对这一点不确定，请联系神策技术支持。
4. 测试数据和正式数据应该接入到不同的项目中，具体概念请参考 多项目。
5. 根据数据采集方案和相关需求，按需要进行具体的接入工作，例如在客户端实施埋点或者导入历史数据，详情参考第二节。
6. 进行数据测试和验证，完成验证之后再上线到正式的环境。
以上流程仅供参考，如有任何疑问请联系您的神策咨询顾问。
接入步骤
要点说明
1. 无论使用哪种接入方式，建议先阅读 数据格式，更好的理解神策数据接入的原理。
2. 建议开发的时候使用 调试模式 测试数据采集的正确性和追查问题。
注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用
Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
3. 经常使用 埋点管理 查看接入的详细情况。
4. 严格按照数据采集方案的定义来进行埋点，尤其注意不同来源（例如安卓/iOS，或者历史数据等）的事件、属性需要统一考虑，以免出现定义的冲
突，尤其是数据类型的定义。例如以下是一些典型的错误用法：
a. Android 支付事件叫 pay_order，iOS 的支付事件叫 PayOrder，这样会造成使用和理解上的困难。
b. Android 端的金额属性叫 money，类型是数字，而 iOS 端使用的是字符串类型，会导致数据无法导入。
5. 一个属性的类型由首次导入时的类型决定，后续导入只接受相同类型的输入， 类型不一致的输入数据会被整条拒绝。
6. 事件名称、属性名称、属性类型在一般情况下是不能修改的，请务必确认事件属性设计之后再进行数据接入。如果是测试阶段中有事件、属性的变
更，可以使用项目重置功能来重新初始化测试环境：多项目管理工具使用说明。
如何标识用户
所谓标识用户，是指选择一个合适的标识符（例如设备 ID 或者注册 ID）作为 distinct_id 来发送数据到神策。是否选择了合适的 distinct_id 对数据分析的准
确性会有很大影响，因此，在进行任何数据接入之前，都应当先确认您的用户标识方式。神策分析提供了灵活、强大的用户标识能力，您可以根据自己的需
求来选择合适的方案，具体请阅读文档 标识用户。如果您依然不确定如何进行用户标识，请联系神策的数据分析师。
客户端埋点
如果您不需要从客户端接入数据，可以跳过此段。
客户端接入目前有以下几类方案：
1. 直接使用神策客户端 SDK（.客户端 SDK v1.13）。这个方案相对简单、易用，并且神策 SDK 提供了更多内置的功能（例如 渠道追踪 等）和可靠
性保证（例如网络不好的情况下延迟发送）。同时神策的所有 SDK 都是完全开源的，不用担心有后门之类的安全问题。一般情况下，我们建议采用
此方案。
2. 使用已有的业务 API，把埋点需要的数据同步传到业务服务器，然后在服务端再使用神策的服务端 SDK（Java SDK） 进行接入。这个方案本质上
其实是服务端埋点，优点是对于业务统计可能会更加准确（因为和业务调用是同步的），安全性比较高（可以进行一定的客户端加密来增大伪造数
据的难度），缺点是实施难度较大。我们一般建议对于关键的业务事件（例如购买、支付等）采用这种方案。
3. 使用自己的埋点 SDK。如果您已经使用了自己的埋点 SDK，并且已经比较完善了，那么可以继续使用此方案，然后和方案 2 一样通过服务端接
入。
4. 如果您使用的是神策暂时不支持的客户端（例如 PC / Mac 软件），那么可以使用方案 2 或者方案 3，当然 也可以在客户端直接使用神策的 数据
接入 API 进行接入。
服务端埋点
如果您不需要从服务端接入数据，可以跳过此段。
不管是客户端的埋点数据通过 API 发送给服务端之后，还是直接在服务端的已有业务逻辑里直接埋点，都属于服务端接入。服务端接入可以使用 服务端
SDK 等 SDK，每个 SDK 均有不同类型的发送方案（即 Consumer）可以选择，有两大类方案：1. 使用直接发送数据的 Consumer（例如 Java 的 AsyncBatchConsumer），实时的发数据给神策的服务。优点是方便简单，缺点是在机器故障或者
超大流量的极端情况下可能会丢失一小部分数据，并且可能对业务造成一定影响。如果数据量不大可以使用此方案。
2. 使用写入本地日志的 Consumer（例如 Java 的 LoggingConsumer），配合 LogAgent 进行导入。优点是因为有本地持久化，可靠性会更高，缺点
是代码会稍微复杂，同时还需要自己负责本地日志的存储和删除等运维操作。建议在大数据量或者对数据准确性有高要求的时候使用此方案。
在一般情况下，我们都建议在服务的入口处（例如 MVC 的 Controller 层）进行埋点，这样既能获取到大部分埋点所需要的数据，又方便统一管理：如果有
埋点额外需要的客户端数据（例如设备信息），可以通过 API 参数传入；对于埋点需要的业务数据（例如下单事件的优惠信息），则可以通过业务处理模块
返回给 Controller 层。
工具导入（历史数据导入）
如果您没有历史数据需要接入，可以跳过此段。
对于已经存在的历史数据，无论是事件还是用户属性，我们都建议使用 Java SDK／PHP SDK SDK 生成特定格式的数据，然后使用 LogAgent（SaaS
版）、BatchImporter小数据量/私有部署） 或者HdfsImporter（大数据量/私有部署/集群版）等工具进行导入。也可以不使用 SDK，直接按照数据格式里
的说明生成数据并导入。
一般情况下，历史数据即可以先导入，也可以等实时数据正式接入之后再导入，不影响最终的分析结果。但是如果使用了login / track_signup，则请务必阅
这里的 标识用户，避免导入数据顺序不对导致的用户 ID 关联错误。
用户属性的接入
用户属性（Profile）是可选的，如果您的业务里并不需要接入用户属性，可以跳过此段。
事件（Event）总是在事件发生的时候进行 track，而用户属性（Profile）则不是那么固定，而是根据不同属性会有所不同，主要还是取决于具体属性的获取
方式，一般来说主要有以下几种方式：
1. 伴随事件的发生：例如神策提供的客户端 SDK 会默认在用户首次访问的时候，设置用户的 首次访问时间 等属性。类似的，您也可以主动在用户首
次购买的时候调用 profile_set_once 设置一个 首次购买时间 的属性。
2. 在属性修改时接入：即在某个用户属性被修改的时候（例如修改用户资料的接口）同时调用 profile_set 系列接口。
3. 定时同步导入：即定时从业务数据库或者其它数据源中导出数据，然后用 LogAgent／BatchImporter 导入神策系统。这里应该尽量用最后更新时间
之类的字段来实现增量导入，否则每次全量导入可能会影响性能。
4. 实时同步导入：例如 MySQL 可以使用 Applier 来对数据的 Binlog 进行实时解析和同步，其它数据库也可以使用类似的工具。此方案的优点是不用
修改已有业务代码，耦合性较低，但是需要根据具体数据库类型进行额外的开发。
由于用户属性的导入效率会低于事件，因此应该尽量避免非必要的 profile 操作，例如在数据没有变化的情况下重复更新某一个 profile。SDK.SDK v1.13
客户端 SDK
服务端 SDK
公共属性
预置事件与预置属性客户端 SDK.客户端 SDK v1.13
Android SDK
iOS SDK
Web JS SDK
小程序
App 第三方框架
C++ SDK
macOS SDK
打通 App 与 H5
App 合规性操作Android SDK.Android SDK v1.13
欢迎使用神策分析 Android SDK！
基本使用(Android)
全埋点(Android)
常见问题(Android)
高级功能(Android)
全埋点插件配置(Android)
OAID使用(Android)
新书推荐《Android 全埋点解决方案》
在使用前，请先阅读 数据模型 的介绍
SDK 的更新日志，可参阅 Release Notes
插件 的更新日志，可参阅 Release Notes
1. 集成神策分析 SDK
1.1. 引入插件
在 project 级别的 build.gradle 文件中添加 Sensors Analytics android-gradle-plugin 依赖：
buildscript {
repositories
{ jcenter(
)
}
dependencies {
classpath ''com.android.tools.build:gradle:3.6.2''
// android-gradle-plugin
classpath ''com.sensorsdata.analytics.android:android-gradle-plugin2:3.2.0''
}
}
allprojects {
repositories
{ jcenter(
)
}
}
Sensors Analytics android-gradle-plugin 的最新版本号请参考 GitHub 更新日志。
如下示例图：1.2. 引入 SDK
在 主 module 的 build.gradle 文件中添加 com.sensorsdata.analytics.android 插件、神策分析 SDK 依赖：
apply plugin: ''com.android.application''
// com.sensorsdata.analytics.android
apply plugin: ''com.sensorsdata.analytics.android''
dependencies {
// Sensors Analytics SDK
implementation ''com.sensorsdata.analytics.android:SensorsAnalyticsSDK:4.0.2''
}
SensorsAnalyticsSDK 的最新版本号请参考 GitHub 更新日志。
如下示例图：
Android SDK 要求最低系统版本为 API 9（Android 2.3）。AutoTrack 功能要求系统最低版本为 API 14 （Android 4.0）如果 API 低于
14 开启 AutoTrack 后 将不能采集 $AppStart、$AppViewScreen、$AppEnd 事件。
目前，Android SDK ( aar 格式) 大小约为 300 KB。
1.3. 权限配置说明SDK 共需要四个权限
权限 用途
INTERNET 必须权限，允许应用发送统计数据，SDK 发送埋点数据需要此权限
ACCESS_NETWORK_STATE 必须权限，允许应用检测网络状态，SDK 会根据网络状态选择是否发送数据
READ_PHONE_STATE 可选权限，允许应用获取设备 IMEI，采用 App 内推广 和采集 $carrier 属性时会用到此权限
ACCESS_WIFI_STATE 可选权限，允许应用获取 MAC 地址，采用 App 内推广 时会用到此权限
如何删除在 AndroidManifest.xml 中已注册权限？
神策 SDK 为简化开发者集成步骤，默认在 AndroidManifest.xml 中注册了以上四个权限，如果开发者不需要其中某个权限，可以使用 tools:node="
remove" 属性删除，打包后的 AndroidManifest.xml 文件将不再包含此权限，关于 tools:node="remove" 的详细说明可参考谷歌 官方文档，配置
参考代码如下：
如果不是特殊要求，可不配置此代码
2. 获取数据接收地址
数据接收地址是 SDK 上报数据的目标地址，需要使用管理员账户进行获取。3. 初始化 SDK 并开启全埋点
一定需要在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfigOptions(SAConfigOptions) 并且
在 主线程 中初始化 SDK：
// SDK
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// SAConfigOptions SA_SERVER_URL
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions SDK SAConfigOptions
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK | //
SensorsAnalyticsAutoTrackEventType.APP_START | //
SensorsAnalyticsAutoTrackEventType.APP_END | //
SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN) //
.enableLog(true) //()
.enableTrackAppCrash(); // crash
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。一旦成功初始化后，则可以通过 sharedInstance 获取 SDK 实例，进
行用户行为事件或属性的追踪。
注意：利用 SAConfigOptions 设置全埋点类型、开启 crash 采集时等操作时，只有 SDK 第一次初始化时有效。请勿对多个 SAConfigOptio
ns 对象进行相关设置
4. 代码埋点
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户浏览商品和下订单等事件
神策分析 SDK 成功初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。以电商产品为例，可以这样追踪一次购物行为：
// ...
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456); // ID
properties.put("ProductCatalog", "Laptop Computer"); //
properties.put("IsAddedToFav", false); //
SensorsDataAPI.sharedInstance().track("ViewProduct", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
// ...
try {
JSONArray orderList = new JSONArray();
orderList.put("Apple iPhone6s");
orderList.put("Nexus 6");
JSONObject properties = new JSONObject();
properties.put("OrderPaid", 50.10); //
properties.put("OrderList", orderList); //
properties.put("OrderDate", new Date()); //
SensorsDataAPI.sharedInstance().track("PaidOrder", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
触发事件后，在神策分析中稍等片刻，便能看到追踪结果。5. 事件属性
每个事件可以设置多个事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属性可以作为统计过滤条件
使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 JSONObject 对象
JSONObject 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型
JSONObject 中，每个元素的 Value 是属性的值，支持 String、Number、Boolean、JSONArray 和 Date，对于 JSONArray，其中所有元素必须是
String 类型
5.1. 设置静态公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件静态公共属性。例如添加应用程序
名称为事件的公共属性，设置方法如下:
// track() "AppName"
try {
JSONObject properties = new JSONObject();
properties.put("AppName", getAppName(this));
SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e)
{ e.printStackTrace();
}
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中，例如：
//
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456);
SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
在设置事件公共属性后，实际发送的事件中会被加入 AppName 属性，等价于//
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456);
properties.put("AppName", getAppName(this));
SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
重复调用 registerSuperProperties() 会覆盖之前已设置的公共属性，公共属性会保存在 App 本地 SharedPreferences 中。可以通过 unregiste
rSuperProperty() 删除一个静态公共属性，使用 clearSuperProperties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。
1. 请在初始化 SDK 后立即调用 registerSuperProperties() 方法，确保每个事件都会添加已设置的公共属性。
2. 神策事件属性大小写敏感（ 详见 数据格式 ），设置公共属性前需确保事件表中不存在仅大小写不同的同名属性，否则会导致所有事件
因存在同名属性而不能入库。
5.2. 设置动态公共属性
Android SDK 2.0.1 及以后的版本可以通过 registerDynamicSuperProperties() 方法设置动态公共属性，设置之后 SDK 会自动获取
getDynamicSuperProperties 中的属性添加到触发的事件中。
// SDK
SensorsDataAPI.sharedInstance().registerDynamicSuperProperties(new SensorsDataDynamicSuperProperties()
{ @Override
public JSONObject getDynamicSuperProperties()
{ try {
// isLogin() SDK getDynamicSuperProperties
boolean bool = isLogin();
return new JSONObject().put("isLogin",bool);
} catch (Exception e)
{ e.printStackTrace(
);
}
return null;
}
});
调用 registerDynamicSuperProperties 方法设置的动态公共属性，不能用 unregisterSuperProperty 方法删除
6. 记录激活事件
可以调用 trackInstallation 方法记录激活事件，多次调用此方法只会触发一次激活事件（触发激活事件时会自动保存 $first_visit_time 首次访
问时间属性到用户表）。
触发激活事件时会尝试获取 IMEI 号，请动态申请 android.permission.READ_PHONE_STATE 权限后再调用 trackInstallation 。
例如，在 Activity 的 onCreate 方法中申请权限：
if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.
PERMISSION_GRANTED) {
// 6.0 READ_PHONE_STATE
ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
} else {
// 6.0 trackInstallation()
trackInstallation();
}
} else {// 6.0 trackInstallation()
trackInstallation();
}
在权限回调的 onRequestPermissionsResult 方法中，调用 trackInstallation
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[]
grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
if (requestCode == 100) {
// trackInstallation()
trackInstallation();
}
}
/**
*
*/
private void trackInstallation()
{ try {
JSONObject properties = new JSONObject();
properties.put("DownloadChannel", "XXX");// DownloadChannel
// AppInstall
SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
} catch (Exception e)
{ e.printStackTrace(
);
}
}
7. 匿名 ID 和登录 ID 关联
用户在登录前 ，SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login 方法，传入对应的登录 ID ；匿名 ID 会与对应的登录 ID
进行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功 、初始化 SDK（如果能获取到登录 ID）都需要调用 login 方法传入登录 ID。
登录 ID 是指可以唯一标识一个用户的 ID，通常是业务数据库里的主键或其它唯一标识。
//SDK login ID
SensorsDataAPI.sharedInstance().login(" ID");
注意：对同一个用户，login() 可调用多次，多次调用 login() 时，如果新设置的 登录 ID 与之前缓存的 登录 ID 相同，神策分析会忽略该次调用。
8. 设置用户属性
8.1. 记录设定的用户属性
为了更准确地提供针对人群的分析服务，可以使用神策分析 SDK 的 profileSet() 等方法设置用户属性，如年龄、性别等。用户可以在留存分析、分布分
析等功能中，使用用户属性作为过滤条件，精确分析特定人群的指标。
使用 profileSet()，可以设定用户属性，例如：
try {
JSONObject properties = new JSONObject();
// "Sex" "Male"
properties.put("Sex", "Male");
// "Age" 18
properties.put("Age", 18);//
SensorsDataAPI.sharedInstance().profileSet(properties);
} catch (JSONException e)
{ e.printStackTrace();
}
使用 profileUnset() 可以删除特定用户的属性值。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
8.2. 记录初次设定的用户属性
对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 方法不同的是，如果被设置的用户属性已存在，
则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时
间等属性。例如：
try {
JSONObject properties = new JSONObject();
properties.put("AdSource", "XXX Store");
// "developer@sensorsdata.cn" "AdSource" "XXX Store"
SensorsDataAPI.sharedInstance().profileSetOnce(properties);
JSONObject newProperties = new JSONObject();
newProperties.put("AdSource", "Email");
// "developer@sensorsdata.cn" "AdSource" "XXX Store"
SensorsDataAPI.sharedInstance().profileSetOnce(newProperties);
} catch (JSONException e)
{ e.printStackTrace();
}
8.3. 数值类型的属性
对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
其他设置用户属性方法请参考以下示例：
//
SensorsDataAPI.sharedInstance().profileIncrement("GamePlayed", 1);
//
Map properties = new HashMap();
properties.put("UserPaid", 1);
properties.put("PointEarned", 12.5);
SensorsDataAPI.sharedInstance().profileIncrement(properties);
8.4. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性，例如：
Set movies = new HashSet();
movies.add("Sicario");
movies.add("Love Letter");
// "Movies" : ["Sicario", "Love Letter"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", movies);
// "Movies" : ["Sicario", "Love Letter", "Dead Poets Society"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", "Dead Poets Society");
需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。关于列表型限制请见 数据格式 。9. 打 通 App与 H5
Android SDK 需要使用 v1.7.10 及之后的版本支持 App 与 H5 打通，详细技术实现请参考 打通 App 与 H5。
10. 获取 scheme
使用 admin 账号，登录到神策分析相应的项目，点击右上角的账号，从「数据接入」页面获取 scheme 的值。
11. 可视化全埋点本功能需要 Android SDK 版本为 v3.1.0+
如果使用 Android SDK 版本是 v4.0.0+，需要对应神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+
可视化全埋点在神策分析中的使用，请参考 可视化全埋点。
11.1. 配置 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值，详情可参考 获取 scheme。
在 AndroidManifest.xml 中 MainActivity 的标签内，配置 scheme ：
在 配 置 SDK Google
11.2. 开启可视化全埋点
SDK 初始化前设置 SAConfigOptions 配置时，调用 enableVisualizedAutoTrack(true) 方法开启可视化全埋点：
// SDK , $AppClick View ViewPath
saConfigOptions.enableVisualizedAutoTrack(true);
11.3. 开启部分页面的可视化全埋点
如果只想开启部分页面的可视化全埋点，需要首先调用 enableVisualizedAutoTrack 方法开启可视化全埋点，然后通过 addVisualizedAutoTrack
Activities 或 addVisualizedAutoTrackActivity 方法开启。
例如，开启 MainActivity 页面的可视化全埋点：
// MainActivity
SensorsDataAPI.sharedInstance().addVisualizedAutoTrackActivity(MainActivity.class);
注意：开启了可视化全埋点功能后，扫描二维码打开 App 时（使用手机自带浏览器扫描），默认情况下会弹出 AlertDialog 提示框，来提示用户是否继续
连接进行可视化全埋点。
如果想关闭此提示框，可以调用 enableVisualizedAutoTrackConfirmDialog 关闭，关闭提示后，扫描二维码打开 App 时，会自动连接进行可视化
全埋点。
//
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrackConfirmDialog(false);12. 调试查看数据
初始化 SDK 后调用 enableLog(true) 打开 SDK 的日志输出功能，如果相应事件触发，SDK 会自动进行采集并定时发送到神策分析后台。
// SDK
SensorsDataAPI.sharedInstance().enableLog(true);
12.1. IDE 控制台查看数据
可以通过 Logcat 查看日志进行数据校验和验证， 在 Logcat 中筛选 SA. 关键词：
埋点事件触发成功时，SDK 会输出 track event 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 valid message 字段开头的事件数据；
事件数据上报失败时，SDK 会输出 invalid message 字段开头的事件数据并输出错误原因。
12.2. 神策分析中查看已入库数据
SDK 默认本地存储的数据超过 100 条或间隔 15S 后将本地触发的事件上报到服务端进行入库，已入库的数据，可以在神策分析中进行筛选和查看。
13. 所有事件公共预置属性神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK
预置事件和预置属性 。基本使用(Android).基本使用(Android) v1.13
在使用前，请先阅读 数据模型 的介绍
SDK 的更新日志，可参阅 Release Notes
插件 的更新日志，可参阅 Release Notes
1. 集成神策分析 SDK
1.1. 引入插件
在 project 级别的 build.gradle 文件中添加 Sensors Analytics android-gradle-plugin 依赖：
buildscript {
repositories
{ jcenter(
)
}
dependencies {
classpath ''com.android.tools.build:gradle:3.5.3''
// android-gradle-plugin
classpath ''com.sensorsdata.analytics.android:android-gradle-plugin2:3.2.0''
}
}
allprojects {
repositories
{ jcenter(
)
}
}
Sensors Analytics android-gradle-plugin 的最新版本号请参考 GitHub 更新日志。
如下示例图：
1.2. 引入 SDK
在 主 module 的 build.gradle 文件中添加 com.sensorsdata.analytics.android 插件、神策分析 SDK 依赖：
apply plugin: ''com.android.application''
// com.sensorsdata.analytics.android
apply plugin: ''com.sensorsdata.analytics.android''dependencies {
// Sensors Analytics SDK
implementation ''com.sensorsdata.analytics.android:SensorsAnalyticsSDK:4.0.1''
}
SensorsAnalyticsSDK 的最新版本号请参考 GitHub 更新日志。
如下示例图：
Android SDK 要求最低系统版本为 API 9（Android 2.3）。AutoTrack 功能要求系统最低版本为 API 14 （Android 4.0）如果 API 低于
14 开启 AutoTrack 后 将不能采集 $AppStart、$AppViewScreen、$AppEnd 事件。
目前，Android SDK ( aar 格式) 大小约为 300 KB。
1.3. 权限配置说明
SDK 共需要四个权限
权限 用途
INTERNET 必须权限，允许应用发送统计数据，SDK 发送埋点数据需要此权限
ACCESS_NETWORK_STATE 必须权限，允许应用检测网络状态，SDK 会根据网络状态选择是否发送数据
READ_PHONE_STATE 可选权限，允许应用获取设备 IMEI，采用 App 内推广 和采集 $carrier 属性时会用到此权限
ACCESS_WIFI_STATE 可选权限，允许应用获取 MAC 地址，采用 App 内推广 时会用到此权限
如何删除在 AndroidManifest.xml 中已注册权限？
神策 SDK 为简化开发者集成步骤，默认在 AndroidManifest.xml 中注册了以上四个权限，如果开发者不需要其中某个权限，可以使用 tools:node="
remove" 属性删除，打包后的 AndroidManifest.xml 文件将不再包含此权限，关于 tools:node="remove" 的详细说明可参考谷歌 官方文档，配置
参考代码如下：
如果不是特殊要求，可不配置此代码
2. 获取数据接收地址
数据接收地址是 SDK 上报数据的目标地址，需要使用管理员账户进行获取。3. 初始化 SDK 并开启全埋点
一定需要在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfigOptions(SAConfigOptions) 并且
在 主线程 中初始化 SDK：
// SDK
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;
// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// SAConfigOptions SA_SERVER_URL
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions SDK SAConfigOptions
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK | //
SensorsAnalyticsAutoTrackEventType.APP_START | //
SensorsAnalyticsAutoTrackEventType.APP_END | //
SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN) //
.enableLog(true) //()
.enableTrackAppCrash(); // crash
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。一旦成功初始化后，则可以通过 sharedInstance 获取 SDK 实例，进
行用户行为事件或属性的追踪。
注意：利用 SAConfigOptions 设置全埋点类型、开启 crash 采集时等操作时，只有 SDK 第一次初始化时有效。请勿对多个 SAConfigOptio
ns 对象进行相关设置4. 代码埋点
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户浏览商品和下订单等事件
神策分析 SDK 成功初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。以电商产品为例，可以这样追踪一次购物行为：
// ...
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456); // ID
properties.put("ProductCatalog", "Laptop Computer"); //
properties.put("IsAddedToFav", false); //
SensorsDataAPI.sharedInstance().track("ViewProduct", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
// ...
try {
JSONArray orderList = new JSONArray();
orderList.put("Apple iPhone6s");
orderList.put("Nexus 6");
JSONObject properties = new JSONObject();
properties.put("OrderPaid", 50.10); //
properties.put("OrderList", orderList); //
properties.put("OrderDate", new Date()); //
SensorsDataAPI.sharedInstance().track("PaidOrder", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
触发事件后，在神策分析中稍等片刻，便能看到追踪结果。5. 事件属性
每个事件可以设置多个事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属性可以作为统计过滤条件
使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 JSONObject 对象
JSONObject 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型
JSONObject 中，每个元素的 Value 是属性的值，支持 String、Number、Boolean、JSONArray 和 Date，对于 JSONArray，其中所有元素必须是
String 类型
5.1. 设置静态公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件静态公共属性。例如添加应用程序
名称为事件的公共属性，设置方法如下:
// track() "AppName"
try {
JSONObject properties = new JSONObject();
properties.put("AppName", getAppName(this));
SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e)
{ e.printStackTrace();
}
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中，例如：
//
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456);
SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
在设置事件公共属性后，实际发送的事件中会被加入 AppName 属性，等价于
//
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456);
properties.put("AppName", getAppName(this));
SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
重复调用 registerSuperProperties() 会覆盖之前已设置的公共属性，公共属性会保存在 App 本地 SharedPreferences 中。可以通过 unregiste
rSuperProperty() 删除一个静态公共属性，使用 clearSuperProperties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。
1. 请在初始化 SDK 后立即调用 registerSuperProperties() 方法，确保每个事件都会添加已设置的公共属性。
2. 神策事件属性大小写敏感（ 详见 数据格式 ），设置公共属性前需确保事件表中不存在仅大小写不同的同名属性，否则会导致所有事件
因存在同名属性而不能入库。
5.2. 设置动态公共属性
Android SDK 2.0.1 及以后的版本可以通过 registerDynamicSuperProperties() 方法设置动态公共属性，设置之后 SDK 会自动获取
getDynamicSuperProperties 中的属性添加到触发的事件中。// SDK
SensorsDataAPI.sharedInstance().registerDynamicSuperProperties(new SensorsDataDynamicSuperProperties()
{ @Override
public JSONObject getDynamicSuperProperties()
{ try {
// isLogin() SDK getDynamicSuperProperties
boolean bool = isLogin();
return new JSONObject().put("isLogin",bool);
} catch (Exception e)
{ e.printStackTrace(
);
}
return null;
}
});
调用 registerDynamicSuperProperties 方法设置的动态公共属性，不能用 unregisterSuperProperty 方法删除
6. 记录激活事件
可以调用 trackInstallation 方法记录激活事件，多次调用此方法只会触发一次激活事件（触发激活事件时会自动保存 $first_visit_time 首次访问
时间属性到用户表）。
触发激活事件时会尝试获取 IMEI 号，请动态申请 android.permission.READ_PHONE_STATE 权限后再调用 trackInstallation 。
例如，在 Activity 的 onCreate 方法中申请权限：
if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.
PERMISSION_GRANTED) {
// 6.0 READ_PHONE_STATE
ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
} else {
// 6.0 trackInstallation()
trackInstallation();
}
} else {
// 6.0 trackInstallation()
trackInstallation();
}
在权限回调的 onRequestPermissionsResult 方法中，调用 trackInstallation
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[]
grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
if (requestCode == 100) {
// trackInstallation()
trackInstallation();
}
}
/**
*
*/
private void trackInstallation()
{ try {
JSONObject properties = new JSONObject();
properties.put("DownloadChannel", "XXX");// DownloadChannel
// AppInstall
SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
} catch (Exception e)
{ e.printStackTrace(
);
}7. 匿名 ID 和登录 ID 关联
用户在登录前 ，SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login 方法，传入对应的登录 ID ；匿名 ID 会与对应的登录 ID
进行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功 、初始化 SDK（如果能获取到登录 ID）都需要调用 login 方法传入登录 ID。
登录 ID 是指可以唯一标识一个用户的 ID，通常是业务数据库里的主键或其它唯一标识。
//SDK login ID
SensorsDataAPI.sharedInstance().login(" ID");
注意：对同一个用户，login() 可调用多次，多次调用 login() 时，如果新设置的 登录 ID 与之前缓存的 登录 ID 相同，神策分析会忽略该次调用。
8. 设置用户属性
8.1. 记录设定的用户属性
为了更准确地提供针对人群的分析服务，可以使用神策分析 SDK 的 profileSet() 等方法设置用户属性，如年龄、性别等。用户可以在留存分析、分布分
析等功能中，使用用户属性作为过滤条件，精确分析特定人群的指标。
使用 profileSet()，可以设定用户属性，例如：
try {
JSONObject properties = new JSONObject();
// "Sex" "Male"
properties.put("Sex", "Male");
// "Age" 18
properties.put("Age", 18);
//
SensorsDataAPI.sharedInstance().profileSet(properties);
} catch (JSONException e)
{ e.printStackTrace();
}
使用 profileUnset() 可以删除特定用户的属性值。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
8.2. 记录初次设定的用户属性
对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 方法不同的是，如果被设置的用户属性已存在，
则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时
间等属性。例如：
try {
JSONObject properties = new JSONObject();
properties.put("AdSource", "XXX Store");
// "developer@sensorsdata.cn" "AdSource" "XXX Store"
SensorsDataAPI.sharedInstance().profileSetOnce(properties);
JSONObject newProperties = new JSONObject();
newProperties.put("AdSource", "Email");
// "developer@sensorsdata.cn" "AdSource" "XXX Store"
SensorsDataAPI.sharedInstance().profileSetOnce(newProperties);
} catch (JSONException e) {e.printStackTrace();
}
8.3. 数值类型的属性
对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
其他设置用户属性方法请参考以下示例：
//
SensorsDataAPI.sharedInstance().profileIncrement("GamePlayed", 1);
//
Map properties = new HashMap();
properties.put("UserPaid", 1);
properties.put("PointEarned", 12.5);
SensorsDataAPI.sharedInstance().profileIncrement(properties);
8.4. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性，例如：
Set movies = new HashSet();
movies.add("Sicario");
movies.add("Love Letter");
// "Movies" : ["Sicario", "Love Letter"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", movies);
// "Movies" : ["Sicario", "Love Letter", "Dead Poets Society"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", "Dead Poets Society");
需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。关于列表型限制请见 数据格式 。
9. 打 通 App与 H5
Android SDK 需要使用 v1.7.10 及之后的版本支持 App 与 H5 打通，详细技术实现请参考 打通 App 与 H5。
10. 获取 scheme
使用 admin 账号，登录到神策分析相应的项目，点击右上角的账号，从「数据接入」页面获取 scheme 的值。11. 可视化全埋点
本功能需要 Android SDK 版本为 v3.1.0+
如果使用 Android SDK 版本是 v4.0.0+，需要对应神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+
可视化全埋点在神策分析中的使用，请参考 可视化全埋点。
11.1. 配置 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值，详情可参考 获取 scheme。
在 AndroidManifest.xml 中 MainActivity 的标签内，配置 scheme ：
在 配 置 SDK Google11.2. 开启可视化全埋点
SDK 初始化前设置 SAConfigOptions 配置时，调用 enableVisualizedAutoTrack(true) 方法开启可视化全埋点：
// SDK , $AppClick View ViewPath
saConfigOptions.enableVisualizedAutoTrack(true);
11.3. 开启部分页面的可视化全埋点
如果只想开启部分页面的可视化全埋点，需要首先调用 enableVisualizedAutoTrack 方法开启可视化全埋点，然后通过 addVisualizedAutoTrack
Activities 或 addVisualizedAutoTrackActivity 方法开启。
例如，开启 MainActivity 页面的可视化全埋点：
// MainActivity
SensorsDataAPI.sharedInstance().addVisualizedAutoTrackActivity(MainActivity.class);
注意：开启了可视化全埋点功能后，扫描二维码打开 App 时（使用手机自带浏览器扫描），默认情况下会弹出 AlertDialog 提示框，来提示用户是否继续
连接进行可视化全埋点。
如果想关闭此提示框，可以调用 enableVisualizedAutoTrackConfirmDialog 关闭，关闭提示后，扫描二维码打开 App 时，会自动连接进行可视化
全埋点。
//
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrackConfirmDialog(false);
12. 调试查看数据
初始化 SDK 后调用 enableLog(true) 打开 SDK 的日志输出功能，如果相应事件触发，SDK 会自动进行采集并定时发送到神策分析后台。
// SDK
SensorsDataAPI.sharedInstance().enableLog(true);
12.1. IDE 控制台查看数据
可以通过 Logcat 查看日志进行数据校验和验证， 在 Logcat 中筛选 SA. 关键词：
埋点事件触发成功时，SDK 会输出 track event 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 valid message 字段开头的事件数据；
事件数据上报失败时，SDK 会输出 invalid message 字段开头的事件数据并输出错误原因。12.2. 神策分析中查看已入库数据
SDK 默认每 15s 会将本地触发的事件上报到服务端进行入库，已入库的数据，可以在神策分析中进行筛选和查看。
13. 所有事件公共预置属性
神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK
预置事件和预置属性 。.基本使用(Android) v1.15
在使用前，请先阅读 数据模型 的介绍
SDK 的更新日志，可参阅 Release Notes
插件 的更新日志，可参阅 Release Notes
1. 集成神策分析 SDK
1.1. 引入插件
在 project 级别的 build.gradle 文件中添加 Sensors Analytics android-gradle-plugin 依赖：
buildscript {
repositories
{ jcenter(
)
}
dependencies {
classpath ''com.android.tools.build:gradle:3.6.2''
// android-gradle-plugin
classpath ''com.sensorsdata.analytics.android:android-gradle-plugin2:3.2.0''
}
}
allprojects {
repositories
{ jcenter(
)
}
}
Sensors Analytics android-gradle-plugin 的最新版本号请参考 GitHub 更新日志。
如下示例图：
1.2. 引入 SDK
在 主 module 的 build.gradle 文件中添加 com.sensorsdata.analytics.android 插件、神策分析 SDK 依赖：
apply plugin: ''com.android.application''
// com.sensorsdata.analytics.android
apply plugin: ''com.sensorsdata.analytics.android''dependencies {
// Sensors Analytics SDK
implementation ''com.sensorsdata.analytics.android:SensorsAnalyticsSDK:4.0.2''
}
SensorsAnalyticsSDK 的最新版本号请参考 GitHub 更新日志。
如下示例图：
Android SDK 要求最低系统版本为 API 9（Android 2.3）。AutoTrack 功能要求系统最低版本为 API 14 （Android 4.0）如果 API 低于
14 开启 AutoTrack 后 将不能采集 $AppStart、$AppViewScreen、$AppEnd 事件。
目前，Android SDK ( aar 格式) 大小约为 300 KB。
1.3. 权限配置说明
SDK 共需要四个权限
权限 用途
INTERNET 必须权限，允许应用发送统计数据，SDK 发送埋点数据需要此权限
ACCESS_NETWORK_STATE 必须权限，允许应用检测网络状态，SDK 会根据网络状态选择是否发送数据
READ_PHONE_STATE 可选权限，允许应用获取设备 IMEI，采用 App 内推广 和采集 $carrier 属性时会用到此权限
ACCESS_WIFI_STATE 可选权限，允许应用获取 MAC 地址，采用 App 内推广 时会用到此权限
如何删除在 AndroidManifest.xml 中已注册权限？
神策 SDK 为简化开发者集成步骤，默认在 AndroidManifest.xml 中注册了以上四个权限，如果开发者不需要其中某个权限，可以使用 tools:node="
remove" 属性删除，打包后的 AndroidManifest.xml 文件将不再包含此权限，关于 tools:node="remove" 的详细说明可参考谷歌 官方文档，配置
参考代码如下：
如果不是特殊要求，可不配置此代码
2. 获取数据接收地址
数据接收地址是 SDK 上报数据的目标地址，需要使用管理员账户进行获取。3. 初始化 SDK 并开启全埋点
一定需要在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfigOptions(SAConfigOptions) 并且
在 主线程 中初始化 SDK：
// SDK
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// SAConfigOptions SA_SERVER_URL
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions SDK SAConfigOptions
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK | //
SensorsAnalyticsAutoTrackEventType.APP_START | //
SensorsAnalyticsAutoTrackEventType.APP_END | //
SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN) //
.enableLog(true) //()
.enableTrackAppCrash(); // crash
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。一旦成功初始化后，则可以通过 sharedInstance 获取 SDK 实例，进
行用户行为事件或属性的追踪。
注意：利用 SAConfigOptions 设置全埋点类型、开启 crash 采集时等操作时，只有 SDK 第一次初始化时有效。请勿对多个 SAConfigOptio
ns 对象进行相关设置
4. 代码埋点
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户浏览商品和下订单等事件
神策分析 SDK 成功初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。以电商产品为例，可以这样追踪一次购物行为：
// ...
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456); // ID
properties.put("ProductCatalog", "Laptop Computer"); //
properties.put("IsAddedToFav", false); //
SensorsDataAPI.sharedInstance().track("ViewProduct", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
// ...
try {
JSONArray orderList = new JSONArray();
orderList.put("Apple iPhone6s");
orderList.put("Nexus 6");
JSONObject properties = new JSONObject();
properties.put("OrderPaid", 50.10); //
properties.put("OrderList", orderList); //
properties.put("OrderDate", new Date()); //
SensorsDataAPI.sharedInstance().track("PaidOrder", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
触发事件后，在神策分析中稍等片刻，便能看到追踪结果。5. 事件属性
每个事件可以设置多个事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属性可以作为统计过滤条件
使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 JSONObject 对象
JSONObject 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型
JSONObject 中，每个元素的 Value 是属性的值，支持 String、Number、Boolean、JSONArray 和 Date，对于 JSONArray，其中所有元素必须是
String 类型
5.1. 设置静态公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件静态公共属性。例如添加应用程序
名称为事件的公共属性，设置方法如下:
// track() "AppName"
try {
JSONObject properties = new JSONObject();
properties.put("AppName", getAppName(this));
SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e)
{ e.printStackTrace();
}
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中，例如：
//
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456);
SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
在设置事件公共属性后，实际发送的事件中会被加入 AppName 属性，等价于//
try {
JSONObject properties = new JSONObject();
properties.put("ProductID", 123456);
properties.put("AppName", getAppName(this));
SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
重复调用 registerSuperProperties() 会覆盖之前已设置的公共属性，公共属性会保存在 App 本地 SharedPreferences 中。可以通过 unregiste
rSuperProperty() 删除一个静态公共属性，使用 clearSuperProperties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。
1. 请在初始化 SDK 后立即调用 registerSuperProperties() 方法，确保每个事件都会添加已设置的公共属性。
2. 神策事件属性大小写敏感（ 详见 数据格式 ），设置公共属性前需确保事件表中不存在仅大小写不同的同名属性，否则会导致所有事件
因存在同名属性而不能入库。
5.2. 设置动态公共属性
Android SDK 2.0.1 及以后的版本可以通过 registerDynamicSuperProperties() 方法设置动态公共属性，设置之后 SDK 会自动获取
getDynamicSuperProperties 中的属性添加到触发的事件中。
// SDK
SensorsDataAPI.sharedInstance().registerDynamicSuperProperties(new SensorsDataDynamicSuperProperties()
{ @Override
public JSONObject getDynamicSuperProperties()
{ try {
// isLogin() SDK getDynamicSuperProperties
boolean bool = isLogin();
return new JSONObject().put("isLogin",bool);
} catch (Exception e)
{ e.printStackTrace(
);
}
return null;
}
});
调用 registerDynamicSuperProperties 方法设置的动态公共属性，不能用 unregisterSuperProperty 方法删除
6. 记录激活事件
可以调用 trackInstallation 方法记录激活事件，多次调用此方法只会触发一次激活事件（触发激活事件时会自动保存 $first_visit_time 首次访
问时间属性到用户表）。
触发激活事件时会尝试获取 IMEI 号，请动态申请 android.permission.READ_PHONE_STATE 权限后再调用 trackInstallation 。
例如，在 Activity 的 onCreate 方法中申请权限：
if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.
PERMISSION_GRANTED) {
// 6.0 READ_PHONE_STATE
ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
} else {
// 6.0 trackInstallation()
trackInstallation();
}
} else {// 6.0 trackInstallation()
trackInstallation();
}
在权限回调的 onRequestPermissionsResult 方法中，调用 trackInstallation
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[]
grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
if (requestCode == 100) {
// trackInstallation()
trackInstallation();
}
}
/**
*
*/
private void trackInstallation()
{ try {
JSONObject properties = new JSONObject();
properties.put("DownloadChannel", "XXX");// DownloadChannel
// AppInstall
SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
} catch (Exception e)
{ e.printStackTrace(
);
}
}
7. 匿名 ID 和登录 ID 关联
用户在登录前 ，SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login 方法，传入对应的登录 ID ；匿名 ID 会与对应的登录 ID
进行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功 、初始化 SDK（如果能获取到登录 ID）都需要调用 login 方法传入登录 ID。
登录 ID 是指可以唯一标识一个用户的 ID，通常是业务数据库里的主键或其它唯一标识。
//SDK login ID
SensorsDataAPI.sharedInstance().login(" ID");
注意：对同一个用户，login() 可调用多次，多次调用 login() 时，如果新设置的 登录 ID 与之前缓存的 登录 ID 相同，神策分析会忽略该次调用。
8. 设置用户属性
8.1. 记录设定的用户属性
为了更准确地提供针对人群的分析服务，可以使用神策分析 SDK 的 profileSet() 等方法设置用户属性，如年龄、性别等。用户可以在留存分析、分布分
析等功能中，使用用户属性作为过滤条件，精确分析特定人群的指标。
使用 profileSet()，可以设定用户属性，例如：
try {
JSONObject properties = new JSONObject();
// "Sex" "Male"
properties.put("Sex", "Male");
// "Age" 18
properties.put("Age", 18);//
SensorsDataAPI.sharedInstance().profileSet(properties);
} catch (JSONException e)
{ e.printStackTrace();
}
使用 profileUnset() 可以删除特定用户的属性值。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
8.2. 记录初次设定的用户属性
对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 方法不同的是，如果被设置的用户属性已存在，
则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时
间等属性。例如：
try {
JSONObject properties = new JSONObject();
properties.put("AdSource", "XXX Store");
// "developer@sensorsdata.cn" "AdSource" "XXX Store"
SensorsDataAPI.sharedInstance().profileSetOnce(properties);
JSONObject newProperties = new JSONObject();
newProperties.put("AdSource", "Email");
// "developer@sensorsdata.cn" "AdSource" "XXX Store"
SensorsDataAPI.sharedInstance().profileSetOnce(newProperties);
} catch (JSONException e)
{ e.printStackTrace();
}
8.3. 数值类型的属性
对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
其他设置用户属性方法请参考以下示例：
//
SensorsDataAPI.sharedInstance().profileIncrement("GamePlayed", 1);
//
Map properties = new HashMap();
properties.put("UserPaid", 1);
properties.put("PointEarned", 12.5);
SensorsDataAPI.sharedInstance().profileIncrement(properties);
8.4. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性，例如：
Set movies = new HashSet();
movies.add("Sicario");
movies.add("Love Letter");
// "Movies" : ["Sicario", "Love Letter"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", movies);
// "Movies" : ["Sicario", "Love Letter", "Dead Poets Society"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", "Dead Poets Society");
需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。关于列表型限制请见 数据格式 。9. 打 通 App与 H5
Android SDK 需要使用 v1.7.10 及之后的版本支持 App 与 H5 打通，详细技术实现请参考 打通 App 与 H5。
10. 获取 scheme
使用 admin 账号，登录到神策分析相应的项目，点击右上角的账号，从「数据接入」页面获取 scheme 的值。
11. 可视化全埋点本功能需要 Android SDK 版本为 v3.1.0+
如果使用 Android SDK 版本是 v4.0.0+，需要对应神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+
可视化全埋点在神策分析中的使用，请参考 可视化全埋点。
11.1. 配置 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值，详情可参考 获取 scheme。
在 AndroidManifest.xml 中 MainActivity 的标签内，配置 scheme ：
在 配 置 SDK Google
11.2. 开启可视化全埋点
SDK 初始化前设置 SAConfigOptions 配置时，调用 enableVisualizedAutoTrack(true) 方法开启可视化全埋点：
// SDK , $AppClick View ViewPath
saConfigOptions.enableVisualizedAutoTrack(true);
11.3. 开启部分页面的可视化全埋点
如果只想开启部分页面的可视化全埋点，需要首先调用 enableVisualizedAutoTrack 方法开启可视化全埋点，然后通过 addVisualizedAutoTrack
Activities 或 addVisualizedAutoTrackActivity 方法开启。
例如，开启 MainActivity 页面的可视化全埋点：
// MainActivity
SensorsDataAPI.sharedInstance().addVisualizedAutoTrackActivity(MainActivity.class);
注意：开启了可视化全埋点功能后，扫描二维码打开 App 时（使用手机自带浏览器扫描），默认情况下会弹出 AlertDialog 提示框，来提示用户是否继续
连接进行可视化全埋点。
如果想关闭此提示框，可以调用 enableVisualizedAutoTrackConfirmDialog 关闭，关闭提示后，扫描二维码打开 App 时，会自动连接进行可视化
全埋点。
//
SensorsDataAPI.sharedInstance().enableVisualizedAutoTrackConfirmDialog(false);12. 调试查看数据
初始化 SDK 后调用 enableLog(true) 打开 SDK 的日志输出功能，如果相应事件触发，SDK 会自动进行采集并定时发送到神策分析后台。
// SDK
SensorsDataAPI.sharedInstance().enableLog(true);
12.1. IDE 控制台查看数据
可以通过 Logcat 查看日志进行数据校验和验证， 在 Logcat 中筛选 SA. 关键词：
埋点事件触发成功时，SDK 会输出 track event 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 valid message 字段开头的事件数据；
事件数据上报失败时，SDK 会输出 invalid message 字段开头的事件数据并输出错误原因。
12.2. 神策分析中查看已入库数据
SDK 默认本地存储的数据超过 100 条或间隔 15S 后将本地触发的事件上报到服务端进行入库，已入库的数据，可以在神策分析中进行筛选和查看。
13. 所有事件公共预置属性神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK
预置事件和预置属性 。Android SDK 全埋点.全埋点(Android) v1.13
1. 全埋点采集策略
SDK 可以自动采集一些用户行为，如 App 启动、退出、浏览页面、控件点击等。可以通过 SAConfigOptions 对象打开自动采集:
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK|
SensorsAnalyticsAutoTrackEventType.APP_START|
SensorsAnalyticsAutoTrackEventType.APP_END|
SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN);
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
3.1.0 及之前的版本，SDK 开启全埋点方式：
try {
// , AutoTrack
List eventTypeList = new ArrayList<>();
// $AppStart
eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_START);
// $AppEnd
eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_END);
// $AppViewScreen
eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_VIEW_SCREEN);
// $AppClick
eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_CLICK);
SensorsDataAPI.sharedInstance().enableAutoTrack(eventTypeList);
} catch (Exception e)
{ e.printStackTrace(
);
}
1.1. $AppStart (App 启动) 事件
App 启动且符合 session 机制 时，会自动记录 $AppStart 事件，事件包含以下属性：
字段名称 类型 显示名 说明 版本
$is_first_time BOOL 是否首次访问 App 安装后是否首次启动
$resume_from_background BOOL 是否从后台唤醒 App 是否是从后台恢复
$title 字符串 页面标题 Activity 的标题（仅 Android 端有）
$screen_name 字符串 页面名称 Activity 的包名.类名（仅 Android 端有）
注意：在 2.0.3 及以上的版本中，$AppStart 的计算规则默认为 30 秒的 session 机制。
1.2. $AppEnd (App 退出)
App 进入后台且符合 session 机制 时，会自动记录 $AppEnd 事件，事件包含以下属性：
字段名称 类型 显示名 说明 版本
$event_duration 数值 事件时长 本次 App 启动的使用时长（单位为秒，此字段虽没加 $ 符，也是预置字段）
$title 字符串 页面标题 Activity 的标题（仅 Android 端有）
$screen_name 字符串 页面名称 Activity 的包名.类名（仅 Android 端有）
1.3. $AppViewScreen (App 浏览页面) 事件
App 浏览页面时（切换 Activity），会自动记录 $AppViewScreen 事件，事件包含以下属性：字段名称 类型 显示名 说明 版本
$title 字符串 页面标题 Activity 的标题
$screen_name 字符串 页面名称 Activity 的包名.类名
备注：$title - String 类型，表示 Activity 的标题（1.6.31 及以后版本支持该属性）。Android SDK 按照如下逻辑读取 title 属性：首先读取 ac
tivity.getTitle()，如果使用 actionBar，并且 actionBar.getTitle() 不为空，则 actionBar.getTitle() 覆盖 activity.getTitle()
，如果以上两步都没有读到 title，则获取 activity 的 android:label 属性。
1.4. $AppClick (App 元素点击) 事件
点击控件时，会发送 $AppClick 事件，包含点击的相应控件的基本信息，事件包含以下属性：
字段名称 类型 显示名 说明 版本
$element_id 字符串 元素 ID 控件的 ID
$element_type 字符串 元素类型 控件的类型，例如 Button
$element_content 字符串 元素内容 控件的内容
$title 字符串 页面标题 Activity 的标题
$screen_name 字符串 页面名称 Activity 的包名.类名
$element_position 字符串 元素位置 元素被点击时所处的位置
注意：只有控件本身有 position 时才有 $element_position 字段，例如 ListView 的 item。另外，控件本身有 id、text 属性时，对应的 App 元
素点击事件才有 $element_id、$element_content 属性。
2. 全埋点使用配置说明
2.1. 自定义页面信息 ($AppViewScreen)
对于 App 中的核心页面（Activity、Fragment），我们提供了一个 接口 ScreenAutoTracker：
public interface ScreenAutoTracker {
/**
* Url
* referrer
* @return String
*/
String getScreenUrl();
/**
*
* :$screen_name,, ,ActivityCanonicalName,:
* activity.getClass().getCanonicalName(), , Mapputkey
* :screen_name"$"
*
* @return JSONObject
* @throws JSONException JSONException
*/
JSONObject getTrackProperties() throws JSONException;
}
当用户实现该接口时，SDK 会将 getTrackProperties 返回的属性（JSONObject 类型）加入 $AppViewScreen 事件的属性中，作为用户访问该页面时
的事件属性；SDK 会将 getScreenUrl 返回的字符串作为页面的 Url Scheme，记录在 $AppViewScreen 事件的 $url 属性中，并且当用户切换页面
时，将前一个页面中的 Url Scheme 作为当前页面的 $AppViewScreen 事件的 $referrer 属性。
例如：
public class OrderDetailActivity extends Activity implements ScreenAutoTracker
{ @Override
public String getScreenUrl() {
return "sensorsdata://page/order/detail?orderId=888888";
}@Override
public JSONObject getTrackProperties() throws JSONException
{ JSONObject jsonObject = new JSONObject();
jsonObject.put("orderId", "888888");
// $title $title $title
jsonObject.put("$title", "HomeFragment");
return jsonObject;
}
}
2.2. 开启 Fragment 页面浏览事件的自动采集 ($AppViewScreen)
从 1.7.10 可以使用 trackFragmentAppViewScreen 方法开启 Fragment 页面浏览事件的自动采集：
// SDK Fragment
SensorsDataAPI.sharedInstance().trackFragmentAppViewScreen();
开启了 Fragment 浏览页面的自动采集，可以通过 注解 @SensorsDataIgnoreTrackAppViewScreen 忽略 Fragment 所在 Activity 的页面浏览事
件；如果某些 Fragment 的页面浏览事件也不想采集，也可以通过此注解来忽略掉。
如果不想使用自动采集的 Fragment 浏览页面，可以通过代码埋点在 tab 切换 Fragment 时触发页面浏览事件：
// Fragment
SensorsDataAPI.sharedInstance().trackViewScreen(fragment);
2.3. 开启部分 Fragment 页面浏览事件的自动采集 ($AppViewScreen)
通过 enableAutoTrackFragment 方法，指定只采集某些 Fragment 页面的信息
// SDK Fragment
SensorsDataAPI.sharedInstance().trackFragmentAppViewScreen();
// HomeFragment
SensorsDataAPI.sharedInstance().enableAutoTrackFragment(HomeFragment.class);
2.4. 通过代码 track 浏览页面事件 ($AppViewScreen)
public void trackViewScreen(String url, JSONObject properties)
此方法用于 Activity 内 切换页面的时候调用，用于记录 $AppViewScreen 事件.
url ：页面的 url， 记录到 $url 字段中 ( 如果不需要此属性，可以传 null )。
properties ：页面的属性。
注意：为保证记录到的 $AppViewScreen 事件和 Auto Track 采集的一致，页面的属性中 需要传入 $title（页面的 title ） 、$screen_name (页
面的名称，即 包名.类名) 字段。
try {
JSONObject properties = new JSONObject();
// Fragment $AppViewSceen
properties.put("$title", "")
.put("$screen_name", "cn.sensorsdata.demo.HomeFragment");
SensorsDataAPI.sharedInstance().trackViewScreen(null, properties);
} catch (Exception e) {
e.printStackTrace();
}
从 v1.7.9 开始也可以使用下面方法来触发浏览页面事件：// Activity
public void trackViewScreen(Activity activity)
// Fragment
public void trackViewScreen(Fragment fragment)
2.5. 通过代码 track 控件点击事件
从 v3.2.6 开始可以使用以下方法来手动采集 $AppClick 事件，并且该接口不受忽略等条件的限制：
// View
public void trackViewAppClick(View view)
// View
public void trackViewAppClick(View view, JSONObject properties)
2.6. 忽略部分 Fragment 页面浏览事件的自动采集 ($AppViewScreen)
从 v3.2.6 开始可以通过如下方法，指定不采集某些 Fragment 页面的信息
// Fragment
SensorsDataAPI.sharedInstance().ignoreAutoTrackFragment(Class fragment);
// Fragment
SensorsDataAPI.sharedInstance().ignoreAutoTrackFragments(List> fragmentList);
从 v3.2.6 开始可以通过如下方法，恢复被忽略的 Fragment 页面浏览事件的自动采集
// Fragment
SensorsDataAPI.sharedInstance().resumeIgnoredAutoTrackFragment(Class fragment);
// Fragment
SensorsDataAPI.sharedInstance().resumeIgnoredAutoTrackFragments(List> fragmentList);
2.7. 忽略某个页面或某些页面的事件
如果想忽略某个或某些页面的事件（$AppClick、$AppViewScreen），可以使用如下方法：
//
SensorsDataAPI.sharedInstance().ignoreAutoTrackActivity(MainActivity.class);
//
List> classList = new ArrayList<>();
classList.add(MainActivity.class);
SensorsDataAPI.sharedInstance().ignoreAutoTrackActivities(classList);
2.8. 忽略某个类型控件的点击事件
如果想忽略某个控件类型及其子类控件的点击事件 ($AppClick)，可以使用如下方法：
SensorsDataAPI.sharedInstance().ignoreViewType(Class viewType);
viewType 可以是 Android 常见的控件类型及自定义类型，如：CheckBox、RadioButton、Button、SwitchCompat、Spinner、TextView、
ImageView、ImageButton、SeekBar、RatingBar、RadioGroup、
ExpandableListView、Dialog、ListView、GridView、TabHost 等。
2.9. 忽略某个 View 的点击事件
如果要忽略某个 view 的点击事件（$AppClick），比如某个 view 的点击事件对整个业务分析完全没有任何作用，或者自定义的密码输入键盘等，可以使用
如下的方法忽略点击事件：SensorsDataAPI.sharedInstance().ignoreView(View view);
2.10. AlertDialog
对于 AlertDialog（ android.app.AlertDialog、android.support.v7.app.AlertDialog），需要给 Dialog 设置 OwnerActivity，才能
采集到 AlertDialog 所属页面 (Activity) 的信息（属性：$screen_name、$title）。
如果是调用 dialog.show() 显示 dialog：
dialog.setOwnerActivity(activity);
如果是调用 builder.show() 显示 dialog
builder.show().setOwnerActivity(activity);
2.11. 设置元素 ID
为了有效的区分页面元素 (view)，SDK 默认使用 android:id 的值作为点击事件的 $element_id 属性，如果元素没有设置 android:id 属性，或者
设置的不符合要求，可以使用如下方法设置元素 ID：
SensorsDataAPI.sharedInstance().setViewID(View view, String viewID);
对于 Dialog，可以使用如下方法：
SensorsDataAPI.sharedInstance().setViewID(android.app.Dialog view, String viewID);
或
SensorsDataAPI.sharedInstance().setViewID(android.support.v7.app.AlertDialog view, String viewID);
注意 setViewID 的优先级高于 android:id。
2.12. 自定义元素属性
点击 view 时，如果在发送 $AppClick 事件时还需要添加其它属性，可以通过如下方法进行扩展：
SensorsDataAPI.sharedInstance().setViewProperties(View view, JSONObject properties);
当点击 view 后，发送 $AppClick 事件时，会把 properties 的内容带上。
对于 ExpandableListView，可以通过 setViewProperties 方法对 item 所在的 view 设置扩展属性，也可以通过 Adapter 实现 Sensors
ExpandableListViewItemTrackProperties 接口来扩展属性。
package com.sensorsdata.analytics.android.sdk;
public interface SensorsExpandableListViewItemTrackProperties {
/**
* groupPositionchildPosition item
* @param groupPosition
* @param childPosition
* @return
* @throws JSONException
*/
JSONObject getSensorsChildItemTrackProperties(int groupPosition, int childPosition) throws
JSONException;
/**
* groupPosition item* @param groupPosition
* @return
* @throws JSONException
*/
JSONObject getSensorsGroupItemTrackProperties(int groupPosition) throws JSONException;
}
对于 ListView、GridView，可以通过 setViewProperties 方法对 item 所在的 view 设置扩展属性，也可以通过 Adapter 实现 Sensors
AdapterViewItemTrackProperties 接口来扩展属性。
package com.sensorsdata.analytics.android.sdk;
public interface SensorsAdapterViewItemTrackProperties {
/**
* position item
* @param position
* @return
* @throws JSONException
*/
JSONObject getSensorsItemTrackProperties(int position) throws JSONException;
}
2.13. 注解 @SensorsDataIgnoreTrackAppViewScreen
忽略某个 Activity 或 Fragment 的页面浏览事件 ($AppViewScreen)
例如：忽略 DemoActivity 的页面浏览事件
// DemoActivity
@SensorsDataIgnoreTrackAppViewScreen
public class DemoActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState)
{ super.onCreate(savedInstanceState);
setContentView(R.layout.activity_demo);
}
}
2.14. 注解 @SensorsDataTrackViewOnClick
如果你是使用 android:onclick 属性给 View 添加点击处理函数，此时你可以在处理函数上使用 @SensorsDataTrackViewOnClick 注解，在该函数
执行时，SDK 会发 $AppClick 事件。
例如：
XML:
处理函数：
import com.sensorsdata.analytics.android.sdk.SensorsDataTrackViewOnClick;
@SensorsDataTrackViewOnClick
public void buttonOnClick(View v) {
}2.15. 注解 @SensorsDataTrackEvent
对于一些简单的场景，比如当某一个方法执行时就 track 一个事件，可以在该方法上使用 @SensorsDataTrackEvent 注解。当该方法执行时，SDK 会
track 一个指定的事件。
注意：被注解的方法一定需要 public 的才可以
例如：
@SensorsDataTrackEvent(eventName = "someEventName", properties = "{"provider":"","number":100,"isLogin":true}")
public void someMethod() {
}
这样，每当函数 someMethod() 执行时，SDK 就会 track 一个事件，其中事件名称为 someEventName，属性有:
"provider":"",
"number":100,
"isLogin":true
2.16. 开启 React Native 页面控件的自动采集（$AppClick）
1.7.14 及以后的版本， 支持在初始化 SDK 之后，通过 enableReactNativeAutoTrack() 方法开启 RN 页面控件点击事件的自动采集。
//SDK RN
SensorsDataAPI.sharedInstance().enableReactNativeAutoTrack();Android SDK 高级功能.高级功能(Android) v1.13
1. 开启 Crash 信息的自动采集
1.8.12 及以后的版本支持 crash 信息收集，App crash 时，会触发 AppCrashed 事件，堆栈信息记录在 app_crashed_reason 属性中。
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions crash
saConfigOptions.enableTrackAppCrash();
SensorsDataAPI.startWithConfiguration(this, saConfigOptions);
3.1.0 及之前的版本，开启 crash 采集：
// crash
SensorsDataAPI.sharedInstance().trackAppCrash();
2. 开启屏幕方向的自动采集
1.10.1 及以后的版本可以通过 enableTrackScreenOrientation 方法开启屏幕方向属性的收集，屏幕方向信息记录在事件的 $screen_orientation
属性中。
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions
saConfigOptions.enableTrackScreenOrientation(true);
SensorsDataAPI.startWithConfiguration(this, saConfigOptions);
3. 开启位置信息自动采集
1.10.1 及以后的版本可以通过 setGPSLocation 方法，把第三方定位获取到的经纬度信息设置给 SDK，设置之后经纬度信息记录在事件的 $longitude、
$latitude 属性中。
//
SensorsDataAPI.sharedInstance().setGPSLocation(latitude,longitude);
4. 事件时长
可以通过计时器统计事件的持续时间。首先，在事件开始时调用（1.10.6 及以后版本支持） trackTimerStart("Event") 记录事件开始时间，该方法并
不会真正发送事件；在事件结束时，调用 trackTimerEnd("Event", properties)，SDK 会追踪 "Event" 事件，并自动将事件持续时间记录在事件属
性 "$event_duration" 中。
从 3.1.5 版本开始，统计事件时长支持暂停和恢复，通过调用 trackTimerPause(String eventName) 和 trackTimerResume(String
eventName) 来分别实现暂停和恢复。
例如记录用户浏览商品页面的时间：
//
// trackTimerStart("ViewProduct")
SensorsDataAPI.sharedInstance().trackTimerStart("ViewProduct");
// ...
//
try {
// ID
JSONObject properties = new JSONObject();
properties.put("product_id", PRODUCT_ID);// track ViewProduct event_duration
SensorsDataAPI.sharedInstance().trackTimerEnd("ViewProduct", properties);
} catch (JSONException e)
{ e.printStackTrace();
}
多次调用 trackTimerStart("Event") 时，事件 "Event" 的开始时间以最后一次调用时为准。
4.1. 同名事件交叉的时长统计
默认情况下，时长的统计以事件名作为标识，相同的事件名会自动匹配 start-end，如果两个同名事件在时间上有交叉部分，会造成错误匹配。为了解决此
问题，从 3.2.11 版本开始 SDK 支持同名事件交叉的时长统计，开发者需要保存 trackTimerStart() 的返回值，以便后续针对性地进行暂停、恢复或停
止。
//
String timer1 = SensorsDataAPI.sharedInstance().trackTimerStart("testTimer");
//
String timer2 = SensorsDataAPI.sharedInstance().trackTimerStart("testTimer");
//
SensorsDataAPI.sharedInstance().trackTimerPause(timer1);
//
SensorsDataAPI.sharedInstance().trackTimerResume(timer1);
//
SensorsDataAPI.sharedInstance().trackTimerEnd(timer1);
//
SensorsDataAPI.sharedInstance().trackTimerEnd(timer2);
5. 获取预置属性
1.8.17 及以后的版本可以调用 getPresetProperties 方法获取预置属性。
一般用于服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性传给自己的服务端。
//
JSONObject presetProperties=SensorsDataAPI.sharedInstance().getPresetProperties();
6. 获取用户标识
在集成了神策分析 SDK 的 App 中，SDK 会为每个设备分配一个匿名 ID（UUID.randomUUID().toString()），用于标记产生事件的未登录用户，并以
此进行用户相关分析，如留存率、事件漏斗等。
当用户重新安装 App 或更换设备时，神策分析会重新分配一个匿名 ID。
1.10.5 及以后的版本默认使用 AndroidId 作为 匿名 ID
通过 getAnonymousId 方法 获取神策分析 SDK 分配的 匿名 ID
//id
String AnonymousId=SensorsDataAPI.sharedInstance().getAnonymousId();
如果服务端做了埋点，需在用户注册/登录的时候将匿名 ID 传给服务端做用户 ID 关联。
也可以通过 getDistinctId 方法获取神策分析 SDK 中 distinct_id 的值，此值在未调用 SDK 中 login 方法前，获取的是默认的 SDK 分配的 匿名 ID
，调用后获取的是 login 方法中传入的值。//distinctId
String distinctId=SensorsDataAPI.sharedInstance().getDistinctId();
7. 开启点击分析功能
7.1. 配置 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值，详情可参考 获取 scheme。
获取 scheme 后，在 AndroidManifest 中 MainActivity 的标签内配置 scheme ：
在 配 置 SDK Google
7.2. 开启点击图
在初始化 SDK 之后调用 enableHeatMap 方法开启点击图，将采集所有页面的点击图 :
// SDK
SensorsDataAPI.sharedInstance().enableHeatMap();
点击图功能依赖于全埋点中 $AppClick 事件，开启点击图后，点击事件会采集 $element_selector 属性（需要先开启全埋点点击事件的采
集）
7.3. 开启部分页面的点击图
如果只想查看部分页面的点击图，可以通过 addHeatMapActivity 或 addHeatMapActivities 方法开启。
例如，开启 MainActivity 页面的点击图：
// MainActivity
SensorsDataAPI.sharedInstance().addHeatMapActivity(MainActivity.class);
开启了点击图功能后，扫描二维码打开 App 时（使用手机自带浏览器扫描），默认情况下会弹出 AlertDialog 提示框，来提示用户是否继续连接点击分
析。
从 1.9.6 开始，如果想关闭此提示框，可以调用 enableAppHeatMapConfirmDialog 关闭，关闭提示后，扫描二维码打开 App 时，会自动连接点击分
析。//
SensorsDataAPI.sharedInstance().enableAppHeatMapConfirmDialog(false);
8. 开启调试模式动态配置功能
在神策 Android SDK (3.0.3+) 中，可以使用调试的设备，通过扫描网页二维码的方式，开启该设备的「调试模式」。调试模式的配置请参考 调试模式动态
配置。
9. 自定义上报策略
当需要更精细地控制神策分析以通过以下选项设置数据采集功能。
9.1. 数据采集
在每次调用 track()、login()、profileSet() 等方法的时，神策分析 SDK 会将事件与属性保存在 App 的存储空间中，并会检查如下条件，以判断是
否向服务器上传数据:
1. 是否是WIFI/2G/3G/4G/5G网络条件
2. 是否满足发送条件之一:
a. 与上次发送的时间间隔是否大于 flushInterval
b. 本地缓存日志数目是否大于 flushBulkSize
默认的 flushBulkSize 为 100 条，默认的 flushInterval 为 15 秒。满足条件后，神策分析 SDK 会将数据 gzip 压缩后，批量发送到神策分析。
如果追求数据采集的时效性，可以调用 flush() 方法，强制将数据发送到神策分析，例如：
//
SensorsDataAPI.sharedInstance().track("UserLogin");
//
SensorsDataAPI.sharedInstance().flush();
在 App 进入后台状态时，SDK 会调用 flush() 方法，将缓存的数据发送到神策分析。
9.2. 设置同步数据时的网络策略
默认情况下，在 WIFI/3G/4G/5G 网络条件下，SDK 都会尝试去同步数据。1.7.2 及以后的版本支持可以自定义同步数据的网络策略。
通过 setFlushNetworkPolicy 方法来指定发送数据的网络策略 。
例如：
//
//SensorsDataAPI.NetworkType.TYPE_2G 2G
//SensorsDataAPI.NetworkType.TYPE_3G 3G
//SensorsDataAPI.NetworkType.TYPE_4G 4G
//SensorsDataAPI.NetworkType.TYPE_5G 5G
//SensorsDataAPI.NetworkType.TYPE_WIFI WIFI
//SensorsDataAPI.NetworkType.TYPE_ALL 2G/3G/4G/5G/WIFI
//SensorsDataAPI.NetworkType.TYPE_NONE
// 3G/4G/WIFI
SensorsDataAPI.sharedInstance().setFlushNetworkPolicy(SensorsDataAPI.NetworkType.TYPE_3G|SensorsDataAPI.
NetworkType.TYPE_4G|SensorsDataAPI.NetworkType.TYPE_WIFI);
9.3. 设置本地缓存上限值
SDK 本地数据库默认缓存数据的上限值为 32MB。 1.7.4 及以后的版本支持通过 setMaxCacheSize 方法来设定缓存数据的上限值。参数单位 byte。
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions 16MB
saConfigOptions.setMaxCacheSize(16 * 1024 * 1024);3.1.0 及之前的版本，设置缓存方式：
//16MB
SensorsDataAPI.sharedInstance().setMaxCacheSize(16 * 1024 * 1024);
当存储数量达到上限值，会依次丢弃老数据，保留最新的数据
9.4. 修改 SDK 配置参数
修改 app/src/main/AndroidManifest.xml，在 标签中，添加 项，可以修改 SDK 的默认参数，支持的选项如下：
com.sensorsdata.analytics.android.FlushInterval - 设置SDK的flushInterval，单位毫秒，默认值为 15 秒；
com.sensorsdata.analytics.android.FlushBulkSize - 设 置 SDK 的 flushBulkSize， 默 认 值 为 100；
com.sensorsdata.analytics.android.ResourcePackageName - 设置 App 的 Package Name，默认值为 Application 对象的 Packa ge
Name，当 App 的 R.* class 的 Package Name 与 Application 不同时，需要手动填入该配置；
例如，设置神策分析 SDK 的 flushInterval 为 30 秒，flushBulkSize 为 50 条，关闭 Toast 提示：
也可以利用代码，修改 FlushInterval 和 FlushBulkSize：
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// SAConfigOptions
// 50
saConfigOptions.setFlushBulkSize(50);
// 30
saConfigOptions.setFlushInterval(30000);
3.1.0 及之前的版本，设置相关参数：
// 50
SensorsDataAPI.sharedInstance().setFlushBulkSize(50);
// 30
SensorsDataAPI.sharedInstance().setFlushInterval(30000);
//
SensorsDataAPI.sharedInstance().enableAutoTrack();
10. 清空本地缓存事件
3.1.5 及以后的版本可以通过 deleteAll 方法，删除 App 本地存储的所有事件。
如果不是特殊要求，请不要调用此方法。
// App
SensorsDataAPI.sharedInstance().deleteAll();11. 设置自签证书
3.1.2 及以后的版本可以通过 setSSLSocketFactory 方法设置自签证书。
在 SDK 初始化后，调用 setSSLSocketFactory(SSLSocketFactory sslSocketFactory) ，设置 javax.net.ssl.SSLSocketFactory 实例进
入 SDK，此时 SDK 内所有的 HTTPS 请求会进行此接口设置的证书校验。
以 DER 格式的证书为例：
try {
// SSLSocketFactory
SSLSocketFactory sslSocketFactory ;
CertificateFactory cf = CertificateFactory.getInstance("X.509");
// R.raw.ca
InputStream in = getResources().openRawResource(R.raw.ca);
Certificate ca = cf.generateCertificate(in);
try {
in.close();
} catch (Exception e)
{ e.printStackTrace(
);
}
KeyStore keystore = KeyStore.getInstance(KeyStore.getDefaultType());
keystore.load(null, null);
keystore.setCertificateEntry("ca", ca);
String tmfAlgorithm = TrustManagerFactory.getDefaultAlgorithm();
TrustManagerFactory tmf = TrustManagerFactory.getInstance(tmfAlgorithm);
tmf.init(keystore);
// Create an SSLContext that uses our TrustManager
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(null, tmf.getTrustManagers(), null);
sslSocketFactory = sslContext.getSocketFactory();
//
SensorsDataAPI.sharedInstance().setSSLSocketFactory(sslSocketFactory);
} catch (Exception e)
{ e.printStackTrace(
);
}
关于 SSL 的更多内容可以参考 谷歌使用文档
12. 追踪并进行渠道匹配和回传
3.2.8 开始 SDK 支持追踪自定义事件时进行渠道匹配，可以调用 SensorsDataAPI.sharedInstance().trackChannelEvent() 方法对匹配的事件
进行追踪，后台匹配到渠道信息后会将结果回传到渠道商。
12.1. 使用方法：
JSONObject properties = new JSONObject(); //
SensorsDataAPI.sharedInstance().trackChannelEvent("", properties);
12.2. 效果：
触发后事件属性会增加 $is_channel_callback_event 和 $channel_device_info 属性 ，如下：其中：
当次安装、首次触发回传事件，记录事件并进行渠道匹配和回传。
当次安装、再次触发回传事件，记录事件并进行渠道匹配，匹配结果不进行回传。
卸载重装、首次触发回传事件，记录事件并进行渠道匹配和回传。
p.s. 上述规则适用于同名事件，不同事件之间不相互影响。
1. 首次触发事件 (事件名存入 sharepreference 中) $is_channel_callback_event 为 true ，否则为 false；
13. 入库前修改事件信息
3.2.10 及以后版本，SDK 可以通过 setTrackEventCallBack 方法过滤埋点的事件数据。
SensorsDataAPI.sharedInstance().setTrackEventCallBack(new SensorsDataTrackEventCallBack() {
/**
*
*
* @param eventName
* @param eventProperties
* @return true false
*/
@Override
public boolean onTrackEvent(String eventName, JSONObject eventProperties) {
// BuyProduct productID
if(eventName.equals("BuyProduct")){
eventProperties.remove("productID");
}
//
return true;
}
});14. 自定义匿名 ID
默认情况下，SDK 会生成匿名 ID 并可以保证该 ID 的唯一性，如果需要替换神策默认分配的匿名 ID ，可以在初始化 SDK 之后立即调用 identify(“用户
自定义匿名 ID ”) 方法进行替换。
// ID SDK
SensorsDataAPI.sharedInstance().identify(“ ID ”);
15. 项目使用 MultiDex 指定神策 Android SDK 的代码都指定到主 DEX 中
如果使用了 MultiDex ，请确保神策 Android SDK 的代码都指定到主 DEX 中。可以通过在 multiDexKeepProguard 里添加如下配置：
-keep class com.sensorsdata.analytics.android.** { *; }Android 全埋点插件配置.全埋点插件配置(Android) v1.13
1. 禁用插件
在工程的 gradle.properties 中配置：
//
sensorsAnalytics.disablePlugin = true
//
sensorsAnalytics.disablePlugin = false
表示插件是否禁用插件，默认值是 false。该配置仅适用于插件版本 3.0.2 及以上。如设置为 true ，将禁用插件，从而影响全埋点的点击事件以及 Fragm
ent 的浏览事件。
2. 多线程编译
在工程 gradle.properties 中配置：
//
sensorsAnalytics.disableMultiThreadBuild = true
//
sensorsAnalytics.disableMultiThreadBuild = false
表示插件是否禁用多线程编译，默认值是 false。该配置仅适用于插件版本 3.0.2 及以上。
3. 增量编译
在工程的 gradle.properties 中配置：
//
sensorsAnalytics.disableIncrementalBuild = true
//
sensorsAnalytics.disableIncrementalBuild = false
表示插件是否禁用增量编译，默认值是 false。该配置仅适用于插件版本 3.0.2 及以上。
4. 开启 Debug 模式
在主 Module 的 build.gradle 中配置：
// Debug
sensorsAnalytics {
debug = true
}
// Debug
sensorsAnalytics {
debug = false
}
表示插件是否开启 Debug 模式，默认值是 false。如果开启 Debug 模式，在编译期间会打印详细日志信息，比如插件当前正在处理哪个 jar、哪个 clas
、哪个 method 等。
5. 启用黑名单/白名单在主 Module 的 build.gradle 中配置：
//
sensorsAnalytics {
useInclude = true
}
//
sensorsAnalytics {
useInclude = false
}
表示是启用黑名单还是白名单，默认值 false。
useInclude = true，表示启用白名单，只处理 include 指定包含的 class、package 和 jar。
useInclude = false，表示启用黑名单，默认会全部处理，然后会排除 exclude 指定的 class、package 和 jar。
6. 白名单
在主 Module 的 build.gradle 中配置：
sensorsAnalytics
{ useInclude =
true
include = [''a.b.c'', ''a.b.c.A'']
}
白名单，可以通过 include 来指定处理哪些 class、package。
如果要自动采集 Fragment 的页面浏览事件，需要将父类是 Fragment 的类加入到白名单中。 例如：A 直接继承 Fragment，B 继承 A ，如果需要采集 B
的页面浏览事件，这个时候需要把 A 加入到白名单中，而不是 B。
示例
sensorsAnalytics
{ useInclude =
true
include = [''demo.sensorsdata.com.sa_sdk_demo.viewpager_fragment'',''com.sensorsdata.analytics.android'']
}
7. 黑名单
在主 Module 的 build.gradle 中配置：
sensorsAnalytics {
exclude = [''a.b.c'', ''a.b.c.A'']
}
黑名单，可以通过 exclude 来指定不处理哪些 class、package，即不处理某个特定的类或包下面的所有类。
示例
sensorsAnalytics {
exclude = [''demo.sensorsdata.com.sa_sdk_demo.viewpager_fragment'',''com.sensorsdata.analytics.android'']
}
8. 是否处理 jar、aar
在主 Module 的 build.gradle 中配置：// jaraar
sensorsAnalytics {
disableJar = true
}
// jaraar
sensorsAnalytics {
disableJar = false
}
表示插件是否处理 jar 和 aar，默认值 false。如果开启使用黑名单，通过 disableJar = true 可以一次性将所有的 jar 和 aar 加入到黑名单里。
9. 是否支持 Lambda
在主 Module 的 build.gradle 中配置：
// Lambda
sensorsAnalytics {
lambdaEnabled = true
}
// Lambda
sensorsAnalytics {
lambdaEnabled = false
}
表示插件是否支持处理 Lambda ，默认值 true。
10. 禁止获取 IMEI 号
在主 Module 的 build.gradle 中配置：
// IMEI
sensorsAnalytics {
sdk {
disableIMEI = true
}
}
// IMEI
sensorsAnalytics {
sdk {
disableIMEI = false
}
}
是否禁止 SDK 获取 IMEI 号，默认值为 false。该配置仅适用于插件版本 3.0.0及以上。如设置为 true , 将会影响到渠道追踪。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
11. 禁止获取 MacAddress
在主 Module 的 build.gradle 中配置：
// MacAddress
sensorsAnalytics {
sdk {
disableMacAddress = true}
}
// MacAddress
sensorsAnalytics {
sdk {
disableMacAddress = false
}
}
是否禁止 SDK 获取 MacAddress，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上。如设置为 true , 将会影响渠道追踪。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
12. 禁止获取 Android ID
在主 Module 的 build.gradle 中配置：
// Android ID
sensorsAnalytics {
sdk {
disableAndroidID = true
}
}
// Android ID
sensorsAnalytics {
sdk {
disableAndroidID = false
}
}
是否禁止 SDK 获取 Android ID，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上。如设置为 true, 将会影响到事件属性 $device_id 以及渠道追
踪。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
13. 禁用 SDK 打印日志
在主 Module 的 build.gradle 中配置：
// SDK
sensorsAnalytics {
sdk {
disableLog = true
}
}
// SDK
sensorsAnalytics {
sdk {
disableLog = false
}
}
是否禁用 SDK 日志打印，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上。如设置为 true，SDK 将不会打印 Log 日志和异常日志。Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
14. 禁用 JavaScript 注入
在主 Module 的 build.gradle 中配置：
// JavaScript
sensorsAnalytics {
sdk {
disableJsInterface = true
}
}
// JavaScript
sensorsAnalytics {
sdk {
disableJsInterface = false
}
}
是否禁用 SDK 中 JavaScript 注入相关代码，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上，如设置为 true ，将会影响 App 与 H5 打通。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
15. 禁止获取运营商信息
在主 Module 的 build.gradle 中配置：
//
sensorsAnalytics {
sdk {
disableCarrier = true
}
}
//
sensorsAnalytics {
sdk {
disableCarrier = false
}
}
是否禁止 SDK 获取运营商信息，默认值为 false。该配置仅适用于插件版本 3.0.1 及以上，如设置为 true ，将会无法采集到运营商信息。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
16. 是否在方法前插入代码
默认值是 false
如需开启配置，在工程的 gradle.properties 中加入以下配置：
sensorsAnalytics.isHookOnMethodEnter = true表示是否在方法前插入代码。该配置仅适用于插件版本 3.1.9 及以上。.全埋点插件配置(Android) v1.14
1. 禁用插件
在工程的 gradle.properties 中配置：
//
sensorsAnalytics.disablePlugin = true
//
sensorsAnalytics.disablePlugin = false
表示插件是否禁用插件，默认值是 false。该配置仅适用于插件版本 3.0.2 及以上。如设置为 true ，将禁用插件，从而影响全埋点的点击事件以及 Fragm
ent 的浏览事件。
2. 多线程编译
在工程 gradle.properties 中配置：
//
sensorsAnalytics.disableMultiThreadBuild = true
//
sensorsAnalytics.disableMultiThreadBuild = false
表示插件是否禁用多线程编译，默认值是 false。该配置仅适用于插件版本 3.0.2 及以上。
3. 增量编译
在工程的 gradle.properties 中配置：
//
sensorsAnalytics.disableIncrementalBuild = true
//
sensorsAnalytics.disableIncrementalBuild = false
表示插件是否禁用增量编译，默认值是 false。该配置仅适用于插件版本 3.0.2 及以上。
4. 开启 Debug 模式
在主 Module 的 build.gradle 中配置：
// Debug
sensorsAnalytics {
debug = true
}
// Debug
sensorsAnalytics {
debug = false
}
表示插件是否开启 Debug 模式，默认值是 false。如果开启 Debug 模式，在编译期间会打印详细日志信息，比如插件当前正在处理哪个 jar、哪个 clas
、哪个 method 等。
5. 启用黑名单/白名单在主 Module 的 build.gradle 中配置：
//
sensorsAnalytics {
useInclude = true
}
//
sensorsAnalytics {
useInclude = false
}
表示是启用黑名单还是白名单，默认值 false。
useInclude = true，表示启用白名单，只处理 include 指定包含的 class、package 和 jar。
useInclude = false，表示启用黑名单，默认会全部处理，然后会排除 exclude 指定的 class、package 和 jar。
6. 白名单
在主 Module 的 build.gradle 中配置：
sensorsAnalytics
{ useInclude =
true
include = [''a.b.c'', ''a.b.c.A'']
}
白名单，可以通过 include 来指定处理哪些 class、package。
如果要自动采集 Fragment 的页面浏览事件，需要将父类是 Fragment 的类加入到白名单中。 例如：A 直接继承 Fragment，B 继承 A ，如果需要采集 B
的页面浏览事件，这个时候需要把 A 加入到白名单中，而不是 B。
示例
sensorsAnalytics
{ useInclude =
true
include = [''demo.sensorsdata.com.sa_sdk_demo.viewpager_fragment'',''com.sensorsdata.analytics.android'']
}
7. 黑名单
在主 Module 的 build.gradle 中配置：
sensorsAnalytics {
exclude = [''a.b.c'', ''a.b.c.A'']
}
黑名单，可以通过 exclude 来指定不处理哪些 class、package，即不处理某个特定的类或包下面的所有类。
示例
sensorsAnalytics {
exclude = [''demo.sensorsdata.com.sa_sdk_demo.viewpager_fragment'',''com.sensorsdata.analytics.android'']
}
8. 是否处理 jar、aar
在主 Module 的 build.gradle 中配置：// jaraar
sensorsAnalytics {
disableJar = true
}
// jaraar
sensorsAnalytics {
disableJar = false
}
表示插件是否处理 jar 和 aar，默认值 false。如果开启使用黑名单，通过 disableJar = true 可以一次性将所有的 jar 和 aar 加入到黑名单里。
9. 是否支持 Lambda
在主 Module 的 build.gradle 中配置：
// Lambda
sensorsAnalytics {
lambdaEnabled = true
}
// Lambda
sensorsAnalytics {
lambdaEnabled = false
}
表示插件是否支持处理 Lambda ，默认值 true。
10. 禁止获取 IMEI 号
在主 Module 的 build.gradle 中配置：
// IMEI
sensorsAnalytics {
sdk {
disableIMEI = true
}
}
// IMEI
sensorsAnalytics {
sdk {
disableIMEI = false
}
}
是否禁止 SDK 获取 IMEI 号，默认值为 false。该配置仅适用于插件版本 3.0.0及以上。如设置为 true , 将会影响到渠道追踪。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
11. 禁止获取 MacAddress
在主 Module 的 build.gradle 中配置：
// MacAddress
sensorsAnalytics {
sdk {
disableMacAddress = true}
}
// MacAddress
sensorsAnalytics {
sdk {
disableMacAddress = false
}
}
是否禁止 SDK 获取 MacAddress，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上。如设置为 true , 将会影响渠道追踪。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
12. 禁止获取 Android ID
在主 Module 的 build.gradle 中配置：
// Android ID
sensorsAnalytics {
sdk {
disableAndroidID = true
}
}
// Android ID
sensorsAnalytics {
sdk {
disableAndroidID = false
}
}
是否禁止 SDK 获取 Android ID，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上。如设置为 true, 将会影响到事件属性 $device_id 以及渠道追
踪。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
13. 禁用 SDK 打印日志
在主 Module 的 build.gradle 中配置：
// SDK
sensorsAnalytics {
sdk {
disableLog = true
}
}
// SDK
sensorsAnalytics {
sdk {
disableLog = false
}
}
是否禁用 SDK 日志打印，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上。如设置为 true，SDK 将不会打印 Log 日志和异常日志。Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
14. 禁用 JavaScript 注入
在主 Module 的 build.gradle 中配置：
// JavaScript
sensorsAnalytics {
sdk {
disableJsInterface = true
}
}
// JavaScript
sensorsAnalytics {
sdk {
disableJsInterface = false
}
}
是否禁用 SDK 中 JavaScript 注入相关代码，默认值为 false。该配置仅适用于插件版本 3.0.0 及以上，如设置为 true ，将会影响 App 与 H5 打通。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
15. 禁止获取运营商信息
在主 Module 的 build.gradle 中配置：
//
sensorsAnalytics {
sdk {
disableCarrier = true
}
}
//
sensorsAnalytics {
sdk {
disableCarrier = false
}
}
是否禁止 SDK 获取运营商信息，默认值为 false。该配置仅适用于插件版本 3.0.1 及以上，如设置为 true ，将会无法采集到运营商信息。
Android Grdle Plugin 3.2.0Android Studio 3.2 gradle.properties
android.enableD8.desugaring = true
16. 是否在方法前插入代码
默认值是 false
如需开启配置，在工程的 gradle.properties 中加入以下配置：
sensorsAnalytics.isHookOnMethodEnter = true表示是否在方法前插入代码。该配置仅适用于插件版本 3.1.9 及以上。Android SDK OAID 使用文档.OAID使用(Android) v1.13
1. OAID 简介
在 Android 10 版本中，广告渠道商们作为非厂商系统应用将无法获取 IMEI、MAC 等设备信息。旧版本的手机系统在用户手动升级前将保持不变，但是搭
载 Android 10 系统的手机系统将不支持获取 IMEI。在一段时间内，将处于新旧版手机系统共存的状态，但是新版手机系统的用户占比将会逐渐提高，会
造成新版系统用户无法进行推广渠道的匹配。
近日移动安全联盟针对该问题联合国内手机厂商推出补充设备标准体系方案，选择 OAID 字段作为 IMEI 等的替代字段 。广告渠道商选择 OAID 作为 IMEI
的替代字段。OAID 字段是由中国信通院联合华为、小米、OPPO、VIVO 等厂商共同推出的设备识别字段，具有一定的权威性。OAID 的准确性和覆盖率均满
足广告场景的使用需求。
关于 OAID 更多信息可参考 移动安全联盟官网。
2. 适配 OAID 渠道匹配基本步骤
2.1. 渠道追踪链接部分
以今日头条为例：
旧的渠道追踪链接：
https://xxx.xxx.com?
token=21f2e56df73988c7&project=chenru&channel_name=toutiao_track&callback_url= CALLBACK_URL &os= OS &idfa=
IDFA &ip= IP &ua= UA1 &mac= MAC
新的渠道追踪链接：
https://xxx.xxx.com?
token=21f2e56df73988c7&project=chenru&channel_name=toutiao_track&callback_url= CALLBACK_URL &oaid= OAID &os=
OS &idfa= IDFA &ip= IP &ua= UA1 &mac= MAC
通过上面对比可以发现新的渠道追踪链接相比旧的渠道追踪链接，增加了 &oaid= OAID 一项。
注意：从神策分析系统 1.15+ 版本之后，部分 App 精准匹配的渠道创建渠道监测连接时，会带有 oaid ，如若没有，可咨询神策值班同学。oaid 的宏参数
样式具体取决于广告商，并非所有渠道的 oaid 宏参数都是 OAID
2.2. Android SDK 部分
App 端参照移动安全联盟集成文档（下载链接：http://www.msa-alliance.cn/col.jsp?id=120），OAID SDK 集成，并且将神策 Android SDK 升级到至
少 3.2.7 版本。
OAID 兼容的 v1.0.13 版本，需要兼容神策 SDK 版本是 3.2.11。
2.3. 神策后台部分
2.3.1. SA
1.13 需要大于等于 1.13.5812
1.14 需要大于等于 1.14.687
2.3.2. SP
1.15 需要大于等于 1.15.870
1.16 需要大于等于 1.16.869
3. 在项目中集成 OAID SDK 步骤
App 端集成步骤，主要是参照移动安全联盟给的集成文档 http://www.msa-alliance.cn/col.jsp?id=120。3.1. 把 miit_mdid_x.x.x.aar 拷⻉到项目的 libs 目录，并设置依赖，其中 x.x.x 代表版本
号。（注意，要及时关注移动联盟更新文档，保持版本及时更新。）
3.2. 将 supplierconfig.json 拷⻉到项目 assets 目录下。3.3. 在项目 Module 的 build.gradle 文件中配置依赖。
dependencies {
implementation fileTree(dir: ''libs'', include: [''*.jar''])
implementation files(''libs/miit_mdid_1.0.10.aar'')
}
3.4. 混淆设置
-keep class com.bun.miitmdid.core.** {*;}
3.5. 设置 gradle 编译选项，这块可以根据自己对平台的选择进合理配置。
android {
compileSdkVersion 28
defaultConfig {
ndk {
abiFilters ''armeabi-v7a'',''x86'',''arm64-v8a'',''x86_64'',''armeabi''
}
packagingOptions {
doNotStrip "*/armeabi-v7a/*.so"
doNotStrip "*/x86/*.so"
doNotStrip "*/arm64-v8a/*.so"
doNotStrip "*/x86_64/*.so"
doNotStrip "armeabi.so"
}
}
}
3.6. 调用神策 SDK 的 trackInstallation 代码触发激活事件
集成获取 OAID 的第三方 SDK 后，调用神策 SDK 中的 trackInstallation 方法即可完成激活，可通过日志查看激活事件中的 $ios_install_source
字段，oaid 有值表示集成成功
"$ios_install_source":"android_id=8bc673b56ca9c1bc##imei=867436048638793##imei_old=867436047338791##mac=20:34:
FB:1A:E3:AA##oaid=47befdff-fb1f-4b96-ddff-bf3fb77f744e"
这里需要注意的是，OAID 只是在 Android Q 上的渠道匹配字段，在其它版本，仍然利用 IMEI 作为渠道匹配字段，所以 trackInstallation 的代码仍
然需要在 READ_PHONE_STATE 权限申请回调中触发。可参考 示例代码.OAID使用(Android) v1.15
1. OAID 简介
在 Android 10 版本中，广告渠道商们作为非厂商系统应用将无法获取 IMEI、MAC 等设备信息。旧版本的手机系统在用户手动升级前将保持不变，但是搭
载 Android 10 系统的手机系统将不支持获取 IMEI。在一段时间内，将处于新旧版手机系统共存的状态，但是新版手机系统的用户占比将会逐渐提高，会
造成新版系统用户无法进行推广渠道的匹配。
近日移动安全联盟针对该问题联合国内手机厂商推出补充设备标准体系方案，选择 OAID 字段作为 IMEI 等的替代字段 。广告渠道商选择 OAID 作为 IMEI
的替代字段。OAID 字段是由中国信通院联合华为、小米、OPPO、VIVO 等厂商共同推出的设备识别字段，具有一定的权威性。OAID 的准确性和覆盖率均满
足广告场景的使用需求。
关于 OAID 更多信息可参考 移动安全联盟官网。
2. 适配 OAID 渠道匹配基本步骤
2.1. 渠道追踪链接部分
以今日头条为例：
旧的渠道追踪链接：
https://xxx.xxx.com?
token=21f2e56df73988c7&project=chenru&channel_name=toutiao_track&callback_url= CALLBACK_URL &os= OS &idfa=
IDFA &ip= IP &ua= UA1 &mac= MAC
新的渠道追踪链接：
https://xxx.xxx.com?
token=21f2e56df73988c7&project=chenru&channel_name=toutiao_track&callback_url= CALLBACK_URL &oaid= OAID &os=
OS &idfa= IDFA &ip= IP &ua= UA1 &mac= MAC
通过上面对比可以发现新的渠道追踪链接相比旧的渠道追踪链接，增加了 &oaid= OAID 一项。
注意：从神策分析系统 1.15+ 版本之后，部分 App 精准匹配的渠道创建渠道监测连接时，会带有 oaid ，如若没有，可咨询神策值班同学。oaid 的宏参数
样式具体取决于广告商，并非所有渠道的 oaid 宏参数都是 OAID
2.2. Android SDK 部分
App 端参照移动安全联盟集成文档（下载链接：http://www.msa-alliance.cn/col.jsp?id=120），OAID SDK 集成，并且将神策 Android SDK 升级到至
少 3.2.7 版本。
OAID 兼容的 v1.0.13 版本，需要兼容神策 SDK 版本是 3.2.11。
2.3. 神策后台部分
2.3.1. SA
1.13 需要大于等于 1.13.5812
1.14 需要大于等于 1.14.687
2.3.2. SP
1.15 需要大于等于 1.15.870
1.16 需要大于等于 1.16.869
3. 在项目中集成 OAID SDK 步骤
App 端集成步骤，主要是参照移动安全联盟给的集成文档 http://www.msa-alliance.cn/col.jsp?id=120。3.1. 把 miit_mdid_x.x.x.aar 拷⻉到项目的 libs 目录，并设置依赖，其中 x.x.x 代表版本
号。（注意，要及时关注移动联盟更新文档，保持版本及时更新。）
3.2. 将 supplierconfig.json 拷⻉到项目 assets 目录下。3.3. 在项目 Module 的 build.gradle 文件中配置依赖。
dependencies {
implementation fileTree(dir: ''libs'', include: [''*.jar''])
implementation files(''libs/miit_mdid_1.0.10.aar'')
}
3.4. 混淆设置
-keep class com.bun.miitmdid.core.** {*;}
3.5. 设置 gradle 编译选项，这块可以根据自己对平台的选择进合理配置。
android {
compileSdkVersion 28
defaultConfig {
ndk {
abiFilters ''armeabi-v7a'',''x86'',''arm64-v8a'',''x86_64'',''armeabi''
}
packagingOptions {
doNotStrip "*/armeabi-v7a/*.so"
doNotStrip "*/x86/*.so"
doNotStrip "*/arm64-v8a/*.so"
doNotStrip "*/x86_64/*.so"
doNotStrip "armeabi.so"
}
}
}
3.6. 调用神策 SDK 的 trackInstallation 代码触发激活事件
集成获取 OAID 的第三方 SDK 后，调用神策 SDK 中的 trackInstallation 方法即可完成激活，可通过日志查看激活事件中的 $ios_install_source
字段，oaid 有值表示集成成功
"$ios_install_source":"android_id=8bc673b56ca9c1bc##imei=867436048638793##imei_old=867436047338791##mac=20:34:
FB:1A:E3:AA##oaid=47befdff-fb1f-4b96-ddff-bf3fb77f744e"
这里需要注意的是，OAID 只是在 Android Q 上的渠道匹配字段，在其它版本，仍然利用 IMEI 作为渠道匹配字段，所以 trackInstallation 的代码仍
然需要在 READ_PHONE_STATE 权限申请回调中触发。可参考 示例代码Android SDK 常见问题.常见问题(Android) v1.13
1. SDK 是否需要混淆？
由于 SDK 本身就是开源的， 如果你们没有对 SDK 的核心逻辑做修改，不建议混淆。再加上 SDK 中有部分类和接口会被 H5 中的 JavaScript 调用，如果
混淆，这部分代码会被混淆掉。
2. DebugMode 中的 DEBUG_ONLY 与 DEBUG_AND_TRACK 有什么区别？
在 DEBUG_ONLY 模式下，同步数据时，服务端只做校验，不会真正的导入数据。 而在 DEBUG_AND_TRACK 模式下，服务端校验并且会导入数据。
3. 事件名称和属性名称，是否可以直接用中文？
event 和 properties 的名称必须是合法的变量名，即不能以数字开头，且只包含：大小写字母、数字、下划线和 $。
事件属性的 value 支持的类型为：String 、Number、JSONArray 、Boolean 、Date 。
4. 渠道信息应该放在哪里？
profile 里面的渠道使用用户第一次启动时带上的渠道信息，记录用户是从哪里来的，这样在以后的事件分析里就可以看到不同渠道来的用户的情况。不太
建议每个事件中都放入当前渠道，因为在 app 中不像 web 一样渠道更新频繁
5. 在发送事件的时候，某些情况下，有的属性值没有，是建议为空还是不带上
这个属性?
不带上，或者为 null，效果一样的。
6. 使用 eclipse 集成时，报 SensorsDataContentProvider 找不到?
eclipse 不能 merge AndroidManifest.xml 文件，需要在 AndroidManifest 标签中下加入以下配置：
...
...
...
7. $title 字段采集不对应 ?
如果没有使用到 ActionBar 可以在 Manifest 中给相应的 Activity 设置 label ，这样 $title 字段采集的内容 就会是你设置的 label 内容。
...8. 初始化 SDK 时出现 javax.net.ssl.SSLHandshakeException:Invalid input
to ASCII
项目的数据接收地址包含了 ‘_’，在https中报错了
9. Fragment 页面浏览事件 $title 的设置
Fragment 页面浏览事件 $title 属性默认与所在 Activity 的 $title 采集规则一致。
在 SDK 2.0.0 及以上的版本可使用 @SensorsDataFragmentTitle 注解设置 Fragment 的 $title 属性的值。
例：
@SensorsDataFragmentTitle(title = "HomeFragment")
public class HomeFragment extends Fragment {
...
}
10. 神策插件与 SDK 适配版本
神策插件 android-gradle-plugin2 版本与 SDK 适配版本，如下：
插件版本 SDK 版本
1.X 1.X
2.X 2.X
3.X 3.X
11. 启动事件与退出事件的详细说明
神策 SDK 为了应对多进程、强杀等场景，在 2.0.3 版本加入了 30 秒的 session 机制，用户退出 App 到后台 30 秒的时候，才会触发退出事件，
之后再启动 App，才会触发启动事件，用户如果在 30 秒内打开了 App，那么是没有对应的退出事件与启动事件的。
另外，如果在退出 App 到后台 30 秒内，进程还没有被杀掉，那么此时会触发退出事件并尝试上报，如果进程被杀掉了，那么退出事件会在下一次启动时补
发。所以在查看数据时，
一般退出事件比启动事件少。
12. 事件的动态公共属性与静态公共属性的区别
SDK 中的 动态公共属性 与 静态公共属性 是为了满足不同的场景而设置的。公共属性适用一直于不变的属性，比如我可以设置一个公共属性为应用名称；动
态公共属性适用于经常变化的属性，比如我可以设置一个用户是否登录的属性。
而在 SDK 中，事件优先级从低到高依次是：预制属性 < 静态公共属性 < 动态公共属性 < 自定义事件属性，当命名相同时，优先级高的会覆盖优先级低的属性
值，所以动态公共属性可以覆盖静态公共属性的值
13. 预置事件增加自定义属性说明
$AppStart（App 启动），$AppEnd（App 退出），只能通过增加 公共属性 增加自定义属性。
$AppViewScreen（App 浏览页面）Android 端全埋点采集的事件通过 ScreenAutoTracker 接口增加自定义属性；通过代码 track 的 $AppViewScr
een 事件，可参考文档 trackViewScreen 方法。
$AppClick（App 元素点击）Android 端全埋点采集的事件通过 setViewProperties 接口增加自定义属性；通过代码 track 的 $AppClick 事件，可
参考此文档：trackViewAppClick 方法。iOS SDK.iOS SDK v1.13
基本使用(iOS)
介绍 SDK 的常用功能点及使用方式。
全埋点(iOS)
介绍 SDK 全埋点采集的原理、全埋点事件的忽略与补充、属性的手动补充等知识。
高级功能(iOS)
介绍 SDK 中特殊场景下的一些功能及使用方式。
常见问题(iOS)
介绍 SDK 集成和使用过程中的一些常见疑问。
App Extension 中的使用
介绍 App Extension 中怎么使用 SDK 采集事件。
在使用前，请先阅读 数据模型 的介绍
SDK 的更新日志，可参阅 Release Notes
集成神策分析 SDK
项目 Podfile 中添加以下配置：
pod ''SensorsAnalyticsSDK''
在 Podfile 目录下执行 pod install 安装 SDK。
注意：如果执行 pod update 无法检测到最新版本，可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存后重新 update。
集成 SDK 会使 App 安装包体积增加约 350KB。
初始化 SDK 并开启全埋点
初始化 SDK 需要配置上报数据的目标地址，该地址可以使用管理员账户进行获取。需要在程序入口主线程同步初始化 SDK，否则可能会丢失部分事件数据。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<##> launchOptions:launchOptions];
//
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
SensorsAnalyticsEventTypeAppEnd |
SensorsAnalyticsEventTypeAppClick |
SensorsAnalyticsEventTypeAppViewScreen;
#ifdef DEBUG
// SDK Log
options.enableLog = YES;
#endif
// SDK
[SensorsAnalyticsSDK startWithConfigOptions:options];return YES;
}
配置 Scheme
项目的 scheme 需要管理员账户进行获取
如果 App 在不同环境中使用到了多个数据接收地址，也应该配置多个与之对应的 scheme
获取当前项目 scheme 值
App 中配置 schemeApp 工程选择 target -> Info -> Types，点击加号(+)，将上一步获取到的 scheme 配置到 URL Schemes 中。
处理传入的 URL
AppDelegate 中的 - application:openURL:options: 方法中调用 - handleSchemeUrl: 对神策分析 scheme 进行处理。
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:
(NSDictionary *)options {
if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url])
{ return YES;
}
return NO;
}
如果 - application:openURL:options: 中还有其他逻辑处理，需要将 - handleSchemeUrl: 尽量前置，以保证 - handleSchemeUrl: 能被执行。
代码埋点追踪事件
可以通过 - track: 和 - track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性：
UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;
[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
withProperties:@{@"ProductID" : [NSNumber
numberWithUnsignedLong:productId],
@"ProductCatalog" :
productCatalog,
@"IsAddedToFav" :
isAddedToFavorites ? @YES : @NO}];
事件名和属性名需要时合法变量名，且不能以 $ 开头；
属性名大小写敏感，并且不同事件会共用同名属性。即若 foo 事件含有 "aaa" 属性，则后续所有事件不能使用与 "aaa" 仅大小写不同的属性
(如 aAa、aaA)；
事件名和属性其他约束，具体请参考 数据格式。
设置事件公共属性如果所有事件中都需要某些相同的属性，可使用 - registerSuperProperties: 把这些属性注册为公共属性：
// AppName
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];
// AppName
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{@"ProductID" : [NSNumber
numberWithUnsignedLong:123456]}];
在初始化 SDK 之后尽早设置公共属性
公共属性会保存在 App 本地缓存中。可以通过 -unregisterSuperProperty: 删除一个公共属性，或使用 -clearSuperProperties: 删除所有已
设置的事件公共属性
公共属性约束和事件属性相同，详情参考数据格式
事件动态公共属性
动态公共属性和公共属性的区别是：前者适合标记年龄，后者适合标记性别。
对于一些值会变化的公共属性，如当前游戏等级、最新金币余额等，1.10.8+ 版本 SDK 提供了- registerDynamicSuperProperties: 接口来设置动态公共属性:
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary *
_Nonnull{ return @{@"level": <##>,
@"balance": <##>};
}];
事件属性的优先级为：track 事件时传入的属性 > 动态公共属性 > 公共属性> 预置属性；
动态公共属性的约束和事件属性相同，详情参考数据格式。
记录激活事件
如果使用了神策渠道追踪功能，则需要在 App 启动时调用 - trackInstallation: 记录安装激活事件：
//
[[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"
withProperties:@{@"DownloadChannel": @"AppStore"}];
第一次调用 - trackInstallation: 时， SDK 会在 KeyChain 中记录一个标志位。只有 App 在当前设备上的首次安装才会记录激活事件，卸载重
装不重复触发。
第一次调用 - trackInstallation: 时， SDK 会触发您命名的激活事件，并设置用户 $first_visit_time 属性。
更多关于渠道追踪功能介绍请参考渠道追踪。
用户登录
当用户在客户端进行登录时，需要调用SDK 的 - login: 接口：
[[SensorsAnalyticsSDK sharedInstance] login:@"<#ID#>"];
为了准确记录登录用户的行为信息，建议在以下时机各调用一次 - login: 接口：·
·
· App
调用- login: 传入的值应当是可以唯一标识单个用户的 ID，通常是业务数据库里的主键或其它唯一标识。
设置用户属性
除了给事件添加属性，SDK 也支持给用户设置属性，如年龄、性别、等级，神策事件分析、留存分析、分布分析等功能均支持使用用户属性作为过滤条件，
精确分析特定人群的指标。
关于事件属性和用户属性的区别，请参考数据模型
用户属性的命名约束，请参考参考数据格式
属性更新
- set:、- set:to:，可以设定用户属性，同一个 key 多次设置时，value 值会进行覆盖替换。
// "Gender" "Male"
// set:WithValue
[[SensorsAnalyticsSDK sharedInstance] set:@"Gender" to:@"Male"];
// "Age" 18
// set:
[[SensorsAnalyticsSDK sharedInstance] set:@{@"Age" : [NSNumber numberWithInt:18]}];
保留初次属性
对于需要保证只有首次设置时有效的属性，如用户首次充值金额、首次设置的昵称等，可以使用 - setOnce: 或 - setOnce:to: 接口进行记录。与 - set: 方
法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。
// AdSource "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"App Store"];
// AdSource AdSource "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"Email"];
数值属性累加
针对一些数值型属性，如消费总额、用户积分等属性，我们可以使用 - increment: 或 - increment:by: 对原值进行累加，神策会自动计算并保存累加之后的
值。
//
// increment:by:
[[SensorsAnalyticsSDK sharedInstance] increment:@"GamePlayed" by:[NSNumber numberWithInt:1]];
//
// increment:
[[SensorsAnalyticsSDK sharedInstance] increment:@{@"UserPaid" : [NSNumber numberWithInt:1],
@"
PointEarned" : [NSNumber numberWithFloat:12.5]}];
列表属性追加对于列表类型用户属性，如用户喜爱的电影、用户点评过的餐厅等属性，可以调用 - append:by: 接口进行追加一些新值。
// "Movies" : ["Sicario", @"Love Letter"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Sicario", @"Love Letter"]]];
// "Movies" : ["Sicario", @"Love Letter", @"Dead Poets Society"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Love Letter", @"Dead Poets
Society"]]];
列表型属性中的元素必须为 NSString 类型，且元素的值会自动去重。关于列表型限制请见数据格式。
属性取消
如果需要取消已设置的某个用户属性，可以调用 - unset: 进行取消
// gender
[[SensorsAnalyticsSDK sharedInstance] unset:@"Gender"];
打 通 App 与 H5
神策分析 SDK 提供打通 iOS App 与 H5 功能，详情介绍请参考打通 App 与 H5。
可视化全埋点
版本要求
神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+
iOS SDK v2.0.0+
本功能使用前，请确保您 iOS 项目中已完成配置 Scheme
可视化全埋点在神策分析中的使用，请参考可视化全埋点
开启可视化全埋点
SDK 初始化前将 SAConfigOptions 实例 - enableVisualizedAutoTrack 属性设置为 YES 即可开启可视化全埋点：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
//
options.enableVisualizedAutoTrack = YES;
部分页面开启可视化全埋点
可视化全埋点开启后，默认对 App 内全部页面生效，如果只需要部分页面开启可视化全埋点，可以在 SDK 初始化后使用- addVisualizedAutoTrackViewC
ontrollers: 进行添加：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// MainController
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"
MainController"]];
调试查看数据
SDK 初始化前将 SAConfigOptions 实例 enableLog 属性设置为 YES 即可打开 SDK 的日志输出功能，呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
#ifdef DEBUG
// SDK Log
options.enableLog = YES;
#endif
然后在 IDE (如 Xcode )日志控制台中筛选 SALog 关键词：
埋点事件触发成功时，SDK 会输出 【track event】 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 【valid message】字段开头的事件数据；
事件数据上报失败时，SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因。
所有事件公共预置属性
神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK
预置事件和预置属性 。iOS SDK 基本使用.基本使用(iOS) v1.13
在使用前，请先阅读 数据模型 的介绍
SDK 的更新日志，可参阅 Release Notes
1. 集成神策分析 SDK
项目 Podfile 中添加以下配置：
pod ''SensorsAnalyticsSDK''
在 Podfile 目录下执行 pod install 安装 SDK。
注意：如果执行 pod update 无法检测到最新版本，可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存后重新 update。
集成 SDK 会使 App 安装包体积增加约 350KB。
2. 初始化 SDK 并开启全埋点
初始化 SDK 需要配置上报数据的目标地址，该地址可以使用管理员账户进行获取。
需要在程序入口主线程同步初始化 SDK，否则可能会丢失部分事件数据。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<##> launchOptions:launchOptions];
//
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
SensorsAnalyticsEventTypeAppEnd |
SensorsAnalyticsEventTypeAppClick |
SensorsAnalyticsEventTypeAppViewScreen;
#ifdef DEBUG
// SDK Log
options.enableLog = YES;
#endif// SDK
[SensorsAnalyticsSDK startWithConfigOptions:options];
return YES;
}
3. 配置 Scheme
项目的 scheme 需要管理员账户进行获取
如果 App 在不同环境中使用到了多个数据接收地址，也应该配置多个与之对应的 scheme
3.1. 获取当前项目 scheme 值
3.2. App 中配置 scheme
App 工程选择 target -> Info -> Types，点击加号(+)，将上一步获取到的 scheme 配置到 URL Schemes 中。
3.3. 处理传入的 URL
AppDelegate 中的 - application:openURL:options: 方法中调用 - handleSchemeUrl: 对神策分析 scheme 进行处理。- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:
(NSDictionary *)options {
if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url])
{ return YES;
}
return NO;
}
如果 - application:openURL:options: 中还有其他逻辑处理，需要将 - handleSchemeUrl: 尽量前置，以保证 - handleSchemeUrl: 能被执行。
4. 代码埋点追踪事件
可以通过 - track: 和 - track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性：
UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;
[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
withProperties:@{@"ProductID" : [NSNumber
numberWithUnsignedLong:productId],
@"ProductCatalog" :
productCatalog,
@"IsAddedToFav" :
isAddedToFavorites ? @YES : @NO}];
事件名和属性名需要时合法变量名，且不能以 $ 开头；
属性名大小写敏感，并且不同事件会共用同名属性。即若 foo 事件含有 "aaa" 属性，则后续所有事件不能使用与 "aaa" 仅大小写不同的属性
(如 aAa、aaA)；
事件名和属性其他约束，具体请参考 数据格式。
5. 设置事件公共属性
如果所有事件中都需要某些相同的属性，可使用 - registerSuperProperties: 把这些属性注册为公共属性：
// AppName
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];
// AppName
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{@"ProductID" : [NSNumber
numberWithUnsignedLong:123456]}];
在初始化 SDK 之后尽早设置公共属性
公共属性会保存在 App 本地缓存中。可以通过 -unregisterSuperProperty: 删除一个公共属性，或使用 -clearSuperProperties: 删除所有已
设置的事件公共属性
公共属性约束和事件属性相同，详情参考数据格式
5.1. 事件动态公共属性
动态公共属性和公共属性的区别是：前者适合标记年龄，后者适合标记性别。对于一些值会变化的公共属性，如当前游戏等级、最新金币余额等，1.10.8+ 版本 SDK 提供了- registerDynamicSuperProperties: 接口来设置动态公共属性:
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary *
_Nonnull{ return @{@"level": <##>,
@"balance": <##>};
}];
事件属性的优先级为：track 事件时传入的属性 > 动态公共属性 > 公共属性> 预置属性动
态公共属性的约束和事件属性相同，详情参考数据格式
6. 记录激活事件
如果使用了神策渠道追踪功能，则需要在 App 启动时调用 - trackInstallation: 记录安装激活事件：
//
[[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"
withProperties:@{@"DownloadChannel": @"AppStore"}];
第一次调用 - trackInstallation: 时， SDK 会在 KeyChain 中记录一个标志位。只有 App 在当前设备上的首次安装才会记录激活事件，卸载重
装不重复触发。
第一次调用 - trackInstallation: 时， SDK 会触发您命名的激活事件，并设置用户 $first_visit_time 属性。
更多关于渠道追踪功能介绍请参考渠道追踪。
7. 用户登录
当用户在客户端进行登录时，需要调用SDK 的 - login: 接口：
[[SensorsAnalyticsSDK sharedInstance] login:@"<#ID#>"];
为了准确记录登录用户的行为信息，建议在以下时机各调用一次 - login: 接口：
·
·
· App
调用- login: 传入的值应当是可以唯一标识单个用户的 ID，通常是业务数据库里的主键或其它唯一标识。
8. 设置用户属性
除了给事件添加属性，SDK 也支持给用户设置属性，如年龄、性别、等级，神策事件分析、留存分析、分布分析等功能均支持使用用户属性作为过滤条件，
精确分析特定人群的指标。
关于事件属性和用户属性的区别，请参考数据模型
用户属性的命名约束，请参考参考数据格式
8.1. 属性更新- set:、- set:to:，可以设定用户属性，同一个 key 多次设置时，value 值会进行覆盖替换。
// "Gender" "Male"
// set:WithValue
[[SensorsAnalyticsSDK sharedInstance] set:@"Gender" to:@"Male"];
// "Age" 18
// set:
[[SensorsAnalyticsSDK sharedInstance] set:@{@"Age" : [NSNumber numberWithInt:18]}];
8.2. 保留初次属性
对于需要保证只有首次设置时有效的属性，如用户首次充值金额、首次设置的昵称等，可以使用 - setOnce: 或 - setOnce:to: 接口进行记录。与 - set: 方
法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。
// AdSource "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"App Store"];
// AdSource AdSource "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"Email"];
8.3. 数值属性累加
针对一些数值型属性，如消费总额、用户积分等属性，我们可以使用 - increment: 或 - increment:by: 对原值进行累加，神策会自动计算并保存累加之后的
值。
//
// increment:by:
[[SensorsAnalyticsSDK sharedInstance] increment:@"GamePlayed" by:[NSNumber numberWithInt:1]];
//
// increment:
[[SensorsAnalyticsSDK sharedInstance] increment:@{@"UserPaid" : [NSNumber numberWithInt:1],
@"
PointEarned" : [NSNumber numberWithFloat:12.5]}];
8.4. 列表属性追加
对于列表类型用户属性，如用户喜爱的电影、用户点评过的餐厅等属性，可以调用 - append:by: 接口进行追加一些新值。
// "Movies" : ["Sicario", @"Love Letter"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Sicario", @"Love Letter"]]];
// "Movies" : ["Sicario", @"Love Letter", @"Dead Poets Society"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Love Letter", @"Dead Poets
Society"]]];
列表型属性中的元素必须为 NSString 类型，且元素的值会自动去重。关于列表型限制请见数据格式。
8.5. 属性取消
如果需要取消已设置的某个用户属性，可以调用 - unset: 进行取消
// gender
[[SensorsAnalyticsSDK sharedInstance] unset:@"Gender"];9. 打 通 App 与 H5
神策分析 SDK 提供打通 iOS App 与 H5 功能，详情介绍请参考打通 App 与 H5。
10. 可视化全埋点
版本要求
神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+
iOS SDK v2.0.0+
本功能使用前，请确保您 iOS 项目中已完成配置 Scheme
可视化全埋点在神策分析中的使用，请参考可视化全埋点
10.1. 开启可视化全埋点
SDK 初始化前将 SAConfigOptions 实例 - enableVisualizedAutoTrack 属性设置为 YES 即可开启可视化全埋点：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
//
options.enableVisualizedAutoTrack = YES;
10.2. 部分页面开启可视化全埋点
可视化全埋点开启后，默认对 App 内全部页面生效，如果只需要部分页面开启可视化全埋点，可以在 SDK 初始化后使用- addVisualizedAutoTrackViewC
ontrollers: 进行添加：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// MainController
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"
MainController"]];
11. 调试查看数据
SDK 初始化前将 SAConfigOptions 实例 enableLog 属性设置为 YES 即可打开 SDK 的日志输出功能，
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
#ifdef DEBUG
// SDK Log
options.enableLog = YES;
#endif
然后在 IDE (如 Xcode )日志控制台中筛选 SALog 关键词：
埋点事件触发成功时，SDK 会输出 【track event】 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 【valid message】字段开头的事件数据；
事件数据上报失败时，SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因。12. 所有事件公共预置属性
神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK
预置事件和预置属性 。.基本使用(iOS) v1.15
在使用前，请先阅读 数据模型 的介绍
SDK 的更新日志，可参阅 Release Notes
1. 集成神策分析 SDK
项目 Podfile 中添加以下配置：
pod ''SensorsAnalyticsSDK''
在 Podfile 目录下执行 pod install 安装 SDK。
注意：如果执行 pod update 无法检测到最新版本，可以先执行 pod cache clean SensorsAnalyticsSDK 清除本地缓存后重新 update。
集成 SDK 会使 App 安装包体积增加约 350KB。
2. 初始化 SDK 并开启全埋点
初始化 SDK 需要配置上报数据的目标地址，该地址可以使用管理员账户进行获取。需要在程序入口主线程同步初始化 SDK，否则可能会丢失部分事件数据。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<##> launchOptions:launchOptions];
//
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
SensorsAnalyticsEventTypeAppEnd |
SensorsAnalyticsEventTypeAppClick |
SensorsAnalyticsEventTypeAppViewScreen;
#ifdef DEBUG
// SDK Log
options.enableLog = YES;
#endif
// SDK
[SensorsAnalyticsSDK startWithConfigOptions:options];return YES;
}
3. 配置 Scheme
项目的 scheme 需要管理员账户进行获取
如果 App 在不同环境中使用到了多个数据接收地址，也应该配置多个与之对应的 scheme
3.1. 获取当前项目 scheme 值
3.2. App 中配置 schemeApp 工程选择 target -> Info -> Types，点击加号(+)，将上一步获取到的 scheme 配置到 URL Schemes 中。
3.3. 处理传入的 URL
AppDelegate 中的 - application:openURL:options: 方法中调用 - handleSchemeUrl: 对神策分析 scheme 进行处理。
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:
(NSDictionary *)options {
if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url])
{ return YES;
}
return NO;
}
如果 - application:openURL:options: 中还有其他逻辑处理，需要将 - handleSchemeUrl: 尽量前置，以保证 - handleSchemeUrl: 能被执行。
4. 代码埋点追踪事件
可以通过 - track: 和 - track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性：
UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;
[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
withProperties:@{@"ProductID" : [NSNumber
numberWithUnsignedLong:productId],
@"ProductCatalog" :
productCatalog,
@"IsAddedToFav" :
isAddedToFavorites ? @YES : @NO}];
事件名和属性名需要时合法变量名，且不能以 $ 开头；
属性名大小写敏感，并且不同事件会共用同名属性。即若 foo 事件含有 "aaa" 属性，则后续所有事件不能使用与 "aaa" 仅大小写不同的属性
(如 aAa、aaA)；
事件名和属性其他约束，具体请参考 数据格式。
5. 设置事件公共属性如果所有事件中都需要某些相同的属性，可使用 - registerSuperProperties: 把这些属性注册为公共属性：
// AppName
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];
// AppName
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{@"ProductID" : [NSNumber
numberWithUnsignedLong:123456]}];
在初始化 SDK 之后尽早设置公共属性
公共属性会保存在 App 本地缓存中。可以通过 -unregisterSuperProperty: 删除一个公共属性，或使用 -clearSuperProperties: 删除所有已
设置的事件公共属性
公共属性约束和事件属性相同，详情参考数据格式
5.1. 事件动态公共属性
动态公共属性和公共属性的区别是：前者适合标记年龄，后者适合标记性别。
对于一些值会变化的公共属性，如当前游戏等级、最新金币余额等，1.10.8+ 版本 SDK 提供了- registerDynamicSuperProperties: 接口来设置动态公共属性:
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary *
_Nonnull{ return @{@"level": <##>,
@"balance": <##>};
}];
事件属性的优先级为：track 事件时传入的属性 > 动态公共属性 > 公共属性> 预置属性；
动态公共属性的约束和事件属性相同，详情参考数据格式。
6. 记录激活事件
如果使用了神策渠道追踪功能，则需要在 App 启动时调用 - trackInstallation: 记录安装激活事件：
//
[[SensorsAnalyticsSDK sharedInstance] trackInstallation:@"AppInstall"
withProperties:@{@"DownloadChannel": @"AppStore"}];
第一次调用 - trackInstallation: 时， SDK 会在 KeyChain 中记录一个标志位。只有 App 在当前设备上的首次安装才会记录激活事件，卸载重
装不重复触发。
第一次调用 - trackInstallation: 时， SDK 会触发您命名的激活事件，并设置用户 $first_visit_time 属性。
更多关于渠道追踪功能介绍请参考渠道追踪。
7. 用户登录
当用户在客户端进行登录时，需要调用SDK 的 - login: 接口：
[[SensorsAnalyticsSDK sharedInstance] login:@"<#ID#>"];
为了准确记录登录用户的行为信息，建议在以下时机各调用一次 - login: 接口：·
·
· App
调用- login: 传入的值应当是可以唯一标识单个用户的 ID，通常是业务数据库里的主键或其它唯一标识。
8. 设置用户属性
除了给事件添加属性，SDK 也支持给用户设置属性，如年龄、性别、等级，神策事件分析、留存分析、分布分析等功能均支持使用用户属性作为过滤条件，
精确分析特定人群的指标。
关于事件属性和用户属性的区别，请参考数据模型
用户属性的命名约束，请参考参考数据格式
8.1. 属性更新
- set:、- set:to:，可以设定用户属性，同一个 key 多次设置时，value 值会进行覆盖替换。
// "Gender" "Male"
// set:WithValue
[[SensorsAnalyticsSDK sharedInstance] set:@"Gender" to:@"Male"];
// "Age" 18
// set:
[[SensorsAnalyticsSDK sharedInstance] set:@{@"Age" : [NSNumber numberWithInt:18]}];
8.2. 保留初次属性
对于需要保证只有首次设置时有效的属性，如用户首次充值金额、首次设置的昵称等，可以使用 - setOnce: 或 - setOnce:to: 接口进行记录。与 - set: 方
法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。
// AdSource "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"App Store"];
// AdSource AdSource "App Store"
[[SensorsAnalyticsSDK sharedInstance] setOnce:@"AdSource" to:@"Email"];
8.3. 数值属性累加
针对一些数值型属性，如消费总额、用户积分等属性，我们可以使用 - increment: 或 - increment:by: 对原值进行累加，神策会自动计算并保存累加之后的
值。
//
// increment:by:
[[SensorsAnalyticsSDK sharedInstance] increment:@"GamePlayed" by:[NSNumber numberWithInt:1]];
//
// increment:
[[SensorsAnalyticsSDK sharedInstance] increment:@{@"UserPaid" : [NSNumber numberWithInt:1],
@"
PointEarned" : [NSNumber numberWithFloat:12.5]}];
8.4. 列表属性追加对于列表类型用户属性，如用户喜爱的电影、用户点评过的餐厅等属性，可以调用 - append:by: 接口进行追加一些新值。
// "Movies" : ["Sicario", @"Love Letter"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Sicario", @"Love Letter"]]];
// "Movies" : ["Sicario", @"Love Letter", @"Dead Poets Society"]
[[SensorsAnalyticsSDK sharedInstance] append:@"Movies" by:[NSSet setWithArray:@[@"Love Letter", @"Dead Poets
Society"]]];
列表型属性中的元素必须为 NSString 类型，且元素的值会自动去重。关于列表型限制请见数据格式。
8.5. 属性取消
如果需要取消已设置的某个用户属性，可以调用 - unset: 进行取消
// gender
[[SensorsAnalyticsSDK sharedInstance] unset:@"Gender"];
9. 打 通 App 与 H5
神策分析 SDK 提供打通 iOS App 与 H5 功能，详情介绍请参考打通 App 与 H5。
10. 可视化全埋点
版本要求
神策分析 v1.15.2420+、v1.16.2386+、v1.17.2517+
iOS SDK v2.0.0+
本功能使用前，请确保您 iOS 项目中已完成配置 Scheme
可视化全埋点在神策分析中的使用，请参考可视化全埋点
10.1. 开启可视化全埋点
SDK 初始化前将 SAConfigOptions 实例 - enableVisualizedAutoTrack 属性设置为 YES 即可开启可视化全埋点：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
//
options.enableVisualizedAutoTrack = YES;
10.2. 部分页面开启可视化全埋点
可视化全埋点开启后，默认对 App 内全部页面生效，如果只需要部分页面开启可视化全埋点，可以在 SDK 初始化后使用- addVisualizedAutoTrackViewC
ontrollers: 进行添加：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// MainController
[[SensorsAnalyticsSDK sharedInstance] addVisualizedAutoTrackViewControllers:[NSArray arrayWithObject:@"
MainController"]];
11. 调试查看数据
SDK 初始化前将 SAConfigOptions 实例 enableLog 属性设置为 YES 即可打开 SDK 的日志输出功能，呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
#ifdef DEBUG
// SDK Log
options.enableLog = YES;
#endif
然后在 IDE (如 Xcode )日志控制台中筛选 SALog 关键词：
埋点事件触发成功时，SDK 会输出 【track event】 开头的事件数据；
埋点事件触发失败时，SDK 会输出相应的错误原因；
事件数据上报成功时，SDK 会输出 【valid message】字段开头的事件数据；
事件数据上报失败时，SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因。
12. 所有事件公共预置属性
神策分析 SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为所有事件都有的公共属性，详细的默认属性列表可以参考 App SDK
预置事件和预置属性 。iOS SDK 全埋点.全埋点(iOS) v1.13
1. 全埋点采集策略
神策 iOS SDK 全埋点包括四个自动采集的事件：
1.1. $AppStart(App 启动) 事件
App 启动或从后台恢复时，触发 $AppStart 事件，事件中包含以下属性:
$is_first_time - Bool 类型，标识本次启动是否为 App 安装后首次启动；
$is_first_day - Bool 类型，标识本次启动与 App 安装后的首次启动是否为同一天；
$resume_from_background - Bool 类型，Yes 为从后台恢复，No 为冷启动。
$AppStartPassively(App被动启动)事件是一种系统后台唤醒的启动事件，事件属性和 $AppStart 事件相同，更多信息可参考 App 被动启动
($AppStartPassively) 是什么事件？
1.2. $AppEnd(App 退出)
App 进入后台或被强制退出时，触发 $AppEnd 事件，事件中包含以下属性：
$event_duration - Number 类型，本次退出与最近一次 App 启动的事件间隔，单位为秒。
1.3. $AppViewScreen(App 浏览页面) 事件
App 浏览页面（UIViewController 的 - viewDidAppear: 被调用）时，会触发 $AppViewScreen 事件，事件中包含以下属性:
$title - String 类型，SDK 会尝试从navigationItem 的 titleView 或 title 属性中控制器的标题信息；
$screen_name - String 类型，默认值为当前 ViewController 类名。
1.4. $AppClick(App 元素点击) 事件
控件被点击时，触发 $AppClick 事件，并且包含该控件的基本信息：
$element_type - String 类型，表示控件的类型；
$element_content - String 类型，表示控件的内容；
$title - String 类型，表示控件所在页面的标题信息；
$screen_name - String 类型，表示控件所在页面的类名；
$element_position - String 类型，cell 点击时特有的属性，表示控件位置信息，格式为 section:row。
注意：$element_position 属性只有在列表点击的时候才会获取，例如 UITableVIew 和 UICollectionView
2. 事件的忽略与补充
对于全埋点中 App 页面浏览和 App 元素点击，开启全埋点后，SDK 也支持通过配置忽略部分页面或控件的采集。
2.1. 忽略页面的浏览事件
//
[[SensorsAnalyticsSDK sharedInstance] ignoreAutoTrackViewControllers:@[@"MyViewController",
@"BaseViewController"]];
2.2. 忽略某个控件的点击事件
button.sensorsAnalyticsIgnoreView = YES;2.3. 忽略某类控件的点击事件
//
[[SensorsAnalyticsSDK sharedInstance] ignoreViewType:[MyButton class]];
[[SensorsAnalyticsSDK sharedInstance] ignoreViewType:[MyView class]];
如果没有开启全埋点，但是想采集部分页面的浏览或部分控件的点击事件，SDK 也有相应的接口支持代码触发 App 页面浏览和 App 元素点击事件。
2.4. 手动触发页面的浏览事件
// viewDidAppear:
[[SensorsAnalyticsSDK sharedInstance] trackViewScreen:self.childViewControllers[0]];
2.5. 手动触发控件的点击事件
[[SensorsAnalyticsSDK sharedInstance] trackViewAppClick:button];
神策分析点击图、可视化全埋点功能，只支持全埋点方式触发的 App 点击事件。
3. 属性的补充与修改
如果在使用全埋点 App 页面浏览和 App 元素点击时遇到如下问题：
·
· $element_content $title
·
则需要您在代码中对全埋点采集的属性进行手动设置，SDK 会使用代码中设置值对全埋点属性进行补充或覆盖。
3.1. 页面设置自定义信息
通过实现 - getTrackProperties 协议方法给页面设置自定义属性：
// 1. UIViewController SAAutoTracker
// 2.- getTrackProperties
- (NSDictionary *)getTrackProperties
{ return @{@"$title": @"",
@"type": @"vendor"};
}
3.2. 页面设置来源($referrer)信息
如果需要在 App 浏览页面事件中添加当前页面的来源信息，可以通过实现 - getScreenUrl: 返回一个自定义的页面标识。
自定义的页面标识会设置到当前页面的 $url 属性中，同时该标识会设置到下一个页面的 $referrer 属性中。后续通过 $referrer 属性即可得知当前页面的上
一个页面信息。
// 1. UIViewController SAScreenAutoTracker
// 2.- getScreenUrl
- (NSString *)getScreenUrl {
return @"sa://page/product_detail";
}
3.3. 控件设置自定义属性继承自 UIView 的控件，可通过 sensorsAnalyticsViewProperties 设置自定义信息。
homeBtn.sensorsAnalyticsViewProperties = @{@"$element_content": @""};
3.4. cell 设置自定义属性
cell 存在重用机制，不能直接设置 sensorsAnalyticsViewProperties 属性，需要使用如下方法进行设置：
// 1. tableView collection sensorsAnalyticsDelegate
self.tableView.sensorsAnalyticsDelegate = self;
// 2. sensorsAnalyticsDelegate
-(NSDictionary *) sensorsAnalytics_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:
(NSIndexPath *)indexPath {
return @{@"customProperty":@"MyValue"};
}iOS SDK 高级功能.高级功能(iOS) v1.15
1. 开启 Crash 信息的自动采集
1.8.12+ 版本 SDK 支持自动采集 Crash 信息，可以在初始化 SDK 时通过配置 SAConfigOptions 进行开启。开启后的 Crash 堆栈信息会记录在 AppCrash
ed 事件的 app_crashed_reason 属性中。
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:
launchOptions];
options.enableTrackAppCrash = YES;
[SensorsAnalyticsSDK startWithConfigOptions:options];
2. 开启屏幕方向的自动采集
1.10.1+ 版本 SDK 支持自动采集屏幕方向，可以在初始化 SDK 后调用 - enableTrackScreenOrientation: 进行开启，开启后的屏幕方向信息记录在事件的
$screen_orientation 属性中。
[[SensorsAnalyticsSDK sharedInstance] enableTrackScreenOrientation:YES];
3. 开启位置信息自动采集
1.10.1+ 版本 SDK 支持自动采集 GPS 信息，可以在初始化 SDK 后调用 - enableTrackGPSLocation: 方法进行开启，开启后的经纬度信息会乘 10⁶ 后记
录在事件的 $longitude、$latitude 属性中。
// CoreLocation GPS
[[SensorsAnalyticsSDK sharedInstance] enableTrackGPSLocation:YES];
4. 统计事件时长
1.10.6+ 版本 SDK 支持代码埋点来统计事件的时长，只需要在行为开始时调用 - trackTimerStart:，在行为结束时调用 - trackTimerEnd:withProperties:
接口，SDK 会自动计算时长，并以秒(浮点数)为单位存在事件的 $event_duration 属性中。
此外，SDK 还支持暂停和恢复操作，可通过 - trackTimerPause:、- trackTimerResume: 接口进行统计。
以直播 App 中用户视频播放行为为例：
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"WatchVideo"];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:@"WatchVideo"];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:@"WatchVideo"];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:@"WatchVideo" withProperties:@{@"VideoType": @"film"}];
4.1. 同名事件交叉的时长统计
默认情况下，时长的统计以事件名作为标识，相同的事件名会自动匹配 start-end，如果两个同名事件在时间上有交叉部分，会造成错误匹配。为了解决此问
题，1.11.17+ 版本 SDK 支持同名事件交叉的时长统计，开发者需要保存 - trackTimerStart: 的返回值，以便后续针对性地进行暂停、恢复或停止。
//
NSString *timer1 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];
//
NSString *timer2 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];//
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:timer1];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:timer1];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer1];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer2];
只有调用 - trackTimerEnd: 时，SDK 才会真正记录事件
多次调用 - trackTimerStart:，以最后一次调用作为计时起点
默认情况下，统计的时长不包括用户 App 在后台的时长
5. 获取预置属性
前端 SDK 在记录事件时会添加设备相关的预置属性，为了保证前后端事件属性的一致性，某些情况下可能需要在前端获取 SDK 预置属性，1.8.19+ 版本
SDK 可以使用 - getPresetProperties 方法获取事件预置属性，然后通过业务接口传到服务端，由服务端添加到事件属性中。
//
[[SensorsAnalyticsSDK sharedInstance] getPresetProperties];
6. 获取用户 ID
神策中每个事件都会关联到一个 ID 上，用于标识该事件所对应的用户或设备信息，我们称之为 distinct_id，您也可以通过 - distinctId 接口获取该 ID：
// ID
[[SensorsAnalyticsSDK sharedInstance] distinctId];
默认情况下，用户登录前，distinct_id 是 SDK 根据设备生成的一个匿名 ID，一般为IDFA、IDFV 或 UUID，具体规则可以参考：SDK 匿名 ID 生成规则是怎
样的？
您也可以通过 - anonymousId 接口获取当前的匿名 ID：
// ID
[[SensorsAnalyticsSDK sharedInstance] anonymousId];
7. 开启点击分析功能
版本要求
神策分析 1.13+
此功能依赖于全埋点中点击事件采集的开启
使用此功能前，确保您的 App 中配置了当前项目的 Scheme，详细操作可参考配置 Scheme
1.9.3+ 版本 SDK 支持 App 点击分析功能，SDK 初始化前将 SAConfigOptions 实例 enableHeatMap 属性设置为 YES 即可开启 SDK 的点击分析功能：
//
options.enableHeatMap = YES;开启 App 点击分析后，该功能默认对所有页面上的点击生效， 如果您只是想部分页面进行热力图，可以通过 -addHeatMapViewControllers: 进行配置添加。
[[SensorsAnalyticsSDK sharedInstance] addHeatMapViewControllers:@"HomeViewController",
"DiscoverViewController"];
8. 实时查看当前设备事件数据
版本要求
神策分析版本 1.13+
使用此功能前，确保您的 App 中配置了当前项目的 Scheme，详细操作可参考配置 Scheme
调试模式只对本次启动有效，退出 App 自动失效
电脑端打开神策分析页面，埋点 -> 导入实时查看 -> Debug 数据 -> 设置设备调试模式，使用相机或其他二维码工具扫码屏幕二维码。
扫码打开 App 后，会弹出提示，选择想要切换的调试模式：
开启调试模式(导入数据)：打开调试模式，校验数据，并将数据导入到神策分析中。
开启调试模式(不导入数据)：打开调试模式，仅校验数据，但不进行数据导入，数据最终不会进入到数据库。
9. 自定义上报策略
为了减少性能和电量损耗，Android SDK 和 iOS SDK 中事件触发后不会立即上报，而是先将事件缓存在本地，然后定时、批量进行上报。
9.1. 上报条件
iOS SDK 每次触发事件时会检查如下条件，以判断是否向服务器上传数据:
1. 当前网络是否符合 flushNetworkPolicy (默认 3G、4G、5G、WiFi)
2. 与上次发送的时间间隔是否大于 flushInterval (默认 15 秒)
3. 本地缓存的事件条目数是否大于 flushBulkSize (默认 100 条)
只有1、2 或1、3 满足时，SDK 才会进行发送数据。以上参数支持自定义，可以通过修改相应参数值来达到控制事件上报的频率。
9.2. 强制上报
如果特定事件需要立即上报，可以在事件触发后调用 - flush 接口强制进行上报。
9.3. 退出上报为了确保数据的及时上报，SDK 会在应用进入后台或退出时强制触发一次事件上报，如不需要，可以将 flushBeforeEnterBackground 设置为 NO 进行关闭.
9.4. 缓存上限
如果事件触发后一直不满足上报条件，本地缓存的数据条数会越来越多，当缓存事件量达到 maxCacheSize 时，每次再触新的事件，SDK 会依次丢弃老数
据，保留最新的数据。maxCacheSize 默认为 10000 条，支持客户自定义。
10. 清空本地缓存事件
为了适应 GDPR 要求，1.10.8+ 版本 SDK 增加了 - deleteAll 方法用于清空本地缓存的所有事件。
[[SensorsAnalyticsSDK sharedInstance] deleteAll];
11. 本地证书校验
1.11.1+ 版本 SDK 发送数据时支持本地证书校验，可按照如下步骤进行配置：
服务器生成 SSL 证书，如果不是 .cer 格式，需要使用 OpenSSL 进行格式转换:
openssl x509 -in .crt -out .cer -outform der
将证书拖入项目中，选取相应 Target 并选择 Copy items if needed。
配置神策 SDK 证书校验方式：
SASecurityPolicy *securityPolicy = [SensorsAnalyticsSDK sharedInstance].securityPolicy;
/*
NO
YES
*/
securityPolicy.allowInvalidCertificates = YES;
/*
YES
NO
*/
securityPolicy.validatesDomainName = NO;
/*
*/
securityPolicy.pinnedCertificates = [SASecurityPolicy certificatesInBundle:[NSBundle mainBundle]];
/*
SASSLPinningModeNone
*/
securityPolicy.SSLPinningMode = SASSLPinningModePublicKey;
其中，SSLPinningMode 有以下三种模式：
SASSLPinningModeNone App
SASSLPinningModePublicKey
SASSLPinningModeCertificate
SASSLPinningModeCertificate 模式会校验证书有效期等信息，如果不能保证用户 App 证书始终处于未过期状态，建议使用
SASSLPinningModePublicKey 模式12. 追踪并进行渠道匹配和回传
1.10.15+ 版本 SDK 支持追踪自定义事件时进行渠道匹配，可以调用 - trackChannelEvent:properties:
比如用户首次下单时，将下单线索同渠道商进行匹配：
//
[[SensorsAnalyticsSDK sharedInstance] trackChannelEvent:@"PayOrder" properties:@{@"Amount": @(35.0)}];
当次安装、首次触发回传事件，记录事件并进行渠道匹配和回传。
当次安装、再次触发回传事件，记录事件，但不进行渠道匹配和回传。
卸载重装、首次触发回传事件，记录事件并进行渠道匹配和回传。
p.s. 上述规则适用于同名事件，不同事件之间不相互影响。
13. 入库前修改事件信息
1.11.16+ 版本 SDK 支持在事件入库前进行修改属性、删除事件，可以使用 - trackEventCallback: 中 block 参数进行设置：
1. block 中 eventName 参数为当前事件名。
2. block 中 properties 参数为当前事件属性，该参数为 NSMutableDictionary 类型，可直接修改此参数达到修改事件属性的目的。
3. block 返回值标志事件是否需要继续入库和上报： YES 事件会继续入库，NO 将删除此条事件。
警告
严禁在 block 中调用 - track: 、- trackInstallation:、 - login: 等触发事件的接口，会因循环调用而导致应用崩溃
block 返回 NO 时 SDK 将删除此条事件，所以请确保判断逻辑，以免造成误删除事件
[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
NSMutableDictionary *properties) {
// BuyProduct
if ([eventName isEqualToString:@"BuyProduct"])
{ return NO;
}
// ViewProduct category
if ([eventName isEqualToString:@"ViewProduct"])
{ [properties
removeObjectForKey:@"category"];
}
return YES;
}];
14. 自定义匿名 ID
默认情况下，SDK 会生成匿名 ID 并可以保证该 ID 的唯一性，如果需要替换神策默认分配的匿名 ID ，可以在初始化 SDK 之后立即调用 - identify: 方法进
行替换。
代码示例：
[[SensorsAnalyticsSDK sharedInstance] identify:<# ID#>];
15. 预编译宏配置 SDK 特性为了满足客户特殊场景下的需求，SDK 支持通过预编译宏来选择性编译某些功能。通过 CocoaPods 集成时，可以通过添加 subspecs 进行配置；其他集成
方式，可以在项目中配置 Preprocessor Macros。
功能 subspec (CocoaPods 方式) Preprocessor Macros (其他集成方式) 备
注
禁用 UIWebView DISABLE_UIWEBVIEW SENSORS_ANALYTICS_DISABLE_UIWEBVIEW=1
卸载重装重新触发激活事件 DISABLE_INSTALLATION_MARK_IN_KEYCHAIN SENSORS_ANALYTICS_DISABLE_INSTALLATION_MARK_IN_KEYCHAIN=1
屏蔽 GPS 相关代码 DISABLE_TRACK_GPS SENSORS_ANALYTICS_DISABLE_TRACK_GPS=1
不采集 UITableView 点击事 DISABLE_AUTOTRACK_UITABLEVIEW SENSORS_ANALYTICS_DISABLE_AUTOTRACK_UITABLEVIEW=1
件
15.1. CocoaPods 集成方式配置
# subspec
pod ''SensorsAnalyticsSDK'', :subspecs => [''DISABLE_UIWEBVIEW'']
# subspec
pod ''SensorsAnalyticsSDK'', :subspecs => [''DISABLE_UIWEBVIEW'', ''DISABLE_TRACK_GPS'']
15.2. 其他集成方式配置.高级功能(iOS ) v1.13
1. 开启 Crash 信息的自动采集
1.8.12+ 版本 SDK 支持自动采集 Crash 信息，可以在初始化 SDK 时通过配置 SAConfigOptions 进行开启。开启后的 Crash 堆栈信息会记录在 AppCrash
ed 事件的 app_crashed_reason 属性中。
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:
launchOptions];
options.enableTrackAppCrash = YES;
[SensorsAnalyticsSDK startWithConfigOptions:options];
2. 开启屏幕方向的自动采集
1.10.1+ 版本 SDK 支持自动采集屏幕方向，可以在初始化 SDK 后调用 - enableTrackScreenOrientation: 进行开启，开启后的屏幕方向信息记录在事件的
$screen_orientation 属性中。
[[SensorsAnalyticsSDK sharedInstance] enableTrackScreenOrientation:YES];
3. 开启位置信息自动采集
1.10.1+ 版本 SDK 支持自动采集 GPS 信息，可以在初始化 SDK 后调用 - enableTrackGPSLocation: 方法进行开启，开启后的经纬度信息会乘 10⁶ 后记
录在事件的 $longitude、$latitude 属性中。
// CoreLocation GPS
[[SensorsAnalyticsSDK sharedInstance] enableTrackGPSLocation:YES];
4. 统计事件时长
1.10.6+ 版本 SDK 支持代码埋点来统计事件的时长，只需要在行为开始时调用 - trackTimerStart:，在行为结束时调用 - trackTimerEnd:withProperties:
接口，SDK 会自动计算时长，并以秒(浮点数)为单位存在事件的 $event_duration 属性中。
此外，SDK 还支持暂停和恢复操作，可通过 - trackTimerPause:、- trackTimerResume: 接口进行统计。
以直播 App 中用户视频播放行为为例：
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"WatchVideo"];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:@"WatchVideo"];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:@"WatchVideo"];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:@"WatchVideo" withProperties:@{@"VideoType": @"film"}];
4.1. 同名事件交叉的时长统计
默认情况下，时长的统计以事件名作为标识，相同的事件名会自动匹配 start-end，如果两个同名事件在时间上有交叉部分，会造成错误匹配。为了解决此问
题，1.11.17+ 版本 SDK 支持同名事件交叉的时长统计，开发者需要保存 - trackTimerStart: 的返回值，以便后续针对性地进行暂停、恢复或停止。
//
NSString *timer1 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];
//
NSString *timer2 = [[SensorsAnalyticsSDK sharedInstance] trackTimerStart:@"testTimer"];//
[[SensorsAnalyticsSDK sharedInstance] trackTimerPause:timer1];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerResume:timer1];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer1];
//
[[SensorsAnalyticsSDK sharedInstance] trackTimerEnd:timer2];
只有调用 - trackTimerEnd: 时，SDK 才会真正记录事件
多次调用 - trackTimerStart:，以最后一次调用作为计时起点
默认情况下，统计的时长不包括用户 App 在后台的时长
5. 获取预置属性
前端 SDK 在记录事件时会添加设备相关的预置属性，为了保证前后端事件属性的一致性，某些情况下可能需要在前端获取 SDK 预置属性，1.8.19+ 版本
SDK 可以使用 - getPresetProperties 方法获取事件预置属性，然后通过业务接口传到服务端，由服务端添加到事件属性中。
//
[[SensorsAnalyticsSDK sharedInstance] getPresetProperties];
6. 获取用户 ID
神策中每个事件都会关联到一个 ID 上，用于标识该事件所对应的用户或设备信息，我们称之为 distinct_id，您也可以通过 - distinctId 接口获取该 ID：
// ID
[[SensorsAnalyticsSDK sharedInstance] distinctId];
默认情况下，用户登录前，distinct_id 是 SDK 根据设备生成的一个匿名 ID，一般为IDFA、IDFV 或 UUID，具体规则可以参考：SDK 匿名 ID 生成规则是怎
样的？
您也可以通过 - anonymousId 接口获取当前的匿名 ID：
// ID
[[SensorsAnalyticsSDK sharedInstance] anonymousId];
7. 开启点击分析功能
版本要求
神策分析 1.13+
此功能依赖于全埋点中点击事件采集的开启
使用此功能前，确保您的 App 中配置了当前项目的 Scheme，详细操作可参考配置 Scheme
1.9.3+ 版本 SDK 支持 App 点击分析功能，SDK 初始化前将 SAConfigOptions 实例 enableHeatMap 属性设置为 YES 即可开启 SDK 的点击分析功能：
//
options.enableHeatMap = YES;开启 App 点击分析后，该功能默认对所有页面上的点击生效， 如果您只是想部分页面进行热力图，可以通过 -addHeatMapViewControllers: 进行配置添加。
[[SensorsAnalyticsSDK sharedInstance] addHeatMapViewControllers:@"HomeViewController",
"DiscoverViewController"];
8. 实时查看当前设备事件数据
版本要求
神策分析版本 1.13+
使用此功能前，确保您的 App 中配置了当前项目的 Scheme，详细操作可参考配置 Scheme
调试模式只对本次启动有效，退出 App 自动失效
电脑端打开神策分析页面，埋点 -> 导入实时查看 -> Debug 数据 -> 设置设备调试模式，使用相机或其他二维码工具扫码屏幕二维码。
扫码打开 App 后，会弹出提示，选择想要切换的调试模式：
开启调试模式(导入数据)：打开调试模式，校验数据，并将数据导入到神策分析中。
开启调试模式(不导入数据)：打开调试模式，仅校验数据，但不进行数据导入，数据最终不会进入到数据库。
9. 自定义上报策略
为了减少性能和电量损耗，Android SDK 和 iOS SDK 中事件触发后不会立即上报，而是先将事件缓存在本地，然后定时、批量进行上报。
9.1. 上报条件
iOS SDK 每次触发事件时会检查如下条件，以判断是否向服务器上传数据:
1. 当前网络是否符合 flushNetworkPolicy (默认 3G、4G、5G、WiFi)
2. 与上次发送的时间间隔是否大于 flushInterval (默认 15 秒)
3. 本地缓存的事件条目数是否大于 flushBulkSize (默认 100 条)
只有1、2 或1、3 满足时，SDK 才会进行发送数据。以上参数支持自定义，可以通过修改相应参数值来达到控制事件上报的频率。
9.2. 强制上报
如果特定事件需要立即上报，可以在事件触发后调用 - flush 接口强制进行上报。
9.3. 退出上报为了确保数据的及时上报，SDK 会在应用进入后台或退出时强制触发一次事件上报，如不需要，可以将 flushBeforeEnterBackground 设置为 NO 进行关闭.
9.4. 缓存上限
如果事件触发后一直不满足上报条件，本地缓存的数据条数会越来越多，当缓存事件量达到 maxCacheSize 时，每次再触新的事件，SDK 会依次丢弃老数
据，保留最新的数据。maxCacheSize 默认为 10000 条，支持客户自定义。
10. 清空本地缓存事件
为了适应 GDPR 要求，1.10.8+ 版本 SDK 增加了 - deleteAll 方法用于清空本地缓存的所有事件。
[[SensorsAnalyticsSDK sharedInstance] deleteAll];
11. 本地证书校验
1.11.1+ 版本 SDK 发送数据时支持本地证书校验，可按照如下步骤进行配置：
服务器生成 SSL 证书，如果不是 .cer 格式，需要使用 OpenSSL 进行格式转换:
openssl x509 -in .crt -out .cer -outform der
将证书拖入项目中，选取相应 Target 并选择 Copy items if needed。
配置神策 SDK 证书校验方式：
SASecurityPolicy *securityPolicy = [SensorsAnalyticsSDK sharedInstance].securityPolicy;
/*
NO
YES
*/
securityPolicy.allowInvalidCertificates = YES;
/*
YES
NO
*/
securityPolicy.validatesDomainName = NO;
/*
*/
securityPolicy.pinnedCertificates = [SASecurityPolicy certificatesInBundle:[NSBundle mainBundle]];
/*
SASSLPinningModeNone
*/
securityPolicy.SSLPinningMode = SASSLPinningModePublicKey;
其中，SSLPinningMode 有以下三种模式：
SASSLPinningModeNone App
SASSLPinningModePublicKey
SASSLPinningModeCertificate
SASSLPinningModeCertificate 模式会校验证书有效期等信息，如果不能保证用户 App 证书始终处于未过期状态，建议使用
SASSLPinningModePublicKey 模式12. 追踪并进行渠道匹配和回传
1.10.15+ 版本 SDK 支持追踪自定义事件时进行渠道匹配，可以调用 - trackChannelEvent:properties:
比如用户首次下单时，将下单线索同渠道商进行匹配：
//
[[SensorsAnalyticsSDK sharedInstance] trackChannelEvent:@"PayOrder" properties:@{@"Amount": @(35.0)}];
当次安装、首次触发回传事件，记录事件并进行渠道匹配和回传。
当次安装、再次触发回传事件，记录事件，但不进行渠道匹配和回传。
卸载重装、首次触发回传事件，记录事件并进行渠道匹配和回传。
p.s. 上述规则适用于同名事件，不同事件之间不相互影响。
13. 入库前修改事件信息
1.11.16 + 版本 SDK 支持在事件入库前进行修改属性、删除事件，可以使用 - trackEventCallback: 中 block 参数进行设置：
1. block 中 eventName 参数为当前事件名。
2. block 中 properties 参数为当前事件属性，该参数为 NSMutableDictionary 类型，可直接修改此参数达到修改事件属性的目的。
3. block 返回值标志事件是否需要继续入库和上报： YES 事件会继续入库，NO 将删除此条事件。
警告
严禁在 block 中调用 - track: 、- trackInstallation:、 - login: 等触发事件的接口，会因循环调用而导致应用崩溃
block 返回 NO 时 SDK 将删除此条事件，所以请确保判断逻辑，以免造成误删除事件
[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
NSMutableDictionary *properties) {
// BuyProduct
if ([eventName isEqualToString:@"BuyProduct"])
{ return NO;
}
// ViewProduct category
if ([eventName isEqualToString:@"ViewProduct"])
{ [properties
removeObjectForKey:@"category"];
}
return YES;
}];
14. 自定义匿名 ID
默认情况下，SDK 会生成匿名 ID 并可以保证该 ID 的唯一性，如果需要替换神策默认分配的匿名 ID ，可以在初始化 SDK 之后立即调用 - identify: 方法进
行替换。
代码示例：
[[SensorsAnalyticsSDK sharedInstance] identify:<# ID#>];
15. 预编译宏配置 SDK 特性为了满足客户特殊场景下的需求，SDK 支持通过预编译宏来选择性编译某些功能。通过 CocoaPods 集成时，可以通过添加 subspecs 进行配置；其他集成
方式，可以在项目中配置 Preprocessor Macros。
功能 subspec (CocoaPods 方式) Preprocessor Macros (其他集成方式) 备
注
禁用 UIWebView DISABLE_UIWEBVIEW SENSORS_ANALYTICS_DISABLE_UIWEBVIEW=1
卸载重装重新触发激活事件 DISABLE_INSTALLATION_MARK_IN_KEYCHAIN SENSORS_ANALYTICS_DISABLE_INSTALLATION_MARK_IN_KEYCHAIN=1
屏蔽 GPS 相关代码 DISABLE_TRACK_GPS SENSORS_ANALYTICS_DISABLE_TRACK_GPS=1
不采集 UITableView 点击事 DISABLE_AUTOTRACK_UITABLEVIEW SENSORS_ANALYTICS_DISABLE_AUTOTRACK_UITABLEVIEW=1
件
15.1. CocoaPods 集成方式配置
# subspec
pod ''SensorsAnalyticsSDK'', :subspecs => [''DISABLE_UIWEBVIEW'']
# subspec
pod ''SensorsAnalyticsSDK'', :subspecs => [''DISABLE_UIWEBVIEW'', ''DISABLE_TRACK_GPS'']
15.2. 其他集成方式配置iOS SDK 常见问题.常见问题(iOS) v1.13
1. 事件触发后会立即上报吗？
为了减少性能和电量损耗，Android SDK 和 iOS SDK 中事件触发后不会立即上报，而是先将事件缓存在本地，然后定时、批量进行上报。iOS SDK 每次触
发事件时会检查如下条件，以判断是否向服务器上传数据:
1. 当前网络是否符合 flushNetworkPolicy (默认 3G、4G、5G、WiFi)；
2. 与上次发送的时间间隔是否大于 flushInterval (默认 15 秒)；
3. 本地缓存的事件条目数是否大于 flushBulkSize (默认 100 条)。
只有 1、2 或 1、3 满足时，SDK 才会进行发送数据。以上参数支持自定义，可以通过修改相应参数值来达到控制事件上报的频率。
2. SDK 是否使用了 IDFA？
神策 SDK 不会主动开启 IDFA，只有您 App 中主动开启了 IDFA(引入 AdSupport 库或显式调用 - advertisingIdentifier)， SDK 才会尝试获取
IDFA 作为匿名 ID 和用于渠道追踪。
如果需要使用神策分析中精准渠道匹配功能，则需要您 App 主动开启 IDFA 功能，否则不能成功匹配。
App 如果主动开启了 IDFA，Apple 审核时可以参考如下策略：
您应用中集成了广告，可选择1、2、3、4选项；
您应用中没有集成广告，为渠道追踪功能开启的 IDFA，可选择2、3、4选项。
)
3. SDK 匿名 ID 生成规则是怎样的？
SDK 生成匿名 ID 的优先顺序为：IDFA > IDFV > UUID，不过 1.10.18 之前 SDK，只有配置了IDFA subspec，SDK 才会尝试去获取 IDFA。
另外，为了解决 App 卸载重装后匿名 ID 变化问题，1.9.10 之后的 SDK，默认将匿名 ID 保存在 Keychain 中，卸载重装后，匿名 ID 不会变化。
通过 - anonymousId 方法可获取 SDK 当前的匿名 ID：
NSString *anonymousId = [[SensorsAnalyticsSDK sharedInstance] anonymousId];
4. 应用版本属性为什么没包含 build 信息？
由于各个公司对 build 定义的不同，SDK 中只获取 CFBundleShortVersionString 作为 $app_version (应用版本)属性。如果您这边有特殊要求，可以通过注册
公共属性方式覆盖 SDK 采集的 $app_version 属性。
5. 属性中 YES/NO 和 true/false 有什么区别？
在 iOS SDK 中 ：
YES/NO 对应的数据类型为BOOL；
true/false 对应的数据类型为NUMBER。
NSMutableDictionary *dict = [[NSMutableDictionary alloc]init];
[dict setObject:@YES forKey:@"isFirst"];
[dict setObject:@true forKey:@"isStart"];其中：
isFirst 对应的数据类型为 BOOL 类型
isStart 对应的数据类型为 NUMBER 类型
6. 如何使用 .a 静态库的方式集成 SDK ？
选中对应的 target ，build settings -> other linker flag 设置为 -ObjC.
7. App 被动启动($AppStartPassively) 是什么事件？
对于 iOS 设备，除了用户主动启动 App。设备中某些条件触发时(如收到通知、用户位置信息变化等)，系统可能会唤醒 App，使程序在后台运行，当程序在
后台启动并运行时，SDK 触发 $AppStartPassively(App 被动启动) 事件。
关于 iOS 设备后台启动和运行的更多信息，可参考 Apple 文档 About the Background Execution Sequence。iOS SDK 在 App Extension 中的使用.App Extension 中的使用 v1.13
1. App Extension 中集成的 SDK 仅支持代码埋点，不支持全埋点。
2. App Extension 中触发的事件信息，需要经过 Containing App 上报，使用前请确保 App Extension 和 Containing App 可以通过 App
Groups 共享数据。详情可参考 App Groups Entitlement。
1. App Extension 集 成 SDK
App Extension 中目前支持通过源码方式集成神策分析 SDK，可通过下面步骤进行集成：
1. 从 GitHub 上下载神策分析 iOS SDK。
2. 将图中四个文件拖入 App Extension target 并选择 Copy items if needed。
2. App Extension 中记录事件
App Extension 中导入 SAAppExtensionDataManager 后，可通过 - writeEvent:properties:groupIdentifier: 记录事件，SDK 会将事件信息缓存到 groupId
entifier 对应的共享内存中。
[[SAAppExtensionDataManager sharedInstance] writeEvent:@"ButtonClick"
properties:@{@"
ButtonType": @"OpenApp"}
groupIdentifier:@"group.cn.
sensorsAnalytics.share"];
3. Containing App 取出并处理事件信息
每次 Containing App 启动时，需要使用相同 groupIdentifier 从共享内存中取出事件信息并进行上报。
- (void)applicationDidBecomeActive:(UIApplication *)application {
[[SensorsAnalyticsSDK sharedInstance] trackEventFromExtensionWithGroupIdentifier:@"group.cn.
sensorsAnalytics.share"
completion:nil];
}
4. 其他注意事项1.11.17 + 版本 SDK，App Extension 中事件 time 为事件触发时间，旧版本 SDK 为Containing App 读取数据时间。如果您使用的是旧版本
SDK，并且需要将 time 设置为事件触发时间，可以使用如下方案：
[[SAAppExtensionDataManager sharedInstance] writeEvent:@"ButtonClick"
properties:@{@"ButtonType": @"OpenApp",
@"$time": [NSDate date]}
groupIdentifier:@"group.cn.com.sensorsAnalytics.share"];Web JSSDK
欢迎使用神策分析 Web JS SDK
Web 快速接入 快速接入 SDK
Web 基本使用 常见功能详解
Web 全埋点 全埋点和网页热力图功能详解
Web 预置属性 预置属性详解
Web 渠道参数 渠道来源相关参数详解
Web 常见问题 使用过程中的常见问题及方案
Web 单页面 单页面使用过程中的常见问题及方案
Web 关页面发数据 关闭页面发数据问题及方案JavaScript SDK 快速使用.Web 快速接入 v1.13
在使用前，请先阅读 数据模型 的介绍。
更多参数接口信息介绍可前往 Web 基本使用。
如果是 vue，react 等单页面应用，必须要用 is_track_single_page 参数，参考文档：Web 单页面。
关闭页面会丢失数据，参考文档：Web 关页面发数据。
1. 集成 SDK
1.1. 获取引入代码
如果您当前的版本没有生成导入代码的功能，请联系神策技术支持进行升级
首先从神策分析的主页中，进入数据导入向导页面：
然后在右上角点击 数据接入 显示如下界面，然后点击 生成导入代码，进入代码生成页面，按需选择合适的选项，然后点击生成代码，如下图：
将以下上生成的代码放入 html 的 head 里面,一般最好放在稍微靠前点的位置。
1.2. 多种集成方式
将以下代码放入 html 的 head 里面,一般最好放在稍微靠前点的位置。 您在使用 sensors.track() 时，只要保证写在上面引用的代码的下面就可以，不需
要等 window.onload 后再执行。
1.3. 数据接收地址 server_url 获取方式
2. 验证接入成功2.1. 前端日志验证
客户有测试项目（project=default）的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
页面集成 SDK 初始化代码且开启全埋点，验证数据接收地址；
浏览器开发者工具 console 会打印采集的是数据，json 格式。
浏览器开发者工具 network 中有 sa.gif 的图片请求，且状态码为 200，
2.2. 验证数据入库
神策分析界面中，打开导入中的数据，点击开始刷新，然后在浏览器刷新页面，查看有无数据进入。如下图，则证明数据已正常入库。.Web 快速接入 v1.15
在使用前，请先阅读 数据模型 的介绍。
更多参数接口信息介绍可前往 Web 基本使用。
如果是 vue，react 等单页面应用，必须要用 is_track_single_page 参数，参考文档：Web 单页面。
关闭页面会丢失数据，参考文档：Web 关页面发数据。
1. 集成 SDK
1.1. 获取引入代码
如果您当前的版本没有生成导入代码的功能，请联系神策技术支持进行升级
首先从神策分析的主页中，进入数据导入向导页面：
然后在右上角点击 数据接入 显示如下界面，然后点击 生成导入代码，进入代码生成页面，按需选择合适的选项，然后点击生成代码，如下图：
将以下上生成的代码放入 html 的 head 里面,一般最好放在稍微靠前点的位置。
1.2. 多种集成方式
将以下代码放入 html 的 head 里面,一般最好放在稍微靠前点的位置。 您在使用 sensors.track() 时，只要保证写在上面引用的代码的下面就可以，不需
要等 window.onload 后再执行。
1.3. 数据接收地址 server_url 获取方式
2. 验证接入成功2.1. 前端日志验证
客户有测试项目（project=default）的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
页面集成 SDK 初始化代码且开启全埋点，验证数据接收地址；
浏览器开发者工具 console 会打印采集的是数据，json 格式。
浏览器开发者工具 network 中有 sa.gif 的图片请求，且状态码为 200，
2.2. 验证数据入库
神策分析界面中，打开导入中的数据，点击开始刷新，然后在浏览器刷新页面，查看有无数据进入。如下图，则证明数据已正常入库。基本使用.Web 基本使用 v1.13
在使用前，请先阅读 数据格式 的介绍。
如想查看 SDK 历史版本，请参考 SDK 更新日志 。
1. 获取和引入神策分析 SDK
详细参考：Web 快速使用
目前 Web JS SDK 压缩文件 sensorsdata.min.js 大小约为 20kb。
当神策服务器异常时，Web JS SDK 发送的图片数据请求无法及时响应，会导致 window.onload 无法生效，所以建议不要将页面渲染的代码放在 window.
onload 中。如果一定要使用 window.onload 的话，建议将 send_type 参数设置为 ''ajax''，使用 ajax 发送数据。
2. 参数配置
如果使用自动代码生成，一般情况下无需手工修改参数
2.1. 普通参数
普通参数对代码埋点有效，下面是必填参数：
sdk_url: sensorsdata.min.js 文件的地址，请从 GitHub 获取并且放在你们自己网站目录下。
name: SDK 使用的一个默认的全局变量，如定义成 sensors 的话，后面可以使用 sensors.track() 用来跟踪信息。为了防止变量名重复，你可以修
改成其他名称比如 sensorsdata 等 。
server_url: 数据接收地址。
heatmap_url: heatmap.min.js 文件的地址，请从 GitHub 获取并且放在你们自己网站目录下。神策分析中点击分析及触达分析功能代码，代码生成工
具会自动生成。如果神策代码中 sensorsdata.min.js 版本是 1.13.1 及以前版本，这个参数须配置，高于此版本不需要配置。
web_url: 神策分析后台地址，神策分析中点击分析及触达分析功能会用到此地址，代码生成工具会自动生成。如果神策后台版本及 sensorsdata.
min.js 均是 1.10 及以上版本，这个参数不需要配置。如果有需要，也可以修改可选参数。
heatmap:点击图配置。配置成 {} 表示开启 $WebClick 和 $WebStay 的自动采集，默认 $WebClick 只采集 a，button，input 三个 dom 元素的点
击事件。 详细配置参考：Web 全埋点
cross_subdomain: 设置成 true 后，表示在根域下设置 cookie 。也就是如果你有 zhidao.baidu.com 和 tieba.baidu.com 两个域，且有一个用户在
同一个浏览器都登录过这两个域的话，我们会认为这个用户是一个用户。如果设置成 false 的话，会认为是两个用户。默认 true。
show_log: 设置 true 后会在网页控制台打 logger，会显示发送的数据,设置 false 表示不显示。默认 true。
use_client_time: 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端时间，使用服务端时间，
如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date 类型，那么这条数据就会使用你在属
性中传入的这个时间。
source_channel: 默认获取的来源是根据 utm_source 等 ga 标准来的，如果使用百度统计的 hmsr 等参数，需在此字段中加入对应参数，参数必须是
数组，例如：[''hmsr'']。使用网页通用渠道添加自定义属性时，需将对应的自定义属性名添加到此字段。
source_type: 自定义搜索引擎流量，社交流量，搜索关键词。[详细配置参考] Web 渠道参数
max_string_length: 通用字符串最大长度，超过部分会被截取丢弃（由于超过 7000 的字符串会导致 url 超长发不出去，所以限制长度），默认值：
500。
send_type: 默认值 ''image'' 表示使用图片 get 请求方式发数据，( 神策系统 1.10 版本以后 ) 可选使用 ''ajax'' 和 ''beacon'' 方式发送数据，这两种默
认都是 post 方式， beacon 方式兼容性较差。
callback_timeout: 默认值 200 ，单位毫秒，表示回调函数超时时间，如果数据发送超过 callback_timeout 还未返回结果，会强制执行回调函数。
（SDK 版本 1.11.6 以后支持）
queue_timeout: 默认值 300 ，单位毫秒，表示队列发送超时时间，如果数据发送时间超过 queue_timeout 还未返回结果，会强制发送下一条数据。
（SDK 版本 1.11.6 以后支持）
datasend_timeout: 默认值 3000 ，单位毫秒，表示数据发送超时时间，如果数据发送超过 datasend_timeout 还未返回结果，会强制取消该请求。
（SDK 版本 1.11.6 以后支持）
preset_properties: 是否开启 $latest 最近一次相关事件属性采集以及配置 $url 作为公共属性，默认值为一个对象。（SDK 版本 1.14.10 及以后支
持） 详细配置参考：Web 渠道参数
is_track_single_page: 默认值 false，表示是否开启单页面自动采集 $pageview 功能，SDK 会在 url 改变之后自动采集web页面浏览事件
$pageview。（SDK 版本 1.12.18 以后支持）
batch_send: 默认值 false，表示不开启批量发送，设置为 true 表示开启批量采集，并且使用以下默认值 { datasend_timeout: 6000, 一次请求超过
多少秒的话自动取消，防止请求无响应。send_interval: 6000, 间隔几秒发一次数据。one_send_max_length: 6 一次请求最大发送几条数据，防止
数据太大 }，也可以直接以 {} 的方式自定义这几个参数的值，详细参考：.Web 基本使用 v1.13#批量发送
3. 如何标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是用来标识用户的，是一段唯一的字符串，默认情况下 Web JS SDK 会自动生成一个 Distin
ct ID 并永久保存在浏览器中的 Cookie 中（我们暂时称这个为 cookie_id），如果你已知了真实的用户 id ，你可以通过 sensors.login("你们服务端分配给
用户具体的登录 ID",function(){//回调函数}) 来发送关联 cookie_id 的事件，同时这个方法还会用"你们服务端分配给用户具体的登录 ID"替换浏览器缓存中
的 cookie_id。
获取 Cookie 中的 Distinct ID ：sensors.store.getDistinctId();由于调用 login 接口之后，Distinct ID 会由匿名 id 变成真实 id，所以我们提供了获取 Cookie 中的 匿名 id 方法
3.1. 获取匿名 ID
前端方式获取匿名 ID：
增加了获取匿名ID的方法 sensors.quick(''getAnonymousID''); 返回匿名 id （SDK 版本 1.13.4 及以上支持），调用这个方法时，可能 Web JS SDK 还未初
始化成功，建议将此方法放在下面代码中。
sensors.quick(''isReady'',function(){ sens
ors.quick(''getAnonymousID'');
});
后端方式获取匿名 ID：
可以在 Cookie 里面找到 key 为sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解码，最后通过 JSON.parse 方法得到一个对
象，对象里面的 Distinct ID 即为用户所需要的 (注意，如果前端已经调用过 login 方法，那么此时 Distinct ID 为真实 id，所以需要获取 first_id 字段)。
3.2. 使用 sensors.login 完成用户标识的注册
在登录和注册成功后，调用 sensors.login("你们服务端分配给用户具体的登录 ID",function(){//回调函数}) 来把 SDK 自动生成的 cookie_id 关联成现在传入
的 "你们服务端分配给用户具体的登录 ID"。且以后会一直使用这个 "你们服务端分配给用户具体的登录 ID"。
login SDK 1.14.8
我们的 Web JS SDK 从 1.6.9 版本开始支持 sensors.login() 方法。
sensors.login(''user1312312123'',function(){
// SDK 1.14.8
});
问题1：这行代码放在哪里？
建议放在所有事件前面。也就是在 sdk 载入代码后面，先使用 sensors.login （"如果此时有这个你们服务端分配给用户具体的登录 ID 的话",function(){//回
调函数}），然后再用 sensors.quick(''autoTrack'') 等，这样后续的事件才会使用这个更改后的 真实 id。
问题2：在什么时候调用？
页面登录的时候，只要获取到用户是登录状态，就需要调用。或者 注册流程成功的时候。
问题3：sensors.login 和 sensors.identify 有什么区别？
login 用来关联数据库的 id，identify 用来改变匿名 id，可以认为匿名 id 是跟浏览器绑定的。
3.3. 使用 sensors.identify 来修改匿名 id
默认情况下，是把 cookie_id 作为 Distinct ID 的。如果你能取到其他匿名 id（比如设备 id，或者你们自己生成的 cookie_id），可以用 sensors.identify(id)
来改变当前的 Distinct ID。
这个方法有三种使用方式:
sensors.identify(id): id
sensors.identify(id, true): id cookie id
sensors.identify(): cookie_id
3.4. 使用 sensors.logout 切换到之前的匿名 id
通过 sensors.logout() 来永久改变当前的 Distinct ID 为 cookie_id 。
sensors.logout(); // login id cookie_id
sensors.logout(true); // login id cookie_id问题1，这个在什么时候使用？
在你用过 sensors.login 后，在一个浏览器有多个用户登录的时候，你想在用户退出后改变当前的 Distinct ID。
4. 公共属性
4.1. 静态公共属性
sensors.registerPage(object)
如果某个事件的属性，在所有事件中都会出现，可以通过 registerPage 方法将该属性设置为事件公共属性。例如电商产品中的用户等级，常作为事件的公共
属性。sensors.registerPage({gender:"male"}) 。这样的话，下次你在使用 sensors.track("index_visit") 时等同于 sensors.track("index_visit", {gender:"
male"})。
再比如想在当前页面的后续事件中都注入当前页面地址及前向地址属性，只针对当前页面有效的方法如下：
4.2. 动态公共属性（SDK 版本 1.14.15 及以后支持）
当设置动态公共属性的时候，注意使用函数类型作为属性值，函数的返回值应当是神策支持的类型，请参考数据格式，否则会被过滤掉。
另外您如果使用了 ES6 语法如箭头函数等，则需要使用编译工具编译后运行。
var i=0
sensors.registerPage({
index: function()
{ return ++i; //
},istrue: function() {
return i<10 ? true : false; // bool
},
isEmptyString: function()
{ return ""; //
},
isDate: function() {
return new Date(''December 17, 1995 03:24:00''); //
},
isArrayOfStr: function()
{ return ["1","2","3"]
//
}
})
另外如果函数在异步回调中返回值，这种情况也是会被过滤掉。
sensors.registerPage({
num:function(){
setTimeout(()=>{
return 100
},500)
}
})
5. 事件采集
5.1. 全埋点事件采集
Web 全埋点
5.2. 自定义事件采集
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
神策分析 SDK 初始化成功后，即可以通过 sensors.track(event_name[, properties][, callback]) 记录事件：
event_name: string
properties: object
callback: function
//
sensors.track(''ViewProduct'', {
//String
ProductName: "MacBook Pro",
//Number -9E15 9E15 3
ProductPrice: 123.45,
//BOOL true false
IsAddedToFav: false,
//List 500 UTF-8 255
ProductList:["apple","orange"],
//DATETIME new Date() yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss
ViewTime:new Date()
});6. 设置用户属性
为了更准确地提供针对人群的分析服务，可以使用神策分析 SDK 的 setProfile() 等方法设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等
功能中，使用用户属性作为过滤条件，精确分析特定人群的指标。
6.1. sensors.setProfile(properties[, callback])
直接设置用户的属性，如果存在则覆盖。
properties：object，必选。
callback：function，可选。
sensors.setProfile({email:''xxx@xx''});
6.2. sensors.setOnceProfile(properties[, callback])
如果不存在则设置，存在就不设置。
properties：object，必选。
callback：function，可选。
sensors.setOnceProfile({email:''xxx@xx''});
6.3. sensors.appendProfile(properties[, callback])
给数组属性添加值。通过setProfile只能改变属性的值。如果这个属性是数组类型的，你不想完全改变这个值，只想做添加操作可以使用此方法。
properties：object，必选。
callback：function，可选。
// category
sensors.appendProfile({catrgory: ['''','''']});
// category
sensors.appendProfile({catrgory: ''''});
6.4. sensors.incrementProfile(properties[, callback])
对当前用户的属性做递增或者递减。
properties：object 或者 string，必选。
callback：function，可选。
// navClick
sensors.incrementProfile({''navClick'': -1});
// navClick 2
sensors.incrementProfile({''navClick'': 2});
// 1
sensors.incrementProfile(''navClick'');
6.5. sensors.deleteProfile([callback])
删除当前用户及他的所有属性。callback: function。{可选}
//
sensors.deleteProfile();
6.6. sensors.unsetProfile(property[, callback])
删除当前用户的一些属性
properties：array 或者 string，必选。
callback：function，可选。
// email location
sensors.unsetProfile([''email'',''location'']);
// email
sensors.unsetProfile(''email'');
7. 高级参数详解
7.1. 批量发送
SDK 版本需 1.14.7 及以上
//
batch_send:false,
//
batch_send:true,
//
batch_send:{
datasend_timeout: 6000, //
send_interval: 6000, //
one_send_max_length: 6 //
},
原理：
写入策略：触发事件就写入 localStorage，localStorage 的兼容性请 [参考文档]，如果浏览器不支持 localStorage，还是使用实时发送数据的方式。
发送策略：定时触发发送，或者，遇到 $pageview（或者使用 quick(''autoTrack''); 方法）和 $SignUp 也会立即存储并且发送。
重复策略：必须请求 success 后，才会删除数据，不然会一直请求，直到数据满一定数量。
注意：
1 track callback callback
2 ajax ajax img
3 localStorage 200 localStorage 200 img
4use_app_track batch_send
7.2. 部分预置属性是否采集(preset_properties)相关参数神策 SDK 采集的最近一次相关的属性会存储在浏览器的 Cookie 中，如果对 Cookie 存储大小有要求，可有选择的采集下列属性，
可配置是否将 $url 和 $title 作为公共属性。
( 1.12.18 版本以上，1.14.10 版本以下的相似功能的 SDK 使用的配置 is_track_latest 已做兼容处理 )
下面配置需要放在初始化配置中，与 server_url 平级，需要 Web JS SDK 版本是 1.14.10 及以上版本
// true ,false ,
preset_properties: {
// $latest_utm true
latest_utm:true,
// $latest_traffic_source_type true
latest_traffic_source_type:true,
// $latest_search_keyword true
latest_search_keyword:true,
// $latest_referrer true
latest_referrer:true,
// $latest_referrer_host 1.14.8 true1.14.8 false true
latest_referrer_host:false,
// $latest_landing_page false
latest_landing_page:false,
// $url false
url: false,
// $title false
title: false,
}
7.3. 获取前端Web JS SDK 采集的预置属性(1.9.13 支持)
此方法可获取，页面地址，页面标题，前向地址，SDK 类型及版本，屏幕宽高，最近一次的相关属性，如果服务端需要使用这些属性需要客户自己传输,且这
些属性不包括需要后端解析的 ip 及 UA 等属性。
sensors.getPresetProperties();JavaScript SDK 常见问题.Web 常见问题 v1.13
1. 字符串最大长度和截取的问题
referrer 字符串截取:
SDK 相关参数 max_referrer_string_length 默认 200 的长度，修改这个值会有两个地方影响。
第一个是与 referrer 相关的属性，会截取这个字段；
第二个是在 cookie 里保存的属性，在下次打开的时候会被截取。
通用字符串截取，超过 7000 的字符串会导致 url 超长发不出去，所以限制长度。
SDK 相关参数 max_string_length 最大默认 500 的长度，可以用来设置字符串最大长度。
另外关于字符串最大长度的问题，也可以保持神策使用 cookie 存贮的数据比较小。
2. 主域名跨域的两个网站，如何统一用户？
如果两个网站是子域名关系，sdk 初始化的时候配置 cross_subdomain 为 true 就行了。
如果两个网站是主域名跨域了，可以使用传递 Distinct ID 的方式实现来两个网站的用户统一。
3. 采集的数据不准确
如果你对 Web JS SDK 的导入数据持有怀疑，想要验证数据导入是否靠谱。可以使用如下代码检测。
var counter = 0;
function test_script_1(){
setTimeout(function(){
if(++counter <= 500 ){
sensors.track(''test_script_1'');
test_script_1();
}
},1000);
}
test_script_1();
上述代码，每秒钟会发一次 test_script_1 事件，总共发送500次，你可以修改次数和间隔。可以直接放在浏览器控制台执行。目前，客观环境都正常的情况
下，准确率100%。
Web JS SDK 如果有漏数据的情况，主要是这么几个情况：
1. 网络环境。突然断线等异常导致数据发送不出去，这种情况难以避免，但是概率比较低。
2. 浏览器环境。老版本浏览器容易崩溃以及异常，某些手机浏览器不支持 Cookie，或者禁用 JavaScript 等，还有浏览器时间异常，或者一些奇葩浏览器取
到的值异常，建议用最新版本的 Chrome、Firefox 等浏览器。
3. 发送的数据格式有误。建议在使用时，一定要看下控制台 console.log 出来的数据！并且在开发阶段使用 debug 模式，查看数据格式是否有问题。如果属
性的类型不一致，事件名不规范，等情况都会导致丢数据，可以在数据导入辅助工具中查看错误原因。
4. 代码逻辑复杂，自己认为会发送某个事件，其实因为程序出错或者逻辑疏忽导致没发，比如自己断定ajax 会成功，然后只在 success 里发了某个事件，
这样是不合理的。
4. 采集客户端 IP
在 Web JS SDK 中不需要传入 $ip 属性。接收数据的服务端会自动解析访问者的 IP。如果您主动设置了 $ip 属性，将会使用你设置的 IP 属性。
5. 在埋点管理中显示埋点信息
因为在 JavaScript 中会自动压缩打包等问题，且很难自动取到当前函数名，行号等信息。所以提供了手动传入埋点信息的方法。
sensors.track(''event'',{$lib_detail:''######''});
// , $lib_detail ##
sensors.track(''clickNav'',{$lib_detail:''##clickNavFunc##nav.js##28''});
// profile
sensors.setProfile({$lib_detail:''####user.js##28''});6. 如何设置页面停留时间
神策分析 1.6 开始提供了 Session 分析功能，可以从页面浏览行为推算出用户大概的页面停留时间，一般情况下使用这个功能就足够了。而精确的页面停留
其实是很难统计的，例如一个用户很可能同时打开多个网页窗口，然后一直不关闭。如果只是想要统计页面打开到关闭的时间，也可以参考以下代码：
假如网站引用了 jQuery ：
var loadHandler = function(e)
{ start = new Date();
};
var unloadHandler = function (e)
{ var end = new Date();
//
var duration = (end.getTime() - start.getTime()) / 1000;
// pageView,()
sensors.track(''pageclose'',
{ pageStayTime: duration,
pageUrl: window.location.href
});
};
if (''onpageshow'' in window) {
$(window).on(''pageshow'', loadHandler);
$(window).on(''pagehide'', unloadHandler);
} else {
$(window).on(''load'', loadHandler);
$(window).on(''unload'', unloadHandler);
}
不使用依赖库：
var start = new Date();
var loadHandler = function(e)
{ start = new Date();
};
var unloadHandler = function (e)
{ var end = new Date();
//
var duration = (end.getTime() - start.getTime()) / 1000;
// pageView,()
sensors.track(''pageclose'', {
pageStayTime: duration,
pageUrl: window.location.href
});
};
if (''onpageshow'' in window) {
addEvent(window, ''pageshow'', loadHandler);
addEvent(window, ''pagehide'', unloadHandler);
} else {
addEvent(window, ''load'', loadHandler);
addEvent(window, ''unload'', unloadHandler);
}
function addEvent(target, type, listener)
{ if (window.addEventListener) {
target.addEventListener(type, listener, false);
} else {
target.attachEvent(''on'' + type, listener);
}
}7. 如何设置页面加载时间
关于页面加载时间，首先要根据需求来选择对应的方法，以 window.onload 为例可以参考如下代码：
// js
var start_time = new Date();
//
var end_time = "" ;
//
window.onload =
function(){ end_time =
new Date();
sensors.track(''pageLoadTime'',{
loadTime:end_time.getTime() - start_time.getTime()
})
}
8. 如何采集输入框的填写时间
这里只是一个事例，如果有需要请参考以下代码：
// !!!
window.addEventListener(''DOMContentLoaded'', function() {
// focusin focusin
document.body.addEventListener(''focusin'', function(event) {
var target = event.target;
if (target.tagName.toLowerCase() === ''input'') { // input
target.dataset.focus_time = (new Date()).valueOf(); // input
target.dataset.focus_value = target.value;
}
});
// focusout input
document.body.addEventListener(''focusout'', function(event) {
var target = event.target;
var targetTag = target.tagName.toLowerCase();
if (targetTag === ''input'') { // input
var now = (new Date()).valueOf();
var requestData = {
input_name: target.name, // input name
begin_time: parseInt(target.dataset.focus_time), //
end_time: now, //
event_duration: now - target.dataset.focus_time, //
previous_value: target.dataset.focus_value,
after_value: target.value
};
// track()
sensors.track(''Input_box_out_of_focus'', requestData);
}
});
});
9. nuxtjs 示例引入代码，需要改成如下
if (process.client) {
var sensors = require(''sensorsdata'');
sensors.init(...)
}
track
if (process.client) {
sensors.track(.......... )
}
10. 全埋点与网页热力分析常见问题
10.1. 没有点击事件，控制台也看不到打印的数据
神策的点击事件是监听在 document 上的，如果阻止了事件的冒泡，就采集不到元素点击事件了。
例如：下面的情况，点击 id 为 one 的标签，就无法触发神策预置的元素点击事件。
$("#one").click(function(event)
{ event.stopPropagation()
;
});
//
$("#one").click(function(event)
{ return false;
});
检测是否阻止了冒泡的方法，在Chrome 浏览器开发者工具控制台上对 document 对象绑定一个点击事件，点击这个按钮看能不能触发，如果不能触发，则阻
止了冒泡
document.addEventListener(''click'',function(){
console.log(123);
});
10.2. $WebClick 事件，预置属性说明
需要客户设置才能采集到的预置属性。
如果客户的神策 SDK 默认采集的标签下列属性都有，那么神策可以默认采集，如果客户的标签缺少其中的某个属性，那么这一条数据的这几个预置属性会
为 未知。
元素 ID：news
元素内容：神策新闻
元素名字：sensorsnews
元素样式名：mnav
元素类型：a
元素链接地址：https://www.sensorsdata.cn
10.3. 如何给 $WebClick 增加自定义属性
// class
方案一，参考本章第 3 节，heatmap 参数的 custom_property 属性。// heatmap.custom_property data="test"
heatmap: {
custom_property: function(element_target) {
// data=test
if(element_target.getAttribute(''data'') ===
''test''){ return {
customProp1: ''test1'',
customProp2: ''test2''
};
}
}
}
方案二，参考本章第 3.1 节，trackHeatMap 及 trackAllHeatMap 方法的使用。
针对非默认标签（非 a, input, button, textarea 标签）的自定义属性，手动触发 trackHeatMap 方法时增加自定义属性
SDK 更新日志
$(''.aa,.bb'').on(''click'', function()
{ sensors.quick(''trackHeatMap'', this,
{
customProp1: ''test1'', // SDK 1.13.7
customProp2: ''test2''
}, function() {
console.log(''callback'');
});
});
所有元素的自定义属性，手动触发 trackAllHeatMap 方法时增加自定义属性
$(''.aa,.bb'').on(''click'', function()
{ sensors.quick(''trackAllHeatMap'', this,
{
customProp1: ''test1'', // SDK 1.13.7
customProp2: ''test2''
}, function() {
console.log(''callback'');
});
});
10.4. 点击会跳转页面的按钮，预置采集的 $WebClick 可能会丢失
详细介绍请参考文档：Web 关页面发数据
10.5. 当前元素有点击，但是没有点击图
建议使用 Chrome 浏览器，在网页热力图页面打开浏览器开发者工具，将包含 Console 中红色部分的完整页面截图发给神策值班同学。
网页热力分析 http 和 https 的问题
首先需要了解一下浏览器的安全性限制:
1 如果一个页面是使用 https 协议打开的，那么在这个页面里面是不能使用 http 协议请求图片、数据、或者 iframe 打开页面，因为都会被浏览器限制。
2 如果一个页面是使用 http 协议打开的，那么在这个页面里面是可以使用 https 协议请求图片、数据、或者 iframe 打开页面，因为浏览器不会受限制。
场景一：客户网站是 http 协议访问，神策后台管理是 https 协议访问
1 这时候 $PageView 事件采集到了页面地址是 http 的。（例如 页面1 ：http://www.abc.com/page1.html）
2 在网页热力分析页面，在列表里面 点击 页面1，这时候页面会使用一个 iframe 来加载 页面1。由于神策后台是 https 协议，页面1 是 http 协议，受浏览
器限制，神策会提示使用 新标签页 打开。
3 点击使用新标签页打开，页面1 是 http 的，这时候页面会向神策后台请求页面点击数据，使用 https 请求。不受限制，可以正常使用。
场景二：客户网站是 https 协议访问，神策后台管理是 http 协议访问1 这时候 $PageView 事件采集到了页面地址是 https 的。（例如 页面1 ：https://www.abc.com/page1.html）
2 在网页热力分析页面，在列表里面 点击 页面1，这时候页面会使用一个 iframe 来加载 页面1。由于神策后台是 http 协议，页面1 是 https 协议，不受限
制，正常打开页面1。
3 页面1 打开后，这时候页面会向神策后台请求页面点击数据，使用 http 请求。由于页面1 是 https 的，受浏览器限制，请求数据异常。
4 Saas 版本默认支持 http 和 https，直接使用 https 访问就可解决问题。
私有部署版本，默认没有开启 https。需要客户自己开启 https。并更新神策后台地址，添加 https 地址。步骤如下：
a、使用 HTTPS 的数据接入
b、更新神策后台地址
10.6. 移动端适配
目前预置的 $WebClick 点击事件是在用户的各种设备的各种屏幕大小下采集的数据，但是点击分析的展示是在一个屏幕下显示的（一般是 PC 端）
方案一:点击分享按钮，用手机扫描二维码，在移动端设备上查看点击分析，后期我们会开发基于多个屏幕大小下的显示方案，敬请期待。
10.7. 样式冲突
如果在页面渲染点击分析数据的时候，发现有样式冲突问题，可以通过切换点击图方案 2 解决（渲染页面顶部黑色操作栏左边切换按钮），我们会持续改
进。
10.8. 其他元素采集
建议除预置采集的 a、button、input 之外只采集部分重点标签元素，不要滥用自定义采集，避免全局采集所有 div 元素，否则会导致 $WebClick 事件量激增，
并且点击图会显示页面上所有 div 元素的色块，导致点击图整体过于混乱无法查看。
10.9. 热力图跨域问题
1 、不配置服务转发的情况下，通常不会存在跨域问题；当配置服务转发后，这个问题可能出现。
2、 私有部署，转发配置错误，可能会导致点击图跨域请求报错。可能修改或重复配置了以下的值
response.setHeader("Access-Control-Allow-Origin", origin);
response.setHeader("Access-Control-Allow-Methods", "POST,GET,PUT,OPTIONS,DELETE");
response.setHeader("Access-Control-Allow-Credentials", "true");
response.setHeader("Access-Control-Allow-Headers", "cors,X-Requested-With,Content-type");
3、https 和 http 的问题
https 页面中不可以发送 http 的 xhr 请求；
http 页面中可以发送 https 请求。
10.10. 网页热力图显示的点击数据不准，手动计算点击数量跟事件分析统计的点击数量不一致
如果页面内容有改动，例如之前页面上有个按钮 A ，后来这个按钮被删除了。那这个按钮 A 的点击事件还在，这会导致事件分析的时候能统计到，但是网页
热力
分析的时候就不能渲染这个按钮了。预置属性.Web 预置属性 v1.13
Web JS SDK 预置事件和预置属性JavaScript SDK 全埋点.Web 全埋点 v1.13
1. 全埋点代码生成
详细参考：Web 快速接入
1.1. 页面浏览事件($pageview)
为了方便使用，神策分析的 SDK 也提供了一些默认事件的收集，例如如果需要采集页面浏览事件（即 PageView），可以通过增加如下代码：
// login
sensors.quick(''autoTrack'')
SDK
platform h5
// login
sensors.quick(''autoTrack'', {
platform:''h5''
})
而如果只想追踪事件，不想设置首次来源到 profile 里，可以使用 sensors.quick(''autoTrackWithoutProfile'') 来替代。
注意： 单页面中发送页面浏览事件($pageview)
参考此文档 Web 单页面
1.2. 页面点击事件($WebClick)
// SDK
heatmap: {
// default $WebClick ''not_collect''
// Web JS SDK 1.7
clickmap:''default''
}
1.2.1. 全埋点默认只自动采集这些交互元素（ a input button textarea ）的 $WebClick 点击事件
开启全埋点，SDK 就会自动追踪页面上的按钮( a button input textarea)这种 html 标签类型 的点击情况，一旦页面某一个按钮发生了点击行为，我们就会去
采集此按钮的一些信息，例如: 这个按钮的标签类型( a button input )，这个按钮的文本内容，这个按钮的 name ，这个按钮的 id 、 class 名，还有一些按钮
特有的属性如 href 等。
1.2.2. 自动采集其他元素 (非 a input button textarea) 的 $WebClick 事件，比如 img 和 div 等
开启全埋点，给需要自动采集点击事件的元素增加属性：data-sensors-click (注意 Web JS SDK 的版本必须是 1.14.23 及以上版本)。
1.2.3. 自定义代码埋点采集其他元素 (非 a input button textarea) 的 $WebClick 事件，比如 img 和 div 等
请注意，在使用该方法采集 div 元素的点击事件时，请根据自身需求采集某些专门的 class 或者 ID 的div 元素，避免全局采集所有 div 元素，否则会导致
$WebClick 事件量激增，并且点击图会显示页面上所有 div 元素的色块，导致点击图整体过于混乱无法查看。
如果你想要对非 a input button textarea 的其他元素采集点击事件的话，请在元素发生点击的时候，调用我们的这个方法。
[SDK 更新日志]// div
// 注意: 在原生js中调用我们绑定的click事件时this指向的是元素节点，在其他框架采集点击事件时this指针也应该指向相应的元素节点，例如在vue中可以参
考下面示例
1.12.14 及以上版本的 SDK 增加新方法 trackAllHeatMap ，当调用这个方法时，此方法的第二个参数可以传入包括 a, input, button, textarea 标签和 div，
img 等的所有标签。而 trackHeatMap 只采集除 a, input, button,textarea 之外的标签。同时，这两个方法均可以设置自定义属性，且支持回调函数（这两个
方法的第四个参数都可以传入一个方法）。
// button
1.3. 视区停留事件($WebStay)
$WebStay
1 4 javascript SDK
2
$WebStay window scroll div// SDK
heatmap: {
// not_collect $WebStay ''default''
// Web JS SDK 1.9.1
scroll_notice_map:''not_collect''
}
2. 网页热力分析
2.1. 点击图
SA SDK 1.7
$pageview, $WebClick
sdk sensors.quick(''autoTrack''); PV (?): Infinity%
可在下图的生成导入代码的页面中，是否开启自动采集开关下选择：采集页面浏览和交互元素的点击，然后重新生成。
相关参数：
web_url: sensorsdata.min.js 1.10
heatmap_url: sensorsdata.min.js 1.13.1
heatmap: heatmap:{} :
heatmap: {
clickmap:''default'',
scroll_notice_map:''default'',
loadTimeout: 3000,
collect_url: function(){
//
if(location.href === ''xxx.com/index.html'' || location.href ===
''xxx.com/''){ return true;
}
},
// $WebClick quick(''trackHeatMap'') quick(''trackAllHeatMap'')
collect_element: function(element_target){
// sensors-disable=trueif(element_target.getAttribute(''sensors-disable'') ===
''true''){ return false;
}else{
return true;
}
},
// $WebClick quick(''trackHeatMap'') quick(''trackAllHeatMap'')
custom_property:function( element_target ){
// data=test name:''aa''
if(element_target.getAttribute(''data'') === ''test''){
return {
name:''aa''
}
}
},
collect_input:function(element_target){
// id a
if(element_target.id ===
''a''){ return true;
}
},
element_selector:''not_use_id'',
renderRefreshTime:1000
}
heatmap 相关参数说明：
参数 参数值说明 备注
名
clickm 是否开启点击图，默认 default 表示开启，可以设置 需要 Web JS SDK 版本号大于 1.7
ap ''not_collect'' 表示关闭
scroll_ 是否开启触达注意力图，设置 default 表示开启，设置 需要 Web JS SDK 版本号大于 1.9.1
notice ''not_collect'' 表示关闭
_map
loadTi 毫秒 设置多少毫秒后开始渲染点击图,因为刚打开页面时候页面有些元素还没加载
meout
collect 返回真会采集当前页面的元素点击事件，返回假表示不采集当
_url 前页面,设置这个函数后，内容为空的话，是返回假的。不设
置函数默认是采集所有页面
collect 用户点击页面元素时会触发这个函数，让你来判断是否要采集
_elem 当前这个元素，返回真表示采集，返回假表示不采集。
ent
custo 假如要在 $WebClick 事件增加自定义属性，可以通过标签的 注意：如果同时使用了 trackAllHeatMap 或者 trackHeatMap 方法设置了自定
m_pro 特征来判断是否要增加 义属性，那么这 两个方法 中的自定义属性对象会覆盖 custom_property 返回值
perty 中的同名属性，它的优先级更高。
collect 考虑到用户隐私，这里可以设置 input 里的内容是否采集 如果返回真，表示采集 input 内容，返回假表示不采集 input 内容,默认不采集
_input
eleme SDK 默认优先以元素 ID 作为选择器采集点击事件，若不想 1.14.12 以上版本支持
nt_sel 以 ID 作为选择器，可以设置该参数为 ''not_use_id''
ector
render 毫秒 第二版点击图滚动滚动条，改变页面尺寸后延时多少毫秒重新渲染页面
Refres
hTime
2.2. 触达图
$WebStay
3javascript sdk 4 ,
$WebStay
2.2.1. 触达图详细配置参数(SDK 1.12.1 以上版本可用)
scrollmap: {
collect_url: function(){
//
if(location.href === ''xxx.com/index.html'' || location.href ===
''xxx.com/''){ return true;
}
},
},
heatmap:{
// not_collect $WebStay ''default''
// Web JS SDK 1.9.1
scroll_notice_map:''not_collect'',
scroll_delay_time: 4000,
scroll_event_duration: 18000 // event_duration 530018000
}
scrollmap 相关参数说明：
参数名 参数值说明 备注
collect_url 返回真会采集当前页面的数据，返回假表示不采集当前页面,设置这个函数后，内容为空的话，是返回假的。不设置函数默认是采
集所有页面
heatmap 相关参数说明：
参数名 参数值说明 备注
scroll_notice_map 是否开启触达图，设置 default 表示开启，设置 ''not_collect'' 表 需要 Web JS SDK 版本号大于 1.9.1
示关闭
scroll_delay_time 毫秒 设置触达图的有效停留时间，默认超过 4 秒以上算有效停留
scroll_event_durati 秒 预置属性停留时长 event_duration 的最大值，默认 18000 秒，
on 5 小时JavaScript SDK 点击图.Web 渠道参数 v1.13
1. 用户相关属性
属性名 名称 更新机制
$first_referr 首次前向地址 仅在新设备首次打开嵌入了 Web JS SDK 的页面并且开启了 sa.quick(''autoTrack'') 或者 sa.quick
er ("autoTrackSinglePage")，才会自动触发 profile_set_once 写入神策用户表（以后不会再自动采集更新）。
$first_referr 首次前向地址域名
er_host
$first_traffic 首次流量来源类型
_source_type
$first_searc 首次搜索引擎关键词
h_keyword
$utm_source 首次广告系列来源
$utm_medium 首次广告系列媒介
$utm_term 首次广告系列字词
$utm_conte 首次广告系列内容
nt
$utm_camp 首次广告系列名称
aign
xxx source_channel 自定义
渠道来源属性: [''xxx'',
''yyy'']
yyy source_channel 自定义
渠道来源属性: [''xxx'',
''yyy'']
2. 事件相关属性
属性名 名称 备注 更新机制
$referrer 前向地址 $pageview 才有该 不区分站内站外，页面地址变化即更新
属性
$referrer_host 前向域名
$utm_xxx 广告系列来源属性(包 不区分站内站外，页面地址变化且带有 utm 或自定义渠道属
括：$utm_source、$utm_medium、$utm_term、$utm_content 性 xxx，即局部 utm 或 xxx 更新(对应的 latest_xxx 或
、$utm_campaign) _latest_xxx 也会更新)
xxx 自定义渠道属性(比如：source_channel:[''xxx''])
(source_channel
自定义渠道来源属
性)
_latest_xxx 最近一次自定义渠道属性(比如：source_channel:[''xxx''])
$latest_utm_xxx 最近一次广告系列来源属性(包 默认采集
括：$latest_utm_source、$latest_utm_medium、$latest_utm_t
erm、$latest_utm_content、$latest_utm_campaign) 可通过配置
preset_properties
$latest_referrer 最近一次站外前向地址 控制是否采集 latest 最近一次，根据域名判断是否从站外跳转进来，如果
是，则更新(同域名站内跳转不更新)
$latest_referrer_ 最近一次站外前向域名 所有事件都有该属
host 性
$latest_traffic_s 最近一次站外流量来源类型
ource_type
$latest_search_k 最近一次站外搜索引擎关键词
eyword
$latest_landing_ 最近一次落地页地址
page3. 一般场景取值
3.1. 流量来源类型 traffic_source_type
关于首次流量来源类型 $first_traffic_source_type 及最近一次流量来源类型 $latest_traffic_source_type 的取值逻辑：
属性名 取值 场景
$first_traffic_source_t 付费广告 落地页地址含有 utm_xxx 参数
ype 流量
$latest_traffic_source 自然搜索 落地页地址无 utm_xxx 参数且前向地址中包含search 中的参数：
_type 流量
神策已有参数：[''www.baidu.'',''m.baidu.'',''m.sm.cn'',''so.com'',''sogou.com'',''youdao.com'',''google.'',''yahoo.com
/'',''bing.com/'',''ask.com/''];
社交网站 落地页地址无 utm_xxx 参数且前向地址中包含 social 中的参数:
流量
神 策 已 有 参 数 ：[''weibo.com'',''kaixin001.com'',''douban.com'',''qzone.qq.com'',''zhihu.com'',''tieba.baidu.com'',''weix
in.qq.com''];
直接流量 如果前向地址为空：直接复制网址或者点击书签打开页面
引荐流量 如果以上情况都不是，比如前向地址为某个私人网站
可以先通过 sensors.para.source_type.search 等方式，来查看目前已经定义的部分判定条件。 如果你有新的判断条件想要增加，可以通过以下代码，来扩
展。
source_type :{
search: [''.baidu.com'',''.google.''],
social: [''.kaixin001.com''],
keyword: {baidu:[''wd'',''word'',''keyword''],sogou:''query''}
}
3.2. 搜索引擎关键词 search_keyword
关于首次搜索引擎关键词 $first_search_keyword 及最近一次搜索引擎关键词 $latest_search_keyword 的取值逻辑，从 $referrer 中解析获取（由于现在搜
索引擎大多不提供关键词，所以大概率会未取到值）：
属性名 取值 场景
$first_search_keyword xxx关键词 比如：source_type :{
search: [''.baidu.com'',''.google.''],
$latest_search_keyword keyword: {baidu:[''wd'',''word'',''keyword''],sogou:''query''}
}
前向地址为：www.baidu.com?...&keyword=xxx&...;则此时可以解析到，取值为：xxx
未取到值 有前向地址，但不符合上面的情况，则取值为：未取到值
未取到值_直接打开 前向地址为空：直接复制网址或者点击书签打开页面
3.3. 场景示例
属性名 百度（搜索：神策，点击无 utm 的链 A 页面 C 页面(直接 C 页面 => 搜狗（搜索：神策，点击带 utm 的链
接） => A页面 => B 页 面 打开) D 页面 接） => A页面
$referrer 百度url A 页面url 空字符串 C 页面url 搜狗url
$referrer_host www.baidu.com A 页面域名 空字符串 C 页面域名 www.sogou.com
$latest_referrer 百度url 百度url 空字符串 空字符串 搜狗url
$latest_referrer_host www.baidu.com www.baidu.com 空字符串 空字符串 搜狗域名$latest_traffic_sourc 自然搜索流量 自然搜索流量 直接流量 直接流量 付费广告流量
e_type
$latest_search_keyw 神策 神策 未取到值_直接 未取到值_直接 未取到值
ord 打开 打开
$latest_landing_page A 页面url A 页面url 空字符串 空字符串 A 页面url
4. 常见问题
4.1. 前向地址 referrer 与 前向域名 referrer_host 特殊场景
属性名 属性值 原因
$first_referrer 空字符串 直接打开页面（比如：输入地址或书签打
开）
$first_referrer_host 未知
$referrer 空字符串
$referrer_host 空字符串
$latest_referrer 空字符串
$latest_referrer_host 空字符串
4.2. 最近一次( latest_xxx )相关属性的特殊场景
属性名 原因：cookie被清空或前一个页面同域名但 原因：当前页面域名 domain 无法解析（比如：www.biz.work、localhost、
未集成 SDK 192.168.11.23 等）
latest_utm_xxx 正常解析 utm_xxx 并更新 latest_utm_xxx 属 正常解析 utm_xxx 并更新 latest_utm_xxx 属性
性
$latest_traffic_sourc 取值异常 url的domain解析失败
e_type
$latest_search_keyw 取值异常 url的domain解析失败
ord
$latest_referrer 取值异常 url的domain解析失败
$latest_referrer_host 取值异常 取值异常
$latest_landing_page 取值异常 url的domain解析失败单页面.Web 单页面 v1.13
1. 单页面简介
1.1. 单页面定义
单页面应用（SPA，Single-page Application）指只有一个主页面的应用，浏览器一开始要加载所有必须的 html, js, css。所有的页面内容都包含在这个所
谓的主页面中。但在写的时候，还是会分开写（页面片段），然后在交互的时候由路由程序动态载入。
1.2. 单页面和多页面的区别
相比之下，传统的多页面应用每个页面（只说动态页面）都是使用服务器端模板编写，然后请求这个页面的时候由服务器渲染成 html 再返回。两者对比，一
个很明显的区别就是，多页面应用的 server 端要干两件事：提供数据+渲染，而单页面应用把渲染拿到浏览器端做了，服务器只提供数据就可以了。
1.3. 单页面特点
单页面不管你点击什么地方，不会刷新页面，都是在一个页面上完成的操作，操作过程中不进行页面跳转，url 地址栏#后面的字符在不停变化，且每一次变
化，页面会跟随着实现局部刷新，呈现出不同的内容。
1.4. 常用框架
Angular / Vue / React / Ionic / Backbone 等 。
1.5. 查看一个页面是否是单页面的方式
F12，Network，当 url 改变时看资源是否被刷新了一遍。
1.6. 单页面埋点
SDK 的获取和引入可以参考 Web 快速接入。需要注意的是，引入代码只需在项目靠前的位置引入一次，以 Vue 为例，将初始化代码
放置在 main.js 中就可以在项目中使用神策分析了。
2. 单页面中的页面浏览事件采集($pageview)
2.1. 自动模式
配置参数 is_track_single_page (推荐使用这种模式)，默认值为 false ，表示是否开启自动采集 web 浏览事件 $pageview 的功能
其原理是修改 window 对象的 pushState 和 replaceState 原生方法，在页面的 url 改变后自动采集 $pageview 事件，若用户浏览器不支持这两种方法或者
是使用 hash 的路由模式，我们也会监听 popstate 和 hashchange 事件来自动触发 $pageview 事件
使用方法示例：
//SDK1.12.18false
is_track_single_page:true
// sa.quick(''autoTrack'')SDK 版本大于等于 1.14.1 的 is_track_single_page 参数增加 function(){} 的配置，必须 return 一个值。
配置一：return true 表示当前页面会发送数据，
配置二：return false 表示不会发数据，
配置三：return {} 对象，表示会把对象的属性新增到当前 $pageview 里。
使用方法示例：
is_track_single_page : function
(){ return true $pageview
return false $pageview
return {} $pageview
}
// sa.quick(''autoTrack'')
另外注意：
必须保证切换页面前神策 Web JS SDK 的已经执行，否则的话可能第一次切换页面不会触发 $pageview。
2.2. 手动模式
在页面切换的时候，手动调用 sensors.quick(''autoTrackSinglePage'') 来采集 web 浏览事件 $pageview ,这个方法在页面 url 切换后调用
// react onUpdate
onUpdate: function(){
sensors.quick(''autoTrackSinglePage'');
}
//vue
router.afterEach((to,from) => {
Vue.nextTick(() => {
sensors.quick("autoTrackSinglePage");
});
});
// vue sa.quick(''autoTrack'')
此方法也可添加自定义属性，
sensors.quick("autoTrackSinglePage",{platForm:"H5"});
3. 单页面的页面标题 $title 问题
对于单页面项目，神策 SDK 全埋点的预置事件采集的页面标题属性，可能存在异常
具体问题：
1、title 如果没有更新赋值，获取的 title 一直是主页的 title 不会变化，切换页面发送的数据不会更新 $title 2、
title 设置的时机晚于数据发送的时机，切换页面发送的 $pageview 事件携带的 $title 值为上一个页面的 title 解决
方案：
在切换页面前完成 title 值的更新（以常见的 vue 为例）
router.beforeEach((to, from, next) =>
{ document.title = '' title '';
next()
})3.1. 单页面 SDK Demo关闭页面发数据.Web 关页面发数据 v1.13
1. 关闭页面发数据丢失不可避免
因为浏览器的特性，关闭页面前发请求，该请求有可能会失败
具体场景： 点击某个按钮后，页面发生跳转
数据丢失的概率：
正常情况下，由于设备，浏览器，网络等因素影响，Web JS SDK 丢数据概率不超过 5%，但是在关闭页面的情况下，丢失率会增加。
尤其在移动网络环境下，丢失率严重。在手机 iOS 下的 Safari 丢失率极高。
2. 优化方案
2.1. 服务端发送事件
如果是关键的点击，需要准确的采集，比如支付等事件是在关闭页面时发送，建议在服务端中埋点采集。
2.2. 采集跳转后页面的 $pageview 事件
用户点击 href 属性为 www.xxx.com 的 a 标签，触发 $WebClick 事件或者用户自定义的 track 事件，这时页面会进行跳转。可能数据未发送成功，页面已
经跳转到 www.xxx.com ，会造成数据的的丢失。
方案：给 a 标签的 href 属性添加某个参数，例如 www.xxx.com?urlfrom=123 ，当页面跳转到 www.xxx.com?urlfrom=123 后，采集这个页面的
$pageview 事件，在神策后台中查看 Web 浏览事件，根据 url 是否包含 urlfrom 这个参数来筛选结果。
2.3. callback 回调中再跳转页面
神策自定义事件的 track 方法的第三个参数，回调函数，受 callback_timeout 参数影响（callback_timeout: 默认值 200 ，单位毫秒，表示回调函数超时时
间，如果数据发送超过 callback_timeout 还未返回结果，会强制执行回调函数）。
正常情况下数据请求返回后，就会执行 callback 方法，但是考虑到网络卡或者死机的情况，设置 callback_timeout 的超时来强制执行 callback。其中有两
种不太常见特殊场景需要注意：
1. 不能把时间设置的太长，比如 3s，因为不能保证网络请求一定能返回，这时候就会使用这个 callback_timeout，所以设置这个时间最好在 500ms 左右，
可接受的范围内。
2. 不能把时间设置的太短，比如 100ms，因为可能请求还没发成功，就执行 callback 了，正常情况下没问题，但是如果 callback 里是页面跳转的操作，那
这个数据可能会丢失。
//
$(''a'').on(''click'',function(e,url){ e.preventDefa
ult(); // sensors.track(''a_click'', {},
function(){
location.href = url;
}); //callback
});
2.4. 使用 setTimeout：
//
function targetLinkIcon( url ){
// SDK
setTimeout(function(){
window.location.href = url;
},500);
//
sensors.track(''demo'',{});
}
2.5. （不稳定） beacon 的方式发送数据，截止到 2018-3-20 前 ie 和 safari 不支持此方法。
sensors.track(''a_click'',{$option:{send_type:''beacon''}});这三种方式，第一种从根本上解决问题，将事件进行转换。推荐使用。
第二种需要阻止默认事件，对浏览器兼容性好。可以尝试。
第三种方式，在网页关闭情况下也可以发送数据，但是兼容性不佳。
2.6. batch_send 批量发送缓存数据
batch_send: 默认值 false，表示不开启批量发送，设置为 true 表示开启批量采集，并且使用以下默认值 { datasend_timeout: 6000, 一次请求超过多少秒的
话自动取消，防止请求无响应。send_interval: 6000, 间隔几秒发一次数据。one_send_max_length: 6 一次请求最大发送几条数据，防止数据太大 },也可以直
接以 {} 的方式自定义这几个参数的值，
详细介绍：Web 基本使用 批量发送。
//
batch_send:false,
//
batch_send:true,
//
batch_send:{
datasend_timeout: 6000, //
send_interval: 6000, //
one_send_max_length: 6 //
},
原理：
写入策略：触发事件就写入 localStorage，localStorage 的兼容性请 参考文档，如浏览器不支持 localStorage，还是使用实时发送数据的方式。
发送策略：定时触发发送，或者，遇到 $pageview（或者使用 quick(''autoTrack''); 方法）和 $SignUp 也会立即存储并且发送。
重复策略：必须请求 success 后，才会删除数据，不然会一直请求，直到数据满一定数量。
注意：
1 SDK tracklogin
2 ajax ajax img
3 localStorage 200 localStorage 200 img
4use_app_track batch_send小程序.小程序 v1.14
微信小程序 SDK
全埋点版 SDK 集成
微信小程序 API
自定义埋点版 SDK 集成
插件版 SDK 集成
历史版本（已废弃）
支付宝小程序 SDK
自定义埋点版集成
全埋点版集成
支付宝小程序 API
百度小程序 SDK
字节跳动小程序 SDK
QQ 小程序 SDK
小程序 SDK 预置属性
小程序 SDK 常见问题
快应用 SDK
微信小游戏 SDK
微信小游戏 API微信小程序 SDK.微信小程序 SDK v1.13
全埋点版 SDK 集成
微信小程序 API
自定义埋点版 SDK 集成
插件版 SDK 集成
历史版本（已废弃）
1.1. 全埋点版微信小程序 SDK
全埋点版微信小程序 SDK 通过代理 App、Page 和 Component 的生命周期函数与各个事件处理函数来实现对 $MPLaunch、 $MPShow、
$MPHide、 $MPViewScreen、 $MPShare、 $MPClick 六个预置事件的采集；
1.2. 自定义埋点版 SDK 集成微信小程序 SDK
全埋点版本的微信小程序 SDK 是通过代理小程序的 App 和 Page 方法实现的自动采集，但是因为代理这两个方法存在这两个方法被微信禁止读写
的风险，另外可能某些用户不需要自动采集，这时候就强烈建议使用自定义采集的方法；
自定义埋点版微信小程序 SDK 提供了在 App 的 onLaunch、 onShow、 onHide 生命周期函数中调用 quick() 接口的方法来采集 $MPLaunch、
$MPShow、 $MPHide 三个预置事件，效果跟全埋点版本一致；
1.3. 插件版 SDK 集成微信小程序 SDK
经过测试发现，如果小程序中使用了第三方插件且调试基础库版本在 2.6.4 以下时，App 和 Page 这两个全局变量是不可读的，这会导致全埋点版
微信小程序 SDK 不可用；基础库版本在 2.6.4 及以上这个问题就不存在了，全埋点版微信小程序 SDK 可以使用；针对使用了第三方插件且调试基
础库版本在 2.6.4 以下的这种情况，可以使用插件版小程序 SDK 。这个版本相比全埋点版微信小程序 SDK ，复杂处在于每个 Page 里的 JS 顶部
都要引入一段代码，才可以自动采集 Page 里的预置事件。
1.4. 历史版本（已废弃）
1.13.1 版本之前 SDK 使用方法说明，已经废弃，仅供历史用户参考。标准版.全埋点版 SDK 集成 v1.13
在使用前，请先阅读数据模型的介绍。
如想查看 SDK 历史版本，请参考 SDK 更新日志。
1. 全埋点版微信小程序 SDK 说明
全埋点版微信小程序 SDK 可以自动采集 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、 $MPShare、 $MPClick 六个预置事件；
全埋点版微信小程序 SDK 通过代理 App、Page 和 Component 的生命周期函数与各个事件处理函数来实现对 $MPLaunch、 $MPShow、
$MPHide、 $MPViewScreen、 $MPShare、 $MPClick 六个预置事件的采集；
全埋点版微信小程序 SDK 目前不支持使用 Chameleon 框架开发的小程序；
2. 快速使用
2.1. 集成与使用
2.1.1. 下载文件
从 GitHub 上下载微信小程序 SDK, sensorsdata.min.js ；
目前微信小程序 SDK 压缩文件 sensorsdata.min.js 大小约为 28kb；
2.1.2. 引入 SDK 、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
调用 setPara() 方法设置初始化参数，必须在 require() 之后，立即调用 setPara() 方法设置；
调用 init() 方法标志已完成初始化；
注意：init() 方法必须调用，否则不会发数据。
app.j
s
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
// false
autoTrack: {
appLaunch: true,
appShow: true,
appHide: true,
pageShow: true,
pageShare: true,
// true
mpClick: false
},
// source_channel: ["custom_param"]
source_channel: [],
// ()
show_log: true,
// onShareAppMessagereturnpath(idpath)app onShow
allow_amend_share_path: true
});
sa.init();
注意：以上初始化代码需要放在 App 构造之前，不可以放在生命周期函数中，否则可能会造成部分预置事件丢失。
2.1.3. 自定义事件采集
在其他页面逻辑 js 文件中通过调用 track() 接口来采集自定义事件；
index.js
var app = getApp();
// clickImage
Page({
bindTapImage: function(){
app.sensors.track(''clickImage'',{name:''''});},
onLoad: function(){
}
});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，微信开发者工具 console 会打印采集的数据，json 格式；
微信开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在微信开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；
3. 标识用户
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中，会有下面 3 种 ID:
1. 默认情况下，微信小程序 SDK 会生成一个唯一的随机数，保存在微信 storage 中，我们称这个为 UUID;
2. 用户打开小程序，可以获得微信分配给用户的 openid ，我们称这个为 openid;
3. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
3.1. 使用 openid 作为匿名 ID
如果不做任何操作，小程序会使用 UUID 作为 Distinct ID，但是这个 UUID 换了设备，或者删除小程序后，会重新生成。所以一般情况下，我们建议使用
openid 作为当前的 Distinct ID。
下面是常见的两种使用 openid 作为匿名 ID 的初始化代码。
方案一
/**
app.js
**/
var sa = require(''sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: ''''
});
// openid
wx.request({
url: '' openid '',
success: function(res){
// openid ID
sa.setOpenid(res.openid);
}complete:
function(){ sa.in
it();
}); }
注意：init 不调用就不会发任何数据，确保无 openid 的时候也有 init 方法可执行
方案二
/**
app.js
**/
var sa = require(''sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
appid: ''''
});
// 1 appid appsecret
// 2setPara() appid
sa.initWithOpenid();
3.2. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID (UUID) 来标识用户。当用户注册成功或登录成功时调用 login() 方法，传入对应的用户 ID；匿名 ID 会与对应的用户
ID 进行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK（如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
app.j
s
var sa = require(''sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: ''''
});
/**
openid ID,
**/
wx.request({
url: '' openid '',
success: function(res){
// openid ID
sa.setOpenid(res.openid);
},
complete:
function(){ if("
ID"){
sa.login(" ID");
}
sa.init();
}
});
/**
UUID ID,
**/
if(" ID"){
sa.login(" ID");
}
sa.init();4. 预置事件
为了方便使用， 0.9 及以上版本的小程序 SDK 已经可以自动追踪微信小程序中的冷启动，热启动，进入后台，页面浏览，页面分享等事件；1.13.18 及以上
版本的 SDK 开始自动追踪页面元素点击动作。
事件名称 相应小程序生命周期 触发时机 说明
$MPLaunch（小程序启动） App.onLaunch 小程序进程被杀死，重新打开时会触发 小程序初始化完成时，全局只触发一次
$MPShow（小程序显示） App.onShow 小程序启动，或从后台进入前台显示 启动小程序时
$MPHide（小程序进入后 App.onHide 点击小程序右上角退出按钮、微信进入后台、进入小程序关于页 小程序从前台进入后台
台） 面、手机锁屏、小程序进程被杀死时
$MPViewScreen（小程序 Page.onShow 小程序启动打开页面、小程序内打开页面、从后台进入前台打开页 每次打开页面都会调用一次
页面浏览） 面时触发
$MPShare（小程序分享） Page. 设置这个函数后，点击分享按钮触发 暂时只能获取到用户触发分享，无法监听
onShareAppMessage 是否分享成功的反馈
$MPClick（小程序元素点 当 Page 中定义的事件处理函数被触发时采集 目前只支持 tap/ longtap / longpress 三
击） 类事件
可以通过设置 setPara() 方法中的 autoTrack 参数，开启自动采集
app.j
s
var sa = require(''sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack:{
appLaunch:true, // $MPLaunch true
appShow:true, // $MPShow true
appHide:true, // $MPHide true
pageShow:true, // $MPViewScreen true
pageShare:true, // $MPShare true
mpClick: true // $MPClick true
}
});
sa.init();
注意事项：
1. 1.13.6 版本之前的微信小程序 SDK 是通过代理监听小程序 Page 构造器与页面生命周期中的 onShareAppMessage() 函数来采集
$MPViewScreen、$MPShare 预置事件的；
2. 当使用框架开发小程序时，如果框架代码在编译后使用的是 Component 构造器形成的页面，那么1.13.6 版本之前的微信小程序 SDK 无法自动采
集该页面的预置事件 $MPViewScreen $MPShare，可以使用 track() 方法自定义采集；
5. 预置属性
所有事件都有的预置属性、预置事件有的预置属性以及预置采集的用户属性可以查看微信小程序 SDK 预置事件与预置属性文档；
6. 相关文档
微信小程序 SDK 预置事件与预置属性；
小程序 SDK 常见问题；
微信小程序 SDK API；各框架下的接入.微信小程序 API v1.13
1. 初始化相关 API
1.1. setPara( args );
说明：用来配置初始化参数；
参数：args : object , 初始化参数对象，可配置的属性如下
name: string , SDK 使用的一个默认的全局变量,会注册在 App 全局函数内，在 Page 中可以通过 app[name].track 来使用，默认值是
sensors 。
appid: string , (非必填参数)如果需要使用 initWithOpenid() 方法来完成初始化，需要在神策后端配置 appid 和 appsecret ，同时在这里指
定 appid 。
server_url: string , 数据接收地址。注意: 请在微信公众平台---开发---开发设置---服务器域名中，把这个地址添加上。
autoTrack: object , 是否开启自动采集，六个属性参数( appLaunch、 appShow、 appHide、 pageShow、 pageShare、mpClick)，其
中 mpClick 默认是 false，其他是 true。即默认采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare（0.9
以上版本的 SDK 支持），其中 $MPShare 事件 1.9 版本以上支持，$MPClick 事件默认不采集，详细介绍见预置事件。
show_log: boolean , 设置 true 后会在模拟器控制台打 logger，会显示发送的数据,设置 false 表示不显示。默认为 true 。
send_timeout: number , 请求发送超时时间（如果一个请求发送后，超过规定时间没响应，则继续发送下一条数据），默认为 1000 毫
秒。
use_client_time: boolean , 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端时
间，使用服务端时间，如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date 类
型，那么这条数据就会使用你在属性中传入的这个时间。
allow_amend_share_path: boolean ,设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性，新增一些参数包括当前用户
的 distinct_id 等，如果要自动采集分享信息，必须设置为 true ，默认为 true 。
batch_send: boolean , 小程序中是否使用批量发送数据功能,默认为 false ,配置注意事项详见常见问题 。
datasend_timeout: number , 请求发送取消时间（请求发送后，在规定时间内未返回结果，则取消请求），默认为 3000 毫秒（1.12.9 及
以上版本支持） 。
source_channel: array , 默认情况下，只会解析参数 utm_source、 utm_content、 utm_campaign、 utm_medium、 utm_term 设置到
预置事件中，可以通过配置该参数来解析其他自定义参数，例如[''from'', ''to''] （1.13.8 及以上版本支持） 。
is_persistent_save: boolean , 是否需要将最近一次渠道信息保存到 wxStorage 中，默认为 false (1.13.9 及以上版本支持) 。
1.2. init();
说明：用来标识小程序 SDK 初始化完成，数据可以通过网络发送；此方法不调用，采集的数据会被缓存在内存中，不能通过网络发送；
1.3. setOpenid();
说明：用来将匿名 ID 修改为 openid;
1.4. initWithOpenid();
说明：当客户希望使用 openid 作为匿名 ID,同时不想自己获取 openid 再修改匿名 ID,而是希望神策自动获取 openid，可以使用这个 API.注意事项
可以参考常见问题；
2. 采集事件数据 API
2.1. track( eventName,[properties] );
说明：采集自定义事件。
参数：
eventName：`string`， 必 填 ， 事 件 名 称 ； properties：`object`，
选填，为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.js
//
var app = getApp();
app.sensors.track(''ViewProduct'', {
//String
ProductName: "MacBook Pro",
//Number -9E15 9E15 3
ProductPrice: 123.45,
//BOOL true false
IsAddedToFav, false//List 500 UTF-8 255
ProductList:["apple","orange"],
//DATETIME new Date() yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss
ViewTime:new Date()
});
2.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 distinct_id 不一致时，会触发 $SignUp 预置事件；
参数：
userID: string, 必填，用户 ID 或登录 ID
2.3. registerApp( properties );
说明：用来给所有事件设置公共属性，可以在 app.js 文件引入 sensorsdata.min.js 文件之后， init() 方法调用之前使用 registerApp() 方法设置公
共属性。
参数：
properties：object，必填,为该方法调用后的所有事件设置的公共事件属性；
app.j
s
//
var sa = require(''sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: ''''
});
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
sa.init();
2.4. quick( [''appLaunch''|''appShow''|''appHide''|''getAnonymousID''], [options], [properties]);
说明：通过给定的第一个参数，来分别实现不同的功能；
参数：
appLaunch:string, 用来发送一条预置事件 $MPLaunch 数据，一般在小程序 App 实例的 onLaunch 生命周期中调用；
第二个参数 options，必须， 需要传入返回的生命周期函数参数对象；
第三个参数 properties，非必须，可以传入要设置给预置事件 $MPLaunch 事件的自定义属性；
appShow:string, 用来发送一条预置事件 $MPShow 数据，一般在小程序 App 实例的 onShow 生命周期中调用；
第二个参数 options，必须， 需要传入返回的生命周期函数参数对象；
第三个参数 properties，非必须，要设置给预置事件 $MPShow 事件的自定义属性
appHide:string, 用来发送一条预置事件 $MPHide 数据，一般在小程序 App 实例的 onHide 生命周期中调用；
第二个参数 options，非必须， 要设置给预置事件 $MPHide 事件的自定义属性；
getAnonymousID:string, 用来获取匿名 ID;
3. 采集用户数据 API
3.1. setProfile( properties );
说明：设置用户的属性，如果存在则覆盖。
参数：
properties：object，必填，要给该用户设置的用户属性；
app.j
s
sa.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});3.2. setOnceProfile( properties );
说明：如果不存在同名属性则设置，存在同名属性，同名属性不会重新设置。
参数：
properties：object，必填，要给该用户设置的用户属性；
app.j
s
sa.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
3.3. incrementProfile( properties );
说明：增加或减少一个用户的某个 Numeric 类型的 Profile，如果该用户属性不存在则自动创建。
参数：
properties：object，必选。
app.j
s
sa.incrementProfile({
subscribers: 5
});
3.4. appendProfile( properties );
说明：向某个用户的某个数组类型的 Profile 添加一个或者多个值。
参数：
properties：object，必选。
app.j
s
sa.appendProfile({
favoriteFruits: ['''', '''']
});
4. 其他 API
4.1. identify( ''anonymousID'', [boolean]);
说明：用来修改当前小程序访问用户的匿名 ID;
参数：
anonymousID: String ,要使用的匿名 ID;
boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到微信 storage 中；不填或者设置为 false，表示该匿名 ID 只在小游戏本次生命周
期中有效，下次冷启动后使用的仍然时修改之前的匿名 ID;
4.2. getPresetProperties();
说明：用来获取部分预置属性；
4.3. clearAllRegister();
说明：用来清除存储在 storage 中的公共属性；
4.4. logout( [boolean])
说明：用来将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;
参数：
boolean: Boolean, 不填, 表示将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID；设置为 true，表示将当前的 Distinct ID 切换
为一个重新生成的 UUID；.微信小程序 API v1.14
1. 初始化相关 API
1.1. setPara( args );
说明：用来配置初始化参数；
参数：args : object , 初始化参数对象，可配置的属性如下
name: string , SDK 使用的一个默认的全局变量,会注册在 App 全局函数内，在 Page 中可以通过 app[name].track 来使用，默认值是
sensors 。
appid: string , (非必填参数)如果需要使用 initWithOpenid() 方法来完成初始化，需要在神策后端配置 appid 和 appsecret ，同时在这里指
定 appid 。
server_url: string , 数据接收地址。注意: 请在微信公众平台---开发---开发设置---服务器域名中，把这个地址添加上。
autoTrack: object , 是否开启自动采集，六个属性参数( appLaunch、 appShow、 appHide、 pageShow、 pageShare、mpClick)，其
中 mpClick 默认是 false，其他是 true。即默认采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare（0.9
以上版本的 SDK 支持），其中 $MPShare 事件 1.9 版本以上支持，$MPClick 事件默认不采集，详细介绍见预置事件。
show_log: boolean , 设置 true 后会在模拟器控制台打 logger，会显示发送的数据,设置 false 表示不显示。默认为 true 。
send_timeout: number , 请求发送超时时间（如果一个请求发送后，超过规定时间没响应，则继续发送下一条数据），默认为 1000 毫
秒。
use_client_time: boolean , 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端时
间，使用服务端时间，如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date 类
型，那么这条数据就会使用你在属性中传入的这个时间。
allow_amend_share_path: boolean ,设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性，新增一些参数包括当前用户
的 distinct_id 等，如果要自动采集分享信息，必须设置为 true ，默认为 true 。
batch_send: boolean , 小程序中是否使用批量发送数据功能,默认为 false ,配置注意事项详见常见问题 。
datasend_timeout: number , 请求发送取消时间（请求发送后，在规定时间内未返回结果，则取消请求），默认为 3000 毫秒（1.12.9 及
以上版本支持） 。
source_channel: array , 默认情况下，只会解析参数 utm_source、 utm_content、 utm_campaign、 utm_medium、 utm_term 设置到
预置事件中，可以通过配置该参数来解析其他自定义参数，例如[''from'', ''to''] （1.13.8 及以上版本支持） 。
is_persistent_save: boolean , 是否需要将最近一次渠道信息保存到 wxStorage 中，默认为 false (1.13.9 及以上版本支持) 。
1.2. init();
说明：用来标识小程序 SDK 初始化完成，数据可以通过网络发送；此方法不调用，采集的数据会被缓存在内存中，不能通过网络发送；
1.3. setOpenid();
说明：用来将匿名 ID 修改为 openid;
1.4. initWithOpenid();
说明：当客户希望使用 openid 作为匿名 ID,同时不想自己获取 openid 再修改匿名 ID,而是希望神策自动获取 openid，可以使用这个 API.注意事项
可以参考常见问题；
2. 采集事件数据 API
2.1. track( eventName,[properties] );
说明：采集自定义事件。
参数：
eventName：`string`， 必 填 ， 事 件 名 称 ； properties：`object`，
选填，为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.js
//
var app = getApp();
app.sensors.track(''ViewProduct'', {
//String
ProductName: "MacBook Pro",
//Number -9E15 9E15 3
ProductPrice: 123.45,
//BOOL true false
IsAddedToFav, false//List 500 UTF-8 255
ProductList:["apple","orange"],
//DATETIME new Date() yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss
ViewTime:new Date()
});
2.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 distinct_id 不一致时，会触发 $SignUp 预置事件；
参数：
userID: string, 必填，用户 ID 或登录 ID
2.3. registerApp( properties );
说明：用来给所有事件设置公共属性，可以在 app.js 文件引入 sensorsdata.min.js 文件之后， init() 方法调用之前使用 registerApp() 方法设置公
共属性。
参数：
properties：object，必填,为该方法调用后的所有事件设置的公共事件属性；
app.j
s
//
var sa = require(''sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: ''''
});
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
sa.init();
2.4. quick( [''appLaunch''|''appShow''|''appHide''|''getAnonymousID''], [options], [properties]);
说明：通过给定的第一个参数，来分别实现不同的功能；
参数：
appLaunch:string, 用来发送一条预置事件 $MPLaunch 数据，一般在小程序 App 实例的 onLaunch 生命周期中调用；
第二个参数 options，必须， 需要传入返回的生命周期函数参数对象；
第三个参数 properties，非必须，可以传入要设置给预置事件 $MPLaunch 事件的自定义属性；
appShow:string, 用来发送一条预置事件 $MPShow 数据，一般在小程序 App 实例的 onShow 生命周期中调用；
第二个参数 options，必须， 需要传入返回的生命周期函数参数对象；
第三个参数 properties，非必须，要设置给预置事件 $MPShow 事件的自定义属性
appHide:string, 用来发送一条预置事件 $MPHide 数据，一般在小程序 App 实例的 onHide 生命周期中调用；
第二个参数 options，非必须， 要设置给预置事件 $MPHide 事件的自定义属性；
getAnonymousID:string, 用来获取匿名 ID;
3. 采集用户数据 API
3.1. setProfile( properties );
说明：设置用户的属性，如果存在则覆盖。
参数：
properties：object，必填，要给该用户设置的用户属性；
app.j
s
sa.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});3.2. setOnceProfile( properties );
说明：如果不存在同名属性则设置，存在同名属性，同名属性不会重新设置。
参数：
properties：object，必填，要给该用户设置的用户属性；
app.j
s
sa.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
3.3. incrementProfile( properties );
说明：增加或减少一个用户的某个 Numeric 类型的 Profile，如果该用户属性不存在则自动创建。
参数：
properties：object，必选。
app.j
s
sa.incrementProfile({
subscribers: 5
});
3.4. appendProfile( properties );
说明：向某个用户的某个数组类型的 Profile 添加一个或者多个值。
参数：
properties：object，必选。
app.j
s
sa.appendProfile({
favoriteFruits: ['''', '''']
});
4. 其他 API
4.1. identify( ''anonymousID'', [boolean]);
说明：用来修改当前小程序访问用户的匿名 ID;
参数：
anonymousID: String ,要使用的匿名 ID;
boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到微信 storage 中；不填或者设置为 false，表示该匿名 ID 只在小游戏本次生命周
期中有效，下次冷启动后使用的仍然时修改之前的匿名 ID;
4.2. getPresetProperties();
说明：用来获取部分预置属性；
4.3. clearAllRegister();
说明：用来清除存储在 storage 中的公共属性；
4.4. logout( [boolean])
说明：用来将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;
参数：
boolean: Boolean, 不填, 表示将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID；设置为 true，表示将当前的 Distinct ID 切换
为一个重新生成的 UUID；自定义埋点版.自定义埋点版 SDK 集成 v1.13
1. 自定义埋点版微信小程序 SDK 说明
全埋点版本的微信小程序 SDK 是通过代理小程序的 App 和 Page 方法实现的自动采集，但是因为代理这两个方法存在风险，另外可能某些用户不
需要自动采集，这时候就强烈建议使用自定义采集的方法；
自定义埋点版微信小程序 SDK 提供了 quick() 方法来采集 $MPLaunch $MPShow $MPHide 三个预置事件，效果跟全埋点版本一致；
自定义埋点版微信小程序 SDK 目前不能通过 quick() 方法来采集 $MPViewScreen $MPShare $MPClick 这三个预置事件；
2. 快速使用
2.1. 集成与使用
2.1.1. 下载文件
从 GitHub 上下载自定义埋点版微信小程序 SDK，sensorsdata.custom.min.js ；
2.1.2. 引入 SDK 、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
调用 setPara() 方法设置初始化参数，必须在 require() 之后，立即调用 setPara() 方法设置；
调用 init() 方法标志已完成初始化；
在 app.js 中设置一个全局变量，如：sensors，以便在其他页面逻辑 js 文件中通过该全局变量调用 SDK 接口；
注意：init() 方法必须调用，否则不会发数据。
app.j
s
var sa= require(''./utils/sensorsdata.custom.min.js'');
sa.setPara({
server_url: ''''
});
App({
onLaunch : function( options ){
//
this.sensors = sa;
}
});
2.1.3. 开启全埋点
在小程序指定的生命周期回调中通过调用 quick() 接口开启全埋点，采集预置事件；
app.j
s
var sa = require(''./utils/sensorsdata.custom.min.js'');
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'', options,{
ProductCatalog: "Laptop Computer"
});
},
onHide : function(){
// quick() appHide, $MPHide
sa.quick(''appHide'',{ProductName: "MacBook Pro"
});
}
});
2.1.4. 自定义事件采集
在其他页面逻辑 js 文件中通过 track() 方法来采集自定义事件数据；
index.js
// App
var app = getApp();
Page({
onShow: function(){
// 2.1.2. sensors track()
app.sensors.track(''pageView'',{
pagename: ''index''
})
}
});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，微信开发者工具 console 会打印采集的数据，json 格式；
微信开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在微信开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；插件版.插件版 SDK 集成 v1.13
1. 插件版微信小程序 SDK 说明
经过测试发现，如果小程序中使用了第三方插件且调试基础库版本在 2.6.4 以下时，App 和 Page 这两个全局变量是不可读的，这会导致全埋点版
微信小程序 SDK 不可用；基础库版本在 2.6.4 及以上这个问题就不存在了，全埋点版微信小程序 SDK 可以使用；针对使用了第三方插件且调试基
础库版本在 2.6.4 以下的这种情况，可以使用插件版小程序 SDK 。这个版本相比全埋点版微信小程序 SDK ，复杂处在于每个 Page 里的 JS 顶部
都要引入一段代码，才可以自动采集 Page 里的预置事件。
2. 快速使用
2.1. 集成与使用
2.1.1. 下载文件
从 Github 上下载插件版微信小程序 SDK，sensorsdata.plugin.min.js ；
2.1.2. 引入 SDK 、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
app.js 文件顶部声明 App 变量并赋值，其他 js 文件中声明 Page 变量并赋值用来采集预置事件；
调用 setPara() 方法设置初始化参数；
调用 init() 方法标志已完成初始化；
注意：App 和 Page 变量名不能修改；
app.j
s
var sa = require(''./utils/sensorsdata.plugin.min.js'');
var App = sa.App;
sa.setPara({
name: ''sensors'',
server_url: ''''
});
sa.init();
在全部（注意是全部！）的 pages 目录里的 js 顶部引入如下代码
index.js
var Page = getApp().sensors.Page;
2.1.3. 自定义事件采集
在其他页面逻辑 js 文件中通过调用 track() 接口来采集自定义事件；
index.js
var app = getApp();
var Page = app.sensors.Page;
app.sensors.track(''addToCart'',{
productName:'' 9S''
});
Page({});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，微信开发者工具 console 会打印采集的数据，json 格式；微信开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在微信开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；.插件版 SDK 集成 v1.17
1. 插件版微信小程序 SDK 说明
经过测试发现，如果小程序中使用了第三方插件且调试基础库版本在 2.6.4 以下时，App 和 Page 这两个全局变量是不可读的，这会导致全埋点版
微信小程序 SDK 不可用；基础库版本在 2.6.4 及以上这个问题就不存在了，全埋点版微信小程序 SDK 可以使用；针对使用了第三方插件且调试基
础库版本在 2.6.4 以下的这种情况，可以使用插件版小程序 SDK 。这个版本相比全埋点版微信小程序 SDK ，复杂处在于每个 Page 里的 JS 顶部
都要引入一段代码，才可以自动采集 Page 里的预置事件。
2. 快速使用
2.1. 集成与使用
2.1.1. 下载文件
从 Github 上下载插件版微信小程序 SDK，sensorsdata.plugin.min.js ；
2.1.2. 引入 SDK 、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
app.js 文件顶部声明 App 变量并赋值，其他 js 文件中声明 Page 变量并赋值用来采集预置事件；
调用 setPara() 方法设置初始化参数；
调用 init() 方法标志已完成初始化；
注意：App 和 Page 变量名不能修改；
app.j
s
var sa = require(''./utils/sensorsdata.plugin.min.js'');
var App = sa.App;
sa.setPara({
name: ''sensors'',
server_url: ''''
});
sa.init();
在全部（注意是全部！）的 pages 目录里的 js 顶部引入如下代码
index.js
var Page = getApp().sensors.Page;
2.1.3. 自定义事件采集
在其他页面逻辑 js 文件中通过调用 track() 接口来采集自定义事件；
index.js
var app = getApp();
var Page = app.sensors.Page;
app.sensors.track(''addToCart'',{
productName:'' 9S''
});
Page({});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，微信开发者工具 console 会打印采集的数据，json 格式；微信开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在微信开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；历史版本（已废弃）.历史版本（已废弃） v1.13
在使用前，请先阅读数据模型的介绍。
1. 获取和引入神策分析 SDK
1.1. 下载 sdk
从 github 上下载 微信小程序 sdk ，sensorsdata.min.js 和 sensorsdata_conf.js
把这两个文件放在小程序的 utils 目录下，然后在 app.js 第一行添加以下代码
var sensors = require(''./utils/sensorsdata.min.js'');
sensors.init();
现在在其他 Page 里就可以通过 getApp 来使用神策的追踪了
var app = getApp();
app.sensors.track(eventName, properties) //
1.2. sensorsdata_conf.js 参数配置
name: SDK 使用的一个默认的全局变量,会注册在 App 全局函数内，在 Page 中可以通过 app[name].track 来使用，默认值是 sensors 。
appid: (非必填参数)如果需要自动获取 openid ，需要在神策后端配置 appid 和 appsecret ，同时在这里指定 appid 。
server_url: 数据接收地址, 注意: 请在微信开发设置，服务器域名的 request 合法域名内，把这个地址加上。
send_timeout: 请求发送超时时间（如果一个请求发送后，超过规定时间没响应，则继续发送下一条数据），默认为 1000 毫秒。
use_client_time: 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端时间，使用服务端时间，
如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date 类型，那么这条数据就会使用你在属
性中传入的这个时间。
autoTrack: 是否开启自动采集，五个参数的值默认为 true，即采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare
（0.9以上版本的 SDK 支持，其中 $MPShare 事件1.9版本以上支持，详细介绍见本页第四点）。
show_log: 设置 true 后会在模拟器控制台打 logger，会显示发送的数据,设置 false 表示不显示。默认为 true 。
allow_amend_share_path: 设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性，新增一些参数包括当前用户的 distinct_id 等，
如果要自动采集分享，必须设置为 true 。
is_plugin: 小程序中是否使用了插件,默认为 false 。小程序中如果使用了插件，该参数必须设置为 true 。
batch_send: 小程序中是否使用批量发送数据功能,默认为 false ,配置注意事项详见常见问题 9.7。
datasend_timeout: 请求发送取消时间（请求发送后，在规定时间内未返回结果，则取消请求），默认为 1000 毫秒（1.12.9 及以上版本支持） 。
1.3. mpvue 小程序框架集成 SDK
1.3.1. 集成与初始化
第一步：从 github 上下载 微信小程序 sdk ，sensorsdata.js 和 sensorsdata_conf.js （其中未压缩的 sensorsdata.js 文件请联系神策值班同学获取）
第二步：将 sensorsdata_conf.js 中的导出方式代码 `module.exports = conf;` 修改为 ·export { conf };`
第三步：修改 sensorsdata.js ,将 `sa.para = require(''sensorsdata_conf.js'');` 修改为 `import { conf } from ''./sensorsdata_conf''; sa.para = conf;odule.
exports = sa;` 修改为 `export { sa };
第四步：将修改好的文件放到小程序项目的 utils 目录下
第五步：在项目的 main.js 中引入 SDK，sensorsdata.min.js 必须在 vue 之前引入,然后初始化
import { sa } from ''./utils/sensorsdata''
import Vue from ''vue''
import App from ''./App''
sa.init();
1.3.2. Page 中追踪自定义事件
const app = getApp()
export default {
data ()
{ return
{}
},
methods: {eventSend(){ app.sensors
.track('''',{
''1'' : ''1'',
''2'' : ''2'',
''...'' : ''...''
})
}
}
}
1.4. wepy 小程序框架集成 SDK
第一步：通过 `npm i sa-sdk-miniprogram` 集成 SDK
第二步：修改 src 目录下的 app.wpy，在 app.wpy 中引入 SDK
import sa from ''sa-sdk-miniprogram''
import wepy from ''wepy''
import ''wepy-async-function''
import { setStore } from ''wepy-redux''
import configStore from ''./store''
sa.init()
2. 用户标识
相关文档链接
在进行任何埋点之前，都应当先确定如何标识用户。distinct_id 是神策用来标识用户的一段唯一的字符串。
在小程序中，会有下面 3 种 id
1. 默认情况下，我们会生成一个随机数 uuid ，保存在 weixin storage 中，我们暂时称这个为 uuid
2. 用户打开小程序，我们可以获得用户的 weixin openid ，我们暂时称这个为 openid
3. 客户用户账号体系中产生或保存的真实用户 id 。我们暂时称为 "你们服务端分配给用户具体的登录 ID"
2.1. 使用 openid
如果不做任何操作，小程序会使用 uuid 作为 distinct_id ，但是这个 uuid 换了设备，或者删除小程序，会重新生成。 所以一般情况下，我们建议使用
openid 作为当前的 distinct_id。 因为获取 openid 是一个异步的操作，但是冷启动事件等会先发生，这时候这个冷启动事件的 distinct_id 就不对了。所
以我们会把先发生的操作，暂存起来，等获取到 openid 后再调用 sensors.init() 才会发数据。 下面是常见的两种获取 openid 的初始化代码。
-------app.js
var sensors = require(''sensorsdata.min.js'');
// openid
sensors.setOpenid(openid);
sensors.init();
-------app.js
var sensors = require(''sensorsdata.min.js'');
// appid appsecret sensorsdata_conf appid
sensors.initWithOpenid();
2.2. 匿名 ID 和用户 ID 关联
默认情况下 ，SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login 方法，传入对应的用户 ID ；匿名 ID 会与对应的用户 ID 进行
关联，关联成功之后视为同一个用户。 调用时机：注册成功、登录成功 、初始化 SDK（如果能获取到用户 ID）都需要调用 login 方法传入用户 ID。
-------app.js
var sensors = require(''sensorsdata.min.js'');// " ID"
sensors.login(" ID");
sensors.init();
3. 自定义事件追踪
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
电商产品，可以追踪用户注册、浏览商品和下订单等事件。
//
var app = getApp();
app.sensors.track(''ViewProduct'', {
ProductId: ''123456'',
ProductCatalog: "Laptop Computer",
ProductName: "MacBook Pro",
ProductPrice: 12345
});
事件公共属性：可以在 app.js 文件引入 sensorsdata.min.js 文件之后， init() 方法调用之前使用 registerApp() 方法设置公共属性。例如：
//
var sensors = require(''sensorsdata.min.js'');
sensors.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
sensors.init();
4. 预置事件
4.1. 预置事件追踪
为了方便使用， 0.9 版本以上的小程序 SDK 已经可以自动追踪微信小程序中的冷启动，热启动，进入后台，页面浏览事件。
事件名称 相应小程序生命周期 触发时机 说明
$MPLaunch App.onLaunch 小程序进程被杀死，重新打开时会触发 小程序初始化完成时，全局只触发一次
$MPShow App.onShow 小程序启动，或从后台进入前台显示 启动小程序时
$MPHide App.onHide 点击小程序右上角退出按钮、微信进入后台、进入小程序关于页面、手机锁 小程序从前台进入后台
屏、小程序进程被杀死时
$MPViewScreen Page.onShow 小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时触发 每次打开页面都会调用一次
$MPShare Page. 设置这个函数后，点击分享按钮触发 暂时只能获取到用户触发分享，无法监
onShareAppMessage 听是否分享成功的反馈
例如：在 sensorsdata_conf.js 中添加下面参数，开启 autoTrack 自动采集
autoTrack:{
appLaunch:true, // $MPLaunch true
appShow:true, // $MPShow true
appHide:true, // $MPHide true
pageShow:true, // $MPViewScreen true
pageShare:true // $MPShare true
}
4.2. 预置事件自定义属性
用户可以在预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen 等中通过 getApp().sensors.para.autoTrack[param] = value 添加自定义属性，
其中param 为 appLaunch, appShow, appHide, pageShow 等；
value 为对象或返回值是对象的函数；例如：
app.j
s
// $MPLaunch appId,query,extraData
var sa = require(''./utils/sensorsdata.min.js'');
App({
onLaunch: function (data)
{ sa.para.autoTrack.appLaunch
={
appId:data.referrerInfo.appId,
query:data.query,
extraData:data.referrerInfo.extraData
}
}
})
//
var sa = require(''./utils/sensorsdata.min.js'');
App({
onLaunch: function (data)
{ sa.para.autoTrack.appLaunch=function(
){
return {
appId:data.referrerInfo.appId,
query:data.query,
extraData:data.referrerInfo.extraData
}
}
}
})
注意：该代码建议嵌入到相应js文件的顶部。
5. 渠道相关问题
5.1. utm 相关属性
在小程序冷启动 appLaunch 和热启动 appShow 还有页面打开 pageShow，我们会自动解析普通网页二维码的 utm 参数，解析 utm 相关的属性 作为这 3
个事件的属性
5.2. ### 5.2 $latest_utm 相关属性
在冷启动 appLaunch 里解析出来的 utm 值，会在小程序的生命周期内，用 $latest_utm 相关属性来一直保存着
在热启动 appShow 中如果有新的 utm 参数时， $latest_utm 值会覆盖
在下次重新冷启动的时候， $latest_utm 的值会重置，如果没有就不会有这个属性
5.3. 首次 utm 的相关属性
在小程序 sdk 发现设备之前没有加载过 sdk ，且如果冷启动 appLaunch 能解析到 utm 值时，会 setOnceProfile 来设置用户属性
5.4. 相关属性解析时机
参考小程序渠道追踪
6. 预置属性
6.1. 所有事件都有的预置属性：
字段说明 类型 说明 SDK 版本
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本$screen_height 数值 小程序屏幕高度
$screen_width 数值 小程序屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商 1.11.1 支持
$network_type 字符串 网络类型
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，
之后都为假，标识存在 storage 缓存中）
$ip 字符串 SDK 发送数据请求携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$latest_utm_source 字符串 最近一次付费广告系列来源（参考本章文档 5.1-5.4 的解释） 1.3 支持
$latest_utm_medium 字符串 最近一次付费广告系列媒介（参考本章文档 5.1-5.4 的解释） 1.3 支持
$latest_utm_term 字符串 最近一次付费广告系列字词（参考本章文档 5.1-5.4 的解释） 1.3 支持
$latest_utm_content 字符串 最近一次付费广告系列内容（参考本章文档 5.1-5.4 的解释） 1.3 支持
$latest_utm_campa 字符串 最近一次付费广告系列名称（参考本章文档 5.1-5.4 的解释） 1.3 支持
ign
$latest_scene 字符串 最近一次启动场景值 1.9 支持
6.1.1. UserAgent 相关的预置属性
这一系列的属性从浏览器的 UserAgent 中进行解析。
字段名称 类型 说明 SDK 版本
$bot_name 字符串 爬虫名称（如果是爬虫）
注意：
1. $screen_height 在 1.11.1 版本之前字段名称为‘小程序窗口高度’,取的值是小程序可使用窗口高度
2. $screen_width 在 1.11.1 版本之前字段名称为‘小程序窗口宽度’,取的值是小程序可使用窗口宽度
3. wx.getSystemInfo 微信小程序提供的接口获取系统信息。
6.2. $MPLaunch （小程序启动）事件的预置属性
字段名称 类型 说明 SDK 版本
$scene 字符串 启动场景 1.0以上
$url_path 字符串 页面路径
$utm_source 字符串 广告系列来源（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_medium 字符串 广告系列媒介（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_term 字符串 广告系列字词（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_content 字符串 广告系列内容（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_campaign 字符串 广告系列名称（参考本章文档 5.1-5.4 的解释） 0.9以上
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真 1.8以上
$share_distinct_id 字符串 分享时的 distinct_id 1.9以上
$share_depth 数值 分享次数 1.9以上
$share_url_path 字符串 分享时的页面路径 1.9以上
$url_query 字符串 页面参数 1.10.4以上
其中场景值的概念及取值可以参考微信小程序的官方介绍场景值
6.3. $MPShow （小程序显示）事件的预置属性字段名称 类型 说明 SDK 版本
$scene 字符串 启动场景 1.0以上
$url_path 字符串 页面路径
$utm_source 字符串 广告系列来源（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_medium 字符串 广告系列媒介（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_term 字符串 广告系列字词（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_content 字符串 广告系列内容（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_campaign 字符串 广告系列名称（参考本章文档 5.1-5.4 的解释） 0.9以上
$share_distinct_id 字符串 分享时的 distinct_id 1.9以上
$share_depth 数值 分享次数 1.9以上
$share_url_path 字符串 分享时的页面路径 1.9以上
$url_query 字符串 页面参数 1.10.4以上
6.4. $MPHide （小程序进入后台）事件的预置属性
字段名称 类型 说明 版本
event_duration NUMBER 从本次小程序显示 $MPShow 到 $MPHide 小程序进入后台或者关闭的时间 1.1及以上
$url_path 字符串 页面路径 1.5及以上
6.5. $MPViewScreen （小程序页面浏览）事件的预置属性
字段名称 类型 说明 SDK 版本
$url_path 字符串 页面路径 0.9版本之前为 $url
$referrer 字符串 前向页面地址 0.9以上
$utm_source 字符串 广告系列来源（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_medium 字符串 广告系列媒介（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_term 字符串 广告系列字词（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_content 字符串 广告系列内容（参考本章文档 5.1-5.4 的解释） 0.9以上
$utm_campaign 字符串 广告系列名称（参考本章文档 5.1-5.4 的解释） 0.9以上
$url_query 字符串 页面参数，比如小程序页面路径为 page/index/index?ceshi=bar，那么页面参数为 ceshi=bar 1.10.4以上
6.6. $MPShare （小程序分享）事件的预置属性：
字段名称 类型 说明 SDK 版本
$share_depth 数值 分享次数 1.9以上
$url_path 字符串 分享时的页面路径 1.9以上
6.7. 预置的用户属性
字段名称 类型 说明 SDK 版本
$first_visit_time Datetime 首次访问时间，新用户第一次来到嵌有神策 SDK 微信小程序的客户端时间 1.12.9 及以上版本
$utm_source 字符串 首次广告系列来源 （参考本章文档 5.3 的解释） 1.0 及以上版本
$utm_medium 字符串 首次广告系列媒介 （参考本章文档 5.3 的解释） 1.0 及以上版本
$utm_term 字符串 首次广告系列字词 （参考本章文档 5.3 的解释） 1.0 及以上版本
$utm_content 字符串 首次广告系列内容 （参考本章文档 5.3 的解释） 1.0 及以上版本
$utm_campaign 字符串 首次广告系列名称 （参考本章文档 5.3 的解释） 1.0 及以上版本7. 设置用户属性
7.1. sensors.setProfile(properties)
直接设置用户的属性，如果存在则覆盖。
properties：`object`，必选。
sensors.setProfile({email:''xxx@xx''});
7.2. sensors.setOnceProfile(properties)
如果不存在则设置，存在就不设置。
properties：`object`，必选。
sensors.setOnceProfile({email:''xxx@xx''});
8. 实际案例使用
先把下载下来的 sensorsdata.min.js 和 sensorsdata_conf.js 放在根目录 untils 目录下
8.1. 在根目录的 app.js 中加入
app.j
s
//
var sensors = require(''./utils/sensorsdata.min.js'');
App({
onLaunch: function () {
// id
sensors.login(userid);
// , profile
sensors.setProfile({name:''tiantian'',age:18});
}
});
8.2. 在 Pages 里的 js 中可以通过 getApp() 来获取 sensors
var app = getApp();
// clickImage
Page({
bindTapImage: function(){
app.sensors.track(''clickImage'',{name:''''});
},
onLoad: function(){
}
});
9. 常见问题
9.1. 小程序中服务器域名设置
小程序 server_url (数据接收地址)需要在微信公众平台---开发---开发设置—服务器域名中配置小
程序中服务器域名必须使用 https 协议。9.2. 获取预置属性
在根目录的 app.js 中使用该方法
var sensors = require(''./utils/sensorsdata.min.js'');
sensors.getPresetProperties();
此方法可获取 SDK 版本、操作系统、操作系统版本、设备型号、网络类型、屏幕宽高、页面路径、最近一次渠道来源的相关属性。需要在获取完网络状态与
设备信息、页面加载完成后调用此方法。
9.3. 小程序分享的计算逻辑和规则
在 SDK 1.9版本加入了小程序的分享事件 $MPShare ，该事件在小程序中调用分享接口时触发。
$url_path 属性值会记录触发分享的页面地址。
$share_depth 属性值会记录分享的层级：A、B、C为三个不同的用户，若小程序一个页面依照 A -> B -> C 的顺序进行分享，则 A 的分享会被标记为1级
分享，B 触发的分享会被标记为2级，C 则为3级分享。
其中，用户打开自己分享的页面是不会增加 $share_depth 的值。
若您希望在后续跟踪分享的效果，需要配置 allow_amend_share_path 为true，这样神策会自动修改分享的path参数，path后面会新增参数包含
distinct_id，分享次数，页面路径信息。在该分享页面被打开时，会自动解析到 $MPLaunch 和 $MPShow 中。
9.4. 不覆盖 App 与 Page
SDK 1.9.5 版本以后，客户可以通过配置 sensorsdata_conf.js 文件中 autoTrack:false， 使 SDK 不再覆盖小程序原生的 App 和 Page 方法。
使用该配置后，小程序 SDK 不再采集预置事件，不能使用神策提供的小程序渠道追踪。
9.5. 通过 init 方法配置初始化参数
SDK 1.9.9 版本支持通过 sensors.init(para) 方法修改 sensorsdata_conf.js 中的配置参数
sensors.init({
// APP app.js getApp().sensors()
name: ''sensors'',
// sdk openid appid appsecret appid,
appid: '''',
//
server_url: '''',
//
send_timeout: 1000,
//
use_client_time: false,
//
show_log: true,
// onShareMessage return path id path app onshow
allow_amend_share_path : true,
//
autoTrack:{appLaunch:true, // $MPLaunch true
appShow:true, // $MPShow true
appHide:true, // $MPHide true
pageShow:true, // $MPViewScreen true
pageShare:true // $MPShare true
}
})
注意：
对于使用 wepy 框架开发的小程序，需要使用按照下面步骤操作
1. 通过 ```npm i sa-sdk-miniprogram```集成 SDK
2. 使用```wepy build --no-cache```重新编译
9.6. 获取 distinct_id
var sensors = require(''./utils/sensorsdata.min.js'');
sensors.init();
sensors.store.getDistinctId()
9.7. 批量发送数据配置
1. 可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次；
2. 可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 };
3. 批量发送可能存在重复发数据的问题，因为关闭小程序的时候，我们会默认发一次数据，可能数据没返回，下次会重发，所以这个版本含有默认去
重的功能，使用这个功能必须升级神策分析系统到 1.11 及以上版本，已经是 1.11 版本以上的系统也需要小版本升级；
4. 批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用
等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上。
9.8. 预置事件添加自定义属性配置
1. 如果是添加不需要延迟获取的属性，可以参考文档 [4.2](#42-预置事件自定义属性) 描述的方案添加。
2. 如果是需要延迟才能获取的属性，首先需要关闭 autoTrack 对应的预置事件，然后手动去发送。
如果不需要我们的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）
如果需要我们的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen 设置自定义属性不支持这种方案 ）
app.js
//
var sensors = require(''./utils/sensorsdata.min.js'');
sensors.init()
App({
onLaunch : function(options){
// $MPLaunch
sensors.quick(''appLaunch'', options, {
'''' : ''''
});
},
onShow : function(options){
// $MPShow
sensors.quick(''appShow'', options,
{ '''' : ''''
});
},
onHide : function(){
// $MPHide
sensors.quick(''appHide'', {
'''' : ''''
});
}
});支付宝小程序 SDK.支付宝小程序 SDK v1.13
自定义埋点版集成
全埋点版集成
支付宝小程序 API
1.1. 自定义埋点版支付宝小程序 SDK
自定义埋点版支付宝小程序 SDK 提供了在 App 的 onLaunch、 onShow、 onHide 生命周期函数中调用 quick() 接口的方法来采集
$MPLaunch、 $MPShow、 $MPHide 三个预置事件，通过此方法采集的预置事件会带有相应的预置属性；
1.2. 全埋点版支付宝小程序 SDK
全埋点版支付宝小程序 SDK 通过使用 SDK 提供的 $global.saAlipay.App() 方法替换原生 App() 方法构造小程序实例，每个页面使用 $global.
saAlipay.Page() 方法替换原生 Page() 方法构造页面来实现全埋点；自定义埋点版集成.自定义埋点版集成 v1.13
在使用前，请先阅读数据模型的介绍。
更新日志
1. 概述
支付宝小程序 SDK 通用于蚂蚁开放生态，可以相同引入方法应用于淘宝、钉钉、高德等应用平台，可参考多端支持；
2. 自定义埋点版支付宝小程序 SDK 说明
自定义埋点版支付宝小程序 SDK 可以采集 $MPLaunch、 $MPShow、 $MPHide 三个预置事件；
自定义埋点版支付宝小程序 SDK 目前不支持 $MPViewScreen、 $MPShare、 $MPClick 这三个预置事件的采集；
自定义埋点版支付宝小程序 SDK 提供了在 App 的 onLaunch、 onShow、 onHide 生命周期函数中调用 quick() 接口的方法来采集
$MPLaunch、 $MPShow、 $MPHide 三个预置事件，通过此方法采集的预置事件会带有相应的预置属性；
3. 快速使用
3.1. 集成与使用
3.1.1. 下载 SDK
从 GitHub 上下载自定义埋点版支付宝小程序 SDK，sensorsdata.custom.min.js ；
3.1.2. 引入、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件；
通过 setPara() 设置初始化参数；
调用 init() 方法标志已完成初始化；
在 app.js 中设置一个全局变量，如：sensors，以便在其他页面逻辑 js 文件中通过该全局变量调用 SDK 接口；
注意：init() 方法必须调用，否则不会发数据。
app.j
s
// sensorsdata.custom.min.js
var sa = require(''./sdk/sensorsdata.custom.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch : function(){
//
this.sensors = sa
}
})
3.1.3. 开启全埋点
在小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点，采集预置事件；
app.j
s
var sa = require(''./sdk/sensorsdata.custom.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'', options,{
ProductCatalog: "Laptop Computer"
});
},
onHide : function(){
// quick() appHide, $MPHide
sa.quick(''appHide'',{
ProductName: "MacBook Pro"
});
}
});
3.1.4. 自定义事件采集
在其他页面逻辑 js 文件中通过 track() 方法来采集自定义事件数据；
index.js
// App
var app = getApp();
Page({
onShow: function(){
// 3.1.2. sensors track()
app.sensors.track(''pageView'',{
pagename: ''index''
})
}
});
3.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点后，小程序开发者工具 console 会打印采集的数据，json 格式；
小程序开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在小程序开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据。
4. 标识用户
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中，会有下面 3 种 ID 作为 Distinct ID:
1. 默认情况下，支付宝小程序 SDK 会生成一个唯一的随机数，保存在 storage 中，我们称这个为 UUID;
2. 用户打开小程序，支付宝为访问小程序用户分配的 userId,称这个为支付宝用户的唯一 userId;
3. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
4.1. 使用支付宝用户的唯一 userId 作为匿名 ID
如果不做任何操作，小程序会使用 UUID 作为 Distinct ID，但是这个 UUID 换了设备，或者删除小程序后，会重新生成。所以一般情况下，我们建议使用支付
宝用户的唯一 userId 作为当前的 Distinct ID。
下面是常见的使用支付宝用户的唯一 userId 作为匿名 ID 的初始化代码。app.j
s
var sa = require(''./sdk/sensorsdata.custom.min.js'')
sa.setPara({
server_url: ''''
});
my.request({
// userId
url: ''https://api.avatardata.cn/Account/Info?key=c1bba87504fc4a6fbf0281e2617d9e58'',
method: ''GET'',
success: function(res) {
// identify() ID userId
sa.identify(res.data.result.login_name, true);
},
complete: function(res) {
// UUID ID
sa.init();
}
});
App({
onLaunch:
function( options ){ this.sens
ors = sa;
sa.quick(''appLaunch'', options)
}
});
注意：init 不调用就不会发任何数据，确保无 openid 的时候也有 init 方法可执行
4.2. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID( UUID ) 来标识用户。当用户注册或登录成功时，调用 login() 方法，传入对应的用户 ID;匿名 ID 会与对应的用户 ID
进行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK （如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
app.j
s
var sa = require(''./sdk/sensorsdata.custom.min.js'');
sa.setPara({
name: ''sensors'',
server_url: ''''
});
/**
userId ID,
**/
my.request({
// userId
url: ''https://api.avatardata.cn/Account/Info?key=c1bba87504fc4a6fbf0281e2617d9e58'',
method: ''GET'',
success: function(res) {
// identify() ID userId
sa.identify(res.data.result.login_name, true);
//
my.getStorage({
key: ''registerInfo'',
success: function(res) {
if(res.data){
// login()
sa.login(res.data.userID);
}
}
});
},
complete: function(res)
{ sa.init();}
});
/**
UUID ID,
**/
//
my.getStorage({
key: ''registerInfo'',
success: function(res) {
if(res.data){
// login()
sa.login(res.data.userID);
}
},
complete(){
sa.init();
}
});
App({
onLaunch:
function( options ){ this.sens
ors = sa;
sa.quick(''appLaunch'', options)
}
});
5. 预置事件
小程序支持采集 $MPLaunch、$MPShow、$MPHide 这三个预置事件。
事件名称 相应小程 触发时机 说明
序生命周
期
$MPLaunch（小 App. 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 sa.quick( ''appLaunch'', options ) 时会 小程序初始化完成时，
程序启动） onLaunch 触发 全局只触发一次
$MPShow（小程 App.onShow 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick( ''appShow'', options ) 启动小程序时
序显示） 时会触发
$MPHide（小程 App.onHide 点击小程序右上角退出按钮、支付宝进入后台、进入小程序关于页面、手机锁屏、小程序进程被杀死且在相 小程序从前台进入后台
序进入后台） 应小程序生命周期函数中调用了 sa.quick( ''appHide'' ) 时会触发时
app.j
s
var sa = require(''./sdk/sensorsdata.custom.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});
},
onHide : function(){
// quick() appHide,ProductName: "MacBook Pro"
});
}
});
6. 预置属性
所有事件都有的预置属性、预置事件有的预置属性以及预置采集的用户属性可以查看支付宝小程序 SDK 预置事件与预置属性文档；
7. 渠道追踪
用户通过含有 utm 相关参数的路径访问小程序时，预置事件 $MPLaunch、$MPShow 会解析启动路径中的 utm 相关参数作为自身的属性与属性值，
并会设置 $latest_utm 相关属性到所有事件中，在小程序的生命周期内有效。
当前支付宝小程序 SDK 并不支持解析除 utm 相关参数以外的其他自定义参数；
8. 相关文档
支付宝小程序 SDK 预置事件与预置属性；
小程序 SDK 常见问题；
支付宝小程序 API；全埋点版集成.全埋点版集成 v1.13
1. 全埋点版支付宝小程序 SDK 说明
全埋点版支付宝小程序 SDK 通过使用 SDK 提供的 $global.saAlipay.App() 方法替换原生 App() 方法构造小程序实例，每个页面使用 $global.
saAlipay.Page() 方法替换原生 Page() 方法构造页面来实现全埋点；
全埋点版支付宝小程序 SDK 可以采集 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、 $MPClick 五个预置事件；
2. 快速使用
2.1. 集成与使用
2.1.1. 下载
从 GitHub 上下载全埋点版支付宝小程序 SDK sensorsdata.autotrack.es6.min.js ；
2.1.2. 引入、配置参数并完成初始化
把文件放入支付宝小程序项目中，在 app.js 中通过 import 引入文件；
调用 setPara() 接口设置初始化参数，需保证该方法在 onLaunch 生命周期执行之前执行；
调用 init() 接口完成初始化；
注意：init() 方法必须调用，否则不会发数据。
// sensorsdata.autotrack.es6.min.js
import sa from ''sensorsdata.autotrack.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: '''',
// true
autoTrack:{
appLaunch: true, // $MPLaunch true false
appShow: true, // $MPShow true false
appHide: true, // $MPHide true false
pageShow: true, // $MPViewScreen true false
mpClick: true // $MPClick true false
}
})
sa.init();
2.1.3. 开启全埋点
在 app.js 中用 $global.saAlipay.App() 来代替 App() ；
在其他页面逻辑 js 文件中用 $global.saAlipay.Page() 来代替 Page()；
// sensorsdata.autotrack.es6.min.js
import sa from ''sensorsdata.autotrack.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: '''',
// true
autoTrack:{
appLaunch: true, // $MPLaunch true false
appShow: true, // $MPShow true false
appHide: true, // $MPHide true false
pageShow: true, // $MPViewScreen true false
mpClick: true // $MPClick true false
}
})
sa.init();
// $global.saAlipay.App App
$global.saAlipay.App({
});
// $global.saAlipay.Page Page
$global.saAlipay.Page({});
2.1.4. 自定义事件采集
在其他页面逻辑 js 文件中通过 track() 方法来采集自定义事件；
index.js
// App
var app = getApp();
$global.saAlipay.Page({
handleClick: function(){
// 2.1.2. sensors track()
app.sensors.track(''click'',{
pagename: ''index''
})
}
});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，小程序开发者工具 console 会打印采集的数据，json 格式；
小程序开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在小程序开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；
3. 标识用户
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中，会有下面 3 种 ID 作为 Distinct ID:
1. 默认情况下，支付宝小程序 SDK 会生成一个唯一的随机数，保存在 storage 中，我们称这个为 UUID;
2. 用户打开小程序，支付宝为访问小程序用户分配的 userId,称这个为支付宝用户的唯一 userId;
3. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
3.1. 使用支付宝用户的唯一 userId 作为匿名 ID
如果不做任何操作，小程序会使用 UUID 作为 Distinct ID，但是这个 UUID 换了设备，或者删除小程序后，会重新生成。所以一般情况下，我们建议使用支付
宝用户的唯一 userId 作为当前的 Distinct ID。
下面是常见的使用支付宝用户的唯一 userId 作为匿名 ID 的初始化代码。
app.j
s
// sensorsdata.autotrack.es6.min.js
import sa from ''sensorsdata.autotrack.es6.min.js''
sa.setPara({
server_url: '''',
name: ''sensors'',
// true
autoTrack:{
appLaunch: true, // $MPLaunch true
appShow: true, // $MPShow trueappHide: true, // $MPHide true
pageShow: true, // $MPViewScreen true
mpClick: true // $MPClick true
}
});
my.request({
// userId
url: ''https://api.avatardata.cn/Account/Info?key=c1bba87504fc4a6fbf0281e2617d9e58'',
method: ''GET'',
success: function(res) {
// identify() ID userId
sa.identify(res.data.result.login_name, true);
},
complete: function(res) {
// UUID ID
sa.init();
}
});
// $global.saAlipay.App App
$global.saAlipay.App({
onLaunch: function( options ){
}
});
注意：init 不调用就不会发任何数据，确保无 openid 的时候也有 init 方法可执行
3.2. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID( UUID ) 来标识用户。当用户注册或登录成功时，调用 login() 方法，传入对应的用户 ID;匿名 ID 会与对应的用户 ID
进行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK （如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
app.j
s
// sensorsdata.autotrack.es6.min.js
import sa from ''sensorsdata.autotrack.es6.min.js''
sa.setPara({
server_url: '''',
name: ''sensors'',
// true
autoTrack:{
appLaunch: true, // $MPLaunch true false
appShow: true, // $MPShow true false
appHide: true, // $MPHide true false
pageShow: true, // $MPViewScreen true false
mpClick: true // $MPClick true false
}
});
/**
userId ID,
**/
my.request({
// userId
url: ''https://api.avatardata.cn/Account/Info?key=c1bba87504fc4a6fbf0281e2617d9e58'',
method: ''GET'',
success: function(res) {
// identify() ID userId
sa.identify(res.data.result.login_name, true);
//
my.getStorage({
key: ''registerInfo'',
success: function(res) {
if(res.data){
// login()sa.login(res.data.userID);
}
}
});
},
complete: function(res)
{ sa.init();
}
});
/**
UUID ID,
**/
//
my.getStorage({
key: ''registerInfo'',
success: function(res) {
if(res.data){
// login()
sa.login(res.data.userID);
}
},
complete(){
sa.init();
}
});
// $global.saAlipay.App App
$global.saAlipay.App({
onLaunch: function( options ){
}
});
4. 预置事件
此版本小程序 SDK 支持采集 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPClick 这五个预置事件。
事件名称 相应小程序生命周 触发时机 说明
期
$MPLaunch（小程序启动） App.onLaunch 小程序进程被杀死，重新打开时会触发 小程序初始化完成时，全局只触发一次
$MPShow（小程序显示） App.onShow 小程序启动，或从后台进入前台显示 启动小程序时
$MPHide（小程序进入后台） App.onHide 小程序隐藏到后台时触发 小程序从前台进入后台
$MPViewScreen（小程序页面浏览） Page.onShow 小程序启动打开页面、小程序内打开页面、从后台进入前台
打开页面时触发
$MPClick（小程序元素点击） 小程序页面元素被点击时触发 被点击元素使用 onTap 或者
onLongTap 添加监听时才会采集
可以通过设置 setPara() 方法中的 autoTrack 参数，开启自动采集
app.j
s
// sensorsdata.autotrack.es6.min.js
import sa from ''sensorsdata.autotrack.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: '''',
// true
autoTrack:{
appLaunch: true, // $MPLaunch true false
appShow: true, // $MPShow true false
appHide: true, // $MPHide true false
pageShow: true, // $MPViewScreen true false
mpClick: true // $MPClick true false}
})
sa.init();
5. 预置属性
所有事件都有的预置属性、预置事件有的预置属性以及预置采集的用户属性可以查看支付宝小程序 SDK 预置事件与预置属性文档；
6. 渠道追踪
用户通过含有 utm 相关参数的路径访问小程序时，预置事件 $MPLaunch、$MPShow 会解析启动路径中的 utm 相关参数作为自身的属性与属性值，并会设置
$latest_utm 相关属性到所有事件中，在小程序的生命周期内有效。
7. 相关文档
支付宝小程序 SDK 预置事件与预置属性；
小程序 SDK 常见问题；
支付宝小程序 API；支付宝小程序 API.支付宝小程序 API v1.13
1. 采集事件数据 API
1.1. track( eventName,[properties] );
说明：采集自定义事件；
参数：
eventName：String， 必 填 ， 事 件 名 称 ； properties：
Object，选填，为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件；
index.js
//
var app = getApp();
app.sensors.track(''ViewProduct'', {
//String
ProductName: "MacBook Pro",
//Number -9E15 9E15 3
ProductPrice: 123.45,
//BOOL true false
IsAddedToFav: false
//List 500 UTF-8 255
ProductList:["apple","orange"],
//DATETIME new Date() yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss
ViewTime:new Date()
});
1.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 Distinct ID 不一致时，会触发 $SignUp 预置事件；
参数：
userID: string, 必填，用户 ID 或登录 ID ；
1.3. registerApp( properties );
说明：用来给所有事件设置公共属性，可以在 app.js 文件引入 sensorsdata.min.js 文件之后，使用 registerApp() 方法设置公共属性；
参数：
properties：Object，必填,为该方法调用后的所有事件设置的公共事件属性；
app.j
s
var sa = require(''sensorsdata.min.js'');
//
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
1.4. quick( [''appLaunch''|''appShow''|''appHide''], [options], [properties]);
说明：通过给定的第一个参数，分别实现不同的功能；
参数：
appLaunch:String, 用来发送一条预置事件 $MPLaunch 数据，一般在小程序 App 的 onLaunch 生命周期中调用；
第二个参数 options，必须， 需要传入相应的生命周期函数参数对象；
第三个参数 properties，非必须，可以传入要设置给预置事件 $MPLaunch 事件的自定义属性；
appShow:String, 用来发送一条预置事件 $MPShow 数据，一般在小程序 App 的 onShow 生命周期中调用；
第二个参数 options，必须， 需要传入相应的生命周期函数参数对象；
第三个参数 properties，非必须，要设置给预置事件 $MPShow 事件的自定义属性；
appHide:String, 用来发送一条预置事件 $MPHide 数据，一般在小程序 App 的 onHide 生命周期中调用；
第二个参数 options，非必须， 要设置给预置事件 $MPHide 事件的自定义属性；2. 采集用户数据 API
2.1. setProfile( properties );
说明：设置用户的属性，如果存在则覆盖；
参数：
properties：Object，必填，要给该用户设置的用户属性；
app.j
s
sa.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
2.2. setOnceProfile( properties );
说明：如果不存在同名属性则设置，存在同名属性，同名属性不会重新设置；
参数：
properties：Object，必填，要给该用户设置的用户属性；
app.j
s
sa.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
3. 其他 API
3.1. identify( anonymousID, [boolean]);
说明：用来修改当前小程序访问用户的匿名 ID；
参数：
anonymousID: String, 要使用的匿名 ID；
boolean: Boolean, 设置为 true，表示该匿名 ID 被保存到 storage 中；不填或者设置为 false, 表示该匿名 ID 在小程序本次生命周期中有
效，下次冷启动后使用的仍然是修改之前的匿名 ID；
3.2. clearAllRegister();
说明：用来清除存储在 storage 中的公共属性；
3.3. logout( [boolean])
说明：用来将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;
参数：
boolean: Boolean, 不填, 表示将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID；设置为 true，表示将当前的 Distinct ID 切换
为一个重新生成的 UUID；百度小程序 SDK.百度小程序 SDK v1.13
自定义版 SDK
全埋点版 SDK
1.1. 自定义埋点版百度小程序 SDK
自定义埋点版百度小程序 SDK 提供了在 App 的 onLaunch、 onShow、 onHide 生命周期函数中调用 quick() 接口的方法来采集 $MPLaunch、
$MPShow、 $MPHide 三个预置事件，通过此方法采集的预置事件会带有相应的预置属性；
1.2. 全埋点版百度小程序 SDK
全埋点版百度小程序 SDK 是基于百度小程序提供的 AOP 机制，在小程序 App 的 onLaunch、 onShow、 onHide 和 Page 的 onShow 生命周期
运行时，注入埋点逻辑，从而实现 $MPLaunch、$MPShow、 $MPHide、 $MPViewScreen 四个预置事件的采集；自定义版 SDK.自定义版 SDK v1.13
在使用前，请先阅读数据模型的介绍。
在使用前，可先了解数据校验的介绍。
更新日志
1. 自定义埋点版百度小程序 SDK 说明
自定义埋点版百度小程序 SDK 可以自动采集 $MPLaunch、 $MPShow、 $MPHide 三个预置事件；
自定义埋点版百度小程序 SDK 提供了在 App 的 onLaunch、 onShow、 onHide 生命周期函数中调用 quick() 接口的方法来采集 $MPLaunch、
$MPShow、 $MPHide 三个预置事件，通过此方法采集的预置事件会带有相应的预置属性；
自定义埋点版百度小程序 SDK 目前不支持 $MPViewScreen、 $MPClick 预置事件的采集；
2. 快速使用
2.1. 集成与使用
2.1.1. 下载 SDK
从 GitHub 上下载百度小程序 SDK，sensorsdata.min.js ;
2.1.2. 引入、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
调用 setPara() 接口配置初始化参数，如 server_url ；
调用 init() 方法标识初始化完成；注：不调用 init() 方法，数据会被缓存到内存中，无法通过网络发送出去；
在 App 函数中设置一个全局变量，如：sensors，以便在其他页面逻辑 js 文件中通过该全局变量调用 SDK 接口；
app.j
s
// sensorsdata.min.js
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch : function(){
//
this.sensors = sa
}
})
2.1.3. 开启全埋点
在小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点，采集预置事件；
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});
},
onHide : function(){
// quick() appHide,
sa.quick(''appHide'',{
ProductName: "MacBook Pro"
});
});
2.1.4. 自定义事件采集
在其他页面逻辑 js 文件中可以通过 track() 方法来采集自定义事件数据；
index.js
// App
var app = getApp();
Page({
onShow: function(){
// 1.1.2. sensors track()
app.sensors.track(''pageView'',{
pagename: ''index''
})
}
});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点后，百度开发者工具 console 会打印采集的数据，json 格式；
百度开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在百度开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；
3. 标识用户
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中，会有下面 2 种 ID 作为 Distinct ID:
1. 默认情况下，百度小程序 SDK 会生成一个唯一的随机数，保存在百度 storage 中，我们称这个为 UUID;
2. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
3.1. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID(UUID) 来标识用户。当用户注册或登录成功时，调用 login() 方法，传入对应的用户 ID;匿名 ID 会与对应的用户 ID 进
行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK （如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
app.j
svar sa = require(''./sdk/sensorsdata.min.js'')
/**
UUID ID,
**/
if(" ID"){
sa.login(" ID");
}
App({
onLaunch:
function( options ){ this.sens
ors = sa;
sa.quick(''appLaunch'', options)
}
});
4. 预置事件
小程序支持采集 $MPLaunch、$MPShow、$MPHide 这三个预置事件。
事件名称 相应小程 触发时机 说明
序生命周
期
$MPLaunch（小 App. 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 sa.quick( ''appLaunch'', options ) 时会 小程序初始化完成时，
程序启动） onLaunch 触发 全局只触发一次
$MPShow（小程 App.onShow 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick( ''appShow'', options ) 启动小程序时
序显示） 时会触发
$MPHide（小程 App.onHide 点击小程序右上角退出按钮、百度 App 进入后台、进入小程序关于页面、手机锁屏、小程序进程被杀死且在相 小程序从前台进入后台
序进入后台） 应小程序生命周期函数中调用了 sa.quick( ''appHide'' ) 时会触发时
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});
},
onHide : function(){
// quick() appHide,
sa.quick(''appHide'',{
ProductName: "MacBook Pro"
});
}
});
5. 常用 API
5.1. 采集事件数据 API5.1.1. track(eventName,[properties])
说明：采集自定义事件。
参数：
eventName: String，必填，事件名称；
properties: Object，选填,为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.js
var app = getApp();
app.sensors.track(''ViewProduct'', {
ProductId: ''123456'',
ProductCatalog: "Laptop Computer",
ProductName: "MacBook Pro",
ProductPrice: 12345
});
5.1.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 Distinct ID 不一致时，会触发 $SignUp 预置事件；
参数：
userID: String , 必填，用户 ID 或登录 ID;
5.1.3. registerApp(properties)
说明：可以在 app.js 文件引入 sensorsdata.min.js 文件之后， 使用 registerApp() 方法设置公共属性。
参数：
properties: Object，必填,要为该方法调用后的所有事件设置的公共事件属性；
app.j
s
//
var sa = require(''./sdk/sensorsdata.min.js'')
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
5.2. 采集用户数据 API
5.2.1. setProfile(properties)
说明：用来设置用户的属性，如果存在同名属性则覆盖。
参数：
properties: Object，必选，要设置的用户属性；
app.j
s
sensors.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
5.2.2. setOnceProfile(properties)
说明：用来设置用户的属性，如果不存在该属性则设置，存在同名属性不覆盖。
参数：
properties: Object，必选，要设置的用户属性；app.j
s
sensors.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
5.3. 其他 API
5.3.1. identify( anonymousID, [boolean]);
说明：用来修改访问当前小程序用户的匿名 ID;
参数：
anonymousID, String, 要使用的匿名 ID
boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到 QQ storage 中；不填或者设置为 false, 表示该匿名 ID 在小程序本次生命周期
中有效，下次冷启动后使用的仍然时修改之前的匿名 ID;
6. 预置属性
所有事件都有的预置属性、预置事件有的预置属性以及预置采集的用户属性可以查看百度小程序 SDK 预置事件与预置属性文档；
7. 渠道追踪
用户通过含有 utm 相关参数的路径访问小程序时，预置事件 $MPLaunch、$MPShow 会解析启动路径中的 utm 相关参数作为自身的属性与属性值，
并会设置 $latest_utm 相关属性到所有事件中，在小程序的生命周期内有效。
支持自定义小程序渠道参数；
8. 相关文档
百度小程序 SDK 预置事件和预置属性；
小程序 SDK 常见问题；全埋点版 SDK.全埋点版 SDK v1.13
1. 全埋点版百度小程序 SDK 说明
全埋点版百度小程序 SDK 会采集 $MPLaunch、$MPShow、 $MPHide、 $MPViewScreen、 $MPClick 五个预置事件；
全埋点版百度小程序 SDK 是基于百度小程序提供的 AOP 机制，在小程序 App 的 onLaunch、 onShow、 onHide 和 Page 的 onShow 生命周期
运行时，注入埋点逻辑，从而实现 $MPLaunch、$MPShow、 $MPHide、 $MPViewScreen 四个预置事件的采集；
全埋点版百度小程序 SDK 目前不支持使用 uni-app 框架开发的小程序；
2. 快速使用
2.1. 集成与使用
2.1.1. 下载
从 GitHub 上下载全埋点版百度小程序 SDK sensorsdata.autotrack.min.js
2.1.2. 引入 SDK 、配置参数并完成初始化
把文件放入百度小程序项目中，在 app.js 中通过 require() 引入文件；
调用 setPara() 接口设置初始化参数；
调用 init() 方法完成初始化；注：不调用 init() 方法，数据会被缓存到内存中，无法通过网络发送出去；
注：全埋点默认开启
// sensorsdata.autotrack.min.js
const sa = require(''./util/sensorsdata.autotrack.min.js'')
sa.setPara({
name: ''sensors'',
server_url: '''',
// true
autoTrack:{
appLaunch: true, // $MPLaunch true false
appShow: true, // $MPShow true false
appHide: true, // $MPHide true false
pageShow: true, // $MPViewScreen true false
mpClick: true // $MPClick true false
}
})
sa.init();
2.1.3. 自定义事件采集
其他页面逻辑 js 文件中可以通过 track() 方法来采集自定义事件数据
index.js
// App
var app = getApp();
Page({
handleClick: function(){
// 2.1.2. sensors track()
app.sensors.track(''click'',{
pagename: ''index''
})
}
});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，小程序开发者工具 console 会打印采集的数据，json 格式；小程序开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在小程序开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；
3. 预置事件
全埋点版本小程序 SDK 支持采集 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPClick 这五个预置事件。
事件名称 相应小程序 触发时机 说明
生命周期
$MPLaunch（小程序启 App.onLaunch 小程序进程被杀死，重新打开时会触发 小程序初始化完成时，全局只触发一次
动）
$MPShow（小程序显 App.onShow 小程序启动，或从后台进入前台显示 启动小程序时
示）
$MPHide（小程序进入 App.onHide 点击小程序右上角退出按钮、百度 App 进入后台、进入小程序关于页 小程序从前台进入后台
后台） 面、手机锁屏、小程序进程被杀死时
$MPViewScreen（小程 Page.onShow 小程序启动打开页面、小程序内打开页面、从后台进入前台打开页面时 每次打开页面都会调用一次
序页面浏览） 触发
$MPClick（小程序元素 小程序页面元素被点击时触发 被点击元素使用 bindtap/bindlongtap
点击） /bindlongpress 添加监听时才会采集
// sensorsdata.autotrack.min.js
const sa = require(''./util/sensorsdata.autotrack.min.js'')
sa.setPara({
name: ''sensors'',
server_url: '''',
//, false
autoTrack:{
appLaunch: true, // $MPLaunch true false
appShow: true, // $MPShow true false
appHide: true, // $MPHide true false
pageShow: true, // $MPViewScreen true false
mpClick: true // $MPClick true false
}
});
sa.init();
4. 预置属性
所有事件都有的预置属性与预置事件 $MPLaunch、 $MPShow、 $MPHide 有的预置属性可以查看百度小程序小程序 SDK 预置属性文档；
4.1. 预置事件有的预置属性
4.1.1. 预置事件 $MPClick 有的预置属性
字段名称 类型 说明
$element_id 字符串 元素 ID。默认是小程序随机生成的 id，如果设置了 id 属性，则是设置之后的值
$element_name 字符串 元素名字。元素需要设置 data-name 属性
$element_content 字符串 元素内容。元素需要设置 data-content 属性
$element_type 字符串 元素类型
$url_path 字符串 页面路径注意：表格中列出的属性表示，如果被点击的标签有这个属性，SDK 会自动采集；如果没有某个属性，那么这个属性的值为未知，但不影响此次点击事件的
采集，相关问题链接。
4.2. 预置用户属性
当用户首次访问集成了 SDK 的小程序时，百度小程序 SDK 会自动采集以下用户属性
字段名称 类型 说明
$utm_source 字符串 首次访问广告系列来源
$utm_medium 字符串 首次访问广告系列媒介
$utm_term 字符串 首次访问广告系列字词
$utm_content 字符串 首次访问广告系列内容
$utm_campaign 字符串 首次访问广告系列名称
$first_visit_time 日期 首次访问时间
5. 渠道追踪
1. 用户通过含有 utm 相关参数的路径访问小程序时，预置事件 $MPLaunch、$MPShow 会解析启动路径中的 utm 相关参数作为自身的属性与属性值，
并会设置 $latest_utm 相关属性到所有事件中，在程序的生命周期内有效；
2. 支持自定义渠道追踪；
6. 相关文档
1. 百度小程序 SDK 预置事件与预置属性文档；
2. 小程序 SDK 常见问题；字节跳动小程序 SDK.字节跳动小程序 SDK v1.13
在使用前，请先阅读数据模型的介绍。
在使用前，可先了解数据校验的介绍。
更新日志
1. 概述
字节跳动小程序 SDK 适用于今日头条/抖音/今日头条极速版/西瓜视频小程序，可以使用相同引入方法应用于各个应用平台，可参考多端支持；
2. 快速使用
2.1. 集成与使用
2.1.1. 下载 SDK
从 GitHub 上下载字节跳动小程序 SDK，sensorsdata.min.js ;
2.1.2. 引入、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
调用 setPara() 接口配置初始化参数，如 server_url ；
调用 init() 方法标识初始化完成；注：不调用 init() 方法，数据会被缓存到内存中，无法通过网络发送出去；
在 App 函数中设置一个全局变量，如：sensors，以便在其他页面逻辑 js 文件中通过该全局变量调用 SDK 接口；
app.j
s
// sensorsdata.min.js
var sa = require(''./sdk/sensorsdata.min.js'');
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch : function(){
//
this.sensors = sa
}
})
2.1.3. 开启全埋点
在小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点，采集预置事件；
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});},
onHide : function(){
// quick() appHide,
sa.quick(''appHide'',{
ProductName: "MacBook Pro"
});
}
});
2.1.4. 自定义事件采集
在其他页面逻辑 js 文件中可以通过 track() 方法来采集自定义事件数据；
index.js
// App
var app = getApp();
Page({
onShow: function(){
// 1.1.2. sensors track()
app.sensors.track(''pageView'',{
pagename: ''index''
})
}
});
2.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点后，字节跳动开发者工具 console 会打印采集的数据，json 格式；
字节跳动开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在字节跳动开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；
3. 标识用户
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中，会有下面 2 种 ID 作为 Distinct ID :
1. 默认情况下，百度小程序 SDK 会生成一个唯一的随机数，保存在百度 storage 中，我们称这个为 UUID;
2. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
3.1. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID(UUID) 来标识用户。当用户注册或登录成功时，调用 login() 方法，传入对应的用户 ID;匿名 ID 会与对应的用户 ID 进
行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK （如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();/**
UUID ID,
**/
if(" ID"){
sa.login(" ID");
}
App({
onLaunch:
function( options ){ this.sens
ors = sa;
sa.quick(''appLaunch'', options)
}
});
4. 预置事件
小程序支持采集 $MPLaunch、$MPShow、$MPHide 这三个预置事件。
事件名称 相应小程 触发时机 说明
序生命周
期
$MPLaunch（小 App. 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 sa.quick( ''appLaunch'', options ) 时会 小程序初始化完成时，
程序启动） onLaunch 触发 全局只触发一次
$MPShow（小程 App.onShow 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick( ''appShow'', options ) 启动小程序时
序显示） 时会触发
$MPHide（小程 App.onHide 点击小程序右上角退出按钮、相关 App 进入后台、进入小程序关于页面、手机锁屏、小程序进程被杀死且在相 小程序从前台进入后台
序进入后台） 应小程序生命周期函数中调用了 sa.quick( ''appHide'' ) 时会触发时
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});
},
onHide : function(){
// quick() appHide,
sa.quick(''appHide'',{
ProductName: "MacBook Pro"
});
}
});
5. 常用 API
5.1. 采集事件数据 API
5.1.1. track(eventName,[properties])说明：采集自定义事件。
参数：
eventName: String，必填，事件名称；
properties: Object，选填,为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.js
var app = getApp();
app.sensors.track(''ViewProduct'', {
ProductId: ''123456'',
ProductCatalog: "Laptop Computer",
ProductName: "MacBook Pro",
ProductPrice: 12345
});
5.1.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 Distinct ID 不一致时，会触发 $SignUp 预置事件；
参数：
userID: String , 必填，用户 ID 或登录 ID;
5.1.3. registerApp(properties)
说明：可以在 app.js 文件引入 sensorsdata.min.js 文件之后， 使用 registerApp() 方法设置公共属性。
参数：
properties: Object，必填,要为该方法调用后的所有事件设置的公共事件属性；
app.j
s
//
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
5.2. 采集用户数据 API
5.2.1. setProfile(properties)
说明：用来设置用户的属性，如果存在同名属性则覆盖。
参数：
properties: Object，必选，要设置的用户属性；
app.j
s
sensors.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
5.2.2. setOnceProfile(properties)
说明：用来设置用户的属性，如果不存在该属性则设置，存在同名属性不覆盖。
参数：
properties: Object，必选，要设置的用户属性；app.j
s
sensors.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
5.3. 其他 API
5.3.1. identify( anonymousID, [boolean]);
说明：用来修改访问当前小程序用户的匿名 ID;
参数：
anonymousID, String, 要使用的匿名 ID
boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到 QQ storage 中；不填或者设置为 false, 表示该匿名 ID 在小程序本次生命周期
中有效，下次冷启动后使用的仍然时修改之前的匿名 ID;
6. 预置属性
所有事件都有的预置属性、预置事件有的预置属性以及预置采集的用户属性可以查看字节跳动小程序 SDK 预置事件与预置属性文档；
7. 渠道追踪
用户通过含有 utm 相关参数的路径访问小程序时，预置事件 $MPLaunch、$MPShow 会解析启动路径中的 utm 相关参数作为自身的属性与属性值，
并会设置 $latest_utm 相关属性到所有事件中，在小程序的生命周期内有效。
支持自定义小程序渠道参数；
8. 相关文档链接
字节跳动小程序 SDK 预置事件与预置属性文档；
小程序 SDK 常见问题；QQ 小程序 SDK.QQ 小程序 SDK v1.13
在使用前，请先阅读数据模型的介绍。
更新日志
1. 快速使用
1.1. 集成与使用
1.1.1. 下载 SDK
从 GitHub 上下载 QQ 小程序 SDK，sensorsdata.min.js ;
1.1.2. 引入、配置参数并完成初始化
把文件放在小程序项目中，然后在 app.js 中通过 require() 引入文件 ；
调用 setPara() 方法设置初始化参数（必须在 require() 之后，立即调用 setPara() 方法设置）；
调用 init() 方法标识初始化完成；注：不调用 init() 方法，数据会被缓存到内存中，无法通过网络发送出去；
在 App 函数中设置一个全局变量，如：sensors，以便其他 js 文件中通过该全局变量调用 SDK 接口；
app.j
s
// sensorsdata.min.js
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch : function(){
//
this.sensors = sa
}
})
1.1.3. 开启全埋点
在小程序特定的生命周期回调中通过调用 quick() 接口开启全埋点，采集预置事件；
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});
},
onHide : function(){
// quick() appHide,
sa.quick(''appHide'',{
ProductName: "MacBook Pro"});
}
});
1.1.4. 自定义事件采集
在其他页面逻辑 js 文件中可以通过 track() 方法来采集自定义事件数据；
index.js
// App
var app = getApp();
Page({
onShow: function(){
// 1.1.2. sensors track()
app.sensors.track(''pageView'',{
pagename: ''index''
})
}
});
1.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点后，QQ 开发者工具 console 会打印采集的数据，json 格式；
QQ 开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在 QQ 开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据；
2. 标识用户
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小程序中，会有下面 2 种 ID 作为 Distinct ID :
1. 默认情况下，QQ 小程序 SDK 会生成一个唯一的随机数，保存在 QQ storage 中，我们称这个为 UUID;
2. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
2.1. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID(UUID) 来标识用户。当用户注册或登录成功时，调用 login() 方法，传入对应的用户 ID;匿名 ID 会与对应的用户 ID 进
行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK （如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
/**
UUID ID,
**/
if(" ID"){sa.login(" ID");
}
App({
onLaunch:
function( options ){ this.sens
ors = sa;
sa.quick(''appLaunch'', options)
}
});
3. 预置事件
小程序支持采集 $MPLaunch、$MPShow、$MPHide 这三个预置事件。
事件名称 相应小程 触发时机 说明
序生命周
期
$MPLaunch（小 App. 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 sa.quick( ''appLaunch'', options ) 时会 小程序初始化完成时，
程序启动） onLaunch 触发 全局只触发一次
$MPShow（小程 App.onShow 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick( ''appShow'', options 启动小程序时
序显示） ) 时会触发
$MPHide（小程 App.onHide 点击小程序右上角退出按钮、QQ 进入后台、进入小程序关于页面、手机锁屏、小程序进程被杀死且在相应小 小程序从前台进入后台
序进入后台） 程序生命周期函数中调用了 sa.quick( ''appHide'' ) 时会触发时
app.j
s
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
App({
onLaunch :
function( options ){ th
is.sensors = sa;
// quick() appLaunch, $MPLaunch,
sa.quick(''appLaunch'', options,{
ProductId: ''123456''
});
},
onShow : function( options ){
// quick() appShow, $MPShow,
sa.quick(''appShow'',
options,{ ProductCatalog: "Laptop
Computer"
});
},
onHide : function(){
// quick() appHide,
sa.quick(''appHide'',{
ProductName: "MacBook Pro"
});
}
});
4. 常用 API
4.1. 采集事件数据 API
4.1.1. track(eventName,[properties])
说明：采集自定义事件。
参数：
eventName: String，必填，事件名称；
properties: Object，选填,为该事件设置的事件属性；第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.js
var app = getApp();
app.sensors.track(''ViewProduct'', {
ProductId: ''123456'',
ProductCatalog: "Laptop Computer",
ProductName: "MacBook Pro",
ProductPrice: 12345
});
4.1.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 Distinct ID 不一致时，会触发 $SignUp 预置事件；
参数：
userID: String , 必填，用户 ID 或登录 ID;
4.1.3. registerApp(properties)
说明：可以在 app.js 文件引入 sensorsdata.min.js 文件之后， 使用 registerApp() 方法设置公共属性。
参数：
properties: Object，必填,要为该方法调用后的所有事件设置的公共事件属性；
app.j
s
//
var sa = require(''./sdk/sensorsdata.min.js'')
sa.setPara({
server_url: ''''
});
sa.init();
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
4.2. 采集用户数据 API
4.2.1. setProfile(properties)
说明：用来设置用户的属性，如果存在同名属性则覆盖。
参数：
properties: Object，必选，要设置的用户属性；
app.j
s
sensors.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
4.2.2. setOnceProfile(properties)
说明：用来设置用户的属性，如果不存在该属性则设置，存在同名属性不覆盖。
参数：
properties: Object，必选，要设置的用户属性；
app.j
ssensors.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
4.3. 其他 API
4.3.1. identify( anonymousID, [boolean]);
说明：用来修改访问当前小程序用户的匿名 ID;
参数：
anonymousID, String, 要使用的匿名 ID
boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到 QQ storage 中；不填或者设置为 false, 表示该匿名 ID 在小程序本次生命周期
中有效，下次冷启动后使用的仍然时修改之前的匿名 ID;
5. 预置属性
所有事件都有的预置属性、预置事件有的预置属性以及预置采集的用户属性可以查看 QQ 小程序 SDK 预置事件与预置属性文档；
6. 渠道追踪
用户通过含有 utm 相关参数的路径访问小程序时，预置事件 $MPLaunch、$MPShow 会解析启动路径中的 utm 相关参数作为自身的属性与属性值，并会设置
$latest_utm 相关属性到所有事件中，在小程序的生命周期内有效。
7. 相关文档
QQ 小程序 SDK 预置事件与预置属性；
小程序 SDK 常见问题；微信小程序 SDK 预置属性.小程序 SDK 预置属性 v1.13
1. 所有事件都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）采集的所有事件都有的预置属性；
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在 storage 中）
$is_login_id 布尔类型 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
2. 所有小程序 SDK 预置事件 $MPLaunch 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPLaunch 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真
3. 所有小程序 SDK 预置事件 $MPShow 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPShow 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
4. 所有小程序 SDK 预置事件 $MPHide 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPHide 预置事件采集的预置属性；字段名称 类型 说明
$event_duration 数值 从本次小程序显示 $MPShow 到 $MPHide 小程序进入后台或者关闭的时间
$url_path 字符串 页面路径
5. 相关文档链接
微信小程序 SDK 预置事件和预置属性；
支付宝小程序 SDK 预置事件和预置属性；
百度小程序 SDK 预置事件和预置属性；
字节跳动小程序 SDK 预置事件和预置属性；
QQ 小程序 SDK 预置事件和预置属性；.小程序 SDK 预置属性 v1.14
1. 所有事件都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）采集的所有事件都有的预置属性；
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在 storage 中）
$is_login_id 布尔类型 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
2. 所有小程序 SDK 预置事件 $MPLaunch 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPLaunch 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真
3. 所有小程序 SDK 预置事件 $MPShow 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPShow 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
4. 所有小程序 SDK 预置事件 $MPHide 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPHide 预置事件采集的预置属性；字段名称 类型 说明
$event_duration 数值 从本次小程序显示 $MPShow 到 $MPHide 小程序进入后台或者关闭的时间
$url_path 字符串 页面路径
5. 相关文档链接
微信小程序 SDK 预置事件和预置属性；
支付宝小程序 SDK 预置事件和预置属性；
百度小程序 SDK 预置事件和预置属性；
字节跳动小程序 SDK 预置事件和预置属性；
QQ 小程序 SDK 预置事件和预置属性；.小程序 SDK 预置属性 v1.15
1. 所有事件都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）采集的所有事件都有的预置属性；
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在 storage 中）
$is_login_id 布尔类型 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
2. 所有小程序 SDK 预置事件 $MPLaunch 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPLaunch 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真
3. 所有小程序 SDK 预置事件 $MPShow 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPShow 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
4. 所有小程序 SDK 预置事件 $MPHide 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPHide 预置事件采集的预置属性；字段名称 类型 说明
$event_duration 数值 从本次小程序显示 $MPShow 到 $MPHide 小程序进入后台或者关闭的时间
$url_path 字符串 页面路径
5. 相关文档链接
微信小程序 SDK 预置事件和预置属性；
支付宝小程序 SDK 预置事件和预置属性；
百度小程序 SDK 预置事件和预置属性；
字节跳动小程序 SDK 预置事件和预置属性；
QQ 小程序 SDK 预置事件和预置属性；.小程序 SDK 预置属性 v1.16
1. 所有事件都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）采集的所有事件都有的预置属性；
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在 storage 中）
$is_login_id 布尔类型 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
2. 所有小程序 SDK 预置事件 $MPLaunch 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPLaunch 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真
3. 所有小程序 SDK 预置事件 $MPShow 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPShow 预置事件采集的预置属性；
字段名称 类型 说明
$scene 字符串 启动场景
$url_path 字符串 页面路径
4. 所有小程序 SDK 预置事件 $MPHide 都有的预置属性
该表格中的预置属性是所有小程序 SDK（微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ 小程序）$MPHide 预置事件采集的预置属性；字段名称 类型 说明
$event_duration 数值 从本次小程序显示 $MPShow 到 $MPHide 小程序进入后台或者关闭的时间
$url_path 字符串 页面路径
5. 相关文档链接
微信小程序 SDK 预置事件和预置属性；
支付宝小程序 SDK 预置事件和预置属性；
百度小程序 SDK 预置事件和预置属性；
字节跳动小程序 SDK 预置事件和预置属性；
QQ 小程序 SDK 预置事件和预置属性；微信小程序 SDK 常见问题.小程序 SDK 常见问题 v1.13
1. 所有小程序 SDK 常见问题
1.1. 为什么项目中看不到线上版小程序的数据？
1. 检查代码逻辑是否有运行 init() 方法；
2. 检查数据接收地址指向的项目与所看的项目是否一致；
3. 检查数据接收地址是否在管理平台服务器域名中配置；
4. 检查埋点管理中是否有报错数据；
1.2. 如何获取 Distinct ID?
可以通过调用小程序 SDK 提供的 sa.store.getDistinctId() 接口获取 Distinct ID；如果是在 login() 方法之后调用，获取到的就是登录 ID；
1.3. 如何修改匿名 ID?
可以通过调用小程序 SDK 提供的 sa.identify(''anonymousID'', true) 接口修改匿名 ID ；
相关 API 介绍：
微信小程序 SDK API；
支付宝小程序 SDK API；
1.4. 如何获取公共属性？
微信小程序 SDK 可以通过调用小程序 SDK 提供的 sa.getPresetProperties() 接口获取部分公共属性；注意，该方法并不能获取到所有的公共属性，只能获
取到所有事件都有的预置属性；
1.5. 如何统计小程序某个页面的停留时长
客户有时需要统计用户在小程序中某个页面的停留时长，可以参考如下代码中的逻辑采集页面停留时长
index.js
var timer;
Page({
onShow:function(){
timer = new Date().getTime();
},
onHide:function(){
let duration = new Date().getTime() - timer;
// SDK
getApp().sensors.track(''countScanTime'',{
duration: duration
})
}
});
2. 微信小程序 SDK 常见问题
2.1. 如何获取匿名 ID?
可以通过调用微信小程序 SDK 提供的 sa.quick(''getAnonymousID'') 接口获取匿名 ID 。如果是在 login() 方法之后调用，获取的仍然是匿名 ID；
2.2. 预置事件设置自定义属性
用户可以在相应生命周期函数执行之前，对预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、$MPShare 添加自定义属性，可以通过为
暴露出来的 sa.para.autoTrack 对象的相关属性设置一个属性值为对象或者返回值是对象的函数值实现。
app.j
s/**
$MPLaunch appId,query
js
*/
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch : true,
appShow : true,
appHide : true,
pageShow : true,
pageShare : true
}
});
sa.init();
App({
onLaunch: function( data ){
// $MPLaunch
sa.para.autoTrack.appLaunch = {
appId:data.referrerInfo.appId,
query:data.query
};
},
onShow: function( data ){
// $MPShow
sa.para.autoTrack.appShow = {
appName: ''''
}
},
onHide: function(){
// $MPHide
sa.para.autoTrack.appHide = {
endTime: new Date()
}
}
})
index.js
var app = getApp();
Page({
onShow: function(){
// $MPViewScreen
app.sensors.para.autoTrack.pageShow = {
pageName : ''''
}
},
onShareAppMessage:
function(){ app.sensors.para.autoTrack.p
ageShare = {
sharePageName : ''''
}
}
});
2.3. 如何设置批量发送？
1. 可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次；
2. 可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 }；
3. 使用批量发送的话，需要升级到神策 1.11 以上（后端增加 _track_id 功能)；
4. 批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用
等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上；
5. 注意：1.13.15 版本之前的 SDK 批量发送功能在网络由无网恢复到有网状态后，数据无法再发送成功的问题；该问题在 1.13.15 版本修复。2.4. 如何设置自定义渠道参数？
微信小程序 SDK 从 1.13.8 版本开始支持 SDK 自动解析自定义渠道参数的功能；用户可以在初始化时，通过设置 source_channel:[''a'', ''b''] 设置要解析的自
定义参数 a, b;当通过带有设置的自定义参数路径访问小程序时，神策微信小程序 SDK 就可以通过生命周期函数参数对象将自定义参数 a, b解析出来，并设
置到预置事件中。
2.5. init() 方法作用？是否可以多次调用？
init() 方法是用来通知微信小程序 SDK，初始化已经完成，可以通过网络请求发送数据了；init() 方法调用之前通过 track() 方法采集的数据会被保存到一个
发送队列中，当调用 init() 之后，会先将队列中的数据发送出去，再正常发送数据，不做缓存。
可以多次调用 init() 方法。
2.6. 渠道相关属性介绍
如何使用神策微信小程序 SDK 进行渠道追踪请参考此文档：小程序渠道追踪
2.6.1. 渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow ，还有页面的生命周期函数 onShow 中，我们会自动解析启动参数对象与页面参数对象中的渠道相关
参数（包含通过 source_channel 自定义的渠道参数以及预置的 utm 渠道参数）作为这三个预置事件的渠道属性，见截图
2.6.2. 最近一次渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow 中，我们会将从启动参数对象中解析出来的渠道参数保存在 $latest_utm 相关属性或 _latest 自定
义渠道相关属性变量中；
默认情况下，即 is_persistent_save 设置为 false 的情况下
当下次启动，热启动时，如果启动参数中带有 utm 渠道参数，会将上次启动的$latest_utm 渠道相关属性重置，只保留本次热启动解析出来的 $latest_utm
渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次内存中保存的 $latest_utm 相关属性；
冷启动时，$latest_utm 渠道相关属性会自动重置；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)在小程序生命周期（从冷启动到退出）有效，下次冷启动时，会被重置；
is_persistent_save 设置为 true 的情况下
我们会将从启动参数对象中解析出来的渠道参数赋值给 $latest_utm 渠道相关属性或 _latest 自定义渠道相关属性，并将$latest_utm 渠道相关属性或
_latest 自定义渠道相关属性保存到 storage 中；
当下次启动（无论热启动或者冷启动）时，如果启动参数中带有 utm 渠道参数，会将上次启动的 $latest_utm 渠道相关属性重置，只保留本次启动解析出来
的 $latest_utm 渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次启动解析出来的 $latest_utm 相关属性；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)会一直有效，直到小程序被删除；
2.6.3. 首次渠道的相关属性
在小程序 SDK 发现设备之前没有加载过 SDK ，且冷启动时在小程序 App 实例生命周期函数 onLaunch 中能解析到渠道相关参数（包含通过
souce_channel 自定义的渠道参数以及预置的 utm 渠道参数） 时，会通过 setOnceProfile() 接口来设置用户属性。
2.6.4. 特殊处理
扫描普通链接二维码时，会去解析参数对象 query 中的 q 属性；
扫描 getUnlimited() 接口生成的小程序码时，会去解析参数对象 query 中的 scene 属性；2.7. 小程序分享的计算逻辑和规则
在 SDK1.9 版本加入了小程序的分享事件 $MPShare ，该事件在小程序中调用分享接口时触发。
$url_path 属性值会记录触发分享的页面地址。
$share_depth 属性值会记录分享的层级：A、B、C为三个不同的用户，若小程序一个页面依照 A -> B -> C 的顺序进行分享，则 A 的分享会被标记为1级
分享，B 触发的分享会被标记为2级，C 则为3级分享。
其中，用户打开自己分享的页面是不会增加 $share_depth 的值。
若您希望在后续跟踪分享的效果，需要配置 allow_amend_share_path 为true，这样神策会自动修改分享的path参数，path后面会新增参数包含
distinct_id，分享次数，页面路径信息。在该分享页面被打开时，会自动解析到$MPLaunch 和 $MPShow 中。
2.8. 预置事件添加异步自定义属性值
1. 如果是添加不需要延迟获取的属性，可以参考文档.小程序 SDK 常见问题 v1.13#预置事件设置自定义属性中描述的方案添加。
2. 如果是需要延迟才能获取的属性，首先需要关闭 autoTrack 对应的预置事件，然后手动去发送。
方案一：如果不需要采集预置事件的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）
方案二：如果需要采集预置事件的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen $MPShare 设置自
定义属性不支持这种方案 ）
app.js
//
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch: false,
appShow: false,
appHide: false,
pageShow: false,
pageShare: false
}
});
sa.init()
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPLaunch'',{
goodsID: ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPShow'',{
goodsID: ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',success:function(res){
//
sa.track(''$MPHide'',{
goodsID: ''xxxx''
});
}
});
}
});
// index.js
Page({
onShow:function(){
// $MPViewScreen
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPViewScreen'',{
goodsID: ''xxxx''
});
}
});
}
});
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appLaunch'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appShow'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',
success:function(res){
// sa.quick(''appHide'',
{
''goodsID'' : ''xxxx''
});
}
});
}
});3. 支付宝小程序 SDK 常见问题
3.1. 为什么预置事件 $MPClick 有的预置属性没有采集？
$MPClick 事件中 $element_id、$element_name 和$element_content 这三个预置属性的采集依赖被点击元素是否设置 id、data_name、data_content。
建议在被点击元素中定义 id、data-name、data-content 这三个属性之一来标识元素的采集，否则在神策分析后台无法分辨 $MPClick 事件由哪个元素触
发。
$element_name 对应点击元素的 data-name 属性；
$element_id 对应点击元素的 id 属性；
$element_content 对应点击元素的 data-content 属性。.小程序 SDK 常见问题 v1.14
1. 所有小程序 SDK 常见问题
1.1. 为什么项目中看不到线上版小程序的数据？
1. 检查代码逻辑是否有运行 init() 方法；
2. 检查数据接收地址指向的项目与所看的项目是否一致；
3. 检查数据接收地址是否在管理平台服务器域名中配置；
4. 检查埋点管理中是否有报错数据；
1.2. 如何获取 Distinct ID?
可以通过调用小程序 SDK 提供的 sa.store.getDistinctId() 接口获取 Distinct ID；如果是在 login() 方法之后调用，获取到的就是登录 ID；
1.3. 如何修改匿名 ID?
可以通过调用小程序 SDK 提供的 sa.identify(''anonymousID'', true) 接口修改匿名 ID ；
相关 API 介绍：
微信小程序 SDK API；
支付宝小程序 SDK API；
1.4. 如何获取公共属性？
微信小程序 SDK 可以通过调用小程序 SDK 提供的 sa.getPresetProperties() 接口获取部分公共属性；注意，该方法并不能获取到所有的公共属性，只能获
取到所有事件都有的预置属性；
1.5. 如何统计小程序某个页面的停留时长
客户有时需要统计用户在小程序中某个页面的停留时长，可以参考如下代码中的逻辑采集页面停留时长
index.js
var timer;
Page({
onShow:function(){
timer = new Date().getTime();
},
onHide:function(){
let duration = new Date().getTime() - timer;
// SDK
getApp().sensors.track(''countScanTime'',{
duration: duration
})
}
});
2. 微信小程序 SDK 常见问题
2.1. 如何获取匿名 ID?
可以通过调用微信小程序 SDK 提供的 sa.quick(''getAnonymousID'') 接口获取匿名 ID 。如果是在 login() 方法之后调用，获取的仍然是匿名 ID；
2.2. 预置事件设置自定义属性
用户可以在相应生命周期函数执行之前，对预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、$MPShare 添加自定义属性，可以通过为
暴露出来的 sa.para.autoTrack 对象的相关属性设置一个属性值为对象或者返回值是对象的函数值实现。
app.j
s/**
$MPLaunch appId,query
js
*/
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch : true,
appShow : true,
appHide : true,
pageShow : true,
pageShare : true
}
});
sa.init();
App({
onLaunch: function( data ){
// $MPLaunch
sa.para.autoTrack.appLaunch = {
appId:data.referrerInfo.appId,
query:data.query
};
},
onShow: function( data ){
// $MPShow
sa.para.autoTrack.appShow = {
appName: ''''
}
},
onHide: function(){
// $MPHide
sa.para.autoTrack.appHide = {
endTime: new Date()
}
}
})
index.js
var app = getApp();
Page({
onShow: function(){
// $MPViewScreen
app.sensors.para.autoTrack.pageShow = {
pageName : ''''
}
},
onShareAppMessage:
function(){ app.sensors.para.autoTrack.p
ageShare = {
sharePageName : ''''
}
}
});
2.3. 如何设置批量发送？
1. 可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次；
2. 可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 }；
3. 使用批量发送的话，需要升级到神策 1.11 以上（后端增加 _track_id 功能)；
4. 批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用
等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上；
5. 注意：1.13.15 版本之前的 SDK 批量发送功能在网络由无网恢复到有网状态后，数据无法再发送成功的问题；该问题在 1.13.15 版本修复。2.4. 如何设置自定义渠道参数？
微信小程序 SDK 从 1.13.8 版本开始支持 SDK 自动解析自定义渠道参数的功能；用户可以在初始化时，通过设置 source_channel:[''a'', ''b''] 设置要解析的自
定义参数 a, b;当通过带有设置的自定义参数路径访问小程序时，神策微信小程序 SDK 就可以通过生命周期函数参数对象将自定义参数 a, b解析出来，并设
置到预置事件中。
2.5. init() 方法作用？是否可以多次调用？
init() 方法是用来通知微信小程序 SDK，初始化已经完成，可以通过网络请求发送数据了；init() 方法调用之前通过 track() 方法采集的数据会被保存到一个
发送队列中，当调用 init() 之后，会先将队列中的数据发送出去，再正常发送数据，不做缓存。
可以多次调用 init() 方法。
2.6. 渠道相关属性介绍
如何使用神策微信小程序 SDK 进行渠道追踪请参考此文档：小程序渠道追踪
2.6.1. 渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow ，还有页面的生命周期函数 onShow 中，我们会自动解析启动参数对象与页面参数对象中的渠道相关
参数（包含通过 source_channel 自定义的渠道参数以及预置的 utm 渠道参数）作为这三个预置事件的渠道属性，见截图
2.6.2. 最近一次渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow 中，我们会将从启动参数对象中解析出来的渠道参数保存在 $latest_utm 相关属性或 _latest 自定
义渠道相关属性变量中；
默认情况下，即 is_persistent_save 设置为 false 的情况下
当下次启动，热启动时，如果启动参数中带有 utm 渠道参数，会将上次启动的$latest_utm 渠道相关属性重置，只保留本次热启动解析出来的 $latest_utm
渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次内存中保存的 $latest_utm 相关属性；
冷启动时，$latest_utm 渠道相关属性会自动重置；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)在小程序生命周期（从冷启动到退出）有效，下次冷启动时，会被重置；
is_persistent_save 设置为 true 的情况下
我们会将从启动参数对象中解析出来的渠道参数赋值给 $latest_utm 渠道相关属性或 _latest 自定义渠道相关属性，并将$latest_utm 渠道相关属性或
_latest 自定义渠道相关属性保存到 storage 中；
当下次启动（无论热启动或者冷启动）时，如果启动参数中带有 utm 渠道参数，会将上次启动的 $latest_utm 渠道相关属性重置，只保留本次启动解析出来
的 $latest_utm 渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次启动解析出来的 $latest_utm 相关属性；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)会一直有效，直到小程序被删除；
2.6.3. 首次渠道的相关属性
在小程序 SDK 发现设备之前没有加载过 SDK ，且冷启动时在小程序 App 实例生命周期函数 onLaunch 中能解析到渠道相关参数（包含通过
souce_channel 自定义的渠道参数以及预置的 utm 渠道参数） 时，会通过 setOnceProfile() 接口来设置用户属性。
2.6.4. 特殊处理
扫描普通链接二维码时，会去解析参数对象 query 中的 q 属性；
扫描 getUnlimited() 接口生成的小程序码时，会去解析参数对象 query 中的 scene 属性；2.7. 小程序分享的计算逻辑和规则
在 SDK1.9 版本加入了小程序的分享事件 $MPShare ，该事件在小程序中调用分享接口时触发。
$url_path 属性值会记录触发分享的页面地址。
$share_depth 属性值会记录分享的层级：A、B、C为三个不同的用户，若小程序一个页面依照 A -> B -> C 的顺序进行分享，则 A 的分享会被标记为1级
分享，B 触发的分享会被标记为2级，C 则为3级分享。
其中，用户打开自己分享的页面是不会增加 $share_depth 的值。
若您希望在后续跟踪分享的效果，需要配置 allow_amend_share_path 为true，这样神策会自动修改分享的path参数，path后面会新增参数包含
distinct_id，分享次数，页面路径信息。在该分享页面被打开时，会自动解析到$MPLaunch 和 $MPShow 中。
2.8. 预置事件添加异步自定义属性值
1. 如果是添加不需要延迟获取的属性，可以参考文档.小程序 SDK 常见问题 v1.13#预置事件设置自定义属性中描述的方案添加。
2. 如果是需要延迟才能获取的属性，首先需要关闭 autoTrack 对应的预置事件，然后手动去发送。
方案一：如果不需要采集预置事件的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）
方案二：如果需要采集预置事件的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen $MPShare 设置自
定义属性不支持这种方案 ）
app.js
//
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch: false,
appShow: false,
appHide: false,
pageShow: false,
pageShare: false
}
});
sa.init()
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPLaunch'',{
goodsID: ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPShow'',{
goodsID: ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',success:function(res){
//
sa.track(''$MPHide'',{
goodsID: ''xxxx''
});
}
});
}
});
// index.js
Page({
onShow:function(){
// $MPViewScreen
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPViewScreen'',{
goodsID: ''xxxx''
});
}
});
}
});
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appLaunch'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appShow'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',
success:function(res){
// sa.quick(''appHide'',
{
''goodsID'' : ''xxxx''
});
}
});
}
});3. 支付宝小程序 SDK 常见问题
3.1. 为什么预置事件 $MPClick 有的预置属性没有采集？
$MPClick 事件中 $element_id、$element_name 和$element_content 这三个预置属性的采集依赖被点击元素是否设置 id、data_name、data_content。
建议在被点击元素中定义 id、data-name、data-content 这三个属性之一来标识元素的采集，否则在神策分析后台无法分辨 $MPClick 事件由哪个元素触
发。
$element_name 对应点击元素的 data-name 属性；
$element_id 对应点击元素的 id 属性；
$element_content 对应点击元素的 data-content 属性。.小程序 SDK 常见问题 v1.15
1. 所有小程序 SDK 常见问题
1.1. 为什么项目中看不到线上版小程序的数据？
1. 检查代码逻辑是否有运行 init() 方法；
2. 检查数据接收地址指向的项目与所看的项目是否一致；
3. 检查数据接收地址是否在管理平台服务器域名中配置；
4. 检查埋点管理中是否有报错数据；
1.2. 如何获取 Distinct ID?
可以通过调用小程序 SDK 提供的 sa.store.getDistinctId() 接口获取 Distinct ID；如果是在 login() 方法之后调用，获取到的就是登录 ID；
1.3. 如何修改匿名 ID?
可以通过调用小程序 SDK 提供的 sa.identify(''anonymousID'', true) 接口修改匿名 ID ；
相关 API 介绍：
微信小程序 SDK API；
支付宝小程序 SDK API；
1.4. 如何获取公共属性？
微信小程序 SDK 可以通过调用小程序 SDK 提供的 sa.getPresetProperties() 接口获取部分公共属性；注意，该方法并不能获取到所有的公共属性，只能获
取到所有事件都有的预置属性；
1.5. 如何统计小程序某个页面的停留时长
客户有时需要统计用户在小程序中某个页面的停留时长，可以参考如下代码中的逻辑采集页面停留时长
index.js
var timer;
Page({
onShow:function(){
timer = new Date().getTime();
},
onHide:function(){
let duration = new Date().getTime() - timer;
// SDK
getApp().sensors.track(''countScanTime'',{
duration: duration
})
}
});
2. 微信小程序 SDK 常见问题
2.1. 如何获取匿名 ID?
可以通过调用微信小程序 SDK 提供的 sa.quick(''getAnonymousID'') 接口获取匿名 ID 。如果是在 login() 方法之后调用，获取的仍然是匿名 ID；
2.2. 预置事件设置自定义属性
用户可以在相应生命周期函数执行之前，对预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、$MPShare 添加自定义属性，可以通过为
暴露出来的 sa.para.autoTrack 对象的相关属性设置一个属性值为对象或者返回值是对象的函数值实现。
app.j
s/**
$MPLaunch appId,query
js
*/
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch : true,
appShow : true,
appHide : true,
pageShow : true,
pageShare : true
}
});
sa.init();
App({
onLaunch: function( data ){
// $MPLaunch
sa.para.autoTrack.appLaunch = {
appId:data.referrerInfo.appId,
query:data.query
};
},
onShow: function( data ){
// $MPShow
sa.para.autoTrack.appShow = {
appName: ''''
}
},
onHide: function(){
// $MPHide
sa.para.autoTrack.appHide = {
endTime: new Date()
}
}
})
index.js
var app = getApp();
Page({
onShow: function(){
// $MPViewScreen
app.sensors.para.autoTrack.pageShow = {
pageName : ''''
}
},
onShareAppMessage:
function(){ app.sensors.para.autoTrack.p
ageShare = {
sharePageName : ''''
}
}
});
2.3. 如何设置批量发送？
1. 可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次；
2. 可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 }；
3. 使用批量发送的话，需要升级到神策 1.11 以上（后端增加 _track_id 功能)；
4. 批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用
等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上；
5. 注意：1.13.15 版本之前的 SDK 批量发送功能在网络由无网恢复到有网状态后，数据无法再发送成功的问题；该问题在 1.13.15 版本修复。2.4. 如何设置自定义渠道参数？
微信小程序 SDK 从 1.13.8 版本开始支持 SDK 自动解析自定义渠道参数的功能；用户可以在初始化时，通过设置 source_channel:[''a'', ''b''] 设置要解析的自
定义参数 a, b;当通过带有设置的自定义参数路径访问小程序时，神策微信小程序 SDK 就可以通过生命周期函数参数对象将自定义参数 a, b解析出来，并设
置到预置事件中。
2.5. init() 方法作用？是否可以多次调用？
init() 方法是用来通知微信小程序 SDK，初始化已经完成，可以通过网络请求发送数据了；init() 方法调用之前通过 track() 方法采集的数据会被保存到一个
发送队列中，当调用 init() 之后，会先将队列中的数据发送出去，再正常发送数据，不做缓存。
可以多次调用 init() 方法。
2.6. 渠道相关属性介绍
如何使用神策微信小程序 SDK 进行渠道追踪请参考此文档：小程序渠道追踪
2.6.1. 渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow ，还有页面的生命周期函数 onShow 中，我们会自动解析启动参数对象与页面参数对象中的渠道相关
参数（包含通过 source_channel 自定义的渠道参数以及预置的 utm 渠道参数）作为这三个预置事件的渠道属性，见截图
2.6.2. 最近一次渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow 中，我们会将从启动参数对象中解析出来的渠道参数保存在 $latest_utm 相关属性或 _latest 自定
义渠道相关属性变量中；
默认情况下，即 is_persistent_save 设置为 false 的情况下
当下次启动，热启动时，如果启动参数中带有 utm 渠道参数，会将上次启动的$latest_utm 渠道相关属性重置，只保留本次热启动解析出来的 $latest_utm
渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次内存中保存的 $latest_utm 相关属性；
冷启动时，$latest_utm 渠道相关属性会自动重置；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)在小程序生命周期（从冷启动到退出）有效，下次冷启动时，会被重置；
is_persistent_save 设置为 true 的情况下
我们会将从启动参数对象中解析出来的渠道参数赋值给 $latest_utm 渠道相关属性或 _latest 自定义渠道相关属性，并将$latest_utm 渠道相关属性或
_latest 自定义渠道相关属性保存到 storage 中；
当下次启动（无论热启动或者冷启动）时，如果启动参数中带有 utm 渠道参数，会将上次启动的 $latest_utm 渠道相关属性重置，只保留本次启动解析出来
的 $latest_utm 渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次启动解析出来的 $latest_utm 相关属性；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)会一直有效，直到小程序被删除；
2.6.3. 首次渠道的相关属性
在小程序 SDK 发现设备之前没有加载过 SDK ，且冷启动时在小程序 App 实例生命周期函数 onLaunch 中能解析到渠道相关参数（包含通过
souce_channel 自定义的渠道参数以及预置的 utm 渠道参数） 时，会通过 setOnceProfile() 接口来设置用户属性。
2.6.4. 特殊处理
扫描普通链接二维码时，会去解析参数对象 query 中的 q 属性；
扫描 getUnlimited() 接口生成的小程序码时，会去解析参数对象 query 中的 scene 属性；2.7. 小程序分享的计算逻辑和规则
在 SDK1.9 版本加入了小程序的分享事件 $MPShare ，该事件在小程序中调用分享接口时触发。
$url_path 属性值会记录触发分享的页面地址。
$share_depth 属性值会记录分享的层级：A、B、C为三个不同的用户，若小程序一个页面依照 A -> B -> C 的顺序进行分享，则 A 的分享会被标记为1级
分享，B 触发的分享会被标记为2级，C 则为3级分享。
其中，用户打开自己分享的页面是不会增加 $share_depth 的值。
若您希望在后续跟踪分享的效果，需要配置 allow_amend_share_path 为true，这样神策会自动修改分享的path参数，path后面会新增参数包含
distinct_id，分享次数，页面路径信息。在该分享页面被打开时，会自动解析到$MPLaunch 和 $MPShow 中。
2.8. 预置事件添加异步自定义属性值
1. 如果是添加不需要延迟获取的属性，可以参考文档.小程序 SDK 常见问题 v1.13#预置事件设置自定义属性中描述的方案添加。
2. 如果是需要延迟才能获取的属性，首先需要关闭 autoTrack 对应的预置事件，然后手动去发送。
方案一：如果不需要采集预置事件的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）
方案二：如果需要采集预置事件的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen $MPShare 设置自
定义属性不支持这种方案 ）
app.js
//
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch: false,
appShow: false,
appHide: false,
pageShow: false,
pageShare: false
}
});
sa.init()
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPLaunch'',{
goodsID: ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPShow'',{
goodsID: ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',success:function(res){
//
sa.track(''$MPHide'',{
goodsID: ''xxxx''
});
}
});
}
});
// index.js
Page({
onShow:function(){
// $MPViewScreen
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPViewScreen'',{
goodsID: ''xxxx''
});
}
});
}
});
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appLaunch'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appShow'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',
success:function(res){
// sa.quick(''appHide'',
{
''goodsID'' : ''xxxx''
});
}
});
}
});3. 支付宝小程序 SDK 常见问题
3.1. 为什么预置事件 $MPClick 有的预置属性没有采集？
$MPClick 事件中 $element_id、$element_name 和$element_content 这三个预置属性的采集依赖被点击元素是否设置 id、data_name、data_content。
建议在被点击元素中定义 id、data-name、data-content 这三个属性之一来标识元素的采集，否则在神策分析后台无法分辨 $MPClick 事件由哪个元素触
发。
$element_name 对应点击元素的 data-name 属性；
$element_id 对应点击元素的 id 属性；
$element_content 对应点击元素的 data-content 属性。.小程序 SDK 常见问题 v1.16
1. 所有小程序 SDK 常见问题
1.1. 为什么项目中看不到线上版小程序的数据？
1. 检查代码逻辑是否有运行 init() 方法；
2. 检查数据接收地址指向的项目与所看的项目是否一致；
3. 检查数据接收地址是否在管理平台服务器域名中配置；
4. 检查埋点管理中是否有报错数据；
1.2. 如何获取 Distinct ID?
可以通过调用小程序 SDK 提供的 sa.store.getDistinctId() 接口获取 Distinct ID；如果是在 login() 方法之后调用，获取到的就是登录 ID；
1.3. 如何修改匿名 ID?
可以通过调用小程序 SDK 提供的 sa.identify(''anonymousID'', true) 接口修改匿名 ID ；
相关 API 介绍：
微信小程序 SDK API；
支付宝小程序 SDK API；
1.4. 如何获取公共属性？
微信小程序 SDK 可以通过调用小程序 SDK 提供的 sa.getPresetProperties() 接口获取部分公共属性；注意，该方法并不能获取到所有的公共属性，只能获
取到所有事件都有的预置属性；
1.5. 如何统计小程序某个页面的停留时长
客户有时需要统计用户在小程序中某个页面的停留时长，可以参考如下代码中的逻辑采集页面停留时长
index.js
var timer;
Page({
onShow:function(){
timer = new Date().getTime();
},
onHide:function(){
let duration = new Date().getTime() - timer;
// SDK
getApp().sensors.track(''countScanTime'',{
duration: duration
})
}
});
2. 微信小程序 SDK 常见问题
2.1. 如何获取匿名 ID?
可以通过调用微信小程序 SDK 提供的 sa.quick(''getAnonymousID'') 接口获取匿名 ID 。如果是在 login() 方法之后调用，获取的仍然是匿名 ID；
2.2. 预置事件设置自定义属性
用户可以在相应生命周期函数执行之前，对预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、$MPShare 添加自定义属性，可以通过为
暴露出来的 sa.para.autoTrack 对象的相关属性设置一个属性值为对象或者返回值是对象的函数值实现。
app.j
s/**
$MPLaunch appId,query
js
*/
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch : true,
appShow : true,
appHide : true,
pageShow : true,
pageShare : true
}
});
sa.init();
App({
onLaunch: function( data ){
// $MPLaunch
sa.para.autoTrack.appLaunch = {
appId:data.referrerInfo.appId,
query:data.query
};
},
onShow: function( data ){
// $MPShow
sa.para.autoTrack.appShow = {
appName: ''''
}
},
onHide: function(){
// $MPHide
sa.para.autoTrack.appHide = {
endTime: new Date()
}
}
})
index.js
var app = getApp();
Page({
onShow: function(){
// $MPViewScreen
app.sensors.para.autoTrack.pageShow = {
pageName : ''''
}
},
onShareAppMessage:
function(){ app.sensors.para.autoTrack.p
ageShare = {
sharePageName : ''''
}
}
});
2.3. 如何设置批量发送？
1. 可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次；
2. 可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 }；
3. 使用批量发送的话，需要升级到神策 1.11 以上（后端增加 _track_id 功能)；
4. 批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用
等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上；
5. 注意：1.13.15 版本之前的 SDK 批量发送功能在网络由无网恢复到有网状态后，数据无法再发送成功的问题；该问题在 1.13.15 版本修复。2.4. 如何设置自定义渠道参数？
微信小程序 SDK 从 1.13.8 版本开始支持 SDK 自动解析自定义渠道参数的功能；用户可以在初始化时，通过设置 source_channel:[''a'', ''b''] 设置要解析的自
定义参数 a, b;当通过带有设置的自定义参数路径访问小程序时，神策微信小程序 SDK 就可以通过生命周期函数参数对象将自定义参数 a, b解析出来，并设
置到预置事件中。
2.5. init() 方法作用？是否可以多次调用？
init() 方法是用来通知微信小程序 SDK，初始化已经完成，可以通过网络请求发送数据了；init() 方法调用之前通过 track() 方法采集的数据会被保存到一个
发送队列中，当调用 init() 之后，会先将队列中的数据发送出去，再正常发送数据，不做缓存。
可以多次调用 init() 方法。
2.6. 渠道相关属性介绍
如何使用神策微信小程序 SDK 进行渠道追踪请参考此文档：小程序渠道追踪
2.6.1. 渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow ，还有页面的生命周期函数 onShow 中，我们会自动解析启动参数对象与页面参数对象中的渠道相关
参数（包含通过 source_channel 自定义的渠道参数以及预置的 utm 渠道参数）作为这三个预置事件的渠道属性，见截图
2.6.2. 最近一次渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow 中，我们会将从启动参数对象中解析出来的渠道参数保存在 $latest_utm 相关属性或 _latest 自定
义渠道相关属性变量中；
默认情况下，即 is_persistent_save 设置为 false 的情况下
当下次启动，热启动时，如果启动参数中带有 utm 渠道参数，会将上次启动的$latest_utm 渠道相关属性重置，只保留本次热启动解析出来的 $latest_utm
渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次内存中保存的 $latest_utm 相关属性；
冷启动时，$latest_utm 渠道相关属性会自动重置；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)在小程序生命周期（从冷启动到退出）有效，下次冷启动时，会被重置；
is_persistent_save 设置为 true 的情况下
我们会将从启动参数对象中解析出来的渠道参数赋值给 $latest_utm 渠道相关属性或 _latest 自定义渠道相关属性，并将$latest_utm 渠道相关属性或
_latest 自定义渠道相关属性保存到 storage 中；
当下次启动（无论热启动或者冷启动）时，如果启动参数中带有 utm 渠道参数，会将上次启动的 $latest_utm 渠道相关属性重置，只保留本次启动解析出来
的 $latest_utm 渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次启动解析出来的 $latest_utm 相关属性；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)会一直有效，直到小程序被删除；
2.6.3. 首次渠道的相关属性
在小程序 SDK 发现设备之前没有加载过 SDK ，且冷启动时在小程序 App 实例生命周期函数 onLaunch 中能解析到渠道相关参数（包含通过
souce_channel 自定义的渠道参数以及预置的 utm 渠道参数） 时，会通过 setOnceProfile() 接口来设置用户属性。
2.6.4. 特殊处理
扫描普通链接二维码时，会去解析参数对象 query 中的 q 属性；
扫描 getUnlimited() 接口生成的小程序码时，会去解析参数对象 query 中的 scene 属性；2.7. 小程序分享的计算逻辑和规则
在 SDK1.9 版本加入了小程序的分享事件 $MPShare ，该事件在小程序中调用分享接口时触发。
$url_path 属性值会记录触发分享的页面地址。
$share_depth 属性值会记录分享的层级：A、B、C为三个不同的用户，若小程序一个页面依照 A -> B -> C 的顺序进行分享，则 A 的分享会被标记为1级
分享，B 触发的分享会被标记为2级，C 则为3级分享。
其中，用户打开自己分享的页面是不会增加 $share_depth 的值。
若您希望在后续跟踪分享的效果，需要配置 allow_amend_share_path 为true，这样神策会自动修改分享的path参数，path后面会新增参数包含
distinct_id，分享次数，页面路径信息。在该分享页面被打开时，会自动解析到$MPLaunch 和 $MPShow 中。
2.8. 预置事件添加异步自定义属性值
1. 如果是添加不需要延迟获取的属性，可以参考文档.小程序 SDK 常见问题 v1.13#预置事件设置自定义属性中描述的方案添加。
2. 如果是需要延迟才能获取的属性，首先需要关闭 autoTrack 对应的预置事件，然后手动去发送。
方案一：如果不需要采集预置事件的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）
方案二：如果需要采集预置事件的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen $MPShare 设置自
定义属性不支持这种方案 ）
app.js
//
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch: false,
appShow: false,
appHide: false,
pageShow: false,
pageShare: false
}
});
sa.init()
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPLaunch'',{
goodsID: ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPShow'',{
goodsID: ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',success:function(res){
//
sa.track(''$MPHide'',{
goodsID: ''xxxx''
});
}
});
}
});
// index.js
Page({
onShow:function(){
// $MPViewScreen
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPViewScreen'',{
goodsID: ''xxxx''
});
}
});
}
});
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appLaunch'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appShow'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',
success:function(res){
// sa.quick(''appHide'',
{
''goodsID'' : ''xxxx''
});
}
});
}
});3. 支付宝小程序 SDK 常见问题
3.1. 为什么预置事件 $MPClick 有的预置属性没有采集？
$MPClick 事件中 $element_id、$element_name 和$element_content 这三个预置属性的采集依赖被点击元素是否设置 id、data_name、data_content。
建议在被点击元素中定义 id、data-name、data-content 这三个属性之一来标识元素的采集，否则在神策分析后台无法分辨 $MPClick 事件由哪个元素触
发。
$element_name 对应点击元素的 data-name 属性；
$element_id 对应点击元素的 id 属性；
$element_content 对应点击元素的 data-content 属性。.小程序 SDK 常见问题 v1.17
1. 所有小程序 SDK 常见问题
1.1. 为什么项目中看不到线上版小程序的数据？
1. 检查代码逻辑是否有运行 init() 方法；
2. 检查数据接收地址指向的项目与所看的项目是否一致；
3. 检查数据接收地址是否在管理平台服务器域名中配置；
4. 检查埋点管理中是否有报错数据；
1.2. 如何获取 Distinct ID?
可以通过调用小程序 SDK 提供的 sa.store.getDistinctId() 接口获取 Distinct ID；如果是在 login() 方法之后调用，获取到的就是登录 ID；
1.3. 如何修改匿名 ID?
可以通过调用小程序 SDK 提供的 sa.identify(''anonymousID'', true) 接口修改匿名 ID ；
相关 API 介绍：
微信小程序 SDK API；
支付宝小程序 SDK API；
1.4. 如何获取公共属性？
微信小程序 SDK 可以通过调用小程序 SDK 提供的 sa.getPresetProperties() 接口获取部分公共属性；注意，该方法并不能获取到所有的公共属性，只能获
取到所有事件都有的预置属性；
1.5. 如何统计小程序某个页面的停留时长
客户有时需要统计用户在小程序中某个页面的停留时长，可以参考如下代码中的逻辑采集页面停留时长
index.js
var timer;
Page({
onShow:function(){
timer = new Date().getTime();
},
onHide:function(){
let duration = new Date().getTime() - timer;
// SDK
getApp().sensors.track(''countScanTime'',{
duration: duration
})
}
});
2. 微信小程序 SDK 常见问题
2.1. 如何获取匿名 ID?
可以通过调用微信小程序 SDK 提供的 sa.quick(''getAnonymousID'') 接口获取匿名 ID 。如果是在 login() 方法之后调用，获取的仍然是匿名 ID；
2.2. 预置事件设置自定义属性
用户可以在相应生命周期函数执行之前，对预置事件 $MPLaunch、 $MPShow、 $MPHide、 $MPViewScreen、$MPShare 添加自定义属性，可以通过为
暴露出来的 sa.para.autoTrack 对象的相关属性设置一个属性值为对象或者返回值是对象的函数值实现。
app.j
s/**
$MPLaunch appId,query
js
*/
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch : true,
appShow : true,
appHide : true,
pageShow : true,
pageShare : true
}
});
sa.init();
App({
onLaunch: function( data ){
// $MPLaunch
sa.para.autoTrack.appLaunch = {
appId:data.referrerInfo.appId,
query:data.query
};
},
onShow: function( data ){
// $MPShow
sa.para.autoTrack.appShow = {
appName: ''''
}
},
onHide: function(){
// $MPHide
sa.para.autoTrack.appHide = {
endTime: new Date()
}
}
})
index.js
var app = getApp();
Page({
onShow: function(){
// $MPViewScreen
app.sensors.para.autoTrack.pageShow = {
pageName : ''''
}
},
onShareAppMessage:
function(){ app.sensors.para.autoTrack.p
ageShare = {
sharePageName : ''''
}
}
});
2.3. 如何设置批量发送？
1. 可配置是否批量发送数据 batch_send:true ;默认情况下，会每隔 6s 或者每采集 6 条数据后合并发送一次；
2. 可配置使用批量发送数据，且可配置批量发送数据的时间间隔或条数 batch_send : { send_timeout : 5000, max_length : 20 }；
3. 使用批量发送的话，需要升级到神策 1.11 以上（后端增加 _track_id 功能)；
4. 批量发送中有一个优化，如果是 $MPLaunch 事件会直接发送，不会等待，因为考虑到会有较多用户打开就关闭小程序，甚至永远不来，如果使用
等待 6s 的批量发送策略，会导致数据丢失，跟其他统计工具对不上；
5. 注意：1.13.15 版本之前的 SDK 批量发送功能在网络由无网恢复到有网状态后，数据无法再发送成功的问题；该问题在 1.13.15 版本修复。2.4. 如何设置自定义渠道参数？
微信小程序 SDK 从 1.13.8 版本开始支持 SDK 自动解析自定义渠道参数的功能；用户可以在初始化时，通过设置 source_channel:[''a'', ''b''] 设置要解析的自
定义参数 a, b;当通过带有设置的自定义参数路径访问小程序时，神策微信小程序 SDK 就可以通过生命周期函数参数对象将自定义参数 a, b解析出来，并设
置到预置事件中。
2.5. init() 方法作用？是否可以多次调用？
init() 方法是用来通知微信小程序 SDK，初始化已经完成，可以通过网络请求发送数据了；init() 方法调用之前通过 track() 方法采集的数据会被保存到一个
发送队列中，当调用 init() 之后，会先将队列中的数据发送出去，再正常发送数据，不做缓存。
可以多次调用 init() 方法。
2.6. 渠道相关属性介绍
如何使用神策微信小程序 SDK 进行渠道追踪请参考此文档：小程序渠道追踪
2.6.1. 渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow ，还有页面的生命周期函数 onShow 中，我们会自动解析启动参数对象与页面参数对象中的渠道相关
参数（包含通过 source_channel 自定义的渠道参数以及预置的 utm 渠道参数）作为这三个预置事件的渠道属性，见截图
2.6.2. 最近一次渠道相关属性
在小程序 App 实例生命周期函数 onLaunch 和 onShow 中，我们会将从启动参数对象中解析出来的渠道参数保存在 $latest_utm 相关属性或 _latest 自定
义渠道相关属性变量中；
默认情况下，即 is_persistent_save 设置为 false 的情况下
当下次启动，热启动时，如果启动参数中带有 utm 渠道参数，会将上次启动的$latest_utm 渠道相关属性重置，只保留本次热启动解析出来的 $latest_utm
渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次内存中保存的 $latest_utm 相关属性；
冷启动时，$latest_utm 渠道相关属性会自动重置；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)在小程序生命周期（从冷启动到退出）有效，下次冷启动时，会被重置；
is_persistent_save 设置为 true 的情况下
我们会将从启动参数对象中解析出来的渠道参数赋值给 $latest_utm 渠道相关属性或 _latest 自定义渠道相关属性，并将$latest_utm 渠道相关属性或
_latest 自定义渠道相关属性保存到 storage 中；
当下次启动（无论热启动或者冷启动）时，如果启动参数中带有 utm 渠道参数，会将上次启动的 $latest_utm 渠道相关属性重置，只保留本次启动解析出来
的 $latest_utm 渠道相关属性；如果启动参数中没有 utm 渠道参数，会保留上次启动解析出来的 $latest_utm 相关属性；
最近一次自定义渠道属性(通过 source_channel 设置采集的那些渠道属性)会一直有效，直到小程序被删除；
2.6.3. 首次渠道的相关属性
在小程序 SDK 发现设备之前没有加载过 SDK ，且冷启动时在小程序 App 实例生命周期函数 onLaunch 中能解析到渠道相关参数（包含通过
souce_channel 自定义的渠道参数以及预置的 utm 渠道参数） 时，会通过 setOnceProfile() 接口来设置用户属性。
2.6.4. 特殊处理
扫描普通链接二维码时，会去解析参数对象 query 中的 q 属性；
扫描 getUnlimited() 接口生成的小程序码时，会去解析参数对象 query 中的 scene 属性；2.7. 小程序分享的计算逻辑和规则
在 SDK1.9 版本加入了小程序的分享事件 $MPShare ，该事件在小程序中调用分享接口时触发。
$url_path 属性值会记录触发分享的页面地址。
$share_depth 属性值会记录分享的层级：A、B、C为三个不同的用户，若小程序一个页面依照 A -> B -> C 的顺序进行分享，则 A 的分享会被标记为1级
分享，B 触发的分享会被标记为2级，C 则为3级分享。
其中，用户打开自己分享的页面是不会增加 $share_depth 的值。
若您希望在后续跟踪分享的效果，需要配置 allow_amend_share_path 为true，这样神策会自动修改分享的path参数，path后面会新增参数包含
distinct_id，分享次数，页面路径信息。在该分享页面被打开时，会自动解析到$MPLaunch 和 $MPShow 中。
2.8. 预置事件添加异步自定义属性值
1. 如果是添加不需要延迟获取的属性，可以参考文档.小程序 SDK 常见问题 v1.13#预置事件设置自定义属性中描述的方案添加。
2. 如果是需要延迟才能获取的属性，首先需要关闭 autoTrack 对应的预置事件，然后手动去发送。
方案一：如果不需要采集预置事件的预置属性，可以通过 track 方法发送个对应的预置事件，加延迟的属性就可以（建议使用此方案）
方案二：如果需要采集预置事件的预置属性，需要在相应的生命周期函数中调用如下方法（预置事件 $MPViewScreen $MPShare 设置自
定义属性不支持这种方案 ）
app.js
//
var sa = require(''./utils/sensorsdata.min.js'');
sa.setPara({
name: ''sensors'',
server_url: '''',
autoTrack: {
appLaunch: false,
appShow: false,
appHide: false,
pageShow: false,
pageShare: false
}
});
sa.init()
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPLaunch'',{
goodsID: ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPShow'',{
goodsID: ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',success:function(res){
//
sa.track(''$MPHide'',{
goodsID: ''xxxx''
});
}
});
}
});
// index.js
Page({
onShow:function(){
// $MPViewScreen
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.track(''$MPViewScreen'',{
goodsID: ''xxxx''
});
}
});
}
});
/**
*/
App({
onLaunch : function(options){
// $MPLaunch
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appLaunch'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onShow : function(options){
// $MPShow
wx.request({
url: ''xxxx'',
success:function(res){
//
sa.quick(''appShow'', options,
{ ''goodsID'' : ''xxxx''
});
}
});
},
onHide : function(){
// $MPHide
wx.request({
url: ''xxxx'',
success:function(res){
// sa.quick(''appHide'',
{
''goodsID'' : ''xxxx''
});
}
});
}
});3. 支付宝小程序 SDK 常见问题
3.1. 为什么预置事件 $MPClick 有的预置属性没有采集？
$MPClick 事件中 $element_id、$element_name 和$element_content 这三个预置属性的采集依赖被点击元素是否设置 id、data_name、data_content。
建议在被点击元素中定义 id、data-name、data-content 这三个属性之一来标识元素的采集，否则在神策分析后台无法分辨 $MPClick 事件由哪个元素触
发。
$element_name 对应点击元素的 data-name 属性；
$element_id 对应点击元素的 id 属性；
$element_content 对应点击元素的 data-content 属性。快应用 SDK.快应用 SDK v1.13
在使用前，请先阅读数据模型的介绍。
在使用前，可先了解数据校验的介绍。
更新日志
1. 快应用集成 SDK
1.1. 下载 SDK
从 GitHub 上下载快应用 SDK sensorsdata.min.js;
1.2. 引入和配置 SDK
将 sensorsdata.min.js 放到项目中的某个目录下，在项目的 app.ux 中引入目录下的 sensorsdata.min.js ,然后调用 setPara() 方法设置初始化参数，必须在
onCreate 中调用 sensors.init(this) 方法完成初始化。
注意：sensors.init() 执行后才能执行其他方法，如 login 等方法如果在 init 之前调用，会存在队列中，等待 init 方法执行完再依次执行。
app.ux
import sensors from ''./sensorsdata.min.js'';
sensors.setPara({
name: ''sensors'',
server_url: ''''
});
//thisPagesensors
export default {
onCreate() {
sensors.init(this);
}
}
2. 预置事件和属性
2.1. 预置事件
2.1.1. $AppStart（App 启动）事件
app.ux
export default {
onCreate () {
sensors.init(this);
sensors.appLaunch();
}
}
2.1.2. $AppViewScreen（App 浏览页面）事件
// src
export default {
onShow() {
this.$app.sensors.pageShow();
}
}2.2. $AppStart（App 启动）事件的预置属性
字段名称 类型 说明 SDK 版本
$scene 字符串 启动场景（source.type） 0.1.0
$source_package_name 字符串 来源包名（source.packageName） 0.1.0
$brand 字符串 设备品牌 0.1.0
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在 storage 0.1.0
中）
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真 0.1.0
$lib 字符串 SDK 类型 0.1.0
$lib_version 字符串 SDK 版本 0.1.0
$manufacturer 字符串 设备制造商 0.1.0
$model 字符串 设备型号 0.1.0
$os 字符串 操作系统 0.1.0
$os_version 字符串 操作系统版本 0.1.0
$screen_height 数值 屏幕高度 0.1.0
$screen_width 数值 屏幕宽度 0.1.0
2.3. $AppViewScreen（App 浏览页面）事件的预置属性
字段名称 类型 说明 SDK 版本
$scene 字符串 启动场景（source.type） 0.1.0
$source_package_name 字符串 来源包名（source.packageName） 0.1.0
$url_path 字符串 页面路径(router.getState().path) 0.1.0
$title 字符串 页面标题（router.getState().name） 0.1.0
$brand 字符串 设备品牌 0.1.0
$is_first_day 布尔类型 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在 storage 0.1.0
中）
$lib 字符串 SDK 类型 0.1.0
$lib_version 字符串 SDK 版本 0.1.0
$manufacturer 字符串 设备制造商 0.1.0
$model 字符串 设备型号 0.1.0
$os 字符串 操作系统 0.1.0
$os_version 字符串 操作系统版本 0.1.0
$screen_height 数值 屏幕高度 0.1.0
$screen_width 数值 屏幕宽度 0.1.0
3. 标识用户
在进行任何埋点之前，都应当先确定如何标识用户。distinct_id 是神策用来标识用户的一段唯一的字符串。
在快应用中，会有下面 2 种 id
1. 默认情况下，我们会生成一个随机数 uuid ，保存在本地缓存中，我们暂时称这个为 uuid
2. 数据库中保存的，用户真实 id 。我们暂时称为 "你们服务端分配给用户具体的登录 ID"
如果不做任何操作，快应用会使用 uuid 作为 distinct_id 。注意： uuid 在换了设备，或者删除快应用后，会重新生成。
3.1. 修改匿名 ID
默认情况下，是把 uuid 作为 distinct_id 的。如果想使用其他匿名 id（比如你们自己生成的 uuid），可以用 identify(id,true) 方法来改变当前的
distinct_id。app.ux
import sensors from
''./sensorsdata.min.js'';
sensors.setPara(...);
sensors.identify(''ID'', true);
3.2. 用户关联
1. 可以通过调用 login("userID") 方法来标识真实用户；
2. 通过 login("userID") 来把 SDK 自动生成的 uuid 与现在传入的 userID 关联。且以后会一直使用这个 userID 。
app.ux
import sensors from ''./sensorsdata.min.js'';
sensors.setPara(...);
sensors.login("userID");
4. Page 中追踪自定义事件 track(eventName,[properties])
采集自定义事件。
eventName：String， 必 填 ， 事 件 名 称 ； properties：
Object，选填,为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.u
x
//
this.$app.sensors.track(''ViewProduct'', {
ProductId: ''123456'',
ProductCatalog: "Laptop Computer",
ProductName: "MacBook Pro",
ProductPrice: 12345
});
5. 设置用户属性
5.1. setProfile(properties)
直接设置用户的属性，如果存在则覆盖。
properties：Object，必选。
index.u
x
sensors.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
5.2. setOnceProfile(properties)
如果不存在则设置，存在就不设置。
properties：Object，必选。
index.uxsensors.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});.小程序 v1.13
微信小程序 SDK
全埋点版 SDK 集成
微信小程序 API
自定义埋点版 SDK 集成
插件版 SDK 集成
历史版本（已废弃）
支付宝小程序 SDK
自定义埋点版集成
全埋点版集成
支付宝小程序 API
百度小程序 SDK
字节跳动小程序 SDK
QQ 小程序 SDK
小程序 SDK 预置属性
小程序 SDK 常见问题
快应用 SDK
微信小游戏 SDK
微信小游戏 API微信小游戏 SDK
1. 快速使用
1.1. 集成与使用
1.1.1. 下载
从 GitHub 上下载微信小游戏 SDK sensorsdata.es6.min.js
1.1.2. 引入并完成初始化
1. 把文件放入小游戏项目中，在 game.js 中通过 import 引入文件 ;
2. 调用 setPara() 接口设置初始化参数；
3. 调用 init() 接口标志初始化完成；
game.js
// sensorsdata.es6.min.js
import sa from ''sensorsdata.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: '''',
// true false
autoTrack: {
appLaunch: true,
appShow:true,
appHide:true
},
// onShareAppMessage return query( id) $MPLaunch $MPShow
allow_amend_share_path: true
});
sa.init();
注意：init() 方法必须调用，否则不会发数据。
1.1.3. 事件采集
在 game.js 中引入 sensorsdata.es6.min.js 之后，可以调用 track() 方法采集数据。我们提供两种方案在其他 js 文件中调用 track() 方法，推荐使用方
案一。
方案一：在文件顶部使用 import 引入 SDK 文件，然后调用 track() 方法。
main.js
// sensorsdata.min.js
import sa from ''sensorsdata.es6.min.js''
export default class Main {
constructor() {
this.restart()
}
restart() {
sa.track("ViewProduct",
{ ProductName: "MacBook
Pro"
})
}
}
方案二：在其他 js 文件中如： main.js 中直接通过调用 setPara() 方法时设置的 name 参数值作为变量（即示例中的 sensors ）调用 track() 方法。
main.jsexport default class Main
{ constructor() {
this.restart()
}
restart() {
sensors.track("ViewProduct",
{ ProductName: "MacBook Pro"
})
}
}
注意：直接访问 sensors 对象需要等到 SDK 注入完毕，在 SDK 没有注入完毕时调用 track() 方法会报错。
1.2. 确认数据发送成功
注意：客户有测试项目的情况下，优先建议客户使用测试项目的数据接收地址向测试项目发数据。
集成 SDK 初始化代码且使用 track() 方法进行埋点，微信开发者工具 console 会打印采集的数据，json 格式；
微信开发者工具 network 中有 sa 的图片请求，且状态码为 200，验证数据接收地址；
神策分析界面中，打开导入中的数据，点击开始刷新按钮。在微信开发者工具触发一些事件，分析后台的导入中数据可以看到数据进入；
神策分析界面中，打开埋点管理查看，已入库 1 条，证明数据采集成功；
神策分析界面中，事件分析查看数据。
2. 用户标识
如何准确的标识用户
在进行任何埋点之前，都应当先确定如何标识用户。Distinct ID 是神策用来标识用户的。在小游戏中，会有下面 3 种 ID:
1. 默认情况下，微信小游戏 SDK 会生成一个唯一的随机数，保存在微信 storage 中，我们称这个为 UUID;
2. 用户打开小游戏，可以获得微信分配给用户的 openid ，我们称这个为 openid;
3. 客户用户账号体系中产生或保存的真实用户 ID ,我们称为 "你们服务端分配给用户具体的登录 ID";
2.1. 使用 openid 作为匿名 ID
如果不做任何操作，小游戏会使用 UUID 作为 Distinct ID，但是这个 UUID 换了设备或者删除小游戏，会重新生成。所以一般情况下，我们建议使用
openid 作为 Distinct ID。
下面是常见的两种使用 openid 作为匿名 ID 的初始化方式。
方案一
game.js
/**
game.js
ES6
**/
import sa from ''sensorsdata.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: ''''
});
// openid
wx.request({
url: '' openid '',
success: function(res){
// openid ID
sa.setOpenid(res.openid);
}
complete: function(){sa.init();
}
});
注意：init() 不调用就不会发任何数据，确保获取不到 openid 的时候也有 init() 方法可执行。
方案二
game.js
/**
ES6
*/
import sa from ''sensorsdata.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: '''',
appid: ''''
});
// 1 appid appsecret
// 2setPara() appid
sa.initWithOpenid();
2.2. 匿名 ID 和用户 ID 关联
默认情况下，SDK 会分配一个匿名 ID(UUID) 来标识用户。当用户注册或登录成功时，调用 login() 方法，传入对应的用户 ID;匿名 ID 会与对应的用户 ID 进
行关联，关联成功之后视为同一个用户。
调用时机：注册成功、登录成功、初始化 SDK （如果能获取到用户 ID）都需要调用 login() 方法传入用户 ID。
game.js
/**
ES6
*/
import sa from ''sensorsdata.es6.min.js''
sa.setPara({
name: ''sensors'',
server_url: ''''
});
/**
openid ID,
**/
wx.request({
url: '' openid '',
success: function(res){
// openid ID
sa.setOpenid(res.openid);
},
complete: function(){
if(" ID"){
sa.login(" ID");
}
sa.init();
}
});
/**
UUID ID,
**/
if(" ID"){
sa.login(" ID");
}
sa.init();3. 预置事件
事件名称 触发时机 备注
$MPLaunch（小程序启 小游戏冷启动时触发
动）
$MPShow（小程序显示） 小游戏热启动或者从后台进入前台时触发 触发小游戏的 onShow 生命周期函数时触发
$MPHide（小程序进入后 小游戏进入后台时触发 触发小游戏的 onHide 生命周期函数时触发
台）
$MPShare（小程序分享） 需要调用神策定义的分享函数 sensors. 调用神策定义的分享函数 sensors.onShareAppMessage() 做分
onShareAppMessage() 享时触发
4. 预置属性
4.1. 所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔类 是否首日访问（从新用户第一次访问到当天的二十三点五十九分五十九秒之间的值都为真，之后都为假，判断标识存在微
型 信 storage 中）
$is_login_id 布尔类 是否是登录 ID（数据入库后添加）
型
$ip 字符串 SDK 发送数据请求携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器类型
$browser_version 字符串 浏览器版本
$latest_utm_source 字符串 最近一次广告系列来源
$latest_utm_medium 字符串 最近一次广告系列媒介
$latest_utm_term 字符串 最近一次广告系列字词
$latest_utm_conte 字符串 最近一次广告系列内容
nt
$latest_utm_campa 字符串 最近一次广告系列名称
ign
$latest_scene 字符串 最近一次场景值注意：如果自定义事件的触发时机早于小程序启动 $MPLaunch 和 小程序显示 $MPShow 这两个预置事件，那么首次发送自定义事件时将不会采集
$latest_utm_source、$latest_utm_medium、$latest_utm_term、$latest_utm_content、$latest_utm_campaign、$latest_scene 这些最近一次来源属性。
4.2. 预置事件具有的预置属性
4.2.1. $MPLaunch（小程序启动）事件的预置属性
字段名称 类型 说明
$scene 字符串 启动场景
$utm_source 字符串 广告系列来源
$utm_medium 字符串 广告系列媒介
$utm_term 字符串 广告系列字词
$utm_content 字符串 广告系列内容
$utm_campaign 字符串 广告系列名称
$is_first_time 布尔类型 是否首次访问，新用户首次触发这个事件标识为真
$share_distinct_id 字符串 分享者的 Distinct ID
$share_depth 数值 分享层级
$url_query 字符串 页面参数
4.2.2. $MPShow（小程序显示）事件的预置属性
字段名称 类型 说明
$scene 字符串 启动场景
$utm_source 字符串 广告系列来源
$utm_medium 字符串 广告系列媒介
$utm_term 字符串 广告系列字词
$utm_content 字符串 广告系列内容
$utm_campaign 字符串 广告系列名称
$share_distinct_id 字符串 分享者的 Distinct ID
$share_depth 数值 分享层级
$url_query 字符串 页面参数
4.2.3. $MPHide（小程序进入后台）事件的预置属性
字段名称 类型 说明
$event_duration 数值 本次小程序显示 $MPShow 到小程序进入后台 $MPHide 的时间，单位：秒
4.2.4. $MPShare（小程序分享）事件的预置属性
字段名称 类型 说明
$share_depth 数值 分享层级
4.3. 预置用户属性
当用户首次访问集成了 SDK 的小游戏时，神策微信小游戏 SDK 会自动采集以下用户属性
字段名称 类型 说明$first_visit_time 日期 首次访问时间
$utm_source 字符串 首次访问广告系列来源
$utm_medium 字符串 首次访问广告系列媒介
$utm_term 字符串 首次访问广告系列字词
$utm_content 字符串 首次访问广告系列内容
$utm_campaign 字符串 首次访问广告系列名称
5. 实际案例使用
先把下载下来的 sensorsdata.es6.min.js 放在项目中的 utils 目录下
5.1. 在根目录的 game.js 中加入
game.js
immapino.rjst sa from ''./utils/sensorsdata.es6.min.js''
sa.setPara({
import sanamfer:om''s''e.n.s/ourtsi''l,s/sensorsdata.es6.min.js''
export desfearuvletr_ucrlla:ss''''Main {
}); constructor()
/** { this.aniId =
0openid ID,
**/ this.restart()
wx.re}quest({
restaurrtl(:)''{openid '',
sduactcaebsuss:.refsuentc(t)ion(res){
//// orpeesntiadrtIDrestart
sa.star.ascekt(O"preensitda(rrte"s,.op{enid);
}, restartX: 223,
complete: functiorne(s)t{artY: 235
i}f)(" ID"){
sa.login(" ID");
} }
sa.init();
}
});
// , profile
sa.setProfile({
name:''guoguo'',
age:18
});
5.2. 在其他 js 文件顶部使用 import 引入 SDK 文件，然后调用 track() 方法微信小游戏 API
1. 初始化相关 API
1.1. setPara( args );
说明：用来配置初始化参数；
参数：args : Object , 初始化参数对象，可配置的属性如下
name: String , SDK 使用的一个默认的全局变量,会在全局对象 GameGlobal ，其他 js 文件中可以通过 [name].track() 来使用，默认值是
sensors 。
appid: String , (非必填参数)如果需要使用 initWithOpenid() 方法来完成初始化，需要在神策后端配置 appid 和 appsecret ，同时在这里指
定 appid 。
server_url: String , 数据接收地址，注意: 请在微信公众平台---开发---开发设置---服务器域名中，把这个地址添加上。
autoTrack: Object , 是否开启自动采集，三个属性参数( appLaunch、 appShow、 appHide )的值默认为 true，即采集三个事件
$MPLaunch、$MPShow、$MPHide。
show_log: Boolean , 设置 true 后会在模拟器控制台打 log，会显示发送的数据，设置 false 表示不显示。默认为 true 。
send_timeout: Number , 请求发送超时时间（如果一个请求发送后，超过规定时间，则继续发送下一条数据），默认为 1000 毫秒。
use_client_time: Boolean , 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端
时间，使用服务端时间，如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date
类型，那么这条数据就会使用你在属性中传入的这个时间。
allow_amend_share_path: Boolean ,设置 true 后会自动修改 wx.onShareAppMessage 中的 query 属性，新增一些参数包括当前用户的
Distinct ID 等。如果要自动采集分享信息，必须设置为 true ，默认为 true 。
batch_send: Boolean , 小游戏中是否使用批量发送数据功能，默认为 false 。
datasend_timeout: Number , 请求发送取消时间（请求发送后，在规定时间内未返回结果，则取消请求），默认为 3000 毫秒 。
source_channel: Array , 默认情况下，只会解析参数 utm_source、 utm_content、 utm_campaign、 utm_medium、 utm_term 设置到
预置事件中，可以通过配置该参数来解析其他自定义参数，例如[''from'', ''to''] 。
is_persistent_save: Boolean , 是否需要将最近一次渠道信息保存到微信 storage 中，默认为 false 。
1.2. init();
说明：用来标识小游戏 SDK 初始化完成，数据可以通过网络发送；由于会存在异步操作如获取 openid 等，冷启动等事件会先发生，这时候这个冷
启动事件的 Distinct ID 就不对了，所以我们会把先发生的操作，暂存起来，等获取到 openid 后再调用 sa.init() 才会发数据。此方法不调用，采集
的数据会被缓存在内存中，不能通过网络发送；
1.3. setOpenid();
说明：用来将匿名 ID 修改为 openid；
1.4. initWithOpenid();
说明：当客户希望使用 openid 作为匿名 ID，同时不想自己获取 openid 再修改匿名 ID，而是希望神策自动获取 openid，可以使用这个 API。
2. 采集事件数据 API
2.1. track( eventName, [properties] );
说明：采集自定义事件。
参数：
eventName：String , 必 填 ， 事 件 名 称 ； properties：
Object , 选填，为该事件设置的事件属性；
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：电商产品，可以追踪用户注册、浏览商品和
下订单等事件。
index.js
//
import sa from ''sensorsdata.min.js''
sa.track(''ViewProduct'', {
//String
ProductName: "MacBook Pro",
//Number -9E15 9E15 3
ProductPrice: 123.45,
//BOOL true false
IsAddedToFav: false
//List 500 UTF-8 255
ProductList:["apple","orange"],//DATETIME new Date() yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss
ViewTime:new Date()
});
2.2. login( userID );
说明：用来做用户关联，当传入的参数与当前 Distinct ID 不一致时，会触发 $SignUp 预置事件；
参数：
userID: String , 必填，用户 ID 或登录 ID
2.3. registerApp( properties );
说明：用来给所有事件设置公共属性，可以在 game.js 文件引入 sensorsdata.min.js 文件之后， init() 方法调用之前使用 registerApp() 方法设置
公共属性。
参数：
properties：Object , 必填，为该方法调用后的所有事件设置的事件公共属性；
app.j
s
//
import sa from ''sensorsdata.min.js''
sa.setPara({
name: ''sensors'',
server_url: ''''
});
sa.registerApp({
userLever: ''VIP3'',
userSex: ''''
});
sa.init();
2.4. quick( ''getAnonymousID'' );
说明：由于调用 login() 接口之后，Distinct ID 会由匿名 ID 变成登录 ID，所以我们提供了此方法来获取微信 storage 中匿名 ID；
参数：
getAnonymousID: String , 用来获取匿名 ID；
Returns: String
返回匿名 ID；调用 login() 接口后，再调用此方法，返回 first_id;
3. 采集用户数据 API
3.1. setProfile( properties );
说明：设置用户的属性，如果存在则覆盖。
参数：
properties：Object , 必填，要给该用户设置的用户属性；
app.j
s
sa.setProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
3.2. setOnceProfile( properties );
说明：如果不存在同名属性则设置，存在同名属性，同名属性不会重新设置。
参数：
properties：Object , 必填，要给该用户设置的用户属性；
app.jssa.setOnceProfile({
email:''xxx@xx'',
favoriteFruits: ['''', ''''],
subscribers: 7277
});
3.3. incrementProfile( properties );
说明：增加或减少一个用户的某个数值类型的 Profile，如果该用户属性不存在则自动创建。
参数：
properties：Object , 必选。
app.j
s
sa.incrementProfile({
subscribers: 5
});
3.4. appendProfile( properties );
说明：向某个用户的某个数组类型的 Profile 添加一个或者多个值。
参数：
properties：Object , 必选。
app.j
s
sa.appendProfile({
favoriteFruits: ['''', '''']
});
4. 其他 API
4.1. identify( anonymousID, [boolean]);
说明：用来修改当前小游戏访问用户的匿名 ID;
参数：
anonymousID: String ,要使用的匿名 ID;
boolean: Boolean, 设置为 true, 标识将该匿名 ID 保存到微信 storage 中；不填或者设置为 false，表示该匿名 ID 只在小游戏本次生命周
期中有效，下次冷启动后使用的仍然时修改之前的匿名 ID;
4.2. getPresetProperties();
说明：用来获取部分预置属性；由于部分预置属性是异步获取到的，所以 init() 之后立即调用该方法会只返回部分属性。
Returns: Object
返回一个包含屏幕宽高、网络类型、操作系统、操作系统版本、设备制造商、设备型号、SDK 版本属性的对象。
4.3. clearAllRegister();
说明：用来清除存储在微信 storage 中的公共属性。App 第三方框架.App 第三方框架 v1.13
React Native
Flutter Weex
（Android）
Weex（iOS）
APICloud SDK
第三方 H5 页面中嵌入 JS（Android）
第三方 H5 页面中嵌入 JS（iOS）Android & iOS SDK 在 React Native 中使用说明.React Native v1.13
神策 react-native-sensors-analytics 模块，封装了神策 Android & iOS SDK 常用 API ，使用此模块，可以在 React Native 开发的 App 中完成埋点的统
计上报。
1. 使用 npm 方式安装神策 SDK 模块
对于 React Native 开发的应用，可以使用 npm 方式集成神策 SDK。
1.1. npm 安装 react-native-sensors-analytics 模块
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
npm install sensorsdata-analytics-react-native
1.2. link react-native-sensors-analytics 模块
注意：React Native 0.60 及以上版本会 autolinking，不需要执行下边的 react-native link 命令
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
react-native link sensorsdata-analytics-react-native
2. Android 端
2.1. 集成神策的 gradle 插件、初始化 SDK
在 project 级别的 build.gradle 文件中添加 Sensors Analytics android-gradle-plugin 依赖：
buildscript {
repositories
{ jcenter()
}
dependencies {
classpath ''com.android.tools.build:gradle:2.2.3''
// android-gradle-plugin
classpath ''com.sensorsdata.analytics.android:android-gradle-plugin2:3.2.0''
}
allprojects {
repositories
{ jcenter()
}
}如下示例图：
在 主 module 的 build.gradle 文件中添加 com.sensorsdata.analytics.android 插件、神策分析 SDK 依赖：
apply plugin: ''com.android.application''
// com.sensorsdata.analytics.android
apply plugin: ''com.sensorsdata.analytics.android''
dependencies {
// Sensors Analytics SDK
implementation ''com.sensorsdata.analytics.android:SensorsAnalyticsSDK:3.2.11''
}
SensorsAnalyticsSDK 的最新版本号请参考 GitHub 更新日志。
如下示例图：
在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfigOptions() 在主线程中初始化 SDK：
import android.app.Application;
import android.content.Context;
import android.content.pm.ApplicationInfo;
import android.content.pm.PackageInfo;
import android.content.pm.PackageManager;
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;
import org.json.JSONObject;import java.util.ArrayList;
import java.util.List;
public class App extends Application {
// debug
final static String SA_SERVER_URL_DEBUG = "";
// release
final static String SA_SERVER_URL_RELEASE = "";
@Override
public void onCreate() {
super.onCreate();
// Application onCreate SDK
initSensorsDataSDK();
}
/**
* SDK
*/
private void initSensorsDataSDK()
{ try {
// SAConfigOptions
SAConfigOptions saConfigOptions = new SAConfigOptions(isDebugMode(this) ? SA_SERVER_URL_DEBUG :
SA_SERVER_URL_RELEASE);
// SAConfigOptions SDK options
saConfigOptions.setAutoTrackEventType( SensorsAna
lyticsAutoTrackEventType.APP_CLICK | //
SensorsAnalyticsAutoTrackEventType.APP_START | //
SensorsAnalyticsAutoTrackEventType.APP_END) //
.enableLog(isDebugMode(this)) // ()
.enableTrackAppCrash(); // crash
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
// SDK RN
SensorsDataAPI.sharedInstance().enableReactNativeAutoTrack();
} catch (Exception e) {
e.printStackTrace();
}
}
/**
* @param context App Context
* @return debug return true,release return false
* debug relase
*/
public static boolean isDebugMode(Context context)
{ try {
ApplicationInfo info = context.getApplicationInfo();
return (info.flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0;
} catch (Exception e) {
e.printStackTrace();
return false;
}
}
2.2. 开启 React Native 页面控件的自动采集（$AppClick）
1.7.14 及以后的版本， 支持在初始化 SDK 之后，通过 enableReactNativeAutoTrack() 方法开启 RN 页面控件点击事件的自动采集。
//SDK RN
SensorsDataAPI.sharedInstance().enableReactNativeAutoTrack();2.3. 添加埋点事件
在具体的位置添加事件埋点，以按钮点击时触发事件为例：
其中对应的事件名为：RN_AddToFav 对应的事件属性为：ProductID 和 VIP
具体操作如下图所示：
3. iOS 端
3.1. 集成并初始化 SDK
使用 CocoaPods 集成：
pod ''SensorsAnalyticsSDK''
注意：React Native 0.60 及以上版本，请在项目中执行下边命令
cd ios && pod install && cd ..
在程序的入口（如 AppDelegate.m ）中引入 SensorsAnalyticsSDK.h，并在初始化方法（如 - application:didFinishLaunchingWithOptions:
launchOptions ）中调用 sharedInstanceWithConfig: 在主线程中初始化 SDK。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
#import
#ifdef DEBUG
#define SA_SERVER_URL @"<##>"
#else
#define SA_SERVER_URL @"<##>"
#endif
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ [self initSensorsAnalyticsWithLaunchOptions:launchOptions];
return YES;
}
- (void)initSensorsAnalyticsWithLaunchOptions:(NSDictionary *)launchOptions {
// SDK options
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:
launchOptions];
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart | SensorsAnalyticsEventTypeAppEnd |
SensorsAnalyticsEventTypeAppClick ;
// SDK
[SensorsAnalyticsSDK sharedInstanceWithConfig:options];
}
3.2. 开启 React Native 页面控件的自动采集（$AppClick）对于直接集成源代码的开发者，可以在编译选项 Preprocessor Macros 中定义选项 SENSORS_ANALYTICS_REACT_NATIVE=1 开启。
（对于直接集成 SDK 工程的项目，需要在 SDK 对应的 project 中修改编译选项，在 Preprocessor Macros 中定义选项 SENSORS_ANALYTICS_
REACT_NATIVE=1）
对于使用 Cocoapods 集成神策分析 SDK 的开发者，推荐使用:
pod ''SensorsAnalyticsSDK'', :subspecs => [''ENABLE_REACT_NATIVE_APPCLICK'']
4. 在 React Native 上使用代码埋点
4.1. 在 js 文件中导入神策模块
在具体的 js 文件中导入神策模块（RNSensorsAnalyticsModule），导入模块示例如下：
import { NativeModules } from ''react-native'';
const RNSensorsAnalyticsModule = NativeModules.RNSensorsAnalyticsModule;
添加导入模块后便可进行代码埋点。
4.2. 添加埋点事件
在具体的位置添加事件埋点，以按钮点击时触发事件为例：
其中对应的事件名为：RN_AddToFav 对应的事件属性为：ProductID 和 UserLevel
具体操作如下图所示：$AppClick（ React Native 元素点击）事件的预置属性：
字段名称 类型 显示名 说明 版本
$element_type 字符串 元素类型 控件的类型（ RNView ）
$element_content 字符串 元素内容 控件文本内容.React Native v1.15
神策 react-native-sensors-analytics 模块，封装了神策 Android & iOS SDK 常用 API ，使用此模块，可以在 React Native 开发的 App 中完成埋点的统
计上报。
使用 npm 方式安装神策 SDK 模块
对于 React Native 开发的应用，可以使用 npm 方式集成神策 SDK。
npm 安装 react-native-sensors-analytics 模块
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
npm install sensorsdata-analytics-react-native
link react-native-sensors-analytics 模块
注意：React Native 0.60 及以上版本会 autolinking，不需要执行下边的 react-native link 命令
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
react-native link sensorsdata-analytics-react-native
Android 端
集成神策的 gradle 插件、初始化 SDK
在 project 级别的 build.gradle 文件中添加 Sensors Analytics android-gradle-plugin 依赖：
buildscript {
repositories
{ jcenter()
}
dependencies {
classpath ''com.android.tools.build:gradle:3.6.2''
// android-gradle-plugin
classpath ''com.sensorsdata.analytics.android:android-gradle-plugin2:3.2.0''
}
allprojects {
repositories
{ jcenter()
}
}如下示例图：
在 主 module 的 build.gradle 文件中添加 com.sensorsdata.analytics.android 插件、神策分析 SDK 依赖：
apply plugin: ''com.android.application''
// com.sensorsdata.analytics.android
apply plugin: ''com.sensorsdata.analytics.android''
dependencies {
// Sensors Analytics SDK
implementation ''com.sensorsdata.analytics.android:SensorsAnalyticsSDK:4.0.2''
}
SensorsAnalyticsSDK 的最新版本号请参考 GitHub 更新日志。
如下示例图：
在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfigOptions() 在主线程中初始化 SDK：
import android.app.Application;
import android.content.Context;
import android.content.pm.ApplicationInfo;
import android.content.pm.PackageInfo;
import android.content.pm.PackageManager;
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;
import org.json.JSONObject;import java.util.ArrayList;
import java.util.List;
public class App extends Application {
// debug
final static String SA_SERVER_URL_DEBUG = "";
// release
final static String SA_SERVER_URL_RELEASE = "";
@Override
public void onCreate() {
super.onCreate();
// Application onCreate SDK
initSensorsDataSDK();
}
/**
* SDK
*/
private void initSensorsDataSDK()
{ try {
// SAConfigOptions
SAConfigOptions saConfigOptions = new SAConfigOptions(isDebugMode(this) ? SA_SERVER_URL_DEBUG :
SA_SERVER_URL_RELEASE);
// SAConfigOptions SDK options
saConfigOptions.setAutoTrackEventType( SensorsAna
lyticsAutoTrackEventType.APP_CLICK | //
SensorsAnalyticsAutoTrackEventType.APP_START | //
SensorsAnalyticsAutoTrackEventType.APP_END) //
.enableLog(isDebugMode(this)) // ()
.enableTrackAppCrash(); // crash
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
// SDK RN
SensorsDataAPI.sharedInstance().enableReactNativeAutoTrack();
} catch (Exception e) {
e.printStackTrace();
}
}
/**
* @param context App Context
* @return debug return true,release return false
* debug relase
*/
public static boolean isDebugMode(Context context)
{ try {
ApplicationInfo info = context.getApplicationInfo();
return (info.flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0;
} catch (Exception e) {
e.printStackTrace();
return false;
}
}
开启 React Native 页面控件的自动采集（$AppClick）
1.7.14 及以后的版本， 支持在初始化 SDK 之后，通过 enableReactNativeAutoTrack() 方法开启 RN 页面控件点击事件的自动采集。
//SDK RN
SensorsDataAPI.sharedInstance().enableReactNativeAutoTrack();添加埋点事件
在具体的位置添加事件埋点，以按钮点击时触发事件为例：
其中对应的事件名为：RN_AddToFav 对应的事件属性为：ProductID 和 VIP
具体操作如下图所示：
iOS 端
集成并初始化 SDK
使用 CocoaPods 集成：
pod ''SensorsAnalyticsSDK''
注意：React Native 0.60 及以上版本，请在项目中执行下边命令
cd ios && pod install && cd ..
在程序的入口（如 AppDelegate.m ）中引入 SensorsAnalyticsSDK.h，并在初始化方法（如 - application:didFinishLaunchingWithOptions:
launchOptions ）中调用 sharedInstanceWithConfig: 在主线程中初始化 SDK。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
#import
#ifdef DEBUG
#define SA_SERVER_URL @"<##>"
#else
#define SA_SERVER_URL @"<##>"
#endif
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ [self initSensorsAnalyticsWithLaunchOptions:launchOptions];
return YES;
}
- (void)initSensorsAnalyticsWithLaunchOptions:(NSDictionary *)launchOptions {
// SDK options
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:
launchOptions];
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart | SensorsAnalyticsEventTypeAppEnd |
SensorsAnalyticsEventTypeAppClick ;
// SDK
[SensorsAnalyticsSDK sharedInstanceWithConfig:options];
}
开启 React Native 页面控件的自动采集（$AppClick）对于直接集成源代码的开发者，可以在编译选项 Preprocessor Macros 中定义选项 SENSORS_ANALYTICS_REACT_NATIVE=1 开启。
（对于直接集成 SDK 工程的项目，需要在 SDK 对应的 project 中修改编译选项，在 Preprocessor Macros 中定义选项 SENSORS_ANALYTICS_
REACT_NATIVE=1）
对于使用 Cocoapods 集成神策分析 SDK 的开发者，推荐使用:
pod ''SensorsAnalyticsSDK'', :subspecs => [''ENABLE_REACT_NATIVE_APPCLICK'']
在 React Native 上使用代码埋点
在 js 文件中导入神策模块
在具体的 js 文件中导入神策模块（RNSensorsAnalyticsModule），导入模块示例如下：
import { NativeModules } from ''react-native'';
const RNSensorsAnalyticsModule = NativeModules.RNSensorsAnalyticsModule;
添加导入模块后便可进行代码埋点。
添加埋点事件
在具体的位置添加事件埋点，以按钮点击时触发事件为例：
其中对应的事件名为：RN_AddToFav 对应的事件属性为：ProductID 和 UserLevel
具体操作如下图所示：$AppClick（ React Native 元素点击）事件的预置属性：
字段名称 类型 显示名 说明 版本
$element_type 字符串 元素类型 控件的类型（ RNView ）
$element_content 字符串 元素内容 控件文本内容Android & iOS SDK 在 Flutter 中使用说明.Flutter v1.13
Android & iOS SDK 在 Flutter 中使用说明
神策 sensors_analytics_flutter_plugin 插件，封装了神策 Android & iOS SDK 常用 API ，使用此插件，可以在 Flutter 开发的 App 中完成埋点的统计上
报。
1. 在项目中添加安装插件
在 Flutter 项目的 pubspec.yam 文件中添加 sensors_analytics_flutter_plugin 依赖
dependencies:
# flutter plugin
sensors_analytics_flutter_plugin: ^1.0.1
执行 flutter packages get 命令安装插件
flutter packages get
Flutter 官网文档
2. Android 端
在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfigOptions() 在主线程中初始化 SDK：
import android.app.Application;
import android.content.Context;
import android.content.pm.ApplicationInfo;
import android.content.pm.PackageInfo;
import android.content.pm.PackageManager;
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;
import org.json.JSONObject;
import java.util.ArrayList;
import java.util.List;
public class App extends Application {
// debug
final static String SA_SERVER_URL_DEBUG = "";
// release
final static String SA_SERVER_URL_RELEASE = "";
@Override
public void onCreate()
{ super.onCreate();
// Application onCreate SDK
initSensorsDataSDK();
}
/**
* SDK
*/
private void initSensorsDataSDK()
{ try {
// SAConfigOptions
SAConfigOptions saConfigOptions = new SAConfigOptions(isDebugMode(this) ? SA_SERVER_URL_DEBUG :
SA_SERVER_URL_RELEASE);
// SAConfigOptions SDK options Flutter AppsaConfigOptions.setAutoTrackEventType(
SensorsAnalyticsAutoTrackEventType.APP_START | // App
SensorsAnalyticsAutoTrackEventType.APP_END) // App
.enableLog(isDebugMode(this)) // ()
.enableTrackAppCrash(); // crash
// SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
} catch (Exception e)
{ e.printStackTrace(
);
}
}
/**
* @param context App Context
* @return debug return true,release return false
* debug relase
*/
public static boolean isDebugMode(Context context)
{ try {
ApplicationInfo info = context.getApplicationInfo();
return (info.flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0;
} catch (Exception e)
{ e.printStackTrace(
); return false;
}
}
3. iOS 端
在程序的入口（如 AppDelegate.m ）中引入 SensorsAnalyticsSDK.h，并在初始化方法（如 - application:didFinishLaunchingWithOptions:
launchOptions ）中调用 sharedInstanceWithConfig: 在主线程中初始化 SDK。
#import "SensorsAnalyticsSDK.h"
#ifdef DEBUG
#define SA_SERVER_URL @"<##>"
#else
#define SA_SERVER_URL @"<##>"
#endif
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ [self initSensorsAnalyticsWithLaunchOptions:launchOptions];
return YES;
}
- (void)initSensorsAnalyticsWithLaunchOptions:(NSDictionary *)launchOptions {
// SDK optionsFlutter App
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:SA_SERVER_URL launchOptions:
launchOptions];
options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart | SensorsAnalyticsEventTypeAppEnd;
// SDK
[SensorsAnalyticsSDK startWithConfigOptions:options];
}
4. Flutter 中使用插件
在具体 dart 文件中导入 sensors_analytics_flutter_plugin.dart
import ''package:sensors_analytics_flutter_plugin/sensors_analytics_flutter_plugin.dart'';4.1 埋点事件
例如，触发事件名为 AddToFav ，对应的事件属性有：ProductID 和 UserLevel 的事件：
SensorsAnalyticsFlutterPlugin.track("AddToFav",{"ProductID":123456,"UserLevel":"VIP"});
4.2 设置用户属性
例如，设置用户 Age 属性：
SensorsAnalyticsFlutterPlugin.profileSet({"Age":18});Weex（Android）.Weex（Android） v1.13
1. Android SDK 在 Weex 中使用说明
1.1 集成神策分析 Android SDK
集成方式可查看 Android SDK 使用说明
2. 在 Weex 上使用代码埋点
2.1 添加神策模块文件
下载 WeexSensorsDataAnalyticsModule 文件，可 点击此处 下载，将 WeexSensorsDataAnalyticsModule.java 文件 粘贴到主 module 的包中。如下图所
示：
在你们的 Application 的 `onCreate` 方法中添加神策 WeexSensorsDataAnalyticsModule 模块。
try {
WXSDKEngine.registerModule("WeexSensorsDataAnalyticsModule", WeexSensorsDataAnalyticsModule.class);
} catch (WXException e)
{ e.printStackTrace()
;
}2.2 在 js 文件中获取神策模块
在具体的 js 文件中获取神策模块（WeexSensorsDataAnalyticsModule），示例如下：
const sa = weex.requireModule(''WeexSensorsDataAnalyticsModule'')
2.3 埋点事件
在具体的位置添加事件埋点，以按钮点击时触发事件为例：
其中对应的事件名为：RN_AddToFav 对应的事件属性为：ProductID 和 UserLevel
sa.track("AddToFav",{"ProductID":123456,"UserLevel":"VIP"})
具体操作如下图所示：Weex（iOS）.Weex（iOS） v1.13
1. 集成神策分析 iOS SDK
参照官方文档集成 weex 开发环境，神策 iOS SDK
2. 在 Weex 上使用代码埋点
2.1. 添加神策模块文件
下载 WeexSensorsDataAnalyticsModule 文件，可 点击此处 下载，并将 WeexSensorsDataAnalyticsModule.h 和 WeexSensorsDataAnalyticsModule.m
文件添加到项目中，如下图所示：
2.2. 初始化 SDK 并注册神策组件
在 -didFinishLaunchingWithOptions: 方法中初始化 SDK 并注册神策组件，如下图所示
2.2.1. 初始化代码示例
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// SDK
SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:@"YOUR_SERVER_URL" launchOptions:
launchOptions];
[SensorsAnalyticsSDK sharedInstanceWithConfig:options];// $AppStart $AppEnd
[[SensorsAnalyticsSDK sharedInstance]enableAutoTrack:
SensorsAnalyticsEventTypeAppStart|SensorsAnalyticsEventTypeAppEnd];
// weex
[WeexSDKManager setup];
// weex
[WXSDKEngine registerModule:@"WeexSensorsDataAnalyticsModule" withClass:[WeexSensorsDataAnalyticsModule
class]];
self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
self.window.backgroundColor = [UIColor whiteColor];
[self.window makeKeyAndVisible];
return YES;
}
3. JS 中的使用
3.1. 在 js 文件中获取神策模块
在具体的 js 文件中获取神策模块（WeexSensorsDataAnalyticsModule），示例如下：
const modal = weex.requireModule(''WeexSensorsDataAnalyticsModule'')
3.2. 埋点事件
在具体的位置添加事件埋点，以按钮点击时触发事件为例：
其中对应的事件名为：RN_AddToFav 对应的事件属性为：ProductID 和 UserLevel
sa.track("AddToFav",{"ProductID":123456,"UserLevel":"VIP"})
具体操作如下图所示：APICloud SDK.APICloud SDK v1.13
1. 概述
SensorsAnalyticsAPICloudSDK 封装了 Sensors Analytics 数据统计 Android & iOS SDK，使用此模块可进行用户行为数据采集。
神策分析，是针对企业级客户推出的深度用户行为分析产品，支持私有化部署，客户端、服务器、业务数据、第三方数据的全端采集和建模，驱动营销渠道
效果评估、用户精细化运营改进、产品功能及用户体验优化、老板看板辅助管理决策、产品个性化推荐改造、用户标签体系构建等应用场景。作为 PaaS 平
台支持二次开发，可通过 BI、大数据平台、CRM、ERP 等内部 IT 系统，构建用户数据体系，让用户行为数据发挥深远的价值。
2. 使用此模块需要在 config.xml 文件中配置相应的 feature
配置示例：
配置说明：
feature 名称：sensorsAnalyticsAPICloudSDK
param 参数
serverURL：(必填项，如果有特殊字符 & ，使用&) 数据接收地址 URL。
debugMode：(必填项) Debug 模式，有三种模式：
debugOff - 关闭 Debug 模式，发版 App 时使用此模式
debugAndTrack - 打开 Debug 模式，校验数据，并将数据导入神策分析系统中
debugOnly - 打开 Debug 模式，校验数据，但不进行数据导入
enableAutoTrack：(可选项) 是否采集 App 启动、App 退出事件，传入字符串 true 表示采集启动、退出事件
downloadChannel：(可选项) App 的下载渠道，配置此参数时，会触发 App 安装激活事件（AppInstall），下载渠道会存储在 DownloadChannel
字段中
enableLog：(可选项) 是否开启调试日志，传入字符串 true 表示开启调试日志。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式
会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
3. login
设置当前用户的 loginId
login({params}) loginId：
类型：字符串
描述：(必填项)用户的登录id，不能为空，且长度不能大于255
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.login({
loginId: ''123456''
});
4. registerSuperProperties
设置公共属性，设置之后，之后触发的事件会带上设置的公共属性
registerSuperProperties({params})
properties：类型：json 格式
描述：(必填项)公共属性，属性名需要满足一般变量的命名规则
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.registerSuperProperties({properties:{ PlatformType:"Android"}});
5. track
track 事件。
track({params})
event：
类型：字符串
描述：(必填项)事件名称，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
properties：
类型：json 格式
描述：(选填项)事件属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.track({
event:''ViewProduct'',
properties:{
ProductID:123456,
ProductCatalog:''Laptop Computer'',
IsAddedToFav: false
}
});
6. trackTimerStart
事件计时开始，需要和 trackTimerEnd 成对使用。
trackTimerStart({params})
event：
类型：字符串
描述：(必填项)事件名称，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.trackTimerStart({event:''ViewPage''});
7. trackTimerEnd
trackTimerEnd 计时结束，并触发事件，事件时长记录在 event_duration 字段中。计时开始和计时结束，所对应的 event 事件名必须一致。
trackTimerEnd({params})
event：
类型：字符串
描述：(必填项)事件名称，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
properties：
类型：json 格式
描述：(选填项)事件属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.trackTimerEnd({event:''ViewPage'',
properties:{
pageID:"111"
}
});
8. profileSet
profileSet 设置用户属性。
profileSet({params})
properties：
类型：json 格式
描述：(选填项)用户属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.profileSet({
properties:{
sex:""
}
});
9. profileSetOnce
profileSetOnce 设置用户首次属性。
profileSetOnce({params})
properties：
类型：json 格式
描述：(选填项)用户属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
sa.profileSet({
properties:{ fi
rstCharge:100
}
});
10. getDistinctId
getDistinctId 获取当前用户的 distinctId ，如果用户未登录时，返回值为 匿名 ID ；登录（调用login）后，返回值为 登录 ID 。
getDistinctId()
返回值类型：String 字符串
var sa = api.require(''sensorsAnalyticsAPICloudSDK'');
var distinctId = sa.getDistinctId();第三方 H5 页面中嵌入 JS（Android）.第三方 H5 页面中嵌入 JS（Android） v1.13
Android 端向第三方 H5 页面 注入 JavaScript SDK 的方案说明
如果 App 内加载一些第三方 H5 页，不能直接集成神策分析 JavaScript SDK，需要采集这些页面的埋点信息，可使用如下方式实现。
实现原理：通过 `WebView` 向第三方 H5 页面注入 JavaScript SDK ，H5 页面触发事件时，会把事件发往 App 端，App SDK 端接收到数据后保存并上
报。
1.1 集成神策分析 Android SDK
集成方式可查看 Android SDK 使用说明
1.2 初始化 WebView 后，调用 showUpWebView():
SensorsDataAPI.sharedInstance().showUpWebView(WebView webView, boolean isSupportJellyBean);
isSupportJellyBean: 是否支持API level 16及以下的版本。
因为API level 16及以下的版本, addJavascriptInterface有安全漏洞,请谨慎使用。
如果使用的是腾讯的X5 WebView ，调用 showUpX5WebView():
SensorsDataAPI.sharedInstance().showUpX5WebView(Object x5WebView);
1.3 获取要插入的 JavaScript SDK 的代码，并保存为 js 文件到主 module 的 src/main/assets
目录下
注意： js 代码中要配置上 use_app_track:true 参数
如下示例图：
1.4 在 mWebView.setWebViewClient 的 onPageFinished 方法中注入 JavaScript SDK 的代码:
// setJavaScriptEnabled
WebSettings webSettings = mWebView.getSettings();
webSettings.setJavaScriptEnabled(true);
// showUpWebViewSensorsDataAPI.sharedInstance().showUpWebView(mWebView,false);
mWebView.setWebViewClient(new WebViewClient() {
@Override
public void onPageFinished(WebView view, String url) {
// JavaScript SDK
injectSensorsDataJSSDK();
}
}
/**
*
*/
private String JSResponse;
public void injectSensorsDataJSSDK()
{ new Thread(new Runnable() {
ByteArrayOutputStream fromFile;
InputStream in;
@Override
public void run()
{ try {
// js
in = getAssets().open("inject_js_sdk.js");
int dataBlock;
byte arr[] = new byte[1024];
fromFile = new ByteArrayOutputStream();
while ((dataBlock = in.read(arr)) != -1) {
fromFile.write(arr, 0, dataBlock);
}
JSResponse = fromFile.toString();
webView.post(new Runnable() {
@Override
public void run()
{ webView.loadUrl("javascript:" +
JSResponse);
}
});
} catch (MalformedURLException e)
{ e.printStackTrace();
} catch (IOException e1)
{ e1.printStackTrace();
} finally
{ try {
if (in != null) {
in.close();
}
if (fromFile != null)
{ fromFile.close();
}
} catch (IOException e)
{ e.printStackTrace();
}
}
}
}).start();
}第三方 H5 页面中嵌入 JS（iOS）.第三方 H5 页面中嵌入 JS（iOS） v1.13
如果在 App 内有加载一些第三方 H5 页面。这些页面不能直接集成神策分析 JavaScript SDK，如果需要获取这些页面对应的埋点信息，可使用如下方式实
现。具体实现原理：通过 webView 向第三方 H5 页面自动嵌入 JavaScript sdk ,当 H5 页面触发事件时，会直接把事件发往 App 端，App 端接收到数据后
保存并上报。
为了防止 H5 不在 App 环境下浏览时，track 的事件无法通过 JavaScript SDK 发送。在初始化完 iOS SDK 之后，调用如下接口：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
[[SensorsAnalyticsSDK sharedInstance] addWebViewUserAgentSensorsDataFlag];
1. 如果是 UIWebView
加载 WebView 时，在 shouldStartLoadWithRequest: 方法中调用如下方法：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:
(UIWebViewNavigationType)navigationType {
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:request])
{ return NO;
}
//
return YES;
}
WebView 加载完成后，在 webViewDidFinishLoad: 方法中调用如下方法：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (void)webViewDidFinishLoad:(UIWebView *)webView {
[webView stringByEvaluatingJavaScriptFromString:@"var script = document.createElement(''script'');"
"script.type = ''text/javascript'';"
"script.src = \''<# SDK js #>\'';"
"document.getElementsByTagName(''head'')[0].appendChild(script);"];
}
2. 如果是 WKWebView
加载 WebView 时，在 decidePolicyForNavigationAction: 方法中调用如下方法：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:navigationAction.request])
{ decisionHandler(WKNavigationActionPolicyCancel);
return;
}
//
decisionHandler(WKNavigationActionPolicyAllow);
}
WebView 加载完成后，在 didFinishNavigation: 方法中调用如下方法：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation
{ [webView evaluateJavaScript:@"var script =
document.createElement(''script'');" "script.type = ''text/javascript'';"
"script.src = \''<# SDK js #>\'';"
"document.getElementsByTagName(''head'')[0].appendChild(script);"
completionHandler:^(id _Nullable obj, NSError * _Nullable error) {
}]; //head
}3. 注意事项
如果 H5 URL 为 https，在上面的 script.src 中使用的链接也应该是 https 协议C++ SDK.C++ SDK v1.13
在使用前，请先阅读 数据模型 的介绍。
1. 概述
本文档所介绍的 C++ SDK 是用于记录客户端埋点的（而不是服务端），例如在 MFC 程序中集成，以收集用户在程序界面上的操作。若需要服务端埋点，
请使用 C SDK。
本 SDK 区别于其他 SDK 在于将数据通过网络发送到服务端需要在代码适当的位置显式调用 Flush() 函数：
1. 将数据发送到服务端需要有可用的网络连接；
2. 在适当的位置调用，如后台线程，避免阻塞界面操作等。
进程退出时，若内存中仍有未 Flush 发送到服务端的数据，则会将数据保存到指定的暂存文件里，下次 Flush 时会从文件加载一起发送。可以通过参数调整
最多暂存的数据条数，若未发送的数据条数超过该值，则从最早的数据开始淘汰。
对暂存文件的读写未使用文件锁，请避免多进程操作同一个文件。
2. 集成神策分析 SDK
SDK 源文件可从 https://github.com/sensorsdata/sa-sdk-cpp 获取。使用时可以将代码直接集成到目标项目中，或先编译为库再引入，SDK 源代码包
括：
./include/sensors_analytics_sdk.h
./src/sensors_analytics_sdk.cpp
SDK 依赖的第三方库包括：
1. curl：用于网络请求；
2. zlib：用于 gzip 压缩。
其他说明：
github 上的 vs2005 分支代码支持在 Visual Studio 2005 版本的 C++ 下编译使用。
若直接引入源代码文件并使用 Visual Studio 编译报错，请看最开始的报错是否是“warning C4819: 该文件包含不能在当前代码页(936)中表示的字
符。请将该文件保存为 Unicode 格式以防止数据丢失”，可以将引入的几个代码文件“文件->高级保存选项->编码->Unicode-代码页1200”然后保存
再尝试编译。VS2017 及以上可以搜索 “Visual Studio 2017隐藏高级保存选项” 找到该功能。
字符串类型的属性值（主要是使用中文值时）需要是合法的 UTF-8 编码，否则会在 stderr 报错无法导入字段，这时请检查是否使用了 GBK 编码
（例如这个字符串所在源代码文件是用 GBK 编码保存的）。将 GBK 编码的 string 转成 UTF-8 的方法，Windows 下可以用
MultiByteToWideChar、WideCharToMultiByte；Linux 下可以用 iconv，具体方法可以搜索。
2.1. Windows 下 SDK 依赖
您可以直接尝试使用我们编译好的依赖文件，或自行编译。
2.1.1. 使用我们编译的 curl 和 zlib
我们在 Visual Studio 2005 上编译了适用 Windows XP 的 curl 和 zlib。使用方法如下：
1. 下载 curl 源代码，在项目名上右键 -> 属性 -> C/C++ -> 常规 -> “附加包含目录”添加 curl 源代码目录下的 include 目录；
2. 下载 zlib 源代码，在项目名上右键 -> 属性 -> C/C++ -> 常规 -> “附加包含目录”添加 zlib 源代码目录；
3. 下载编译好的 curl 和 zlib 库文件，在项目的“资源文件”右键 -> 添加 -> 现有项，选择 libcurl.dll、libcurl.lib、zlib.lib；
更高版本的 Visual Studio 也可以引入并使用这个预编译的库。
2.1.2. 自行编译 curl
1. 下载 curl 源码：https://curl.haxx.se/download/curl-7.61.1.zip 并解压；
2. 开始菜单中打开 Visual Studio 目录中的 VS2017的开发人员命令提示符，并切换到 curl 解压目录下的 winbuild 目录下；
3. 执行命令开始编译，见下面的代码片：
4. 编译输出在 curl 目录 builds 下。
nmake /f Makefile.vc mode=dll如需要静态编译：
nmake /f Makefile.vc mode=static ENABLE_IDN=no
如果需要静态链接 curl，需要在项目配置中：
1. 链接器 -> 常规 -> 链接库依赖，添加 libcurl_a.lib;Ws2_32.lib;Wldap32.lib;winmm.lib;Crypt32.lib
2. 在C/C++ -> 预处理器 -> 预处理器定义中，加入 CURL_STATICLIB
另外，若希望上报数据使用 HTTPS 做传输加密，建议编译 curl 时配置使用 OpenSSL 以获取更好的兼容性，或使用我们编译好的 curl。
2.1.3. 自行编译 zlib
1. 下载 zlib 源码：https://zlib.net/zlib-1.2.11.tar.gz
2. 开始菜单中打开 Visual Studio 目录中的 `VS2017的开发人员命令提示符`，并切换到 zlib 解压目录下；
3. 执行命令开始编译：
4. 编译输出在 zlib 目录下。
nmake -f win32/Makefile.msc
3. 初始化神策分析 SDK
在程序中使用
// SDK
// data_file_path:
// server_url:
// distinct_id: ID
// is_login_id: distinct_id “ ID”
// max_staging_record_count:
//
sensors_analytics::Sdk::Init(staging_file_path,
server_url,
distinct_id,
is_login_id,
max_staging_record_size);
distinct_id 是标识用户的 ID，若初始化 SDK 时无可用 ID，可以随机生成一个 UUID 作为 distinct_id，并且 is_login_id 传值为 false，并将这个 ID 保存起
来，下次初始化 SDK 时传入相同的值；若有可用的登录 ID，可以传入登录 ID的值，并且 is_login_id 传值为 true。更多关于标识用户的介绍请见 标识用户。
4. 追踪事件
首次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
用户通过
//
sensors_analytics::Sdk::Track(event_name);
sensors_analytics::Sdk::Track(event_name, event_properties);
接口记录事件。以 App 产品为例，可以这样追踪一次启动行为：
sensors_analytics::PropertiesNode event_properties;
event_properties.SetString("computer_name", "MyComputer");
sensors_analytics::Sdk::Track("OpenApp", event_properties);
4.1. 事件属性如前文中的样例，开发者追踪的事件可以自定义事件的属性，例如购买商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件
属性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 sensors_analytics::PropertiesNode 对象；
通过 PropertiesNode 的方法设置属性，属性名称必需是字符串类型，以大小写字母开头，由字母和数字组成，长度不超过100个字符；
PropertiesNode 属性值支持 String、Number、Bool、List 和 DateTime，对于神策分析中事件属性的更多约束，请参考 数据格式。
开发者可以通过以下接口，向 `PropertiesNode` 对象加入属性值，如加入 Bool 类型的属性:
sensors_analytics::PropertiesNode event_properties;
event_properties.SetBool("use_ticket", true);
其中属性名称必须为大小写字母开头、长度不超过 100 的由字母和数字组成的字符串。加入 Number 类型的属性：
event_properties.SetNumber("price", 100.0);
加入 DateTime 类型的属性，其中第一个参数为 time_t 类型，如系统函数 `time(NULL)` 的返回值，第二个参数为毫秒部分。或者直接用一个字符串作为
DateTime 类型属性的值：
event_properties.SetDateTime("view_from_time", time(NULL), 0);
event_properties.SetDateTime("view_to_time", "2018-09-12 18:02:15.234");
加入 String 类型的属性，字符串必须为 UTF-8 编码，字符串长度为实际的 UTF-8 长度，如一个汉字占 3 个字节：
event_properties.SetString("view_page_title", "title1");
std::string page_name = "page-1";
event_properties.SetString("view_page_name", page_name);
向 List 类型的属性中添加 String 对象：
std::vector item_list;
item_list.push_back("Book1");
item_list.push_back("Movie2");
event_properties.SetList("view_items", item_list);
具体使用方式，可以参考上一节中的样例。
5. 追踪登录与 ID 关联
若 Init 时使用了随机生成的设备 ID，当获取到登录 ID后，可调用 SDK 的 Login 方法将“设备 ID”与登录 ID关联：
sensors_analytics::Sdk::Login("123456");
更详细的说明请参考 标识用户，并在必要时联系我们的技术支持人员。
6. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。使用
sensors_analytics::Sdk::ProfileSet(const PropertiesNode& properties);
设置用户属性，例如在电商应用中，用户注册时，填充了一些个人信息，可以用 Profile 接口记录下来:
sensors_analytics::PropertiesNode profile_properties;
profile_properties.SetString("vip_level", "3");
sensors_analytics::Sdk::ProfileSet(profile_properties);// :
sensors_analytics::Sdk::ProfileSetNumber("Age", 26);
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
6.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用
sensors_analytics::Sdk::ProfileSetOnce(const PropertiesNode& properties);
接口记录这些属性。与 ProfileSet 接口不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创
建。因此，ProfileSetOnce 比较适用于为用户设置首次相关属性。例如：
sensors_analytics::Sdk::ProfileSetOnceString("first_visit_page", "Page567");
7. 其他
7.1. 使用 HTTPS 数据接收地址
使用 HTTPS 数据接收地址需要 curl 配置了 OpenSSL（建议）或 WinSSL（默认），我们提供的编译好的 curl 使用了 OpenSSL。
另外在某些操作系统里，curl 无法正确获取 ca-bundle，有两种方法处理：
1. 不添加 ca-bundle，不校验服务端 SSL 证书（会降低传输安全性，建议仅测试时使用）。具体做法是在 sensors_analytics_sdk.cpp 文件中搜索 C
URLOPT_SSL_VERIFYPEER，取消相关两行代码的注释；
2. 附带 ca-bundle 下载地址 。具体做法是在 sensors_analytics_sdk.cpp 文件中搜索 CURLOPT_CAINFO，取消该行注释，并指定证书文件的路
径。macOS SDK.macOS SDK v1.13
1. 源码集成 macOS SDK
1. GitHub 下载 SDK 源码
2. 将 SDK 源码拖入 App 项目中，并选中 Copy items if needed；
3. 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库：libicucore、libsqlite3 和 libz。
2. 初始化神策分析 macOS SDK
2.1. 获取数据接收地址
数据接收地址是 SDK 上报数据的目标地址，需要使用管理员账户进行获取。
2.2. 初始化 SDK 及基本配置
注意：需要在 程序入口 主线程 初始化 SDK，否则可能会丢失部分事件数据。
初始化 SDK
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
// Insert code here to initialize your application
//
[SensorsAnalyticsSDK sharedInstanceWithServerURL:<##> andDebugMode:SensorsAnalyticsDebugOff];
/** SDK [SensorsAnalyticsSDK sharedInstance] **/
/**
SDK track
*/
// log
[[SensorsAnalyticsSDK sharedInstance] enableLog:YES];
}
3. 使用神策分析 macOS SDK
3.1. 代码埋点追踪事件
神策分析 SDK 成功初始化后，可以通过 track: 和 track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性。以电商产品为例，可
以这样追踪一次购物行为
代码埋点
UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;
[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:productId],
@"ProductCatalog" : productCatalog,
@"IsAddedToFav" : isAddedToFavorites ? @YES : @NO}];
注意：
1. 事件名和属性名需要时合法变量名，且不能以 $ 开头；
2. 属性名大小写敏感，并且不同事件会共用同名属性。即若 foo 事件含有 "aaa" 属性，则后续所有事件不能使用与 "aaa" 仅大小写不同的属性(如
aAa、aaA)；3. 事件名和属性其他约束，具体请参考 数据格式；
4. Mac SDK 暂时只支持代码埋点，不支持自动埋点。
3.2. 设置事件公共属性
如果所有事件中都具有某个属性值，则可以将该属性作为公共属性，一个属性注册成公共属性后，SDK 自动会将该属性拼接到所有的埋点事件中，省去了每
次都手动添加困扰。
3.2.1. 静态公共属性
可以通过 registerSuperProperties: 注册事件公共属性，例如将应用名称作为事件的公共属性：
注册公共属性
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];
成功设置事件公共属性后，再通过 track: 追踪事件时，事件公共属性会被添加进每个事件中，例如：
//
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:123456]}];
在设置事件公共属性后，实际发送的事件中会被加入 AppName 属性，等价于：
//
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{
@"ProductID" : [NSNumber numberWithUnsignedLong:123456],
@"AppName" : @"<#YOUR APP NAME#>"
}];
3.2.2. 动态公共属性
通过 registerDynamicSuperProperties 方法设置动态公共属性，设置之后，事件触发时候 SDK 会自动实时获取 registerDynamicSuperProper
ties 中的属性添加到触发的事件中
动态公共属性
//
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary * _Nonnull{
block NSApplicationOcclusionState appState;
if (NSThread.isMainThread) {
appState = NSApplication.sharedApplication.occlusionState;
}else {
dispatch_sync(dispatch_get_main_queue(), ^{
appState = NSApplication.sharedApplication.occlusionState;
});
}
return @{@" APPState ":@(appState)};
}];
注意：动态公共属性和静态公共属性的作用相同，注册之后的所有事件都会包含这个属性。
3.3. 用户标识
3.3.1. ID 与用户标识
无论是自定义代码埋点事件还是全埋点自动采集的事件，神策中每个事件都会关联到一个 ID 上，用于标识该事件所对应的用户或设备信息，我们称之为 di
stinct_id。默认情况下，用户登录前，distinct_id 是 SDK 根据设备生成的一个 匿名 ID，默认使用 mac 序列号，如果获取失败，则使用 UUID；用
户登录后，开发人员调用 login: 将用户 登录 ID 传给 SDK，后续该设备上所有事件的 distinct_id 就会变成用户所对应的 登录 ID。3.3.2. ID 绑定和用户关联
用户登录前，distinct_id 为 匿名 ID；用户登录后，distinct_id 为 登录 ID。为了将用户登录前后的事件序列串联起来，神策分析采用了用户关联机
制：调用 login: 接口时，后台会尝试将 匿名 ID 和 登录 ID 关联起来，并生成一个新的 user_id，并在神策分析中使用 user_id 作为标识用户和计算
指标的依据。 SDK 内部做了逻辑处理，多次调用 login: 传入相同的 登录 ID 时，SDK 会进行忽略。为了保证用户关联的覆盖率，在如下时机时均需要调
用 login: 进行用户关联：
1. 用户注册或登录成功时，需调用 login: 进行用户关联
2. App 启动时，若当前为已登录用户，需调用 login: 传入登录 ID 进行用户关联
[[SensorsAnalyticsSDK sharedInstance] login:<# ID#>];
4. macOS SDK 中预置属性
字段名称 类型 显示名 说明
$app_version 字符串 应用版本 应用的版本
$lib 字符串 SDK类型 例如 macOS
$lib_version 字符串 SDK版本
$manufacturer 字符串 设备制造商 例如Apple
$model 字符串 设备型号 例如 x86_64
$os 字符串 操作系统 例如 macOS
$os_version 字符串 操作系统版本 例如 10.15.2
$screen_height 数值 屏幕高度 例如 1440
$screen_width 数值 屏幕宽度 例如 2560
$wifi BOOL 是否wifi
$network_type 字符串 网络类型 例如 WIFI
$is_first_day 布尔值 是否首日访问
$device_id 字符串 设备ID 默认获取 序列号，获取不到则获取UUID。.macOS SDK v1.16
1. 源码集成 macOS SDK
1. GitHub 下载 SDK 源码
2. 将 SDK 源码拖入 App 项目中，并选中 Copy items if needed；
3. 项目设置 "Build Phase" -> "Link Binary With Libraries" 中添加依赖库：libicucore、libsqlite3 和 libz。
2. 初始化神策分析 macOS SDK
2.1. 获取数据接收地址
数据接收地址是 SDK 上报数据的目标地址，需要使用管理员账户进行获取。
re
2.2. 初始化 SDK 及基本配置
注意：需要在程序入口主线程初始化 SDK，否则可能会丢失部分事件数据。
初始化 SDK
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
//
[SensorsAnalyticsSDK sharedInstanceWithServerURL:<##> andDebugMode:SensorsAnalyticsDebugOff];
/* SDK [SensorsAnalyticsSDK sharedInstance] track */
// log
[[SensorsAnalyticsSDK sharedInstance] enableLog:YES];
}
3. 使用神策分析 macOS SDK
3.1. 代码埋点追踪事件
神策分析 SDK 成功初始化后，可以通过 track: 和 track:withProperties: 方法追踪用户行为事件，并为事件添加自定义属性。以电商产品为例，可
以这样追踪一次购物行为
代码埋点
UInt64 productId = 123456;
NSString *productCatalog = @"Laptop Computer";
BOOL isAddedToFavorites = NO;
[[SensorsAnalyticsSDK sharedInstance] track:@"ViewProduct"
withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:productId],
@"ProductCatalog" : productCatalog,
@"IsAddedToFav" : isAddedToFavorites ? @YES : @NO}];
注意：
1. 事件名和属性名需要时合法变量名，且不能以 $ 开头；
2. 属性名大小写敏感，并且不同事件会共用同名属性。即若 foo 事件含有 aaa 属性，则后续所有事件不能使用与 aaa 仅大小写不同的属性(如
aAa、aaA)；
3. 事件名和属性其他约束，具体请参考 数据格式；
4. macOS SDK 暂时只支持代码埋点，不支持全埋点。
3.2. 设置事件公共属性如果所有事件中都具有某个属性值，则可以将该属性作为公共属性，一个属性注册成公共属性后，SDK 自动会将该属性拼接到所有的埋点事件中，省去了每
次都手动添加困扰。
3.2.1. 静态公共属性
可以通过 registerSuperProperties: 注册事件公共属性，例如将应用名称作为事件的公共属性：
注册公共属性
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"AppName" : @"<#YOUR APP NAME#>"}];
成功设置事件公共属性后，再通过 track: 追踪事件时，事件公共属性会被添加进每个事件中，例如：
//
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{@"ProductID" : [NSNumber numberWithUnsignedLong:123456]}];
在设置事件公共属性后，实际发送的事件中会被加入 AppName 属性，等价于：
//
[[SensorsAnalyticsSDK sharedInstance] track:@"AddToFav"
withProperties:@{
@"ProductID" : [NSNumber numberWithUnsignedLong:123456],
@"AppName" : @"<#YOUR APP NAME#>"
}];
3.2.2. 动态公共属性
通过 registerDynamicSuperProperties 方法设置动态公共属性，设置之后，事件触发时候 SDK 会自动实时获取 registerDynamicSuperProper
ties 中的属性添加到触发的事件中
动态公共属性
//
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary * _Nonnull{
block NSApplicationOcclusionState appState;
if (NSThread.isMainThread) {
appState = NSApplication.sharedApplication.occlusionState;
}else {
dispatch_sync(dispatch_get_main_queue(), ^{
appState = NSApplication.sharedApplication.occlusionState;
});
}
return @{@" APPState ":@(appState)};
}];
注意：动态公共属性和静态公共属性的作用相同，注册之后的所有事件都会包含这个属性。
3.3. 用户标识
3.3.1. ID 与用户标识
无论是自定义代码埋点事件还是全埋点自动采集的事件，神策中每个事件都会关联到一个 ID 上，用于标识该事件所对应的用户或设备信息，我们称之为 di
stinct_id。默认情况下，用户登录前，distinct_id 是 SDK 根据设备生成的一个匿名 ID，默认使用 mac 序列号，如果获取失败，则使用 UUID；用户
登录后，开发人员调用 login: 将用户登录 ID 传给 SDK，后续该设备上所有事件的 distinct_id 就会变成用户所对应的 登录 ID。
3.3.2. ID 绑定和用户关联
用户登录前，distinct_id 为匿名 ID；用户登录后，distinct_id 为登录 ID。为了将用户登录前后的事件序列串联起来，神策分析采用了用户关联机
制：调用 login: 接口时，后台会尝试将匿名 ID 和登录 ID 关联起来，并生成一个新的 user_id，并在神策分析中使用 user_id 作为标识用户和计算指标的依据。 SDK 内部做了逻辑处理，多次调用 login: 传入相同的登录 ID 时，SDK 会进行忽略。为了保证用户关联的覆盖率，在如下时机时均需要调用
login: 进行用户关联：
1. 用户注册或登录成功时，需调用 login: 进行用户关联
2. App 启动时，若当前为已登录用户，需调用 login: 传入登录 ID 进行用户关联
[[SensorsAnalyticsSDK sharedInstance] login:<# ID#>];
4. macOS SDK 中预置属性
字段名称 类型 显示名 说明
$app_version 字符串 应用版本 应用的版本
$lib 字符串 SDK类型 例如 macOS
$lib_version 字符串 SDK版本
$manufacturer 字符串 设备制造商 例如Apple
$model 字符串 设备型号 例如 MacBookPro14,1
$os 字符串 操作系统 例如 macOS
$os_version 字符串 操作系统版本 例如 10.15.2
$screen_height 数值 屏幕高度 例如 1440
$screen_width 数值 屏幕宽度 例如 2560
$wifi BOOL 是否wifi
$network_type 字符串 网络类型 例如 WiFi
$is_first_day 布尔值 是否首日访问
$device_id 字符串 设备ID 默认获取 序列号，获取不到则使用 UUID打通 App 与 H5.打通 App 与 H5 v1.13
1. 方案一：完全打通（新版方式）建议使用
H5 使用 JavaScript SDK ，采集到数据后，发往 App，App SDK 收到 JavaScript SDK 发送的数据后，首先会纠正事件中的 distinct_id，然后会把 App 端
默认的所有事件都会有的预置属性加上，最后如果 App 端设置了公共属性，也会把公共属性加上。
因此，可以通过查看 H5 页面采集的事件中，$device_id（设备 ID） ,$app_version（应用版本）等预置属性是否有值，验证 App 和 H5 是否有打通。如果
有值，则说明打通成功。反之则需要检查代码调用是否正确。
Android SDK：需要使用 v1.7.10 及之后的版本
iOS SDK：需要使用 v1.7.14 及之后的版本
JavaScript SDK：需使用 v1.7.20 及之后的版本
1.1. Android SDK 使用方法
在初始化 WebView 时，调用 showUpWebView:
SensorsDataAPI.sharedInstance().showUpWebView(WebView webView, boolean isSupportJellyBean, boolean
enableVerify);
isSupportJellyBean ：是否支持API level 16及以下的版本。
因为API level 16及以下的版本, addJavascriptInterface 有安全漏洞,请谨慎使用。
enableVerify ：是否开启数据安全验证，true 表示验证。
注意：使用 Android SDK v1.10.3 及之后的版本，开启了数据安全验证后，会验证 App 端的数据接收地址与 H5 端的数据接收地址是否一致，如果不一致
H5 端的数据将不能发往 App 端，H5 端的数据直接上报；如果一致 H5 端的数据发往 App 端统一标识用户。
如果 App 内有第三方的 H5 页面，请将 enableVerify 指定为 true
如果使用的是腾讯的 X5 WebView ，调用 showUpX5WebView:
SensorsDataAPI.sharedInstance().showUpX5WebView(Object x5WebView, boolean enableVerify);
1.2. iOS SDK 使用方法
为了确保 iOS SDK 正常接收 JavaScript SDK 端打通的数据，需要在初始化完 iOS SDK 之后，调用如下接口：
[[SensorsAnalyticsSDK sharedInstance] addWebViewUserAgentSensorsDataFlag];
然后 WebView 即将加载新的请求时，调用 [[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:request enableVerify:
YES];方法:
如果是 UIWebView
- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:
(UIWebViewNavigationType)navigationType {
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:request enableVerify:YES])
{ return NO;
}
//
return YES;
}
如果是 WKWebView
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:navigationAction.requestenableVerify:YES]) {
decisionHandler(WKNavigationActionPolicyCancel);
return;
}
//
decisionHandler(WKNavigationActionPolicyAllow);
}
enableVerify ：是否开启数据安全验证，YES 表示验证。
注意：使用 iOS SDK v1.10.3 及之后的版本，开启了数据安全验证后，会验证 App 端的数据接收地址与 H5 端的数据接收地址是否一致，如果不一致 H5
端的数据将不能发往 App 端，H5 端的数据直接上报；如果一致 H5 端的数据发往 App 端统一标识用户。
如果 App 内有第三方的 H5 页面，请将 enableVerify 指定为 YES
1.3. JavaScript SDK 使用方法
在参数配置中加入 use_app_track: true， 这时候使用 JavaScript SDK 不会直接发送数据，都会发往 App 内，通过 App 内的 SDK 发送数据。
异步载入 在参数配置中加入 use_app_track: true 示例:
在这种情况下，首先会判断外层是否有 App 的 SDK ，如果有的话，会往 App 的 SDK 发数据。如果没有，就正常发送数据。
注意：js 端开启安全验证需使用 1.10.1 及以后的版本。
1.4. App 与 H5 打通属性说明
App 与 H5 打通后，App SDK 会对 JavaScript SDK 采集的数据进行处理。
覆盖字段：
time //
distinct_id // id
$is_first_day //
$os //
$os_version //
$manufacturer //$model //
$screen_height //
$screen_width //
新增字段：
$wifi // Wifi
$network_type //
$carrier //
$app_version //
$device_id // ID
如果有 $wifi,$network_type,$app_version,$carrier 等字段，说明 App 和 H5 打通成功。
如果 JavaScript SDK 端设了和 App 端同样的公共属性，打通后 App 端公共属性会覆盖 JavaScript SDK 端相同的公共属性。
参考文档：预置属性
2. 方案二：共享 distinct_id 达到打通（老版方式）
在混合模式开发的 App 中，H5 会先获取外部 App 的 distinct_id 等信息，这样 H5 就会使用 App 的 distinct_id ，达到用户打通的目的。此方案 H5 页面
采集的数据并不会发往 App 端，而是通过 JavaScript SDK 直接上报。
2.1. Android SDK
在初始化 WebView 时，调用`showUpWebView()`:
SensorsDataAPI.sharedInstance().showUpWebView(WebView webView, boolean isSupportJellyBean);
如果需要传递其它自定义属性，可以按如下方式调用：
try {
JSONObject properties = new JSONObject();
properties.put("testKey", "testValue");
SensorsDataAPI.sharedInstance().showUpWebView(webView, isSupportJellyBean, properties);
} catch (Exception ex) {
ex.printStackTrace();
}
isSupportJellyBean: 是否支持API level 16及以下的版本。
因为API level 16及以下的版本, addJavascriptInterface有安全漏洞,请谨慎使用。
注意：v1.6.7 及之后的版本才支持该功能。
2.2. iOS SDK
需要在 WebView 加载完成时，调用[[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:request];方法:
如果是 UIWebView
- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:
(UIWebViewNavigationType)navigationType {
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:request])
{ return NO;
}
//
return YES;
}
如果需要传递其它自定义属性，可以按如下方式调用：- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:
(UIWebViewNavigationType)navigationType {
NSMutableDictionary *properties = [[NSMutableDictionary alloc] init];
[properties setValue:@"testValue" forKey:@"testKey"];
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:webView WithRequest:request andProperties:
properties]) {
return NO;
}
//
return YES;
}
如果是 WKWebView
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:_webView WithRequest:navigationAction.request])
{
decisionHandler(WKNavigationActionPolicyCancel);
return;
}
//
decisionHandler(WKNavigationActionPolicyAllow);
}
如果需要传递其它自定义属性，可以按如下方式调用：
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
NSMutableDictionary *properties = [[NSMutableDictionary alloc] init];
[properties setValue:@"testValue" forKey:@"testKey"];
if ([[SensorsAnalyticsSDK sharedInstance] showUpWebView:_webView WithRequest:navigationAction.request
andProperties:properties]) {
decisionHandler(WKNavigationActionPolicyCancel);
return;
}
//
decisionHandler(WKNavigationActionPolicyAllow);
}
注意：v1.6.14 及之后的版本才支持该功能。
2.3. JavaScript SDK
使用该功能需要使用 同步加载 JavaScript 代码的方式，即直接用 script 标签引入 SDK 代码
在代码生成工具中，选择高级设置，选择 SDK 引入方式为 同步模式。
JavaScript SDK 在 v1.6.6 之后的版本中提供一个方法 sa.getAppStatus 方法来获取 App 传递的信息，有两种使用方式。
sa.getAppStatus();：同步返回 app_info 对象
1. 在 App 打通的环境下会返回一个对象，内容如：{type: ''iOS'', distinct_id: ''123456''}。
2. 在没有打通的环境，会返回 null。
3. 这是一个即时运行的方法，可以连续被调用。
4. 在 Android 环境下，刚开始直接调用这个方法，就能取到返回值，如果只有 Android 环境，推荐使用这个方法。
5. 在 iOS 环境下，由于有调用延迟，不一定每次都能取到值。
sa.getAppStatus(function(app_info){ ... });：异步回调
1. 在 App 打通的环境下，会执行回调函数。
2. 如果没有打通，回调函数不会被调用。
3. 这个方法的主要作用，就是考虑到 iOS 的异步问题，所以会在取到数据后自动回调。
2.3.1. 示例代码
使用回调方式，JavaScript SDK 获取到 AppInfo 之后再执行应用代码，例如：sa.getAppStatus(function(app_info){
// ID
sa.identify(app_info.distinct_id);
//
sa.track("ViewHomePage");
});
需要注意的是，这个回调在没有打通时不会触发。因此，如果这个页面既会在 App 打通的环境下使用，又会在未打通的情况下使用，需要参考以下代码来实
现：
// App
function trackInApp(trackFunc) {
// App UserAgent Cookie
if (isInApp) {
sa.getAppStatus(function(app_info){ sa.ide
ntify(app_info.distinct_id);
trackFunc();
});
} else {
trackFunc();
}
}
//
trackInApp(function() {
sa.quick(''autoTrack'');
sa.track("ViewHomePage");
})
//
2.3.2. 实现原理
Android：
安卓提供 SensorsData_APP_JS_Bridge.sensorsdata_call_app 方法，JS 在载入后，会去调用 SensorsData_APP_JS_Bridge。
iOS：
JS 提供 sensorsdata_app_js_bridge_call_js 函数，JS 在载入成功后，会通知 iOS 来调用这个方法。经测试，iOS 会在 JS 加载完成之后的 500ms 以内调
用这个函数，因此存在调用延迟。Android SDK、iOS SDK 合规操作.App 合规性操作 v1.13
1. 初始化后是否开始采集数据
iOS 1.10.0+ 版本 SDK、 Android 1.10.1+ 版本 SDK 支持通过在线控制关闭 SDK，可以联系神策运维人员进行操作开启和关闭。
2. 采集的数据是否进行上报
iOS SDK 可以通过 - setFlushNetworkPolicy: 接口设置允许数据上报的网络类型，
可以通过设置 SensorsAnalyticsNetworkTypeNONE 来阻止 SDK 数据上报。待用户允许后，再调用该接口设置为相应策略即可恢复 SDK 数据上报功能。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// SDK
[[SensorsAnalyticsSDK sharedInstance] setFlushNetworkPolicy:SensorsAnalyticsNetworkTypeNONE];
// SDK
[[SensorsAnalyticsSDK sharedInstance] setFlushNetworkPolicy:SensorsAnalyticsNetworkType3G
|SensorsAnalyticsNetworkType4G
|SensorsAnalyticsNetworkTypeWIFI];
Android SDK 可以通过 setFlushNetworkPolicy 接口设置允许数据上报的网络类型，
可以通过设置 SensorsDataAPI.NetworkType.TYPE_NONE 来阻止 SDK 数据上报。待用户允许后，再调用该接口设置为相应策略即可恢复 SDK 数据上报功
能。
// SDK
SensorsDataAPI.sharedInstance().setFlushNetworkPolicy(SensorsDataAPI.NetworkType.TYPE_NONE);
// SDK
SensorsDataAPI.sharedInstance().setFlushNetworkPolicy(SensorsDataAPI.NetworkType.TYPE_3G
|SensorsDataAPI.NetworkType.TYPE_4G
|SensorsDataAPI.NetworkType.TYPE_WIFI);
3. 禁止特定属性的采集
iOS 1.11.16+ 版本 SDK 支持通过 - trackEventCallback: 接口对即将入库的数据进行修改，可以移除事件中特定属性。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName, NSMutableDictionary *properties) {
// price
properties removeObjectForKey:@"price"];
return YES;
}];
Android 3.2.10+ 版本 SDK 支持通过 setTrackEventCallBack 接口对即将入库的数据进行修改，可以移除事件中特定属性。
SensorsDataAPI.sharedInstance().setTrackEventCallBack(new SensorsDataTrackEventCallBack()
{ @Override
public boolean onTrackEvent(String eventName, JSONObject eventProperties) {
// price
eventProperties.remove("price");
return true;
}
});
4. 禁止特定埋点的采集iOS 1.11.16+ 版本 SDK 支持通过 - trackEventCallback: 接口对即将入库的数据进行修改，可以禁止特定事件入库和上报。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName, NSMutableDictionary * properties) {
// BuyProduct
if (eventName isEqualToString:@"BuyProduct"])
{ return NO;
}
return YES;
}];
Android 3.2.10+ 版本 SDK 支持通过 setTrackEventCallBack 接口对即将入库的数据进行修改，可以禁止特定事件入库和上报。
SensorsDataAPI.sharedInstance().setTrackEventCallBack(new SensorsDataTrackEventCallBack()
{ @Override
public boolean onTrackEvent(String eventName, JSONObject eventProperties) {
// BuyProduct
if(eventName.equals("BuyProduct")){
return false;
}
return true;
}
});
5. 禁止特定埋点下的特定属性的采集
iOS 1.11.16+ 版本 SDK 支持通过 - trackEventCallback: 接口对即将入库的数据进行修改，可以移除事件中特定属性。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName, NSMutableDictionary *properties) {
// BuyProduct productID
if (eventName isEqualToString:@"BuyProduct"])
{ properties
removeObjectForKey:@"productID"];
}
return YES;
}];
Android 3.2.10+ 版本 SDK 支持通过 setTrackEventCallBack 接口对即将入库的数据进行修改，可以移除事件中特定属性。
SensorsDataAPI.sharedInstance().setTrackEventCallBack(new SensorsDataTrackEventCallBack()
{ @Override
public boolean onTrackEvent(String eventName, JSONObject eventProperties) {
// BuyProduct productID
if(eventName.equals("BuyProduct")){
eventProperties.remove("productID");
}
return true;
}
});
6. 当前用户的识别 ID，用于导出数据
iOS 1.11.5+ 版本 SDK 可以通过 - distinctId 、- loginId、- anonymousId 获取相关 ID 信息，用于导出特定数据。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// distinctId
[[SensorsAnalyticsSDK sharedInstance] distinctId];
// ID
[[SensorsAnalyticsSDK sharedInstance] anonymousId]
// ID nil
[[SensorsAnalyticsSDK sharedInstance] loginId];Android 3.1.2+ 版本 SDK 可以通过 getDistinctId、getAnonymousId、getLoginId 获取相关 ID 信息，用于导出特定数据。
// distinctId
SensorsDataAPI.sharedInstance().getDistinctId();
// ID
SensorsDataAPI.sharedInstance().getAnonymousId();
// ID null
SensorsDataAPI.sharedInstance().getLoginId();
7. 删除特定用户数据的功能
iOS SDK 可以通过 - unset:、 - deleteUser 接口删除相应用户在神策系统中的属性信息。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// gender
[[SensorsAnalyticsSDK sharedInstance] unset:@"gender"];
//
[[SensorsAnalyticsSDK sharedInstance] deleteUser];
Android SDK 可以通过 profileUnset、 profileDelete 接口删除相应用户在神策系统中的属性信息。
// gender
SensorsDataAPI.sharedInstance().profileUnset("gender");
//
SensorsDataAPI.sharedInstance().profileDelete();
8. 基于接口/工具删除数据的功能
iOS SDK 可以通过 - deleteAll 接口删除本地缓存的所有事件信息。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
//
[[SensorsAnalyticsSDK sharedInstance] deleteAll];
Android SDK 可以通过 deleteAll 接口删除本地缓存的所有事件信息。
//
SensorsDataAPI.sharedInstance().deleteAll();服务端 SDK.服务端 SDK v1.13
C SDK
C SDK Demo
C# SDK
Java SDK
Java SDK Demo
Golang SDK
PHP SDK
Python SDK
Ruby SDK
Node SDKC SDK.C SDK v1.13
C SDK 使用说明
在使用前，请先阅读 数据模型 的介绍。
1. 集成神策分析 SDK
开发者可以在 C 程序中集成 神策分析 SDK，使用神策分析采集并分析用户数据。
从 GitHub 下载 神策分析 SDK 的源代码，可在本地编译，通过静态库的形式加入项目中，也可以直接将源文件引入项目中。SDK 源代码包括：
./LICENSE
./Makefile // Makefile
./sensors_analytics.h // SDK
./sensors_analytics.c // SDK
./demo.c // Demo LoggingConsumer
开发者编译 SDK 后，会生成静态库：
./output/include/sensors_analytics.h
./output/lib/libsensorsanalytics.a
SDK 符合 ANSI C99 规范，部分功能依赖 POSIX 库，不依赖第三方库。
开发者通过 C SDK 在程序中记录用户行为数据。SDK 将格式化的行为数据以日志文件的形式输出到本地磁盘文件中，开发者需要通过神策分析的 LogAgen
t 工具 将日志文件传输到神策分析中。LogAgent 工具 保证日志传输的时效性和完整性。
2. 初始化神策分析 SDK
在程序中使用
//
//
// @param consumer “”
// @param sa
//
// @return SA_OK
int sa_init(struct SAConsumer* consumer, struct SensorsAnalytics** sa);
初始化神策分析实例，通过它实现 SDK 各项功能。其中第一个参数 consumer 对象负责“消费”用户行为日志，在程序中使用
// Logging Consumer
//
// @param file_name : /data/logs/http.log
// @param consumer SALoggingConsumer
//
// @return SA_OK
int sa_init_logging_consumer(const char* file_name, SALoggingConsumer** consumer);
初始化 SALoggingConsumer 实例，它负责将用户行为日志输出到本地磁盘。
// SALogingConsumer
SALoggingConsumer* consumer = NULL;
if (SA_OK != sa_init_logging_consumer("./demo.out", &consumer))
{ fprintf(stderr, "Failed to initialize the consumer.");
return 1;
}
SensorsAnalytics *sa = NULL;if (SA_OK != sa_init(consumer, &sa))
{ fprintf(stderr, "Failed to initialize the
SDK."); return 1;
}
// ...
// Sensors Analtycis
sa_flush(sa);
// Sensors Analtycis
sa_free(sa);
3. 追踪事件
首次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
用户通过
//
//
// @param distinct_id ID
// @param event
// @param properties SAProperties NULL
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_track(distinct_id, event, properties, sa)
接口记录事件。开发者必须传入用户 ID（distinct_id）和事件名（event）两个参数，标记用户和事件名称，同时，开发者可以在第三个参数传入一个 SAPro
perties 对象，为事件添加自定义事件属性，传入 NULL 表示无自定义事件属性，在自定义属性中需要包含 $is_login_id 属性来说明 distinct_id 是否为登录
ID。以电商产品为例，可以这样追踪一次购物行为：
//
//
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
// UA iOS
assert(SA_OK == sa_add_string("$os", "iOS", strlen("iOS"), properties));
//
assert(SA_OK == sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties));
// IP $ip
assert(SA_OK == sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties));
//
assert(SA_OK == sa_add_string("product_name", "XX", 8, properties));
//
assert(SA_OK == sa_add_number("product_price", 5888, properties));
// $is_login_id distinct_id ID SA_TRUE SA_FALSE SA_FALSE
assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);
//
assert(SA_OK == sa_track(cookie_id, "SubmitOrder", properties, sa));
//
sa_free_properties(properties);
3.1 事件属性如前文中的样例，开发者追踪的事件可以自定义事件的属性，例如购买商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件
属性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 SAProperties 对象，SDK 提供接口由开发者进行初始化和释放；
SAProperties 中每个元素描述一个事件属性，属性名称必需是字符串类型，以大小写字母开头，由字母和数字组成，长度不超过100个字符；
SAProperties 中元素的值为事件属性值，支持 String、Number、Bool、List 和 Date，对于神策分析中事件属性的更多约束，请参考 数据格式。
开发者可以通过以下接口，向 SAProperties 对象加入属性值，如加入 Bool 类型的属性:
// Bool
//
// @param key
// @param bool_ SABool
// @param properties SAProperties
//
// @return SA_OK
int sa_add_bool(const char* key, SABool bool_, SAProperties* properties);
其中属性名称必须为大小写字母开头、长度不超过100的由字母和数字组成的字符串。加入 Number 类型的属性：
// Number
//
// @param key
// @param number_
// @param properties SAProperties
//
// @return SA_OK
int sa_add_number(const char* key, double number_, SAProperties* properties);
加入 Date 类型的属性，其中第一个参数为单位为秒的时间戳，如系统函数 time(NULL) 的返回值，第二个参数为毫秒部分：
// Date
//
// @param key
// @param seconds
// @param microseconds
// @param properties SAProperties
//
// @return SA_OK
int sa_add_date(const char* key, time_t seconds, int microseconds, SAProperties* properties);
加入 String 类型的属性，字符串必须为 UTF-8 编码，字符串长度为实际的 UTF-8 长度，如一个汉字占 3 个字节：
// String
//
// @param key
// @param string_
// @param length
// @param properties SAProperties
//
// @return SA_OK
向 List 类型的属性中添加 String 对象：
// List String
//
// @param key
// @param string_
// @param length
// @param properties SAProperties
//
// @return SA_OK
int sa_append_list(
const char* key,const char* string_,
unsigned int length,
SAProperties* properties);
具体使用方式，可以参考上一节中的样例。
3.1.1 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - 通过 sa_add_string() 向 SAProperties 对象加入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息；
$time - 通过 sa_add_date() 向 SAProperties 对象加入该属性，神策分析将事件时间设置为属性值的时间。请注意，神策分析默认会过滤忽略 2
年前或 1 小时后的数据，如需修改这个限制请联系我们的技术支持。
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct Id，不建议使用用户名、Email、手机号码等可以被修改的信息。
4.1 用户注册/登录
当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过
//
//
// @param distinct_id ID
// @param origin_id ID
// @param properties
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_track_signup(distinct_id, origin_id, properties, sa)
将旧的 Distinct Id 和新的 Distinct Id 关联，以保证用户分析的准确性。例如：
// SDK ...
// ID ( ID )
const char* anonymous_id = ''9771C579-71F0-4650-8EE8-8999FA717761'';
#
assert(SA_OK == sa_track(anonymous_id, "ViewProduct", NULL, sa));
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
assert(SA_OK == sa_add_string("register", "Baidu", 5, properties));
// ID
const char* login_id = "abcdefg";
//
assert(SA_OK == sa_track_signup(login_id, anonymous_id, properties, sa));
//
sa_free_properties(properties);
注意，对同一个用户，sa_track_signup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户 登录 前后的行为的关联建议在业务端实现。在神
策分析 1.13 版本之前，多次调用 sa_track_signup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说
明请参考 标识用户，并在必要时联系我们的技术支持人员。5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。使用
//
//
// @param distinct_id ID
// @param properties
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_profile_set(distinct_id, properties, sa)
设置用户属性，例如在电商应用中，用户注册时，填充了一些个人信息，可以用Profile接口记录下来:
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
assert(SA_OK == sa_add_string("register", "Baidu", 5, properties));
//
assert(SA_OK == sa_add_date("$signup_time", time(NULL), 0, properties));
//
assert(SA_OK == sa_add_bool("is_vip", SA_FALSE, properties));
// $is_login_id distinct_id ID SA_TRUE SA_FALSE SA_FALSE
assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);
//
assert(SA_OK == sa_profile_set(login_id, properties, sa));
sa_free_properties(properties);
对于不再需要的用户的一个属性，可以通过
//
//
// @param distinct_id ID
// @param key
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_profile_unset(distinct_id, key, sa)
接口将属性删除。也可以通过
//
//
// @param distinct_id ID
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_profile_delete(distinct_id, sa)
接口将某个用户的所有属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
5.1 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用//
//
// @param distinct_id ID
// @param properties
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_profile_set_once(distinct_id, properties, sa)
接口记录这些属性。与 sa_profile_set() 接口不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动
创建。因此，sa_profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如：
//
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
assert(SA_OK == sa_add_date("first_time", time(NULL), 0, properties));
// $is_login_id distinct_id ID SA_TRUE SA_FALSE SA_FALSE
assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);
//
assert(SA_OK == sa_profile_set_once(cookie_id, properties, sa));
sa_free_properties(properties);
5.2 数值类型的属性
对于数值型的用户属性，可以使用
// Number
//
// @param distinct_id ID
// @param properties Number
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_profile_increment(distinct_id, properties, sa)
对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
//
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
assert(SA_OK == sa_add_number("pay", 5888, properties));
//
assert(SA_OK == sa_append_list("title", "VIP", 3, properties));
//
assert(SA_OK == sa_profile_increment(login_id, properties, sa));
sa_free_properties(properties);
5.3 列表类型的属性对于用户喜爱的电影、用户点评过的餐厅等属性，可以通过
// List
//
// @param distinct_id ID
// @param properties List
// @param sa SensorsAnalytics
//
// @return SA_OK
#define sa_profile_append(distinct_id, properties, sa)
接口记录列表型属性。需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。关于列表类型限制请见 数据格式 7.3 属性长度限
制。
接口样例请参考前一节中的代码。C SDK Demo.C SDK Demo v1.13
C SDK 使用样例
下面，是针对一个典型的电商产品，在后台服务端，使用神策分析 C SDK 采集数据的样例
登录样例主要展示数据的记录能力，使用者需要根据自己的需求和具体的产品形态，来设计相应的事件和属性。
/*
* Copyright (C) 2015 SensorsData
* All rights reserved.
*/
#include
#include
#include
#include
#include "sensors_analytics.h"
int main(int args, char** argv) {
(void)(args);
(void)(argv);
SALoggingConsumer* consumer = NULL;
if (SA_OK != sa_init_logging_consumer("./demo.out", &consumer))
{ fprintf(stderr, "Failed to initialize the consumer.");
return 1;
}
SensorsAnalytics *sa = NULL;
if (SA_OK != sa_init(consumer, &sa)) { fprintf(stderr,
"Failed to initialize the SDK."); return 1;
}
SAProperties* properties = NULL;
// Demo
// SA
// Demo SA Event Property
//
// 1.
const char* cookie_id = "ABCDEF123456789"; // cookieId
// 1.1
// $propertySA
//
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
// UAwindows
SA_ASSERT(SA_OK == sa_add_string("$os", "iOS", strlen("iOS"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties));
// IPSASA
SA_ASSERT(SA_OK == sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties));
//
SA_ASSERT(SA_OK == sa_add_bool("is_first_time", SA_FALSE, properties));
//
SA_ASSERT(SA_OK == sa_track(cookie_id, "ViewHomePage", properties, sa));sa_free_properties(properties);
}
// 1.2
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
SA_ASSERT(SA_OK == sa_add_date("first_time", time(NULL), 0, properties));
//
SA_ASSERT(SA_OK == sa_profile_set_once(cookie_id, properties, sa));
sa_free_properties(properties);
}
// 1.3
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
// UAwindows
SA_ASSERT(SA_OK == sa_add_string("$os", "iOS", strlen("iOS"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties));
// IPSASA
SA_ASSERT(SA_OK == sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("key_word", "XX", 8, properties));
//
SA_ASSERT(SA_OK == sa_track(cookie_id, "SearchProduct", properties, sa));
sa_free_properties(properties);
}
// 1.4
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
// UAwindows
SA_ASSERT(SA_OK == sa_add_string("$os", "iOS", strlen("iOS"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties));
// IPSASA
SA_ASSERT(SA_OK == sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("product_name", "XX", 8, properties));
// Tag
SA_ASSERT(SA_OK == sa_append_list("product_tag", "", 6, properties));
SA_ASSERT(SA_OK == sa_append_list("product_tag", "", 12, properties));
//
SA_ASSERT(SA_OK == sa_add_number("product_price", 5888, properties));
//
assert(SA_OK == sa_track(cookie_id, "ViewProduct", properties, sa));
sa_free_properties(properties);
}// 2. ID
const char* login_id = "123456";
// 2.1 track_signupIDID
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
SA_ASSERT(SA_OK == sa_add_string("register", "Baidu", 5, properties));
//
SA_ASSERT(SA_OK == sa_track_signup(login_id, cookie_id, properties, sa));
sa_free_properties(properties);
}
// 2.2 Profile
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
SA_ASSERT(SA_OK == sa_add_string("register", "Baidu", 5, properties));
//
SA_ASSERT(SA_OK == sa_add_date("$signup_time", time(NULL), 0, properties));
//
SA_ASSERT(SA_OK == sa_add_bool("is_vip", SA_FALSE, properties));
//
SA_ASSERT(SA_OK == sa_profile_set(login_id, properties, sa));
sa_free_properties(properties);
}
// 3.
// 3.1
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
// UA iOS
SA_ASSERT(SA_OK == sa_add_string("$os", "iOS", strlen("iOS"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties));
// IPSASA
SA_ASSERT(SA_OK == sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties));
//
SA_ASSERT(SA_OK == sa_add_string("product_name", "XX", 8, properties));
//
SA_ASSERT(SA_OK == sa_add_int("product_price", 5888, properties));
//
SA_ASSERT(SA_OK == sa_add_number("product_discount", 0.8, properties));
//
SA_ASSERT(SA_OK == sa_track(cookie_id, "SubmitOrder", properties, sa));
sa_free_properties(properties);
}// 3.2
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
SA_ASSERT(SA_OK == sa_add_number("pay", 5888, properties));
//
SA_ASSERT(SA_OK == sa_append_list("title", "VIP", 3, properties));
//
SA_ASSERT(SA_OK == sa_profile_increment(login_id, properties, sa));
sa_free_properties(properties);
}
// 3.3
{
properties = sa_init_properties();
if (NULL == properties) {
fprintf(stderr, "Failed to initialize the properties.");
return 1;
}
//
SA_ASSERT(SA_OK == sa_append_list("title", "VIP", 3, properties));
//
SA_ASSERT(SA_OK == sa_profile_append(login_id, properties, sa));
sa_free_properties(properties);
}
// 4.
// 4.1
{
SA_ASSERT(SA_OK == sa_profile_unset(login_id, "title", sa));
}
// 4.2
{
SA_ASSERT(SA_OK == sa_profile_delete(login_id, sa));
}
// 4.3
{
SA_ASSERT(SA_INVALID_PARAMETER_ERROR == sa_track(login_id, "time", NULL, sa));
SA_ASSERT(SA_INVALID_PARAMETER_ERROR == sa_track(login_id, "100vip", NULL, sa));
}
sa_flush(sa);
sa_free(sa);
return 0;
}CSharp SDK.C# SDK v1.13
C# SDK 使用说明
在使用前，请先阅读数据模型的介绍。
C# SDK 主要适用于服务端 .NET 框架之上的应用，目前支持 .Net Core 2.0+ 和 .Net Framework 4.6.1+；同时支持通过 NuGet 方式集成我们的 SDK。
1. 集成神策分析 SDK
在服务端 .NET 应用中集成 神策分析 SDK，使用神策分析采集并分析用户行为。
SDK 的工程源代码可以从 GitHub 下载，并选用下面的一种方法进行集成：
1. (推荐）通过 NuGet 方式直接引入我们的 SDK: https://www.nuget.org/packages/SensorsData.Analytics/
2. 对 SDK 源代码编译后从 Release 目录下取得 dll 文件用于集成；
3. 将 SDK 项目其作为模块添加进需要集成的项目中使用。
2. 初始化神策分析 SDK
2.1 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token=
{$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为
8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
2.2 在程序中初始化 SDK
在程序启动时（如 static void Main(string[] args) 方法中），调用构造函数 new SensorsAnalytics(consumer) 初始化 SDK 实例。
// LoggingConsumer SensorsAnalytics
IConsumer consumer = new LoggingConsumer("D:/test/");
SensorsAnalytics sa = new SensorsAnalytics(consumer);// Distinct Id
String distinctId = "ABCDEF123456789";
//
sa.Track(distinctId, "UserLogin");
//
// ...
// SDK
sa.Shutdown();
程序结束前需要使用 shutdown() 接口显式结束，该接口可能需要等待若干秒，直到本地缓存的数据都已发送到神策分析。
至此，我们已经可以正常使用神策分析 SDK 采集用户数据了。在开发多线程程序时，开发者可以在线程间复用神策分析实例用于记录数据。
3. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
Sensors Analytics SDK 初始化成功后，可以通过 track() 记录事件，必须包含用户 ID（distinctId ）和事件名（eventName）这两个参数，同时可以传入
一个 Dictionary 对象，为事件添加自定义事件属性，在自定义属性中需要包含 $is_login_id 属性来说明 distinct_id 是否为登录 ID。以电商
产品为例，可以这样追踪一次购物行为：
// Distinct Id
String distinctId = "ABCDEF123456789";
//
Dictionary properties = new Dictionary();
// ''$time''
properties.Add("$time", new Date());
// ''$ip'' IP IP
properties.Add("$ip", "123.123.123.123");
// $is_login_id distinct_id ID true false false
properties.Add("$is_login_id", true);
// ID
properties.Add("ProductId", "123456");
//
properties.Add("ProductCatalog", "Laptop Computer");
// Boolean
properties.Add("isAddedToFav", true);
//
sa.Track(distinctId, "ViewProduct", properties);
}
3.1 事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 Dictionary 对象
Dictionary 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型
Dictionary 中，每个元素的 Value 是属性的值，支持 String、Number、List 和 Date
对于神策分析中事件属性的更多约束，请参考 数据格式。在开发多线程程序时，开发者不能在线程间复用传入的属性对象。
3.1.1 系统预置属性
如前文中样例，事件属性中以 $ 开头的属性为系统预置属性，在自定义事件属性中填入对应 $ 开头的属性值可以覆盖这些预置属性：
$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 String 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 Date 类型。请注意，神策分析默认会过滤忽略 365 天前或 3
天后的数据，如需修改请联系我们。关于其他更多预置属性，请参考 数据格式 中 预置属性 一节。
3.1.2 事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 RegisterSuperPropperties() 将该属性设置为事件公共属性。例如电商产品中的用户等
级，常作为事件的公共属性，设置方法如下:
Dictionary properties = new Dictionary();
//
properties.Add("ServerVersion", "1.2");
//
properties.Add("Location", "BeiJing");
//
sa.RegisterSuperPropperties(properties);
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中，例如：
Dictionary properties = new Dictionary();
// IP
properties.Add("$ip", "123.123.123.123");
//
sa.Track("ABCDEF123456789", "UserLogin", properties);
在设置事件公共属性后，实际发送的事件中会被加入 ServerVersion 和 Location 属性，等价于
Dictionary properties = new Dictionary();
//
properties.Add("ServerVersion", "1.2");
properties.Add("Location", "BeiJing");
// IP
properties.Add("$ip", "123.123.123.123");
//
sa.Track("ABCDEF123456789","UserLogin", properties);
使用 ClearSuperProperties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。
4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct Id，不建议使用用户名、Email、手机号码等可以被修改的信息；
对于未注册的匿名用户：
1. 如果前端网页中使用了 JavaScript SDK，您可以在 Cookie 里面找到 key 为 sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent
解码，最后通过 JSON.parse 方法得到一个对象，对象里面的 distinct_id 即为用户所需要的。
2. 如果 APP 中嵌入了 iOS SDK 或 Android SDK，您需要自己将匿名 ID 传到服务器端应用，然后获取这个匿名 ID 作为用户标识 Distinct Id。
3. 如果您没有使用前端 SDK（JS SDK / iOS SDK / Android SDK），则服务端也要生成一个随机 ID 作为用户标识 Distinct Id。每一个随机 ID 被认为一个
独立的用户。
所有的 track 和 profile 系列方法都必须同时指定用户 ID及用户 ID 是否为登录 ID这两个参数，以便明确告知神策分析用户 ID 的类型。
4.1 用户注册/登录
当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过 trackSignUp() 将旧的 Distinct Id 和新的 Distinct Id 关联，以保证用
户分析的准确性。例如：
// ID
String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";
// ID
String registerId = "0012345678";
// / ID ID
sa.TrackSignUp(registerId, anonymousId);注意，对同一个用户，TrackSignUp() 一般情况下建议只调用一次（通常在用户注册时调用），用户登录前后的行为的关联建议在业务端实现。在神策分析
1.13 版本之前，多次调用 TrackSignUp()时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参考
如何准确的标识用户，并在必要时联系我们的技术支持人员。
5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 ProfileSet() 设置用户属性:
String distinctId = "ABCDEF123456789";
Dictionary properties = new Dictionary();
// Level VIP
properties.Add("UserLv", "Elite VIP");
// $is_login_id distinct_id ID true false false
properties.Add("$is_login_id", true);
sa.ProfileSet(distinctId, properties);
对于不再需要的用户属性，可以通过 ProfileUnset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
5.1 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 ProfileSetOnce()记录这些属性。与 ProfileSet()接口不同的是，如果被设置的用户属性已存在，则这条记
录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如：
String distinctId = "ABCDEF123456789";
Dictionary properties = new Dictionary();
// AdSource "App Store"
properties.Add("AdSource", "App Store");
// $is_login_id distinct_id ID true false false
properties.Add("$is_login_id", true);
sa.ProfileSetOnce(distinctId,properties);
// AdSource "AdSource" "App Store"
properties.Add("AdSource", "Search Engine");
sa.ProfileSetOnce(distinctId, properties);
5.2 数值类型的属性
对于数值型的用户属性，可以使用 ProfileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
String distinctId = "ABCDEF123456789";
Dictionary properties = new Dictionary();
// GamePlayed1
properties.Add("GamePlayed", 1);
// $is_login_id distinct_id ID true false false
properties.Add("$is_login_id", true);
sa.ProfileIncrement(distinctId,properties );
5.3 列表类型的属性对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式 7.3 属性长度限制。
String distinctId = "ABCDEF123456789";
//
List movies = new List();
movies.Add("Sicario");
movies.Add("Love Letter");
//
List games = new List();
games.Add("Call of Duty");
games.Add("Halo");
//
Dictionary properties = new Dictionary();
properties.Add("movies", movies);
properties.Add("games", games);
// $is_login_id distinct_id ID true false false
properties.Add("$is_login_id", true);
// propertiesmoviesgames
// "movies" ["Sicario", "Love Letter"]"games" ["Call of Duty", "Halo"]
sa.ProfileAppend(distinctId, properties);
// movies
// "movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.ProfileAppend(distinctId, "movies", "Dead Poets Society");
// movies
// "Love Letter"
// "movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.ProfileAppend(distinctId, "movies", "Love Letter");
6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
6.1. 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
public void ItemSet(String itemType, String itemId, Dictionary properties)
//
Dictionary properties = new Dictionary();
properties.put("name", "C++ Primer");
properties.put("price", 31.54);
sensorsAnalytics.ItemSet("book", "0321714113", properties);
6.2. 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
public void ItemDelete(String itemType, String itemId);
//
sensorsAnalytics.itemDelete("book", "0321714113");7. 设置神策分析 SDK
以下内容说明如何更精细地控制神策分析 SDK 的行为。
7.1. 数据采集
C# SDK 主要由以下两个组件构成:
SensorsAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例。
Consumer: Consumer 会进行实际的数据发送
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:
LoggingConsumer: 用于将数据输出到指定目录，在生产环境中需使用 LoggingConsumer 并配合 LogAgent 工具上报数据，该工具能保证导入的数
据不重复、不遗漏。
// LoggingConsumer SensorsAnalytics
// "D:/test/" "yyyyMMdd.txt"
IConsumer consumer = new LoggingConsumer("D:/test/");
SensorsAnalytics sa = new SensorsAnalytics(consumer);
//
// ...
// SDK
sa.Shutdown();Java SDK.Java SDK v1.13
Java SDK 主要用于服务端 Java 应用，对于 Android App，请使用 Android SDK。
1. 集成神策分析 SDK
在服务端 Java 应用中集成 Java SDK，使用神策分析采集并分析用户行为。
我们推荐使用 Maven 管理 Java 项目，请在 pom.xml 文件中，添加以下依赖信息，Maven 将自动获取神策分析 SDK 并更新项目配置。
// ...
com.sensorsdata.analytics.javasdk
SensorsAnalyticsSDK
3.1.15
若出现依赖冲突的问题（例如运行时找不到类），可以使用 standalone 版本：将上面的 version 替换为 3.1.15-standalone。
如果不使用 Maven，也可以用下面任意一种方式集成：
直接从 GitHub 下载 Java SDK 的源代码，并将其作为模块添加进项目中使用；
下载 SensorsAnalyticsSDK-3.1.15-standalone.jar 并添加到项目使用。
最新版本的神策 Java SDK 支持的 JDK 最低版本为 Java 7，神策 Java SDK 3.1.9 版支持 JDK 1.6。
2. 初始化神策分析 SDK
2.1. 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
2.2. 在程序中初始化 SDK
在程序启动时（如 public static void main(String[] args) 方法中），调用构造函数 new SensorsAnalytics(Consumer) 初始化 Java SDK 实例。
// ConcurrentLoggingConsumer SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(new SensorsAnalytics.ConcurrentLoggingConsumer(""));
// Distinct ID
String distinctId = "ABCDEF123456789";
//
sa.track(distinctId, true, "UserLogin");
//
// ...
// Java SDK
sa.shutdown();
在生产环境中使用 ConcurrentLoggingConsumer，并结合 LogAgent 工具完成数据采集，具体信息请参考文档中 设置 Java SDK 第七节 。
程序结束前需要使用 shutdown() 接口显式结束，该接口可能需要等待若干秒，直到本地缓存的数据都已落盘，程序调试时可以使用 DebugConsumer。至
此，我们已经可以正常使用神策分析 SDK 采集用户数据了。在开发多线程程序时，开发者可以在线程间复用神策分析实例用于记录数据。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线
上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
3. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析提供更准确的留存率等数据。
对于注册用户，推荐使用客户业务系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息作为 Distinct ID；
对于未注册的匿名用户，获取用户匿名 ID 的方法如下：
1. 后端获取前端 JavaScript SDK 生成的匿名 ID 的方式：
可以在 Cookie 里面找到 key 为sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解码，最后通过 JSON.parse 方法得到一个对
象，对象里面的 distinct_id 的值即为所需要的 ID
(注意，如果前端已经调用过 login 方法，那么此时 distinct_id 为登录 ID，所以需要先获取 first_id 字段的值，如果获取不到，就去获取 distinct_id 的值)。
2. 如果 App 中嵌入了 Login 方法，需要客户端使用神策提供的获取匿名 ID 接口，将匿名 ID 传给服务端，服务端使用客户端传过来的匿名 ID 作为
Distinct ID。
所有的 track 和 profile 系列方法都必须同时指定用户 ID（distinctId）和用户 ID 是否为登录 ID (isLoginId) 这两个参数，以便明确告知神策分析用户 ID 的
类型。
3.1. 用户注册/登录
通过 trackSignUp() 将匿名 ID 和登录 ID 关联，以保证用户分析的准确性。例如：
// ID, ID
String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";
String registerId = "0012345678";
// / ID ID
sa.trackSignUp(registerId, anonymousId);注意以下问题:
trackSignUp() 建议在用户注册/登录时调用。如果客户端也有采集任意事件，在注册/登录时，也需要在客户端调用一次关联方法 login() 将匿名
ID 和登录 ID 关联。 注册/登录时，客户端和服务端都各自调用一次关联方法的原因如下：
一对一关联机制下，避免出现用户注册/登录时，客户端的关联信息 $SignUp 事件没有发送成功/延迟发送到神策系统，而服务端触发的事
件( $is_login_id=true )先发送到神策系统中，导致登录 ID 自关联，从而导致登录 ID 无法再和匿名 ID 关联，客户端匿名行为和登录后的行
为识别两个用户的行为。
客户端调用一次关联方法 login() 的作用，除了将匿名 ID 和 登录 ID 关联之外，还会会将客户端标记用户的 distinctId 值从匿名 ID 切换为
登录 ID。这样查看用户行为序列时，可以很好的根据 distinctId 的值判断用户行为是登录后的行为还是匿名行为。因此强烈建议用户登录/
注册时，在客户端调用一次 login() 的同时，在服务端也调用一次 trackSignUp() 。
如果服务端只在用户登录成功之后，才会采集相关事件或者设置用户属性，要保证 track 事件/profileSet 设置用户属性（$is_login_id 设置为
true）的代码在 trackSignUp() 方法之后调用，从而可以保证先将匿名 ID 和登录 ID 关联之后，再采集登录用户的行为事件/设置用户属性。
在神策分析 1.13 版本之前，多次调用 trackSignUp() /login()时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 ID 关联的
方法。更详细的说明请参考 标识用户，并在必要时联系我们的技术支持人员。
4. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
神策分析 SDK 初始化成功后，可以通过 track() 记录事件，必须包含用户 ID（distinctId）、用户 ID 是否为登录 ID (isLoginId)、事件名（eventName）这三
个参数，同时可以传入一个 Map 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
// ConcurrentLoggingConsumer SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(new SensorsAnalytics.ConcurrentLoggingConsumer(""));
// Distinct ID
String distinctId = "ABCDEF123456789";
//
{
Map properties = new HashMap();
// ''$time''
properties.put("$time", new Date());
// ''$ip'' IP IP
properties.put("$ip", "123.123.123.123");
// ID
properties.put("ProductId", "123456");
//
properties.put("ProductCatalog", "Laptop Computer");
// Boolean
properties.put("isAddedToFav", true);
//
sa.track(distinctId, true, "ViewProduct", properties);
}
//
{
// ID
List productIdList = new ArrayList();
productIdList.add("123456");
productIdList.add("234567");
productIdList.add("345678");
Map properties = new HashMap();
properties.put("$ip", "123.123.123.123");
// ID
properties.put("OrderId", "abcdefg");
// ID List
properties.put("ProductIdList", productIdList);
//
properties.put("OrderPaid", 12.10);
//
sa.track(distinctId, true, "PaidOrder", properties);
}通过 调试模式 ，可以校验追踪的事件及属性是否正确。正常模式下，数据导入后，在神策分析中稍等片刻，便能看到追踪结果。
4.1. 事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 Map 对象；
Map 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型；
Map 中，每个元素的 Value 是属性的值，支持 String、Boolean、Number、List 和 Date。
对于神策分析中事件属性的更多约束，请参考 数据格式。在开发多线程程序时，开发者不能在线程间复用传入的属性对象。
4.1.1. 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 String 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 Date 类型。请注意，神策分析默认会过滤忽略 2 年前或 1 小时
后的数据，如需修改请联系我们；
$project - 填入该属性，神策分析某些导入工具例如 LogAgent （LogAgent 的配置中未指定 project 参数时）会将数据导入指定项目。
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
4.1.2. 事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机房
地址设置为事件的公共属性，设置方法如下:
Map properties = new HashMap();
//
properties.put("ServerVersion", "1.2");
//
properties.put("Location", "BeiJing");
//
sa.registerSuperProperties(properties);
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中，例如：
Map properties = new HashMap();
// IP
properties.put("$ip", "123.123.123.123");
//
sa.track("ABCDEF123456789", true, "UserLogin", properties);
在设置事件公共属性后，实际发送的事件中会被加入 ServerVersion 和 Location 属性，等价于
Map properties = new HashMap();
//
properties.put("ServerVersion", "1.2");
properties.put("Location", "BeiJing");
// IP
properties.put("$ip", "123.123.123.123");
//
sa.track("ABCDEF123456789", true, "UserLogin", properties);
使用 clearSuperProperties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。
5. 设置用户属性为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profileSet() 设置用户属性:
String distinctId = "ABCDEF123456789";
// Sex
sa.profileSet(distinctId, true, "Sex", "Male");
Map properties = new HashMap();
// Level VIP
properties.put("UserLv", "Elite VIP");
sa.profileSet(distinctId, true, properties);
对于不再需要的用户属性，可以通过 profileUnset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
5.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 接口不同的是，如果被设置的用户属性已存在，则这条记录
会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如：
String distinctId = "ABCDEF123456789";
// AdSource "App Store"
sa.profileSetOnce(distinctId, true, "AdSource", "App Store");
// AdSource "AdSource" "App Store"
sa.profileSetOnce(distinctId, true, "AdSource", "Search Engine");
5.2. 数值类型的属性
对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
String distinctId = "ABCDEF123456789";
// GamePlayed1
sa.profileIncrement(distinctId, true, "GamePlayed", 1);
5.3. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式 1.7.4 属性长度限制。
String distinctId = "ABCDEF123456789";
//
List movies = new ArrayList();
movies.add("Sicario");
movies.add("Love Letter");
//
List games = new ArrayList();
games.add("Call of Duty");
games.add("Halo");
//Map properties = new HashMap();
properties.put("movies", movies);
properties.put("games", games);
// propertiesmoviesgames
// "movies" ["Sicario", "Love Letter"]"games" ["Call of Duty", "Halo"]
sa.profileAppend(distinctId, true, properties);
// movies
// "movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profileAppend(distinctId, true, "movies", "Dead Poets Society");
// movies
// "Love Letter"
// "movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profileAppend(distinctId, true, "movies", "Love Letter");
6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
6.1. 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
public void itemSet(String itemType, String itemId, Map properties);
//
Map properties = new LinkedHashMap<>();
properties.put("name", "C++ Primer");
properties.put("price", 31.54);
sensorsAnalytics.itemSet("book", "0321714113", properties);
6.2. 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
public void itemDelete(String itemType, String itemId, Map properties);
//
sensorsAnalytics.itemDelete("book", "0321714113", null);
7. 设置神策分析 SDK
以下内容说明如何更精细地控制神策分析 SDK 的行为。
7.1. 数据采集
Java SDK 主要由以下两个组件构成:
SensorsAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
Consumer: Consumer 会进行实际的数据发送
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer。7.1.1. DebugConsumer
用于校验数据导入是否正确，关于 调试模式 的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试
而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。
线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// Debug Debug
final boolean SA_WRITE_DATA = true;
// DebugConsumer SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.DebugConsumer(SA_SERVER_URL, SA_WRITE_DATA));
//
// ...
// SDK
sa.shutdown();
7.1.2. ConcurrentLoggingConsumer
用于将数据输出到指定目录并按天切割生成日志，并使用 LogAgent 等工具导入，该工具能保证导入不重复、不遗漏。ConcurrentLoggingConsumer 内部有
一个 8k 的缓存队列，当缓存队列写满时落盘写入磁盘日志文件中（如果测试的数据量较少，达不到缓存上限，则数据不会落盘到日志）。缓存队列的长度可
在构造函数中设置，也可以调用 flush() 方法强制落盘。推荐在生产环境中使用 ConcurrentLoggingConsumer 导入数据。支持多个进程写同一个目录
（目录不能是 nas、nfs 类文件系统），生成的文件始终是带日期后缀的，每天一个。
LogAgent 配置文件中一定要注释掉 real_time_file_name 参数，否则无法正常导入数据。
Windows 环境中使用请参考下面关于文件锁的描述。
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa access.log.2017-01-11
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/access.log"));
// !! !! Windows ConcurrentLoggingConsumer LogAgent
//
// SensorsAnalytics sa = new SensorsAnalytics(
// new SensorsAnalytics.ConcurrentLoggingConsumer("D:\\data\\service", "D:\\var\\sa.lock"));
// LogAgent pattern
//
// ...
// SDK
sa.shutdown();
7.1.3. LoggingConsumer
已不推荐在生产环境中使用，因为在多进程下文件切分可能有问题。已使用 LoggingConsumer 的客户建议按照如下步骤切换到 ConcurrentLoggingConsu
mer：
第 1 步 停掉 LogAgent，并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步 将日志目录下的 real_time_file_name 的文件加上当前时间的后缀。
第 3 步 后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步 重新启动 LogAgent。
关于 LogAgent 操作请参见 LogAgent7.1.4. BatchConsumer
通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在
任何线上服务中。批量发送数据的 Consumer，当数据达到指定的量时（默认50条，最多可指定1000条），才将数据进行发送。也可以调用 flush() 方法去
强制发送。
// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// 50
final int SA_BULK_SIZE = 50;
//
final boolean THROW_EXCEPTION = false;
// 0 3000 6000
final int MAX_CACHE_SIZE = 0;
// BatchConsumer SensorsAnalytics
// Consumer
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.BatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, MAX_CACHE_SIZE, THROW_EXCEPTION));
//
// ...
// SDK
sa.shutdown();
7.1.5. ConsoleConsumer
用于将数据输出到特定 Writer，一般用于在生产环境的 Java 程序中处理历史数据，生成日志文件并使用 BatchImporter 等工具导入
//
final Writer writer = new PrintWriter(System.out);
// ConsoleConsumer SensorsAnalytics
final SensorsAnalytics sa = new
SensorsAnalytics( new
SensorsAnalytics.ConsoleConsumer(writer));
//
// ...
// SDK
sa.shutdown();
// Flush the writer
writer.flush();
7.2. 其它设置
导入历史数据：默认情况下，神策会过滤发生时间比较久远数据（例如 10 天之前，具体取决于服务端设置），如果想导入历史数据，可以通过开启 Time
Free 选项来绕过这个限制。
// SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(...);
// Time Free
sa.setEnableTimeFree(true);.Java SDK v1.17
Java SDK 主要用于服务端 Java 应用，对于 Android App，请使用 Android SDK。
集成神策分析 SDK
在服务端 Java 应用中集成 Java SDK，使用神策分析采集并分析用户行为。
我们推荐使用 Maven 管理 Java 项目，请在 pom.xml 文件中，添加以下依赖信息，Maven 将自动获取神策分析 SDK 并更新项目配置。
// ...
com.sensorsdata.analytics.javasdk
SensorsAnalyticsSDK
3.1.15
若出现依赖冲突的问题（例如运行时找不到类），可以使用 standalone 版本：将上面的 version 替换为 3.1.15-standalone。
如果不使用 Maven，也可以用下面任意一种方式集成：
直接从 GitHub 下载 Java SDK 的源代码，并将其作为模块添加进项目中使用；
下载 SensorsAnalyticsSDK-3.1.15-standalone.jar 并添加到项目使用。
最新版本的神策 Java SDK 支持的 JDK 最低版本为 Java 7，神策 Java SDK 3.1.9 版支持 JDK 1.6。
初始化神策分析 SDK
获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
在程序中初始化 SDK
在程序启动时（如 public static void main(String[] args) 方法中），调用构造函数 new SensorsAnalytics(Consumer) 初始化 Java SDK 实例。
// ConcurrentLoggingConsumer SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(new SensorsAnalytics.ConcurrentLoggingConsumer(""));
// Distinct ID
String distinctId = "ABCDEF123456789";
//
sa.track(distinctId, true, "UserLogin");
//
// ...
// Java SDK
sa.shutdown();
在生产环境中使用 ConcurrentLoggingConsumer，并结合 LogAgent 工具完成数据采集，具体信息请参考文档中 设置 Java SDK 第七节 。
程序结束前需要使用 shutdown() 接口显式结束，该接口可能需要等待若干秒，直到本地缓存的数据都已落盘，程序调试时可以使用 DebugConsumer。至
此，我们已经可以正常使用神策分析 SDK 采集用户数据了。在开发多线程程序时，开发者可以在线程间复用神策分析实例用于记录数据。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线
上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析提供更准确的留存率等数据。
对于注册用户，推荐使用客户业务系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息作为 Distinct ID；
对于未注册的匿名用户，获取用户匿名 ID 的方法如下：
1. 后端获取前端 JavaScript SDK 生成的匿名 ID 的方式：
可以在 Cookie 里面找到 key 为sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解码，最后通过 JSON.parse 方法得到一个对
象，对象里面的 distinct_id 的值即为所需要的 ID
(注意，如果前端已经调用过 login 方法，那么此时 distinct_id 为登录 ID，所以需要先获取 first_id 字段的值，如果获取不到，就去获取 distinct_id 的值)。
2. 如果 App 中嵌入了 Login 方法，需要客户端使用神策提供的获取匿名 ID 接口，将匿名 ID 传给服务端，服务端使用客户端传过来的匿名 ID 作为
Distinct ID。
所有的 track 和 profile 系列方法都必须同时指定用户 ID（distinctId）和用户 ID 是否为登录 ID (isLoginId) 这两个参数，以便明确告知神策分析用户 ID 的
类型。
用户注册/登录
通过 trackSignUp() 将匿名 ID 和登录 ID 关联，以保证用户分析的准确性。例如：
// ID, ID
String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";
String registerId = "0012345678";
// / ID ID
sa.trackSignUp(registerId, anonymousId);注意以下问题:
trackSignUp() 建议在用户注册/登录时调用。如果客户端也有采集任意事件，在注册/登录时，也需要在客户端调用一次关联方法 login() 将匿名
ID 和登录 ID 关联。 注册/登录时，客户端和服务端都各自调用一次关联方法的原因如下：
一对一关联机制下，避免出现用户注册/登录时，客户端的关联信息 $SignUp 事件没有发送成功/延迟发送到神策系统，而服务端触发的事
件( $is_login_id=true )先发送到神策系统中，导致登录 ID 自关联，从而导致登录 ID 无法再和匿名 ID 关联，客户端匿名行为和登录后的行
为识别两个用户的行为。
客户端调用一次关联方法 login() 的作用，除了将匿名 ID 和 登录 ID 关联之外，还会会将客户端标记用户的 distinctId 值从匿名 ID 切换为
登录 ID。这样查看用户行为序列时，可以很好的根据 distinctId 的值判断用户行为是登录后的行为还是匿名行为。因此强烈建议用户登录/
注册时，在客户端调用一次 login() 的同时，在服务端也调用一次 trackSignUp() 。
如果服务端只在用户登录成功之后，才会采集相关事件或者设置用户属性，要保证 track 事件/profileSet 设置用户属性（$is_login_id 设置为
true）的代码在 trackSignUp() 方法之后调用，从而可以保证先将匿名 ID 和登录 ID 关联之后，再采集登录用户的行为事件/设置用户属性。
在神策分析 1.13 版本之前，多次调用 trackSignUp() /login()时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 ID 关联的
方法。更详细的说明请参考 标识用户，并在必要时联系我们的技术支持人员。
追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
神策分析 SDK 初始化成功后，可以通过 track() 记录事件，必须包含用户 ID（distinctId）、用户 ID 是否为登录 ID (isLoginId)、事件名（eventName）这三
个参数，同时可以传入一个 Map 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
// ConcurrentLoggingConsumer SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(new SensorsAnalytics.ConcurrentLoggingConsumer(""));
// Distinct ID
String distinctId = "ABCDEF123456789";
//
{
Map properties = new HashMap();
// ''$time''
properties.put("$time", new Date());
// ''$ip'' IP IP
properties.put("$ip", "123.123.123.123");
// ID
properties.put("ProductId", "123456");
//
properties.put("ProductCatalog", "Laptop Computer");
// Boolean
properties.put("isAddedToFav", true);
//
sa.track(distinctId, true, "ViewProduct", properties);
}
//
{
// ID
List productIdList = new ArrayList();
productIdList.add("123456");
productIdList.add("234567");
productIdList.add("345678");
Map properties = new HashMap();
properties.put("$ip", "123.123.123.123");
// ID
properties.put("OrderId", "abcdefg");
// ID List
properties.put("ProductIdList", productIdList);
//
properties.put("OrderPaid", 12.10);
//
sa.track(distinctId, true, "PaidOrder", properties);
}通过 调试模式 ，可以校验追踪的事件及属性是否正确。正常模式下，数据导入后，在神策分析中稍等片刻，便能看到追踪结果。
事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 Map 对象；
Map 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型；
Map 中，每个元素的 Value 是属性的值，支持 String、Boolean、Number、List 和 Date。
对于神策分析中事件属性的更多约束，请参考 数据格式。在开发多线程程序时，开发者不能在线程间复用传入的属性对象。
系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 String 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 Date 类型。请注意，神策分析默认会过滤忽略 2 年前或 1 小时
后的数据，如需修改请联系我们；
$project - 填入该属性，神策分析某些导入工具例如 LogAgent （LogAgent 的配置中未指定 project 参数时）会将数据导入指定项目。
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机房
地址设置为事件的公共属性，设置方法如下:
Map properties = new HashMap();
//
properties.put("ServerVersion", "1.2");
//
properties.put("Location", "BeiJing");
//
sa.registerSuperProperties(properties);
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中，例如：
Map properties = new HashMap();
// IP
properties.put("$ip", "123.123.123.123");
//
sa.track("ABCDEF123456789", true, "UserLogin", properties);
在设置事件公共属性后，实际发送的事件中会被加入 ServerVersion 和 Location 属性，等价于
Map properties = new HashMap();
//
properties.put("ServerVersion", "1.2");
properties.put("Location", "BeiJing");
// IP
properties.put("$ip", "123.123.123.123");
//
sa.track("ABCDEF123456789", true, "UserLogin", properties);
使用 clearSuperProperties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。
设置用户属性为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profileSet() 设置用户属性:
String distinctId = "ABCDEF123456789";
// Sex
sa.profileSet(distinctId, true, "Sex", "Male");
Map properties = new HashMap();
// Level VIP
properties.put("UserLv", "Elite VIP");
sa.profileSet(distinctId, true, properties);
对于不再需要的用户属性，可以通过 profileUnset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 接口不同的是，如果被设置的用户属性已存在，则这条记录
会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如：
String distinctId = "ABCDEF123456789";
// AdSource "App Store"
sa.profileSetOnce(distinctId, true, "AdSource", "App Store");
// AdSource "AdSource" "App Store"
sa.profileSetOnce(distinctId, true, "AdSource", "Search Engine");
数值类型的属性
对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
String distinctId = "ABCDEF123456789";
// GamePlayed1
sa.profileIncrement(distinctId, true, "GamePlayed", 1);
列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 String 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式 1.7.4 属性长度限制。
String distinctId = "ABCDEF123456789";
//
List movies = new ArrayList();
movies.add("Sicario");
movies.add("Love Letter");
//
List games = new ArrayList();
games.add("Call of Duty");
games.add("Halo");
//Map properties = new HashMap();
properties.put("movies", movies);
properties.put("games", games);
// propertiesmoviesgames
// "movies" ["Sicario", "Love Letter"]"games" ["Call of Duty", "Halo"]
sa.profileAppend(distinctId, true, properties);
// movies
// "movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profileAppend(distinctId, true, "movies", "Dead Poets Society");
// movies
// "Love Letter"
// "movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profileAppend(distinctId, true, "movies", "Love Letter");
物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
public void itemSet(String itemType, String itemId, Map properties);
//
Map properties = new LinkedHashMap<>();
properties.put("name", "C++ Primer");
properties.put("price", 31.54);
sensorsAnalytics.itemSet("book", "0321714113", properties);
删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
public void itemDelete(String itemType, String itemId, Map properties);
//
sensorsAnalytics.itemDelete("book", "0321714113", null);
设置神策分析 SDK
以下内容说明如何更精细地控制神策分析 SDK 的行为。
数据采集
Java SDK 主要由以下两个组件构成:
SensorsAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
Consumer: Consumer 会进行实际的数据发送
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer。DebugConsumer
用于校验数据导入是否正确，关于 调试模式 的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试
而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。
线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// Debug Debug
final boolean SA_WRITE_DATA = true;
// DebugConsumer SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.DebugConsumer(SA_SERVER_URL, SA_WRITE_DATA));
//
// ...
// SDK
sa.shutdown();
ConcurrentLoggingConsumer
用于将数据输出到指定目录并按天切割生成日志，并使用 LogAgent 等工具导入，该工具能保证导入不重复、不遗漏。ConcurrentLoggingConsumer 内部有
一个 8k 的缓存队列，当缓存队列写满时落盘写入磁盘日志文件中（如果测试的数据量较少，达不到缓存上限，则数据不会落盘到日志）。缓存队列的长度
可在构造函数中设置，也可以调用 flush() 方法强制落盘。推荐在生产环境中使用 ConcurrentLoggingConsumer 导入数据。支持多个进程写同一个目录
（目录不能是 nas、nfs 类文件系统），生成的文件始终是带日期后缀的，每天一个。
LogAgent 配置文件中一定要注释掉 real_time_file_name 参数，否则无法正常导入数据。
Windows 环境中使用请参考下面关于文件锁的描述。
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa access.log.2017-01-11
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/access.log"));
// !! !! Windows ConcurrentLoggingConsumer LogAgent
//
// SensorsAnalytics sa = new SensorsAnalytics(
// new SensorsAnalytics.ConcurrentLoggingConsumer("D:\\data\\service", "D:\\var\\sa.lock"));
// LogAgent pattern
//
// ...
// SDK
sa.shutdown();
LoggingConsumer
已不推荐在生产环境中使用，因为在多进程下文件切分可能有问题。已使用 LoggingConsumer 的客户建议按照如下步骤切换到 ConcurrentLoggingConsu
mer：
第 1 步 停掉 LogAgent，并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步 将日志目录下的 real_time_file_name 的文件加上当前时间的后缀。
第 3 步 后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步 重新启动 LogAgent。
关于 LogAgent 操作请参见 LogAgentBatchConsumer
通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在
任何线上服务中。批量发送数据的 Consumer，当数据达到指定的量时（默认50条，最多可指定1000条），才将数据进行发送。也可以调用 flush() 方法去
强制发送。
// URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";
// 50
final int SA_BULK_SIZE = 50;
//
final boolean THROW_EXCEPTION = false;
// 0 3000 6000
final int MAX_CACHE_SIZE = 0;
// BatchConsumer SensorsAnalytics
// Consumer
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.BatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, MAX_CACHE_SIZE, THROW_EXCEPTION));
//
// ...
// SDK
sa.shutdown();
ConsoleConsumer
用于将数据输出到特定 Writer，一般用于在生产环境的 Java 程序中处理历史数据，生成日志文件并使用 BatchImporter 等工具导入
//
final Writer writer = new PrintWriter(System.out);
// ConsoleConsumer SensorsAnalytics
final SensorsAnalytics sa = new
SensorsAnalytics( new
SensorsAnalytics.ConsoleConsumer(writer));
//
// ...
// SDK
sa.shutdown();
// Flush the writer
writer.flush();
其它设置
导入历史数据：默认情况下，神策会过滤发生时间比较久远数据（例如 10 天之前，具体取决于服务端设置），如果想导入历史数据，可以通过开启 Time
Free 选项来绕过这个限制。
// SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(...);
// Time Free
sa.setEnableTimeFree(true);Java SDK Demo.Java SDK Demo v1.13
下面，是针对一个典型的电商产品，在后台服务端，使用 Java SDK 向神策分析系统发送数据的样例。
样例主要展示数据的记录能力，使用者需要根据自己的需求和具体的产品形态，来设计相应的 Event 和 Property。
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa access.log.2017-01-11 LogAgent
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/access.log"));
/*
Demo
SA
DemoSAEventProperty
*/
// 1.
String cookieId = "ABCDEF123456789"; // cookieId
Map properties = new HashMap();
// 1.1
/*
$propertySA
*/
properties.clear();
properties.put("$time", new Date()); // event
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("Channel", "baidu"); // baidu
sa.track(cookieId, false, "ViewHomePage", properties); // event
// 1.2
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("KeyWord", "XX"); //
sa.track(cookieId, false, "SearchProduct", properties); // event
// 1.3
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("ProductName", "xx"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
sa.track(cookieId, false, "ViewProduct", properties); // event
// 2.
String registerId = "123456"; // Id
// 2.1 trackSignUPIDID
sa.trackSignUp(registerId, cookieId);
//
sa.flush();
// 2.2 Profile
Map profiles = new HashMap();
profiles.put("$city", ""); //
profiles.put("$province", ""); //
profiles.put("$name", "123"); //
profiles.put("Gender", "male"); //
profiles.put("Birthday", new SimpleDateFormat("yyyy-MM-dd
HH:mm:ss").parse( "1984-11-03 " + "00:00:00")); //profiles.put("RegisterChannel", "baidu"); //
sa.profileSet(registerId, true, profiles); // ID
// 3.
// 3.1
//
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ShipPrice", 10.0); //
properties.put("OrderTotalPrice", 1234.0); //
sa.track(registerId, true, "SubmitOrder", properties); // ID
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "XX"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 1200.0); //
properties.put("ProductAmount", 1.0); //
properties.put("ProductTotalPrice", 1200.0); //
sa.track(registerId, true, "SubmitOrderDetail", properties);
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "5"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 12.0); //
properties.put("ProductAmount", 2.0); //
properties.put("ProductTotalPrice", 24.0); //
sa.track(registerId, true, "SubmitOrderDetail", properties);
// 3.2
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ShipPrice", 10.0); //
properties.put("OrderTotalPrice", 1234.0); //
properties.put("PaymentMethod", "AliPay"); //
properties.put("AllowanceAmount", 30.0); //
properties.put("PaymentAmount", 1204.0); //
sa.track(registerId, true, "PayOrder", properties);
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "XX"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 1200.0); //
properties.put("ProductAmount", 1.0); //
properties.put("ProductTotalPrice", 1200.0); //
properties.put("ProductAllowanceAmount", 30.0); //
properties.put("ProductPaymentAmount", 1170.0); //properties.put("PaymentMethod", "AliPay"); //
sa.track(registerId, true, "PayOrderDetail", properties);
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "5"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 12.0); //
properties.put("ProductAmount", 2.0); //
properties.put("ProductTotalPrice", 24.0); //
properties.put("ProductAllowanceAmount", 0.0); //
properties.put("ProductPaymentAmount", 24.0); //
properties.put("PaymentMethod", "AliPay"); //
sa.track(registerId, true, "PayOrderDetail", properties);
// 3.3
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ShipPrice", 10.0); //
properties.put("OrderTotalPrice", 1234.0); //
properties.put("PaymentMethod", "AliPay"); //
properties.put("AllowanceAmount", 30.0); //
properties.put("PaymentAmount", 1204.0); //
properties.put("CancelReason", ""); //
properties.put("CancelTiming", "AfterPay"); //
sa.track(registerId, true, "CancelOrder", properties);
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "XX"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 1200.0); //
properties.put("ProductAmount", 1.0); //
properties.put("ProductTotalPrice", 1200.0); //
properties.put("ProductAllowanceAmount", 30.0); //
properties.put("ProductPaymentAmount", 1170.0); //
properties.put("PaymentMethod", "AliPay"); //
properties.put("CancelReason", ""); //
properties.put("CancelTiming", "AfterPay"); //
sa.track(registerId, true, "CancelOrderDetail", properties);
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "5"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 12.0); //
properties.put("ProductAmount", 2.0); //
properties.put("ProductTotalPrice", 24.0); //
properties.put("ProductAllowanceAmount", 0.0); //
properties.put("ProductPaymentAmount", 24.0); //
properties.put("PaymentMethod", "AliPay"); //
sa.track(registerId, true, "CancelOrderDetail", properties);
// 4.
//properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "XX"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 1200.0); //
properties.put("ProductAmount", 1.0); //
properties.put("ProductTotalPrice", 1200.0); //
properties.put("ProductAllowanceAmount", 30.0); //
properties.put("ProductPaymentAmount", 1170.0); //
properties.put("PaymentMethod", "AliPay"); //
properties.put("SupplyTime", 49.0); // 49
properties.put("SupplyMethod", ""); //
sa.track(registerId, true, "ReceiveProduct", properties);
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "5"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 12.0); //
properties.put("ProductAmount", 2.0); //
properties.put("ProductTotalPrice", 24.0); //
properties.put("ProductAllowanceAmount", 0.0); //
properties.put("ProductPaymentAmount", 24.0); //
properties.put("PaymentMethod", "AliPay"); //
properties.put("SupplyTime", 98.0); // 98
properties.put("SupplyMethod", ""); //
sa.track(registerId, true, "ReceiveProduct", properties);
// 5.
// 5.1
//
properties.clear();
properties.put("$os", "Windows"); // UAwindows
properties.put("$os_version", "8.1"); //
properties.put("$ip", "123.123.123.123"); // IPSASA
properties.put("OrderId", "SN_123_AB_TEST"); // ID
properties.put("ProductName", "XX"); //
properties.put("ProductType", ""); //
properties.put("ShopName", "XX"); //
properties.put("ProductUnitPrice", 1200.0); //
properties.put("ProductAmount", 1.0); //
properties.put("ProductTotalPrice", 1200.0); //
properties.put("ProductAllowanceAmount", 30.0); //
properties.put("ProductPaymentAmount", 1170.0); //
properties.put("PaymentMethod", "AliPay"); //
properties.put("ServiceContent", ""); //
properties.put("ServiceStatus", ""); // sa.track(registerId,
true, "ServiceAfterSale", properties);
//
properties.put("ServiceStatus", ""); // sa.track(registerId,
true, "ServiceAfterSale", properties);
//
properties.put("ServiceStatus", ""); // sa.track(registerId,
true, "ServiceAfterSale", properties);
//
sa.flush();Golang SDK.Golang SDK v1.13
Golang SDK 使用说明
在使用前，请先阅读 数据模型 的介绍。
1. 集成神策分析 SDK
在 Golang 代码中集成 神策分析 SDK，使用神策分析采集并分析用户数据。
我们推荐 Golang 官方工具管理 Golang 项目并获取神策分析 SDK：
go get github.com/sensorsdata/sa-sdk-go
或更新本地已经存在的sdk:
go get -u github.com/sensorsdata/sa-sdk-go
也可以从 GitHub 下载 神策分析 SDK 的源代码。
SDK 需要 Golang 1.6 以上，不依赖第三方库。目前 Golang SDK 不支持 Windows。
2. 初始化神策分析 SDK
2.1 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的：http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token=
{$project_token}
数据接收地址，带端口号的：http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址：http://{$host_name}:8106/sa?project={$project_name}（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为
8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址：http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
2.2 在程序中初始化 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：
import sdk "github.com/sensorsdata/sa-sdk-go"
// URL
SA_SERVER_URL := "YOUR_SERVER_URL"
// Consumer
// DefaultConsumer Consumer
consumer, err := sdk.InitDefaultConsumer(SA_SERVER_URL, 10000)
//...
// Consumer SensorsAnalytics
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()
properties :=
map[string]interface{}{ "pric
e": 12,
"name": "apple",
}
//
err = sa.Track("ABCDEFG1234567", "ViewProduct", properties, false)
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 Close() 方
法显式关闭，否则可能丢失部分缓存的数据。
使用神策分析时，引入神策分析 SDK 后首先初始化一个 consumer，接着初始化神策分析对象。
初始化神策分析对象的接口为：
// c consumerprojectName timeFree
// 10 timeFree
func InitSensorsAnalytics(c consumers.Consumer, projectName string, timeFree bool) SensorsAnalytics
例子
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
// Close
defer sa.Close()
// ...
至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的控制神策分析 SDK 一节。
3. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
用户通过 Track() 接口记录事件，对于任何事件，必须包含用户标志符（Distinct ID）和事件名（event）两个参数。同时，用户可以在 Track() 的第三个参数
传入一个 map[string]interface{} 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：接口
// distinctId event properties isLoginId
func (sa *SensorsAnalytics) Track(distinctId, event string, properties map[string]interface{}, isLoginId bool)
error
例子
distinct_id := "ABCDEF123456"
properties := map[string]interface{}{
// "$time" datetime
"$time" : time.Now(),
// "$ip" IP IP
"$ip" : "123.123.123.123",
// ID
"ProductId" : "123456",
//
"ProductCatalog" : "Laptop Computer",
// Boolean
"IsAddedToFav" : True,
}
//
err := sa.Track(distinct_id, "ViewProduct", properties, true)
properties:= map[string]interface{}{
// IP
"$ip" : "123.123.123.123",
// ID []string
"ProductIdList" : []string{"123456", "234567", "345678"},
//
"OrderPaid" : 12.10,
}
//
err = sa.Track(distinct_id, "PaidOrder", properties, true)
3.1 事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 map[string]interface{} 对象
map 中每个元素描述一个属性，Key 为属性名称，必需是 string 类型
map 中，每个元素的 Value 是属性的值，支持 string、int、float64、[]string、time.Time
对于神策分析中事件属性的更多约束，请参考 数据格式
3.1.1 系统预置属性
如前文中样例，事件属性中以 "$" 开头的属性为系统预置属性，在自定义事件属性中填入对应 "$" 开头的属性值可以覆盖这些预置属性：
$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 string 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 time.Time 。请注意，神策分析默认会过滤忽略 365 天前或 3
天后的数据，如需修改请联系我们。
关于其他更多预置属性，请参考 数据格式 中 "预置属性" 一节。
4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。所
有的 Track 和 Profile 系列方法建议明确指定 isLoginId 参数，以便明确告知神策分析用户 ID 的类型。4.1 用户注册/登录
当同一个用户的 Distinct ID 发生变化时（一般情况为匿名用户注册行为），可以通过 TrackSignup() 将旧的 Distinct ID 和新的 Distinct ID 关联，以保证用
户分析的准确性。
接口
// distinctId ID IDoriginId ID ID
func (sa *SensorsAnalytics) TrackSignup(distinctId, originId string) error
例子
// ID
anonymous_id := "9771C579-71F0-4650-8EE8-8999FA717761"
register_id := "0012345678"
// / ID ID
err := sa.TrackSignup(register_id, anonymous_id)
注意，对同一个用户，TrackSignup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户登录前后的行为的关联建议在业务端实现。在神策分
析 1.13 版本之前，多次调用 TrackSignup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 ID 关联的方法。更详细的说明请参
考 标识用户，并在必要时联系我们的技术支持人员。
5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 ProfileSet() 设置用户属性:
接口
// distinctId properties isLoginId distinctId ID
func (sa *SensorsAnalytics) ProfileSet(distinctId string, properties map[string]interface{}, isLoginId bool)
error
例子
distinct_id := "ABCDEF123456789"
properties := map[string]interface{}{
// Sex
"Sex" : "Male",
// Level VIP
"UserLevel" : "Elite VIP",
}
//
err := sa.ProfileSet(distinct_id, properties, true)
对于不再需要的用户属性，可以通过 ProfileUnset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
5.1 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 ProfileSetOnce() 记录这些属性。与 ProfileSet() 接口不同的是，如果被设置的用户属性已存在，则这条记录
会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，ProfileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。
接口// distinctId properties isLoginId distinctId ID
func (sa *SensorsAnalytics) ProfileSetOnce(distinctId string, properties map[string]interface{}, isLoginId
bool) error
例子
distinct_id := "ABCDEF123456789"
// AdSource "App Store"
properties :=
map[string]interface{}{ "AdSource
" : "App Store",
}
err := sa.ProfileSetOnce(distinct_id, properties, true)
properties =
map[string]interface{}{ "AdSourc
e" : "Search Engine",
}
// AdSource "AdSource" "App Store"
err = sa.ProfileSetOnce(distinct_id, properties, true)
5.2 数值类型的属性
对于数值型的用户属性，可以使用 ProfileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。
接口
// distinctId properties value int isLoginId distinctId ID
func (sa *SensorsAnalytics) ProfileIncrement(distinctId string, properties map[string]interface{}, isLoginId
bool) error
例子
distinct_id := "ABCDEF123456789"
properties :=
map[string]interface{}{ "GamePlay
ed" : 1,
}
// GamePlayed1
err := sa.ProfileIncrement(distinct_id, properties, true)
5.3 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 string 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式7.3 属性长度限制。
接口
// distinctId properties value [string] isLoginId distinctId ID
func (sa *SensorsAnalytics) ProfileAppend(distinctId string, properties map[string]interface{}, isLoginId bool)
error
例子
distinct_id := "ABCDEF123456789"
properties := map[string]interface{}{
//
"Movies" : []string{"Sicario", "Love Letter"},
//
"Games" : []string{"Call of Duty", "Halo"},
}
// propertiesmoviesgames// "Movies" ["Sicario", "Love Letter"]"Games" ["Call of Duty", "Halo"]
err := sa.ProfileAppend(distinct_id, properties, true)
// Movies
// "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
properties = map[string]interface{}{
"Movies" : []string{"Dead Poets Society"},
}
err = sa.ProfileAppend(distinct_id, properties, true)
// Movies
// "Love Letter"
// "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
properties = map[string]interface{}{
"Movies" : []string{"Love Letter"},
}
err = sa.ProfileAppend(distinct_id, properties, true)
6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
6.1 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 $properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
//
itemType := "apple"
itemId := "12345"
err = sa.ItemSet(itemType, itemId, map[string]interface{}{"price": "3",})
6.2 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
//
itemType := "apple"
itemId := "12345"
err = sa.ItemDelete(itemType, itemId)
7. 设置神策分析 SDK
Golang SDK 主要由以下两个组件构成:
SensorsAnalytics：用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
Consumer：Consumer 会进行实际的数据发送
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer：
LoggingConsumer
ConcurrentLoggingConsumer
DebugConsumer
DefaultConsumer
BatchConsumer
7.1 LoggingConsumer(推荐)
用于将数据输出到指定目录并按天切割文件，支持通过参数指定是否按小时切割，一般用来处理实时数据，生成日志文件并使用 LogAgent 等工具导入。初始化接口
// filename hourRotate
func InitLoggingConsumer(filename string, hourRotate bool) (*consumers.LoggingConsumer, error)
例子
import sdk "github.com/sensorsdata/sa-sdk-go"
// LoggingConsumer
consumer, err := sdk.InitLoggingConsumer("/data/sa/access.log", false)
// ...
// Consumer SensorsAnalytics
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()
// ...
LoggingConsumer 的第一个参数是保存文件前缀，第二个参数表示是否启用按小时切割，默认是每天 0 点切割保留所有文件。
按小时切割关闭的情况下，文件将保存在以 prefix.YYYY-MM-DD（例如：假设 prefix 为 /data/sa/access.log，当天是 2018-04-13，则输出文
件为 /data/sa/access.log.2018-03-13）
按小时切割开启的情况下，在小时整点切割，文件将保存在以 prefix.YYYY-MM-DD.H（例如：假设 prefix 为 /data/sa/access.log，当天是
2018-04-13 14 点，则输出文件为 /data/sa/access.log.2018-03-13.14）
//
consumer, err := sdk.InitLoggingConsumer("/data/sa/access.log", true)
注意，请不要使用多进程写入同一个日志文件，可能会造成数据丢失或者错乱。如果需要多进程写入，请使用 ConcurrentLoggingConsumer。
7.2 ConcurrentLoggingConsumer（推荐）
用于将数据输出到指定目录，并自动按 天 切割文件，支持按小时切割，参数含义同 LoggingConsumer ，与 LoggongConsumer 不同的是，它支持多进程
写入同一个文件。
初始化接口
// filename hourRotate
func InitConcurrentLoggingConsumer(filename string, hourRotate bool) (*consumers.ConcurrentLoggingConsumer,
error)
例子
import sdk "github.com/sensorsdata/sa-sdk-go"
// ConcurrentLoggingConsumer
consumer, err := sdk.InitConcurrentLoggingConsumer("/data/sa/access.log", true)
// ...
// Consumer SensorsAnalytics
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
// Close() Consumer
defer sa.Close()
// ...
注意： LogAgent 配置文件中一定要注释掉 real_time_file_name 参数，否则无法正常导入数据。已使用 LoggingConsumer 的客户建议按照如下步骤切换
到 ConcurrentLoggingConsumer：
第 1 步 停掉 LogAgent，并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步 将日志目录下的 real_time_file_name 的文件加上当前时间的后缀 ".YYYY-MM-DD"。
第 3 步 后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步 重新启动 LogAgent。7.3 DebugConsumer（测试使用)
用于校验数据导入是否正确，关于 Debug 模式 的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条
校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭
Debug 模式。
初始化接口为
// urlurlwriteDatatimeout
// writeData
// true -
// false -
func InitDebugConsumer(url string, writeData bool, timeout int) (*consumers.DebugConsumer, error)
例子
import sdk "github.com/sensorsdata/sa-sdk-go"
// URL
SA_SERVER_URL := "YOUR_SERVER_URL"
//
SA_REQUEST_TIMEOUT := 100000
// Debug
// true -
// false -
SA_DEBUG_WRITE_DATA := true
// Debug Consumer
consumer, err := sdk.InitDebugConsumer(SA_SERVER_URL, SA_DEBUG_WRITE_DATA, SA_REQUEST_TIMEOUT)
// ...
// Consumer SensorsAnalytics
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()
// ...
7.4 DefaultConsumer
通常用于导入小规模历史数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。普通
Consumer，实现，逐条、同步的发送数据给接收服务器。
初始化接口
// url URLtimeout
func InitDefaultConsumer(url string, timeout int) (*consumers.DefaultConsumer, error)
例子
import sdk "github.com/sensorsdata/sa-sdk-go"
// URL
SA_SERVER_URL := "YOUR_SERVER_URL"
//
SA_REQUEST_TIMEOUT := 100000
// Default Consumer
consumer, err := sdk.InitDefaultConsumer(SA_SERVER_URL, SA_REQUEST_TIMEOUT)
// ...
// Consumer SensorsAnalytics
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()
// ...7.5 BatchConsumer
通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在
任何线上服务中。批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。
初始化接口
// urlurlmaxtimeout
func InitBatchConsumer(url string, max, timeout int) (*consumers.BatchConsumer, error)
例子
import sdk "github.com/sensorsdata/sa-sdk-go"
// URL
SA_SERVER_URL := "YOUR_SERVER_URL"
//
SA_REQUEST_TIMEOUT := 100000
//
SA_BULK_SIZE := 100
// Batch Consumer
consumer, err := sdk.InitBatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, SA_REQUEST_TIMEOUT)
// ...
// Consumer SensorsAnalytics
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()
// ...PHP SDK.PHP SDK v1.13
1. PHP SDK 使用说明
在使用前，请先阅读 数据模型 的介绍。
1.1. 集成神策分析 SDK
在 PHP 脚本中集成 神策分析 SDK ，使用神策分析采集并分析用户数据。SDK 最低兼容 PHP 5.X，部分功能依赖 curl 扩展。有两种集成方式：
使用 composer 集成。
{
"require": {
"sensorsdata/sa-sdk-php": "v1.10.5"
}
}
直接从 GitHub 获取 SDK 的源码并集成到项目中。
1.2. 初始化神策分析 SDK
1.2.1. 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
: http://{$host_name}:8106/sa?project={$project_name} 1.7 8006
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
: http://{$host_name}:8106/sa?project={$project_name}其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
1.2.2. 在程序中初始化 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：
track($distinct_id, true, ''UserLogin'');
$sa->close();
?>
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 `close()`
方法显式关闭，否则可能丢失部分缓存的数据。
至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的 .PHP SDK v1.13#设置神策分析 SDK 一节。
1.3. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
用户通过 track() 接口记录事件，对于任何事件，必须包含用户标志符（distinct_id）、用户标识是否为登录 ID (is_login_id)和事件名（event_name）这三个
参数。同时，用户可以在 track() 的第四个参数传入一个 object 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
(int)(microtime(true) * 1000), # windows ''$time'' => substr((microtime(true) * 1000),
0, 13)
# ''$ip'' IP IP
''$ip'' => ''123.123.123.123'',
# ID
''ProductId'' => ''123456'',
#
''ProductCatalog'' => ''Laptop Computer'',
# Boolean
''IsAddedToFav'' => true,
);#
$sa->track($distinct_id, true, ''ViewProduct'', $properties);
$properties =
array( # IP
''$ip'' => ''123.123.123.123'',
# ID list
''ProductIdList'' => array(''123456'', ''234567'', ''345678''),
#
''OrderPaid'' => 12.10,
);
#
$sa->track($distinct_id, true, ''PaidOrder'', $properties);
?>
1.3.1. 事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
array
array Key string
array Value stringintfloatarray DateTime
对于神策分析中事件属性的更多约束，请参考 数据格式
1.3.1.1. 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - IP string
$time - DateTime 365 3
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
1.3.1.2. 事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 register_super_properties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机
房地址设置为事件的公共属性，设置方法如下:
''1.2'',
#
''Location'' => ''BeiJing'',
);
#
$sa->register_super_properties($properties);
?>
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中。
使用 clear_super_properties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。1.4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct Id，不建议使用用户名、Email、手机号码等可以被修改的信息。
所有的 track 和 profile 系列方法都必须同时指定用户 ID 及用户 ID 是否为登录 ID 这两个参数，以便明确告知神策分析用户 ID 的类型。
1.4.1. 用户注册/登录
当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过 track_signup() 将旧的 Distinct Id 和新的 Distinct Id 关联，以保证用
户分析的准确性。例如：
track_signup($register_id, $anonymous_id);
?>
注意，对同一个用户，track_signup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户 登录 前后的行为的关联建议在业务端实现。在神策分
析 1.13 版本之前，多次调用 track_signup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参
考 如何正确地标识用户，并在必要时联系我们的技术支持人员。
1.5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profile_set() 设置用户属性:
''Male'',
# Level VIP
''UserLevel'' => ''Elite VIP'',
);
#
$sa->profile_set($distinct_id, true, $properties);
?>
对于不再需要的用户属性，可以通过 `profile_unset()` 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
1.5.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profile_set_once() 记录这些属性。与 profile_set() 接口不同的是，如果被设置的用户属性已存在，则这条
记录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动创建。因此，profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属
性。例如：
profile_set_once($distinct_id, true, array(''AdSource'' => ''App Store''));# AdSource "AdSource" "App Store"
$sa->profile_set_once($distinct_id, true, array(''AdSource'' => ''Search Engine''));
?>
1.5.2. 数值类型的属性
对于数值型的用户属性，可以使用 profile_increment() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
profile_increment($distinct_id, true, array(''GamePlayed'' => 1));
?>
1.5.3. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 string 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式。
array(''Sicario'', ''Love Letter''),
#
''Games'' => array(''Call of Duty'', ''Halo''),
);
# propertiesmoviesgames
# "Movies" ["Sicario", "Love Letter"]"Games" ["Call of Duty", "Halo"]
$sa->profile_append($distinct_id, true, $properties);
# Movies
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
$sa->profile_append($distinct_id, true, array(''Movie'' => array(''Dead Poets Society'')));
# Movies
# "Love Letter"
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
$sa->profile_append($distinct_id, true, array(''Movie'' => array(''Love Letter'')));
?>
1.6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析SDK提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
1.6.1. 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 $properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
item_set($item_type, $item_id, array(''apple'' => 1));
?>
1.6.2. 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
item_delete($item_type, $item_id, null);
?>
1.7. 设置神策分析 SDK
PHP SDK 主要由以下两个组件构成:
SensorsAnalytics: Consumer
Consumer: Consumer
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:
FileConsumer: 将待发送的数据写入指定的本地文件，后续可以使用 LogAgent 或者 BatchImporter 来进行导入。
close();
?>
BatchConsumer: 通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，
因此不要用在任何线上服务中 。使用 CURL 批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。
close();
?>
DebugConsumer: 用于校验数据导入是否正确，关于 调试模式 的详细信息，请进入相关页面查看。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会
严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
.PHP SDK v1.14
1. PHP SDK 使用说明
在使用前，请先阅读 数据模型 的介绍。
1.1. 集成神策分析 SDK
在 PHP 脚本中集成 神策分析 SDK ，使用神策分析采集并分析用户数据。SDK 最低兼容 PHP 5.X，部分功能依赖 curl 扩展。有两种集成方式：
使用 composer 集成。
{
"require": {
"sensorsdata/sa-sdk-php": "v1.10.5"
}
}
直接从 GitHub 获取 SDK 的源码并集成到项目中。
1.2. 初始化神策分析 SDK
1.2.1. 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
: http://{$host_name}:8106/sa?project={$project_name} 1.7 8006
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
: http://{$host_name}:8106/sa?project={$project_name}其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
1.2.2. 在程序中初始化 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：
track($distinct_id, true, ''UserLogin'');
$sa->close();
?>
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 `close()`
方法显式关闭，否则可能丢失部分缓存的数据。
至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的 .PHP SDK v1.13#设置神策分析 SDK 一节。
1.3. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
用户通过 track() 接口记录事件，对于任何事件，必须包含用户标志符（distinct_id）、用户标识是否为登录 ID (is_login_id)和事件名（event_name）这三个
参数。同时，用户可以在 track() 的第四个参数传入一个 object 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
(int)(microtime(true) * 1000), # windows ''$time'' => substr((microtime(true) * 1000),
0, 13)
# ''$ip'' IP IP
''$ip'' => ''123.123.123.123'',
# ID
''ProductId'' => ''123456'',
#
''ProductCatalog'' => ''Laptop Computer'',
# Boolean
''IsAddedToFav'' => true,
);#
$sa->track($distinct_id, true, ''ViewProduct'', $properties);
$properties =
array( # IP
''$ip'' => ''123.123.123.123'',
# ID list
''ProductIdList'' => array(''123456'', ''234567'', ''345678''),
#
''OrderPaid'' => 12.10,
);
#
$sa->track($distinct_id, true, ''PaidOrder'', $properties);
?>
1.3.1. 事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
array
array Key string
array Value stringintfloatarray DateTime
对于神策分析中事件属性的更多约束，请参考 数据格式
1.3.1.1. 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - IP string
$time - DateTime 365 3
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
1.3.1.2. 事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 register_super_properties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机
房地址设置为事件的公共属性，设置方法如下:
''1.2'',
#
''Location'' => ''BeiJing'',
);
#
$sa->register_super_properties($properties);
?>
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中。
使用 clear_super_properties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。1.4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct Id，不建议使用用户名、Email、手机号码等可以被修改的信息。
所有的 track 和 profile 系列方法都必须同时指定用户 ID 及用户 ID 是否为登录 ID 这两个参数，以便明确告知神策分析用户 ID 的类型。
1.4.1. 用户注册/登录
当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过 track_signup() 将旧的 Distinct Id 和新的 Distinct Id 关联，以保证用
户分析的准确性。例如：
track_signup($register_id, $anonymous_id);
?>
注意，对同一个用户，track_signup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户 登录 前后的行为的关联建议在业务端实现。在神策分
析 1.13 版本之前，多次调用 track_signup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参
考 2019-12-03_22-18-28_如何准确的标识用户，并在必要时联系我们的技术支持人员。
1.5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profile_set() 设置用户属性:
''Male'',
# Level VIP
''UserLevel'' => ''Elite VIP'',
);
#
$sa->profile_set($distinct_id, true, $properties);
?>
对于不再需要的用户属性，可以通过 `profile_unset()` 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
1.5.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profile_set_once() 记录这些属性。与 profile_set() 接口不同的是，如果被设置的用户属性已存在，则这条
记录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动创建。因此，profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属
性。例如：
profile_set_once($distinct_id, true, array(''AdSource'' => ''App Store''));# AdSource "AdSource" "App Store"
$sa->profile_set_once($distinct_id, true, array(''AdSource'' => ''Search Engine''));
?>
1.5.2. 数值类型的属性
对于数值型的用户属性，可以使用 profile_increment() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
profile_increment($distinct_id, true, array(''GamePlayed'' => 1));
?>
1.5.3. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 string 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式。
array(''Sicario'', ''Love Letter''),
#
''Games'' => array(''Call of Duty'', ''Halo''),
);
# propertiesmoviesgames
# "Movies" ["Sicario", "Love Letter"]"Games" ["Call of Duty", "Halo"]
$sa->profile_append($distinct_id, true, $properties);
# Movies
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
$sa->profile_append($distinct_id, true, array(''Movie'' => array(''Dead Poets Society'')));
# Movies
# "Love Letter"
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
$sa->profile_append($distinct_id, true, array(''Movie'' => array(''Love Letter'')));
?>
1.6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析SDK提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
1.6.1. 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 $properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
item_set($item_type, $item_id, array(''apple'' => 1));
?>
1.6.2. 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
item_delete($item_type, $item_id, null);
?>
1.7. 设置神策分析 SDK
PHP SDK 主要由以下两个组件构成:
SensorsAnalytics: Consumer
Consumer: Consumer
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:
FileConsumer: 将待发送的数据写入指定的本地文件，后续可以使用 LogAgent 或者 BatchImporter 来进行导入。
close();
?>
BatchConsumer: 通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，
因此不要用在任何线上服务中 。使用 CURL 批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。
close();
?>
DebugConsumer: 用于校验数据导入是否正确，关于 调试模式 的详细信息，请进入相关页面查看。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会
严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
.PHP SDK v1.17
PHP SDK 使用说明
在使用前，请先阅读 数据模型 的介绍。
集成神策分析 SDK
在 PHP 脚本中集成 神策分析 SDK ，使用神策分析采集并分析用户数据。SDK 最低兼容 PHP 5.X，部分功能依赖 curl 扩展。有两种集成方式：
使用 composer 集成。
{
"require": {
"sensorsdata/sa-sdk-php": "v1.10.5"
}
}
直接从 GitHub 获取 SDK 的源码并集成到项目中。
初始化神策分析 SDK
获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
: http://{$host_name}:8106/sa?project={$project_name} 1.7 8006
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
: http://{$host_name}:8106/sa?project={$project_name}其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
在程序中初始化 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：
track($distinct_id, true, ''UserLogin'');
$sa->close();
?>
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 `close()`
方法显式关闭，否则可能丢失部分缓存的数据。
至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的 .PHP SDK v1.13#设置神策分析 SDK 一节。
追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
用户通过 track() 接口记录事件，对于任何事件，必须包含用户标志符（distinct_id）、用户标识是否为登录 ID (is_login_id)和事件名（event_name）这三个
参数。同时，用户可以在 track() 的第四个参数传入一个 object 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
(int)(microtime(true) * 1000), # windows ''$time'' => substr((microtime(true) * 1000),
0, 13)
# ''$ip'' IP IP
''$ip'' => ''123.123.123.123'',
# ID
''ProductId'' => ''123456'',
#
''ProductCatalog'' => ''Laptop Computer'',
# Boolean
''IsAddedToFav'' => true,
);#
$sa->track($distinct_id, true, ''ViewProduct'', $properties);
$properties =
array( # IP
''$ip'' => ''123.123.123.123'',
# ID list
''ProductIdList'' => array(''123456'', ''234567'', ''345678''),
#
''OrderPaid'' => 12.10,
);
#
$sa->track($distinct_id, true, ''PaidOrder'', $properties);
?>
事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
array
array Key string
array Value stringintfloatarray DateTime
对于神策分析中事件属性的更多约束，请参考 数据格式
系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - IP string
$time - DateTime 365 3
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 register_super_properties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机
房地址设置为事件的公共属性，设置方法如下:
''1.2'',
#
''Location'' => ''BeiJing'',
);
#
$sa->register_super_properties($properties);
?>
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中。
使用 clear_super_properties() 会删除所有已设置的事件公共属性。
当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct Id，不建议使用用户名、Email、手机号码等可以被修改的信息。
所有的 track 和 profile 系列方法都必须同时指定用户 ID 及用户 ID 是否为登录 ID 这两个参数，以便明确告知神策分析用户 ID 的类型。
用户注册/登录
当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过 track_signup() 将旧的 Distinct Id 和新的 Distinct Id 关联，以保证用
户分析的准确性。例如：
track_signup($register_id, $anonymous_id);
?>
注意，对同一个用户，track_signup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户 登录 前后的行为的关联建议在业务端实现。在神策分
析 1.13 版本之前，多次调用 track_signup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参
考 如何准确的标识用户，并在必要时联系我们的技术支持人员。
设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profile_set() 设置用户属性:
''Male'',
# Level VIP
''UserLevel'' => ''Elite VIP'',
);
#
$sa->profile_set($distinct_id, true, $properties);
?>
对于不再需要的用户属性，可以通过 `profile_unset()` 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profile_set_once() 记录这些属性。与 profile_set() 接口不同的是，如果被设置的用户属性已存在，则这条
记录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动创建。因此，profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属
性。例如：
profile_set_once($distinct_id, true, array(''AdSource'' => ''App Store''));# AdSource "AdSource" "App Store"
$sa->profile_set_once($distinct_id, true, array(''AdSource'' => ''Search Engine''));
?>
数值类型的属性
对于数值型的用户属性，可以使用 profile_increment() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
profile_increment($distinct_id, true, array(''GamePlayed'' => 1));
?>
列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 string 类型，且元素的值会自动去重。
关于列表类型限制请见 数据格式。
array(''Sicario'', ''Love Letter''),
#
''Games'' => array(''Call of Duty'', ''Halo''),
);
# propertiesmoviesgames
# "Movies" ["Sicario", "Love Letter"]"Games" ["Call of Duty", "Halo"]
$sa->profile_append($distinct_id, true, $properties);
# Movies
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
$sa->profile_append($distinct_id, true, array(''Movie'' => array(''Dead Poets Society'')));
# Movies
# "Love Letter"
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
$sa->profile_append($distinct_id, true, array(''Movie'' => array(''Love Letter'')));
?>
物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析SDK提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。
设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 $properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
item_set($item_type, $item_id, array(''apple'' => 1));
?>
删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
item_delete($item_type, $item_id, null);
?>
设置神策分析 SDK
PHP SDK 主要由以下两个组件构成:
SensorsAnalytics: Consumer
Consumer: Consumer
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:
FileConsumer: 将待发送的数据写入指定的本地文件，后续可以使用 LogAgent 或者 BatchImporter 来进行导入。
close();
?>
BatchConsumer: 通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，
因此不要用在任何线上服务中 。使用 CURL 批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。
close();
?>
DebugConsumer: 用于校验数据导入是否正确，关于 调试模式 的详细信息，请进入相关页面查看。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会
严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
Python SDK.Python SDK v1.13
1. 集成神策分析 SDK
在 Python 脚本中集成神策分析 SDK，使用神策分析采集并分析用户数据。
我们推荐使用 pip 管理 Python 项目并获取神策分析 SDK：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
pip install SensorsAnalyticsSDK
如果不使用 pip，也可以从 GitHub 下载 神策分析 SDK 的源代码。
SDK 兼容 Python 2.6+ 和 Python3 3.X，不依赖第三方库。
2. 初始化神策分析 SDK
2.1. 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
2.2. 在程序中初始化 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：
DefaultConsumer 是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。线上请使用
ConcurrentLoggingConsumer。import sensorsanalytics
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
# Consumer
# DefaultConsumer Consumer
consumer = sensorsanalytics.DefaultConsumer(SA_SERVER_URL)
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)
#
distinct_id = ''ABCDEF123456789''
sa.track(distinct_id, ''UserLogin'', is_login_id=True)
sa.close()
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 close() 方
法显式关闭，否则可能丢失部分缓存的数据。
至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的控制神策分析 SDK 一节。
3. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
用户通过 track() 接口记录事件，对于任何事件，必须包含用户标志符（Distinct ID）和事件名（event_name）两个参数。同时，用户可以在 track() 的第三
个参数传入一个 dict 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
distinct_id = ''ABCDEF123456''
properties = {
# ''$time'' datetime
''$time'' : datetime.datetime.now(),
# ''$ip'' IP IP
''$ip'' : ''123.123.123.123'',
# ID
''ProductId'' : ''123456'',
#
''ProductCatalog'' : ''Laptop Computer'',
# Boolean
''IsAddedToFav'' : True,
}
#
sa.track(distinct_id, ''ViewProduct'', properties, is_login_id=True)
properties =
{ # IP
''$ip'' : ''123.123.123.123'',
# ID list
''ProductIdList'' : [''123456'', ''234567'', ''345678''],
#
''OrderPaid'' : 12.10,
}
#
sa.track(distinct_id, ''PaidOrder'', properties, is_login_id=True)
3.1. 事件属性如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:
事件属性是一个 dict 对象
dict 中每个元素描述一个属性，Key 为属性名称，必需是 str 类型
dict 中，每个元素的 Value 是属性的值，支持 str、int、float、list、datetime.datetime 和 datetime.date
对于神策分析中事件属性的更多约束，请参考 数据格式。
3.1.1. 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 str 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 datetime.datetime 或 datetime.date 类型。请注意，神策分析
默认会过滤忽略 365 天前或 3 天后的数据，如需修改请联系我们。
关于其他更多预置属性，请参考 数据格式中 ''预置属性'' 一节。
4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。
对于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。对于未注册的匿名用户，服务端也
需要生成一个随机 ID 以标记用户。
所有的 track 和 profile 系列方法建议明确指定 is_login_id 参数，以便明确告知神策分析用户 ID 的类型。
4.1. 用户注册/登录
当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过 track_signup() 将旧的 Distinct ID 和新的 Distinct ID 关联，以保证用
户分析的准确性。例如：
# ID
anonymous_id = ''9771C579-71F0-4650-8EE8-8999FA717761''
register_id = ''0012345678''
# / ID ID
sa.track_signup(register_id, anonymous_id)
注意，对同一个用户，track_signup() 一般情况下建议只调用一次（通常在用户注册时调用），用户登录前后的行为的关联建议在业务端实现。在神
策分析 1.13 版本之前，多次调用 track_signup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更
详细的说明请参考 标识用户，并在必要时联系我们的技术支持人员。
5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profile_set() 设置用户属性:
distinct_id = ''ABCDEF123456789''
properties =
{ # Sex
''Sex'' : ''Male'',
# Level VIP
''UserLevel'' : ''Elite VIP'',
}#
sa.profile_set(distinct_id, properties, is_login_id=True)
对于不再需要的用户属性，可以通过 profile_unset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
5.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profile_set_once() 记录这些属性。与 profile_set() 接口不同的是，如果被设置的用户属性已存在，则这条
记录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动创建。因此，profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属
性。例如：
distinct_id = ''ABCDEF123456789''
# AdSource "App Store"
sa.profile_set_once(distinct_id, {''AdSource'' : ''App Store''})
# AdSource "AdSource" "App Store"
sa.profile_set_once(distinct_id, {''AdSource'' : ''Search Engine''})
5.2. 数值类型的属性
对于数值型的用户属性，可以使用 profile_increment() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
distinct_id = ''ABCDEF123456789''
# GamePlayed1
sa.profile_increment(distinct_id, {''GamePlayed'' : 1}, is_login_id=True)
5.3. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 str 类型，且元素的值不会自动去重
（1.12 之前的神策系统版本才会自动去重）。关于列表类型限制请见 数据格式 中属性长度限制。
distinct_id = ''ABCDEF123456789''
properties =
{ #
''Movies'' : [''Sicario'', ''Love Letter''],
#
''Games'' : [''Call of Duty'', ''Halo''],
}
# propertiesmoviesgames
# "Movies" ["Sicario", "Love Letter"]"Games" ["Call of Duty", "Halo"]
sa.profile_append(distinct_id, properties, is_login_id=True)
# Movies
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profile_append(distinct_id, {''Movies'' : [''Dead Poets Society'']}, is_login_id=True)
# Movies
# "Love Letter"
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society", "Love Letter"]
sa.profile_append(distinct_id, {''Movies'' : [''Love Letter'']}, is_login_id=True)6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。
item_id（物品 ID ）和item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID及物品所属类型这两个参
数，来完成对物品的操作。
6.1. 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 $properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
#
item_type = ''apple''
item_id = ''12345''
sa.item_set(item_type, item_id, {"price": "3"})
6.2. 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
#
item_type = ''apple''
item_id = ''12345''
sa.item_delete(item_type, item_id)
7. 设置神策分析 SDK
Python SDK 主要由以下两个组件构成:
SensorsAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例。
Consumer: Consumer 会进行实际的数据发送
为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:
7.1. LoggingConsumer
用于将数据输出到指定目录并按天切割文件，一般用于在 Python 脚本中处理实时数据，生成日志文件并使用 LogAgent 等工具导入。适用于单进程程序。
import sensorsanalytics
# Logging Consumer
consumer = sensorsanalytics.LoggingConsumer(''/data/sa/access.log'')
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)
可以通过参数配置切分间隔和保留的文件数，默认是每天0点切割，保留所有文件。具体参数含义参考 Python 标准库 logging.handlers.
TimedRotatingFileHandler 文档。# 10
consumer = sensorsanalytics.LoggingConsumer(''/data/sa/access.log'', backupCount=10, when=''H'')
请不要使用多进程写入同一个日志文件，可能会造成数据丢失或者错乱。如果需要多进程写入，请使用 ConcurrentLoggingConsumer。
7.2. ConcurrentLoggingConsumer（推荐）
用于将数据输出到指定目录，并自动按 天 切割文件，与 LoggingConsumer 不同的是，它支持多进程写入同一个文件。一般用于 Django、uWSGI 等特殊
的多进程场景。
import sensorsanalytics
#
SA_BULK_SIZE = 1024
# Concurrent Logging Consumer ''/data/sa/access.log.YYYY-MM-DD'' 1024
consumer = sensorsanalytics.ConcurrentLoggingConsumer(''/data/sa/access.log'', SA_BULK_SIZE)
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)
# ...
#
sa.flush()
LogAgent 配置文件中一定要注释掉 real_time_file_name 参数，否则无法正常导入数据。已使用 LoggingConsumer 的客户建议按照如下步骤切
换到 ConcurrentLoggingConsumer：
第 1 步 停掉 LogAgent，并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步 将日志目录下的 real_time_file_name 的文件加上当前时间的后缀 ".YYYY-MM-DD"。
第 3 步 后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步 重新启动 LogAgent。
7.3. DebugConsumer（测试使用）
用于校验数据导入是否正确，关于 调试模式 的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校
验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭
Debug 模式。
import sensorsanalytics
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
#
SA_REQUEST_TIMEOUT = 100000
# Debug
# True -
# False -
SA_DEBUG_WRITE_DATA = True
# Debug Consumer
consumer = sensorsanalytics.DebugConsumer(SA_SERVER_URL, SA_DEBUG_WRITE_DATA, SA_REQUEST_TIMEOUT)
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)7.4. ConsoleConsumer
用于将数据输出到标准输出，一般用于在 Python 脚本中处理历史数据，生成日志文件并使用 BatchImporter 等工具导入。
import sensorsanalytics
# Console Consumer
consumer = sensorsanalytics.ConsoleConsumer()
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)
7.5. DefaultConsumer
通常用于导入小规模历史数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。普通
Consumer，实现，逐条、同步的发送数据给接收服务器。
import sensorsanalytics
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
#
SA_REQUEST_TIMEOUT = 100000
# Default Consumer
consumer = sensorsanalytics.DefaultConsumer(SA_SERVER_URL, SA_REQUEST_TIMEOUT)
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)
7.6. BatchConsumer
通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在
任何线上服务中。批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。
import sensorsanalytics
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
#
SA_REQUEST_TIMEOUT = 100000
#
SA_BULK_SIZE = 100
# Batch Consumer
consumer = sensorsanalytics.BatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, SA_REQUEST_TIMEOUT)
# Consumer SensorsAnalytics
sa = sensorsanalytics.SensorsAnalytics(consumer)
# close() Consumer
sa.close()Ruby SDK.Ruby SDK v1.13
1. Ruby SDK 使用说明
在使用前，请先阅读数据模型的介绍。
1.1. 集成神策分析 SDK
在 Ruby 脚本中集成 神策分析 SDK，使用神策分析采集并分析用户数据。
我们推荐使用 RubyGem 管理 Ruby 项目并获取神策分析 SDK：
gem install sensors_analytics_sdk
如果不使用 RubyGem，也可以从 GitHub 下载 神策分析 SDK 的源代码。
1.2. 初始化神策分析 SDK
1.2.1. 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
1.2.2. 在程序中初始化 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：require ''sensors_analytics_sdk.rb''
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
# Consumer
consumer = SensorsAnalytics::DefaultConsumer.new(SA_SERVER_URL)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)
#
distinct_id = ''ABCDEF123456''
sa.track(distinct_id, ''UserLogin'')
其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 close() 方
法显式关闭，否则可能丢失部分缓存的数据。
至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以查看本文末尾的 控制神策分析 SDK 一节。
1.3. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件
用户通过 track() 接口记录事件，对于任何事件，必须包含用户标志符（Distinct ID）和事件名（event_name）两个参数。同时，用户可以在 track() 的第三个
参数传入一个 dict 对象，为事件添加自定义事件属性，在自定义属性中需要包含 $is_login_id 属性来说明 Distinct ID 是否为登录 ID。以电商产品为例，
可以这样追踪一次购物行为：
distinct_id = ''ABCDEF123456''
properties = {
# ''$time'' datetime
''$time'' => Time.now(),
# ''$ip'' IP IP
''$ip'' => ''123.123.123.123'',
# ID
''ProductId'' => ''123456'',
#
''ProductCatalog'' => ''Laptop Computer'',
# Boolean
''IsAddedToFav'' => true,
# $is_login_id distinct_id ID true false false
''$is_login_id'' => true,
}
#
sa.track(distinct_id, ''ViewProduct'', properties)
properties = {
# IP
''$ip'' => ''123.123.123.123'',
# ID list
''ProductIdList'' => [''123456'', ''234567'', ''345678''],
#
''OrderPaid'' => 12.10,
# $is_login_id distinct_id ID true false false
''$is_login_id'' => true,
}
#
sa.track(distinct_id, ''PaidOrder'', properties)
1.3.1. 事件属性
如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属
性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:事件属性是一个 Hash 对象
Hash 中每个元素描述一个属性，Key 为属性名称，必需是 String 或 Symbol 类型
Hash 中，每个元素的 Value 是属性的值，支持 String、Symbol、Integer、Float、Array、TrueClass/FalseClass 和 Time
对于神策分析中事件属性的更多约束，请参考 数据格式
1.3.1.1. 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 String 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 Time 类型。请注意，神策分析默认会过滤忽略 365 天前或 3 天
后的数据，如需修改请联系我们。
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
1.4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析数据。
对于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。
1.4.1. 用户注册/登录
当同一个用户的 Distinct ID 发生变化时（一般情况为匿名用户注册行为），可以通过 track_signup() 将旧的 Distinct ID 和新的 Distinct ID 关联，以保证用
户分析的准确性。例如：
# ID
anonymous_id = ''9771C579-71F0-4650-8EE8-8999FA717761''
register_id = ''0012345678''
# / ID ID
sa.track_signup(register_id, anonymous_id)
注意，对同一个用户，track_signup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户 登录 前后的行为的关联建议在业务端实现。在神策分
析 1.13 版本之前，多次调用 track_signup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 ID 关联的方法。更详细的说明请参
考 标识用户，并在必要时联系我们的技术支持人员。
1.5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profile_set() 设置用户属性:
distinct_id = ''ABCDEF123456789''
properties = {
# Sex
''Sex'' => ''Male'',
# Level VIP
''UserLevel'' => ''Elite VIP'',
# $is_login_id distinct_id ID true false false
''$is_login_id'' => true,
}
#
sa.profile_set(distinct_id, properties)
对于不再需要的用户属性，可以通过 profile_unset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
1.5.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profile_set_once() 记录这些属性。与 profile_set() 接口不同的是，如果被设置的用户属性已存在，则这条
记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例
如：distinct_id = ''ABCDEF123456789''
properties = {
# AdSource "App Store"
''AdSource'' => ''App Store'',
# $is_login_id distinct_id ID true false false
''$is_login_id'' => true,
}
sa.profile_set_once(distinct_id, properties)
# AdSource "AdSource" "App Store"
properties[''AdSource''] = ''Search Engine''
sa.profile_set_once(distinct_id, properties)
1.5.2. 数值类型的属性
对于数值型的用户属性，可以使用 profile_increment() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
distinct_id = ''ABCDEF123456789''
properties = {
# GamePlayed1
''GamePlayed'' => 1,
# $is_login_id distinct_id ID true false false
''$is_login_id'' => true,
}
sa.profile_increment(distinct_id, properties)
1.5.3. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 String 或 Symbol 类型，且元素的值会
自动去重。关于列表类型限制请见 数据格式 7.3 属性长度限制。
distinct_id = ''ABCDEF123456789''
properties = {
#
''Movies'' => [''Sicario'', ''Love Letter''],
#
''Games'' => [''Call of Duty'', ''Halo''],
# $is_login_id distinct_id ID true false false
''$is_login_id'' => true,
}
# propertiesmoviesgames
# "Movies" ["Sicario", "Love Letter"]"Games" ["Call of Duty", "Halo"]
sa.profile_append(distinct_id, properties)
# Movies
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profile_append(distinct_id, {''Movie'' => [''Dead Poets Society'']})
# Movies
# "Love Letter"
# "Movies" ["Sicario", "Love Letter", "Dead Poets Society"]
sa.profile_append(distinct_id, {''Movie'' => [''Love Letter'']})
1.6. 设置神策分析 SDK
Ruby SDK 主要由以下两个组件构成:
SensorsAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例。
Consumer: Consumer 会进行实际的数据发送为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:
DefaultConsumer: 通常用于导入小规模历史数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任
何线上服务中。普通 Consumer，实现，逐条、同步的发送数据给接收服务器。
require ''sensors_analytics_sdk.rb''
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
# Consumer
consumer = SensorsAnalytics::DefaultConsumer.new(SA_SERVER_URL)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)
BatchConsumer: 通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重
发或丢失，因此不要用在任何线上服务中。批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。
require ''sensors_analytics_sdk.rb''
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
#
SA_BULK_SIZE = 100
# Batch Consumer
consumer = SensorsAnalytics::BatchConsumer.new(SA_SERVER_URL, SA_BULK_SIZE)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)
# flush() Consumer
consumer.flush()
DebugConsumer: 用于校验数据导入是否正确，关于 Debug 模式的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试而设
置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险， 产
品上线前请务必替换掉/关闭 Debug 模式。
require ''sensors_analytics_sdk.rb''
# URL
SA_SERVER_URL = ''YOUR_SERVER_URL''
# Debug
# true -
# false -
SA_DEBUG_WRITE_DATA = true
# Debug Consumer
consumer = SensorsAnalytics::DebugConsumer.new(SA_SERVER_URL, SA_DEBUG_WRITE_DATA)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)Node SDK.Node SDK v1.13
在使用前，请先阅读数据模型的介绍。
1. 集成神策分析 SDK
在 NodeJS 中集成 神策分析 SDK，使用神策分析采集并分析用户数据。
我们推荐使用 npm 管理 Node 模块并获取神策分析 SDK：
npm install sa-sdk-node --save
注： 目前只支持 4.x 及以上 Node 版本
2. 注意事项
在 1.0.8 及之后版本中，添加了一个 allowReNameOption 选项，默认值为 true，在此情况下将属性值和键值格式化为下划线风格命名格式，例如：
sa.track(''user-id'', ''userHappy'', {
''$appVersion'': ''1.0.0'',
''orderId'': ''123''
})
//then we get data
{
...
''event'': ''user_happy''
''properties'': {
''$app_version'': ''1.0.0'',
''order_id'': ''123''
}
...
}
可以通过调用 sa.disableReNameOption() 来设置 allowReNameOption 为 false。这种情况下，传递默认属性时，需要传递如 $app_version 风格的命名规
范的键值和属性值，自定义属性如 orderId 会被保留当前驼峰的命名风格。默认属性格式规范请查看 数据格式 的介绍。
3. 使用 Node SDK
3.1. 获取配置信息
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name} （注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为
8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
3.2. 导入 SDK
在程序中初始化的代码段中构造神策分析 SDK 的实例：
ES6:
import SensorsAnalytics from ''sa-sdk-node''
const sa = new SensorsAnalytics()
sa.disableReNameOption()
non-ES6:
var SensorsAnalytics = require(''sa-sdk-node'')
var sa = new SensorsAnalytics;
sa.disableReNameOption()
sa.submitTo(''http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}'')
3.3. 追踪事件用户通过 track() 接口记录事件，对于任何事件，必须包含用户标志符（distinct_id）和事件名（event_name）两个参数。同时，用户可以在 track() 的第三个
参数为事件添加自定义事件属性，在自定义属性中需要包含 $is_login_id 属性来说明 distinct_id 是否为登录 ID。以电商产品为例，可以这样追踪一次购物
行为：
var distinct_id = ''ABCDEF123456''
var properties = {
// ''$time'' datetime
''$time'' : datetime.datetime.now(),
// ''$ip''
''$ip'' : ''123.123.123.123'',
// $is_login_id distinct_id ID true false false
''$is_login_id'' : True,
// ID
''ProductId'' : ''123456'',
//
''ProductCatalog'' : ''Laptop Computer'',
// Boolean
''IsAddedToFav'' : True,
}
//
sa.track(distinct_id, ''ViewProduct'', properties)
var properties = {
// IP
''$ip'' : ''123.123.123.123'',
// $is_login_id distinct_id ID true false false
''$is_login_id'' : True,
// ID list
''ProductIdList'' : [''123456'', ''234567'', ''345678''],
//
''OrderPaid'' : 12.10,
}
//
sa.track(distinct_id, ''PaidOrder'', properties)
3.3.1. 系统预置属性
如前文中样例，事件属性中以 ''$'' 开头的属性为系统预置属性，在自定义事件属性中填入对应 ''$'' 开头的属性值可以覆盖这些预置属性：
Distinct$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 str 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 datetime.datetime 或 datetime.date 类型。请注意，神策分析
默认会过滤忽略 365 天前或 3 天后的数据，如需修改请联系我们。
关于其他更多预置属性，请参考 数据格式 中 ''预置属性'' 一节。
3.3.2. 事件公共属性
特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件公共属性。例如，应用版本设置为所有事件
共有属性方法如下:
sa.registerSuperProperties({
$appVersion: ''1.0.0'',
env: ''production''
});
成功设置事件公共属性后，再通过 track() 追踪事件时，事件公共属性会被添加进每个事件中。
4. 用户识别
在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析提供更准确的留存率等数据。对
于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。
4.1. 用户注册/登录当同一个用户的 Distinct ID 发生变化时（一般情况为匿名用户注册行为），可以通过 trackSignup() 将旧的 Distinct ID 和新的 Distinct ID 关联，以保证用
户分析的准确性。例如：
// ID
var anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";
String registerId = "0012345678";
// / ID ID
sa.trackSignup(registerId, anonymousId);
注意，对同一个用户，trackSignup() 一般情况下建议只调用一次（通常在用户 注册 时调用），用户 登录 前后的行为的关联建议在业务端实现。在神策分
析 1.13 版本之前，多次调用 trackSignup() 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参
考 标识用户，并在必要时联系我们的技术支持人员。
5. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为
过滤条件或以用户属性作为维度进行多维分析。
使用 profileSet() 设置用户属性:
var properties = {
// Level VIP
''UserLv'': ''Elite VIP'',
// $is_login_id distinct_id ID true false false
''$is_login_id'' : True,
}
sa.profileSet(distinctId, properties);
对于不再需要的用户属性，可以通过 profileUnset() 接口将属性删除。
用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
5.1. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 接口不同的是，如果被设置的用户属性已存在，则这条记
录会被忽略而不会覆盖已有数据>，如果属性不存在则会自动创建。因此，profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如：
var distinctId = "ABCDEF123456789";
// AdSource "App Store"
sa.profileSetOnce(distinctId, {
"AdSource": "App Store"
// $is_login_id distinct_id ID true false false
''$is_login_id'' : True,
});
// AdSource "AdSource" "App Store"
sa.profileSetOnce(distinctId, {
"AdSource": "Search Engine",
// $is_login_id distinct_id ID true false false
''$is_login_id'' : True,
});
6. 物品元数据上报
在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。
item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个
参数，来完成对物品的操作。6.1. 设置物品
直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 properties 中定义。
物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
// Type
const itemType = ''book''
// ID
const itemId = ''0321714113''
//
const properties =
{ name: ''C++
Primer'', price:
31.54,
}
//
sa.itemSet(itemType, itemId, properties)
6.2. 删除一个物品
如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。
除物品 ID 与 物品所属类型外，不解析其他物品属性。
const itemType = ''book''
// ID
const itemId = ''0321714113''
//
sa.itemDelete(itemType, itemId)// Type
7. 设置 Node SDK
7.1. 设置数据发送参数
ES6
import SensorsAnalytics from )''sa-sdk-node''
const url = ''http://xxx.datasink.sensorsdata.cn/sa?token=xxx''
const sa = new SensorsAnalytics()
sa.disableReNameOption()
sa.submitTo(url)
采用自定义配置项目
import SensorsAnalytics from ''sa-sdk-node''
const url = ''http://xxx.datasink.sensorsdata.cn/sa?token=xxx''
const sa = new SensorsAnalytics()
sa.disableReNameOption()
const submitter = sa.submitTo({ url, gzip: true, mode: ''track'', timeout: 10 * 1000 })
// gzip: gzip true
// mode:
// : trackdebugdryRun track
// timeout: http(ms) 10simport SensorsAnalytics, { Submitter } from ''sa-sdk-node''
const url = ''http://xxx.datasink.sensorsdata.cn/sa?token=xxx''
const sa = new SensorsAnalytics()
const submitter = new Submitter(url)
sa.disableReNameOption()
sa.subscribe(submitter)
import SensorsAnalytics, { Submitter } from ''sa-sdk-node''
const url = ''http://xxx.datasink.sensorsdata.cn/sa?token=xxx''
const sa = new SensorsAnalytics()
sa.disableReNameOption()
const submitter = new Submitter({ url, gzip: true, mode: ''track'', timeout: 10 * 1000 })
sa.subscribe(submitter)
7.2. 批量发送 Batch Submit
WARN 批量发送不支持 debug 和 dryRun ，会出现 400 错误。
7.2.1. 按照数量大包发送
// Submit when 20 events are tracked
sa.submitTo(url, { count: 20 })
7.2.2. 按时间发送
// Submit when every 5 seconds
sa.submitTo(url, { timeSpan: 5 * 1000 })
7.2.3. 时间和数据量结合
// Submit every 5 seconds, but also submit immediately if 20 events tracked
sa.submitTo(url, { count: 20, timeSpan: 5 * 1000 })
8. 使用LoggingConsumer
Node SDK 中还提供了 LoggingConsumer ，如果启用，将不通过 Node 模块进行数据发送，而将所有数据都写到本地的日志文件里，然后用户再使用
LogAgent 读取日志文件，将数据导入我们的系统。
WARN 注意在生产环境下使用 pm2 的情况下，需要初始化时添加 pm2Mode(bool)，设置为 true。另外，还需要执行 pm2 install pm2-intercom。
// sa
var customPath = ''/Users/user/logs'';
sa.initLoggingConsumer(customPath, pm2Mode)
调用 LoggingConsumer 初始化语句后，后续数据发送仍然调用原有模式下的接口，如 track 等，SDK 将自动将数据写入当前设置的日志路径里面。 对应
的 SDK 版本最低为 sdk-sa-node@1.0.11 和 sa-sdk-node@1.1.1。
9. 更多信息更多信息请访问 GitHub 主页公共属性.公共属性 v1.13
1. 概述
如果某个事件的属性，在所有事件中都会出现，可以将该属性设置为事件公共属性。设置公共属性后，之后触发的所有事件，都会自动加上设置的公共属
性。
2. Android 公共属性
2.1. Android 设置事件公共属性
可以通过 registerSuperProperties() 设置事件公共属性。
例如将平台类型设置为事件的公共属性，设置方法如下:
// '''' "PlatformType" "Android"
try {
JSONObject properties = new JSONObject();
properties.put("PlatformType", "Android");
SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e)
{ e.printStackTrace(
);
}
重复调用 registerSuperProperties 会覆盖之前已设置的公共属性，公共属性会保存在 App 本地存储中。可以通过 unregisterSuperProperty() 删除一个公共
属性，使用 clearSuperProperties() 会删除所有已设置的事件公共属性。
当公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖公共属性。
注意：请在初始化 SDK 后调用 registerSuperProperties 方法，确保每个事件都会添加已设置的公共属性。
2.2. Android 设置动态公共属性
2.0.1 及以后的版本可以通过 registerDynamicSuperProperties 方法设置动态公共属性，设置之后 SDK 会自动获取 getDynamicSuperProperties 中的属性添
加到触发的事件中。
// SDK
SensorsDataAPI.sharedInstance().registerDynamicSuperProperties(new SensorsDataDynamicSuperProperties()
{ @Override
public JSONObject getDynamicSuperProperties()
{ try {
// isLogin() SDK getDynamicSuperProperties
boolean bool = isLogin();
return new JSONObject().put("isLogin",bool);
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
});
3. iOS 公共属性
3.1. iOS 设置事件公共属性
可以通过 registerSuperProperties: 方法设置事件公共属性。
例如将平台类型设置为事件的公共属性，设置方法如下:
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// '''' "PlatformType" "iOS"
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"PlatformType" : @"iOS"}];重复调用 registerSuperProperties: 会覆盖之前已设置的公共属性，公共属性会保存在 App 本地存储中。可以通过 unregisterSuperProperty: 删除一个公共属
性，使用 clearSuperProperties: 会删除所有已设置的事件公共属性。
当公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖公共属性。
注意：请在初始化 SDK 后调用 registerSuperProperties 方法，确保每个事件都会添加已设置的公共属性。
3.2. iOS 设置动态公共属性
1.10.8 及以后版本可以通过 registerDynamicSuperProperties: 方法设置动态公共属性，设置之后 SDK 会自动将设置的动态属性添加到触发的事件中。呈
现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary * _Nonnull{
// LoginManager isLogin App
BOOL isLogin = [LoginManager isLogin];
return @{@"isLogin":@(isLogin)};
}];
4. JavaScript 公共属性
4.1. JavaScript 设置静态公共属性
如果某个事件的属性，在所有事件中都会出现，可以通过 registerPage 方法将该属性设置为事件公共属性。例如电商产品中的用户等级，常作为事件的公共
属性。sensors.registerPage({gender:"male"}) 。这样的话，下次你在使用 sensors.track("index_visit") 时等同于 sensors.track("index_visit", {gender:"
male"})。
再比如想在当前页面的后续事件中都注入当前页面地址及前向地址属性，只针对当前页面有效的方法如下：
当公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖公共属性。
4.2. JavaScript 设置动态公共属性
当设置动态公共属性的时候，注意使用函数类型作为属性值，函数的返回值应当是神策支持的类型，请参考数据格式，否则会被过滤掉。
另外您如果使用了 ES6 语法如箭头函数等，则需要使用编译工具编译后运行。
var i=0
sensors.registerPage({
index: function()
{ return ++i; //
},
istrue: function() {
return i<10 ? true : false; // bool
},
isEmptyString: function()
{ return ""; //
},
isDate: function() {
return new Date(''December 17, 1995 03:24:00''); //
},
isArrayOfStr: function()
{ return ["1","2","3"]
//
}
})
另外如果函数在异步回调中返回值，这种情况也是会被过滤掉。
sensors.registerPage({
num:function(){
setTimeout(()=>{
return 100
},500)
}
})
5. 微信小程序公共属性
可以在 app.js 文件引入 sensorsdata.min.js 文件之后， init() 方法调用之前使用 registerApp() 方法设置公共属性。
例如将平台类型设置为事件的公共属性，设置方法如下:
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
let sensors = require(''./utils/sensorsdata.min.js'');
// '''' PlatformType ''miniprogram''
sensors.registerApp({
PlatformType:''miniprogram''
});
sensors.init();
当公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖公共属性。
6. 服务端公共属性
以 Java 端为例。可以通过 registerSuperProperties() 设置公共属性。例如将服务器的应用版本及机房地址设置为事件的公共属性，设置方法如下:
Map properties = new HashMap();
//
properties.put("ServerVersion", "1.2");
//
properties.put("Location", "BeiJing");//
sa.registerSuperProperties(properties);
设置公共属性后，再通过 track() 追踪事件时，公共属性会被添加到每个事件中，使用 clearSuperProperties() 会删除所有已设置的事件公共属性。当
公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖公共属性。预置事件与预置属性
1. 预置属性总表格
2. App SDK 预置事件和预置属性
3. Web JS SDK 预置事件和预置属性
4. 微信小程序 SDK 预置事件和预置属性
5. 支付宝小程序 SDK 预置事件和预置属性
6. QQ 小程序 SDK 预置事件和预置属性
7. 百度小程序 SDK 预置事件和预置属性
8. 微信小游戏 SDK 预置事件和预置属性
9. 字节跳动小程序 SDK 预置事件和预置属性
10. 快应用 SDK 预置事件和预置属性
11. 服务端预置事件及预置属性.预置事件与预置属性 v1.13
1. 预置属性总表格
2. App SDK 预置事件和预置属性
3. Web JS SDK 预置事件和预置属性
4. 微信小程序 SDK 预置事件和预置属性
5. 支付宝小程序 SDK 预置事件和预置属性
6. QQ 小程序 SDK 预置事件和预置属性
7. 百度小程序 SDK 预置事件和预置属性
8. 微信小游戏 SDK 预置事件和预置属性
9. 字节跳动小程序 SDK 预置事件和预置属性
10. 快应用 SDK 预置事件和预置属性
11. 服务端预置事件及预置属性1. 预置属性总表格
类别 英文变 中文名 类型 详细说明 示例值 是否 支持关闭 是 作用（分析 隐 Extractor 补充
量名 无需 （SDK 采 否 /技术 私
手动 集维度） 默 /Debug） 风
调用 认 险
自动 隐 相
开启 藏 关
保留属性 distinct_id 用户 ID 字符串 没登录就是 device_id，登录就是登 是 不支持 / 分析 高
录后 id
time 时间 时间 日期+时间 是 不支持 / 分析 无
基础预置 $app_state App状态 字符串 如果是被动启动（位置变化，收到 background 是 否 技术 无
属性 通知），系统会唤醒 App，在后台
运行，会有这个值
$app_versi 应用版本 字符串 客户的 App 的版本 1.2 是 不支持 否 分析 低
on
$is_first_d 是否首日访 逻辑 是不是首日之内触发 是 不支持 否 分析 低 服务端会根据 id 修
ay 问 正值
$is_first_ti 是否首次触 逻辑 历史上是不是地第一次触发,说明文 是 支持 否 分析 低 服务端会根据 id 修
me 发事件 档 ：https://manual.sensorsdata. 正值
cn/sa/latest/page-1573780.
html#id-.%E6%96%B0%E5%
A2%9E%E7%94%A8%E6%88%
B7%E5%8F%8A%E9%A6%96%
E6%97%A5%E9%A6%96%E6%
AC%A1%E6%A0%87%E8%AE%
B0v1.13-%E9%A6%96%E6%
AC%A1%E9%A6%96%E6%97%
A5%E6%A0%87%E8%AE%B0%
E4%BF%AE%E6%AD%A3
$event_dur 事件时长 数值 （$WebStay1.10.5 版本开始就采 是 支持 否 分析 低
ation / 视区停留 集的时长单位为秒，之前为毫秒。
时间，单位 对于神策分析版本大于等于 1.13
秒 的环境，如果上传了
event_duration 属性，会自动
rename 为 $event_duration）
（$MPHide 从本次小程序显示
$MPShow 到 $MPHide 小程序进
入后台或者关闭的时间）
$latitude 纬度 数值 iOS和 Android 需要手动开启， 否 支持 否 分析 高
Android 需要手动传入
$longitude 经度 数值 iOS和 Android 需要手动开启， 否 支持 否 分析 高
Android 需要手动传入
$title 页面标题 字符串 有业务含义的标题名称，比如浏览 是 支持 否 分析 低
器的标签上面可以看见的那个 title
$screen_n 页面名称 字符串 包名.类名 cn. 是 支持 否 技术 低
ame sensorsdata.
demo.
HomeFragm
ent
app_crash 崩溃原因 字符串 App 崩溃时调用栈的信息 / 否 支持 否 Debug 无
ed_reason
$url 页面地址 字符串 App SDK 自动采集的版本 是 不支持 否 分析 低
Android：3.2.8，iOS：1.11.5
$url_query 页面参数 字符串 页面地址?后面的部分 是 支持 否 分析 低
$url_path 页面路径 字符串 地址中从「/」到「?」前的部分 是 支持 否 分析 低
$referrer 前向地址 字符串 需要代码手动开启 是 支持 否 分析 中
微信小程序的 $referrer 只能取到
前一页的 $url_path，取不到 query
$referrer_h 前向域名 字符串 前序页面的域名，可能是站外域名 是 支持 否 分析 中
ost
$user_age UserAgent 字符串 http://http协议的一个部分，首部 User-Agent: 否 支持 是 技术 中
nt 包含了一个特征字符串，用来让网 /
络协议的对端来识别发起请求的用
统、软件开发商以及版本号。
$scene 启动场景 字符串 开启小程序时的场景值 扫描二维码 是 支持 否 分析 低
$share_de 分享次数 数值 当前这个分享行为/被分享行为的层 是 支持 否 分析 中
pth 级，比如第一个人的 $MPshare 的
这个数字为 1，另一个人通过那个
分享行为打开页面之后，
$MPshow 对应数字的值为 2
$share_dis 分享者 字符串 分享出当前这个小程序的用户的 id 是 支持 否 分析 中
tinct_id
$share_url 分享路径 字符串 分享出当前这个小程序时当时的分 是 支持 否 分析 低_path 享路径
$source_p 来源应用包 字符串 跳转到这个应用之前的应用的包名 是 支持 否 分析 中
ackage_na 名
me
$bot_name 爬虫名称 字符串 如果是爬虫，则会尝试解析爬虫名 是 支持 否 分析 低
称
$viewport_ 视区高度， 数值 浏览器实际视区大小 否 支持 否 分析 低
height 单位是 px
$viewport_ 视区距顶部 数值 如果一个页面没有滚动条，那么你 否 支持 否 分析 低
position 的位置，单 见到的界面与页面顶部的距离就是
位是 px 0，$viewport_position 就是 0
$viewport_ 视区宽度， 数值 浏览器实际视区大小 否 支持 否 分析 低
width 单位是 px
$item_join Item匹配模 匹配模式 任意事件都有可能，值为对应维度 否 否 技术 无
式 表的名称
$receive_ti 服务端收到 时间 / 是 不支持 是 技术 无 √
me 这个消息的
时间
设备相关 $brand 设备品牌 字符串 Apple，Huawei，HONOR， 是 不支持 否 分析 中
Xiaomi，Redmi 等
$manufact 设备制造商 字符串 Apple，Huawei，Xiaomi 等 是 不支持 否 分析 中
urer
$model 设备型号 字符串 是 不支持 否 分析 中
$os 操作系统 字符串 是 不支持 否 分析 中
$os_version 操作系统版 字符串 是 不支持 否 分析 中
本
$screen_h 屏幕高度 数值 是 不支持 否 分析 低
eight
$screen_wi 屏幕宽度 数值 是 不支持 否 分析 低
dth
$wifi 是否WIFI 逻辑 是 不支持 否 分析 低
$carrier 运营商 字符串 是 不支持 否 分析 中
$network_t 网络类型 字符串 是 不支持 否 分析 低
ype
$device_id 设备ID 字符串 JSSDK 需要手动开启，因为JSSDK 否 不支持 否 分析 高
没有本来就没有 device_id 的概念
$screen_or 屏幕方向 字符串 iOS和 Android 需要手动开启 否 不支持 否 分析 低
ientation
浏览器相 $browser 浏览器 字符串 是 不支持 否 分析 中
关
$browser_ 浏览器版本 字符串 是 不支持 否 分析 中
version
点击事件 $element_id 元素ID 字符串 不一定每个元素都有 是 支持 否 技术 低
相关
$element_ 元素名字 字符串 是 支持 否 技术 低
name
$element_t 元素类型 字符串 是 支持 否 技术 低
ype
$element_ 元素内容 字符串 是 支持 否 分析 低
content
$element_ 元素位置 字符串 列表控件才有该元素，否则为空 是 支持 否 技术 低
position
$element_ 元素选择器 字符串 iOS和 Android 需要手动开启 否 支持 否 技术 低
selector
$element_t 元素链接地 字符串 是 支持 否 技术 低
arget_url 址
$element_ 元素样式名 字符串 是 支持 否 技术 低
class_name
latest 相 $latest_ref 最近一次站 字符串 是 支持 否 分析 中
关属性 errer 外地址
$latest_ref 最近一次站 字符串 是 支持 否 分析 中
errer_host 外域名
$latest_se 最近一次搜 字符串 根据 refer 解析的，无需配置推广 是 支持 否 分析 中
arch_keyw 索引擎关键 链接
ord 词
$latest_tra 最近一次流 字符串 是 支持 否 分析 中
ffic_source 量来源类型
_type
$latest_lan 最近一次落 字符串 是 支持 否 分析 中
ding_page 地页$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_campai 告系列名称
gn
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_content 告系列内容
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_medium 告系列媒介
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_source 告系列来源
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_term 告系列字词
$latest_sc 最近一次启 字符串 是 支持 否 分析 低
ene 动场景
SDK 相关 $lib SDK类型 字符串 是 不支持 否 Debug 无
$lib_version SDK版本 字符串 是 不支持 是 Debug 无
$lib_method 埋点方式 字符串 是 不支持 是 Debug 无
$lib_detail 埋点细节 字符串 仅有预置事件才有 是 支持 是 Debug 无
渠道相关 $ios_install App 渠 道 匹 字符串 否 支持 / 技术 高 服务端会将本属性在
_source 配所需要的 数据库中删除
设备指纹信
息
$channel_ App 渠 道 匹 字符串 否 支持 / 技术 高 服务端会将本属性在
device_info 配所需要的 数据库中删除
设备指纹信
息（与上方
事件变量名
不同）
$ios_install 是否不进行 逻辑 禁用回调用 否 支持 否 技术 低
_disable_c 追踪回调
allback
$is_channe 是否进行渠 逻辑 标明该事件是否回调 否 支持 是 技术 低
l_callback_ 道匹配回调
event
$channel_ 渠道额外信 字符串 渠道监测链接里面的字段（比如 否 支持 是 技术 高
extra_infor 息 imei，oaid 等）变为属性
mation 中文名要改
$utm_matc 渠道追踪匹 字符串 模糊匹配，精准匹配 否 支持 否 技术 低
hing_type 配模式
$utm_sour 广告系列来 字符串 否 支持 否 分析 中
ce 源
$utm_medi 广告系列媒 字符串 否 支持 否 分析 中
um 介
$utm_term 广告系列字 字符串 否 支持 否 分析 中
词
$utm_cont 广告系列内 字符串 否 支持 否 分析 中
ent 容
$utm_cam 广告系列名 字符串 否 支持 否 分析 中
paign 称
$matched_ 渠道匹配关 字符串 用来记录渠道模糊匹配或者精准匹 否 支持 否 技术 高
key 键字 配的匹配成功的 key 的 key 值
$matching 渠道匹配关 字符串 用来记录渠道模糊匹配或者精准匹 否 支持 是 技术 高
_key_list 键字列表 配的匹配成功待匹配的 key 的 list
$short_url_ 短链Key 字符串 服务端用来记录渠道短链访问事件 否 支持 否 技术 低
key 的短链 key 值的属性
App 匹配有用，网页没有用，但是
也记了
$short_url_ 短链目标地 字符串 服务端用来记录渠道短链访问事件 否 支持 否 技术 低
target 址 的短链 key 值的属性
IP 相关 $ip IP 字符串 是 不支持 否 技术 无 √（Nginx 解析）
$city 城市 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
$province 省份 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
$country 国家 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
$ip_isp IP运营商 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
用户关联 $is_login_id 是否登录ID 逻辑 凡是发生在$SignUp后的事件值都 是 不支持 是 技术 低 √（入库时加上的）
相关 为 true
$track_sig 关联原始ID 字符串 是 不支持 否 技术 高
nup_origin
al_id
item 相关 $is_valid 是否为有效 逻辑 √
预置属性 记录$receive_ti 入库时间 时间 √
me
$update_ti 更新时间 时间 √
me.1. 预置属性总表格 v1.13
类别 英文变 中文名 类型 详细说明 示例值 是否 支持关闭 是 作用（分析 隐 Extractor 补充
量名 无需 （SDK 采 否 /技术 私
手动 集维度） 默 /Debug） 风
调用 认 险
自动 隐 相
开启 藏 关
保留属性 distinct_id 用户 ID 字符串 没登录就是 device_id，登录就是登 是 不支持 / 分析 高
录后 id
time 时间 时间 日期+时间 是 不支持 / 分析 无
基础预置 $app_state App状态 字符串 如果是被动启动（位置变化，收到 background 是 否 技术 无
属性 通知），系统会唤醒 App，在后台
运行，会有这个值
$app_versi 应用版本 字符串 客户的 App 的版本 1.2 是 不支持 否 分析 低
on
$is_first_d 是否首日访 布尔值 是不是首日之内触发 是 不支持 否 分析 低 服务端会根据 id 修
ay 问 正值
$is_first_ti 是否首次触 布尔值 历史上是不是地第一次触发,说明文 是 支持 否 分析 低 服务端会根据 id 修
me 发事件 档 ：https://manual.sensorsdata. 正值
cn/sa/latest/page-1573780.
html#id-.%E6%96%B0%E5%
A2%9E%E7%94%A8%E6%88%
B7%E5%8F%8A%E9%A6%96%
E6%97%A5%E9%A6%96%E6%
AC%A1%E6%A0%87%E8%AE%
B0v1.13-%E9%A6%96%E6%
AC%A1%E9%A6%96%E6%97%
A5%E6%A0%87%E8%AE%B0%
E4%BF%AE%E6%AD%A3
$event_dur 事件时长 数值 （$WebStay1.10.5 版本开始就采 是 支持 否 分析 低
ation / 视区停留 集的时长单位为秒，之前为毫秒。
时间，单位 对于神策分析版本大于等于 1.13
秒 的环境，如果上传了
event_duration 属性，会自动
rename 为 $event_duration）
（$MPHide 从本次小程序显示
$MPShow 到 $MPHide 小程序进
入后台或者关闭的时间）
$latitude 纬度 数值 iOS和 Android 需要手动开启， 否 支持 否 分析 高
Android 需要手动传入
$longitude 经度 数值 iOS和 Android 需要手动开启， 否 支持 否 分析 高
Android 需要手动传入
$title 页面标题 字符串 有业务含义的标题名称，比如浏览 是 支持 否 分析 低
器的标签上面可以看见的那个 title
$screen_n 页面名称 字符串 包名.类名 cn. 是 支持 否 技术 低
ame sensorsdata.
demo.
HomeFragm
ent
app_crash 崩溃原因 字符串 App 崩溃时调用栈的信息 / 否 支持 否 Debug 无
ed_reason
$url 页面地址 字符串 App SDK 自动采集的版本 是 不支持 否 分析 低
Android：3.2.8，iOS：1.11.5
$url_query 页面参数 字符串 页面地址?后面的部分 是 支持 否 分析 低
$url_path 页面路径 字符串 地址中从「/」到「?」前的部分 是 支持 否 分析 低
$referrer 前向地址 字符串 需要代码手动开启 是 支持 否 分析 中
微信小程序的 $referrer 只能取到
前一页的 $url_path，取不到 query
$referrer_h 前向域名 字符串 前序页面的域名，可能是站外域名 是 支持 否 分析 中
ost
$user_age UserAgent 字符串 http://http协议的一个部分，首部 User-Agent: 否 支持 是 技术 中
nt 包含了一个特征字符串，用来让网 /
络协议的对端来识别发起请求的用
统、软件开发商以及版本号。
$scene 启动场景 字符串 开启小程序时的场景值 扫描二维码 是 支持 否 分析 低
$share_de 分享次数 数值 当前这个分享行为/被分享行为的层 是 支持 否 分析 中
pth 级，比如第一个人的 $MPshare 的
这个数字为 1，另一个人通过那个
分享行为打开页面之后，
$MPshow 对应数字的值为 2
$share_dis 分享者 字符串 分享出当前这个小程序的用户的 id 是 支持 否 分析 中
tinct_id
$share_url 分享路径 字符串 分享出当前这个小程序时当时的分 是 支持 否 分析 低_path 享路径
$source_p 来源应用包 字符串 跳转到这个应用之前的应用的包名 是 支持 否 分析 中
ackage_na 名
me
$bot_name 爬虫名称 字符串 如果是爬虫，则会尝试解析爬虫名 是 支持 否 分析 低
称
$viewport_ 视区高度， 数值 浏览器实际视区大小 否 支持 否 分析 低
height 单位是 px
$viewport_ 视区距顶部 数值 如果一个页面没有滚动条，那么你 否 支持 否 分析 低
position 的位置，单 见到的界面与页面顶部的距离就是
位是 px 0，$viewport_position 就是 0
$viewport_ 视区宽度， 数值 浏览器实际视区大小 否 支持 否 分析 低
width 单位是 px
$item_join Item匹配模 匹配模式 任意事件都有可能，值为对应维度 否 否 技术 无
式 表的名称
$receive_ti 服务端收到 时间 / 是 不支持 是 技术 无 √
me 这个消息的
时间
设备相关 $brand 设备品牌 字符串 Apple，Huawei，HONOR， 是 不支持 否 分析 中
Xiaomi，Redmi 等
$manufact 设备制造商 字符串 Apple，Huawei，Xiaomi 等 是 不支持 否 分析 中
urer
$model 设备型号 字符串 是 不支持 否 分析 中
$os 操作系统 字符串 是 不支持 否 分析 中
$os_version 操作系统版 字符串 是 不支持 否 分析 中
本
$screen_h 屏幕高度 数值 是 不支持 否 分析 低
eight
$screen_wi 屏幕宽度 数值 是 不支持 否 分析 低
dth
$wifi 是否WIFI 布尔值 是 不支持 否 分析 低
$carrier 运营商 字符串 是 不支持 否 分析 中
$network_t 网络类型 字符串 是 不支持 否 分析 低
ype
$device_id 设备ID 字符串 JSSDK 需要手动开启，因为JSSDK 否 不支持 否 分析 高
没有本来就没有 device_id 的概念
$screen_or 屏幕方向 字符串 iOS和 Android 需要手动开启 否 不支持 否 分析 低
ientation
浏览器相 $browser 浏览器 字符串 是 不支持 否 分析 中
关
$browser_ 浏览器版本 字符串 是 不支持 否 分析 中
version
点击事件 $element_id 元素ID 字符串 不一定每个元素都有 是 支持 否 技术 低
相关
$element_ 元素名字 字符串 是 支持 否 技术 低
name
$element_t 元素类型 字符串 是 支持 否 技术 低
ype
$element_ 元素内容 字符串 是 支持 否 分析 低
content
$element_ 元素位置 字符串 列表控件才有该元素，否则为空 是 支持 否 技术 低
position
$element_ 元素选择器 字符串 iOS和 Android 需要手动开启 否 支持 否 技术 低
selector
$element_t 元素链接地 字符串 是 支持 否 技术 低
arget_url 址
$element_ 元素样式名 字符串 是 支持 否 技术 低
class_name
latest 相 $latest_ref 最近一次站 字符串 是 支持 否 分析 中
关属性 errer 外地址
$latest_ref 最近一次站 字符串 是 支持 否 分析 中
errer_host 外域名
$latest_se 最近一次搜 字符串 根据 refer 解析的，无需配置推广 是 支持 否 分析 中
arch_keyw 索引擎关键 链接
ord 词
$latest_tra 最近一次流 字符串 是 支持 否 分析 中
ffic_source 量来源类型
_type
$latest_lan 最近一次落 字符串 是 支持 否 分析 中
ding_page 地页$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_campai 告系列名称
gn
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_content 告系列内容
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_medium 告系列媒介
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_source 告系列来源
$latest_ut 最近一次广 字符串 是 支持 否 分析 中
m_term 告系列字词
$latest_sc 最近一次启 字符串 是 支持 否 分析 低
ene 动场景
SDK 相关 $lib SDK类型 字符串 是 不支持 否 Debug 无
$lib_version SDK版本 字符串 是 不支持 是 Debug 无
$lib_method 埋点方式 字符串 是 不支持 是 Debug 无
$lib_detail 埋点细节 字符串 仅有预置事件才有 是 支持 是 Debug 无
渠道相关 $ios_install App 渠 道 匹 字符串 否 支持 / 技术 高 服务端会将本属性在
_source 配所需要的 数据库中删除
设备指纹信
息
$channel_ App 渠 道 匹 字符串 否 支持 / 技术 高 服务端会将本属性在
device_info 配所需要的 数据库中删除
设备指纹信
息（与上方
事件变量名
不同）
$ios_install 是否不进行 布尔值 禁用回调用 否 支持 否 技术 低
_disable_c 追踪回调
allback
$is_channe 是否进行渠 布尔值 标明该事件是否回调 否 支持 是 技术 低
l_callback_ 道匹配回调
event
$channel_ 渠道额外信 字符串 渠道监测链接里面的字段（比如 否 支持 是 技术 高
extra_infor 息 imei，oaid 等）变为属性
mation 中文名要改
$utm_matc 渠道追踪匹 字符串 模糊匹配，精准匹配 否 支持 否 技术 低
hing_type 配模式
$utm_sour 广告系列来 字符串 否 支持 否 分析 中
ce 源
$utm_medi 广告系列媒 字符串 否 支持 否 分析 中
um 介
$utm_term 广告系列字 字符串 否 支持 否 分析 中
词
$utm_cont 广告系列内 字符串 否 支持 否 分析 中
ent 容
$utm_cam 广告系列名 字符串 否 支持 否 分析 中
paign 称
$matched_ 渠道匹配关 字符串 用来记录渠道模糊匹配或者精准匹 否 支持 否 技术 高
key 键字 配的匹配成功的 key 的 key 值
$matching 渠道匹配关 字符串 用来记录渠道模糊匹配或者精准匹 否 支持 是 技术 高
_key_list 键字列表 配的匹配成功待匹配的 key 的 list
$short_url_ 短链Key 字符串 服务端用来记录渠道短链访问事件 否 支持 否 技术 低
key 的短链 key 值的属性
App 匹配有用，网页没有用，但是
也记了
$short_url_ 短链目标地 字符串 服务端用来记录渠道短链访问事件 否 支持 否 技术 低
target 址 的短链 key 值的属性
IP 相关 $ip IP 字符串 是 不支持 否 技术 无 √（Nginx 解析）
$city 城市 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
$province 省份 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
$country 国家 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
$ip_isp IP运营商 字符串 是 不支持 否 分析 无 √（根据 IP 解析）
用户关联 $is_login_id 是否登录ID 布尔值 凡是发生在$SignUp后的事件值都 是 不支持 是 技术 低 √（入库时加上的）
相关 为 true
$track_sig 关联原始ID 字符串 是 不支持 否 技术 高
nup_origin
al_id
item 相关 $is_valid 是否为有效 布尔值 √
预置属性 记录$receive_ti 入库时间 时间 √
me
$update_ti 更新时间 时间 √
me2. APP SDK 预置属性和预置属性
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 备注
件 件 性 件 性
英 显 英 属 值
文 示 文 性 类
变 名 变 显 型
量 量 示
名 名 名
$App App $预置 启动 App 或从后台切换进入 App 时触发 Android/iOS SDK通用性采
Start 启动 属性 集，开启AutoTrack接口将自
动开启，文档请参考https://w
$is_fi 是否 逻辑 表示是否是首次启动 App，可参考文档 新增用户及首日首次标 ww.sensorsdata.cn/manual
rst_ti 首次 记 /android_sdk_autotrack.html
me
$resu 是否 逻辑
me_fr 从后
om_b 台唤 UTM广告系列参数，用来渠道
ackgr 醒 追 踪 ， 参 考 文 档 ：
ound https://sensorsdata.cn
/manual
$scre 页面 字符 Activity 的包名.类名（仅 Android 端有，iOS 端的启动逻辑并 /app_channel_tracking.html
en_n 名称 串 不需要跳转到某个页面即可判断是否启动，因此 iOS 端启动时
ame 采集不到页面名称） $AppStart 、 $AppEnd 不 支 持
增加自定义属性，可以增加自
定义的公共属性
$title 页面 字符 Activity 的标题（仅 Android 端有，iOS 端的启动逻辑并不需
标题 串 要跳转到某个页面即可判断是否启动，因此 iOS 端启动时采集
不到页面标题)
$App App $预置 退出 App 或 App
End 退出 属性 进入后台时触发
$eve 停留 数值 本次 App 启动到 App退出的时长，单位为 秒
nt_du 时长
ration
$scre 页面 字符 Activity 的包名.类名（仅 Android 端有，iOS 端的退出逻辑并
en_n 名称 串 不需要跳转到某个页面即可判断是否启动，因此 iOS 端退出时
ame 采集不到页面标题）
$title 页面 字符 Activity 的标题（仅 Android 端有，iOS 端的退出逻辑并不需
标题 串 要跳转到某个页面即可判断是否启动，因此 iOS 端退出时采集
不到页面标题）
$App App $预置 打开一个 Activity / ViewController 页面时触发（对
View 浏览 属性 于Android Fragment 默认不会触发浏览页面事件，
Screen 页面 如果采集，需要单独开启）
$scre 页面 字符 Activity 的包名.类名（Android 端） / ViewController 的类名
en_n 名称 串 （iOS 端）；可手动设置该属性的值
ame
$title 页面 字符 Activity 的标题（Android 端）/ViewController 的标题（iOS
标题 串 端）
$url 页面 字符 自动采集的版本 Android：3.2.8，iOS：1.11.5
地址 串
$refe 前向 字符 自动采集的版本 Android：3.2.8，iOS：1.11.5
rrer 地址 串
$App App $预置 点击控件时触发
Click 元素 属性
点击 可采集大部分控件，如：CheckBox、RadioButton、
$scre 页面 字符 Activity 的包名.类名（Android 端） / ViewController 的类名 button、SwitchCompat、Spinner、TextView、
en_n 名称 串 （iOS 端）；可手动设置该属性的值 ImageView、ImageButton、SeekBar、RatingBar、
ame RadioGroup、Menultem、ExpandableListView、
Dialog、ListView、GridView、TabHost等
$title 页面 字符 Activity 的标题（Android 端）/ViewController 的标题（iOS
标题 串 端）
$ele 元素 字符 元素在模块中的位置，从 0 开始。
ment 位置 串 只有特殊控件下，该属性才会采集到值（比如 iOS 端
_posi 的 UITableView 和UICollectionView 等，Android 端
tion 的 ListView 等。对于采集不到该属性值的控件，该属性值在神
策分析页面展示为「未知」。
$ele 元素 字符 Android 端默认会获取；
ment ID 串
_id iOS 端每个控件一般不会设置 ID，因此 iOS 端默认会不获取。
可手动设置
$ele 元素 字符 控件代码内设置的元素内容，如果一个控件中没有设置元素内
ment 内容 串 容，或者控件类型为图片，则该属性采集不到值，在神策事件
_cont 分析页面展示为 「未知」。因此如果发现某个按钮的内容采集
ent 不到值，需要和客户的研发同学确认下这个按钮控件的类型，
以及是否有在代码中设置元素内容。
$ele 元素 字符 控件的类型，例如 Button
ment 类型 串_type
$ele 元素 字符 该属性主要记录一个按钮在 APP 中的位置，神策的 App 点击
ment 选择 串 图展示时会使用到此属性，业务人员无需关注此属性的取值逻
_sele 器 辑。
ctor
$ele 元素 字符 可视化全埋点功能会采集该属性的值，需要手动代码开启
ment 路径 串
_path
AppIn App $预置 需要调用 trackInstallation 接口采集采集该事件，且
stall 激活 属性 App 安装后首次打开才会触发，第二次打开不会再触
发。
$bro 浏览 字符 通过 UA 解析出来的值
wser 器名 串
$utm 广告 字符 需要使用神策 App 渠道追踪方法，渠道匹配成功之后，
_sour 系列 串 AppInstall 事件才会有 $utm 相关的属性，具体可参考神策的 A
ce 来源 pp 渠道追踪。
$utm 广告 字符
_med 系列 串
ium 媒介
$utm 广告 字符
_term 系列 串
字词
$utm 广告 字符
_cont 系列 串
ent 内容
$utm 广告 字符
_cam 系列 串
paign 名称
$ios_ / 字符 记录 App 精准匹配时的匹配字段，比如 IMEI、Android ID、
instal 串 Mac 地址、IDFA。在 App 端采集数据时，会上传此字段，但是
l_sou 在 extractor 模块会将该字段去掉不入库。因此该属性不会入
rce 库。
$utm 渠道 字符 在 App 端采集事件时默认没有该属性，而是在 extractor 模块
_mat 追踪 串 添加，是App 渠道追踪匹配成功时，记录渠道匹配成功的模
ching 匹配 式，比如设备指纹模糊匹配，设备标识精准匹配，如果没有匹
_type 模式 配成功，该属性值在事件分析页面展示为「未知」。
$mac 渠道 字符 在 App 端采集事件时默认没有该属性，而是在 extractor 模块
tched 匹配 串 添加，是App 渠道追踪匹配成功时，记录匹配关键字段，比如
_key 关键 是用 IMEI 匹配成功的，则记录 md5 后的IMEI，如果是用
字 IP_UA 的方式匹配成功的，则记录为 IP_UA。如果没有匹配成
功，该属性值在事件分析页面展示为「未知」。
$mac 渠道 字符 SA 1.14 版本后支持；在 App 端采集事件时默认没有该属性，
tched 匹配 串 而是在 extractor 模块添加，是记录该激活事件所有可匹配的关
_key_ 关键 键字，比如 md5 后的 IMEI，Android ID，oaid ，IP_UA 等。
list 字列 在匹配的时候，会按照这些关键字的优先级，和点击广告时记录
表 的关键字进行匹配。
AppC App $预置 只有在开启崩溃采集时才会采集 APP 崩溃
rash 崩溃 属性
app_ 崩溃 字符
crash 原因 串
ed_re
ason
$App App $预置 iOS APP 被系统拉活 iOS 端有此事件，Android 端
Start 被动 属性 没有。
Passi 启动
vely $app App 字符 iOS 端会默认获取，Android 端不会获取
_state 状态 串
所有事件都有的预置属性
属性名 属性 默认显 说明 备注
类型 示名
$app_version 字符串 应用版本 APP 的应用版本
$lib 字符串 SDK类型 SDK 类型，比如 Android/iOS
$lib_version 字符串 SDK版本 SDK 版本
$manufacturer 字符串 设备制造 设备制造商
商
$model 字符串 设备型号 设备型号
$os 字符串 操作系统 操作系统$os_version 字符串 操作系统 操作系统版本
版本
$screen_heig 数值 屏幕高度 屏幕高度
ht
$screen_width 数值 屏幕宽度 屏幕宽度
$wifi 逻辑 是否 WiFi 事件触发时是否为 WiFi
$carrier 字符串 运营商名 事件触发时设备 SIM 卡的运营商名称
称
$network_type 字符串 网络类型 事件触发时的网络类型，如果 SDK 没有获取网络类型的权限，或者手机为飞行模式、未插卡且没有连接
WiFi等情况，对应的网络类型为 NULL。
$is_first_day 逻辑 是否首日 表示是否是首日触发事件，此属性可用于筛选新老用户，具体取值逻辑可参考文档 新增用户及首日首次标记 Android SDK 1.6.27
访问 版本支持
iOS SDK 1.6.29 版 本
支持
$device_id 字符串 设备ID Android 端主要取 Android ID ，iOS 端先尝试获取 IDFA，如果获取不到，则取 IDFV，具体取值逻辑可参 Android SDK 1.7.1
考文档 如何准确的标识用户 版本支持
iOS SDK 1.10.18 版
本支持
$screen_orie 字符串 屏幕方向 只有在开启 enableTrackScreenOrientation: 时才会采集 Android/iOS 1.10.1
ntation 版本支持
$latitude 数值 GPS信息 纬度*106 Android/iOS 1.10.1
版本支持
只有在开启 enableTrackGPSLocation: 时才会采集
Android 端需要手动
传入
$longitude 数值 GPS信息 经度*106 Android/iOS 1.10.1
版本支持
只有在开启 enableTrackGPSLocation: 时才会采集
Android 端需要手动
传入
追踪并进行渠道匹配和回传时的预置事件属性
属性名 属 默认 说明 备注
性 显示
类 名
型
$channel_d 字符 是否不进 App 渠道追踪自定义事件时进行渠道匹配，可以调用 - track SA 1.15+ 版本后支持
evice_info 串 行追踪回 ChannelEvent:properties: IMEIAndroid IDMac
调 IDFA SDK
$is_channel 逻辑 是否进行 App 渠道追踪自定义事件时进行渠道匹配，可以调用 - track SA 1.15+ 版本支持；
_callback_e 渠道匹配 ChannelEvent:properties: SDK
vent 回调 默认只有第一次触发渠道追踪自定义事件时，该属性的值为 ture，表示匹
配成功会，会给广告商回调渠道数据。后续再次触发该事件时，该属 性
值为 false。
预置用户属性
属 属 默 说明 备注
性 性 认
名 类 显
型 示
名
$first Date 首次 调用 trackInstallation 接口后，新用户首次启动App， 会给此属性赋值 该属性是在调用 trackInstallation 接口时设置的， 一般标记
_visit time 访问 在匿名 ID （Android ID/IDFA）的用户身上，如果登录 ID 和
_time （时 时间 匿名 ID 没有关联成功，则登录 ID 用户的该属性值没值。
间）
$utm 字符 首次 同上
_sour 串 广告
ce 系列
来源$utm 字符 首次 同上
_med 串 广告
ium 系列
媒介
$utm 字符 首次 这些属性是依赖于调用 trackInstallation 接口，且使用 APP 渠道追踪，在匹配成功 同上
_term 串 广告 后，渠道链接中包含的对应渠道信息（ utm_ 参数）会被写入用户表，渠道追踪匹配
系列 模式和渠道匹配关键字则记录匹配的渠道方式，以及通过哪个关键字匹配上的，
字词
$utm 字符 首次 同上
_cont 串 广告
ent 系列
内容
$utm 字符 首次 同上
_cam 串 广告
paign 系列
名称
$utm 字符 渠道 同上
_mat 串 追踪
ching 匹配
_type 模式
$mat 字符 渠道 同上
ched 串 匹配
_key 关键
字
$mat 字符 渠道 渠道匹配关键字列表，包含所有可能用于渠道匹配的 key 同上，且 SA 1.14+ 版本支持，渠道匹配关键字列表，包含
ching 串 匹配 所有可能用于渠道匹配的 关键字
_key_ 关键
list 字列
表.2. App SDK 预置事件和预置属性 v1.13
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 备注
件 件 性 件 性
英 显 英 属 值
文 示 文 性 类
变 名 变 显 型
量 量 示
名 名 名
$App App $预置 启动 App 或从后台切换进入 App 时触发 Android/iOS SDK通用性采
Start 启动 属性 集，开启AutoTrack接口将自
动开启，文档请参考https://w
$is_fi 是否 布尔 表示是否是首次启动 App，可参考文档 新增用户及首日首次标 ww.sensorsdata.cn/manual
rst_ti 首次 值 记 /android_sdk_autotrack.html
me
$resu 是否 布尔
me_fr 从后 值
om_b 台唤 UTM广告系列参数，用来渠道
ackgr 醒 追 踪 ， 参 考 文 档 ：
ound https://sensorsdata.cn
/manual
$scre 页面 字符 Activity 的包名.类名（仅 Android 端有，iOS 端的启动逻辑并 /app_channel_tracking.html
en_n 名称 串 不需要跳转到某个页面即可判断是否启动，因此 iOS 端启动时
ame 采集不到页面名称） $AppStart 、 $AppEnd 不 支 持
增加自定义属性，可以增加自
定义的公共属性
$title 页面 字符 Activity 的标题（仅 Android 端有，iOS 端的启动逻辑并不需
标题 串 要跳转到某个页面即可判断是否启动，因此 iOS 端启动时采集
不到页面标题)
$App App $预置 退出 App 或 App
End 退出 属性 进入后台时触发
$eve 停留 数值 本次 App 启动到 App退出的时长，单位为 秒
nt_du 时长
ration
$scre 页面 字符 Activity 的包名.类名（仅 Android 端有，iOS 端的退出逻辑并
en_n 名称 串 不需要跳转到某个页面即可判断是否启动，因此 iOS 端退出时
ame 采集不到页面标题）
$title 页面 字符 Activity 的标题（仅 Android 端有，iOS 端的退出逻辑并不需
标题 串 要跳转到某个页面即可判断是否启动，因此 iOS 端退出时采集
不到页面标题）
$App App $预置 打开一个 Activity / ViewController 页面时触发（对
View 浏览 属性 于Android Fragment 默认不会触发浏览页面事件，
Screen 页面 如果采集，需要单独开启）
$scre 页面 字符 Activity 的包名.类名（Android 端） / ViewController 的类名
en_n 名称 串 （iOS 端）；可手动设置该属性的值
ame
$title 页面 字符 Activity 的标题（Android 端）/ViewController 的标题（iOS
标题 串 端）
$url 页面 字符 自动采集的版本 Android：3.2.8，iOS：1.11.5
地址 串
$refe 前向 字符 自动采集的版本 Android：3.2.8，iOS：1.11.5
rrer 地址 串
$App App $预置 点击控件时触发
Click 元素 属性
点击 可采集大部分控件，如：CheckBox、RadioButton、
$scre 页面 字符 Activity 的包名.类名（Android 端） / ViewController 的类名 button、SwitchCompat、Spinner、TextView、
en_n 名称 串 （iOS 端）；可手动设置该属性的值 ImageView、ImageButton、SeekBar、RatingBar、
ame RadioGroup、Menultem、ExpandableListView、
Dialog、ListView、GridView、TabHost等
$title 页面 字符 Activity 的标题（Android 端）/ViewController 的标题（iOS
标题 串 端）
$ele 元素 字符 元素在模块中的位置，从 0 开始。
ment 位置 串 只有特殊控件下，该属性才会采集到值（比如 iOS 端
_posi 的 UITableView 和UICollectionView 等，Android 端
tion 的 ListView 等。对于采集不到该属性值的控件，该属性值在神
策分析页面展示为「未知」。
$ele 元素 字符 Android 端默认会获取；
ment ID 串
_id iOS 端每个控件一般不会设置 ID，因此 iOS 端默认会不获取。
可手动设置
$ele 元素 字符 控件代码内设置的元素内容，如果一个控件中没有设置元素内
ment 内容 串 容，或者控件类型为图片，则该属性采集不到值，在神策事件
_cont 分析页面展示为 「未知」。因此如果发现某个按钮的内容采集
ent 不到值，需要和客户的研发同学确认下这个按钮控件的类型，
以及是否有在代码中设置元素内容。
$ele 元素 字符 控件的类型，例如 Button
ment 类型 串_type
$ele 元素 字符 该属性主要记录一个按钮在 APP 中的位置，神策的 App 点击
ment 选择 串 图展示时会使用到此属性，业务人员无需关注此属性的取值逻
_sele 器 辑。
ctor
$ele 元素 字符 可视化全埋点功能会采集该属性的值，需要手动代码开启
ment 路径 串
_path
AppIn App $预置 需要调用 trackInstallation 接口采集采集该事件，且
stall 激活 属性 App 安装后首次打开才会触发，第二次打开不会再触
发。
$bro 浏览 字符 通过 UA 解析出来的值
wser 器名 串
$utm 广告 字符 需要使用神策 App 渠道追踪方法，渠道匹配成功之后，
_sour 系列 串 AppInstall 事件才会有 $utm 相关的属性，具体可参考神策的 A
ce 来源 pp 渠道追踪。
$utm 广告 字符
_med 系列 串
ium 媒介
$utm 广告 字符
_term 系列 串
字词
$utm 广告 字符
_cont 系列 串
ent 内容
$utm 广告 字符
_cam 系列 串
paign 名称
$ios_ / 字符 记录 App 精准匹配时的匹配字段，比如 IMEI、Android ID、
instal 串 Mac 地址、IDFA。在 App 端采集数据时，会上传此字段，但是
l_sou 在 extractor 模块会将该字段去掉不入库。因此该属性不会入
rce 库。
$utm 渠道 字符 在 App 端采集事件时默认没有该属性，而是在 extractor 模块
_mat 追踪 串 添加，是App 渠道追踪匹配成功时，记录渠道匹配成功的模
ching 匹配 式，比如设备指纹模糊匹配，设备标识精准匹配，如果没有匹
_type 模式 配成功，该属性值在事件分析页面展示为「未知」。
$mac 渠道 字符 在 App 端采集事件时默认没有该属性，而是在 extractor 模块
tched 匹配 串 添加，是App 渠道追踪匹配成功时，记录匹配关键字段，比如
_key 关键 是用 IMEI 匹配成功的，则记录 md5 后的IMEI，如果是用
字 IP_UA 的方式匹配成功的，则记录为 IP_UA。如果没有匹配成
功，该属性值在事件分析页面展示为「未知」。
$mac 渠道 字符 SA 1.14 版本后支持；在 App 端采集事件时默认没有该属性，
tched 匹配 串 而是在 extractor 模块添加，是记录该激活事件所有可匹配的关
_key_ 关键 键字，比如 md5 后的 IMEI，Android ID，oaid ，IP_UA 等。
list 字列 在匹配的时候，会按照这些关键字的优先级，和点击广告时记录
表 的关键字进行匹配。
AppC App $预置 只有在开启崩溃采集时才会采集 APP 崩溃
rashed 崩溃 属性
app_ 崩溃 字符
crash 原因 串
ed_re
ason
$App App $预置 iOS APP 被系统拉活 iOS 端有此事件，Android 端
Start 被动 属性 没有。
Passi 启动
vely $app App 字符 iOS 端会默认获取，Android 端不会获取
_state 状态 串
所有事件都有的预置属性
属性名 属性 默认 说明 备注
类型 显示
名
$app_version 字符串 应用版本 APP 的应用版本
$lib 字符串 SDK类型 SDK 类型，比如 Android/iOS
$lib_version 字符串 SDK版本 SDK 版本
$manufactur 字符串 设备制造 设备制造商
er 商
$model 字符串 设备型号 设备型号
$os 字符串 操作系统 操作系统$os_version 字符串 操作系统 操作系统版本
版本
$screen_heig 数值 屏幕高度 屏幕高度（iOS 端是逻辑分辨率，开发中的点像素；Android 采集的是物理像素点，例如 Android 手机分辨
ht 率是 1920 x 1080，采集到的就是这个值。）
$screen_width 数值 屏幕宽度 屏幕宽度（iOS 端是逻辑分辨率，开发中的点像素；Android 采集的是物理像素点，例如 Android 手机分辨
率是 1920 x 1080，采集到的就是这个值。）
$wifi 布尔值 是否 事件触发时是否为 WiFi
WiFi
$carrier 字符串 运营商名 事件触发时设备 SIM 卡的运营商名称
称
$network_type 字符串 网络类型 事件触发时的网络类型，如果 SDK 没有获取网络类型的权限，或者手机为飞行模式、未插卡且没有连接
WiFi等情况，对应的网络类型为 NULL。
$is_first_day 布尔值 是否首日 表示是否是首日触发事件，此属性可用于筛选新老用户，具体取值逻辑可参考文档 新增用户及首日首次标记 Android SDK
访问 1.6.27 版本支持
iOS SDK 1.6.29 版
本支持
$ip 字符串 IP 后端通过解析 HTTP 请求而得到
$country 字符串 国家 由 IP 解析得到
$province 字符串 省份
$city 字符串 城市
$device_id 字符串 设备ID Android 端主要取 Android ID ，iOS 端先尝试获取 IDFA，如果获取不到，则取 IDFV，具体取值逻辑可参考 Android SDK 1.7.1
文档 如何准确的标识用户 版本支持
iOS SDK 1.10.18 版
本支持
$screen_orie 字符串 屏幕方向 只有在开启 enableTrackScreenOrientation: 时才会采集 Android/iOS 1.10.1
ntation 版本支持
$latitude 数值 GPS信息 纬度*106 Android/iOS 1.10.1
版本支持
只有在开启 enableTrackGPSLocation: 时才会采集
Android 端需要手动
传入
$longitude 数值 GPS信息 经度*106 Android/iOS 1.10.1
版本支持
只有在开启 enableTrackGPSLocation: 时才会采集
Android 端需要手动
传入
追踪并进行渠道匹配和回传时的预置事件属性
属性名 属 默认 说明 备注
性 显示
类 名
型
$channel_d 字符 是否不进 App 渠道追踪自定义事件时进行渠道匹配，可以调用 - track SA 1.15+ 版本后支持
evice_info 串 行追踪回 ChannelEvent:properties: IMEIAndroid IDMac
调 IDFA SDK
$is_channel 布尔 是否进行 App 渠道追踪自定义事件时进行渠道匹配，可以调用 - track SA 1.15+ 版本支持；
_callback_e 值 渠道匹配 ChannelEvent:properties: SDK
vent 回调 默认只有第一次触发渠道追踪自定义事件时，该属性的值为 ture，表示匹
配成功会，会给广告商回调渠道数据。后续再次触发该事件时，该属 性
值为 false。
预置用户属性
属 属 默 说明 备注
性 性 认
名 类 显
型 示
名$first Date 首次 调用 trackInstallation 接口后，新用户首次启动App， 会给此属性赋值 该属性是在调用 trackInstallation 接口时设置的， 一般标记
_visit time 访问 在匿名 ID （Android ID/IDFA）的用户身上，如果登录 ID 和
_time （时 时间 匿名 ID 没有关联成功，则登录 ID 用户的该属性值没值。
间）
$utm 字符 首次 同上
_sour 串 广告
ce 系列
来源
$utm 字符 首次 同上
_med 串 广告
ium 系列
媒介
这些属性是依赖于调用 trackInstallation 接口，且使用 APP 渠道追踪，在匹配成功
$utm 字符 首次 后，渠道链接中包含的对应渠道信息（ utm_ 参数）会被写入用户表，渠道追踪匹配 同上
_term 串 广告 模式和渠道匹配关键字则记录匹配的渠道方式，以及通过哪个关键字匹配上的，
系列
字词
$utm 字符 首次 同上
_cont 串 广告
ent 系列
内容
$utm 字符 首次 同上
_cam 串 广告
paign 系列
名称
$utm 字符 渠道 同上
_mat 串 追踪
ching 匹配
_type 模式
$mat 字符 渠道 同上
ched 串 匹配
_key 关键
字
$mat 字符 渠道 渠道匹配关键字列表，包含所有可能用于渠道匹配的 key 同上，且 SA 1.14+ 版本支持，渠道匹配关键字列表，包含
ching 串 匹配 所有可能用于渠道匹配的 关键字
_key_ 关键
list 字列
表3. Web JS SDK 预置事件和预置属性
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 备注
件 件 性 件 性
英 显 英 属 值
文 示 文 性 类
变 名 变 显 型
量 量 示
名 名 名
$pag Web $预置 打开一个页面时自动采集，根据 autoTrack 的触 JS SDK通用性采集，打开autoTrack接口后会自动采
eview 浏览 属性 发进行上报记录，触发时机可以自定义配置，一 集，参考文档：JS SDK
页面 般建议放在初始化神策 SDK 后立刻执行。
$is_fir 是否 逻辑 新用户首次访问页面时，触发的第一 https://www.sensorsdata.cn/manual/js_sdk.html
st_time 首次 个 $pageview ，该属性值为 true，后续再
触发 $pageview 事件时，该属性都为
false。
UTM广告系列参数，可用来进行渠道追踪，参考文
$title 页面 字符 页面标签对的内容 档：
标题 串
$url 页面 字符 JS SDK默认采集的预置属性 https://www.sensorsdata.cn/manual
地址 串 /app_channel_tracking.html
$url_p 页面 字符
ath 路径 串
$refer 前向 字符 如果直接打开页面，值为空字符串
rer_ho 域名 串
st
$refer 前向 字符 如果直接打开页面，值为空字符串
rer 地址 串
$utm_ 广告 字符 打开页面的 url 有该参数就采集
campa 系列 串
ign 名称
$utm_ 广告 字符 打开页面的 url 有该参数就采集
source 系列 串
来源
$utm_ 广告 字符 打开页面的 url 有该参数就采集
medium 系列 串
媒介
$utm_ 广告 字符 打开页面的 url 有该参数就采集
term 系列 串
字词
$utm_ 广告 字符 打开页面的 url 有该参数就采集
conte 系列 串
nt 内容
$Web Web $预置 点击一个元素/控件/按钮（可扩展） 时自动采集 JS SDK通用性采集，打开autoTrack接口后会自动采
Click 元素 属性 集，参考文档：
点击
$elem 元素 字符 元素有 id 属性才采集 https://www.sensorsdata.cn/manual/js_sdk.html
ent_id ID 串
$elem 元素 字符 元素标签对直接的文本，例如：<a><span>
ent_co 内容 串 提交</span></a>，采集的是 “提交”
ntent
$elem 元素 字符 元素有 name 属性的时候才采集
ent_na 名字 串
me
$elem 元素 字符 元素有 class name 属性的时候才采集
ent_cl 样式 串
ass_n 名
ame
$elem 元素 字符 默认采集
ent_ty 类型 串
pe
$elem 元素 字符 默认采集
ent_se 选择 串
lector 器
$elem 元素 字符 a 标签默认采集
ent_ta 链接 串
rget_u 地址
rl
$url 页面 字符
地址 串
$title 页面 字符
标题 串
$url_p 页面 字符
ath 路径 串$view 视区 数值
port_ 宽度
width
$Web Web $预置 有效停留：关注网页区域不滚动，期间鼠标可以 若要使用神策分析中热力图-触达率图的功能，则需采
Stay 视区 属性 移动、点击等操作。 集此事件。事件触发条件：在一个页面停留4秒以上并
停留 进行有效滑动则触发。不支持增加自定义属性
$view 视区 数值 视区宽度（当前浏览器的可视区域的宽度， 有效停留时间：停留时间超过规定的时间，
port_ 宽度 单位是 px。） javascript sdk 中默认为 4 秒(参数可设置)。
width
如果发生页面滚动时候，之前的页面停留是有效
$view 视区 数值 视区距顶部的位置（当前滚动条所在位置， 停留，也就是超过默认的4秒或者自定义的时间，
port_p 距顶 距离页面顶部的高度，单位是 px。） javascript sdk就会发送一次页面停留事件。
osition 部的
位置
$view 视区 数值 视区高度（当前浏览器的可视区域的高度，
port_h 高度 单位是 px。）
eight
$event 停留 数值 距上次触发该事件的时间差。
_durat 时长
ion 页面没有操作，超过 4 秒后滚动页面触发
一次事件。
如果页面有滚动，时长清零。
$url 页面 字符
地址 串
$title 页面 字符
标题 串
$url_p 页面 字符
ath 路径 串
所有事件都有的预置属性
属性名 属性 默认显示名 说明 备注
类型
$lib 字符串 SDK 类型 SDK 类型
$lib_version 字符串 SDK 版本 SDK 版本
$lib_method 字符串 埋点方式 埋点方式，目前值统一为 code
$manufacturer 字符串 设备制造商 设备制造商，从浏览器的 UserAgent 中进行解析 JS SDK 1.6 版 本
支持
$model 字符串 设备型号 设备型号，从浏览器的 UserAgent 中进行解析
$os 字符串 操作系统 操作系统，从浏览器的 UserAgent 中进行解析
$os_version 字符串 操作系统版本 操作系统版本，从浏览器的 UserAgent 中进行解析
$browser 字符串 浏览器名 浏览器名，从浏览器的 UserAgent 中进行解析
$browser_version 字符串 浏览器版本 浏览器版本，从浏览器的 UserAgent 中进行解析
$bot_name 字符串 爬虫名称 如果是爬虫，则会尝试解析爬虫名称
$screen_height 数值 屏幕高度 屏幕高度
$screen_width 数值 屏幕宽度 屏幕宽度
$url 字符串 页面地址 默认不采集，需要手动设置 preset_properties 详细配置参考 JS SDK 1.14.10
版本支持
$is_first_day 逻辑 是否首日访问 表示是否是首日触发事件，可参考文档 新增用户及首日首次标记 JS SDK 1.5 版 本
支持
$latest_referrer 字符串 最近一次站外地 只要前向域名不是当前页面的域名，就会重置 JS SDK 1.6 版 本
址 支持
$latest_referrer_h 字符串 最近一次站外域 1.14.8 及以上版本，默认不采集，需要手动设置 preset_properties 详细配置参考 JS SDK 1.6 版 本
ost 名 支持
$latest_utm_sour 字符串 最近一次广告系
ce 列来源
$latest_utm_term 字符串 最近一次广告系
列字词 使用 Web 渠道追踪 后，只要 URL 中包含 对应渠道信息（ utm_ 参数）就会重置 JS SDK 1.6 版 本
支持
$latest_utm_cont 字符串 最近一次广告系
ent 列内容
$latest_utm_cam 字符串 最近一次广告系
paign 列名称$latest_utm_medi 字符串 最近一次广告系
um 列媒介
$latest_search_k 字符串 最近一次搜索引 由于各搜索引擎策略不同，可能有获取不到的情况 JS SDK 1.8 版 本
eyword 擎关键词 支持
$latest_traffic_so 字符串 最近一次流量来 取值规则可参考文档 流量来源类型说明 JS SDK 1.8 版 本
urce_type 源类型 支持
$device_id 字符串 设备 ID 默认取 cookie_id，具体取值逻辑可参考文档 如何准确的标识用户，默认不采集该属性，需要在初始化
SDK 中手动设置 is_track_device_id 参数说明
预置用户属性
属性 属 默 说明 备注
名 性 认
类 显
型 示
名
$first_v 时间 首次 新用户首次访问网页时， 会给此属性赋值 因为这些属性的设置时机是新用户首次访问网页时，才会设置
isit_time 访问 这些属性，新用户一般时以匿名 ID 标记用户行为，如果登录
时间 ID 和匿名 ID 关联失败，则登录 ID 不会由这些属性值。
$utm_s 字符 首次
ource 串 广告
系列
来源
使用Web渠道追踪，且新用户首次访问时，通过带有 utm 参数的渠道访问时， 才
$utm_ 字符 首次 会采集这些用户属性。如果时老用户，即使通过渠道访问网页，也不会设置这 些
medium 串 广告 用户属性。新老用户的标记可以参考此文档：新增用户及首日首次标记
系列
媒介
$utm_t 字符 首次
erm 串 广告
系列
字词
$utm_c 字符 首次
ontent 串 广告
系列
内容
$utm_c 字符 首次
ampaign 串 广告
系列
名称
$first_r 字符 首次 新用户第一次来到有神策 SDK 页面时的前向页面地址
eferrer 串 前向
地址
$first_r 字符 首次 新用户第一次来到有神策 SDK 页面时的前向页面域名
eferrer 串 前向
_host 域名
$first_b 字符 首次 新用户第一次来到有神策 SDK 页面时的浏览器语言
rowser 串 使用
_langua 的浏
ge 览器
语言
$first_b 字符 首次 SDK 1.8 版本支持，新用户第一次来到有神策 SDK 页面时的浏览器符类型
rowser 串 浏览
_charset 器字
符类
型
$first_s 字符 首次 SDK 1.8 版本支持
earch_k 串 搜索
eyword 引擎
关键
词
$first_t 字符 首次 SDK 1.8 版本支持，这个的属性值包括：付费广告流量、自然搜索流量、社交网
raffic_s 串 流量 站流量、引荐流量、直接流量。
ource_t 来源
ype 类型.3. Web JS SDK 预置事件和预置属性 v1.13
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 备注
件 件 性 件 性
英 显 英 属 值
文 示 文 性 类
变 名 变 显 型
量 量 示
名 名 名
$pag Web $预置 打开一个页面时自动采集，根据 autoTrack 的触 JS SDK通用性采集，打开autoTrack接口后会自动采
eview 浏览 属性 发进行上报记录，触发时机可以自定义配置，一 集，参考文档：JS SDK
页面 般建议放在初始化神策 SDK 后立刻执行。
$is_fir 是否 布尔 新用户首次访问页面时，触发的第一 https://www.sensorsdata.cn/manual/js_sdk.html
st_time 首次 值 个 $pageview ，该属性值为 true，后续再
触发 $pageview 事件时，该属性都为
false。
UTM广告系列参数，可用来进行渠道追踪，参考文
$title 页面 字符 页面<title>标签对的内容 档：
标题 串
$url 页面 字符 JS SDK默认采集的预置属性 https://www.sensorsdata.cn/manual
地址 串 /app_channel_tracking.html
$url_p 页面 字符
ath 路径 串
$refer 前向 字符 如果直接打开页面，值为空字符串
rer_ho 域名 串
st
$refer 前向 字符 如果直接打开页面，值为空字符串
rer 地址 串
$utm_ 广告 字符 打开页面的 url 有该参数就采集
campa 系列 串
ign 名称
$utm_ 广告 字符 打开页面的 url 有该参数就采集
source 系列 串
来源
$utm_ 广告 字符 打开页面的 url 有该参数就采集
medium 系列 串
媒介
$utm_ 广告 字符 打开页面的 url 有该参数就采集
term 系列 串
字词
$utm_ 广告 字符 打开页面的 url 有该参数就采集
conte 系列 串
nt 内容
$Web Web $预置 点击一个元素/控件/按钮（可扩展） 时自动采集 JS SDK通用性采集，打开autoTrack接口后会自动采
Click 元素 属性 集，参考文档：
点击
$elem 元素 字符 元素有 id 属性才采集 https://www.sensorsdata.cn/manual/js_sdk.html
ent_id ID 串
$elem 元素 字符 元素标签对直接的文本，例如：<a><span>
ent_co 内容 串 提交</span></a>，采集的是 “提交”
ntent
$elem 元素 字符 元素有 name 属性的时候才采集
ent_na 名字 串
me
$elem 元素 字符 元素有 class name 属性的时候才采集
ent_cl 样式 串
ass_n 名
ame
$elem 元素 字符 默认采集
ent_ty 类型 串
pe
$elem 元素 字符 默认采集
ent_se 选择 串
lector 器
$elem 元素 字符 a 标签默认采集
ent_ta 链接 串
rget_u 地址
rl
$url 页面 字符
地址 串
$title 页面 字符
标题 串
$url_p 页面 字符
ath 路径 串$view 视区 数值
port_ 宽度
width
$Web Web $预置 有效停留：关注网页区域不滚动，期间鼠标可以 若要使用神策分析中热力图-触达率图的功能，则需采
Stay 视区 属性 移动、点击等操作。 集此事件。事件触发条件：在一个页面停留4秒以上并
停留 进行有效滑动则触发。不支持增加自定义属性
$view 视区 数值 视区宽度（当前浏览器的可视区域的宽度， 有效停留时间：停留时间超过规定的时间，
port_ 宽度 单位是 px。） javascript sdk 中默认为 4 秒(参数可设置)。
width
如果发生页面滚动时候，之前的页面停留是有效
$view 视区 数值 视区距顶部的位置（当前滚动条所在位置， 停留，也就是超过默认的4秒或者自定义的时间，
port_p 距顶 距离页面顶部的高度，单位是 px。） javascript sdk就会发送一次页面停留事件。
osition 部的
位置
$view 视区 数值 视区高度（当前浏览器的可视区域的高度，
port_h 高度 单位是 px。）
eight
$event 停留 数值 距上次触发该事件的时间差。
_durat 时长
ion 页面没有操作，超过 4 秒后滚动页面触发
一次事件。
如果页面有滚动，时长清零。
$url 页面 字符
地址 串
$title 页面 字符
标题 串
$url_p 页面 字符
ath 路径 串
所有事件都有的预置属性
属性名 属性类型 默认显示名 说明 备注
$lib 字符串 SDK 类型 SDK 类型
$lib_version 字符串 SDK 版本 SDK 版本
$lib_method 字符串 埋点方式 埋点方式，目前值统一为 code
$screen_height 数值 屏幕高度 屏幕高度，采集的是像素
$screen_width 数值 屏幕宽度 屏幕宽度，采集的是像素
$url 字符串 页面地址 默认不采集，需要手动设置 preset_properties 详细配置参考 JS SDK 1.14.10 版本支持
$is_first_day 布尔值 是否首日访问 表示是否是首日触发事件，可参考文档 新增用户及首日首次标 JS SDK 1.5 版本支持
记
$ip 字符串 IP 后端通过解析 HTTP 请求而得到
$country 字符串 国家 由 IP 解析得到
$province 字符串 省份
$city 字符串 城市
$latest_referrer 字符串 最近一次站外地址 只要前向域名不是当前页面的域名，就会重置 JS SDK 1.6 版本支持
$latest_referrer_host 字符串 最近一次站外域名 1.14.8 及以上版本，默认不采集，需要手动设置 JS SDK 1.6 版本支持
preset_properties 详细配置参考
$latest_utm_source 字符串 最近一次广告系列来源
$latest_utm_term 字符串 最近一次广告系列字词
$latest_utm_content 字符串 最近一次广告系列内容 使用 Web 渠道追踪 后，只要 URL 中包含 对应渠道信息 JS SDK 1.6 版本支持
（ utm_ 参数）就会重置
$latest_utm_campaign 字符串 最近一次广告系列名称
$latest_utm_medium 字符串 最近一次广告系列媒介
$latest_search_keywo 字符串 最近一次搜索引擎关键词 由于各搜索引擎策略不同，可能有获取不到的情况 JS SDK 1.8 版本支持
rd
$latest_traffic_source 字符串 最近一次流量来源类型 取值规则可参考文档 流量来源类型说明 JS SDK 1.8 版本支持
_type
注意：
（1） 其中 $latest_search_keyword 最近一次搜索引擎关键词由于各搜索引擎策略不同，可能有获取不到的情况。
（2） 其中 $latest_traffic_source_type 这个的属性值包括：付费广告流量、自然搜索流量、社交网站流量、引荐流量、直接流量。
（3） 最近一次付费广告相关参数是一个事件属性，且不需要做任何配置，会在所有事件中都存在。这个属性会保存最近一次有效的 utm_source 。UserAgent 相关的预置属性
这一系列的属性从浏览器的 UserAgent 中进行解析。
字段名称 类型 说明 SDK 版本
$manufacturer 字符串 设备制造商 1.6 新解析方式支持
$model 字符串 设备型号
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$browser 字符串 浏览器名
$browser_version 字符串 浏览器版本
$bot_name 字符串 爬虫名称
目前是通过 UA 判断并有一个默认的属性 $bot_name （爬虫名称），但是有两种情况无法判断：
第一种：如果 UA 里没有标明、且会触发 JS 脚本的非法爬虫。
第二种：如果爬虫没有触发 JS 脚本，那么也不会触发我们的 SDK ，所以本身就不会被统计到。
对于爬虫种类，目前已经支持了主流爬虫名称的解析，对于新增或其他小众类型的爬虫，会出现无法解析的情况。
预置用户属性
属性 属 默 说明 备注
名 性 认
类 显
型 示
名
$first_v 时间 首次 新用户首次访问网页时， 会给此属性赋值 因为这些属性的设置时机是新用户首次访问网页时，才会设置
isit_time 访问 这些属性，新用户一般时以匿名 ID 标记用户行为，如果登录
时间 ID 和匿名 ID 关联失败，则登录 ID 不会由这些属性值。
$utm_s 字符 首次
ource 串 广告
系列
来源
使用Web渠道追踪，且新用户首次访问时，通过带有 utm 参数的渠道访问时， 才
$utm_ 字符 首次 会采集这些用户属性。如果是老用户，即使通过渠道访问网页，也不会设置这 些
medium 串 广告 用户属性。新老用户的标记可以参考此文档：新增用户及首日首次标记
系列
媒介
$utm_t 字符 首次
erm 串 广告
系列
字词
$utm_c 字符 首次
ontent 串 广告
系列
内容
$utm_c 字符 首次
ampaign 串 广告
系列
名称
$first_r 字符 首次 新用户第一次来到有神策 SDK 页面时的前向页面地址
eferrer 串 前向
地址
$first_r 字符 首次 新用户第一次来到有神策 SDK 页面时的前向页面域名
eferrer 串 前向
_host 域名
$first_b 字符 首次 新用户第一次来到有神策 SDK 页面时的浏览器语言
rowser 串 使用
_langua 的浏
ge 览器
语言
$first_b 字符 首次 SDK 1.8 版本支持，新用户第一次来到有神策 SDK 页面时的浏览器字符类型
rowser 串 浏览
_charset 器字符类
型
$first_s 字符 首次 SDK 1.8 版本支持
earch_k 串 搜索
eyword 引擎
关键
词
$first_t 字符 首次 SDK 1.8 版本支持，这个的属性值包括：付费广告流量、自然搜索流量、社交网
raffic_s 串 流量 站流量、引荐流量、直接流量。
ource_t 来源
ype 类型4. 微信小程序 SDK 预置事件和预置属性
预置事件
事件 事 属性 事件 属 属性值示例或说明 触发时机 备注
英文 件 英文 属性 性
变量 显 变量 显示 值
名 示 名 名 类
名 型
$MPLau 小程序 $预置属 小程序初始化完成时触发或者小程序进入后台一 小程序 SDK 通用性采集，打
nch 启动 性 定时间后被微信杀死进程后再次启动小程序时触 开 autoTrack 接口后自动采集
发
$scene 启动场景 字符 1.0 以上版本支持 参考小程序SDK：https://www.
串 sensorsdata.cn/manual/mp_sdk.
html
$url_qu 页面参数 字符
ery 串
$url_path 页面路径 字符
串
$utm_c 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集 UTM广告系列参数，用来渠道追
ampaign 名称 串 踪 ， 参 考 文 档 ：
https://sensorsdata.cn/manual
$utm_s 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集 /mp_channel_tracking.html
ource 来源 串
$utm_m 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集
edium 媒介 串
$utm_te 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集
rm 字词 串
$utm_c 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集
ontent 内容 串
$is_first 是否首次 逻辑 1.8 版本以上
_time
$share_ 分享时的 数值 1.9 版本以上
depth 层级
$share_ 分享时 字符 1.9 版本以上
distinct 的 distin 串
_id ct_id
$share_ 分享时的 字符 1.9 版本以上
url_path 页面路径 串
$MPSh 小程序 $预置属 小程序启动时触发或者从后台切换到前台时触
ow 显示 性 发，包括首次启动
$scene 启动场景 字符 1.0 以上
串
$url_qu 页面参数 字符
ery 串
$url_path 页面路径 字符
串
$utm_c 广告系列 字符 0.9 版本以上
ampaign 名称 串
$utm_s 广告系列 字符 0.9 版本以上
ource 来源 串
$utm_m 广告系列 字符 0.9 版本以上
edium 媒介 串
$utm_te 广告系列 字符 0.9 版本以上
rm 字词 串
$utm_c 广告系列 字符 0.9 版本以上
ontent 内容 串
$share_ 分享时的 数值 1.9 版本以上
depth 层级
$share_ 分享时 字符 1.9 版本以上
distinct 的 distin 串
_id ct_id
$share_ 分享时的 字符 1.9 版本以上
url_path 页面路径 串
$MPHide 小程序 $预置属 小程序从前台进入后台
进入后 性
台
$event_ 停留时长 数值 从本次小程序显示( $MPShow) 到进入后台或者关闭
duration ( $MPHide) 的时间
$url_path 页面路径 字符 1.5 版本及以上
串
$MPVie 小程序 $预置属 打开一个小程序页面时触发wScreen 页面浏 性
览
$url_qu 页面参数 字符
ery 串
$url_path 页面路径 字符
串
$utm_c 广告系列 字符 0.9 版本以上
ampaign 名称 串
$utm_s 广告系列 字符 0.9 版本以上
ource 来源 串
$utm_m 广告系列 字符 0.9 版本以上
edium 媒介 串
$utm_te 广告系列 字符 0.9 版本以上
rm 字词 串
$utm_c 广告系列 字符 0.9 版本以上
ontent 内容 串
$referrer 前向地址 字符 需要代码手动开启
串
$MPSha 小程序 $预置属 设置这个函数后，点击小程序右上角的转发(分 暂时只能获取到用户触发分享，无
re 分享 性 享)按钮触发上报 法监听是否分享成功的反馈
$share_ 分享时的 数值 1.9 以上
depth 层级
$url_path 页面路径 字符 1.9 以上
串
$MPCli 小程序 $eleme 元素内容 字符 1.13.18 及以上版本，需要在组件上设置 data-
ck 元素点 nt_cont 串 content 属性才可以采集到，未设置采集不到该属性
击 ent
$eleme 元素 ID 字符 1.13.18 及以上版本，用来区分组件，需要在组件上设
nt_id 串 置 id 属性才可以采集到，未设置采集不到该属性
$eleme 元素名称 字符 1.13.18 及以上版本，用来区分组件，需要在组件上设
nt_name 串 置 data-name 属性才可以采集到，未设置采集不到该
属性
$eleme 元素类型 字符 1.13.18 及以上版本，需要在组件上设置 data-type 属
nt_type 串 性才可以采集到，未设置采集不到该属性
$url_path 字符串 页面 1.13.18 及以上版本
路径
所有事件都有的预置属性
属性名 属 默认显 说明 注意
性 示名
类
型
$lib 字符 SDK 类型 SDK 类型
串
$lib_version 字符 SDK 版本 SDK 版本
串
$screen_he 数值 小程序屏幕 小程序屏幕高度 小程序 SDK 1.11.1 版本之前，此字段名称为”小程序
ight 高度 窗口高度”，取的值是小程序可使用窗口高度
$screen_wi 数值 小程序屏幕 小程序屏幕宽度 小程序 SDK 1.11.1 版本之前，字段名称为‘小程序窗
dth 宽度 口宽度’,取的值是小程序可使用窗口宽度
$model 字符 设备型号
串
$manufact 字符 设备制造商 小程序 SDK 1.11.1 版本支持
urer 串 不从 UA 解析，直接获取对应设备的值
$os 字符 操作系统
串
$os_version 字符 操作系统版
串 本
$is_first_day 逻辑 是否首日访 从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后都为假，标
问 识存在 storage 缓存中，可参考文档 新增用户及首日首次标记
$ip 字符 IP SDK 发送数据请求携带的属性
串
$country 字符 国家 由 IP 解析得到
串$province 字符 省份
串
$city 字符 城市
串
$network_t 字符 网络类型
ype 串
$browser 字符 浏览器名称
串
$browser_v 字符 浏览器版本
ersion 串
$latest_utm 字符 最近一次广 使用 小程序渠道追踪 后会采集对应渠道信息（ utm_ 参数），取值逻辑可参
_source 串 告系列来源 考文档 $latest_utm 相关属性
$latest_utm 字符 最近一次广
_medium 串 告系列媒介 小程序 SDK 1.3 版本支持
$latest_utm 字符 最近一次广
_term 串 告系列字词
$latest_utm 字符 最近一次广
_content 串 告系列内容
$latest_utm 字符 最近一次广
_campaign 串 告系列名称
$latest_sce 字符 最近一次启 描述最近一次小程序启动的场景，场景值说明可参考 微信小程序官方介绍 小程序 SDK 1.9 版本支持
ne 串 动场景
预置用户属性
属 属 默 说明 备注
性 性 认
名 类 显
型 示
名
$firs 时间 首次 新用户首次访问小程序时， 会给此属性赋值 因为这些属性的设置时机是新用户首次访问小程序时，才会设
t_vis 访问 置这些属性，新用户一般时以匿名 ID 标记用户行为，如果登
it_ti 时间 录 ID 和匿名 ID 关联失败，则登录 ID 不会由这些属性值。
me
$ut 字符 首次 使用小程序渠道追踪，且新用户首次访问时，通过带有 utm 参数的渠道访问时，才会
m_s 串 广告 采集这些用户属性。如果时老用户，即使通过渠道访问小程序，也不会给这些设 置
ource 系列 utm 用户属性。新老用户的标记可以参考此文档：新增用户及首日首次标记
来源
$ut 字符 首次
m_m 串 广告
edium 系列
媒介
$ut 字符 首次
m_te 串 广告
rm 系列
字词
$ut 字符 首次
m_c 串 广告
onte 系列
nt 内容
$ut 字符 首次
m_c 串 广告
amp 系列
aign 名称.4. 微信小程序 SDK 预置事件和预置属性 v1.13
预置事件
事件 事 属性 事件 属 属性值示例或说明 触发时机 备注
英文 件 英文 属性 性
变量 显 变量 显示 值
名 示 名 名 类
名 型
$MPLau 小程序 $预置属 小程序初始化完成时触发或者小程序进入后台一 小程序 SDK 通用性采集，打
nch 启动 性 定时间后被微信杀死进程后再次启动小程序时触 开 autoTrack 接口后自动采集
发
$scene 启动场景 字符 1.0 以上版本支持 参考小程序SDK：https://www.
串 sensorsdata.cn/manual/mp_sdk.
html
$url_qu 页面参数 字符
ery 串
$url_path 页面路径 字符
串
UTM广告系列参数，用来渠道追
$utm_c 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集 踪 ， 参 考 文 档 ：
ampaign 名称 串 https://sensorsdata.cn/manual
$utm_s 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集 /mp_channel_tracking.html
ource 来源 串
$utm_m 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集
edium 媒介 串
$utm_te 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集
rm 字词 串
$utm_c 广告系列 字符 0.9 版本以上。打开小程序的地址有就采集
ontent 内容 串
$is_first 是否首次 布尔 1.8 版本以上
_time 值
$share_ 分享时的 数值 1.9 版本以上
depth 层级
$share_ 分享时 字符 1.9 版本以上
distinct 的 distin 串
_id ct_id
$share_ 分享时的 字符 1.9 版本以上
url_path 页面路径 串
$MPSh 小程序 $预置属 小程序启动时触发或者从后台切换到前台时触
ow 显示 性 发，包括首次启动
$scene 启动场景 字符 1.0 以上
串
$url_qu 页面参数 字符
ery 串
$url_path 页面路径 字符
串
$utm_c 广告系列 字符 0.9 版本以上
ampaign 名称 串
$utm_s 广告系列 字符 0.9 版本以上
ource 来源 串
$utm_m 广告系列 字符 0.9 版本以上
edium 媒介 串
$utm_te 广告系列 字符 0.9 版本以上
rm 字词 串
$utm_c 广告系列 字符 0.9 版本以上
ontent 内容 串
$share_ 分享时的 数值 1.9 版本以上
depth 层级
$share_ 分享时 字符 1.9 版本以上
distinct 的 distin 串
_id ct_id
$share_ 分享时的 字符 1.9 版本以上
url_path 页面路径 串
$MPHide 小程序 $预置属 小程序从前台进入后台
进入后 性
台
$event_ 停留时长 数值 从本次小程序显示( $MPShow) 到进入后台或者关闭
duration ( $MPHide) 的时间
$url_path 页面路径 字符 1.5 版本及以上
串
$MPVie 小程序 $预置属 打开一个小程序页面时触发wScreen 页面浏 性
览
$url_qu 页面参数 字符
ery 串
$url_path 页面路径 字符
串
$utm_c 广告系列 字符 0.9 版本以上
ampaign 名称 串
$utm_s 广告系列 字符 0.9 版本以上
ource 来源 串
$utm_m 广告系列 字符 0.9 版本以上
edium 媒介 串
$utm_te 广告系列 字符 0.9 版本以上
rm 字词 串
$utm_c 广告系列 字符 0.9 版本以上
ontent 内容 串
$referrer 前向地址 字符 需要代码手动开启
串
$MPSha 小程序 $预置属 设置这个函数后，点击小程序右上角的转发(分 暂时只能获取到用户触发分享，无
re 分享 性 享)按钮触发上报 法监听是否分享成功的反馈
$share_ 分享时的 数值 1.9 以上
depth 层级
$url_path 页面路径 字符 1.9 以上
串
$MPCli 小程序 $eleme 元素内容 字符 1.13.18 及以上版本，需要在组件上设置 data-
ck 元素点 nt_cont 串 content 属性才可以采集到，未设置采集不到该属性
击 ent
$eleme 元素 ID 字符 1.13.18 及以上版本，用来区分组件，需要在组件上设
nt_id 串 置 id 属性才可以采集到，未设置采集不到该属性
$eleme 元素名称 字符 1.13.18 及以上版本，用来区分组件，需要在组件上设
nt_name 串 置 data-name 属性才可以采集到，未设置采集不到该
属性
$eleme 元素类型 字符 1.13.18 及以上版本，需要在组件上设置 data-type 属
nt_type 串 性才可以采集到，未设置采集不到该属性
$url_path 字符串 页面 1.13.18 及以上版本
路径
所有事件都有的预置属性
属性名 属 默认显 说明 注意
性 示名
类
型
$lib 字符 SDK 类型 SDK 类型
串
$lib_version 字符 SDK 版本 SDK 版本
串
$screen_hei 数值 小程序屏幕 小程序屏幕高度 小程序 SDK 1.11.1 版本之前，此字段名称为”小程序
ght 高度 窗口高度”，取的值是小程序可使用窗口高度
$screen_wid 数值 小程序屏幕 小程序屏幕宽度 小程序 SDK 1.11.1 版本之前，字段名称为‘小程序窗
th 宽度 口宽度’,取的值是小程序可使用窗口宽度
$model 字符 设备型号
串
$manufactur 字符 设备制造商 小程序 SDK 1.11.1 版本支持
er 串 不从 UA 解析，直接获取对应设备的值
$os 字符 操作系统
串
$os_version 字符 操作系统版
串 本
$is_first_day 布尔 是否首日访 从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后都为假，标
值 问 识存在 storage 缓存中，可参考文档 新增用户及首日首次标记
$ip 字符 IP 后端通过解析 HTTP 请求而得到
串
$country 字符 国家 由 IP 解析得到
串$province 字符 省份
串
$city 字符 城市
串
$network_ty 字符 网络类型
pe 串
$browser 字符 浏览器名称
串
$browser_ve 字符 浏览器版本
rsion 串
$latest_utm_ 字符 最近一次广 使用 小程序渠道追踪 后会采集对应渠道信息（ utm_ 参数），取值逻辑可参
source 串 告系列来源 考文档 $latest_utm 相关属性
$latest_utm_ 字符 最近一次广
medium 串 告系列媒介 小程序 SDK 1.3 版本支持
$latest_utm_ 字符 最近一次广
term 串 告系列字词
$latest_utm_ 字符 最近一次广
content 串 告系列内容
$latest_utm_ 字符 最近一次广
campaign 串 告系列名称
$latest_scene 字符 最近一次启 描述最近一次小程序启动的场景，场景值说明可参考 微信小程序官方介绍 小程序 SDK 1.9 版本支持
串 动场景
$latest_shar 字符 最近一次分 小程序 SDK 1.13.21 版本支持
e_distinct_id 串 享者
$latest_shar 字符 最近一次分 小程序 SDK 1.13.21 版本支持
e_depth 串 享层次
$latest_shar 字符 最近一次分 小程序 SDK 1.13.21 版本支持
e_url_path 串 享路径
预置用户属性
属 属 默 说明 备注
性 性 认
名 类 显
型 示
名
$firs 时间 首次 新用户首次访问小程序时， 会给此属性赋值 因为这些属性的设置时机是新用户首次访问小程序时，才会设
t_vis 访问 置这些属性，新用户一般时以匿名 ID 标记用户行为，如果登
it_ti 时间 录 ID 和匿名 ID 关联失败，则登录 ID 不会由这些属性值。
me
$ut 字符 首次 使用小程序渠道追踪，且新用户首次访问时，通过带有 utm 参数的渠道访问时，才会
m_s 串 广告 采集这些用户属性。如果时老用户，即使通过渠道访问小程序，也不会给这些设 置
ource 系列 utm 用户属性。新老用户的标记可以参考此文档：新增用户及首日首次标记
来源
$ut 字符 首次
m_m 串 广告
edium 系列
媒介
$ut 字符 首次
m_te 串 广告
rm 系列
字词
$ut 字符 首次
m_c 串 广告
onte 系列
nt 内容
$ut 字符 首次
m_c 串 广告
amp 系列
aign 名称5. 支付宝小程序 SDK 预置事件和预置属性
预置事件
事件英 事件 属性英 事件属 属性 属性值示例或说 触发时机 备注
文变量 显示 文变量 性显示 值类 明
名 名 名 名 型
$MPLaunch 小程序启 $预置属性 小程序进程被杀死，重新打开时会触发，小程序初始化完成 小程序SDK通用性采集，打开 autoTrack 接
动 时，全局只触发一次 口后自动采集
$scene 启动场景 字符串
参 考 小 程 序 SDK：https://www.
$url_path 页面路径 字符串 sensorsdata.cn/manual/mp_sdk.html
$is_first_ti 是否首次 逻辑
me
$utm_sour 字符串 广告系
ce 列来源 UTM广告系列参数，用来渠道追踪，参考文
档：
$utm_medi 字符串 广告系
um 列媒介 https://sensorsdata.cn/manual
/mp_channel_tracking.html
$utm_term 字符串 广告系
列字词
$utm_cont 字符串 广告系
ent 列内容
$utm_cam 字符串 广告系
paign 列名称
$MPShow 小程序显 $预置属性 小程序启动时，或从后台进入前台显示
示
$scene 启动场景 字符串
$url_path 页面路径 字符串
$utm_sour 字符串 广告系
ce 列来源
$utm_medi 字符串 广告系
um 列媒介
$utm_term 字符串 广告系
列字词
$utm_cont 字符串 广告系
ent 列内容
$utm_cam 字符串 广告系
paign 列名称
$MPHide 小程序进 $预置属性 小程序从前台进入后台
入后台
$event_dur 停留时长 数值
ation
$url_path 页面路径 字符串
$MPClick 小程序元 $预置属性 小程序页面元素被点击时触发，被点击元素使用 onTap 或 1.0.6 及以上版本
素点击 者 onLongTap 添加监听时才会采集
$element_id 元素 ID 字符串 元素需要设置 id 属
性
$element_ 元素名字 字符串 元素需要设置 data-
name name 属性
$element_ 元素内容 字符串 元素需要设置 data-
content content 属性
$element_t 元素类型 字符串
ype
$url_path 页面路径 字符串
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 逻辑 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存
在 storage 中）
$is_login_id 逻辑 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
$latest_utm_source 字符串 最近一次付费广告系列来源
$latest_utm_medium 字符串 最近一次付费广告系列媒介
$latest_utm_term 字符串 最近一次付费广告系列字词
$latest_utm_content 字符串 最近一次付费广告系列内容
$latest_utm_campaign 字符串 最近一次付费广告系列名称.5. 支付宝小程序 SDK 预置事件和预置属性 v1.13
预置事件
事件英 事件 属性英 事件属 属性 属性值示例或说 触发时机 备注
文变量 显示 文变量 性显示 值类 明
名 名 名 名 型
$MPLaunch 小程序启 $预置属性 小程序进程被杀死，重新打开时会触发，小程序初始化完成 小程序SDK通用性采集，打开 autoTrack 接
动 时，全局只触发一次 口后自动采集
$scene 启动场景 字符串
参 考 小 程 序 SDK：https://www.
$url_path 页面路径 字符串 sensorsdata.cn/manual/mp_sdk.html
$is_first_ti 是否首次 布尔值
me
$utm_sour 字符串 广告系
ce 列来源 UTM广告系列参数，用来渠道追踪，参考文
档：
$utm_medi 字符串 广告系
um 列媒介 https://sensorsdata.cn/manual
/mp_channel_tracking.html
$utm_term 字符串 广告系
列字词
$utm_cont 字符串 广告系
ent 列内容
$utm_cam 字符串 广告系
paign 列名称
$MPShow 小程序显 $预置属性 小程序启动时，或从后台进入前台显示
示
$scene 启动场景 字符串
$url_path 页面路径 字符串
$utm_sour 字符串 广告系
ce 列来源
$utm_medi 字符串 广告系
um 列媒介
$utm_term 字符串 广告系
列字词
$utm_cont 字符串 广告系
ent 列内容
$utm_cam 字符串 广告系
paign 列名称
$MPHide 小程序进 $预置属性 小程序从前台进入后台
入后台
$event_dur 停留时长 数值
ation
$url_path 页面路径 字符串
$MPClick 小程序元 $预置属性 小程序页面元素被点击时触发，被点击元素使用 onTap 或 1.0.6 及以上版本
素点击 者 onLongTap 添加监听时才会采集
$element_id 元素 ID 字符串 元素需要设置 id 属
性
$element_ 元素名字 字符串 元素需要设置 data-
name name 属性
$element_ 元素内容 字符串 元素需要设置 data-
content content 属性
$element_t 元素类型 字符串
ype
$url_path 页面路径 字符串
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔值 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在
storage 中）
$is_login_id 布尔值 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
$latest_utm_source 字符串 最近一次付费广告系列来源
$latest_utm_medium 字符串 最近一次付费广告系列媒介
$latest_utm_term 字符串 最近一次付费广告系列字词
$latest_utm_content 字符串 最近一次付费广告系列内容
$latest_utm_campaign 字符串 最近一次付费广告系列名称6. QQ 小程序 SDK 预置事件和预置属性
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 备注
件 件 性 件 性
英 显 英 属 值
文 示 文 性 类
变 名 变 显 型
量 量 示
名 名 名
$MPL 小程 $预置 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用 小程序 SDK 通用性采集，打开 autoTrack 接
aunch 序启 属性 了 sa.quick( ''appLaunch'', options ) 时会触发 口后自动采集
动
$scene 启动场 字符 参考小程序 SDK：https://www.sensorsdata.
景 串 cn/manual/mp_sdk.html
$url_p 页面路 字符
ath 径 串
$is_fir 是否首 BOOL
st_time 次
UTM 广告系列参数，用来渠道追踪，需要使
$utm_ 字符串 广告 用神策的小程序渠道追踪方式，才会采集这些
source 系列 属 性 值 ， 具 体 参 考 文 档 ：
来源 https://sensorsdata.cn/manual
/mp_channel_tracking.html
$utm_ 字符串 广告
medium 系列
媒介
$utm_ 字符串 广告
term 系列
字词
$utm_ 字符串 广告
conte 系列
nt 内容
$utm_ 字符串 广告
camp 系列
aign 名称
$MPS 小程 $预置 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中
how 序显 属性 调用了 sa.quick( ''appShow'', options ) 时会触发
示
$scene 启动场 字符
景 串
$url_p 页面路 字符
ath 径 串
$utm_ 字符串 广告
source 系列
来源
$utm_ 字符串 广告
medium 系列
媒介
$utm_ 字符串 广告
term 系列
字词
$utm_ 字符串 广告
conte 系列
nt 内容
$utm_ 字符串 广告
camp 系列
aign 名称
$MPHi 小程 $预置 点击小程序右上角退出按钮、QQ 进入后台、进入小程序关于页面、
de 序进 属性 手机锁屏、小程序进程被杀死且在相应小程序生命周期函数中调用
入后 了 sa.quick( ''Hide'' ) 时会触发时
台 $url_p 页面路 字符
ath 径 串
$even 事件时 数值 从本次小程序显示
t_dura 长 $MPShow 到 $MPHide 小程
tion 序进入后台或者关闭的时间
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 逻辑 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识
存在 storage 中）
$is_login_id 逻辑 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称，由 UA 解析得到
$browser_version 字符串 浏览器版本，由 UA 解析得到
$latest_utm_source 字符串 最近一次付费广告系列来源，以最近一次有值的广告系列来源取值。
$latest_utm_medium 字符串 最近一次付费广告系列媒介，以最近一次有值的广告系列媒介取值。
$latest_utm_term 字符串 最近一次付费广告系列字词，以最近一次有值的广告系列字词取值。
$latest_utm_content 字符串 最近一次付费广告系列内容，以最近一次有值的广告系列内容取值。
$latest_utm_campaign 字符串 最近一次付费广告系列名称，以最近一次有值的广告系列名称取值
$latest_scene 字符串 最近一次启动场景值
预置用户属性
属 属 默 说明 备注
性 性 认
名 类 显
型 示
名
$firs 时间 首次 新用户首次访问小程序时， 会给此属性赋值 因为这些属性的设置时机是新用户首次访问小程序时，才会设
t_vis 访问 置这些属性，新用户一般时以匿名 ID 标记用户行为，如果登
it_ti 时间 录 ID 和匿名 ID 关联失败，则登录 ID 不会由这些属性值。
me
$ut 字符 首次 使用小程序渠道追踪，且新用户首次访问时，通过带有 utm 参数的渠道访问时，才会
m_s 串 广告 采集这些用户属性。如果时老用户，即使通过渠道访问小程序，也不会设置这些 用
ource 系列 户属性。新老用户的标记可以参考此文档：新增用户及首日首次标记
来源
$ut 字符 首次
m_m 串 广告
edium 系列
媒介
$ut 字符 首次
m_te 串 广告
rm 系列
字词
$ut 字符 首次
m_c 串 广告
onte 系列
nt 内容
$ut 字符 首次m_c 串 广告
amp 系列
aign 名称.6. QQ 小程序 SDK 预置事件和预置属性 v1.13
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 备注
件 件 性 件 性
英 显 英 属 值
文 示 文 性 类
变 名 变 显 型
量 量 示
名 名 名
$MPL 小程 $预置 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用 小程序 SDK 通用性采集，打开 autoTrack 接
aunch 序启 属性 了 sa.quick( ''appLaunch'', options ) 时会触发 口后自动采集
动
$scene 启动场 字符 参考小程序 SDK：https://www.sensorsdata.
景 串 cn/manual/mp_sdk.html
$url_p 页面路 字符
ath 径 串
$is_fir 是否首 BOOL
st_time 次
UTM 广告系列参数，用来渠道追踪，需要使
$utm_ 字符串 广告 用神策的小程序渠道追踪方式，才会采集这些
source 系列 属 性 值 ， 具 体 参 考 文 档 ：
来源 https://sensorsdata.cn/manual
/mp_channel_tracking.html
$utm_ 字符串 广告
medium 系列
媒介
$utm_ 字符串 广告
term 系列
字词
$utm_ 字符串 广告
conte 系列
nt 内容
$utm_ 字符串 广告
camp 系列
aign 名称
$MPS 小程 $预置 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中
how 序显 属性 调用了 sa.quick( ''appShow'', options ) 时会触发
示
$scene 启动场 字符
景 串
$url_p 页面路 字符
ath 径 串
$utm_ 字符串 广告
source 系列
来源
$utm_ 字符串 广告
medium 系列
媒介
$utm_ 字符串 广告
term 系列
字词
$utm_ 字符串 广告
conte 系列
nt 内容
$utm_ 字符串 广告
camp 系列
aign 名称
$MPHi 小程 $预置 点击小程序右上角退出按钮、QQ 进入后台、进入小程序关于页面、
de 序进 属性 手机锁屏、小程序进程被杀死且在相应小程序生命周期函数中调用
入后 了 sa.quick( ''Hide'' ) 时会触发时
台 $url_p 页面路 字符
ath 径 串
$even 事件时 数值 从本次小程序显示
t_dura 长 $MPShow 到 $MPHide 小程
tion 序进入后台或者关闭的时间
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔值 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识
存在 storage 中）
$is_login_id 布尔值 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称，由 UA 解析得到
$browser_version 字符串 浏览器版本，由 UA 解析得到
$latest_utm_source 字符串 最近一次付费广告系列来源，以最近一次有值的广告系列来源取值。
$latest_utm_medium 字符串 最近一次付费广告系列媒介，以最近一次有值的广告系列媒介取值。
$latest_utm_term 字符串 最近一次付费广告系列字词，以最近一次有值的广告系列字词取值。
$latest_utm_content 字符串 最近一次付费广告系列内容，以最近一次有值的广告系列内容取值。
$latest_utm_campaign 字符串 最近一次付费广告系列名称，以最近一次有值的广告系列名称取值
$latest_scene 字符串 最近一次启动场景值
预置用户属性
属 属 默 说明 备注
性 性 认
名 类 显
型 示
名
$firs 时间 首次 新用户首次访问小程序时， 会给此属性赋值 因为这些属性的设置时机是新用户首次访问小程序时，才会设
t_vis 访问 置这些属性，新用户一般时以匿名 ID 标记用户行为，如果登
it_ti 时间 录 ID 和匿名 ID 关联失败，则登录 ID 不会由这些属性值。
me
$ut 字符 首次 使用小程序渠道追踪，且新用户首次访问时，通过带有 utm 参数的渠道访问时，才会
m_s 串 广告 采集这些用户属性。如果时老用户，即使通过渠道访问小程序，也不会设置这些 用
ource 系列 户属性。新老用户的标记可以参考此文档：新增用户及首日首次标记
来源
$ut 字符 首次
m_m 串 广告
edium 系列
媒介
$ut 字符 首次
m_te 串 广告
rm 系列
字词
$ut 字符 首次
m_c 串 广告
onte 系列
nt 内容
$ut 字符 首次m_c 串 广告
amp 系列
aign 名称7. 百度小程序 SDK 预置事件和预置属性
预置事件
事件 事 属性 事件 属 触发时机 备注
英文 件 英文 属性 性
变量 显 变量 显示 值
名 示 名 名 类
名 型
$MPLa 小程 $预置属 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 小程序SDK通用性采集，打
unch 序启 性 sa.quick( ''appLaunch'', options ) 时会触发 开 autoTrack 接口后自动采集
动
$scene 启动场 字符 参考小程序SDK：https://www.
景 串 sensorsdata.cn/manual/mp_sdk.
html
$url_pa 页面路 字符
th 径 串
$is_firs 是否首 逻辑
t_time 次
$MPSh 小程 $预置属 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick
ow 序显 性 ( ''appShow'', options ) 时会触发
示
$scene 启动场 字符
景 串
$url_pa 页面路 字符
th 径 串
$MPHi 小程 $预置属 点击小程序右上角退出按钮、百度 App 进入后台、进入小程序关于页面、手机锁屏、小
de 序进 性 程序进程被杀死且在相应小程序生命周期函数中调用了 sa.quick( ''Hide'' ) 时会触发时
入后
台 $event_ 停留时 数值
duration 长
$url_pa 页面路 字符
th 径 串
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 逻辑 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在
storage 中）
$is_login_id 逻辑 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称$browser_version 字符串 浏览器版本.7. 百度小程序 SDK 预置事件和预置属性 v1.13
预置事件
事件 事 属性 事件 属 触发时机 备注
英文 件 英文 属性 性
变量 显 变量 显示 值
名 示 名 名 类
名 型
$MPLa 小程 $预置属 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 小程序SDK通用性采集，打
unch 序启 性 sa.quick( ''appLaunch'', options ) 时会触发 开 autoTrack 接口后自动采集
动
$scene 启动场 字符 参考小程序SDK：https://www.
景 串 sensorsdata.cn/manual/mp_sdk.
html
$url_pa 页面路 字符
th 径 串
$is_firs 是否首 布尔
t_time 次 值
$MPSh 小程 $预置属 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa.quick
ow 序显 性 ( ''appShow'', options ) 时会触发
示
$scene 启动场 字符
景 串
$url_pa 页面路 字符
th 径 串
$MPHi 小程 $预置属 点击小程序右上角退出按钮、百度 App 进入后台、进入小程序关于页面、手机锁屏、小
de 序进 性 程序进程被杀死且在相应小程序生命周期函数中调用了 sa.quick( ''Hide'' ) 时会触发时
入后
台 $event_ 停留时 数值
duration 长
$url_pa 页面路 字符
th 径 串
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔值 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在
storage 中）
$is_login_id 布尔值 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称$browser_version 字符串 浏览器版本8. 微信小游戏 SDK 预置事件和预置属性
预置事件
事件英文变量名 事件显示名 属性英文变量名 事件属性显示名 属性值类型 属性值示 触发时机 对应的生命周期
例或说明
$MPLaunch 小程序启动 $预置属性 小游戏冷启动时触发
$scene 启动场景 字符串
$url_query 页面参数 字符串
$utm_campaign 广告系列名称 字符串
$utm_source 广告系列来源 字符串
$utm_medium 广告系列媒介 字符串
$utm_term 广告系列字词 字符串
$utm_content 广告系列内容 字符串
$is_first_time 是否首次 逻辑
$share_depth 分享时的层级 数值
$share_distinct_id 分享者的 distinct_id 字符串
$MPShow 小程序显示 $预置属性 小游戏热启动或者从后台进 触发小游戏的 onShow 生
入前台时触发 命周期函数时触发
$scene 启动场景 字符串
$url_query 页面参数 字符串
$url_path 页面路径 字符串
$utm_campaign 广告系列名称 字符串
$utm_source 广告系列来源 字符串
$utm_medium 广告系列媒介 字符串
$utm_term 广告系列字词 字符串
$utm_content 广告系列内容 字符串
$share_depth 分享时的层级 数值
$share_distinct_id 分享时的 distinct_id 字符串
$MPHide 小程序进入后台 $预置属性 小游戏进入后台时触发 触发小游戏的 onHide 生命
周期函数时触发
$event_duration 停留时长 数值
$url_path 页面路径 字符串
$MPShare 小程序分享 $预置属性 需要调用神策定义的分享函
数 sensors.
$share_depth 分享时的层级 数值 onShareAppMessage()
$url_path 页面路径 字符串
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 逻辑 是否首日访问（从新用户第一次访问到当天的二十三点五十九分五十九秒之间的值都为真，之后
都为假，判断标识存在微信 storage 中）$is_login_id 逻辑 是否是登录 ID（数据入库后添加）
$ip 字符串 SDK 发送数据请求携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器类型
$browser_version 字符串 浏览器版本
$latest_utm_source 字符串 最近一次广告系列来源
$latest_utm_medium 字符串 最近一次广告系列媒介
$latest_utm_term 字符串 最近一次广告系列字词
$latest_utm_content 字符串 最近一次广告系列内容
$latest_utm_campaign 字符串 最近一次广告系列名称
$latest_scene 字符串 最近一次场景值
注意：如果自定义事件的触发时机早于小程序启动 $MPLaunch 和 小程序显示 $MPShow 这两个预置事件，那么首次发送自定义事件时将不会采集
$latest_utm_source、$latest_utm_medium、$latest_utm_term、$latest_utm_content、$latest_utm_campaign、$latest_scene 这些最近一次来源属性。.8. 微信小游戏 SDK 预置事件和预置属性 v1.13
预置事件
事件英文变量名 事件显示名 属性英文变量名 事件属性显示名 属性值类型 属性值示 触发时机 对应的生命周期
例或说明
$MPLaunch 小程序启动 $预置属性 小游戏冷启动时触发
$scene 启动场景 字符串
$url_query 页面参数 字符串
$utm_campaign 广告系列名称 字符串
$utm_source 广告系列来源 字符串
$utm_medium 广告系列媒介 字符串
$utm_term 广告系列字词 字符串
$utm_content 广告系列内容 字符串
$is_first_time 是否首次 布尔值
$share_depth 分享时的层级 数值
$share_distinct_id 分享者的 distinct_id 字符串
$MPShow 小程序显示 $预置属性 小游戏热启动或者从后台进 触发小游戏的 onShow 生
入前台时触发 命周期函数时触发
$scene 启动场景 字符串
$url_query 页面参数 字符串
$url_path 页面路径 字符串
$utm_campaign 广告系列名称 字符串
$utm_source 广告系列来源 字符串
$utm_medium 广告系列媒介 字符串
$utm_term 广告系列字词 字符串
$utm_content 广告系列内容 字符串
$share_depth 分享时的层级 数值
$share_distinct_id 分享时的 distinct_id 字符串
$MPHide 小程序进入后台 $预置属性 小游戏进入后台时触发 触发小游戏的 onHide 生命
周期函数时触发
$event_duration 停留时长 数值
$url_path 页面路径 字符串
$MPShare 小程序分享 $预置属性 需要调用神策定义的分享函
数 sensors.
$share_depth 分享时的层级 数值 onShareAppMessage()
$url_path 页面路径 字符串
所有事件都有的预置属性
字段名称 类 说明
型
$lib 字符 SDK 类型
串
$lib_version 字符 SDK 版本
串
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符 设备型号
串
$manufacturer 字符 设备制造商
串
$os 字符 操作系统
串$os_version 字符 操作系统版本
串
$is_first_day 布尔 是否首日访问（从新用户第一次访问到当天的二十三点五十九分五十九秒之间的值都为真，之后都为假，判断标识存在微
值 信 storage 中）
$is_login_id 布尔 是否是登录 ID（数据入库后添加）
值
$ip 字符 SDK 发送数据请求携带的属性
串
$country 字符 由 IP 解析得到
串
$province 字符 由 IP 解析得到
串
$city 字符 由 IP 解析得到
串
$network_type 字符 网络类型
串
$browser 字符 浏览器类型
串
$browser_version 字符 浏览器版本
串
$latest_utm_source 字符 最近一次广告系列来源
串
$latest_utm_medium 字符 最近一次广告系列媒介
串
$latest_utm_term 字符 最近一次广告系列字词
串
$latest_utm_content 字符 最近一次广告系列内容
串
$latest_utm_campa 字符 最近一次广告系列名称
ign 串
$latest_scene 字符 最近一次场景值
串
注意：如果自定义事件的触发时机早于小程序启动 $MPLaunch 和 小程序显示 $MPShow 这两个预置事件，那么首次发送自定义事件时将不会采集
$latest_utm_source、$latest_utm_medium、$latest_utm_term、$latest_utm_content、$latest_utm_campaign、$latest_scene 这些最近一次来源属性。9. 字节跳动小程序 SDK 预置事件和预置属性
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 说明 对
件 件 性 件 性 应
英 显 英 属 值 的
文 示 文 性 类 生
变 名 变 显 型 命
量 量 示 周
名 名 名 期
$MPLa 小程 $预置 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 小程序初始化完 App.
unch 序启 属性 sa.quick( ''appLaunch'', options ) 时会触发 成时，全局只触 onLaun
动 发一次 ch
$scene 启动场 字符
景 串
$url_pa 页面路 字符
th 径 串
$is_firs 是否首 逻辑
t_time 次
$utm_s 广告系 字符 0.3 版本以上
ource 列来源 串
$utm_ 广告系 字符 0.3 版本以上
medium 列媒介 串
$utm_t 广告系 字符 0.3 版本以上
erm 列字词 串
$utm_c 广告系 字符 0.3 版本以上
ontent 列内容 串
$utm_c 广告系 字符 0.3 版本以上
ampaign 列名称 串
$MPSh 小程 $预置 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa. 启动小程序时 App.
ow 序显 属性 quick( ''appShow'', options ) 时会触发 onShow
示
$scene 启动场 字符
景 串
$url_pa 页面路 字符
th 径 串
$utm_s 字符串 广告 0.3 版本以上
ource 系列
来源
$utm_ 字符串 广告 0.3 版本以上
medium 系列
媒介
$utm_t 字符串 广告 0.3 版本以上
erm 系列
字词
$utm_c 字符串 广告 0.3 版本以上
ontent 系列
内容
$utm_c 字符串 广告 0.3 版本以上
ampaign 系列
名称
$MPHi 小程 $预置 点击小程序右上角退出按钮、相关 App 进入后台、进入小程序关于页面、手机 小程序从前台进 App.
de 序进 属性 锁屏、小程序进程被杀死且在相应小程序生命周期函数中调用了 入后台 onHide
入后 sa.quick( ''Hide'' ) 时会触发时
台 $event 停留时 数值 从本次小程序显示 $MPShow 到
_durati 长 $MPHide 小程序进入后台或者关
on 闭的时间
$url_pa 页面路 字符
th 径 串
所有事件都有的预置属性
字段名称 类型 说明 SDK 版本
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 逻辑 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为
假，标识存在 storage 中）
$is_login_id 逻辑 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
$latest_utm_source 字符串 最近一次付费广告系列来源 0.3 及以上版本
$latest_utm_medium 字符串 最近一次付费广告系列媒介 0.3 及以上版本
$latest_utm_term 字符串 最近一次付费广告系列字词 0.3 及以上版本
$latest_utm_content 字符串 最近一次付费广告系列内容 0.3 及以上版本
$latest_utm_campaign 字符串 最近一次付费广告系列名称 0.3 及以上版本
$latest_scene 字符串 最近一次启动场景值 0.3 及以上版本.9. 字节跳动小程序 SDK 预置事件和预置属性 v1.13
预置事件
事 事 属 事 属 属性值示例或说明 触发时机 说明 对
件 件 性 件 性 应
英 显 英 属 值 的
文 示 文 性 类 生
变 名 变 显 型 命
量 量 示 周
名 名 名 期
$MPLa 小程 $预置 小程序进程被杀死，重新打开且在相应小程序生命周期函数中调用了 小程序初始化完 App.
unch 序启 属性 sa.quick( ''appLaunch'', options ) 时会触发 成时，全局只触 onLaun
动 发一次 ch
$scene 启动场 字符
景 串
$url_pa 页面路 字符
th 径 串
$is_firs 是否首 布尔
t_time 次 值
$utm_s 广告系 字符 0.3 版本以上
ource 列来源 串
$utm_ 广告系 字符 0.3 版本以上
medium 列媒介 串
$utm_t 广告系 字符 0.3 版本以上
erm 列字词 串
$utm_c 广告系 字符 0.3 版本以上
ontent 列内容 串
$utm_c 广告系 字符 0.3 版本以上
ampaign 列名称 串
$MPSh 小程 $预置 小程序启动，或从后台进入前台显示且在相应小程序生命周期函数中调用了 sa. 启动小程序时 App.
ow 序显 属性 quick( ''appShow'', options ) 时会触发 onShow
示
$scene 启动场 字符
景 串
$url_pa 页面路 字符
th 径 串
$utm_s 字符串 广告 0.3 版本以上
ource 系列
来源
$utm_ 字符串 广告 0.3 版本以上
medium 系列
媒介
$utm_t 字符串 广告 0.3 版本以上
erm 系列
字词
$utm_c 字符串 广告 0.3 版本以上
ontent 系列
内容
$utm_c 字符串 广告 0.3 版本以上
ampaign 系列
名称
$MPHi 小程 $预置 点击小程序右上角退出按钮、相关 App 进入后台、进入小程序关于页面、手机 小程序从前台进 App.
de 序进 属性 锁屏、小程序进程被杀死且在相应小程序生命周期函数中调用了 入后台 onHide
入后 sa.quick( ''Hide'' ) 时会触发时
台 $event 停留时 数值 从本次小程序显示 $MPShow 到
_durati 长 $MPHide 小程序进入后台或者关
on 闭的时间
$url_pa 页面路 字符
th 径 串
所有事件都有的预置属性
字段名称 类型 说明 SDK 版本
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔值 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为
假，标识存在 storage 中）
$is_login_id 布尔值 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型
$browser 字符串 浏览器名称
$browser_version 字符串 浏览器版本
$latest_utm_source 字符串 最近一次付费广告系列来源 0.3 及以上版本
$latest_utm_medium 字符串 最近一次付费广告系列媒介 0.3 及以上版本
$latest_utm_term 字符串 最近一次付费广告系列字词 0.3 及以上版本
$latest_utm_content 字符串 最近一次付费广告系列内容 0.3 及以上版本
$latest_utm_campaign 字符串 最近一次付费广告系列名称 0.3 及以上版本
$latest_scene 字符串 最近一次启动场景值 0.3 及以上版本10. 快应用 SDK 预置事件和预置属性
预置事件
事件英文变量名 事件显示名 属性英文变量名 事件属性显示名 属性值类型 属性值示例或说明
$AppStart App启动 $预置属性
$is_first_time 是否首次 逻辑
$scene 启动场景 字符串 启动场景（source.type）
$source_package_name 来源应用 字符串 来源包名（source.packageName）
$AppViewScreen App 浏览页面 $预置属性
$scene 启动场景 字符串 启动场景（source.type）
$title 页面标题 字符串 页面标题（router.getState().name）
$url_path 页面路径 字符串 页面路径(router.getState().path)
$source_package_name 来源应用 字符串 来源包名（source.packageName）
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 逻辑 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在
storage 中）
$is_login_id 逻辑 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型.10. 快应用 SDK 预置事件和预置属性 v1.13
预置事件
事件英文变量名 事件显示名 属性英文变量名 事件属性显示名 属性值类型 属性值示例或说明
$AppStart App启动 $预置属性
$is_first_time 是否首次 布尔值
$scene 启动场景 字符串 启动场景（source.type）
$source_package_name 来源应用 字符串 来源包名（source.packageName）
$AppViewScreen App 浏览页面 $预置属性
$scene 启动场景 字符串 启动场景（source.type）
$title 页面标题 字符串 页面标题（router.getState().name）
$url_path 页面路径 字符串 页面路径(router.getState().path)
$source_package_name 来源应用 字符串 来源包名（source.packageName）
所有事件都有的预置属性
字段名称 类型 说明
$lib 字符串 SDK 类型
$lib_version 字符串 SDK 版本
$screen_height 数值 屏幕高度
$screen_width 数值 屏幕宽度
$model 字符串 设备型号
$manufacturer 字符串 设备制造商
$os 字符串 操作系统
$os_version 字符串 操作系统版本
$is_first_day 布尔值 是否首日访问（从新用户第一次访问到当天的凌晨十二点之间的值都为真，之后为假，标识存在
storage 中）
$is_login_id 布尔值 是否是登录 ID (数据入库时判断添加)
$ip 字符串 SDK 发送数据请求时携带的属性
$country 字符串 由 IP 解析得到
$province 字符串 由 IP 解析得到
$city 字符串 由 IP 解析得到
$network_type 字符串 网络类型11. 服务端预置事件及预置属性
预置事件
事件英文变量名 事件显示名 属性英文变量名 事件属性显示名 属性值类型
$SignUp $SignUp $track_signup_origunal_id 关联原始ID 字符串.11. 服务端预置事件及预置属性 v1.13
预置事件
事件英文变量名 事件显示名 属性英文变量名 事件属性显示名 属性值类型
$SignUp $SignUp $track_signup_origunal_id 关联原始ID 字符串数据导入.数据导入 v1.13
神策分析提供几种不同的工具，方便用户将各种形式的数据导入系统中。
BatchImporter：一般用于批量的导入历史数据。
LogAgent：用于实时的从日志文件导入数据。
FormatImporter：用于导入 CSV、MySQL 数据库等结构化数据，也可以一次性导入日志文件。
HdfsImporter：适用于集群版的海量数据导入工具。
Logstash + Filebeat：Filebeat 是 Elastic 公司为解决 Logstash "太重" 的问题推出的一款轻量级日志采集器，在处理数量众多的服务器、虚拟机和容器生
成的日志时可使用 Logstash + Filebeat 的日志采集方式。BatchImporter.BatchImporter v1.13
在使用前，请先阅读数据模型和数据格式的介绍。
1. BatchImporter 概述
批量导入工具用于将历史数据或外部数据导入神策分析进行使用。实时数据导入请使用 LogAgent。
使用批量导入工具导入的数据需要符合数据格式，本文最后附录也有简单格式介绍。
2. 运行环境
批量导入工具只能在部署神策分析的单机或集群机器上使用。
3. 经典使用方法
本节介绍 BatchImporter 最常见的使用方法，其他功能请参考“4.使用方法详解”。
步骤如下：
a 将数据置于某个路径，比如需要导入的数据在 /home/work/data 下，有 part-001、part-002、part-003（命名可以随意）几个文件(每行一个符合数据
格式的 Json )。
b 切换到 sa_cluster 账户。
sudo su - sa_cluster
c 切换到批量导入工具目录下。
cd /home/sa_cluster/sa/tools/batch_importer
d 运行批量导入工具，**检查数据正确性，但不进行真的数据导入**。
注意：path 指向的是数据所在文件夹而不是文件，该文件夹下的所有文件都会被批量导入工具读取。
bin/sa-importer --path /home/work/data
运行后会显示统计信息，
Import session read 32 valid records, 0 lines can''t be parsed, 0 records invalid.
这里说明有32条有效数据，0条数据不可解析，0条可解析但数据无效。若有无效数据，将会在日志里体现。
e 经过步骤4检查数据都没问题以后，进行真正的数据导入。
bin/sa-importer --path /home/work/data --import --session new
当出现如下信息时说明导入结束。
Send 32 records to kafka
Import /home/work/data completed.
注意：
sa_cluster 需要有数据目录和文件的访问权限，可以切换到 sa_cluster 后 tail 一下数据文件看是否能打开。
导入后清理数据较复杂，请检查好再操作。对同一份数据多次运行导入会导致数据重复。批量导入工具的日志在神策分析的目录下，一般是在 /data/sa_cluster/logs/batch_importer 。由于数据有问题被过滤的数据将额外存储在上述日
志目录的 invalid_records 中。
批量导入工具通过 --path 参数指定要导入的目录，并导入目录下所有的文件。请在启动导入后不要增删、修改目录下的文件，否则无法保证导入
结果符合预期。
指定数据导入的项目有两种方法：
在数据中添加 project 字段（详见数据格式），使用这种方式可以一次导入多个项目的数据；
启动导入时，添加 --project 参数。所有数据无论是否指定 project 字段都将导入到参数设置的项目中。
常见问题：
1. distinct_id 是一个字符串 "123123" ，所给的数据里却是数值 123123 (没有双引号)。
2. 某个 property 字段的类型与之前数据的类型不符，比如之前是字符串，后来是数值。
4. 使用方法详解
4.1. 调用和参数
在批量导入工具的部署路径或其他路径下执行 sa-importer 。
sa-importer []
参数简介：
参数 说明
--help 打印使用说明
--type_define properties 中各字段类型限定
--import 是否执行导入，若不配置该参数，运行只做校验
--speed_limit 导入速度限制，单位是 条/秒，默认为不限速
--sample 输出一些样例数据。
--path 需要导入数据的路径
--session 本次运行导入的 Session 文件。如果是一次新的导入任务，请设置为 new
--parser 默认 Json ，一般请勿使用该参数
--manifest 批量导入工具运行结束后，使用参数值作为路径输出 manifest 文件。若启动时该路径已经有文件，那么启动失败。
--project 将数据导入的项目。请注意，若指定该参数，数据中的 project 字段将无效，本次运行的所有数据都将导入到 --
project 指定的项目。
-- 允许导入的数据时间区间截至未来的小时数，默认为 1，即超过未来 1 小时的数据将被过滤。
expired_record_filter_after_ho
ur
-- 允许导入的数据时间区间向前的小时数，默认为 17520，即超过 2 年以前的数据将被过滤。
expired_record_filter_before_h
our
批量导入工具两种运行模式为：校验数据模式 和 导入数据模式。
4.2. 校验数据模式
由于数据导入是一个复杂的过程，所以我们希望导入数据前用户可以对数据先进行简单的校验工作，主要是校验数据是否符合最基本的规范（见概述中数据
格式的描述）。
批量导入工具校验功能的使用流程如下：
1. 将需要检验的数据放入部署神策分析系统的某台机器中，该目录中不要包含其他不需要检验的无关文件，例如路径是 /home/work/data 。
2. 运行批量导入工具：
bin/sa-importer --path /home/work/data运行结束会显示统计：
Import session read 33128 valid records, 3 lines can''t be parsed, 2 records invalid.
表示有 33128 条数据符合格式，3 条数据无法解析，2 条数据有问题。
若希望 BatchImporter 遇到错误数据立刻停止运行，可以添加参数 --debug_exit_with_bad_record。例如：
bin/sa-importer --path /home/work/data --debug_exit_with_bad_record
4.3. 导入数据模式
导入数据的过程分为启动一个新的导入任务和恢复旧的导入任务。
**导入数据模式的标志是 --import 参数，如果不加该参数则运行模式为4.2中介绍的校验数据。**
**导入数据模式必须使用 --session <SessionFile> 参数显式的指定 SessionFile ，如果是一次新导入任务，请设置 SessionFile 的值为 new。**
4.3.1. 新建导入任务
1. 将需要检验的数据放入部署神策分析系统的某台机器中，该目录中不要包含其他不需要检验的无关文件，例如路径是 /home/work/data 。
2. 运行批量导入工具：使用 --import --session new ，必须指定路径 --path 。
bin/sa-importer --path /home/work/data --import --session new
刚开始运行或 Ctrl+C 中断都会显示本次的 SessionID ：
启动时：Importer Session File: ''2015-06-19-18-19-50.session''
Ctrl+C 退 出 时 ：Import session file: ''2015-06-19-18-19-50.session'', you can run importer with arg ''-session 2015-06-19-18-19-50.session'' to
continue import.
4.3.2. 恢复导入任务
如果某次数据导入任务被中止，使用 SessionFile 可以进行该任务的恢复：
1. 例如某次导入 /home/work/data 的导入任务被中止。
2. 运行批量导入工具：使用--import，必须指定--session <SessionID>，**不能指定--path**。
bin/sa-importer --import --session 2015-06-19-18-19-50.session
注意：如果要恢复导入任务，那么之前使用的目录下不能有**任何文件变动**（修改内容，添加文件，删除文件），否则将启动失败。如需追加导入内容，
请将数据放到其他目录，并使用“新建导入任务”。
4.4. manifest 文件内容解读
若使用了 manifest 参数指定了 manifest 文件，导入运行结束后会在参数值目录生成 manifest 文件，该文件包含导入的基本统计信息，可用于自动化脚
本，作为 done 文件（导入结束的标志）。
若启动导入时 manifest 参数值所指路径文件已经存在，那么导入启动会失败。
生成 manifest 不是必须的，该文件内容可用于调试和判断导入过程是否结束，并简单校验导入正确性。
bin/sa-importer --path /home/work/data --session new --import --manifest info_2015_12_22
生成的 info_2015_12_22 文件样例：
{
"session_id" : "1", // SessionID
"do_import" : true, // false
"complete" : true, // false
"read_files" : [ "/home/work/data/a", "/home/work/data/b" ], //"plan_files" : [ "/home/work/data/a", "/home/work/data/b" ], //
"valid_count" : 209, //
"total_count" : 209, //
"progress" : {
"synced_source_progress" : { //
"f" : "(dev=801,ino=1055397)",
"o" : 32232,
"n" : "b",
"s" : 208,
"c" : 208,
"e" : "1"
},
"sended_source_progress" : { //
"f" : "(dev=801,ino=1055397)",
"o" : 32232,
"n" : "b",
"s" : 208,
"c" : 208,
"e" : "1"
},
"kafka_progress" : { // kafka
"0" : {
"offset" : 22435,
"partition_id" : 0,
"update_timestamp" : 1450771040053
},
"1" : {
"offset" : 22838,
"partition_id" : 1,
"update_timestamp" : 1450771045419
},
"2" : {
"offset" : 23185,
"partition_id" : 2,
"update_timestamp" : 1450771040071
}
},
"last_update_time" : 1450771042587, //
"last_sync_time" : 1450771045419, // kafka
"status" : {
"start_times" : 1,
"this_time_start_running_time" : 1450771040213, //
"sending_speed" : 0.0,
"sending_records_in_store" : 0,
"counter_filtered_by_expired_time" : 0,
"counter_invalid_log_entry" : 0,
"counter_invalid_reader_log_entry" : 0,
"sent_to_kafka" : 209,
"raw_read_count" : 209,
"message_counter" : {
"counter_map" : { }
}
}
}
}
5. 注意事项
1. 运行批量导入工具导入的数据不易清除，请谨慎操作。
2. 批量导入工具读取文件的顺序是按照指定文件夹中文件名的字典序。
3. 如果SensorsAnalytics有正在运行的实时数据流，请设置限速以免影响实时数据，设置的方法是加参数 --speed_limit <limit> ，例如 --
speed_limit 300 。
附录 I. 数据格式
另外有专门页面介绍数据格式，请参考数据格式
需要导入的文件每行为一条如下格式的 JSON ：{"type":"track","properties":{"propertie1":"value1","propertie2":"value2"},"event":"EventName","distinct_id":"
DistinctId","original_id":"OriginalId","time":1431353191267}
属性简介：
属性名 要求 含义
type 必须字段，值只能是下表中给出的 这条记录的类型
properties 必须字段，JSON 的 k-v 对 Event 或 Profile 关联的属性
event type 为 track 类时为必须字段，profile 类时不需设置。字符串 Event 的名字
distinct_id 必须字段。字符串 用户的固定且唯一标识
original_id type 为 track_signup 时为必须字段，其他 type 该字段没有用。字符串 注册之前的随机匿名ID
time 必须字段。unix 时间戳，精确到毫秒! 这条记录对应的时间
type：这条数据的类型，可以是如下类型中的一种
Type 解释
track 一个 Event 及关联的 Properties
track_signup 跟踪用户的注册行为，该接口与 track 基本相同，除了多了一个 original_id 参数。
profile_set 直接设置一个用户的 Profile，如果用户或者 Profile 已存在则覆盖，不存在则自动创建。
profile_append 追加一个用户的某个 List 类型的 Profile，如果用户或者 Profile 不存在则自动创建。
profile_increment 增加或减少一个用户的某个 Numeric 类型的 Profile，如果用户不存在则自动创建, Profile 不存在则默认为 0。
profile_delete 删除一个用户。
profile_unset 删除一个用户的某个特定的 Profile。
properties：Event 或 Profile 关联的属性，Key-Value 结构。Key 必须为字符串， Value 的类型可以是字符串、整数、浮点数、布尔、字符串数
组。Key 中字符只能为大小写字母、数字和下划线。SensorsAnalytics 中的属性数据类型定义，及长度限制，详见：数据格式。
注意：每个 property 的类型需要保证从始至终都是同一个。如一开始为 NUMBER ，之后不能变为 STRING event：
Event 的名字。如果 type 是 track 类，说明这是一条 event 类型数据，需要包含该字段，否则这条数据将无效被过滤。
original_id：在用户注册之前所使用的随机匿名 ID。
distinct_id: 用户的固定且唯一标识，例如用户表的主键等，一般应当是由产品的注册行为返回。
time：这条数据对应的时间，单位为毫秒。 2015/6/19 17:36:11 对应 1434706571000。.BatchImporter v1.15
在使用前，请先阅读数据模型和数据格式的介绍。
1. BatchImporter 概述
批量导入工具用于将历史数据或外部数据导入神策分析进行使用。实时数据导入请使用 LogAgent。
使用批量导入工具导入的数据需要符合数据格式，本文最后附录也有简单格式介绍。
2. 运行环境
批量导入工具只能在部署神策分析的单机或集群机器上使用。
3. 经典使用方法
本节介绍 BatchImporter 最常见的使用方法，其他功能请参考“4.使用方法详解”。
步骤如下：
a 将数据置于某个路径，比如需要导入的数据在 /home/work/data 下，有 part-001、part-002、part-003（命名可以随意）几个文件(每行一个符合数据
格式的 Json )。
b 切换到 sa_cluster 账户。
sudo su - sa_cluster
c 切换到批量导入工具目录下。
cd /home/sa_cluster/sa/tools/batch_importer
d 运行批量导入工具，检查数据正确性，但不进行真的数据导入。
注意：path 指向的是数据所在文件夹而不是文件，该文件夹下的所有文件都会被批量导入工具读取。
bin/sa-importer --path /home/work/data
运行后会显示统计信息，
Import session read 32 valid records, 0 lines can''t be parsed, 0 records invalid.
这里说明有32条有效数据，0条数据不可解析，0条可解析但数据无效。若有无效数据，将会在日志里体现。
e 经过步骤4检查数据都没问题以后，进行真正的数据导入。
bin/sa-importer --path /home/work/data --import --session new
当出现如下信息时说明导入结束。
Send 32 records to kafka
Import /home/work/data completed.
注意：
sa_cluster 需要有数据目录和文件的访问权限，可以切换到 sa_cluster 后 tail 一下数据文件看是否能打开。
导入后清理数据较复杂，请检查好再操作。对同一份数据多次运行导入会导致数据重复。批量导入工具的日志在神策分析的目录下，一般是在 /data/sa_cluster/logs/batch_importer 。由于数据有问题被过滤的数据将额外存储在上述日
志目录的 invalid_records 中。
批量导入工具通过 --path 参数指定要导入的目录，并导入目录下所有的文件。请在启动导入后不要增删、修改目录下的文件，否则无法保证导入
结果符合预期。
指定数据导入的项目有两种方法：
在数据中添加 `project` 字段（详见数据格式），使用这种方式可以一次导入多个项目的数据；
启动导入时，添加 `--project` 参数。所有数据无论是否指定 `project` 字段都将导入到参数设置的项目中。
常见问题：
1. distinct_id 是一个字符串 "123123" ，所给的数据里却是数值 123123 (没有双引号)。
2. 某个 property 字段的类型与之前数据的类型不符，比如之前是字符串，后来是数值。
4. 使用方法详解
4.1. 调用和参数
在批量导入工具的部署路径或其他路径下执行 sa-importer 。
sa-importer []
参数简介：
参数 说明
--help 打印使用说明
--type_define properties 中各字段类型限定
--import 是否执行导入，若不配置该参数，运行只做校验
--speed_limit 导入速度限制，单位是 条/秒，默认为不限速
--sample 输出一些样例数据。
--path 需要导入数据的路径
--session 本次运行导入的 Session 文件。如果是一次新的导入任务，请设置为 new
--parser 默认 Json ，一般请勿使用该参数
--manifest 批量导入工具运行结束后，使用参数值作为路径输出 manifest 文件。若启动时该路径已经有文件，那么启动失败。
--project 将数据导入的项目。请注意，若指定该参数，数据中的 project 字段将无效，本次运行的所有数据都将导入到 --
project 指定的项目。
-- 允许导入的数据时间区间截至未来的小时数，默认为 1，即超过未来 1 小时的数据将被过滤。
expired_record_filter_after_ho
ur
-- 允许导入的数据时间区间向前的小时数，默认为 17520，即超过 2 年以前的数据将被过滤。
expired_record_filter_before_h
our
批量导入工具两种运行模式为：校验数据模式 和 导入数据模式。
4.2. 校验数据模式
由于数据导入是一个复杂的过程，所以我们希望导入数据前用户可以对数据先进行简单的校验工作，主要是校验数据是否符合最基本的规范（见概述中数据
格式的描述）。
批量导入工具校验功能的使用流程如下：
1. 将需要检验的数据放入部署神策分析系统的某台机器中，该目录中不要包含其他不需要检验的无关文件，例如路径是 `/home/work/data` 。
2. 运行批量导入工具：
bin/sa-importer --path /home/work/data运行结束会显示统计：
Import session read 33128 valid records, 3 lines can''t be parsed, 2 records invalid.
表示有 33128 条数据符合格式，3 条数据无法解析，2 条数据有问题。
若希望 BatchImporter 遇到错误数据立刻停止运行，可以添加参数 `--debug_exit_with_bad_record`。例如：
bin/sa-importer --path /home/work/data --debug_exit_with_bad_record
4.3. 导入数据模式
导入数据的过程分为启动一个新的导入任务和恢复旧的导入任务。
导入数据模式的标志是 --import 参数，如果不加该参数则运行模式为4.2中介绍的校验数据。
导入数据模式必须使用 --session <SessionFile> 参数显式的指定 SessionFile ，如果是一次新导入任务，请设置 SessionFile 的值为 new。
4.3.1. 新建导入任务
1. 将需要检验的数据放入部署神策分析系统的某台机器中，该目录中不要包含其他不需要检验的无关文件，例如路径是 /home/work/data 。
2. 运行批量导入工具：使用 --import --session new ，必须指定路径 --path 。
bin/sa-importer --path /home/work/data --import --session new
刚开始运行或 Ctrl+C 中断都会显示本次的 SessionID ：
启动时：Importer Session File: ''2015-06-19-18-19-50.session''
Ctrl+C 退 出 时 ：Import session file: ''2015-06-19-18-19-50.session'', you can run importer with arg ''-session 2015-06-19-18-19-50.session'' to
continue import.
4.3.2. 恢复导入任务
如果某次数据导入任务被中止，使用 SessionFile 可以进行该任务的恢复：
1. 例如某次导入 /home/work/data 的导入任务被中止。
2. 运行批量导入工具：使用 --import，必须指定 --session <SessionID>，不能指定 --path。
bin/sa-importer --import --session 2015-06-19-18-19-50.session
注意：如果要恢复导入任务，那么之前使用的目录下不能有任何文件变动（修改内容，添加文件，删除文件），否则将启动失败。如需追加导入内容，请将
数据放到其他目录，并使用“新建导入任务”。
4.4. manifest 文件内容解读
若使用了 manifest 参数指定了 manifest 文件，导入运行结束后会在参数值目录生成 manifest 文件，该文件包含导入的基本统计信息，可用于自动化脚
本，作为 done 文件（导入结束的标志）。
若启动导入时 manifest 参数值所指路径文件已经存在，那么导入启动会失败。
生成 manifest 不是必须的，该文件内容可用于调试和判断导入过程是否结束，并简单校验导入正确性。
bin/sa-importer --path /home/work/data --session new --import --manifest info_2015_12_22
生成的 info_2015_12_22 文件样例：
{
"session_id" : "1", // SessionID
"do_import" : true, // false
"complete" : true, // false
"read_files" : [ "/home/work/data/a", "/home/work/data/b" ], //
"plan_files" : [ "/home/work/data/a", "/home/work/data/b" ], //"valid_count" : 209, //
"total_count" : 209, //
"progress" : {
"synced_source_progress" : { //
"f" : "(dev=801,ino=1055397)",
"o" : 32232,
"n" : "b",
"s" : 208,
"c" : 208,
"e" : "1"
},
"sended_source_progress" : { //
"f" : "(dev=801,ino=1055397)",
"o" : 32232,
"n" : "b",
"s" : 208,
"c" : 208,
"e" : "1"
},
"kafka_progress" : { // kafka
"0" : {
"offset" : 22435,
"partition_id" : 0,
"update_timestamp" : 1450771040053
},
"1" : {
"offset" : 22838,
"partition_id" : 1,
"update_timestamp" : 1450771045419
},
"2" : {
"offset" : 23185,
"partition_id" : 2,
"update_timestamp" : 1450771040071
}
},
"last_update_time" : 1450771042587, //
"last_sync_time" : 1450771045419, // kafka
"status" : {
"start_times" : 1,
"this_time_start_running_time" : 1450771040213, //
"sending_speed" : 0.0,
"sending_records_in_store" : 0,
"counter_filtered_by_expired_time" : 0,
"counter_invalid_log_entry" : 0,
"counter_invalid_reader_log_entry" : 0,
"sent_to_kafka" : 209,
"raw_read_count" : 209,
"message_counter" : {
"counter_map" : { }
}
}
}
}
5. 注意事项
1. 运行批量导入工具导入的数据不易清除，请谨慎操作。
2. 批量导入工具读取文件的顺序是按照指定文件夹中文件名的字典序。
3. 如果SensorsAnalytics有正在运行的实时数据流，请设置限速以免影响实时数据，设置的方法是加参数 `--speed_limit <limit>` ，例如 `--
speed_limit 300` 。
附录 I. 数据格式
另外有专门页面介绍数据格式，请参考 数据格式
需要导入的文件每行为一条如下格式的 JSON ：{"type":"track","properties":{"propertie1":"value1","propertie2":"value2"},"event":"EventName","distinct_id":"
DistinctId","original_id":"OriginalId","time":1431353191267}
属性简介：
属性名 要求 含义
type 必须字段，值只能是下表中给出的 这条记录的类型
properties 必须字段，JSON 的 k-v 对 Event 或 Profile 关联的属性
event type 为 track 类时为必须字段，profile 类时不需设置。字符串 Event 的名字
distinct_id 必须字段。字符串 用户的固定且唯一标识
original_id type 为 track_signup 时为必须字段，其他 type 该字段没有用。字符串 注册之前的随机匿名ID
time 必须字段。unix 时间戳，精确到毫秒! 这条记录对应的时间
type：这条数据的类型，可以是如下类型中的一种
Type 解释
track 一个 Event 及关联的 Properties
track_signup 跟踪用户的注册行为，该接口与 track 基本相同，除了多了一个 original_id 参数。
profile_set 直接设置一个用户的 Profile，如果用户或者 Profile 已存在则覆盖，不存在则自动创建。
profile_append 追加一个用户的某个 List 类型的 Profile，如果用户或者 Profile 不存在则自动创建。
profile_increment 增加或减少一个用户的某个 Numeric 类型的 Profile，如果用户不存在则自动创建, Profile 不存在则默认为 0。
profile_delete 删除一个用户。
profile_unset 删除一个用户的某个特定的 Profile。
properties：Event 或 Profile 关联的属性，Key-Value 结构。Key 必须为字符串， Value 的类型可以是字符串、整数、浮点数、布尔、字符串数
组。Key 中字符只能为大小写字母、数字和下划线。SensorsAnalytics 中的属性数据类型定义，及长度限制，详见：数据格式。
注意：每个 property 的类型需要保证从始至终都是同一个。如一开始为 NUMBER ，之后不能变为 STRING event：
Event 的名字。如果 type 是 track 类，说明这是一条 event 类型数据，需要包含该字段，否则这条数据将无效被过滤。
original_id：在用户注册之前所使用的随机匿名 ID。
distinct_id: 用户的固定且唯一标识，例如用户表的主键等，一般应当是由产品的注册行为返回。
time：这条数据对应的时间，单位为毫秒。 2015/6/19 17:36:11 对应 1434706571000。FormatImporter.FormatImporter v1.13
1. FormatImporter 概述
FormatImporter 用于将一些常见格式的外部数据导入到神策分析，目前支持读取 csv 表格、Nginx 日志、mysql 数据库、oracle 数据库，以及符合 数据格
式 的 json 数据。
下载请点击此链接，脚本下载后是一个压缩包，注意运行此脚本需要 python3.4。另外如果需要导入 mysql、oracle 数据库中的数据的话需要确保机器上包
含相关客户端的程序包。
2. 经典使用方法
2.1. 获取数据接收地址
首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。
如果使用神策分析 Cloud 服务，需获取的配置信息为:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
2.2. 示例场景
假设有一个电商网站，需要采集以下用户事件：浏览事件，包括浏览的商品名称 ( item_name ) 和商品 id ( item_id)
购买事件，包括购买的商品名称 ( item_name ) 和商品 id ( item_id)
示例事件如下
用户 事件 时间 商品id 商品名称
bug29 浏览 2018-05-12 13:01:11 13245 男士护耳保暖鸭舌皮帽平顶八角帽头层牛皮帽子时尚休闲
bug29 购买 2018-05-12 13:05:03 13245 男士护耳保暖鸭舌皮帽平顶八角帽头层牛皮帽子时尚休闲
小武 浏览 2018-05-13 10:20:32 23421 New Order Technique 2CD豪华版 欧版行货 全新未拆
菠菜 浏览 2018-05-13 20:42:53 3442 NUK安抚奶嘴宝宝防胀气安慰奶嘴乳胶迪士尼安睡型
并采集以下用户属性：
* 用户的性别 ( gender )，男或女
* 用户是否是会员 ( is_member )
* 用户的会员积分 ( score )
示例用户属性如下
用户名 性别 是否为会员 会员积分
bug29 男 是 131
小武 女 否 <没有积分>
2.3. 导入 csv 格式的数据
2.3.1. 导入事件
假设有以下 csv 文件描述了上面的示例用户事件 ( 参考代码包下 examples/events.csv )。
user_id,action,time,item_id,item_name,item_cate
bug29,view,2018-05-12 13:01:11,13245,,
bug29,buy,2018-05-12 13:05:03,13245,,
,view,2018-05-13 10:20:32,23421,New Order Technique 2CD ,
,view,2018-05-13 20:42:53,3442,NUK,
将这些数据导入到本地私有部署的环境，以 user_id 作为用户的 id，以 time 作为事件发生的时间，以 action 作为事件名称，只导入 item_id 和
item_name 作为事件属性。
python3 format_importer.py csv_event \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \
--timestamp_from ''time'' \
--event_from ''action'' \
--filename ''./examples/events.csv'' \
--property_list ''item_id,item_name'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/csv_event.conf )。
url: http://localhost:8106/sa
distinct_id_from: user_id
event_from: action
timestamp_from: time
filename: ./examples/events.csv
property_list: item_id,item_name
debug
然后执行
python3 format_importer.py csv_event @./conf/csv_event.conf2.3.2. 导入用户属性
假设有以下 csv 文件描述了上面的示例用户属性 ( 参考代码包下 examples/profiles.csv )。
user_id,gender,is_member,score
bug29,,true,131
,,false,
将这些数据导入到本地私有部署的环境，以 user_id 作为用户的 id。
python3 format_importer.py csv_profile \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \
--filename ''./examples/profiles.csv'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/csv_profile.conf )。
url: http://localhost:8106/sa?project=xxx
distinct_id_from: user_id
filename: ./examples/profiles.csv
debug
然后执行
python3 format_importer.py csv_profile @./conf/csv_profile.conf
2.3.3. 导入 item 数据
假设有以下 csv 文件描述了上面的示例用户事件 ( 参考代码包下 examples/item.csv )。
item_type,item_id,item_name,item_cate,action
view,13245,,,
buy,13245,,,
view,23421,New Order Technique 2CD ,,
view,3442,NUK,,
将数据导入 item 表中，--item_type 和 --item_id 命令分别指定 item 数据的 item_type 和 item_id 字段值
python3 format_importer.py csv_item \
--url ''http://localhost:8106/sa?project=xxx'' \
--item_type ''item_type'' \
--item_id ''item_id'' \
--property_list ''item_name,item_cate,action'' \
--filename ''./examples/item.csv'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/csv_item.conf )。
url: http://localhost:8106/sa?project=xxx
item_type: item_type
item_id: item_id
filename: ./examples/events.csv
debug
然后执行
python3 format_importer.py csv_item @./conf/csv_item.conf2.3.4. 导入 nginx 日志
2.3.4.1. 导入事件
假设有以下 nginx 日志描述了上面的示例用户事件 ( 参考代码包下 examples/events.log )。
123.4.5.6 - [12/May/2018:13:01:11 +0800] "GET /item?id=13245&action=view&cate=%e7%94%b7%e8%a3%85" 200 1127
"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.
36" "http://fake_web.com/login.html" "" "bug29"
123.4.5.6 - [12/May/2018:13:05:03 +0800] "GET /item?id=13245&action=buy&cate=%e7%94%b7%e8%a3%85" 200 1127
"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.
36" "http://fake_web.com/login.html" "" "bug29"
123.4.5.7 - [13/May/2018:10:20:32 +0800] "GET /item?id=23421&action=view&cate=%e9%9f%b3%e5%83%8f" 200 1127
"Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36"
"http://www.baidu.com?q=abc" "New Order Technique 2CD " ""
123.8.5.7 - [13/May/2018:20:42:53 +0800] "GET /item?id=&action=view&cate=%e6%af%8d%e5%a9%b4" 200 1127 "Mozilla
/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36" "http://www.
baidu.com?q=abc" "NUK" ""
对应 nginx 配置的格式如下:
log_format compression ''$remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent"
"$http_referer" "$title" "$user_id"'';
access_log /data/nginx_log/access.log compression;
将这些数据导入到本地私有部署的环境，以 $user_id 作为用户的 id，以 $time_local 作为事件发生的时间，$reqeust 解析后的参数 action 对应的值是事件
名，只导入两个事件属性： $request 解析后的 id 作为 item_id，自定义的变量 $title 作为 item_name。
python3 format_importer.py nginx_event \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \
--timestamp_from ''time_local'' \
--timestamp_format ''%d/%b/%Y:%H:%M:%S %z'' \
--event_from '' request_param_action'' \
--filename ''./examples/events.log'' \
--log_format ''$remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent" "$http_referer"
"$title" "$user_id"'' \
--property_list '' request_param_id,title'' \
--property_list_cnames ''item_id,item_name'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/nginx_event.conf )。
url: http://localhost:8106/sa?project=xxx
distinct_id_from: user_id
event_from: request_param_action
timestamp_from: time_local
timestamp_format: %d/%b/%Y:%H:%M:%S %z
filename: ./examples/events.log
log_format: $remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent" "$http_referer"
"$title" "$user_id"
property_list: request_param_id,title
property_list_cnames: item_id,item_name
debug
然后执行
python3 format_importer.py nginx_event @./conf/nginx_event.conf
2.3.5. 导入用户属性假设有以下 nginx 日志描述了上面的示例用户属性 ( 参考代码包下 examples/profiles.log )。
123.4.5.6 - [12/May/2018:13:01:11 +0800] "POST /profile?user=bug29&is_member=true" 200 1127 "Mozilla/5.0
(Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.36"
"http://fake_web.com/login.html" "" "131"
123.4.5.7 - [13/May/2018:10:20:32 +0800] "POST /profile?user=%e5%b0%8f%e6%ad%a6&is_member=false" 200 1127
"Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36"
"http://www.baidu.com?q=abc" "" ""
对应 nginx 配置的格式如下:
log_format compression ''$remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent"
"$http_referer" "$gender" "$score"'';
access_log /data/nginx_log/access.log compression;
将这些数据导入到本地私有部署的环境，以 $reqeust 解析后的参数 user 作为用户的 id，导入三个用户属性： 自定义变量 $gender 和 $score ，以及
$reqeust 解析后的参数 is_member。
python3 format_importer.py nginx_profile \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from '' request_param_user'' \
--filename ''./examples/profiles.log'' \
--log_format ''$remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent" "$http_referer"
"$gender" "$score"'' \
--property_list ''gender,score, request_param_is_member'' \
--property_list_cnames ''gender,score,is_member'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/nginx_profile.conf )。
url: http://localhost:8106/sa?project=xxx
distinct_id_from: request_param_user
filename: ./examples/profiles.log
log_format: $remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent" "$http_referer"
"$gender" "$score"
property_list: gender,score, request_param_is_member
property_list_cnames: gender,score,is_member
debug
然后执行
python3 format_importer.py nginx_profile @./conf/nginx_profile.conf
2.3.6. 导入 item 数据
假设有以下 nginx 日志描述了上面的示例用户属性 ( 参考代码包下 examples/item.log )。
123.4.5.6 - [12/May/2018:13:01:11 +0800] "GET /item?id=13245&action=view&cate=%e7%94%b7%e8%a3%85" 200 1127
"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.
36" "http://fake_web.com/login.html" "" "bug29"
123.4.5.6 - [12/May/2018:13:05:03 +0800] "GET /item?id=13245&action=buy&cate=%e7%94%b7%e8%a3%85" 200 1127
"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.
36" "http://fake_web.com/login.html" "" "bug29"
123.4.5.7 - [13/May/2018:10:20:32 +0800] "GET /item?id=23421&action=view&cate=%e9%9f%b3%e5%83%8f" 200 1127
"Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36"
"http://www.baidu.com?q=abc" "New Order Technique 2CD " ""
123.8.5.7 - [13/May/2018:20:42:53 +0800] "GET /item?id=&action=view&cate=%e6%af%8d%e5%a9%b4" 200 1127 "Mozilla
/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36" "http://www.
baidu.com?q=abc" "NUK" ""
对应 nginx 配置的格式如下:log_format compression ''$remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent"
"$http_referer" "$title" "$user_id"'';
access_log /data/nginx_log/access.log compression;
将这些数据导入到本地私有部署的环境，以 $reqeust 解析后的参数 user 作为用户的 id，导入三个用户属性： 自定义变量 $gender 和 $score ，以及
$reqeust 解析后的参数 is_member。
python3 format_importer.py nginx_item \
--url ''http://localhost:8106/sa?project=xxx'' \
--item_id ''user_id'' \
--item_type '' request_param_action'' \
--filename ''./examples/item.log'' \
--log_format ''$remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent" "$http_referer"
"$title" "$user_id"'' \
--property_list '' request_param_id,title'' \
--property_list_cnames ''$gender,$score'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/nginx_item.conf )。
url: http://localhost:8106/sa?project=xxx
item_id: user_id
filename: ./examples/profiles.log
log_format: $remote_addr [$time_local] "$request" $status $bytes_sent "$http_user_agent" "$http_referer"
"$gender" "$score"
property_list: gender,score, request_param_is_member
property_list_cnames: gender,score,is_member
debug
然后执行
python3 format_importer.py nginx_item @./conf/nginx_item.conf
2.3.7. 导入 mysql 的数据
注意使用 mysql 导入需要先安装相关库，请运行下面命令来安装 PyMySQL。
python3 -m pip install PyMySQL --upgrade
2.3.7.1. 导入事件
假设有以下 mysql 表描述了上面的示例用户事件 ( 参考代码包下 examples/events.sql )。
drop table if exists events;
create table events
( user_id varchar(100),
action varchar(100),
time timestamp,
item_id int,
item_name text,
item_cate varchar(100));
insert into events values(''bug29'', ''view'', ''2018-05-12 13:01:11'', 13245, '''', '''');
insert into events values(''bug29'', ''buy'', ''2018-05-12 13:05:03'', 13245, '''', '''');
insert into events values('''', ''view'', ''2018-05-13 10:20:32'', 23421, ''New Order Technique 2CD '', '''');
insert into events values('''', ''view'', ''2018-05-13 20:42:53'', 3442, ''NUK'', '''');
将这些数据导入到本地私有部署的环境，以 user_id 作为用户的 id，以 time 作为事件发生的时间，以 action 作为事件名称，只导入 item_id 和
item_name 作为事件属性。最后的 ORDER BY 主要是保证多次查询数据顺序一致，这样假如导入一半失败了，可以使用我们的参数跳过导入成功的行数。
python3 format_importer.py mysql_event \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \--timestamp_from ''time'' \
--event_from ''action'' \
--user ''root'' \
--password ''pass'' \
--host ''localhost'' \
--port 3307 \
--db ''test_db'' \
--sql ''select user_id, action, time, item_id, item_name from events order by time;'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/mysql_event.conf )。
url: http://localhost:8106/sa?project=xxx
distinct_id_from: user_id
event_from: action
timestamp_from: time
user: root
password: pass
host: localhost
port: 3307
db: test_db
sql: select user_id, action, time, item_id, item_name from events order by time;
debug
然后执行
python3 format_importer.py mysql_event @./conf/mysql_event.conf
2.3.7.2. 导入用户属性
假设有以下 mysql 表描述了上面的示例用户属性 ( 参考代码包下 examples/profiles.sql )。
drop table if exists profiles;
create table profiles
( user_id varchar(100),
gender varchar(20),
is_member bool,
score int);
insert into profiles values(''bug29'', '''', true, 131);
insert into profiles values('''', '''', false, null);
将这些数据导入到本地私有部署的环境，以 user_id 作为用户的 id，导入全部用户属性。最后的 ORDER BY 主要是保证多次查询数据顺序一致，这样假如
导入一半失败了，可以使用我们的参数跳过导入成功的行数。
python3 format_importer.py mysql_profile \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \
--user ''root'' \
--password ''pass'' \
--host ''localhost'' \
--port 3307 \
--db ''test_db'' \
--sql ''select user_id, gender, is_member, score from profiles order by user_id;'' \
--bool_property_list ''is_member'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/mysql_profile.conf )。
url: http://localhost:8106/sa?project=xxx
distinct_id_from: user_id
user: root
password: pass
host: localhost
port: 3307db: test_db
sql: select user_id, gender, is_member, score from profiles order by user_id;
bool_property_list: is_member
debug
然后执行
python3 format_importer.py mysql_profile @./conf/mysql_profile.conf
2.3.7.3. 导入 item 数据
假设有以下 mysql 表描述了上面的示例用户事件 ( 参考代码包下 examples/events.sql )。
drop table if exists events;
create table events
( user_id varchar(100),
action varchar(100),
time timestamp,
item_id int,
item_name text,
item_cate varchar(100));
insert into events values(''bug29'', ''view'', ''2018-05-12 13:01:11'', 13245, '''', '''');
insert into events values(''bug29'', ''buy'', ''2018-05-12 13:05:03'', 13245, '''', '''');
insert into events values('''', ''view'', ''2018-05-13 10:20:32'', 23421, ''New Order Technique 2CD '', '''');
insert into events values('''', ''view'', ''2018-05-13 20:42:53'', 3442, ''NUK'', '''');
将这些数据导入到本地私有部署的环境，以数据库中的 item_id 作为 item 数据的 item_id，以数据库的 action 作为 item_type 。最后的 ORDER BY 主要
是保证多次查询数据顺序一致，这样假如导入一半失败了，可以使用我们的参数跳过导入成功的行数。
format_importer.py mysql_item \
--url ''http://localhost:8106/sa?project=xxx'' \
--item_type ''action'' \
--item_id ''item_id'' \
--user ''root'' \
--password ''root1234'' \
--host ''localhost'' \
--port 3306 \
--db ''sa_item'' \
--sql ''select user_id, gender, is_member, score from profiles order by user_id'' \
--debug \ # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/mysql_event.conf )。
url: http://localhost:8106/sa?project=xxx
item_id: user_id
item_type: action
user: root
password: pass
host: localhost
port: 3307
db: test_db
sql: select user_id, gender, is_member, score from profiles order by user_id;
debug
然后执行
python3 format_importer.py mysql_event @./conf/mysql_item.conf
2.3.8. 导入 json 格式的日志
用户也可以将日志写入文件中，每行是一个 数据格式 表示事件或属性或者 item 数据。假设有以下日志描述了上面的示例的事件、用户属性、item 数据 ( 参
考代码包下 examples/json_data.json )。{"type":"track","time":1526101271000,"distinct_id":"bug29","properties":{"item_id":13245.0,"item_name":"
\u7537\u58eb\u62a4\u8033\u4fdd\u6696\u9e2d\u820c\u76ae\u5e3d\u5e73\u9876\u516b\u89d2\u5e3d\u5934\u5c42\u725b\u76
ae\u5e3d\u5b50\u65f6\u5c1a\u4f11\u95f2"},"event":"view","time_free":true}
{"type":"track","time":1526101503000,"distinct_id":"bug29","properties":{"item_id":13245.0,"item_name":"
\u7537\u58eb\u62a4\u8033\u4fdd\u6696\u9e2d\u820c\u76ae\u5e3d\u5e73\u9876\u516b\u89d2\u5e3d\u5934\u5c42\u725b\u76
ae\u5e3d\u5b50\u65f6\u5c1a\u4f11\u95f2"},"event":"buy","time_free":true}
{"type":"track","time":1526178032000,"distinct_id":"\u5c0f\u6b66","properties":{"item_id":23421.0,"item_name":"
New Order Technique 2CD\u8c6a\u534e\u7248 \u6b27\u7248\u884c\u8d27 \u5168\u65b0\u672a\u62c6"}, "event":"view","
time_free":true}
{"type":"track","time":1526215373000,"distinct_id":"\u83e0\u83dc","properties":{"item_id":3442.0,"item_name":"
NUK\u5b89\u629a\u5976\u5634\u5b9d\u5b9d\u9632\u80c0\u6c14\u5b89\u6170\u5976\u5634\u4e73\u80f6\u8fea\u58eb\u5c3c\
u5b89\u7761\u578b"},"event":"view","time_free":true}
{"type":"profile_set","time":1526263297951,"distinct_id":"bug29","properties":{"gender":"\u7537","is_member":
true,"score":131.0},"time_free":true}
{"type":"profile_set","time":1526263297951,"distinct_id":"\u5c0f\u6b66","properties":{"gender":"\u5973","
is_member":false},"time_free":true}
{"type":"item_set","properties":{"name":"yuejz","OrderPaid":12.1},"item_id":"item_id","time":1566022866941,"
item_type":"item_type"}
{"type":"item_set","properties":{"name":"yuejz"},"item_id":"item_id","time":1566022866941,"item_type":"
item_type"}
{"type":"item_set","time":1566023226152,"properties":{"OrderTime":"2019-07-01 12:02:36","OrderPaid":12.1},"
item_id":"item_id","item_type":"item_type"}
{"type":"itpe":"profile_set","time":1526263297951,"distinct_id":"\u5c0f\u6b66","properties":{"gender":"\u5973","
is_member":false},"time_free":true}
将这些数据导入到本地私有部署的环境，
python3 format_importer.py json \
--url ''http://localhost:8106/sa?project=xxx'' \
--path ''./examples/json_data.json'' \
--debug # --debug
也可以将上述参数写入 json.conf
url: http://localhost:8106/sa?project=xxx
path: ./examples/events_and_profiles.json
debug
然后执行
python3 format_importer.py json @./conf/json.conf
2.3.9. 导入 oracle 的数据
注意使用 oracle 导入需要先安装相关库，请运行下面命令来安装 cx_Oracle 并需要确保机器上包含了相关 oracle 客户端程序包。
python3 -m pip install cx_Oracle --upgrade
2.3.9.1. 导入事件
假设有以下 oracle 表描述了上面的示例用户事件 ( 参考代码包下 examples/events.plsql )。
drop table if exists events;
create table events
( user_id varchar(100),
action varchar(100),
time timestamp,
item_id int,
item_name text,
item_cate varchar(100));
insert into events values(''bug29'', ''view'', ''2018-05-12 13:01:11'', 13245, '''', '''');
insert into events values(''bug29'', ''buy'', ''2018-05-12 13:05:03'', 13245, '''', '''');insert into events values('''', ''view'', ''2018-05-13 10:20:32'', 23421, ''New Order Technique 2CD '', '''');
insert into events values('''', ''view'', ''2018-05-13 20:42:53'', 3442, ''NUK'', '''');
将这些数据导入到本地私有部署的环境，以 user_id 作为用户的 id，以 time 作为事件发生的时间，以 action 作为事件名称，只导入 item_id 和
item_name 作为事件属性。最后的 ORDER BY 主要是保证多次查询数据顺序一致，这样假如导入一半失败了，可以使用我们的参数跳过导入成功的行数。
python3 format_importer.py oracle_event \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \
--timestamp_from ''time'' \
--event_from ''action'' \
--user ''root'' \
--password ''pass'' \
--dsn ''127.0.0.1/orcl'' \
--sql ''select user_id, action, time, item_id, item_name from events order by time'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/oracle_event.conf )。
url: http://localhost:8106/sa?project=xxx
distinct_id_from: user_id
event_from: action
timestamp_from: time
user: root
password: pass
dsn: 127.0.0.1/orcl
sql: select user_id, action, time, item_id, item_name from events order by time;
debug
然后执行
python3 format_importer.py oracle_event @./conf/oracle_event.conf
2.3.9.2. 导入用户属性
假设有以下 oracle 表描述了上面的示例用户属性 ( 参考代码包下 examples/profiles.plsql )。
drop table if exists profiles;
create table profiles
( user_id varchar(100),
gender varchar(20),
is_member bool,
score int);
insert into profiles values(''bug29'', '''', true, 131);
insert into profiles values('''', '''', false, null);
将这些数据导入到本地私有部署的环境，以 user_id 作为用户的 id，导入全部用户属性。最后的 ORDER BY 主要是保证多次查询数据顺序一致，这样假如
导入一半失败了，可以使用我们的参数跳过导入成功的行数。
python3 format_importer.py oracle_profile \
--url ''http://localhost:8106/sa?project=xxx'' \
--distinct_id_from ''user_id'' \
--user ''root'' \
--password ''pass'' \
--dsn ''127.0.0.1/orcl \
--sql ''select user_id, gender, is_member, score from profiles order by user_id'' \
--bool_property_list ''is_member'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/oracle_profile.conf )。url: http://localhost:8106/sa?project=xxx
distinct_id_from: user_id
user: root
password: pass
dsn: 127.0.0.1/orcl
sql: select user_id, gender, is_member, score from profiles order by user_id
bool_property_list: is_member
debug
然后执行
python3 format_importer.py oracle_profile @./conf/oracle_profile.conf
2.3.9.3. 导入 item 数据
假设有以下 oracle 表描述了上面的示例用户事件 ( 参考代码包下 examples/events.plsql )。
drop table if exists events;
create table events
( user_id varchar(100),
action varchar(100),
time timestamp,
item_id int,
item_name text,
item_cate varchar(100));
insert into events values(''bug29'', ''view'', ''2018-05-12 13:01:11'', 13245, '''', '''');
insert into events values(''bug29'', ''buy'', ''2018-05-12 13:05:03'', 13245, '''', '''');
insert into events values('''', ''view'', ''2018-05-13 10:20:32'', 23421, ''New Order Technique 2CD '', '''');
insert into events values('''', ''view'', ''2018-05-13 20:42:53'', 3442, ''NUK'', '''');
将这些数据导入到本地私有部署的环境，以数据库中的 item_id 作为item 数据的 item_id，以数据库的 action 作为 item 数据的 item_type，只导入
item_cate 和 item_name 作为事件属性。最后的 ORDER BY 主要是保证多次查询数据顺序一致，这样假如导入一半失败了，可以使用我们的参数跳过导入
成功的行数。
python3 format_importer.py oracle_item \
--url ''http://localhost:8106/sa?project=xxx'' \
--item_id ''item_id'' \
--item_type ''action'' \
--user ''root'' \
--password ''pass'' \
--dsn ''127.0.0.1/orcl'' \
--sql ''select item_id, action, item_cate, item_name from events order by time'' \
--debug # --debug
也可以将上述参数写入配置文件中 ( 参考代码包下 conf/oracle_item.conf )。
url: http://localhost:8106/sa?project=xxx
item_id: user_id
item_type: action
user: root
password: pass
dsn: 127.0.0.1/orcl
sql: select item_id, action, item_cate, item_name from events order by time;
debug
然后执行
python3 format_importer.py oracle_item @./conf/oracle_item.conf
2.4. 使用建议1. 先选用部分数据，增加 --debug 选项测试通过后再正式导入。增加 --debug 后进入调试模式，对于每条数据，若成功则发送的数据打到标准输出上，否
则会打印出错信息。执行完毕之后打印读取多少条，出错多少条。
导入 csv / nginx 日志的时候，可以先用 head -1000 file_name > test_file 的方式先导入一部分数据到测试文件，然后使用测试文件导入
导入 mysql 数据的时候，可以在查询语句后面加上 LIMIT 1000 然后测试导入
2. 运行时在 format_importer 目录下会产生日志, 日志名为 format_importer.log，包含比输出更全的调试信息，如果增加 --debug 后屏幕上输出比较多，
可以查看日志查找出错信息和调试信息。
3. 由于参数比较复杂，建议 使用配置文件的方式传递参数，具体配置文件样例可以解压后查看 conf 目录。
4. 对于 csv 日志导入，需要确保日志文件是有效的 csv 格式，建议先阅读 csv 转义 相关的内容。
5. 由于 nginx 的日志格式所限，导入的 property 的名字可能看起来并不具有可读性，比如 request_param_action 这样的，强烈建议使用
property_list_cnames 来转化成可读的属性名。
6. 对于 mysql 导入，如果 sql 语句写的比较长的时候，容易出现 sql 传递给程序后 shell 转义错误的问题，建议出错时查看在 format_impoter 目录下的日
志，会在启动后第一条日志里面写上传递的参数，请仔细查看和传递的 sql 是否一致。另外建议如果 sql 比较长，建议使用 --filename 的方式写入文件传
递。
7. 对于 mysql 导入，如果 sql 语句是两个表的 join, 那么指定列名的时候需要指定的是别名或者列名，而不是<表名>.<列名>。详细解释参见 用 mysql 将两张
表 join 起来导入，明明有数据为什么提示我 distinct_id / timestamp / event 为空。
8. 如果需要更高效导入，建议先使用 --output_file 来导出到日志文件中去，然后使用 BatchImporter 或者 HDFSImporter导入到集群中去。
2.5. 使用方法详解
2.5.1. 子命令说明
子命令就是跟在执行脚本后的第一个参数，比如 2.1 中执行
python3 format_importer.py csv_event \
--url ''http://localhost:8106/sa?project=xxx'' \
--event_default ''UserBuy'' \
--distinct_id_from ''user'' \
--timestamp_from ''buy_time'' \
--filename ''buy.csv''
使用的子命令是 csv_event，表示 csv 格式数据导入为event。目前支持以下7种子命令。
自命令名称 解释
csv_profile 将 csv 格式文件导入, 导入 profile
csv_event 将 csv 格式文件导入, 导入 event
csv_item 将 csv 格式文件导入, 导入 item
mysql_profile 提供 sql，将 mysql 的数据导入, 导入 profile
mysql_event 提供 sql，将 mysql 的数据导入, 导入 event
mysql_item 提供 sql，将 mysql 的数据导入, 导入 item
nginx_profile 将 Nginx 日志导入, 导入 profile
nginx_event 将 Nginx 日志导入, 导入 event
nginx_item 将 Nginx 日志导入, 导入 item
json 将 Json 日志导入，注意日志不区分 event、profile、item
oracle_profile 提供 sql，将 oracle 的数据导入, 导入 profile
oracle_event 提供 sql，将 oracle 的数据导入, 导入 event
oracle_item 提供 sql，将 oracle 的数据导入, 导入 item
如果想看单个子命令支持哪些参数，可以在子命令之后加 -h，将获取所有的参数和说明，如
python3 format_importer.py csv_event -h
python3 format_importer.py json -h
2.5.2. 从配置文件中导入format_importer 支持从配置文件中读取参数，使用方法是在子命令之后增加 @<配置文件路径>。下载后的源码包里面即包含了默认的几个配置，在 conf 目
录下，可以修改后使用配置文件导入。
举例想导入 csv 的 event，可以修改 conf/csv_event.conf，然后执行
python3 format_importer.py csv_event @./conf/csv_event.conf
2.5.3. 公共参数
通用的公共参数包括：
参数名 别名 是否必填 解释
--url -l 和 output_file 选一个必填 发送数据的 url，获取方式在 2.1 节已经进行过描述。
--output_file -O 和 url 选一个必填 输出的文件名，输出每行是一个符合格式的json。
--project -j 否 指定的project名，默认是default
--skip_cnt -c 否 第一次运行请忽略，如果运行失败，需要跳过成功的那几行，这个就是指定跳过几行的。
--debug -D 否 如果指定了就是使用debug模式，不会导入数据，只在stdout显示数据，参见调试模式
--quit_on_error -Q 否 如果选中，则出现一条错误日志就会退出
此外，导入 csv 日志 / nginx 日志 / mysql 数据时需要区分是导入 event 还是 profile，二者有不同的公共参数；导入 json 日志时，只支持设置如上的公共
参数。
2.5.4. event/profile/item 公共参数
对于profile, 导入需要指定哪一列作为 distinct_id.
对于 event，除了指定 distinct_id，还需要指定 event 和 timestamp。指定 event 目前支持两种方法，一种将所有的数据都认为是同一个 event，另一种是
指定哪一列作为 event。同样指定 timestamp 目前支持两种方法，一种将所有数据都认为是同一个 timestamp，另一种是指定哪一列作为 timestamp。
对应 item，必须指定 item_type 和 item_id。
参数名 别 导入 导入 event 导入 解释
名 profile 是 是否需要 item 是否
否需要 需要
-- -df 必填 必填 不可以填 从哪个字段作为 distinct_id，如果指定，则每条数据算作对应字段的用户的行为。
distinct_id_
from
--is_login 选填 选填 不可以填 distinct_id 是否是 login id，默认不是；注：导入 json 格式数据不支持此参数，如需使用请在
json 数据中添加 "$is_login_id" 属性。
-- -ef 不可以填 和 不可以填 哪个字段作为 event 名，如果指定，则每条数据的事件名为对应字段的值。
event_from event_default
选一个必填
-- -ed 不可以填 和 event_from 不可以填 默认的 event 名，如果指定，则将所有数据都算作这个 event 的。
event_defau 选一个必填
lt
-- -tf 不可以填 选填 不可以填 哪个字段作为 time, 如果指定，则每条数据对应的时间为对应字段的值。
timestamp_
from
-- -td 不可以填 选填 不可以填 默认的 timestamp, 如果指定，则将所有数据都算作这个时间的事件。
timestamp_
default
-- -tf 不可以填 选填 不可以填 和 timestamp_from 一起使用，如果指定，并 timestamp_from 对应的字段是个字符串，可以通过
timestamp_ 这种方式指定时间格式。默认是%Y-%m-%d %H:%M:%S。
format
-- 不可以填 不可以填 必填 导入 item 数据时，指定 item_type 字段的值
item_type
--item_id 不可以填 不可以填 必填 导入 item 数据时，指定 item_id 字段的值
2.5.5. 导入 csv 格式的其他参数
参数名 别 是否必填 解释名
-- -f 是 csv文件路径
filename
-- -pl 否 用逗号分割选取的 property, 举例-p name,time将会将 name 和 time 两列作为 property 导入。如果不填写则表示全部作为
property_li property 导入。
st
-- -i 否 对应的列将不会做自动类型判断，举例--skip_identify name,id将会将 name 和 id 不做类型判断，完全作为 string 导入如果
skip_identi 不填写则表示全部的选中列都会自动做类型判断。
fy
-- 否 指定某些值为空，比如指定 --ignore_value null 则所有的null都被认为是空值
ignore_val
ue
-- -ac 否 是否添加中文名，只对 event 有效. 如果 csv 的表头是中文，程序会将对应的 property 名改为对应的拼音。这时，如果将
add_cname add_cname 选中，会自动再程序的最后把中英文的映射关系填上去，这样在Ui上看到的对应 property 就是中文的了。
--web_url -w 如果选择 web 访问的 url ，单机版类似 http://localhost:8007/, cloud 版类似 http://xxx.cloud.sensorsdata.cn。
add_cname 则
必填
-- -u 如果选择 web 登录用户名。
username add_cname 则
必填
-- -p 如果选择 web 登录密码。
password add_cname 则
必填
-- 否 csv文件的列分隔符，默认为'',''，只接受单字符参数, 也可以传\ + ascii的数字，比如\9表示是\t
csv_delimi
ter
-- 否 csv文件的引用字符，用于指定csv字符串的开始和结尾，默认为''"''，只接受单字符参数, 也可以传\ + ascii的数字，比如\9表示是\t
csv_quote
char
-- 否 csv文件预读行数，预读用于判断列的类型，默认为-1，即预读整个文件。注意如果数据分布不均（比如前几行某个字段没有但是后
csv_prefet 面有）不要加这个参数
ch_lines
-- 否 设置 csv 文件编码格式，默认为 utf-8
file_encod
ing
2.5.6. 导入 nginx 日志的其他参数
参 别 是 解释
数 名 否
名 必
填
-- -f 是 nginx 日志文件路径
filena
me
-- -F 是 nginx 日志配置，类似''"$remote_addr" "$time_local" "$http_refer" "$status"''。
log_fo
rmat
-- -pl 是 用逗号分割选取的 property, 举例--property_list http_refer,status将会将http_refer和status两列作为 property 导入。
prope
rty_list
-- -i 否 对应的列将不会做自动类型判断，举例--skip_identify request_user,status将会将 request_user, status 不做类型判断，完全作为
skip_i string 导入。如果不填写则表示全部的选中列都会自动做类型判断。
dentify
-- -uf 否 对应的列将作为url解析，用逗号分割。解析后会生成 <>_<>这样命名的property,解析内容包括netloc, path, query, param_<参数名>。举例对于
url_fie $my_url字段值为http://www.abc.com/path/to/mine?k1=v1&k2=2,会解析为{" my_url_netloc": "www.abc.com"," my_url_pa
lds th": "/path/to/mine", " my_url_query":"k1=v1&k2=v", " my_url_param_k1": "v1"," my_url_param_k2":2}。注意可以再property_list
配置这些字段。默认是"http_referer"。
-- -fp 否 过滤对应的 path ，可多选。这里的 path 取的是 $request的path。支持正则。举例 --filter_path ''.*\.gif'' --filter_path ''
filter_ /index\.html'' 将过滤对 gif 的请求和 index 的请求。
path
-- -if 否 只对 event 有效, 哪个字段作为 ip, 如果指定，则每条数据对应的 ip 为对应字段的值, 默认是$remote_addr
ip_from
-- 否 指定某些值为空，比如指定 --ignore_value null 则所有的null都被认为是空值
ignore_value
-- 否 用逗号分割property的对应名称, 需要和--property_list一一对应
prope
rty_lis
t_cna
mes
2.5.7. 导入 mysql 数据的其他参数
参数名 别名 是否必填 解释
--user -u 是 mysql 的 username
--password -p 是 mysql 的 password
--host -i 是 mysql 的地址
--port -P 是 mysql 的端口号
--db -d 是 mysql 对应的 db 名，一次只能指定一个
--sql -q 和 filename 选一个必填 查询语句，建议加 order by 等方式保证多次查询结果顺序一致。
--filename -f 和 sql 选一个必填 查询语句所在的文件路径，建议加 order by 等方式保证多次查询结果顺序一致。
--bool_property_list -bp 否 逗号分割的bool类型属性列表，会将对应的属性值为1的转化为true，0转化为false
--case_sensitive -cs 否 导入的属性名是否是大小写敏感，注意如果大小写不敏感会全部转化为大写，默认为true
2.5.8. 导入 json 日志的其他参数
参数名 别名 是否必填 解释
--path -p 是 日志的文件/目录路径
注意导入 json 日志，如果传递了日志目录，那么会遍历该目录下一级的所有的文件，并且按照字母顺序导入。本参数不支持嵌套目录。
2.5.9. 导入 oracle 数据的其他参数
参数名 别名 是否必填 解释
--user -u 是 oracle 的 username
--password -p 是 oracle 的 password
--dsn -dsn 是 oracle 的 dsn
--sql -q 和 filename 选一个必填 查询语句，建议加 order by 等方式保证多次查询结果顺序一致。
--filename -f 和 sql 选一个必填 查询语句所在的文件路径，建议加 order by 等方式保证多次查询结果顺序一致。
--bool_property_list -bp 否 逗号分割的 bool 类型属性列表，会将对应的属性值为 1 的转化为 true，0 转化为 false
--case_sensitive -cs 否 导入的属性名是否是大小写敏感，注意如果大小写不敏感会全部转化为大写，默认为 false
2.6. 常见问题
2.6.1. csv 的表头是中文是否可以支持
根据我们在 数据格式 里面的说明，property 的名称是不可以包含中文的，但是可以设置 property 在 UI 上显示为对应的中文名。通过配置 --add_cname
即可自动完成这一过程。使用上面的例子，buy.csv 格式如下:
,,id,,
,2015-01-20 10:35:22,13579, ,
,2015-07-13 23:12:03,24680,ZINO 3DBBSPF30PA++ 3ml,
,2015-04-03 20:30:01,31415,New Order Technique 2CD ,
导入参数如下：
python3 format_importer.py csv_event \
--url ''http://localhost:8006/sa?project=xxx'' \
--event_default ''UserBuy'' \--distinct_id_from '''' \
--timestamp_from '''' \
--filename ''buy.csv'' \
--add_cname \
--web_url ''http://localhost:8007'' \
--username admin \
--password password
注意在不同的平台上对编码要求不同，需要保证默认编码和文件编码一致，具体请参考 windows下使用说明。
2.6.2. 如何配置 nginx 可以过滤掉静态文件？
假设 nginx 日志中包含了对 gif 文件, css 文件和 js 文件的请求，这些请求希望过滤掉，可以使用 --filter_path 来过滤。
python3 format_importer.py nginx_event \
--filter_path ''.*\.gif'' \
--filter_path ''.*\.css'' \
--filter_path ''.*\.js'' \
#
2.6.3. 导入了一半出错了怎么办？
默认的情况下，出现解析错误的数据，导入工具会在运行过程中对错误打印错误原因和错误的行数，然后丢弃错误数据继续处理。打印日志类似这样的:
2015-10-28 14:58:52,020 808 WARNING failed to parse line 12
2015-10-28 14:58:52,021 809 WARNING Traceback (most recent call last):
File "format_importer.py", line 804, in main
sa.track(distinct_id, event, properties)
File "/Users/padme/git/sa2/tools/format_importer/sensorsanalytics/sdk.py", line 118, in track
data = self._normalize_data(data)
File "/Users/padme/git/sa2/tools/format_importer/sensorsanalytics/sdk.py", line 149, in _normalize_data
raise SensorsAnalyticsIllegalDataException("property [distinct_id] must not be empty")
sensorsanalytics.sdk.SensorsAnalyticsIllegalDataException: property [distinct_id] must not be empty
在运行结束的时候会打印读取(total_read)了多少行，写入(total_write)多少行，出错(error)了多少行，跳过(skip)了多少行，类似这样:
2015-10-28 14:58:52,023 618 INFO end import nginx
2015-10-28 14:58:52,024 838 INFO counter = {''error'': 3, ''skip'': 0, ''total'': 300, ''total_read'': 100,
''total_write'': 97}.
如果希望能够出错就提示，可以增加选项 --quit_on_error，这样的话出错了的日志如下：
2015-10-28 14:58:29,499 808 WARNING failed to parse line 12
2015-10-28 14:58:29,502 809 WARNING Traceback (most recent call last):
File "format_importer.py", line 804, in main
sa.track(distinct_id, event, properties)
File "/Users/padme/git/sa2/tools/format_importer/sensorsanalytics/sdk.py", line 118, in track
data = self._normalize_data(data)
File "/Users/padme/git/sa2/tools/format_importer/sensorsanalytics/sdk.py", line 149, in _normalize_data
raise SensorsAnalyticsIllegalDataException("property [distinct_id] must not be empty")
sensorsanalytics.sdk.SensorsAnalyticsIllegalDataException: property [distinct_id] must not be empty
2015-10-28 14:58:29,502 618 INFO end import nginx
2015-10-28 14:58:29,502 835 ERROR failed to import, please fix it and run with[--skip_cnt 11] again!
注意下方提示，说明已经成功导入了11行，修复第12行的数据后在之前的命令上再加上参数 --skip_cnt 11 即可。
需要特别说明的是，对于 mysql，为了防止数据错误后不可恢复的问题，请务必保证 查询sql多次调用结果一致，即：
没有新数据在写入，比如通过增加 WHERE 保证只导入历史数据。
查询结果增加排序选项保证顺序一致，比如增加 ORDER BY id。
2.6.3.1. 用 mysql 将两张表 join 起来导入，明明有数据为什么提示我 distinct_id / timestamp / event 为空？注意如果使用两个表 join，列名要么是唯一的，要么取别名。这里的列名一方面是表示使用 distinct_id_from, timestamp_from, event_from 的参数，另一
方面也是导入后 property 的名字。
举例，sql 如下:
SELECT a.uid, a.event, a.time, b.property1, b.property2
FROM a JOIN b ON a.action_id = b.action_id
那么运行参数需要指定为
--distinct_id_from ''uid'' \
--timestamp_from ''time'' \
--event_from ''event''
导入的 property 的名字也分别是(property1, property2) 而不是(b.property1, b.property2)。如
果列名不是唯一的，另一种方法是取别名. 举例sql如下:
SELECT a.u AS uid, a.e AS event, a.t AS time, b.property AS property1, a.property AS property2
FROM a JOIN b ON a.action_id = b.action_id
那么运行的参数指定为:
--distinct_id_from ''uid'' \
--timestamp_from ''time'' \
--event_from ''event''
导入的 property 的名字也分别是(property1, property2)。
2.6.3.2. 用 mysql 导入的时候，如何将数值转化成文本/文本转化成数值导入？
mysql 的 CAST 方法支持类型转化。
举例，mysql 中有个类型为 int 的列 property1 和一个类型为 varchar(10) 的列为 property2，可以使用 sql:
SELECT CAST(property1 AS CHAR(10)) AS property1, CAST(property2 AS SIGNED) AS property2 FROM test_table;
将 property1 的值转化成 10 个字符长的文本，将 property2 的值转化为数值。
2.6.3.3. 如何导入其他Project
如果没有显示指定 project，则默认导入默认 project (default)。
可以通过 --url 里面包含 project=<project_name> 来指定project 名，也可以通过 --project 参数来指定。如果同时指定则采用 --project 的参数。
注意，如果 --url 的值是通过右上角“账号” -> “数据接入” -> “复制数据接收地址” 来获取的话，则复制的接口里面自带 project 参数，不需要额外指定。此
外，如果是导入 json 日志，可以在 json 中增加 "project":"project名称" 来使用一份数据导入多个 project。日志里面的 project 字段优先级高于参数。
2.6.3.4. csv如何转义
csv是用逗号分割的文件格式，如果某一列的内容中包含逗号，需要用双引号分割开，否则 format importer 将会报错。举例，csv 文件内容如下:
col1,col2,col3
a,b,c,d
运行时将会报错:
csv error near line 1: content has 1 more fields than header即提示内容的列数比头部的列数多一列。 正确的做法是加上双引号：
col1,col2,col3
a,"b,c",d
将会被识别为:
col1 col2 col3
a b,c d
注意双引号可以跨行。举例，csv文件内容如下：
col1,col2,col3
a,"b,c
d,e",f
将会被识别为:
col1 col2 col3
a b,c,d,e f
因此如果某一列以双引号开头，那么csv会一直找到下一个双引号结尾。如果两个双引号直接的字符过多，会报错列超长：
_csv.Error: field larger than field limit (131072)
解决方法有两个，一个是可以通过 --csv_quotechar 参数替换 csv 默认的字符串边界符号，需要保证这个符号没有出现过。 另外就是对双引号转义，需要
把一个双引号变成两个，并且对本列用双引号引住。举例，csv文件内容如下:
col1,col2,col3
a,"""b",c
将会识别为
col1 col2 col3
a "b c
2.6.3.5. 对于 json 格式的日志，使用 FormatImporter 导入，和使用 LogAgent/BatchImporter导入有什么区别？
1. LogAgent 实时流式将日志内容导入，如果日志在不断更新，建议使用 LogAgent 导入. 而 FormatImporter 和 BatchImporter 都是一次性导入。
2. BatchImporter 在三者中导入效率最高，但是只能在部署神策分析的机器上使用。 FormatImporter , LogAgent 可以在任意机器上运行。
2.6.3.6. windows下使用说明
在 windows 下使用 FormatImporter 时，由于终端的语法不同，默认编码不同，有以下几个注意事项：
1. 尽量使用配置文件传递参数，而不是命令行传递，避免命令转义。注意上述示例中的命令都是基于 unix 操作系统，如果直接在 windows 下面运行可能会
出现语法错误或转义。
2. csv 文件默认支持 utf-8 编码，如果出现编码错误，可以先查看文件编码格式，然后使用 --file_encoding 命令设置编码格式
3. 如果需要在 windows 下访问 mysql / oracle，需要对编码做特殊处理，具体处理方式请咨询神策技术支持同学。
2.6.3.7. 导入限制
导入数据时，formatImporter 导入本身没有数据量上限，但是如果导入数据较大时，速度较慢，大约 1 分钟导入 500~700 条左右，且导入的速度和网络稳定
性有关，如果导入超时，可以使用内网数据接收地址尝试下是否可以HdfsImporter.HdfsImporter v1.13
在使用前，请先阅读数据模型和数据格式的介绍。
1. HdfsImporter 概述
HdfsImporter 与 BatchImporter 一样用于将历史数据或外部数据导入神策分析。
2. 运行环境
HdfsImporter 仅可在神策分析集群版使用，且只能运行在神策分析集群的 Hadoop 环境中。
3. 经典使用方法
3.1. 一次新启动的导入步骤如下：
1. 将数据置于神策分析集群上的 HDFS 中。例如 HDFS 集群 /data/input 目录，其中包含文件data01、data02、data03等文件，文件内容为每行一
个符合 数据格式 的 Json。
2. 切换到 sa_cluster 账户：
sudo su - sa_cluster
3. 请确定 HDFS 上数据不再进行修改（增删修改文件）后，运行 HdfsImporter。
3.2. 使用方式
1. 先检查数据正确性，但不进行真的数据导入：开始 debug 模式，数据只会以 `JSON` 文本的方式输出到相应的 HDFS 目录下，并且不会真正的导
入到神策系统当中。
hdfs_importer \
--path /data/input \
--project default \
--debug
2. 检查无误后，进行真正的数据导入 ：
hdfs_importer \
--path /data/input \
--project default
3.3. 备注
1.13 版本以前，由于没有简略命令 hdfs_importer , 需使用 sh $SENSORS_ANALYTICS_HOME/tools/hdfs_importer/bin/hdfs_importer.sh 代
替
导入后清理数据较复杂，请检查好再操作。对同一份数据多次运行导入会导致数据重复。
path 可以是一个包含子目录的数据目录。
HdfsImporter 执行成功之后，数据大约会在1分钟之后被查询到。
hdfs 操作命令文档参考
4. 配置项说明
列出所有配置项：
hdfs_importer --help
参数 必 说明 默
填 认
值
path 是 需要导入的数据所在的 HDFS 路径。project 否 期望导入的 project 名称，不指定的则导入到 default。导入数据中的 project 字段会失效，以此参数指定为准。 defa
ult
all_data_without_trac 否 是否所有数据（包括之前各种类型导入）都不包含 track_signup 类型数据。若所有导入数据均不包含 track_signup 类型
k_signup 数据，添加这个选项可以提高导入速度。注意，导入项目中使用过用户关联功能则不能使用该选项。
split_max_size_mb 否 MapReduce 每个 Mapper 处理分片的最大值。该值会影响 Mapper 数量。 512
job_queue_name 否 MapReduce Job 的队列名。
split_reduce_size_mb 否 MapReduce 每个 Reducer 处理的数据量大小。该值会影响 Reducer 的数据。Reducer 个数 = 输入的总数据量 / 2048
split_reduce_size_mb 。
mapper_max_memor 否 MapReduce 每个 Mapper 使用的内存最大值。 1024
y_size_mb
reduce_max_memory 否 MapReduce 每个 Reducer 使用的内存最大值。 2048
_size_mb
reduce_output_file_si 否 MapReduce 每个 Reducer 输出的文件最大值。 256
ze_mb
shuffle_partition_spli 否 Shuffer 时，每个 Mapper 切分 partition 的大小，一般用来调整数据分布不均匀 500
t_size 000
expired_record_filter 否 允许导入的数据时间区间截至未来的小时数，默认为 1，即超过未来 1 小时的数据将被过滤。 1
_after_hour
expired_record_filter 否 允许导入的数据时间区间向前的小时数，默认为 17520，即超过 2 年以前的数据将被过滤。 175
_before_hour 20
user_define_job_name 否 允许自定义 job name，比如在 HdfsImpoter-12345-[your_name] 中，your_name 是自定义的部分 无
debug 否 开始 debug 模式，数据只会以 JSON 文本的方式输出到相应的 HDFS 目录下，并且不会真正的导入到神策系统当中。
disable_import_succ 否 禁止重复导入已成功过的导入路径 false
eeded_source_path
write_import_info 否 在命令执行路径生成 import info 文件 false
一个复杂的例子：
hdfs_importer \
--path /data/input \
--project test_project \
--all_data_without_track_signup \
--split_max_size_mb 128 \
--job_queue_name data_import_queue \
--split_reduce_size_mb 2048 \
--reduce_max_memory_size_mb 2048 \
--reduce_output_file_size_mb 256 \
--disable_import_succeeded_source_path
5. 查询导入历史
自1.13 版本，支持查询 hdfs importer 导入历史, 查询结果以 JSON 格式输出。
使用方式 ：
hdfs_importer list \
--project default
列出所有配置项 ：
hdfs_importer list --help
参数 必填 说明 默认值
project_name 否 project name, 可指定按照 project name 查询导入任务记录
session_id 否 session id, 可指定按照 session id 查询导入任务记录
job_name 否 job name，可指定按照 job_name 查询导入任务记录。这里的 job_name 为导入任务中的 user_define_job_name
status 否 hdfs importer 导入任务的状态，status 值可为 WAITING，RUNNING，SUCCESS，FAILEDstart_time 否 start time, 可查询startTime比传入的指定时间晚的导入记录， 格式%Y-%m-%d %H:%M:%S
max_num 否 recent N times，可指定最近N次导入记录 10
dump 否 查询结果输出到指定的FILENAME；如果没有指定，则会输出到控制台
full 否 指定后则查看所有任务，否则同一个session_id只查看最新的任务 False
例如，查询按小时的例行导入任务：
hdfs_importer list \
--project_name test_project \
--job_name hourly_import \
--status SUCCESS \
--start_time ''2018-08-30 00:00:00'' \
--max_num 2 \
--dump /data/work/list_output_file1
输出到文件中的结果为：
[
{
"id": 12,
"session_id": 320,
"job_name": "hourly_import",
"scheduler_job_record_id": null,
"import_path": "/sa/tmp/hdfsImport",
"parameters": "{\"path\":\"/sa/tmp/hdfsImport\",\"project\":\"test_project\",\"
user_define_job_name\":\"hourly_import\"}",
"start_time": "2018-09-11 18:46:50",
"end_time": "2018-09-11 18:49:46",
"counter_info": "{\"event_read_count\":252600,\"event_import_count\":252600,\"
event_skipped_count\":0,\"profile_read_count\":10104,\"profile_import_count\":10104,\"
profile_skipped_count\":0}",
"log_path": "/data/sa_cluster/logs/tools/hdfsimporter/hdfsimporter-43c7d4ea-0b14-48f6-8b03-
764178e927ae.log",
"event_job_id": "job_1536029076029_3074",
"profile_job_id": "job_1536029076029_3077",
"event_job_status": "SUCCESS",
"profile_job_status": "SUCCESS",
"event_data_load_status": "SUCCESS",
"project_name": "test_project"
},
{
"id": 10,
"session_id": 317,
"job_name": "hourly_import",
"scheduler_job_record_id": null,
"import_path": "/sa/tmp/hdfsImport",
"parameters": "{\"path\":\"/sa/tmp/hdfsImport\",\"project\":\"test_project\",\"
user_define_job_name\":\"hourly_import\"}",
"start_time": "2018-09-11 10:23:20",
"end_time": "2018-09-11 10:26:21",
"counter_info": "{\"event_read_count\":252600,\"event_import_count\":252600,\"
event_skipped_count\":0,\"profile_read_count\":10104,\"profile_import_count\":10104,\"
profile_skipped_count\":0}",
"log_path": "/data/sa_cluster/logs/tools/hdfsimporter/hdfsimporter-67a00f94-67d8-415e-a004-
c9ca82a17a2a.log",
"event_job_id": "job_1536029076029_3044",
"profile_job_id": null,
"event_job_status": "SUCCESS",
"profile_job_status": null,
"event_data_load_status": "SUCCESS",
"project_name": "test_project"
}
]
再如，查询指定 session_id 的所有导入任务状态：hdfs_importer list \
--session_id 306 \
--full
输出到控制台的结果为
[
{
"id": 8,
"session_id": 306,
"job_name": "hourly_import",
"scheduler_job_record_id": null,
"import_path": "/sa/tmp/hdfsImport",
"parameters": "{\"session\":\"HdfsImport-306\"}",
"start_time": "2018-09-10 19:02:08",
"end_time": "2018-09-10 19:02:46",
"counter_info": "{\"profile_read_count\":10104,\"profile_import_count\":10104,\"
profile_skipped_count\":0}",
"log_path": "/data/sa_cluster/logs/tools/hdfsimporter/hdfsimporter-0634112a-6b90-40db-a26d-
5492dbc7b995.log",
"event_job_id": null,
"profile_job_id": "job_1536029076029_3084",
"event_job_status": null,
"profile_job_status": "SUCCESS",
"event_data_load_status": null,
"project_name": "test_project"
},
{
"id": 7,
"session_id": 306,
"job_name": "hourly_import",
"scheduler_job_record_id": null,
"import_path": "/sa/tmp/hdfsImport",
"parameters": "{\"path\":\"/sa/tmp/hdfsImport\",\"project\":\"test_project\",\"
user_define_job_name\":\"hourly_import\"}",
"start_time": "2018-09-10 18:58:45",
"end_time": "2018-09-10 19:01:10",
"counter_info": "{\"event_read_count\":252600,\"event_import_count\":252600,\"
event_skipped_count\":0}",
"log_path": "/data/sa_cluster/logs/tools/hdfsimporter/hdfsimporter-c7514335-5a55-42b8-bfd3-
0ad7a27ec1a3.log",
"event_job_id": "job_1536029076029_3082",
"profile_job_id": "job_1536029076029_3083",
"event_job_status": "SUCCESS",
"profile_job_status": "FAILED",
"event_data_load_status": "SUCCESS",
"project_name": "test_project"
}
]
6. 更新日志
6.1. 2018-09-13 (SA 版本号：1.13)
1. 导入配置项中增加参数 disable_import_succeeded_source_path
2. 导入配置项中增加参数 write_import_info
3. 可使用简略的 hdfs_importer 命令替换 sh $SENSORS_ANALYTICS_HOME/tools/hdfs_importer/bin/hdfs_importer.sh
4. 新增查询导入历史子命令
6.2. 2017-11-29 (SA 版本号：1.10.3329)
1. 支持自定义 job_name 参数： user_define_job_name
6.3. 2017-07-10 (SA 版本号：1.7.2628)1. 新增 Mapper 内存参数 mapper_max_memory_size_mb
2. 支持用户自定义 InputFormat，详情请参考 github ：HDFSImporter 自定义 InputFormat
6.4. 2017-07-04 (SA 版本号：1.7.2614)
1. 支持用户自定义预处理模块，详情请参考 github ：HDFSImporter 预处理模块
2. 新增 debug 模式LogAgent.LogAgent v1.13
在使用前，请先阅读 数据模型 和 数据格式 的介绍。
1. LogAgent 概述
LogAgent 是用于将 后端数据实时 导入到神策分析的工具，一般运行在生产日志的服务器上。
几个应用场景举例：
我的程序不方便嵌入神策分析的 SDK，但又想将程序输出的数据导入神策分析；
我希望在本地生成神策分析的导入数据，并在本地保留完整的副本；
我不想自己控制数据发送进度，但又希望发送的数据不重不漏；
这时就可以考虑使用 LogAgent 来进行数据导入。
LogAgent 所做的事情非常简单，即按指定规则 tail 目录下的文件：
若发现新数据，将数据简单格式校验并打包发送到神策分析；
若无新数据，等待一段时间再查看是否有新数据；
LogAgent 启动时，会向神策分析询问本地目录文件的发送进度，以实现断点续传。
2. 下载 LogAgent
当前最新版本：20191227
LogAgent 部署包: http://download.sensorsdata.cn/release/logagent/logagent_20191227.tgz
3. 部署 LogAgent
Logagent 即支持在 Linux 环境下部署，也支持在 windows 环境下部署，windows 环境下部署时，需要注意文件编码问题，具体注意事项参考本文的 4.5
节。
下面以 Linux 环境为例说明 LogAgent 的部署方法。
1. 下载 LogAgent 部署包和解压：
wget http://download.sensorsdata.cn/release/logagent/logagent_20190605.tgz
tar zxvf logagent_20191227.tgz
cd logagent
2. 检查运行环境（至少 Java 8 以上）：
bin/check-java
如果提示 Can''t find java ，请指定 JAVA_HOME 环境变量 或 直接用附带的脚本（仅适用于 Linux 环境）安装绿色 JRE 环境（自动解压到 LogAgent 所在
目录，不影响系统下其他 Java 环境）：
bin/install-jre
3. 编辑配置文件：
可参考 LogAgent 场景使用示例 和 logagent.conf 中对每个配置项的说明；
4. 检查配置文件：
bin/logagent --show_conf
输出类似如下的信息：
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent version: SensorsAnalytics LogAgent_20170922
17/09/22 15:16:27 INFO logagent.LogAgentMain: Use FQDN as LogAgentID
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent ID: test01.sa
17/09/22 15:16:27 INFO logagent.LogAgentMain: Source config, path: ''/home/work/data'', pattern: ''service_log.*''17/09/22 15:16:27 INFO logagent.LogAgentMain: Service Uri: http://10.10.90.131:8106/log_agent
17/09/22 15:16:27 INFO logagent.LogAgentMain: Sender Type: BatchSender
17/09/22 15:16:27 INFO logagent.LogAgentMain: Pid file: /home/work/logagent/logagent.pid
若有多台机器部署 LogAgent，需要确保在不同机器上 LogAgent ID 取值不同（上面示例中是 test01.sa），服务端记录各机器的进度，以
LogAgent ID 区分不同机器；
5. 启动 LogAgent：
可以通过执行以下命令在后端执行 LogAgent：
nohup bin/logagent >/dev/null 2>&1 &
出现步骤 4 中的 pid 文件（步骤 4 输出样例最后一行 Pid file）则说明加载配置启动成功；
若未成功启动，可以查看 log 目录下的日志排查问题，或者直接在前端启动 LogAgent 观察是否有错误输出：
bin/logagent
6. 一台机器启动多个 LogAgent：
一个 LogAgent 程序目录仅能启动一个 LogAgent 进程实例；若需要启动多个 LogAgent，请将 LogAgent 部署到不同目录分别启动即可。
7. 监控 LogAgent：
LogAgent 启动后会在程序目录下生成一个 logagent.pid 文件，记录了进程的 pid 号，如果 LogAgent 需要常驻，建议自行对该进程做监控。
8. 关闭 LogAgent：
在 LogAgent 目录下执行以下命令，即 kill 进程即可：
kill $(cat logagent.pid)
4. 常见问题
4.1. 文件读取顺序
LogAgent 读取的文件列表由 path 目录下：pattern 所匹配的文件 和 real_time_file_name 指定的文件（若有配置）组成。其他文件将被忽略，这意味着
real_time_file_name （即实时文件）改名后需要符合 pattern 的匹配规则;
LogAgent 会对指定目录下所有规则匹配 pattern 的文件 按字典序排序，依次读取;
real_time_file_name（若有配置）总是被放在文件列表的最后，即认为其是最新的文件;
4.2. 读取文件流程
假设目录 path 下有如下文件：
service.log.20160817
service.log.20160818
service.log.20160819
1. 当一个文件例如 service.log.20160818 读取到末尾时，刷新目录文件列表，若当前正在读取的文件 service.log.20160818 不是文件列表中最后一
个文件，即认为有下一个时间点的文件如 service.log.20160819，那么标记当前文件 service.log.20160818 已经结束（即该文件不再继续写
入）。
2. 再次读取当前文件，若仍然没有读到数据，关闭当前文件 service.log.20160818，并开始从头读取下一个时间点的文件 service.log.20160819。
注意：当切换到读取 service.log.20160819 后，任何 字典序 位于 service.log.20160819 之前的数据都不会再被读取。
4.3. 不发送数据排查
导致数据不能正常读取发送可能有多种原因，请按如下步骤检查：
1. LogAgent 目录下的 log 目录中的 logagent.log 是否有报错信息。错误可能是数据格式问题、网络问题等。其中有问题的数据会被 LogAgent 过滤
而不会被导入，并记录在 log 目录下的 invalid_records 文件里；
2. 期望被读取的文件是否匹配配置中的 pattern 。不符合 pattern 的文件不会被 LogAgent 扫描；
3. 期望读取的文件在文件列表中是否位于当前进度之前。例如当前目录下有下列文件：data.2016090120
data.2016090121
假设当前 LogAgent 正在读取 data.2016090121。
a. 新增一个文件 data.20160901，不会被读取，因为按字典序排序目录下的文件，data.20160901 在 data.2016090121 之前；
b. 在 data.2016090120 后面追加写入，不会被读取，因为 LogAgent 不会读取当前读取文件 data.2016090121 之前文件的数据。
4. 删除或截断（truncate）正在读取的文件。不应当删除或截断 LogAgent 正在读取的文件（4.3 节可以看到当前在读取哪个文件）！因为
LogAgent 进度是 当前读取到哪个文件以及文件内读到的位置 ，一旦这个文件被删除，LogAgent 不知道应该读哪个文件或从文件哪个位置开始读
取。此时可参考 LogAgent 日志中的处理方法，老版本处理步骤如下：
a. 停止 LogAgent；
b. 将数据目录 path 下已经读取过的文件移到其他目录；
c. 修改配置文件，使用新的 logagent_id；
d. 删除 logagent.pid.context 文件；
e. 启动 LogAgent；
上面 步骤 c 将使新启动的 LogAgent 使用新的进度，即从头读取发送所有文件，而 步骤 b 是避免从头发送导致数据发送重
复。
5. 发送的数据文件用 “记事本” 等工具编辑后无法发送数据。“记事本” 等文本编辑工具在 “保存” 时可能是通过删除旧文件或截断文件后重新写入的方
式来完成，这时会导致 4.删除或截断（truncate）正在读取的文件 提到的问题。
6. 是否有多台机器使用了相同 LogAgent ID，问题一般表现为埋点管理里 LogAgent 的 已接收 > 已校验。LogAgent ID 用于服务端数据去重，若配
置文件里没有指定 LogAgent ID，默认以 fqdn 作为 LogAgent ID，这时请检查 fqdn 是否相同。
7. LogAgent 日志没有明显错误信息，服务端查不到相关数据。LogAgent 只校验数据是否符合基本的数据格式，其他更详细的校验例如数据字段类型会
在服务端模块内校验，请查看导入项目的 埋点管理 查看是否有报错信息。
4.4. 查看 LogAgent 运行状态
LogAgent 每间隔 10 秒会输出如下格式日志：
LogAgent send speed: 1.200 records/sec, reading file: /home/work/app/logs/service.log.2016-08-17 (key:
(dev=fc01,ino=1197810), offset: 122071 / 145071).
样例中值的解释：
send speed: 1.200 records/sec：根据之前 10 秒处理情况计算的速度平均值；
reading file: /home/work/app/logs/service.log.2016-08-17：正在读取的文件路径；
key: (dev=fc01,ino=1197810)：文件所在磁盘以及 inode；
offset: 122071 / 145071：第一个值是读取到文件中的位置，第二个值是正在读取的文件总大小。
4.5. 在 Windows 下使用 LogAgent
Windows 下不支持 real_time_file_name 参数，即无法跟踪实时文件改名；
需要 Java 8 运行环境；
如果打开配置文件只有一行，可以用尝试用 “写字板”（非记事本）或 notepad++ 等编辑器打开；
Windows 下配置 path 请注意转义的问题，例如 path 是：
D:\data\logs
则需要在配置文件中设置：
path=D:\\data\\logs
其他使用方式同本文档描述，先填写配置文件，再运行 bin/logagent.bat 启动 LogAgent。
4.6. 升级 LogAgent
操作步骤如下：
1. 关闭正在运行的 LogAgent，可以通过 kill 进程使 LogAgent 退出；
2. 下载新版本 LogAgent 部署包 并解压；
3. 替换之前 LogAgent 部署目录下的 bin 目录 和 lib 目录；
4. 使用之前相同的参数和配置文件启动 LogAgent；另外：
若是从 20171028 之前版本升级到新版，需要在旧的配置文件中增加（新版配置文件中已包含） pid_file 项：
# pid , pid , pid , LogAgent
pid_file=logagent.pid
4.7. 断点续传
LogAgent 以 (LogAgent ID, path, pattern) 三元组对应一个数据 读取进度（哪个文件 inode 的哪个位置 offset）。
如果根据 读取进度 找不到续读的点（例如根据 inode 找不到文件，或 offset > 文件长度）将导致 LogAgent 启动失败进程退出。这时可以根据 LogAgent
日志中的提示来清除进度再开始新的导入。
5. 使用 LogAgent 校验数据
当需要对数据格式、字段类型等进行校验时，可以使用 LogAgent 的 DebugSender。LogAgent 会按如下流程进行校验数据：
1. LogAgent 本地校验数据格式是否合法，如 JSON 格式、必要字段（distinct_id 等）是否存在等。
2. 将通过内部校验的数据发送到远端进行数据内容的校验，如字段类型、track_signup 等。
校验失败会将数据和错误原因打印到日志里，若配置文件设置了 debug_exit_with_bad_record=true，则 LogAgent 会中止，不再处理后面的数据； 校
验通过的数据可以直接导入神策分析，或通过配置项 debug_not_import=true 设置为不导入这些数据。
启动 LogAgent 校验数据，校验通过的数据导入系统，校验失败的输出错误日志：
sender=DebugSender
启动 LogAgent 校验数据，校验通过的数据 不导入系统，当遇到错误数据 LogAgent 退出：
sender=DebugSender
debug_exit_with_bad_record=true
debug_not_import=true
参数解释：
debug_exit_with_bad_record：当添加该参数时，如遇到一条有问题的数据，LogAgent 会输出错误数据和原因，并退出。
debug_not_import：当添加该参数时，校验通过的数据不会写入神策分析系统。
注意：校验数据一般用于少量数据检验格式、字段类型是否正确，不适用于大数据量的生产环境。
6. 注意事项
1. 当数据地址为负载均衡的时候，请保证 LogAgent 的请求能一直落在某台数据接收机上不要随意更改。
2. 当服务端存在数据延迟的时候不要随意更改数据接收地址，其他细节请联系神策技术支持。
7. 更新日志
7.1. 20191227
1. 修改部分日志文案；
2. 修复当 jre 版本大于 10 的时候启动失败的问题。
3. 修复 window 环境下启动脚本找不到主类的问题。
4. 修复 20191021 版本在生成额外日志文件可能导致进程僵死的问题。
7.2. 20191021
1. 移除了通过启动参数指定 Sender 的功能；
2. 可通过启动参数手工指定起始文件和 offset；
3. 在出错时可额外生成日志文件保存最近的日志与错误原因；
4. 修复 cookie 反序列化异常的问题。7.3. 20190605
1. Windows 下运行支持过滤 BOM；
2. 支持 item 相关操作；
7.4. 20180125
1. 可通过环境变量指定 LogAgent 调试日志输出路径：
SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log bin/logagent
export SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log
bin/logagent
2. 更新 file-list-tool 脚本，详见 LogAgent 场景使用示例；
7.5. 20180108
1. 修复 LogAgent 在 Windows 下使用时读取已加锁的文件导致的异常退出；
7.6. 20171030
1. LogAgent 启动时若读到不完整的 context 将忽略文件内容；
7.7. 20171028
1. 修复当数据目录下文件列表为空时导致的空指针退出的问题，该问题于 20170922 之后版本存在；
2. 修复 LogAgent 未成功启动时重写了 context 文件，该问题于 20170922 之后版本存在，context 文件用于排查问题和加速启动；
7.8. 20171011
1. 修复一个导致意外退出的 bug；
7.9. 20170922
1. 更详细的错误输出，以及相应的处理方法；
2. 新增上下文文件，记录 LogAgent 运行状态，并通过上下文文件避免错误的 LogAgent 启动；
3. 定期向服务端上报 LogAgent 状态，方便问题排查；
7.10. 20170907
1. host 可以配置多个并以 ; 半角分号分隔；
7.11. 20170707
1. 修复安装 Java 脚本;
2. 启动失败时，将异常写入日志便于排查;
7.12. 20170511
1. 新增对过期数据（根据数据 time 字段）的过滤，默认当前时间 2 年前和 1 小时后的数据将被忽略，并记录到日志目录下;
2. 修复内部统计数据占用内存的问题;
7.13. 20161122
1. 添加对 $is_login_id 的支持，详情请见 标识用户;
2. 优化使用参数 --show_progress 时执行流程;
3. 获取进度的请求超时改为 10 分钟;
7.14. 20161114
1. 优化 logagent.bat，Windows 下方便看到错误提示。
7.15. 20160927
1. 对有实时写入的文件，即配置 real_time_file_name 的场景进行优化。.LogAgent v1.17
在使用前，请先阅读 数据模型 和 数据格式 的介绍。
1.1. LogAgent 概述
LogAgent 是用于将 后端数据实时 导入到神策分析的工具，一般运行在生产日志的服务器上。
几个应用场景举例：
我的程序不方便嵌入神策分析的 SDK，但又想将程序输出的数据导入神策分析；
我希望在本地生成神策分析的导入数据，并在本地保留完整的副本；
我不想自己控制数据发送进度，但又希望发送的数据不重不漏；
这时就可以考虑使用 LogAgent 来进行数据导入。
LogAgent 所做的事情非常简单，即按指定规则 tail 目录下的文件：
若发现新数据，将数据简单格式校验并打包发送到神策分析；
若无新数据，等待一段时间再查看是否有新数据；
LogAgent 启动时，会向神策分析询问本地目录文件的发送进度，以实现断点续传。
1.2. 下载 LogAgent
当前最新版本：20191227
LogAgent 部署包: http://download.sensorsdata.cn/release/logagent/logagent_20191227.tgz
1.3. 部署 LogAgent
Logagent 即支持在 Linux 环境下部署，也支持在 windows 环境下部署，windows 环境下部署时，需要注意文件编码问题，具体注意事项参考本文的 4.5
节。
下面以 Linux 环境为例说明 LogAgent 的部署方法。
1. 下载 LogAgent 部署包和解压：
wget http://download.sensorsdata.cn/release/logagent/logagent_20191227.tgz
tar zxvf logagent_20191227.tgz
cd logagent
2. 检查运行环境（至少 Java 8 以上）：
bin/check-java
如果提示 Can''t find java ，请指定 JAVA_HOME 环境变量 或 直接用附带的脚本（仅适用于 Linux 环境）安装绿色 JRE 环境（自动解压到 LogAgent 所在
目录，不影响系统下其他 Java 环境）：
bin/install-jre
3. 编辑配置文件：
可参考 LogAgent 场景使用示例 和 logagent.conf 中对每个配置项的说明；
4. 检查配置文件：
bin/logagent --show_conf
输出类似如下的信息：
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent version: SensorsAnalytics LogAgent_20170922
17/09/22 15:16:27 INFO logagent.LogAgentMain: Use FQDN as LogAgentID
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent ID: test01.sa
17/09/22 15:16:27 INFO logagent.LogAgentMain: Source config, path: ''/home/work/data'', pattern: ''service_log.*''17/09/22 15:16:27 INFO logagent.LogAgentMain: Service Uri: http://10.10.90.131:8106/log_agent
17/09/22 15:16:27 INFO logagent.LogAgentMain: Sender Type: BatchSender
17/09/22 15:16:27 INFO logagent.LogAgentMain: Pid file: /home/work/logagent/logagent.pid
若有多台机器部署 LogAgent，需要确保在不同机器上 LogAgent ID 取值不同（上面示例中是 test01.sa），服务端记录各机器的进度，以
LogAgent ID 区分不同机器；
5. 启动 LogAgent：
可以通过执行以下命令在后端执行 LogAgent：
nohup bin/logagent >/dev/null 2>&1 &
出现步骤 4 中的 pid 文件（步骤 4 输出样例最后一行 Pid file）则说明加载配置启动成功；
若未成功启动，可以查看 log 目录下的日志排查问题，或者直接在前端启动 LogAgent 观察是否有错误输出：
bin/logagent
6. 一台机器启动多个 LogAgent：
一个 LogAgent 程序目录仅能启动一个 LogAgent 进程实例；若需要启动多个 LogAgent，请将 LogAgent 部署到不同目录分别启动即可。
7. 监控 LogAgent：
LogAgent 启动后会在程序目录下生成一个 logagent.pid 文件，记录了进程的 pid 号，如果 LogAgent 需要常驻，建议自行对该进程做监控。
8. 关闭 LogAgent：
在 LogAgent 目录下执行以下命令，即 kill 进程即可：
kill $(cat logagent.pid)
1.4. 常见问题
1.4.1. 文件读取顺序
LogAgent 读取的文件列表由 path 目录下：pattern 所匹配的文件 和 real_time_file_name 指定的文件（若有配置）组成。其他文件将被忽略，这意味着
real_time_file_name （即实时文件）改名后需要符合 pattern 的匹配规则;
LogAgent 会对指定目录下所有规则匹配 pattern 的文件 按字典序排序，依次读取;
real_time_file_name（若有配置）总是被放在文件列表的最后，即认为其是最新的文件;
1.4.2. 读取文件流程
假设目录 path 下有如下文件：
service.log.20160817
service.log.20160818
service.log.20160819
1. 当一个文件例如 service.log.20160818 读取到末尾时，刷新目录文件列表，若当前正在读取的文件 service.log.20160818 不是文件列表中最后一
个文件，即认为有下一个时间点的文件如 service.log.20160819，那么标记当前文件 service.log.20160818 已经结束（即该文件不再继续写
入）。
2. 再次读取当前文件，若仍然没有读到数据，关闭当前文件 service.log.20160818，并开始从头读取下一个时间点的文件 service.log.20160819。
注意：当切换到读取 service.log.20160819 后，任何 字典序 位于 service.log.20160819 之前的数据都不会再被读取。
1.4.3. 不发送数据排查
导致数据不能正常读取发送可能有多种原因，请按如下步骤检查：
1. LogAgent 目录下的 log 目录中的 logagent.log 是否有报错信息。错误可能是数据格式问题、网络问题等。其中有问题的数据会被 LogAgent 过滤
而不会被导入，并记录在 log 目录下的 invalid_records 文件里；
2. 期望被读取的文件是否匹配配置中的 pattern 。不符合 pattern 的文件不会被 LogAgent 扫描；
3. 期望读取的文件在文件列表中是否位于当前进度之前。例如当前目录下有下列文件：data.2016090120
data.2016090121
假设当前 LogAgent 正在读取 data.2016090121。
a. 新增一个文件 data.20160901，不会被读取，因为按字典序排序目录下的文件，data.20160901 在 data.2016090121 之前；
b. 在 data.2016090120 后面追加写入，不会被读取，因为 LogAgent 不会读取当前读取文件 data.2016090121 之前文件的数据。
4. 删除或截断（truncate）正在读取的文件。不应当删除或截断 LogAgent 正在读取的文件（4.3 节可以看到当前在读取哪个文件）！因为
LogAgent 进度是 当前读取到哪个文件以及文件内读到的位置 ，一旦这个文件被删除，LogAgent 不知道应该读哪个文件或从文件哪个位置开始读
取。此时可参考 LogAgent 日志中的处理方法，老版本处理步骤如下：
a. 停止 LogAgent；
b. 将数据目录 path 下已经读取过的文件移到其他目录；
c. 修改配置文件，使用新的 logagent_id；
d. 删除 logagent.pid.context 文件；
e. 启动 LogAgent；
上面 步骤 c 将使新启动的 LogAgent 使用新的进度，即从头读取发送所有文件，而 步骤 b 是避免从头发送导致数据发送重
复。
5. 发送的数据文件用 “记事本” 等工具编辑后无法发送数据。“记事本” 等文本编辑工具在 “保存” 时可能是通过删除旧文件或截断文件后重新写入的方
式来完成，这时会导致 4.删除或截断（truncate）正在读取的文件 提到的问题。
6. 是否有多台机器使用了相同 LogAgent ID，问题一般表现为埋点管理里 LogAgent 的 已接收 > 已校验。LogAgent ID 用于服务端数据去重，若配
置文件里没有指定 LogAgent ID，默认以 fqdn 作为 LogAgent ID，这时请检查 fqdn 是否相同。
7. LogAgent 日志没有明显错误信息，服务端查不到相关数据。LogAgent 只校验数据是否符合基本的数据格式，其他更详细的校验例如数据字段类型会
在服务端模块内校验，请查看导入项目的 埋点管理 查看是否有报错信息。
1.4.4. 查看 LogAgent 运行状态
LogAgent 每间隔 10 秒会输出如下格式日志：
LogAgent send speed: 1.200 records/sec, reading file: /home/work/app/logs/service.log.2016-08-17 (key:
(dev=fc01,ino=1197810), offset: 122071 / 145071).
样例中值的解释：
send speed: 1.200 records/sec：根据之前 10 秒处理情况计算的速度平均值；
reading file: /home/work/app/logs/service.log.2016-08-17：正在读取的文件路径；
key: (dev=fc01,ino=1197810)：文件所在磁盘以及 inode；
offset: 122071 / 145071：第一个值是读取到文件中的位置，第二个值是正在读取的文件总大小。
1.4.5. 在 Windows 下使用 LogAgent
Windows 下不支持 real_time_file_name 参数，即无法跟踪实时文件改名；
需要 Java 8 运行环境；
如果打开配置文件只有一行，可以用尝试用 “写字板”（非记事本）或 notepad++ 等编辑器打开；
Windows 下配置 path 请注意转义的问题，例如 path 是：
D:\data\logs
则需要在配置文件中设置：
path=D:\\data\\logs
其他使用方式同本文档描述，先填写配置文件，再运行 bin/logagent.bat 启动 LogAgent。
1.4.6. 升级 LogAgent
操作步骤如下：
1. 关闭正在运行的 LogAgent，可以通过 kill 进程使 LogAgent 退出；
2. 下载新版本 LogAgent 部署包 并解压；
3. 替换之前 LogAgent 部署目录下的 bin 目录 和 lib 目录；
4. 使用之前相同的参数和配置文件启动 LogAgent；另外：
若是从 20171028 之前版本升级到新版，需要在旧的配置文件中增加（新版配置文件中已包含） pid_file 项：
# pid , pid , pid , LogAgent
pid_file=logagent.pid
1.4.7. 断点续传
LogAgent 以 (LogAgent ID, path, pattern) 三元组对应一个数据 读取进度（哪个文件 inode 的哪个位置 offset）。
如果根据 读取进度 找不到续读的点（例如根据 inode 找不到文件，或 offset > 文件长度）将导致 LogAgent 启动失败进程退出。这时可以根据 LogAgent
日志中的提示来清除进度再开始新的导入。
1.5. 使用 LogAgent 校验数据
当需要对数据格式、字段类型等进行校验时，可以使用 LogAgent 的 DebugSender。LogAgent 会按如下流程进行校验数据：
1. LogAgent 本地校验数据格式是否合法，如 JSON 格式、必要字段（distinct_id 等）是否存在等。
2. 将通过内部校验的数据发送到远端进行数据内容的校验，如字段类型、track_signup 等。
校验失败会将数据和错误原因打印到日志里，若配置文件设置了 debug_exit_with_bad_record=true，则 LogAgent 会中止，不再处理后面的数据； 校
验通过的数据可以直接导入神策分析，或通过配置项 debug_not_import=true 设置为不导入这些数据。
启动 LogAgent 校验数据，校验通过的数据导入系统，校验失败的输出错误日志：
sender=DebugSender
启动 LogAgent 校验数据，校验通过的数据 不导入系统，当遇到错误数据 LogAgent 退出：
sender=DebugSender
debug_exit_with_bad_record=true
debug_not_import=true
参数解释：
debug_exit_with_bad_record：当添加该参数时，如遇到一条有问题的数据，LogAgent 会输出错误数据和原因，并退出。
debug_not_import：当添加该参数时，校验通过的数据不会写入神策分析系统。
注意：校验数据一般用于少量数据检验格式、字段类型是否正确，不适用于大数据量的生产环境。
1.6. 注意事项
1. 当数据地址为负载均衡的时候，请保证 LogAgent 的请求能一直落在某台数据接收机上不要随意更改。
2. 当服务端存在数据延迟的时候不要随意更改数据接收地址，其他细节请联系神策技术支持。
1.7. 更新日志
1.7.1. 20191227
1. 修改部分日志文案；
2. 修复当 jre 版本大于 10 的时候启动失败的问题。
3. 修复 window 环境下启动脚本找不到主类的问题。
4. 修复 20191021 版本在生成额外日志文件可能导致进程僵死的问题。
1.7.2. 20191021
1. 移除了通过启动参数指定 Sender 的功能；
2. 可通过启动参数手工指定起始文件和 offset；
3. 在出错时可额外生成日志文件保存最近的日志与错误原因；
4. 修复 cookie 反序列化异常的问题。1.7.3. 20190605
1. Windows 下运行支持过滤 BOM；
2. 支持 item 相关操作；
1.7.4. 20180125
1. 可通过环境变量指定 LogAgent 调试日志输出路径：
SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log bin/logagent
export SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log
bin/logagent
2. 更新 file-list-tool 脚本，详见 LogAgent 场景使用示例；
1.7.5. 20180108
1. 修复 LogAgent 在 Windows 下使用时读取已加锁的文件导致的异常退出；
1.7.6. 20171030
1. LogAgent 启动时若读到不完整的 context 将忽略文件内容；
1.7.7. 20171028
1. 修复当数据目录下文件列表为空时导致的空指针退出的问题，该问题于 20170922 之后版本存在；
2. 修复 LogAgent 未成功启动时重写了 context 文件，该问题于 20170922 之后版本存在，context 文件用于排查问题和加速启动；
1.7.8. 20171011
1. 修复一个导致意外退出的 bug；
1.7.9. 20170922
1. 更详细的错误输出，以及相应的处理方法；
2. 新增上下文文件，记录 LogAgent 运行状态，并通过上下文文件避免错误的 LogAgent 启动；
3. 定期向服务端上报 LogAgent 状态，方便问题排查；
1.7.10. 20170907
1. host 可以配置多个并以 ; 半角分号分隔；
1.7.11. 20170707
1. 修复安装 Java 脚本;
2. 启动失败时，将异常写入日志便于排查;
1.7.12. 20170511
1. 新增对过期数据（根据数据 time 字段）的过滤，默认当前时间 2 年前和 1 小时后的数据将被忽略，并记录到日志目录下;
2. 修复内部统计数据占用内存的问题;
1.7.13. 20161122
1. 添加对 $is_login_id 的支持，详情请见 标识用户;
2. 优化使用参数 --show_progress 时执行流程;
3. 获取进度的请求超时改为 10 分钟;
1.7.14. 20161114
1. 优化 logagent.bat，Windows 下方便看到错误提示。
1.7.15. 20160927
1. 对有实时写入的文件，即配置 real_time_file_name 的场景进行优化。LogAgent 场景使用示例.LogAgent 场景使用示例 v1.13
1. 生成数据
1.1 使用神策分析 SDK 生成数据文件
神策分析各后端语言的 SDK 都支持将数据写入文件，例如使用 Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK
的 LoggingConsumer。下面以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa service_log.2017-09-25
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
以上配置将在 /data/sa 目录下生成数据文件，一天一个文件，文件列表如：
service_log.20170923
service_log.20170924
service_log.20170925
对应 LogAgent 中的配置：
path=/data/sa
pattern=service_log.*
1.2 使用其他方式输出数据文件
若所使用的编程语言有对应的 SDK，建议直接使用 SDK 来输出数据文件；若需要自己写数据文件，有几点需要注意：
1. （非常重要）文件只能追加写入，即打开文件时以 Open Append 方式打开；
2. 文件内容需要是 一条数据一行，并且是符合 数据格式 的完整 JSON；
3. 数据文件名 必须 包含日期，还可以包含更详细的时间，例如将数据写到 service_log.20170925 或 service_log.2017092517，文件目录下文件应
该类似如下：
service_log.20170923
service_log.20170924
service_log.20170925
对应 LogAgent 中的配置：
path=/data/sa
pattern=service_log.*
4. 若多个进程写入同一个文件，需要使用文件锁避免文件交叉写入数据损坏；
2. 配置数据接收服务地址
2.1 私有部署版配置
LogAgent 将数据发送到服务端，至少需要配置接收数据的服务端地址，对应配置文件中 host 和 port 两个参数：
host：一个 或 多个以 ; 半角分号分隔的服务器 IP 地址。例如 192.168.50.10;192.168.50.11;192.168.50.12，LogAgent 启动时会选定其中一台
发送数据，以均衡负载；
port：数据接收服务端口号，默认情况下集群版是 8106，单机版（1.7 及之前的版本为 8006，1.8 及之后的版本是 8106），云版不带端口号；若部署神策分析同时有外网 IP 和 内网 IP，host 的值应取内网 IP;
2.2 云版配置
点击“复制 https 数据接收地址”，例如复制到的是 https://example.datasink.sensorsdata.cn/sa?project=production&token=c9239cb3139077ca
在配置文件中，请删除或注释掉 host、port 和 token 字段，启用 service_uri 字段，取值是将上面获取到的值中的 /sa 改为 /log_agent，例如对于上面样
例，应配置 https://example.datasink.sensorsdata.cn/log_agent?token=c9239cb3139077ca。
指定数据发往的项目请参考本文档 4.1 节。
2.3 通过外网使用额外需要注意的配置
LogAgent 是为内网后端实时数据导入设计开发，若通过公网使用 LogAgent 需要额外注意：
请确保一个 LogAgent 每次请求都落到同一台机器上。如果使用负载均衡，负载均衡算法请选择 ip_hash 源地址 方式；如果域名 DNS 直接解析到
多台机器，则不能使用域名，应直接指定一个 IP 或按上面规则拼接多个服务器的外网 IP；
若公网使用 LogAgent 且服务端已经配置了 HTTPS 数据接入方式，可以按如下步骤配置使用 HTTPS 发送数据：
1. 注释掉配置文件中的 host、port 和 token 字段，即不使用 host、port 和 token 参数；
2. 在配置文件中启用 service_uri 字段，一个样例值为 https://example.sensorsdata.cn:4006/log_agent，请注意端口号应为 HTTPS 数据
接入服务的地址，uri 是 /log_agent，而不是 /sa;
3. 其他配置说明
3.1 配置实时写入文件的文件名 real_time_file_name
配置文件中的 real_time_file_name 即实时写入文件的文件名, 一般用在滚动日志文件的场景。例如按日切分的数据目录下文件列表如下：
service_log.20170922
service_log.20170923
service_log
数据输出进程只向 service_log 中写入，当到了新的一天，定时调度程序将 service_log 改名为带日期的文件例如 service_log.20170923，数据输出进程开始
写一个新的 service_log 文件，在这个场景里配置应当是:
pattern=service_log.*
real_time_file_name=service_log
即 pattern 可以匹配所有改名后的数据文件名，而 real_time_file_name 为实时输出的数据文件名。
3.2 以下场景无需配置 real_time_file_name
配置文件中的 real_time_file_name 优先级高于 pattern 参数，如果数据输出进程直接向 service_log.yyyymmdd / service_log.yyyymmddhh 中写入数据，
且每天自动生成新的文件，则需要注释掉此参数，只配置 pattern 参数即可，否则数据可能会无法正常导入。
以 JAVA SDK 为例，使用 JAVA SDK 的 ConcurrentLoggingConsumer，通过 new SensorsAnalytics.ConcurrentLoggingConsumer(“/data/sa
/service_log”))，此配置将在 /data/sa 目录下每天生成一个带日期的数据文件，文件列表如：
service_log.20170923
service_log.20170924
service_log.20170925
对应 LogAgent 中的配置：
path=/data/sa
pattern=service_log.*
# real_time_file_name=access_log
注：目前神策分析所有服务端 SDK 的 ConcurrentLoggingConsumer 模式下生成的日志文件都是每天生成一个带日期的数据文件，对应 LogAgent 的配置
均无需配置 real_time_file_name 参数。
4. 其他使用场景说明4.1 指定数据导入项目
指定数据导入的项目有两种方法：
1. 在每条数据中添加 project 字段（详见 数据格式），使用这种方式可以每条数据导入各自的项目；
2. 在配置文件中指定 project。每条数据无论是否指定 project 字段都将导入到参数设置的项目中。
系统判定一条数据所属项目的流程为：
1. 取配置文件中的 project；
2. 若上一步没有取到，取数据中的 project 字段；
3. 若上一步没有取到，（若有配置）取 service_uri 的 project 参数；
4. 若上一步没有取到，取默认项目的项目名，即 default。
如果想用一个 LogAgent 导入多个项目的数据，请不要在配置文件中设置 project，在数据中添加 project 字段来设置每条数据所属项目。
4.2 使用 file-list-tool 列出文件读取情况
新版本 LogAgent 提供了 file-list-tool：
$ bin/file-list-tool
usage: [file-checker] --context_file <arg> [-h] [--new_file_format <arg>]
[--old_file_format <arg>] [--reading_file_format <arg>]
--context_file <arg> LogAgent context file path, e.g.
logagent.pid.context
-h,--help help
--new_file_format <arg> {}
--old_file_format <arg> {}
--reading_file_format <arg> {}
使用 file-list-tool 解析 context 文件（与 pid 文件在同一个目录下）可以列出每个文件的读取状态：
$ bin/file-list-tool --context_file logagent.pid.context
18/01/22 17:35:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982,
sourceCount: 161982 ]
18/01/22 17:35:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012212, size:
19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:35:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012213, size:
11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:35:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012214, size:
19191980, key: (dev=fc10,ino=118226960)
“进度之前的文件” 即已经读取过的可以安全地从 LogAgent 读取目录移走或删除的文件。
file-list-tool 还可以以指定格式输出文件列表，例如下面的例子生成将已经读取过的文件移到指定目录的命令文件 mv.sh 并执行：
$ bin/file-list-tool --context_file logagent.pid.context --old_file_format ''mv {} /data/test/logagent/backup'' >
mv.sh
18/01/22 17:44:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982,
sourceCount: 161982 ]
18/01/22 17:44:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012212, size:
19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:44:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012213, size:
11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:44:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012214, size:
19191980, key: (dev=fc10,ino=118226960)
$ cat mv.sh
mv /data/test/logagent/data/test_data.2018012212 /data/test/logagent/backup
$ bash mv.sh
4.3 使用 --filename --offset 参数指定起始文件和 offset在启动时手工指定起始文件和 offset 的参考示例：
$ bin/logagent --filename service.log.20191021 --offset 100
注意：
1. 启动后会忽略起始值之前所有的日志文件；
2. 该配置在与服务端正常获取进度之后才会生效。
3. --filename 只需设置文件名无需包含路径，文件必须在配置文件中指定的路径 path 下存在且名称必须符合 pattern 规定的格式。
4. --offset 必须与 --filename 搭配使用，默认值为 0。
5. 如果 --offset 指定的位置分割了一条完整的埋点数据，那么该数据会被舍弃。.LogAgent 场景使用示例 v1.17
1. 生成数据
1.1 使用神策分析 SDK 生成数据文件
神策分析各后端语言的 SDK 都支持将数据写入文件，例如使用 Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK
的 LoggingConsumer。下面以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa service_log.2017-09-25
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
以上配置将在 /data/sa 目录下生成数据文件，一天一个文件，文件列表如：
service_log.20170923
service_log.20170924
service_log.20170925
对应 LogAgent 中的配置：
path=/data/sa
pattern=service_log.*
1.2 使用其他方式输出数据文件
若所使用的编程语言有对应的 SDK，建议直接使用 SDK 来输出数据文件；若需要自己写数据文件，有几点需要注意：
1. （非常重要）文件只能追加写入，即打开文件时以 Open Append 方式打开；
2. 文件内容需要是 一条数据一行，并且是符合 数据格式 的完整 JSON；
3. 数据文件名 必须 包含日期，还可以包含更详细的时间，例如将数据写到 service_log.20170925 或 service_log.2017092517，文件目录下文件应
该类似如下：
service_log.20170923
service_log.20170924
service_log.20170925
对应 LogAgent 中的配置：
path=/data/sa
pattern=service_log.*
4. 若多个进程写入同一个文件，需要使用文件锁避免文件交叉写入数据损坏；
2. 配置数据接收服务地址
2.1 私有部署版配置
LogAgent 将数据发送到服务端，至少需要配置接收数据的服务端地址，对应配置文件中 host 和 port 两个参数：
host：一个 或 多个以 ; 半角分号分隔的服务器 IP 地址。例如 192.168.50.10;192.168.50.11;192.168.50.12，LogAgent 启动时会选定其中一台
发送数据，以均衡负载；
port：数据接收服务端口号，默认情况下集群版是 8106，单机版（1.7 及之前的版本为 8006，1.8 及之后的版本是 8106），云版不带端口号；若部署神策分析同时有外网 IP 和 内网 IP，host 的值应取内网 IP;
2.2 云版配置
点击“复制 https 数据接收地址”，例如复制到的是 https://example.datasink.sensorsdata.cn/sa?project=production&token=c9239cb3139077ca
在配置文件中，请删除或注释掉 host、port 和 token 字段，启用 service_uri 字段，取值是将上面获取到的值中的 /sa 改为 /log_agent，例如对于上面样
例，应配置 https://example.datasink.sensorsdata.cn/log_agent?token=c9239cb3139077ca。
指定数据发往的项目请参考本文档 4.1 节。
2.3 通过外网使用额外需要注意的配置
LogAgent 是为内网后端实时数据导入设计开发，若通过公网使用 LogAgent 需要额外注意：
请确保一个 LogAgent 每次请求都落到同一台机器上。如果使用负载均衡，负载均衡算法请选择 ip_hash 源地址 方式；如果域名 DNS 直接解析到
多台机器，则不能使用域名，应直接指定一个 IP 或按上面规则拼接多个服务器的外网 IP；
若公网使用 LogAgent 且服务端已经配置了 HTTPS 数据接入方式，可以按如下步骤配置使用 HTTPS 发送数据：
1. 注释掉配置文件中的 host、port 和 token 字段，即不使用 host、port 和 token 参数；
2. 在配置文件中启用 service_uri 字段，一个样例值为 https://example.sensorsdata.cn:4006/log_agent，请注意端口号应为 HTTPS 数据
接入服务的地址，uri 是 /log_agent，而不是 /sa;
3. 其他配置说明
3.1 配置实时写入文件的文件名 real_time_file_name
配置文件中的 real_time_file_name 即实时写入文件的文件名, 一般用在滚动日志文件的场景。例如按日切分的数据目录下文件列表如下：
service_log.20170922
service_log.20170923
service_log
数据输出进程只向 service_log 中写入，当到了新的一天，定时调度程序将 service_log 改名为带日期的文件例如 service_log.20170923，数据输出进程开始
写一个新的 service_log 文件，在这个场景里配置应当是:
pattern=service_log.*
real_time_file_name=service_log
即 pattern 可以匹配所有改名后的数据文件名，而 real_time_file_name 为实时输出的数据文件名。
3.2 以下场景无需配置 real_time_file_name
配置文件中的 real_time_file_name 优先级高于 pattern 参数，如果数据输出进程直接向 service_log.yyyymmdd / service_log.yyyymmddhh 中写入数据，
且每天自动生成新的文件，则需要注释掉此参数，只配置 pattern 参数即可，否则数据可能会无法正常导入。
以 JAVA SDK 为例，使用 JAVA SDK 的 ConcurrentLoggingConsumer，通过 new SensorsAnalytics.ConcurrentLoggingConsumer(“/data/sa
/service_log”))，此配置将在 /data/sa 目录下每天生成一个带日期的数据文件，文件列表如：
service_log.20170923
service_log.20170924
service_log.20170925
对应 LogAgent 中的配置：
path=/data/sa
pattern=service_log.*
# real_time_file_name=access_log
注：目前神策分析所有服务端 SDK 的 ConcurrentLoggingConsumer 模式下生成的日志文件都是每天生成一个带日期的数据文件，对应 LogAgent 的配置
均无需配置 real_time_file_name 参数。
4. 其他使用场景说明4.1 指定数据导入项目
指定数据导入的项目有两种方法：
1. 在每条数据中添加 project 字段（详见 数据格式），使用这种方式可以每条数据导入各自的项目；
2. 在配置文件中指定 project。每条数据无论是否指定 project 字段都将导入到参数设置的项目中。
系统判定一条数据所属项目的流程为：
1. 取配置文件中的 project；
2. 若上一步没有取到，取数据中的 project 字段；
3. 若上一步没有取到，（若有配置）取 service_uri 的 project 参数；
4. 若上一步没有取到，取默认项目的项目名，即 default。
如果想用一个 LogAgent 导入多个项目的数据，请不要在配置文件中设置 project，在数据中添加 project 字段来设置每条数据所属项目。
4.2 使用 file-list-tool 列出文件读取情况
LogAgent 提供了 file-list-tool：
$ bin/file-list-tool
usage: [file-checker] --context_file <arg> [-h] [--new_file_format <arg>]
[--old_file_format <arg>] [--reading_file_format <arg>]
--context_file <arg> LogAgent context file path, e.g.
logagent.pid.context
-h,--help help
--new_file_format <arg> {}
--old_file_format <arg> {}
--reading_file_format <arg> {}
使用 file-list-tool 解析 context 文件（与 pid 文件在同一个目录下）可以列出每个文件的读取状态：
$ bin/file-list-tool --context_file logagent.pid.context
18/01/22 17:35:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982,
sourceCount: 161982 ]
18/01/22 17:35:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012212, size:
19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:35:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012213, size:
11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:35:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012214, size:
19191980, key: (dev=fc10,ino=118226960)
“进度之前的文件” 即已经读取过的可以安全地从 LogAgent 读取目录移走或删除的文件。
file-list-tool 还可以以指定格式输出文件列表，例如下面的例子生成将已经读取过的文件移到指定目录的命令文件 mv.sh 并执行：
$ bin/file-list-tool --context_file logagent.pid.context --old_file_format ''mv {} /data/test/logagent/backup'' >
mv.sh
18/01/22 17:44:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982,
sourceCount: 161982 ]
18/01/22 17:44:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012212, size:
19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:44:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012213, size:
11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:44:29 INFO logagent.FileListTool: , path: /data/test/logagent/data/test_data.2018012214, size:
19191980, key: (dev=fc10,ino=118226960)
$ cat mv.sh
mv /data/test/logagent/data/test_data.2018012212 /data/test/logagent/backup
$ bash mv.sh
4.3 使用 --filename --offset 参数指定起始文件和 offset版本高于 20191021 的 LogAgent 启动时可手工指定起始文件和 offset ：
$ bin/logagent --filename service.log.20191021 --offset 100
注意：
1. 启动后会忽略起始值之前所有的日志文件；
2. 该配置在与服务端正常获取进度之后才会生效。
3. --filename 只需设置文件名无需包含路径，文件必须在配置文件中指定的路径 path 下存在且名称必须符合 pattern 规定的格式。
4. --offset 必须与 --filename 搭配使用，默认值为 0。
5. 如果 --offset 指定的位置分割了一条完整的埋点数据，那么该数据会被舍弃。Logstash + Filebeat.Logstash + Filebeat v1.15
在使用前，请先阅读 数据模型 和 数据格式 的介绍。
1. 概述
神策分析支持使用 Logstash + Filebeat 的方式将 后端数据实时 导入神策分析。
Logstash 是由 Elastic 公司推出的一款开源的服务器端数据处理管道，能够同时从多个来源采集数据，转换数据，然后将数据发送指定的存储库中。Logsta
sh 官方介绍。
Filebeat 是 Elastic 公司为解决 Logstash "太重" 的问题推出的一款轻量级日志采集器，在处理数量众多的服务器、虚拟机和容器生成的日志时可使用
Logstash + Filebeat 的日志采集方式。Filebeat 官方介绍。
基于 Logstash + Filbeat 的数据采集流程为：后端 SDK 生成数据文件 => Filebeat 读取文件 => Logstash Beat input => Logstash sensors_analytic
output => 神策分析 。
结构如下图所示：
本文将介绍以下三个场景中如何使用 Logstash + Filebeat 完成数据采集并发送至神策分析。
服务器场景中的数据采集。
使用 Docker 容器化场景下的数据采集。
使用 K8s（Kubernetes）自动编排容器场景中的数据采集。
在阅读详细方案前，请先阅读 Logstash 和 Filebeat 的使用说明。
2. Logstash 使用说明
无论使用哪种方案 Logstash 都必须装有 sensors_analytics_output 插件。
请使用 Logstash-6.x 以上版本。
2.1. Logstash 下载与安装
请参考 installing Logstash 官方说明文档 ，选择您喜欢的下载与安装方式。
2.2. 安装 logstash-output-sensors_analytics 插件
该插件将检查数据是否为 Json 格式，并加入一些神策需要的字段值如 lib、data 等，打包数据，压缩并经过 base64 之后发送至神策的数据接收地址。
插件已经发布至 Ruby 官方公共库，Github repository : logstash-output-sensors_analytics 。直接在 Logstash 目录下执行安装即可，安装需要一段时
间，请耐心等待。
bin/logstash-plugin install logstash-output-sensors_analytics
在安装完成后执行 ：
bin/logstash-plugin list
看见新安装的插件 logstash-output-sensors_analytics 证明安装成功。插件在使用时直接配置在 output 里即可
output{
sensors_analytics {
url => "https://example.sensorsdata.cn/sa"
}
}
sensors_analytics 参数说明：
参数名 类 必 说明
型 须
url string 是 神策分析的数据接收地址，完整的 url 地址并以 sa 结尾，有端口号需要加上端口号。例如 :https://example.sensorsdata.cn:8106
/sa 。
project string 否 项目名，配置后会覆盖事件中和 url 中指定的 project。优先级为：project 参数配置 > 事件中指定 > url 中指定。
flush_interval_sec number 否 触发 flush 间隔的时间（单位：秒），默认值为 2。
flush_batch_size number 否 触发批量发送的最大 record 数量，默认值为 100 。
2.3. Logstash 配置
2.3.1. Logstash Pipeline 配置
Logstash 支持同时运行多个 Pipeline ，各个 Pipeline 之间互不影响，拥有各自独立的输入输出配置，Pipeline 的配置文件位于 config/pipelines.yml 。如
果您目前正在使用 Logstash 完成一些其他的日志采集工作，可以在原有的 Logstash 上新增一条 Pipeline 专门负责收集神策的日志数据，并发送至神策分
析。
pipelines.yml 参考示例：
# Pipeline
-pipeline.id: elastic-output
pipeline.workers: 4
path.config: "/home/app/logstash/elastic_output.config"
# sensorsdata
-pipeline.id: sensorsdata-output
# Logstash
pipeline.workers: 1
queue.type: persisted
#
path.config: "/home/app/logstash/beat_sa_output.config"
注意：神策分析日志的输入要不同于其他导入到 Logstash 的 Piplines 输入。比如之前使用的日志导入方式是通过 Filebeat 采集并发送到 Logstash 的
5044 端口，那么负责采集神策日志的 Filebeat 可以将数据发送至 5055 端口，从而能够应用 id = sensorsdata-output 的管道。
更多信息 Pipeline 信息请参考 : Multiple-Pipelines 官方说明文档 。
2.3.2. Logstash 输入输出配置
配置中主要包含 input、filter 和 output 三部分，Logstash 处理神策的日志数据只需配置 input 和 output 即可
beat_sa_output.conf 参考示例：# beats
input {
beats {
port => "5044"
}
}
# sensors_analytics
output{
sensors_analytics {
url => "https://example.sensorsdata.cn/sa"
}
}
2.3.3. Logstash 运行配置
Logstash 默认使用 config/logstash.yml 作为运行配置。
这里需要注意的是：
1. 在需要保证数据导入顺序的情况下请更改配置 pipeline.workers 的值为 1。配置项 pipeline.workers 的值默认为 cpu 的核心数，当 workers 的值大于 1
时，会导致处理数据的顺序发生变化。
2. 为保证数据的传输不会因为程序的意外终止而丢失，请设置 queue.type:persisted，该配置为 Logstash 使用的缓冲队列类型，这样配置可在重启
Logstash 后继续发送缓冲队列中的数据。 queue.type 的默认值为 memory （基于内存的）。
3. 建议设置 queue.drain 的值为 true ，该配置项会使 Logstash 在正常退出之前将所有缓冲队列中的数据全部发送完毕。
更多 logstash.yml 信息请参考 : logstash.yml 官方说明文档 。
2.4. Logstash 启动
直接启动，会使用 config/pipelines.yml 作为 Pipeline 配置和运行配置。
bin/logstash
指定 ~/logstash/beat_sa_output.conf 为输入输出配置文件启动 ，会使用 config/logstash.yml 作为运行配置。
bin/logstash -f ~/logstash/beat_sa_output.conf
通过命令参数指定输入输出启动，会使用 config/logstash.yml 作为运行配置。
bin/logstash -e ''output { sensors_analytics { url => "https://example.sensorsdata.cn/sa" }}''
更多启动相关信息请参考 : Getting Started with Logstash 官方说明文档。
2.5. Logstash 进度
Logstash 在使用 Filebeat 作为输入时文件的读取进度是由 Filebeat 进行控制的，当使用其他的输入方式时，例如 Logstash 读取文件，消费 Kafka 等，数
据的读取进度存放在 Logstash 目录 data/plugins 下，基于硬盘的数据缓冲队列存放在 data/queue 中。可在 logstash.yml 中配置 path.data 来指定
Logstash 启动时使用的 data/ 目录的位置。
3. Filebeat 使用说明
3.1. Filebeat 下载与安装
请参考：Install Filebeat 官方说明文档 。选择您喜欢的下载与安装方式。
3.2. Filebeat 配置
使用 Filebeat 读取后端 SDK 产生的埋点日志文件。Filebeat 默认配置文件为：filebeat.yml 。修改配置文件请使用 log 类型作为 Filebeat 的输入，paths
指定数据文件所在的位置，使用通配符 `*` 匹配后端 SDK 输出的文件名路径。
Filebeat 的输入输出配置 `filebeat.yml` 参考示例：# Filebeat /var/logs/ service_log.
filebeat.inputs:
- type: log
paths:
- /var/logs/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
需要注意的是：
1. 导入的数据必须是神策的数据格式。
2. 在需要保证导入顺序的情况下不要额外设置 loadbalance : true ，当配置了多个 Logstash hosts 作为数据接收端时该设置会使用轮询的方式将数据发送
至所有的 Logstash 这很可能导致数据的顺序被打乱。Filebeat 的默认配置为 loadbalance : false 。
3. Filebeat 的文件读取进度存放在 data/registry 目录下，在启动时用于恢复进度。
4. 在 Filebeat 运行时间，避免使用 vim 之类的可能生成文件副本的编辑器编辑文件，Filebeat 会读取目录中临时生成的文件。
更多配置相关信息请参考：Filebeat 官方文档。
3.3. 启动 Filebeat
./filebeat -e -c filebeat.yml
-c用于指定 filebeat.yml 配置文件的位置，-e 可在终端上显示 Filebeat 的日志信息。
3.4. Filebeat 进度
如果你的目录下有多个文件未被读取，filebeat 会同时读取多个文件，文件的读取进度存放在 Filebeat 目录下 data/registry 中，重启 Filebeat 时会根据进
度继续执行发送。
4. 服务器场景下的数据采集
如果您生产日志的后端应用直接部署在服务器上，本节内容将介绍如何使用 Filebeat + Logstash 采集产生的日志数据。该场景下也可使用 LogAgent 完成
日志的收集工作。
4.1. 部署 Logstash
如果您已经在使用 Logstash 做一些其他的日志收集工作请参考 Logstash 配置 。
参考 Logstash 使用说明 直接在您的一台或多台服务器上部署 Logstash 。
Logstash 输入输出配置 logstash.conf 示例：
# beats
input {
beats {
port => "5044"
}
}
# sensors_analytics
output{
sensors_analytics {
url => "https://example.sensorsdata.cn/sa"
}
}
Logstash 运行配置 logstash.yml 示例：
pipeline.workers: 1
queue.type: persisted
queue.drain: true
启动 Logstash 应用 logstash.conf ，更多启动方式请参考 Logstash 启动 和 Logstash 官方文档。bin/logstash -f logstash.conf
4.2. 部署 Filebeat
在会产生埋点日志的服务器上部署 Filebeat 采集指定目录下的日志发送至神策分析。
神策分析各后端语言的 SDK 都支持将数据写入文件，例如使用 Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK
的 LoggingConsumer 它们能将日志文件写入指定的目录下。
以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa_log service_log
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa_log/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
以上配置将在 /data/sa_log 目录下生成数据文件，一天一个文件，文件列表如：
service_log.20170923
service_log.20170924
service_log.20170925
Filebeat 通过配置 filebeat.yml 读取目录 /data/sa_log 下的以 service_log. 开头的日志文件，发送至部署好的 Logstash 。
filebeat.yml 参考示例：
# Filebeat /data/sa_log service_log.
filebeat.inputs:
- type: log
paths:
- /data/sa_log/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
当在一台服务器上有多个产生日志的目录时可配置 Filebeat 同时读取多个目录。
读取多目录 filebeat.yml 参考示例：
filebeat.inputs:
- type: log
paths:
# /data/sa_log service_log.
- /data/sa_log/service_log.*
# /another/logs/ sdk_log.
- /another/logs/sdk_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
后台启动 Filebeat
nohup ./filebeat -c filebeat.yml > /dev/null 2>&1 &5. 使用 Docker 容器化场景下的数据采集
5.1. 部署 Logstash
为保证 Logstash 的稳定工作，建议直接部署 Logstash，下文为 docker 部署方式仅供参考。
如果您已经在使用 Logstash 做一些其他的日志收集工作请参考 Logstash 配置 。为避免容器意外关闭导致丢失数据，请设法保存缓冲区内的数据。
首先，获取一个具有 sensors_analytics output 插件的 Logstash 镜像
方式一：直接下载我们已经安装好的插件的 Logstash (7.2.0 版本) 镜像。
docker pull sensorsdata/logstash:7.2.0
方式二：自行制作带有 sensors_analytics output 插件的 Logstash 镜像。
Dockerfile 示例：
FROM docker.elastic.co/logstash/logstash:7.2.0
RUN /usr/share/logstash/bin/logstash-plugin install logstash-output-sensors_analytics
准备需要的配置文件。
Logstash 的输入输出配置 logstash.conf 示例：
input {
beats {
port => "5044"
}
}
output {
sensors_analytics{
url => "http://10.42.34.189:8106/sa?project=default"
project => "default"
}
}
Logstash 的运行配置 logstash.yml 示例：
pipeline.workers: 1
queue.type: persisted
queue.drain: true
由于 Logstash 需要使用磁盘做缓冲队列，这里我们创建一个 Volume 专门用于保存 Logstash 的进度和缓冲队列，当重启该 Logstash 容器时请复用该
Volume 。
docker volume create logstash-data
在启动该容器时挂载配置文件和存放缓存队列的数据卷。
启动命令参考示例：
docker run -d -p 5044:5044 --name logstash \
--mount source=logstash-data,target=/usr/share/logstash/data \
-v ~/local/logstash/logstash.conf:/usr/share/logstash/pipeline/logstash.conf \
-v ~/local/logstash/logstash.yml:/usr/share/logstash/config/logstash.yml \ sensorsdata/logstash:7.2.0
5.2. 部署 Filebeat5.2.1. 方案一：在 SDK 容器中安装 Filebeat 采集日志并发送至 Logstash（推荐）
在您能够产生埋点日志的容器上安装一个 Filebeat 采集日志并发送至部署好的 Logstash，Filebeat 为一款轻量级的日志采集器，运行内存大概 10 MB 左
右，并不会给您的工作容器带来太多的负担。
优点：部署方便，不用担心 Filebeat 的进度问题。
缺点：侵入了原有的 SDK 容器。
下面以 JavaSDK 作为工作容器举例：
Dockerfile 示例：
FROM centos
ADD jdk-8u211-linux-x64.tar.gz /usr/local/
ENV JAVA_HOME /usr/local/jdk1.8.0_211
ENV CLASSPATH $JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
ENV PATH $PATH:$JAVA_HOME/bin
COPY javasdk.jar /home
# Filebaet
ADD filebeat-7.2.0-linux-x86_64.tar.gz /home
#
COPY filebeat.yml /etc
COPY run.sh /home
WORKDIR /home
# run.sh SDK Filebeat
CMD ["/bin/bash","-e","run.sh"]
run.sh 中的内容：
#!/bin/bash
nohup java -jar javasdk.jar > /dev/null 2>&1 &
nohup filebeat-7.2.0-linux-x86_64/filebeat -c /etc/filebeat.yml > /dev/null 2>&1 &
while [[ true ]]; do
sleep 10000
done
在容器中要保证 SDK 的日志写入路径与 Filebeat 的日志读取路径相同。
以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa_log service_log
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa_log/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();Filebeat 配置示例：
# Filebeat /data/sa_log service_log.
filebeat.inputs:
- type: log
paths:
- /data/sa_log/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
启动命令参考示例：
docker run -d --name sdk-beat \
-v ~/local/filebeat/filebeat.yml:/filebeat.yml \
sdk-beat
5.2.2. 方案二：SDK 使用共享数据保存日志 Filebeat 进行读取
后端 SDK 和 Filebeat 分别运行在不同的容器上，SDK 将生产的日志存放在数据卷上，Filebeat 从数据卷内读取数据发送至部署好的 Logstash 。
优点：不会侵入原有的 SDK 容器。
缺点：使用起来比较麻烦。
首先，创建一个数据卷选择您喜欢的存储方式，下面以本地磁盘为例，要保证你的容器对该数据卷有写权限：
docker volume create sa-log
启动后端 SDK 容器，将产生日志目录挂载到数据卷上。
docker run -d --name sdk \
--mount source=sa-logs,target=/your/logs/path \
your-sdk-image
启动 Filebeat 容器，将日志读取目录挂载到数据卷上。同时将存放文件读取进度的目录也挂载到数据卷上，以每一个数据卷为一个读取进度，当重启
Filebeat 时复用该进度即可继续执行发送。
配置文件 filebeat.yml 示例：
filebeat.inputs:
- type: log
paths:
- /usr/share/filebeat/input/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
将读取目录和进度目录同时挂载到数据卷上。
docker run -d --name filebeat \
--mount source=sa-logs,target=/usr/share/filebeat/input \
--mount source=sa-logs,target=/usr/share/filebeat/data/ \
-v ~/docker_workspace/filebeat/filebeat.yml:/usr/share/filebeat/filebeat.yml \
docker.elastic.co/beats/filebeat:7.2.0如果想用多个 SDK 容器挂载同一个数据卷的，建议容器以环境变量 HOSTNAME 为路径名存放日志文件，再将上级目录挂载到数据卷上。
举个例子：
容器内日志的输出路径：/mount/${HOSTNAEM}-logs/service_log.20190708
将容器中的 /mount 目录挂载至 Volume 。
因此 Volume 中日志的目录的存放格式为：
|-- Volume
| |-- c1369239e7ba-logs
| |-- fcdfdb3bdb2b-logs
| | |-- service_logs.20190702
| | |-- service_logs.20190703
| |-- da86e6ba6ca1-logs
| | |-- service_logs.20190701
| | |-- service_logs.20190702
| | |-- service_logs.20190703
更改 Filebeat 的文件读取路径为:
filebeat.inputs:
- type: log
paths:
- /usr/share/filebeat/input/*/service_log.*
以 Java SDK 为例生成带有 HOSTNAME 的路径存放日志：
// HOSTNAME
String hostname = System.getenv("HOSTNAME");
File logPath = new File("/mount/" + hostname + "-logs/");
if (!logPath.exists()) {
logPath.mkdirs();
}
// ConcurrentLoggingConsumer SensorsAnalytics
// /mount/${HOSTNAME}-logs/ service_log /mount
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer(logPath.getAbsolutePath() + "/service_log"));
//
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
如果您不希望更改原容器的日志路径存放方式，可以在容器启动时建立一条软链指向日志目录，将软链挂载到 Volume 上。
rm -rf /your/logs/path \
&& mkdir -p /mount/${HOSTNAME}_logs \
&& ln -s /mount/${HOSTNAME}_logs /your/logs/path \
&& bin/sdk start
在启动容器时将 /mount 挂载到 Volume 中。
docker run -d --name sdk \
--mount source=sa-logs,target=/mount \
your-sdk-image
6. 使用 K8s（Kubernetes）自动编排容器场景中的数据采集6.1. Logstash 部署
为保证 Logstash 的稳定工作，建议直接部署 Logstash 在服务器上，下文为 K8s 的部署方式供参考。
如果您已经在使用 Logstash 做一些其他的日志收集工作请参考 Logstash 配置。为避免容器意外关闭导致丢失数据，请设法保存缓冲区内的数据。
注册一份 Logstash 配置文件，使用 Filebeat 作为输入，sensors_analytics 作为输出，并指定运行配置。
配置文件 logstash-conf.yaml 参考示例：
apiVersion: v1
kind: ConfigMap
metadata:
name: logstash-set
labels:
sa-app: logstash
data:
logstash.yml: |-
http.host: 0.0.0.0
pipeline.workers: 1
queue.type: persisted
# 1024MB Pod
queue.max_bytes: 900mb
queue.drain: true
---
apiVersion: v1
kind: ConfigMap
metadata:
name: logstash-pipe-conf
labels:
sa-app: logstash
data:
logstash.conf: |-
input {
beats {
port => "5044"
}
}
output
{ sensors_analytics
{
url => "http://10.42.34.189:8106/sa?project=default"
}
}
为了不丢失数据，使用了基于硬盘的数据缓冲队列 (queue.type: persisted)，所以需要在容器外保存 Logstash 的进度信息，这样在重启 Logstash 的时候可
以继续完成发送。
建议通过 StatefulSet 的方式进行部署从而保存 Logstash 的状态。
首先，创建一个 StorageClass 用于生成保存进度的 PV ，设置手动回收，下面以 NFS 为例。
logstash-sc.yaml 的参考示例如下：
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: logstash-nfs-storage
provisioner: nfs-provisioner
reclaimPolicy: Retain
StatefulSet logstash-nfs-storage Headless Service Logstash Pod
logstash-sts.yaml
apiVersion: v1
kind: Service
metadata:name: logstash
labels:
app: logstash
spec:
ports:
- port: 5044
name: beat-in
clusterIP: None
selector:
app: logstash
---
apiVersion: apps/v1beta1
kind: StatefulSet
metadata:
name: logstash
spec:
# Headless Service
serviceName: "logstash"
selector:
matchLabels:
app: logstash
replicas: 3
template:
metadata:
labels:
app: logstash
spec:
containers:
- name: logstash
image: sensorsdata/logstash:7.2.0
ports:
- containerPort: 5044
name: beat-in
volumeMounts:
- name: logstash-pipe-conf
mountPath: /usr/share/logstash/pipeline/logstash.conf
subPath: logstash.conf
- name: logstash-set
mountPath: /usr/share/logstash/config/logstash.yml
subPath: logstash.yml
# /usr/share/logstash/data
- name: ldata
mountPath: /usr/share/logstash/data
volumes:
- name: logstash-pipe-conf
configMap:
name: logstash-pipe-conf
- name: logstash-set
configMap:
name: logstash-set
volumeClaimTemplates: # Logstash PVC
- metadata:
name: ldata
spec:
accessModes: [ "ReadWriteOnce" ]
#
storageClassName: "logstash-nfs-storage"
resources:
requests:
#
storage: 1Gi
StatefulSet 创建完成后 Pod name 的生成规则为 StatefulSetName - Pod - 序号。
上面的配置文件会生成 logstash-0、logstash-1，logstash-2 这样命名的 Pod。 Pod 副本也是按照序号 0 到 N-1 的顺序依次进行创建的，在删除时是按
照序号 N-1 到 0 依次删除。
Headless Service 为控制的每个 Pod 副本创建了一个 DNS 域名，完整的域名规则为：(pod name).(headless server name).namespace.svc.cluster.local
，因此 Filebeat 是通过域名来寻找 Logstash 的，而不是 IP 。当使用默认的 namespace 时可省略 namespace.svc.cluster.local 。StatefulSet 根据 volumeClaimTemplates，为每个 Pod 创建一个 PVC，PVC 的命名前缀为：namespace-volumeMounts.name -
volumeClaimTemplates.name - pod_name，删除一个 Pod 副本不会删除 PVC ，在重启后新的 Pod 会复用之前 PVC 中的进度继续完成发送。
创建完成后检查一下运行的情况：
kubectl get pods -l app=logstash
NAME READY STATUS RESTARTS AGE
logstash-0 1/1 Running 0 3h56m
logstash-1 1/1 Running 0 3h56m
logstash-2 1/1 Running 0 3h56m
查看一下数据卷的创建情况：
kubectl get pvc -l app=logstash
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
ldata-logstash-0 Bound pvc-c1833d35-d2ee-49a5-ae16-3a9d3227ebe5 1Gi RWO logstash-nfs-storage 3h56m
ldata-logstash-1 Bound pvc-9aa4b50c-45f7-4b64-9e4d-056838906675 1Gi RWO logstash-nfs-storage 3h56m
ldata-logstash-2 Bound pvc-95bcdbf0-e84d-4068-9967-3c69c731311b 1Gi RWO logstash-nfs-storage 3h56m
检查一下集群内部的 DNS 创建情况：
for i in 0 1; do kubectl exec logstash-$i -- sh -c ''hostname''; done
logstash-0
logstash-1
logstash-2
kubectl run -i --tty --image busybox:1.28.3 dns-test --restart=Never --rm /bin/sh
nslookup logstash-0.logstash
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local
Name: logstash-0.logstash
Address 1: 10.244.7.54 logstash-0.logstash.default.svc.cluster.local
nslookup logstash-1.logstash
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local
Name: logstash-1.logstash
Address 1: 10.244.5.150 logstash-1.logstash.default.svc.cluster.local
nslookup logstash-2.logstash
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local
Name: logstash-2.logstash
Address 1: 10.244.34.177 logstash-2.logstash.default.svc.cluster.local
Logstash 的扩容/缩容
StatefulSet 的更新策略也是顺序的。
将之前设置的 StatefulSet 容量从 3 变成 5 。
kubectl scale sts web --replicas=5
kubectl get pods -l app=logstash
NAME READY STATUS RESTARTS AGE
logstash-0 1/1 Running 0 6h1m
logstash-1 1/1 Running 0 6h1m
logstash-2 1/1 Running 0 6h1m
logstash-3 1/1 Running 0 1h3m
logstash-4 1/1 Running 0 1h3m
新增的 Pod 在原有的基础上序号递增。将 StatefulSet 容量从 5 变回 3 。
kubectl scale sts web --replicas=3
之前新增的 PVC 不会被删除，当下次达到该容量时会继续复用。不用担心有 Filebeat 会向被删除的 Logstash 发送数据， Filebeat 会自行寻找另一个运行
正常的 Logstash。
由于设置了 queue.drain: true 所以撤除的 Logstash 在关闭前会将缓冲区内的数据发送完毕。
6.2. 部署 Filebeat
6.2.1. 方案一：将 Filebeat 与 后端 SDK 封装在同一个 Pod 里采集日志文件（推荐）
将 Filebeat 容器与能够产生日志的后端 SDK 容器配置在同一个 Pod 里，后端 SDK 将日志写入 emptyDir 中，由 Filebeat 进行读取并发送至 Logstash。
优点：部署方便，哪个 Pod 里有日志就在哪个 Pod 里新增一个 Filebeat。
缺点：与 SDK Pod 有耦合，Filebeat 的数量可能较多，稍显冗余。
神策分析各后端语言的 SDK 都支持将数据写入文件，例如： Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK 的
LoggingConsumer。
以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa_log service_log
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa_log/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
以上配置将在 /data/sa_log 目录下生成数据文件，一天一个文件，文件列表如下：
service_log.20170923
service_log.20170924
service_log.20170925
在部署 Pod 时首先将 SDK 容器中的 /data/sa_log 目录下的内容挂载到 emptyDir: {} 上。然后设置 Filebeat 的读取的文件目录为：/var/log/containers
/service_log.* 。Filebeat 将会读取该目录下所有以 service_log. 开头的文件。最后把 Filebeat 容器的 /var/log/containers/ 目录也挂载到 emptyDir: {} 上
，运行时即可读取 SDK 容器产生的日志文件。
部署文件 pod.yaml 参考示例：
apiVersion: v1
kind: ConfigMap
metadata:
name: filebeat-config-in
labels:
sa-app: filebeat
data:
filebeat.yml: |-
filebeat.inputs:
- type: log# /var/log/containers service_log
paths:
- /var/log/containers/service_log.*
output.logstash:
# Logstash
hosts: ["logstash-0.logstash:5044","logstash-1.logstash:5044"]
---
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: javasdk-beat
labels:
sa-app: javasdk-beat
spec:
replicas: 3
template:
metadata:
name: javasdk-beat
labels:
sa-app: javasdk-beat
spec:
containers:
- name: javasdk
image: javasdk:20190705
command: ["/bin/bash", "-c"]
args:
- "bin/javasdk start"
volumeMounts:
- name: log-path
# /data/sa_log SDK emptyDir
mountPath: /data/sa_log
- name: filebeat
image: docker.elastic.co/beats/filebeat:7.2.0
args: [
"-c", "/etc/filebeat.yml",
"-e",
]
volumeMounts:
- name: config
mountPath: /etc/filebeat.yml
readOnly: true
subPath: filebeat.yml
- name: log-path
# emptyDir
mountPath: /var/log/containers
readOnly: true
volumes:
- name: log-path
emptyDir: {}
- name: config
configMap:
name: filebeat-config-in
6.2.2. 方案二：Filebeat 部署在 K8s 节点上采集日志文件
Filebeat 以 DaemonSet 的方式部署在 K8s 节点上收集日志数据。节点上运行的后端 SDK 统一将日志存放在宿主机的指定目录内由 Filebeat 进行读取并发
送至 Logstash。优点：Filebeat 部署方便，与 SDK Pod 无耦合。
缺点：需要解决目录问题，在宿主机上会存在额外的日志文件。
考虑到在同一宿主机上可能存在多个相同的后端 SDK 容器，因此需要使每个容器在向宿主机目录写入日志的时候使用不同的目录。建议在启动容器时使用系
统环境变量 HOSTNAME 作为路径名存放日志文件，然后将上一级目录挂载到宿主机目录上。
举个例子：
容器内日志的输出路径：/mount/${HOSTNAEM}-logs/service_log.20190708
宿主机存放日志的路径：/home/data/javasdk_logs/
将 /mount 挂载至 /home/data/javasdk_logs/ 下。
因此宿主机的 /home/data/javasdk_logs/ 目录下存放的内容大致如下：
[root@node-1 javasdk_logs]$ pwd
/home/data/javasdk_logs/
[root@node-1 javasdk_logs]$ ls -l
drwxr-xr-x 2 root root 22 Jul 8 12:06 javasdk-7d878c784d-5fpjz_logs
drwxr-xr-x 2 root root 22 Jul 6 18:33 javasdk-7d878c784d-7xmbb_logs
drwxr-xr-x 2 root root 22 Jul 6 18:52 javasdk-7d878c784d-vv9fz_logs
drwxr-xr-x 2 root root 22 Jul 8 12:08 javasdk-7d878c784d-w7q65_logs
drwxr-xr-x 2 root root 22 Jul 8 11:19 javasdk-7d878c784d-wkvxd_logs
[root@node-1 javasdk_logs]$ cd javasdk-7d878c784d-5fpjz_logs
[root@node-1 javasdk-7d878c784d-5fpjz_logs]$ ls -l
-rw-r--r-- 1 root root 6592991 Jul 8 23:59 service_log.20190706
-rw-r--r-- 1 root root 4777188 Jul 8 23:58 service_log.20190707
-rw-r--r-- 1 root root 137778 Jul 8 12:03 service_log.20190708
以 Java SDK 为例在保存日志时以 HOSTNAME 作为路径，参考如下：
// HOSTNAME
String hostname = System.getenv("HOSTNAME");
File logPath = new File("/mount/" + hostname + "-logs/");
if (!logPath.exists()) {
logPath.mkdirs();
}
// ConcurrentLoggingConsumer SensorsAnalytics
// /mount/${HOSTNAME}-logs/ service_log /mount
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer(logPath.getAbsolutePath() + "/service_log"));
//
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
参考的 javasdk.yaml 文件配置：
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
replicas: 3
template:
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
containers:
- name: javasdk
image: java-sdk-host:0715
command: ["/bin/bash", "-c"]args:
- "bin/javasdk start"
volumeMounts:
- name: logfile
mountPath: /mount
volumes:
- name: logfile
hostPath:
path: /home/data/javasdk_logs/
type: DirectoryOrCreate
如果您不希望更改原容器的日志路径存放方式，可以在容器启动时建立一条软链指向日志目录，将软链挂载在宿主机即可。
参考的 javasdk.yaml 文件配置：
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
replicas: 3
template:
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
containers:
- name: javasdk
image: java-sdk:0712
command: ["/bin/bash", "-c"]
args:
- "rm -rf /your/logs/path
&& mkdir -p /mount/${HOSTNAME}_logs
&& ln -s /mount/${HOSTNAME}_logs /your/logs/path
&& bin/javasdk start"
volumeMounts:
- name: logfile
mountPath: /mount
volumes:
- name: logfile
hostPath:
path: /home/data/javasdk_logs/
type: DirectoryOrCreate
将 Filebeat 匹配的路径设置为 /home/data/javasdk_logs/*/service_log.*，并且把 Filebeat 存放进度的目录也挂载在宿主机上，这样在重启 DaemonSet 的
时候节点上的 Filebeat 会继续之前的发送进度。
DaemonSet 配置文件 filebeat-ds.yaml 参考如下：
apiVersion: v1
kind: ConfigMap
metadata:
name: filebeat-config
labels:
sa-app: filebeat
data:
filebeat.yml: |-
filebeat.inputs:
- type: log
paths:
# service_log
- /var/log/containers/*/service_log.*
output.logstash:
# Logstashhosts: ["logstash-0.logstash:5044","logstash-1.logstash:5044"]
---
apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
name: filebeat
labels:
sa-app: filebeat
spec:
template:
metadata:
labels:
sa-app: filebeat
spec:
serviceAccountName: filebeat
terminationGracePeriodSeconds: 30
containers:
- name: filebeat
image: docker.elastic.co/beats/filebeat:7.2.0
imagePullPolicy: IfNotPresent
args: [
"-c", "/etc/filebeat.yml",
"-e",
]
volumeMounts:
- name: config
mountPath: /etc/filebeat.yml
readOnly: true
subPath: filebeat.yml
- name: inputs
mountPath: /var/log/containers
readOnly: true
- name: data
mountPath: /usr/share/filebeat/data
volumes:
- name: config
configMap:
name: filebeat-config
- name: inputs
hostPath:
path: /home/data/javasdk_logs/
- name: data
hostPath:
path: /home/data/filebeat_data/
type: DirectoryOrCreate
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
name: filebeat
subjects:
- kind: ServiceAccount
name: filebeat
namespace: default
roleRef:
kind: ClusterRole
name: filebeat
apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRole
metadata:
name: filebeat
labels:
sa-app: filebeat
rules:
- apiGroups: [""]
resources:
- namespaces
- pods
verbs:- get
- watch
- list
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: filebeat
namespace: default
labels:
sa-app: filebeat.Logstash Filebeat v1.13
在使用前，请先阅读 数据模型 和 数据格式 的介绍。
1. 概述
神策分析支持使用 Logstash + Filebeat 的方式将 后端数据实时 导入神策分析。
Logstash 是由 Elastic 公司推出的一款开源的服务器端数据处理管道，能够同时从多个来源采集数据，转换数据，然后将数据发送指定的存储库中。Logsta
sh 官方介绍。
Filebeat 是 Elastic 公司为解决 Logstash "太重" 的问题推出的一款轻量级日志采集器，在处理数量众多的服务器、虚拟机和容器生成的日志时可使用
Logstash + Filebeat 的日志采集方式。Filebeat 官方介绍。
基于 Logstash + Filbeat 的数据采集流程为：后端 SDK 生成数据文件 => Filebeat 读取文件 => Logstash Beat input => Logstash sensors_analytic
output => 神策分析 。
结构如下图所示：
本文将介绍以下三个场景中如何使用 Logstash + Filebeat 完成数据采集并发送至神策分析。
服务器场景中的数据采集。
.Logstash Filebeat v1.13#使用 Docker 容器化场景下的数据采集。
.Logstash Filebeat v1.13#使用 K8s（Kubernetes）自动编排容器场景中的数据采集。
在阅读详细方案前，请先阅读 Logstash 和 Filebeat 的使用说明与 版本支持信息。
2. Logstash 使用说明
无论使用哪种方案 Logstash 都必须装有 sensors_analytics_output 插件。
请使用 Logstash-6.x 以上版本。
2.1. Logstash 下载与安装
请参考 installing Logstash 官方说明文档 ，选择您喜欢的下载与安装方式。
2.2. 安装 logstash-output-sensors_analytics 插件
该插件将检查数据是否为 Json 格式，并加入一些神策需要的字段值如 lib、data 等，打包数据，压缩并经过 base64 之后发送至神策的数据接收地址。
插件已经发布至 Ruby 官方公共库，Github repository : logstash-output-sensors_analytics 。直接在 Logstash 目录下执行安装即可，安装需要一段时
间，请耐心等待。
bin/logstash-plugin install logstash-output-sensors_analytics
在安装完成后执行 ：
bin/logstash-plugin list
看见新安装的插件 logstash-output-sensors_analytics 证明安装成功。插件在使用时直接配置在 output 里即可
output{
sensors_analytics {
url => "https://example.sensorsdata.cn/sa"
}
}
sensors_analytics 参数说明：
参数名 类 必 说明
型 须
url list 是 神策分析的数据接收地址，完整的 url 地址并以 sa 结尾，有端口号需要加上端口号。例如 :https://example.sensorsdata.cn:8106/sa 。可同
时配置多个数据接收地址，一条数据具体发到哪个数据接收地址，是由输入插件中部分元数据信息 hash 后决定。在使用 Filebeat 时默认使用
Filebeat 当时的 hostname + filename进行 hash 后选择数据接收地址。
project string 否 项目名，不写默认为 default ，配置后会覆盖事件中和 url 中指定的 project。优先级为：project 参数配置 > 事件中指定 > url 中指定。
flush_inter num 否 触发 flush 间隔的时间（单位：秒），默认值为 2。
val_sec ber
flush_batc num 否 触发批量发送的最大 record 数量，默认值为 100 。
h_size ber
hash_filed list 否 用于 hash 选择数据接收地址的 filed，层级关系与输入的 logstash.event 结构相同，可在 output 中使用 stdout 观察。
enable_file bool 否 默认开启，在日志展示中一分钟内活动的 Filebeat 读取状态。
beat_statu ean
s_report
2.3. Logstash 配置
2.3.1. Logstash Pipeline 配置
Logstash 支持同时运行多个 Pipeline ，各个 Pipeline 之间互不影响，拥有各自独立的输入输出配置，Pipeline 的配置文件位于 config/pipelines.yml 。如
果您目前正在使用 Logstash 完成一些其他的日志采集工作，可以在原有的 Logstash 上新增一条 Pipeline 专门负责收集神策的日志数据，并发送至神策分
析。
pipelines.yml 参考示例：
# Pipeline
-pipeline.id: elastic-output
pipeline.workers: 4
path.config: "/home/app/logstash/elastic_output.config"
# sensorsdata
-pipeline.id: sensorsdata-output
# Logstash
pipeline.workers: 1
queue.type: persisted
#
path.config: "/home/app/logstash/beat_sa_output.config"
注意：神策分析日志的输入要不同于其他导入到 Logstash 的 Piplines 输入。比如之前使用的日志导入方式是通过 Filebeat 采集并发送到 Logstash 的
5044 端口，那么负责采集神策日志的 Filebeat 可以将数据发送至 5055 端口，从而能够应用 id = sensorsdata-output 的管道。
更多信息 Pipeline 信息请参考 : Multiple-Pipelines 官方说明文档 。2.3.2. Logstash 输入输出配置
配置中主要包含 input、filter 和 output 三部分，Logstash 处理神策的日志数据只需配置 input 和 output 即可
beat_sa_output.conf 参考示例：
# beats
input {
beats {
port => "5044"
}
}
# sensors_analytics
output{
sensors_analytics {
url => "https://example.sensorsdata.cn/sa"
}
}
提醒：在使用 logstash-file-input-plugin 时当 logstash 处于关闭状态下时重命名已读文件（重命名后依然符合 pattern），启动后会导致重复读取。
2.3.3. Logstash 运行配置
Logstash 默认使用 config/logstash.yml 作为运行配置。
这里需要注意的是：
1. 在需要保证数据导入顺序的情况下请更改配置 pipeline.workers 的值为 1。配置项 pipeline.workers 的值默认为 cpu 的核心数，当 workers 的值大于 1
时，会导致处理数据的顺序发生变化。
2. 为保证数据的传输不会因为程序的意外终止而丢失，请设置 queue.type:persisted，该配置为 Logstash 使用的缓冲队列类型，这样配置可在重启
Logstash 后继续发送缓冲队列中的数据。 queue.type 的默认值为 memory （基于内存的）。
3. 建议设置 queue.drain 的值为 true ，该配置项会使 Logstash 在正常退出之前将所有缓冲队列中的数据全部发送完毕。
更多 logstash.yml 信息请参考 : logstash.yml 官方说明文档 。
2.4. Logstash 启动
直接启动，会使用 config/pipelines.yml 作为 Pipeline 配置和运行配置。
bin/logstash
指定 ~/logstash/beat_sa_output.conf 为输入输出配置文件启动 ，会使用 config/logstash.yml 作为运行配置。
bin/logstash -f ~/logstash/beat_sa_output.conf
通过命令参数指定输入输出启动，会使用 config/logstash.yml 作为运行配置。
bin/logstash -e ''output { sensors_analytics { url => "https://example.sensorsdata.cn/sa" }}''
更多启动相关信息请参考 : Getting Started with Logstash 官方说明文档。
2.5. Logstash 进度
Logstash 在使用 Filebeat 作为输入时文件的读取进度是由 Filebeat 进行控制的，当使用其他的输入方式时，例如 Logstash 读取文件，消费 Kafka 等，数
据的读取进度存放在 Logstash 目录 data/plugins 下，基于硬盘的数据缓冲队列存放在 data/queue 中。可在 logstash.yml 中配置 path.data 来指定
Logstash 启动时使用的 data/ 目录的位置。
2.6. sensors-output-plugin 升级与回滚
已安装插件升级至最新版本
bin/logstash-plugin update logstash-output-sensors_analytics
安装指定版本的插件# v0.1.0
bin/logstash-plugin install --version 0.1.0 logstash-output-sensors_analytics
# v1.1.2
bin/logstash-plugin install --version 0.1.2 logstash-output-sensors_analytics
卸载插件
bin/logstash-plugin remove logstash-output-sensors_analytics
3. Filebeat 使用说明
3.1. Filebeat 下载与安装
请参考：Install Filebeat 官方说明文档 。选择您喜欢的下载与安装方式。
3.2. Filebeat 配置
使用 Filebeat 读取后端 SDK 产生的埋点日志文件。Filebeat 默认配置文件为：filebeat.yml 。修改配置文件请使用 log 类型作为 Filebeat 的输入，paths
指定数据文件所在的位置，使用通配符 `*` 匹配后端 SDK 输出的文件名路径。
Filebeat 的输入输出配置 `filebeat.yml` 参考示例：
# Filebeat /var/logs/ service_log.
filebeat.shutdown_timeout: 5s
filebeat.inputs:
- type: log
paths:
- /var/logs/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
需要注意的是：
1. 导入的数据必须是神策的数据格式。
2. 在需要保证导入顺序的情况下不要额外设置 loadbalance : true ，当配置了多个 Logstash hosts 作为数据接收端时该设置会使用轮询的方式将数据发送
至所有的 Logstash 这很可能导致数据的顺序被打乱。Filebeat 的默认配置为 loadbalance : false 。
3. Filebeat 的文件读取进度存放在 data/registry 目录下，在启动时用于恢复进度。
4. 在 Filebeat 运行时间，避免使用 vim 之类的可能生成文件副本的编辑器编辑文件，Filebeat 会读取目录中临时生成的文件。5.
建议新增配置项 filebeat.shutdown_timeout: 5s ，filebeat 在退出时有可能造成少量数据重复。
更多配置相关信息请参考：Filebeat 官方文档。
3.3. 启动 Filebeat
./filebeat -e -c filebeat.yml
-c用于指定 filebeat.yml 配置文件的位置，-e 可在终端上显示 Filebeat 的日志信息。
3.4. Filebeat 进度
如果你的目录下有多个文件未被读取，filebeat 会同时读取多个文件，文件的读取进度存放在 Filebeat 目录下 data/registry 中，重启 Filebeat 时会根据进
度继续执行发送。
4. 服务器场景下的数据采集如果您生产日志的后端应用直接部署在服务器上，本节内容将介绍如何使用 Filebeat + Logstash 采集产生的日志数据。该场景下也可使用 LogAgent 完成
日志的收集工作。
4.1. 部署 Logstash
如果您已经在使用 Logstash 做一些其他的日志收集工作请参考 .Logstash Filebeat v1.13#Logstash 配置 。
参考 .Logstash Filebeat v1.13#Logstash 使用说明 直接在您的一台或多台服务器上部署 Logstash 。
Logstash 输入输出配置 logstash.conf 示例：
# beats
input {
beats {
port => "5044"
}
}
# sensors_analytics
output{
sensors_analytics {
url => "https://example.sensorsdata.cn/sa"
}
}
Logstash 运行配置 logstash.yml 示例：
pipeline.workers: 1
queue.type: persisted
queue.drain: true
启动 Logstash 应用 logstash.conf ，更多启动方式请参考 .Logstash Filebeat v1.13#Logstash 启动 和 Logstash 官方文档。
bin/logstash -f logstash.conf
4.2. 部署 Filebeat
在会产生埋点日志的服务器上部署 Filebeat 采集指定目录下的日志发送至神策分析。
神策分析各后端语言的 SDK 都支持将数据写入文件，例如使用 Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK
的 LoggingConsumer 它们能将日志文件写入指定的目录下。
以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa_log service_log
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa_log/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
以上配置将在 /data/sa_log 目录下生成数据文件，一天一个文件，文件列表如：
service_log.20170923
service_log.20170924
service_log.20170925
Filebeat 通过配置 filebeat.yml 读取目录 /data/sa_log 下的以 service_log. 开头的日志文件，发送至部署好的 Logstash 。filebeat.yml 参考示例：
# Filebeat /data/sa_log service_log.
filebeat.inputs:
- type: log
paths:
- /data/sa_log/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
当在一台服务器上有多个产生日志的目录时可配置 Filebeat 同时读取多个目录。
读取多目录 filebeat.yml 参考示例：
filebeat.inputs:
- type: log
paths:
# /data/sa_log service_log.
- /data/sa_log/service_log.*
# /another/logs/ sdk_log.
- /another/logs/sdk_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
后台启动 Filebeat
nohup ./filebeat -c filebeat.yml > /dev/null 2>&1 &
5. 使用 Docker 容器化场景下的数据采集
5.1. 部署 Logstash
为保证 Logstash 的稳定工作，建议直接部署 Logstash，下文为 docker 部署方式仅供参考。
如果您已经在使用 Logstash 做一些其他的日志收集工作请参考 .Logstash Filebeat v1.13#Logstash 配置 。为避免容器意外关闭导致丢失数据，请设法保
存缓冲区内的数据。
首先，获取一个具有 sensors_analytics output 插件的 Logstash 镜像
方式一：直接下载我们已经安装好的插件的 Logstash (7.2.0 版本) 镜像。
docker pull sensorsdata/logstash:7.2.0
方式二：自行制作带有 sensors_analytics output 插件的 Logstash 镜像。
Dockerfile 示例：
FROM docker.elastic.co/logstash/logstash:7.2.0
RUN /usr/share/logstash/bin/logstash-plugin install logstash-output-sensors_analytics
准备需要的配置文件。
Logstash 的输入输出配置 logstash.conf 示例：
input {
beats {
port => "5044"
}}
output {
sensors_analytics{
url => "http://10.42.34.189:8106/sa?project=default"
project => "default"
}
}
Logstash 的运行配置 logstash.yml 示例：
pipeline.workers: 1
queue.type: persisted
queue.drain: true
由于 Logstash 需要使用磁盘做缓冲队列，这里我们创建一个 Volume 专门用于保存 Logstash 的进度和缓冲队列，当重启该 Logstash 容器时请复用该
Volume 。
docker volume create logstash-data
在启动该容器时挂载配置文件和存放缓存队列的数据卷。
启动命令参考示例：
docker run -d -p 5044:5044 --name logstash \
--mount source=logstash-data,target=/usr/share/logstash/data \
-v ~/local/logstash/logstash.conf:/usr/share/logstash/pipeline/logstash.conf \
-v ~/local/logstash/logstash.yml:/usr/share/logstash/config/logstash.yml \ sensorsdata/logstash:7.2.0
5.2. 部署 Filebeat
5.2.1. 方案一：在 SDK 容器中安装 Filebeat 采集日志并发送至 Logstash（推荐）
在您能够产生埋点日志的容器上安装一个 Filebeat 采集日志并发送至部署好的 Logstash，Filebeat 为一款轻量级的日志采集器，运行内存大概 10 MB 左
右，并不会给您的工作容器带来太多的负担。
优点：部署方便，不用担心 Filebeat 的进度问题。
缺点：侵入了原有的 SDK 容器。
下面以 JavaSDK 作为工作容器举例：
Dockerfile 示例：
FROM centos
ADD jdk-8u211-linux-x64.tar.gz /usr/local/
ENV JAVA_HOME /usr/local/jdk1.8.0_211
ENV CLASSPATH $JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
ENV PATH $PATH:$JAVA_HOME/bin
COPY javasdk.jar /home
# Filebaet
ADD filebeat-7.2.0-linux-x86_64.tar.gz /home
#
COPY filebeat.yml /etcCOPY run.sh /home
WORKDIR /home
# run.sh SDK Filebeat
CMD ["/bin/bash","-e","run.sh"]
run.sh 中的内容：
#!/bin/bash
nohup java -jar javasdk.jar > /dev/null 2>&1 &
nohup filebeat-7.2.0-linux-x86_64/filebeat -c /etc/filebeat.yml > /dev/null 2>&1 &
while [[ true ]]; do
sleep 10000
done
在容器中要保证 SDK 的日志写入路径与 Filebeat 的日志读取路径相同。
以 Java SDK 为例：
// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa_log service_log
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa_log/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
Filebeat 配置示例：
# Filebeat /data/sa_log service_log.
filebeat.inputs:
- type: log
paths:
- /data/sa_log/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
启动命令参考示例：
docker run -d --name sdk-beat \
-v ~/local/filebeat/filebeat.yml:/filebeat.yml \
sdk-beat
5.2.2. 方案二：SDK 使用共享数据保存日志 Filebeat 进行读取
后端 SDK 和 Filebeat 分别运行在不同的容器上，SDK 将生产的日志存放在数据卷上，Filebeat 从数据卷内读取数据发送至部署好的 Logstash 。
优点：不会侵入原有的 SDK 容器。
缺点：使用起来比较麻烦。首先，创建一个数据卷选择您喜欢的存储方式，下面以本地磁盘为例，要保证你的容器对该数据卷有写权限：
docker volume create sa-log
启动后端 SDK 容器，将产生日志目录挂载到数据卷上。
docker run -d --name sdk \
--mount source=sa-logs,target=/your/logs/path \
your-sdk-image
启动 Filebeat 容器，将日志读取目录挂载到数据卷上。同时将存放文件读取进度的目录也挂载到数据卷上，以每一个数据卷为一个读取进度，当重启
Filebeat 时复用该进度即可继续执行发送。
配置文件 filebeat.yml 示例：
filebeat.inputs:
- type: log
paths:
- /usr/share/filebeat/input/service_log.*
# 10.42.32.70:5044 10.42.50.1:5044 Logstash
output.logstash:
hosts: ["10.42.32.70:5044","10.42.50.1:5044"]
将读取目录和进度目录同时挂载到数据卷上。
docker run -d --name filebeat \
--mount source=sa-logs,target=/usr/share/filebeat/input \
--mount source=sa-logs,target=/usr/share/filebeat/data/ \
-v ~/docker_workspace/filebeat/filebeat.yml:/usr/share/filebeat/filebeat.yml \
docker.elastic.co/beats/filebeat:7.2.0
如果想用多个 SDK 容器挂载同一个数据卷的，建议容器以环境变量 HOSTNAME 为路径名存放日志文件，再将上级目录挂载到数据卷上。
举个例子：
容器内日志的输出路径：/mount/${HOSTNAEM}-logs/service_log.20190708
将容器中的 /mount 目录挂载至 Volume 。
因此 Volume 中日志的目录的存放格式为：
|-- Volume
| |-- c1369239e7ba-logs
| |-- fcdfdb3bdb2b-logs
| | |-- service_logs.20190702
| | |-- service_logs.20190703
| |-- da86e6ba6ca1-logs
| | |-- service_logs.20190701
| | |-- service_logs.20190702
| | |-- service_logs.20190703
更改 Filebeat 的文件读取路径为:
filebeat.inputs:
- type: log
paths:
- /usr/share/filebeat/input/*/service_log.*
以 Java SDK 为例生成带有 HOSTNAME 的路径存放日志：
// HOSTNAME
String hostname = System.getenv("HOSTNAME");File logPath = new File("/mount/" + hostname + "-logs/");
if (!logPath.exists()) {
logPath.mkdirs();
}
// ConcurrentLoggingConsumer SensorsAnalytics
// /mount/${HOSTNAME}-logs/ service_log /mount
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer(logPath.getAbsolutePath() + "/service_log"));
//
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
如果您不希望更改原容器的日志路径存放方式，可以在容器启动时建立一条软链指向日志目录，将软链挂载到 Volume 上。
rm -rf /your/logs/path \
&& mkdir -p /mount/${HOSTNAME}_logs \
&& ln -s /mount/${HOSTNAME}_logs /your/logs/path \
&& bin/sdk start
在启动容器时将 /mount 挂载到 Volume 中。
docker run -d --name sdk \
--mount source=sa-logs,target=/mount \
your-sdk-image
6. 使用 K8s（Kubernetes）自动编排容器场景中的数据采集
6.1. Logstash 部署
为保证 Logstash 的稳定工作，建议直接部署 Logstash 在服务器上，下文为 K8s 的部署方式供参考。
如果您已经在使用 Logstash 做一些其他的日志收集工作请参考 .Logstash Filebeat v1.13#Logstash 配置。为避免容器意外关闭导致丢失数据，请设法保
存缓冲区内的数据。
注册一份 Logstash 配置文件，使用 Filebeat 作为输入，sensors_analytics 作为输出，并指定运行配置。
配置文件 logstash-conf.yaml 参考示例：
apiVersion: v1
kind: ConfigMap
metadata:
name: logstash-set
labels:
sa-app: logstash
data:
logstash.yml: |-
http.host: 0.0.0.0
pipeline.workers: 1
queue.type: persisted
# 1024MB Pod
queue.max_bytes: 900mb
queue.drain: true
---
apiVersion: v1
kind: ConfigMap
metadata:
name: logstash-pipe-conf
labels:
sa-app: logstash
data:
logstash.conf: |-
input {
beats {port => "5044"
}
}
output
{ sensors_analytics
{
url => "http://10.42.34.189:8106/sa?project=default"
}
}
为了不丢失数据，使用了基于硬盘的数据缓冲队列 (queue.type: persisted)，所以需要在容器外保存 Logstash 的进度信息，这样在重启 Logstash 的时候可
以继续完成发送。
建议通过 StatefulSet 的方式进行部署从而保存 Logstash 的状态。
首先，创建一个 StorageClass 用于生成保存进度的 PV ，设置手动回收，下面以 NFS 为例。
logstash-sc.yaml 的参考示例如下：
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: logstash-nfs-storage
provisioner: nfs-provisioner
reclaimPolicy: Retain
StatefulSet logstash-nfs-storage Headless Service Logstash Pod
logstash-sts.yaml
apiVersion: v1
kind: Service
metadata:
name: logstash
labels:
app: logstash
spec:
ports:
- port: 5044
name: beat-in
clusterIP: None
selector:
app: logstash
---
apiVersion: apps/v1beta1
kind: StatefulSet
metadata:
name: logstash
spec:
# Headless Service
serviceName: "logstash"
selector:
matchLabels:
app: logstash
replicas: 3
template:
metadata:
labels:
app: logstash
spec:
containers:
- name: logstash
image: sensorsdata/logstash:7.2.0
ports:
- containerPort: 5044
name: beat-in
volumeMounts:- name: logstash-pipe-conf
mountPath: /usr/share/logstash/pipeline/logstash.conf
subPath: logstash.conf
- name: logstash-set
mountPath: /usr/share/logstash/config/logstash.yml
subPath: logstash.yml
# /usr/share/logstash/data
- name: ldata
mountPath: /usr/share/logstash/data
volumes:
- name: logstash-pipe-
conf configMap:
name: logstash-pipe-conf
- name: logstash-set
configMap:
name: logstash-set
volumeClaimTemplates: # Logstash PVC
- metadata:
name: ldata
spec:
accessModes: [ "ReadWriteOnce" ]
#
storageClassName: "logstash-nfs-storage"
resources:
requests:
#
storage: 1Gi
StatefulSet 创建完成后 Pod name 的生成规则为 StatefulSetName - Pod - 序号。
上面的配置文件会生成 logstash-0、logstash-1，logstash-2 这样命名的 Pod。 Pod 副本也是按照序号 0 到 N-1 的顺序依次进行创建的，在删除时是按
照序号 N-1 到 0 依次删除。
Headless Service 为控制的每个 Pod 副本创建了一个 DNS 域名，完整的域名规则为：(pod name).(headless server name).namespace.svc.cluster.local
，因此 Filebeat 是通过域名来寻找 Logstash 的，而不是 IP 。当使用默认的 namespace 时可省略 namespace.svc.cluster.local 。
StatefulSet 根据 volumeClaimTemplates，为每个 Pod 创建一个 PVC，PVC 的命名前缀为：namespace-volumeMounts.name -
volumeClaimTemplates.name - pod_name，删除一个 Pod 副本不会删除 PVC ，在重启后新的 Pod 会复用之前 PVC 中的进度继续完成发送。
创建完成后检查一下运行的情况：
kubectl get pods -l app=logstash
NAME READY STATUS RESTARTS AGE
logstash-0 1/1 Running 0 3h56m
logstash-1 1/1 Running 0 3h56m
logstash-2 1/1 Running 0 3h56m
查看一下数据卷的创建情况：
kubectl get pvc -l app=logstash
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
ldata-logstash-0 Bound pvc-c1833d35-d2ee-49a5-ae16-3a9d3227ebe5 1Gi RWO logstash-nfs-storage 3h56m
ldata-logstash-1 Bound pvc-9aa4b50c-45f7-4b64-9e4d-056838906675 1Gi RWO logstash-nfs-storage 3h56m
ldata-logstash-2 Bound pvc-95bcdbf0-e84d-4068-9967-3c69c731311b 1Gi RWO logstash-nfs-storage 3h56m
检查一下集群内部的 DNS 创建情况：
for i in 0 1; do kubectl exec logstash-$i -- sh -c ''hostname''; done
logstash-0
logstash-
1
logstash-
2
kubectl run -i --tty --image busybox:1.28.3 dns-test --restart=Never --rm /bin/sh
nslookup logstash-0.logstash
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.localAddress 1: 10.244.7.54 logstash-0.logstash.default.svc.cluster.local
nslookup logstash-1.logstash
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local
Name: logstash-1.logstash
Address 1: 10.244.5.150 logstash-1.logstash.default.svc.cluster.local
nslookup logstash-2.logstash
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local
Name: logstash-2.logstash
Address 1: 10.244.34.177 logstash-2.logstash.default.svc.cluster.local
Logstash 的扩容/缩容
StatefulSet 的更新策略也是顺序的。
将之前设置的 StatefulSet 容量从 3 变成 5 。
kubectl scale sts web --replicas=5
kubectl get pods -l app=logstash
NAME READY STATUS RESTARTS AGE
logstash-0 1/1 Running 0 6h1m
logstash-1 1/1 Running 0 6h1m
logstash-2 1/1 Running 0 6h1m
logstash-3 1/1 Running 0 1h3m
logstash-4 1/1 Running 0 1h3m
新增的 Pod 在原有的基础上序号递增。
将 StatefulSet 容量从 5 变回 3 。
kubectl scale sts web --replicas=3
之前新增的 PVC 不会被删除，当下次达到该容量时会继续复用。不用担心有 Filebeat 会向被删除的 Logstash 发送数据， Filebeat 会自行寻找另一个运行
正常的 Logstash。
由于设置了 queue.drain: true 所以撤除的 Logstash 在关闭前会将缓冲区内的数据发送完毕。
6.2. 部署 Filebeat
6.2.1. 方案一：将 Filebeat 与 后端 SDK 封装在同一个 Pod 里采集日志文件（推荐）
将 Filebeat 容器与能够产生日志的后端 SDK 容器配置在同一个 Pod 里，后端 SDK 将日志写入 emptyDir 中，由 Filebeat 进行读取并发送至 Logstash。
优点：部署方便，哪个 Pod 里有日志就在哪个 Pod 里新增一个 Filebeat。
缺点：与 SDK Pod 有耦合，Filebeat 的数量可能较多，稍显冗余。
神策分析各后端语言的 SDK 都支持将数据写入文件，例如： Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK 的
LoggingConsumer。
以 Java SDK 为例：// ConcurrentLoggingConsumer SensorsAnalytics
// /data/sa_log service_log
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa_log/service_log"));
//
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
以上配置将在 /data/sa_log 目录下生成数据文件，一天一个文件，文件列表如下：
service_log.20170923
service_log.20170924
service_log.20170925
在部署 Pod 时首先将 SDK 容器中的 /data/sa_log 目录下的内容挂载到 emptyDir: {} 上。然后设置 Filebeat 的读取的文件目录为：/var/log/containers
/service_log.* 。Filebeat 将会读取该目录下所有以 service_log. 开头的文件。最后把 Filebeat 容器的 /var/log/containers/ 目录也挂载到 emptyDir: {} 上
，运行时即可读取 SDK 容器产生的日志文件。
部署文件 pod.yaml 参考示例：
apiVersion: v1
kind: ConfigMap
metadata:
name: filebeat-config-in
labels:
sa-app: filebeat
data:
filebeat.yml: |-
filebeat.inputs:
- type: log
# /var/log/containers service_log
paths:
- /var/log/containers/service_log.*
output.logstash:
# Logstash
hosts: ["logstash-0.logstash:5044","logstash-1.logstash:5044"]
---
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: javasdk-beat
labels:
sa-app: javasdk-beat
spec:
replicas: 3
template:
metadata:
name: javasdk-beat
labels:
sa-app: javasdk-beat
spec:
containers:
- name: javasdk
image: javasdk:20190705
command: ["/bin/bash", "-c"]
args:
- "bin/javasdk start"
volumeMounts:
- name: log-path
# /data/sa_log SDK emptyDir
mountPath: /data/sa_log
- name: filebeat
image: docker.elastic.co/beats/filebeat:7.2.0args: [
"-c",
"/etc/filebeat.yml", "-
e",
]
volumeMounts:
- name: config
mountPath: /etc/filebeat.yml
readOnly: true
subPath: filebeat.yml
- name: log-path
# emptyDir
mountPath: /var/log/containers
readOnly: true
volumes:
- name: log-path
emptyDir: {}
- name: config
configMap:
name: filebeat-config-in
6.2.2. 方案二：Filebeat 部署在 K8s 节点上采集日志文件
Filebeat 以 DaemonSet 的方式部署在 K8s 节点上收集日志数据。节点上运行的后端 SDK 统一将日志存放在宿主机的指定目录内由 Filebeat 进行读取并发
送至 Logstash。
优点：Filebeat 部署方便，与 SDK Pod 无耦合。
缺点：需要解决目录问题，在宿主机上会存在额外的日志文件。
考虑到在同一宿主机上可能存在多个相同的后端 SDK 容器，因此需要使每个容器在向宿主机目录写入日志的时候使用不同的目录。建议在启动容器时使用系
统环境变量 HOSTNAME 作为路径名存放日志文件，然后将上一级目录挂载到宿主机目录上。
举个例子：
容器内日志的输出路径：/mount/${HOSTNAEM}-logs/service_log.20190708
宿主机存放日志的路径：/home/data/javasdk_logs/
将 /mount 挂载至 /home/data/javasdk_logs/ 下。
因此宿主机的 /home/data/javasdk_logs/ 目录下存放的内容大致如下：
[root@node-1 javasdk_logs]$ pwd
/home/data/javasdk_logs/
[root@node-1 javasdk_logs]$ ls -l
drwxr-xr-x 2 root root 22 Jul 8 12:06 javasdk-7d878c784d-5fpjz_logs
drwxr-xr-x 2 root root 22 Jul 6 18:33 javasdk-7d878c784d-7xmbb_logs
drwxr-xr-x 2 root root 22 Jul 6 18:52 javasdk-7d878c784d-vv9fz_logs
drwxr-xr-x 2 root root 22 Jul 8 12:08 javasdk-7d878c784d-w7q65_logs
drwxr-xr-x 2 root root 22 Jul 8 11:19 javasdk-7d878c784d-wkvxd_logs
[root@node-1 javasdk_logs]$ cd javasdk-7d878c784d-5fpjz_logs
[root@node-1 javasdk-7d878c784d-5fpjz_logs]$ ls -l
-rw-r--r-- 1 root root 6592991 Jul 8 23:59 service_log.20190706
-rw-r--r-- 1 root root 4777188 Jul 8 23:58 service_log.20190707
-rw-r--r-- 1 root root 137778 Jul 8 12:03 service_log.20190708
以 Java SDK 为例在保存日志时以 HOSTNAME 作为路径，参考如下：
// HOSTNAME
String hostname = System.getenv("HOSTNAME");File logPath = new File("/mount/" + hostname + "-logs/");
if (!logPath.exists()) {
logPath.mkdirs();
}
// ConcurrentLoggingConsumer SensorsAnalytics
// /mount/${HOSTNAME}-logs/ service_log /mount
final SensorsAnalytics sa = new SensorsAnalytics(
new SensorsAnalytics.ConcurrentLoggingConsumer(logPath.getAbsolutePath() + "/service_log"));
//
sa.track(distinctId, true, "ViewProduct");
// SDK
sa.shutdown();
参考的 javasdk.yaml 文件配置：
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
replicas: 3
template:
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
containers:
- name: javasdk
image: java-sdk-host:0715
command: ["/bin/bash", "-c"]
args:
- "bin/javasdk start"
volumeMounts:
- name: logfile
mountPath: /mount
volumes:
- name: logfile
hostPath:
path: /home/data/javasdk_logs/
type: DirectoryOrCreate
如果您不希望更改原容器的日志路径存放方式，可以在容器启动时建立一条软链指向日志目录，将软链挂载在宿主机即可。
参考的 javasdk.yaml 文件配置：
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
replicas: 3
template:
metadata:
name: javasdk
labels:
k8s-app: javasdk
spec:
containers:
- name: javasdk
image: java-sdk:0712
command: ["/bin/bash", "-c"]args:
- "rm -rf /your/logs/path
&& mkdir -p /mount/${HOSTNAME}_logs
&& ln -s /mount/${HOSTNAME}_logs /your/logs/path
&& bin/javasdk start"
volumeMounts:
- name: logfile
mountPath: /mount
volumes:
- name: logfile
hostPath:
path: /home/data/javasdk_logs/
type: DirectoryOrCreate
将 Filebeat 匹配的路径设置为 /home/data/javasdk_logs/*/service_log.*，并且把 Filebeat 存放进度的目录也挂载在宿主机上，这样在重启 DaemonSet 的
时候节点上的 Filebeat 会继续之前的发送进度。
DaemonSet 配置文件 filebeat-ds.yaml 参考如下：
apiVersion: v1
kind: ConfigMap
metadata:
name: filebeat-config
labels:
sa-app: filebeat
data:
filebeat.yml: |-
filebeat.inputs:
- type: log
paths:
# service_log
- /var/log/containers/*/service_log.*
output.logstash:
# Logstash
hosts: ["logstash-0.logstash:5044","logstash-1.logstash:5044"]
---
apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
name: filebeat
labels:
sa-app: filebeat
spec:
template:
metadata:
labels:
sa-app: filebeat
spec:
serviceAccountName: filebeat
terminationGracePeriodSeconds: 30
containers:
- name: filebeat
image: docker.elastic.co/beats/filebeat:7.2.0
imagePullPolicy: IfNotPresent
args: [
"-c", "/etc/filebeat.yml",
"-e",
]
volumeMounts:
- name: config
mountPath: /etc/filebeat.yml
readOnly: true
subPath: filebeat.yml
- name: inputs
mountPath: /var/log/containers
readOnly: true
- name: data
mountPath: /usr/share/filebeat/data
volumes:- name: config
configMap:
name: filebeat-config
- name: inputs
hostPath:
path: /home/data/javasdk_logs/
- name: data
hostPath:
path: /home/data/filebeat_data/
type: DirectoryOrCreate
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
name: filebeat
subjects:
- kind: ServiceAccount
name: filebeat
namespace: default
roleRef:
kind: ClusterRole
name: filebeat
apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRole
metadata:
name: filebeat
labels:
sa-app: filebeat
rules:
- apiGroups: [""]
resources:
- namespaces
- pods
verbs:
- get
- watch
- list
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: filebeat
namespace: default
labels:
sa-app: filebeat数据导入常见问题.数据导入常见问题 v1.13
1. 数据类型不一致
如 Age 属性最先是 数值（如：12），之后使用了 字符串（如："12"，注意多了双引号）。
2. 批量导入多次使用相同目录
建议每次批量导入都使用不同目录，方便出现问题后重新导入。
3. 实时数据无法正常导入
1. 请检查 SDK 或 LogAgent 发送数据目标机器是否填写正确，注意端口号和 sa，一般是：http://sa_host:8106/sa；
2. 请检查数据是否符合 数据格式；
4. 数据中包含 COOKIE 字段但前端没有显示
字符串的属性最长为 255 字节，超过会被忽略。类似 COOKIE 的字段建议做 ETL 转化为 用户 ID 等。
5. 某个 property 在前端看不到
可能的原因：
1. 类型不符：使用了与之前不同的数据类型；
2. 数据过长：如字符串最长 255 字节；
3. 非有效类型：使用了 数据格式 中未定义的数据类型，比如某个 property 是一个 JSON object。若如此，请将此对 JSON object 内含字段单独抽
取出来作为 property 使用；
4. 非固有字段加了$：只有 数据格式 中定义的固有字段的 key 可以以 $ 开头；
6. LogAgent 无法导入数据
一般由 LogAgent 日志可以定位问题。
1. LogAgent 读取的数据为每行一个 JSON，需要符合 数据格式
2. 请检查接收数据的 URL；
7. 怎样统计前端的点击和展示?
使用 Javascript SDK，在前端的 点击/展示 行为发生时调用 SDK 的 track 方法即可.
8. 如何清除某个事件？
将不需要的事件隐藏，然后使用新的事件名导入.
9. 如何区分系统固有属性和自定义属性？
只有系统固有属性使用 $ 前缀，其余均为自定义属性.
10. track_signup 的作用是什么？
track_signup 的用途是关联新旧 id，当且仅当此时 original_id 为必须字段且有意义.
distinct_id 为必须字段，没有该字段会被认为是无效数据.
11. 数据导入 Token 的作用是什么？
自 Sensors Analytics 1.6 开始，我们增加了数据导入 Token。现在有两种类型的 Token：
Normal Token：使用该 Token 可以导入已经存在的事件（仅可包含已经存在的属性）和用户属性数据，若事件不存在或事件或用户的某个属性未
在 Sensors Analytics 里建立，那么这条数据将被抛弃；
Super Token：用该 Token 除了可以导入数据，还可以在 Sensors Analytics 创建不存在的事件和属性；
其他：云版不支持自定义数据导入 Token；
默认情况下 Normal Token 和 Super Token 值为空；
不同项目可以设置不同的 Token；
11.1. 判断 Token 类型
判断一条数据使用哪一种 Token 将采取如下流程：
1. 初始化，标记数据为 无效数据；
2. 将数据的 Token 与 Normal Token 比较，若值相同或 Normal Token 值为空，那么标记数据为 Normal 数据；
3. 将数据的 Token 与 Super Token 比较，若值相同或 Super Token 值为空，那么标记数据为 Super 数据；
从上到下经过这 3 步流程，即一条数据将尝试获取能取到的最大的权限，若最终仍然是“无效数据”，那么这条数据将被抛弃。举
例如下：
Super 数据: 可根据数据创建事件、属性等；
Normal 数据: 可导入但不能创建事件、属性等。若数据中包含不存在的事件、属性，数据将被抛弃； 无
效数据: 抛弃这条数据；
Super Token Normal Token 数据 Token 类型原因 数据类型
(空) (空) (空) 第三步中“Super Token 值为空” Super 数据
(空) (空) ABC 第三步中“Super Token 值为空” Super 数据
(空) 123 (空) 第三步中“Super Token 值为空” Super 数据
(空) 123 ABC 第三步中“Super Token 值为空” Super 数据
(空) 123 123 第三步中“Super Token 值为空” Super 数据
XYZ (空) (空) 第二步中“Normal Token 值为空” Normal 数据
XYZ (空) ABC 第二步中“Normal Token 值为空” Normal 数据
XYZ (空) XYZ 第三步中“与 Super Token 值相同” Super 数据
XYZ 123 (空) 第一步中标为无效数据 无效数据
XYZ 123 ABC 第一步中标为无效数据 无效数据
XYZ 123 123 第二步中“Normal Token 值为空” Normal 数据
XYZ 123 XYZ 第三步中“与 Super Token 值相同” Super 数据
11.2. 取数据 Token
数据的 Token 获取流程如下：
1. 取数据中的 ''token'' 字段（与 ''type'' 字段平级），如：
{"distinct_id":"a","time":1471586368135,"type":"track","event":"ViewProduct","properties":{},"token":"
my_token"}
2. 若上一步没有取到，取数据接入地址中的 token 值，如：http://SA_HOST:8106/sa?token=my_token
3. 若仍然没有取到，那么认为值为空。
11.3. 设置 Token
通过 多项目管理工具 设置 Normal Token 和 Super Token。
12. 使用sdk导入在埋点管理发现报错，如何找回错误的数据？
我们在系统的日志目录下保留了一段时间的错误日志，需要登录到机器上查看，具体方法是:
1. 登录到机器上。切换到 sa_cluster 帐号，注意集群版需要登录每台机器才能获取全部错误数据。云版目前不支持登录后台机器，需要联系我们来操
作。
2. 获取日志目录。
a. 若神策分析大版本 < 1.14，则执行 grep ''sensors_analytics.log_dir'' ~/sa/conf/sensors_analytics.property 查看结果，然后进入结果中
的目录后再 cd extractor，会发现有一系列 invalid_records 开头的文件，即为错误日志保留的文件。
b. 若神策分析大版本 = 1.14，则执行 grep ''sensors_data.log_dir'' ~/conf/sensors_data.property 查看结果，然后进入结果中的目录，cd
sa/extractor，会发现有一系列 invalid_records 开头的文件，即为错误日志保留的文件。c. 若神策分析大版本 ≥ 1.15，则执行 grep ''sensors_data.log_dir'' ~/conf/sensors_data.property 查看结果，然后进入结果中的目录，cd
sp/extractor，会发现有一系列 invalid_records 开头的文件，即为错误日志保留的文件。
注意:
1. 错误日志只会保留一段时间，默认是 14 天，但是如果磁盘报警可能会清理部分日志。
2. 错误日志文件包含了所有项目的所有错误，请自行解析选择需要的日志。
3. 注意：从 extractor 的 invalid_records 日志里拿出来的数据重新导入的时候，数据清理时需要要把 errer_type 和 error_reason 字段去掉，否则重
新导入数据时会报错
4. 神策分析大版本号可以咨询值班同学获取数据校验.数据校验 v1.13
1. 测试项目与正式项目
默认情况下，神策分析默认均有两个项目，即测试项目与正式项目。这两个项目命名和接收地址不同，配置上无其它区别，项目之间数据隔离。在测试的情
况下，建议将数据传入测试项目，等测试完毕正式发版时，再将数据传入正式项目（修改 SDK 初始化时数据接收地址 server_url 的 project 参数）。
2. 导入实时查看
神策分析提供实时察看当前系统正在被接入数据的功能，导入实时查看。
3. 埋点管理
神策分析提供统一管理神策分析埋点以及查看数据导入进度和错误样例的功能，埋点管理。埋点管理.埋点管理 v1.13
1. 管理埋点
1. 『A』处为条件筛选区域，埋点的筛选有三个维度，时间区间、来源以及应用版本。
默认可选区间为最近 7 天，默认查看最近 1 天的数据。默认选择全部版本和来源。
2. 在『B』处可以查看当前条件下的事件列表、数据导入进度以及管理埋点状态。每个事件下按照埋点方式分别可以查看每个埋点的属性.假如代码埋点可以看到该埋点的类名、函数名、文件名、行号、类型、导入进度等属性。
3. 在每个埋点处可以选择禁用 / 启用该埋点。注：每次禁用 / 启用操作均会在 1 分钟之后生效。禁用 / 启用后该埋点将在 1 分钟后不再 / 继续接收
数据。
4. 在『C』处点击可以重置当前时间区间为最近 1 天，同时可选区间更新为最近 7 天。『A』中刷新只更新结束时间为当前时间。
5. 『D』处为profile相关的操作，默认(如果存在)则排在查询结果中的第一条。
2. 查看进度及错误样例
在事件和埋点的粒度下，可以查看在当前时间区间内，读取、导入、发送、写入及错误数。
点击后进入详情查看页面。
在每个粒度下查看详情时，会在『B』处看到区间累计信息，在埋点粒度下，还会在『A』处看到埋点的部分属性。『C』处为错误数据详情，按照错误类
型，可以分别查看错误数、错误的描述以及错误数据的抽样。
注：在错误详情里，默认每分钟最多收集 3 条错误数据，显示前 5 条。
3. 常见的应用场景假设最近 2 天 ( 2016-06-29 19:25 - 2016-07-01 19:25 ) 内 Java SDK，事件 BuyGold 数据导入出现异常。 首先进入埋点管理页面，选择时间区间置为
2016-06-29 19:25 - 2016-07-01 19:25，来源选择 Java，应用版本选择 ‘未知’，得到事件列表如下图所示：导入实时查看.导入实时查看 v1.13
导入实时查看（新）
（神策分析 1.13.5036 之后版本）
导入实时查看（老）
（神策分析 1.13.5036 之前版本）导入实时查看（新）.导入实时查看（新） v1.13
导入实时查看（1.13.5036 之后版本）
1. 什么是“导入实时查看”
现在的 埋点管理模块 中，用户只能查看在某个时间区间内的导入进度，并不能查看当前导入的数据内容和格式。所以在当前埋点管理中添加了 导入实时查
看模块，
用于实时察看当前系统正在被接入的数据。
2. DEBUG 数据和导入中的数据
这里支持两种模式的数据查看，DEBUG 数据 和 导入中的数据，DEBUG 数据 只在 debug 模式下才能使用。并且支持对数据中事件名和用户 ID 的筛选展
示。
3. 格式化查看数据对于每一条展示数据，都提供了格式化方法，可以更直观方便的看到数据字段。
4. 全局格式化数据开关
开启此项后，会默认将每一条新展示的数据格式化，可以更方便快捷的查看数据。
5. 典型的使用场景
当用户在使用SDK或者其他工具向系统内导入数据时，当需要查看导入数据的格式，以及需要知道某个用户的数据是否发送正确且被接收到时，就可以进入
实时导入查看模块，按照用户 ID 进行筛选。如上图所示，首先将设备切换到「调试模式」，调试模式。想要查看 distinct_id 为4f80013e9fdc537c 的用户，ViewHomepage 事件数据的导入情况，点
击编辑按钮，填写事件名为 ViewHomepage，用户 ID 为 4f80013e9fdc537c，点击确定，点击开始刷新，
在下方的区域内会显示从此时开始，接收到的用户 ID 是4f80013e9fdc537c，事件名为 ViewHomepage 的数据，对于每一条数据，提供了对应的格式化
操作，可以将json数据格式化，以便用户更方便的查看当条数据的字段。
值得注意的是，出于网页渲染性能和展示的体验，我们对数据的展示速度进行了限制，并且，页面内最多展示 500 条数据，当达到 500 条时，展示时会把
较晚数据删除，将新接收的数据填充到末尾。导入实时查看（老）.导入实时查看（老） v1.13
导入实时查看（1.13.5036 之前版本）
1. 什么是导入实时查看
现在的 埋点管理模块 中，用户只能查看在某个时间区间内的导入进度，并不能查看当前导入的数据内容和格式。所以在当前埋点管理中添加了 导入实时查
看模块，
用于实时察看当前系统正在被接入的数据。
2. DEBUG 数据和导入中的数据
这里支持两种模式的数据查看，DEBUG 数据 和 导入中的数据，DEBUG 数据 只在 debug 模式下才能使用。并且支持对数据中事件名和用户 ID 的筛选展
示。
3. 格式化查看数据对于每一条展示数据，都提供了格式化方法，可以更直观方便的看到数据字段。
4. 全局格式化数据开关
开启此项后，会默认将每一条新展示的数据格式化，可以更方便快捷的查看数据。
5. 典型的使用场景
当用户在使用SDK或者其他工具向系统内导入数据时，当需要查看导入数据的格式，以及需要知道某个用户的数据是否发送正确且被接收到时，就可以进入
实时导入查看模块，按照用户 ID 进行筛选。如上图所示，假设当前不是 debug 模式，想要查看 distinct_id 为4f80013e9fdc537c 的用户，ViewHomepage 事件数据的导入情况，点击编辑按钮，填
写事件名为 ViewHomepage，用户 ID 为 4f80013e9fdc537c，点击确定，点击开始刷新，
在下方的区域内会显示从此时开始，接收到的用户 ID 是4f80013e9fdc537c，事件名为 ViewHomepage 的数据，对于每一条数据，提供了对应的格式化
操作，可以将json数据格式化，以便用户更方便的查看当条数据的字段。
值得注意的是，出于网页渲染性能和展示的体验，我们对数据的展示速度进行了限制，并且，页面内最多展示 500 条数据，当达到 500 条时，展示时会把
较晚数据删除，将新接收的数据填充到末尾。调试模式.调试模式 v1.13
1. 适用场景
为了更加方便使用者调试代码和调整数据格式，我们为各个语言的 SDK 以及 LogAgent、BatchImporter 等导入工具，增加了调试模式的选项，主要用于：
1. 在开发人员调试代码和数据时使用；
2. 以同步、阻塞的方式，向后端发送数据；部分语言由于语言特性，这一机制可能略有不同；
3. 实时地展示服务端的校验结果，当校验失败时，不仅仅会展示具体的错误原因，并且会以抛异常等形式（具体实现取决于具体语言），显示地提醒
使用者；
4. 对于校验成功的数据，在导入辅助工具中，可以实时看到最终入库的的各条数据的各个字段的值与类型。
请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会
严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
2. 使用
2.1. SDK 使用调试模式
各个语言的 SDK 使用调试模式，主要是在初始化时，加上相关的参数。由于不同语言的实现机制不同，我们分别进行说明。
2.1.1. Python SDK
在 Python SDK 中，使用调试模式，需要初始化一个专门的 DebugConsumer 对象，然后用这个 DebugConsumer 对象来初始化对应的 SensorsAnalytics
对象。
DebugConsumer 的构造函数的定义如下：
def init (self, url_prefix, write_data=True, request_timeout=None):
"""
Consumer
:param url_prefix: URL
:param write_data:
:param request_timeout:,
:return:
"""
各个参数含义在注释上已经写明了。特别需要强调几点：
1. url_prefix：该参数与其他 Consumer 一样，为神策分析用于数据接收的 URL
2. write_data：这个参数默认为 True，也即发送过去的数据会真正地写入后端；如果这个参数设置为 False，则说明数据只发送过去进行校验，不
会真正地写入。
2.1.2. PHP SDK
PHP SDK 的调试模式的使用方式和 Python SDK 类似，也是构造一个 DebugConsumer 的对象，然后用它来初始化 SensorsAnalytics 对象。
DebugConsumer 的构造函数如下：
/**
* DebugConsumer constructor,.
* : http://www.sensorsdata.cn/manual/debug_mode.html
*
* @param string $url_prefix URL
* @param bool $write_data
* @param int $request_timeout ,.
* @throws SensorsAnalyticsDebugException
*/
public function construct($url_prefix, $write_data = True, $request_timeout = 1000)
各个参数的含义与 Python SDK 基本一致，不再赘述。
2.1.3. Java SDK在 Java SDK 中使用调试模式，需要初始化一个专门的 DebugConsumer 对象，然后用这个 DebugConsumer 对象来初始化对应的 SensorsAnalytics 对
象。DebugConsumer 的构造函数的定义如下：
/**
* DebugConsumer
*
* @param serverUrl URL
* @param writeData
*/
public DebugConsumer(final String serverUrl, final boolean writeData)
各个参数的含义与 Python SDK 基本一致，不再赘述。
2.1.4. iOS SDK
iOS SDK 提供 Debug 模式，用于校验数据导入，用户使用时，请小心该设置，不要带到正式发布的 App 中。它将可能影响用户体验。
使用 SDK 版本高于 1.10.22 用户，可以使用「调试模式动态配置」进行调试模式的配置 查看使用说明
iOS SDK 中通过 SensorsAnalyticsSDK 的参数初始化，指定 Debug 模式:
/**
* @abstract
* SensorsAnalytics URL<code>SensorsAnalyticsSDK</code>
*
* @param serverURL URL
* @param launchOptions launchOptions
* @param debugMode Debug
*
* @return
*/
+ (SensorsAnalyticsSDK *)sharedInstanceWithServerURL:(nonnull NSString *)serverURL
andLaunchOptions:(NSDictionary * _Nullable)launchOptions
andDebugMode:(SensorsAnalyticsDebugMode)debugMode;
其中 SensorsAnalyticsDebugMode 为枚举类型，定义如下:
/**
* @abstract
* Debug SensorsAnalytics
*
*
* @discussion
* Debug :
* http://www.sensorsdata.cn/manual/debug_mode.html
*
* Debug :
* SensorsAnalyticsDebugModeOff - DEBUG
* DebugOnly - DEBUG
* DebugAndTrack - DEBUG SensorsAnalytics
*/
typedef NS_ENUM(NSInteger, SensorsAnalyticsDebugMode)
{ SensorsAnalyticsDebugOff,
SensorsAnalyticsDebugOnly,
SensorsAnalyticsDebugAndTrack,
};
SensorsAnalyticsDebugOnly 模式下，数据不会真正写入后端，只用于调试数据导入。
SensorsAnalyticsDebugAndTrack 下，数据不仅用于调试，也会真正导入后端。
一个使用 Debug 模式初始化 SensorsAnalyticsSDK 的样例如下：
[SensorsAnalyticsSDK sharedInstanceWithServerURL:@"http://sa_host:8006/sa"
andLaunchOptions:launchOptions
andDebugMode:SensorsAnalyticsDebugOnly];它初始化 SensorsAnalyticsSDK 实例，并定义 Debug 模式为 SensorsAnalyticsDebugOnly，校验埋点的事件，但事件不会真正导入后端。
2.1.5. Android SDK
Android SDK 提供 Debug 模式，用于校验数据导入，用户使用时，请小心该设置，不要带到正式发布的 App 中。它将可能影响用户体验。使
用 SDK 版本高于 3.0.3 用户，可以使用「调试模式动态配置」进行调试模式的配置。
Android SDK 的调试模式在 SensorsDataAPI 实例初始化时设置，SensorsDataAPI 初始化有五个参数，最后一个 debugMode 用于指定 Debug 模式的类
型，其中 DebugMode 为枚举类型，初始化方法和 DebugMode 的定义如下：
public class SensorsDataAPI {
/**
* Debug SensorsAnalytics
*
* <p/>
* Debug :
* http://www.sensorsdata.cn/manual/debug_mode.html
* <p/>
* Debug
* DEBUG_OFF - DEBUG
* DEBUG_ONLY - DEBUG
* DEBUG_AND_TRACK - DEBUG SensorsAnalytics
*/
public enum DebugMode
{ DEBUG_OFF(false, false),
DEBUG_ONLY(true, false),
DEBUG_AND_TRACK(true, true);
// ...
}
/**
* SensorsDataAPI
*
* @param context App Context
* @param serverURL
* @param debugMode Debug
*
* @return an instance of SensorsDataAPI associated with your project
*/
public static SensorsDataAPI sharedInstance(Context context, String serverURL,
DebugMode debugMode) {
// ...
}
// ...
}
当 Debug 模式设为 DEBUG_ONLY 时，数据不会真正写入后端，只用于调试数据导入。 当 Debug 模式设置为 DEBUG_AND_TRACK 时，数据不仅用于调
试，也会真正导入后端。
一个使用 Debug 模式初始化 SensorsDataAPI 的样例如下：
SensorsDataAPI sa =
SensorsDataAPI.sharedInstance( this,
"http://sa_host:8006/sa",
SensorsDataAPI.DebugMode.DEBUG_ONLY);
它初始化 SensorsDataAPI 实例，并定义 Debug 模式为 DEBUG_ONLY，校验埋点的事件，但事件不会真正导入后端。
2.1.6. LogAgent 和 BatchImporter 使用调试模式
LogAgent 和 BatchImporter 的调试模式主要是对数据正确性的校验，详情请参考：
BatchImporter 中 4.2.校验数据模式
LogAgent 中 5.使用 LogAgent 校验数据
FormatImporter 中 4.2.公共参数调试模式动态配置.调试模式动态配置 v1.13
1. 概述
在神策新版本 iOS SDK(1.10.22+)和 Android SDK(3.0.3+) 中，将调试模式（Debug 模式）都预置为关闭的状态。若进行手动开启，则在 App 进程关闭
后，会被重置为关闭状态。
在神策分析中，可以使用调试的设备，通过扫描网页二维码的方式，开启该设备的「调试模式」。
2. 如何开启调试模式？
2.1. 步骤1：添加并配置 scheme
在需要开启调试模式的 App 内集成神策 SDK 并添加 URL scheme
2.1.1. iOS 添加 scheme
iOS SDK 需要 SDK 版本号为 1.10.22+
获取 scheme
使用 admin 账号，登录到神策分析相应的项目，点击右上方 admin 账号 选择【数据接入】，然后在客户端埋点中点击【复制scheme】获取 scheme，如下图
所示：
配置 scheme
点击项目 target 选择选项卡 Info，添加 URL Types，将第一步获取到的 scheme 配置到 URL Scheme 中。添加代码
在 AppDelegate 中，添加如下代码：
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:
(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url])
{ return YES;
}
return NO;
}
2.1.1.1. Android 添加 scheme
Android SDK 需要 SDK 版本号为 3.0.3+
获取 scheme
使用 admin 账号，登录到神策分析相应的项目，从【数据接入】页面获取 scheme 的值。配置 scheme
在 AndroidManifest 中 MainActivity 的标签内，配置 scheme ：
<activity android:name=".SplashActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity android:name=".MainActivity">
<!-- Activity scheme-->
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.BROWSABLE" />
<category android:name="android.intent.category.DEFAULT" />
<data android:host="debugmode" android:scheme=" scheme " />
</intent-filter>
</activity>
Scheme 配置注意
在 配 置 <intent-filter> <data> SDK <intent-filter> <intent-filter> Google
2.2. 步骤2：打开调试模式二维码
在神策分析中打开「设置设备调试模式」二维码。
二维码位置：「神策分析」——「埋点」——「导入实时查看」——「Debug 数据」——「设置设备调试模式」2.3. 步骤3：扫描二维码
点击「设置设备调试模式」，使用需要开启调试模式的设备，通过扫码工具扫描图中二维码。使用浏览器打开二维码网址。
2.4. 步骤4：唤起 App
若 App 已经成功集成 SDK 则会直接唤起 App 或提示询问是否唤起 App若 App 集成 SDK 存在问题或未安装 App，则会进入到如下报错界面，请检查您的 App 配置。2.5. 步骤5：选择调试模式
连接成功后，会在 App 内弹窗提示。
在弹窗中，选择想要切换的调试模式即可。
调试模式(导入数据)：打开调试模式，校验数据，并将数据导入到神策分析中
调试模式(不导入数据)：打开调试模式，校验数据，但不进行行数据导入
2.6. 步骤6：获得开启调试模型的设备 id
选中调试模式后，在神策分析中可以接收到您的设备 id。
点击复制：点击复制按钮，可将该设备 id 复制到剪切板
点击确定：会直接将该设备 id 回填入「Debug 数据」的用户 ID 输入框中
2.7. 步骤7：使用该设备 id 进行导入查询
点击「开始刷新」：即可实时同步该设备在调试模式下的数据上报情况。
以 JSON 格式展示：会将数据进行排版，便于查看。3. 如何退出调试模式？
当 App 从后台退出进程，或通过工具关闭进程后，SDK 将自动关闭调试模式。数据导出.数据导出 v1.13
神策分析致力于帮助客户搭建完整的数据平台，因此除了在产品的分析界面上可以下载查询的明细结果以外，我们也提供了各种完整的方案帮助客户从平台
中导出和获取数据：
1. 通过 查询 API 来获取数据，此方法可以用于平台的计算结果，也可以通过写 SQL 的方式获取最细粒度的用户行为和属性数据，适用于一次性或者
周期性地批量获取数据的需求，可用于所有版本的神策分析；注意，由于效率问题，此方式不建议用于导出大量的原始数据。如果需要导出大量数
据，可以使用 JDBC 的方式导出，但 JDBC 只适用于私有部署版，云版需要使用 API 分批导出。
2. 直接 订阅实时数据 ，此方法用于实时获取最细粒度的用户行为和属性数据，适用于有实时计算实时获取数据的场景，可用于私有部署的单机版和集
群版神策分析；
3. 对于 1.8 之后的神策分析，也可以直接 使用 JDBC 进行数据访问，适用于有通过 JDBC 协议与其它系统打通的应用场景；此方式相比 HTTP 查询
API 的性能更好，可以用于较大量数据的导出。查询 API(数据导出).查询 API(数据导出) v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您
的数据咨询顾问获取一对一的协助。
查询 API 主要用于获取各种数据分析报告。
调用方法
请参见 API 文档 中的调用方法描述。
通用参数
2.1 属性表达式
几乎所有的 API 都会用到属性表达式，例如按照某个属性进行过滤、分组或者聚合等等。属性包括事件属性和用户属性，事件属性使用 event.事件名.属性名的
方式，例如表示 注册渠道 这个属性的表达式如下:
event.Signup.Channel
用户属性类似，例如表示 用户性别:
user.Gender
筛选表达式
筛选表达式同样适用于绝大多数 API，用于表示对某些事件或者用户的筛选操作，使用如下格式的 JSON 表示:
{
// conditions
"relation": "and",
//
"conditions": [{
//
"field": "event.BuyGold.$os",
//
"function": "equal",
//
"params": [
"iOS"
]
}, {
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}]
}
目前支持的操作符如下:
equal / notEqual
表示等于/不等于，对字符串、数值类型有效。如果 Params 有多个，则相当于 In 或者 Not In。例如想筛选出来自北京或者上海的用户:
{
"field": "user.$city","function": "equal",
"params": ["", ""]
}
isTrue / isFalse
只对布尔类型有效。
isSet / notSet
某个属性是否有值，对字符串、数值类型有效。
include
针对集合的操作，表示包含某个元素，例如筛选出所有喜欢苹果的用户:
{
"field": "user.FavoriteFruits",
"function": "include",
"params": ["Apple"]
}
less / greater / between：表示小于/大于/小于且大于，其中 between 是前闭后闭的区间，只对数值类型有效。例如筛选买入黄金的价格在 230
和 232 之间的所有事件:
{
"field": "event.BuyGold.GoldPrice",
"function": "between",
"params": [230, 232]
}
contain / notContain
包含或者不包含，表示字符串的部分匹配，只对字符串类型有效。
absoluteBetween / relativeBefore / relativeWithin
针对日期类型的操作符，分别表示在一个绝对日期范围/在 N 天之前/在 N 天之内。例如想筛选所有注册时间在 3 天之内的用户:
{
"field": "user.$signup_time",
"function": "relativeWithin",
"params": [3]
}
或者筛选所有在 2015-1-1~2015-1-10 注册的用户:
{
"field": "user.$signup_time",
"function": "absoluteBetween",
"params": ["2015-01-01", "2015-01-10"]
}
行为分析报告
所有的分析报告均有 JSON 和 CSV 两种格式，默认是 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析报告对应的 CSV
格式的 URL 为: /events/report?format=csv 。
事件分析报告
[POST /events/report]{
"measures":[
{
// $Anything
"event_name":"payOrder",
//
"aggregator":"uniq_count",
// "filter":
{
"conditions": [
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
]
}
}
],
//
"from_date":"2018-04-30",
//
"to_date":"2018-05-02",
// hour/day/week/month
"unit":"day",
//
"filter":{
"relation":"and",
"conditions":[
{
"field":"event.payOrder.$lib_version",
"function":"equal",
"params":[
"1.6.18"
]
},
{
"field":"event.payOrder.$lib",
"function":"equal",
"params":[
"Android"
]
}
]
},
//
"by_fields":[ "event.payOrder.$sc
reen_width",
"event.payOrder.$screen_height"
],
//
"bucket_params":{
"event.payOrder.$screen_width":[2000,3000],
"event.payOrder.$screen_height":[2000]
},
//
"detail_and_rollup":true,
//643221
"sampling_factor":64,
//
"approx":true,
//hyperloglog12
"hll_precision":12,
//“approx”true“approx_total”true“approx”false“approx_total”true
"approx_total":false,
//
"limit":1000,
//
"use_cache":true
}
{
"by_fields":[ "event.$Anything.$sc
reen_width",
"event.$Anything.$screen_height"
],
"series":[
"2018-04-30 00:00:00",
"2018-05-01 00:00:00",
"2018-05-02 00:00:00"
],
"rows":[{
"values":[
[57],
[60],
[38]
],
"by_values":[
"-INF~2000",
"-INF~2000"
]
},
{
"values":[
[7],
[7],
[2]
],
"by_values":[
"2000~3000",
"-INF~2000"
]
}
],
"num_rows": 2,
"total_rows": 2,
"report_update_time": "2018-05-02 13:51:08.356",
"data_update_time": "2018-05-02 16:03:32.000",
"data_sufficient_update_time": "2018-05-02 16:03:32.000",
"truncated": false
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/events/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"measures": [
{
"event_name": "payOrder",
"aggregator": "unique",
"filter": {
"conditions": [
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
]
}
}
],
"from_date": "2018-04-30",
"to_date": "2018-05-02",
"unit": "day",
"filter": {
"relation": "and",
"conditions": [
{
"field": "event.payOrder.$lib_version",
"function": "equal",
"params": [
"1.6.18"
]
},
{
"field": "event.payOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
]
},
"by_fields":
[ "event.payOrder.$screen_width
",
"event.payOrder.$screen_height"
],
"bucket_params":
{ "event.payOrder.$screen_width":
[
2000,
3000],
"event.payOrder.$screen_height":
[ 2000
]
},
"unit":"day",
"detail_and_rollup": true,
"sampling_factor": 64,
"approx": true,
"hll_precision": 12,
"approx_total": false,
"limit": 1000, "use_cache":
true
}
''
关键参数说明：
aggregator: 聚合操作符，可取值为：
count: 事 件 触 发 次 数uniq_count:
触 发 用 户 数 uniq_avg:人均次数或
人均值
sum: 数值总和
max:数值最大值
min:数值最小值
avg:数值平均值
field: 若aggregator为sum/max/min/avg，需要添加field字段，即聚合的字段名，与aggregator同级，例如：“field" :
"event.payOrder.discountAmount"
bucket_params: 分桶条件，对数值型属性进行分组时，可以自定义分桶条件，分桶条件里所包含的属性必须全包含在分组属性
“by_fields”
limit: 最大分组个数，如果limit超过5w，建议使用 JDBC 导出。limit超过1W，建议使用stream模式下载（仅对于事件分
析）。stream模式开启：添加参数“downloadOriginalFormat” : true，如果不传入该字段，返回的分组数量将根据以下规则计
算：10000 / 时间段个数 / 指标个数，时间段个数为 from_date 和 to_date 包含多少个单位为 unit 的时间段，指标个数即
measures 数组个数
漏斗分析报告
[POST /funnels/report]
{
// ID "funnel_id":
158,
//
"from_date": "2015-04-17",
//
"to_date": "2015-04-19",
// "filter":
{
"conditions": [
{
"field": "event.$Anything.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
},
{
"field": "event.$Anything.$lib",
"function": "contain", "params":
[
"python"
]
},
{
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},//
"by_field": "event.$Anything.$os",
// true:false:
"extend_over_end_date": true,
// & id -1
"by_field_step": -1,
//
"sampling_factor": 64,
// filter.conditions-1,
"filter_field_steps": [-1]
}
在 1.13 及以上的版本中，我们支持 "from_date" 与 "to_date" 使用"秒级精度"或"天级精度"进行筛选
示例：
//
"from_date": "2015-04-17 22:00:00",
"to_date" : "2015-04-18 22:00:00",
系统将会匹配出时间范围为 2015-04-17 22:00:00.000 至 2015-04-18 22:00:00.999 的全部数据
//
"from_date": "2015-04-17",
"to_date" : "2015-04-18",
系统将会匹配出时间范围为 2015-04-17 00:00:00.000 至 2015-04-18 23:59:59.999 的全部数据
{
"date_list": [
"$ALL",
"2017-04-17",
"2017-04-18",
"2017-04-19"
],
"funnel_detail": [
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 98726,
"conversion_rate": 100,
"rows": [
{
"converted_user": 76110,
"conversion_rate": 77.09,
"wastage_user": 22616,
"median_converted_time": 1505
},
{
"converted_user": 76110,
"conversion_rate": 77.09,
"wastage_user": 22616,
"median_converted_time": 1505
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 76110,
"conversion_rate": 77.09,
"rows": [
{
"converted_user": 21266,
"conversion_rate": 27.94,
"wastage_user": 54844,
"median_converted_time": 2530
},
{
"converted_user": 21266,
"conversion_rate": 27.94,
"wastage_user": 54844,
"median_converted_time": 2530
}
]
},
{
"event_name": "SubmitOrder",
"converted_user": 21266,
"conversion_rate": 27.94,
"rows": [
{"converted_user": 17522,
"conversion_rate": 82.39,
"wastage_user": 3744,
"median_converted_time": 939
},
{
"converted_user": 17522,
"conversion_rate": 82.39,
"wastage_user": 3744,
"median_converted_time": 939
}
]
},
{
"event_name": "PayOrder",
"converted_user": 17522,
"conversion_rate": 82.39,
"rows": []
}
],
"completion_rate": 17.75,
"overview": [
[
{
"converted_user": 98726,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 76110,
"conversion_rate": 77.09,
"completion_rate": 77.09
},
{
"converted_user": 21266,
"conversion_rate": 27.94,
"completion_rate": 21.54
},
{
"converted_user": 17522,
"conversion_rate": 82.39,
"completion_rate": 17.75
}
],
[
{
"converted_user": 98726,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 76110,
"conversion_rate": 77.09,
"completion_rate": 77.09
},
{
"converted_user": 21266,
"conversion_rate": 27.94,
"completion_rate": 21.54
},
{
"converted_user": 17522,
"conversion_rate": 82.39,
"completion_rate": 17.75
}
]
]
},
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 34099,
"conversion_rate": 100,
"rows": [
{
"converted_user": 26813,
"conversion_rate": 78.63,
"wastage_user": 7286,
"median_converted_time": 1537
},
{
"converted_user": 26813,
"conversion_rate": 78.63,"wastage_user": 7286,
"median_converted_time": 1537
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 26813,
"conversion_rate": 78.63,
"rows": [
{
"converted_user": 7787,
"conversion_rate": 29.04,
"wastage_user": 19026,
"median_converted_time": 2710
},
{
"converted_user": 7787,
"conversion_rate": 29.04,
"wastage_user": 19026,
"median_converted_time": 2710
}
]
},
{
"event_name": "SubmitOrder",
"converted_user": 7787,
"conversion_rate": 29.04,
"rows": [
{
"converted_user": 6449,
"conversion_rate": 82.82,
"wastage_user": 1338,
"median_converted_time": 942
},
{
"converted_user": 6449,
"conversion_rate": 82.82,
"wastage_user": 1338,
"median_converted_time": 942
}
]
},
{
"event_name": "PayOrder",
"converted_user": 6449,
"conversion_rate": 82.82,
"rows": []
}
],
"completion_rate": 18.91,
"overview": [
[
{
"converted_user": 34099,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26813,
"conversion_rate": 78.63,
"completion_rate": 78.63
},
{
"converted_user": 7787,
"conversion_rate": 29.04,
"completion_rate": 22.84
},
{
"converted_user": 6449,
"conversion_rate": 82.82,
"completion_rate": 18.91
}
],
[
{
"converted_user": 34099,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26813,
"conversion_rate": 78.63,
"completion_rate": 78.63},
{
"converted_user": 7787,
"conversion_rate": 29.04,
"completion_rate": 22.84
},
{
"converted_user": 6449,
"conversion_rate": 82.82,
"completion_rate": 18.91
}
]
]
},
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 34445,
"conversion_rate": 100,
"rows": [
{
"converted_user": 26701,
"conversion_rate": 77.52,
"wastage_user": 7744,
"median_converted_time": 1521
},
{
"converted_user": 26701,
"conversion_rate": 77.52,
"wastage_user": 7744,
"median_converted_time": 1521
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 26701,
"conversion_rate": 77.52,
"rows": [
{
"converted_user": 7407,
"conversion_rate": 27.74,
"wastage_user": 19294,
"median_converted_time": 2594
},
{
"converted_user": 7407,
"conversion_rate": 27.74,
"wastage_user": 19294,
"median_converted_time": 2594
}
]
},
{
"event_name": "SubmitOrder",
"converted_user": 7407,
"conversion_rate": 27.74,
"rows": [
{
"converted_user": 6111,
"conversion_rate": 82.5,
"wastage_user": 1296,
"median_converted_time": 956
},
{
"converted_user": 6111,
"conversion_rate": 82.5,
"wastage_user": 1296,
"median_converted_time": 956
}
]
},
{
"event_name": "PayOrder",
"converted_user": 6111,
"conversion_rate": 82.5,
"rows": []
}
],
"completion_rate": 17.74,
"overview": [
[
{"converted_user": 34445,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26701,
"conversion_rate": 77.52,
"completion_rate": 77.52
},
{
"converted_user": 7407,
"conversion_rate": 27.74,
"completion_rate": 21.5
},
{
"converted_user": 6111,
"conversion_rate": 82.5,
"completion_rate": 17.74
}
],
[
{
"converted_user": 34445,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26701,
"conversion_rate": 77.52,
"completion_rate": 77.52
},
{
"converted_user": 7407,
"conversion_rate": 27.74,
"completion_rate": 21.5
},
{
"converted_user": 6111,
"conversion_rate": 82.5,
"completion_rate": 17.74
}
]
]
},
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 33579,
"conversion_rate": 100,
"rows": [
{
"converted_user": 25271,
"conversion_rate": 75.26,
"wastage_user": 8308,
"median_converted_time": 1485
},
{
"converted_user": 25271,
"conversion_rate": 75.26,
"wastage_user": 8308,
"median_converted_time": 1485
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 25271,
"conversion_rate": 75.26,
"rows": [
{
"converted_user": 6845,
"conversion_rate": 27.09,
"wastage_user": 18426,
"median_converted_time": 2469
},
{
"converted_user": 6845,
"conversion_rate": 27.09,
"wastage_user": 18426,
"median_converted_time": 2469
}
]
},{
"event_name": "SubmitOrder",
"converted_user": 6845,
"conversion_rate": 27.09,
"rows": [
{
"converted_user": 5599,
"conversion_rate": 81.8,
"wastage_user": 1246,
"median_converted_time": 928
},
{
"converted_user": 5599,
"conversion_rate": 81.8,
"wastage_user": 1246,
"median_converted_time": 928
}
]
},
{
"event_name": "PayOrder",
"converted_user": 5599,
"conversion_rate": 81.8,
"rows": []
}
],
"completion_rate": 16.67,
"overview": [
[
{
"converted_user": 33579,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 25271,
"conversion_rate": 75.26,
"completion_rate": 75.26
},
{
"converted_user": 6845,
"conversion_rate": 27.09,
"completion_rate": 20.38
},
{
"converted_user": 5599,
"conversion_rate": 81.8,
"completion_rate": 16.67
}
],
[
{
"converted_user": 33579,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 25271,
"conversion_rate": 75.26,
"completion_rate": 75.26
},
{
"converted_user": 6845,
"conversion_rate": 27.09,
"completion_rate": 20.38
},
{
"converted_user": 5599,
"conversion_rate": 81.8,
"completion_rate": 16.67
}
]
]
}
],
"by_field": "event.$Anything.$os",
"by_values": [
"$ALL",
"iOS"
],
"event_names":
[ "ViewHomePage
",
"ViewProduct",
"SubmitOrder","PayOrder"
],
"report_update_time": "2017-04-21 11:13:47.703",
"data_update_time": "2017-04-21 11:12:56.000",
"data_sufficient_update_time": "2017-04-21 11:12:56.000"
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/funnels/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"from_date":"2017-03-01",
"to_date":"2017-03-31",
"funnel_id":"220",
"filter":{
"conditions":[
{
"field":"event.BindCard.BankCard",
"function":"equal",
"params":[
""
]
},
{
"field":"event.$Anything.$province",
"function":"equal",
"params":[
""
]
}
],
"relation":"and"
},
"by_field":"event.$Anything.$os_version"
}
''
留存分析报告
[POST /retentions/report]
{
//
"from_date": "2018-04-30",
//
"to_date": "2018-05-02",
// N "duration":
"7",
// "first_event":
{
//
"event_name": "login"
},
// "second_event":
{
//
"event_name": "submitOrder",
// "filter":
{
"conditions": [
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation":"and"
}
},
//
"measures": [
{
"event_name": "payOrder","aggregator": "unique"
}
],
//
"user_filter":
{ "conditions":
[
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation":"and"
},
// from_date to_date
"rangeText": ""
// day/week/month
"unit": "day",
//
"extend_over_end_date": true,
// 643221
"sampling_factor": 64,
// falsetrue
"is_wastage": false,
"use_cache": true
}
{
"by_field": "",
"has_first_day": false,
"rows": [
{
"by_value": "2018-04-30",
"total_people": 95,
"cells": [
{
"people": 36,
"percent": 37.89,
//values
"values": [
0
]
},
{
"people": 6,
"percent": 6.32,
"values":
[ 5
]
}
]
},
{
"by_value": "2018-05-01",
"total_people": 91,
"cells": [
{
"people": 25,
"percent": 27.47,
"values":
[ 0
]
},
{
"people": 1,
"percent": 1.1,
"values":
[ 1
]
}
]
},
{
"by_value": "2018-05-02",
"total_people": 62,
"cells": [
{
"people": 25,
"percent": 40.32,
"values":
[ 0
]}
]
}
],
"report_update_time": "2018-05-02 17:00:21.355",
"data_update_time": "2018-05-02 16:59:43.000",
"data_sufficient_update_time": "2018-05-02 16:59:43.000",
"truncated": false
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/retentions/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"from_date": "2018-04-30",
"to_date": "2018-05-02",
"duration": "7",
"first_event": {
"event_name": "login"
},
"second_event": { "event_name":
"submitOrder", "filter": {
"conditions": [
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation": "and"
}
},
"measures": [
{
"event_name": "payOrder",
"aggregator": "unique"
}
],
"user_filter":
{ "conditions":
[
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},
"unit": "day",
"extend_over_end_date": true,
"sampling_factor": 64,
"is_wastage": false,
"use_cache": true
}
''
分布分析报告
[POST /addictions/report]
{
//
"event_name": "submitOrder",
//
"from_date": "2018-04-30",
//
"to_date": "2018-05-02",
// "filter":
{
"conditions": [
{
"field": "event.submitOrder.$lib","function": "equal",
"params": [
"Android"
]
}
],
"relation":"and"
},
// "user_filter":
{
"conditions": [
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation":"and"
},
// from_dateto_date
"rangeText":"",
// 643221
"sampling_factor":64,
// day/week/month
"unit": "day",
// ,times/period, period
"measure_type":"times",
//times
"result_bucket_param": [
2,
3
]
}
{
"by_field": "",
"rows": [
{
"by_value": "2018-04-30",
"total_people": 455,
"cells": [
{
"people": 436,
"percent": 95.82,
"bucket_end": 2
},
{
"people": 19,
"percent": 4.18,
"bucket_start": 2,
"bucket_end": 3
}
]
},
{
"by_value": "2018-05-01",
"total_people": 499,
"cells": [
{
"people": 484,
"percent": 96.99,
"bucket_end": 2
},
{
"people": 15,
"percent": 3.01,
"bucket_start": 2,
"bucket_end": 3
}
]
},
{
"by_value": "2018-05-02",
"total_people": 280,
"cells": [
{
"people": 273,
"percent": 97.5,
"bucket_end": 2
},
{
"people": 7,"percent": 2.5,
"bucket_start": 2,
"bucket_end": 3
}
]
}
],
"report_update_time": "2018-05-02 17:15:26.739",
"data_update_time": "2018-05-02 17:14:10.000",
"data_sufficient_update_time": "2018-05-02 17:14:10.000",
"truncated": false
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/addictions/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"event_name": "submitOrder",
"from_date": "2018-04-30",
"to_date": "2018-05-02",
"filter": {
"conditions": [
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation": "and"
},
"user_filter":
{ "conditions":
[
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},
"sampling_factor": 64,
"unit": "day",
"measure_type": "times",
"result_bucket_param": [
2,
3
]
}
''
用户路径分析报告
[POST /path/analytics/report]
{
// initial_event, termination_event
"source_type": "initial_event",
// "source_event":
{
"event_name": "StartApp",
"filter": {
"conditions": [
{
"field": "event.StartApp.$wifi",
"function": "isTrue",
"params": []
}
]
}
},
"event_names":
[ "BuyBullion",
"BuyGold","SaleGold",
"StartApp"
],
"by_fields":
[ "event.BuyBullion.$countr
y"
],
//
"col_limit": 20,
// "row_limit":
7,
"from_date": "2017-05-01",
"to_date": "2017-05-22",
"user_filter": {},
"bucket_params": {},
"sampling_factor": 64,
"session_interval": 1200,
"use_cache": true
}
{
"nodes":
[ [
{
"id": "0_StartApp",
"event_name": "StartApp",
"times": 27336
}
],
[
{
"id": "1_StartApp",
"event_name": "StartApp",
"times": 163
},
{
"id": "1_BuyGold",
"event_name": "BuyGold",
"times": 118
},
{
"id": "1_SaleGold",
"event_name": "SaleGold",
"times": 104
},
{
"id": "1_BuyBullion_$country_3392903",
"event_name": "BuyBullion",
"times": 37
}
],
[
{
"id": "2_SaleGold",
"event_name": "SaleGold",
"times": 68
},
{
"id": "2_BuyGold",
"event_name": "BuyGold",
"times": 50
},
{
"id": "2_BuyBullion_$country_3392903",
"event_name": "BuyBullion",
"times": 18
},
{
"id": "2_StartApp",
"event_name": "StartApp",
"times": 2
}
],
[
{
"id": "3_SaleGold",
"event_name": "SaleGold",
"times": 39
},
{
"id": "3_BuyGold",
"event_name": "BuyGold",
"times": 23
},
{"id": "3_BuyBullion_$country_3392903",
"event_name": "BuyBullion",
"times": 1
}
],
[
{
"id": "4_StartApp",
"event_name": "StartApp",
"times": 1
}
]
],
"links":
[ [
{
"source": "0_StartApp",
"target": "1_wastage",
"is_wastage": true,
"times": 26914
},
{
"source": "0_StartApp",
"target": "1_StartApp",
"times": 163
},
{
"source": "0_StartApp",
"target": "1_BuyGold",
"times": 118
},
{
"source": "0_StartApp",
"target": "1_SaleGold",
"times": 104
},
{
"source": "0_StartApp",
"target": "1_BuyBullion_$country_3392903",
"times": 37
}
],
[
{
"source": "1_StartApp",
"target": "2_wastage",
"is_wastage": true,
"times": 160
},
{
"source": "1_StartApp",
"target": "2_StartApp",
"times": 2
},
{
"source": "1_StartApp",
"target": "2_BuyBullion_$country_3392903",
"times": 1
},
{
"source": "1_BuyGold",
"target": "2_wastage",
"is_wastage": true,
"times": 68
},
{
"source": "1_BuyGold",
"target": "2_BuyGold",
"times": 50
},
{
"source": "1_SaleGold",
"target": "2_SaleGold",
"times": 68
},
{
"source": "1_SaleGold",
"target": "2_wastage",
"is_wastage": true,
"times": 36
},
{
"source": "1_BuyBullion_$country_3392903",
"target": "2_wastage","is_wastage": true,
"times": 20
},
{
"source": "1_BuyBullion_$country_3392903",
"target": "2_BuyBullion_$country_3392903",
"times": 17
}
],
[
{
"source": "2_SaleGold",
"target": "3_SaleGold",
"times": 39
},
{
"source": "2_SaleGold",
"target": "3_wastage",
"is_wastage": true,
"times": 29
},
{
"source": "2_BuyGold",
"target": "3_wastage",
"is_wastage": true,
"times": 27
},
{
"source": "2_BuyGold",
"target": "3_BuyGold",
"times": 23
},
{
"source": "2_BuyBullion_$country_3392903",
"target": "3_wastage",
"is_wastage": true,
"times": 17
},
{
"source": "2_BuyBullion_$country_3392903",
"target": "3_BuyBullion_$country_3392903",
"times": 1
},
{
"source": "2_StartApp",
"target": "3_wastage",
"is_wastage": true,
"times": 2
}
],
[
{
"source": "3_SaleGold",
"target": "4_wastage",
"is_wastage": true,
"times": 38
},
{
"source": "3_SaleGold",
"target": "4_StartApp",
"times": 1
},
{
"source": "3_BuyGold",
"target": "4_wastage",
"is_wastage": true,
"times": 23
},
{
"source": "3_BuyBullion_$country_3392903",
"target": "4_wastage",
"is_wastage": true,
"times": 1
}
],
[
{
"source": "4_StartApp",
"target": "5_wastage",
"is_wastage": true,
"times": 1
}
]
],"truncate_row": [],
"truncate_col": false,
"report_update_time": "2017-05-22 11:07:40.544",
"data_update_time": "2017-05-22 11:06:54.000",
"data_sufficient_update_time": "2017-05-22 11:06:54.000"
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/path/analytics/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"source_type": "initial_event",
"source_event": {
"event_name": "StartApp",
"filter": {
"conditions": [
{
"field": "event.StartApp.$wifi",
"function": "isTrue",
"params": []
}
]
}
},
"event_names":
[ "BuyBullion",
"BuyGold",
"SaleGold",
"StartApp"
],
"by_fields":
[ "event.BuyBullion.$countr
y"
],
"col_limit": 20,
"row_limit": 7,
"from_date": "2017-05-01",
"to_date": "2017-05-22",
"user_filter": {},
"bucket_params": {},
"sampling_factor": 64,
"session_interval": 1200,
"use_cache": true
}
''
属性分析报告
[POST /user/analytics/report]
{
"measures": [
{
"aggregator": "count",
"field": ""
}
],
"filter":
{ "conditions":
[
{
"field": "user.HasByGold",
"function": "isTrue",
"params": []
}
]
},
"by_fields":
[ "user.IncomeLevel
", "user.Gender"
],
"sampling_factor": null,
//
"x_axis_field": "user.IncomeLevel",
"use_cache": false
}
{
"by_fields": ["user.Gender"
],
"series":
[ "5000~10000",
"3000~5000",
"10000~20000",
"0~3000",
null
],
"rows": [
{
"values":
[ [
83169
],
[
27776
],
[
55699
],
[
27892
],
[
36106
]
],
"by_values":
[ ""
]
},
{
"values":
[ [
55363
],
[
18208
],
[
37030
],
[
18668
],
[
24090
]
],
"by_values":
[ ""
]
},
{
"values":
[ [
25864
],
[
8490
],
[
17327
],
[
8628
],
[
17353
]
],
"by_values":
[ null
]
}
],
"num_rows": 3,
"report_update_time": "2017-05-22 14:16:03.595",
"data_update_time": "1970-01-01 08:00:00.000",
"data_sufficient_update_time": "1970-01-01 08:00:00.000"
}curl ''https://golddemo.cloud.sensorsdata.cn/api/user/analytics/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"measures": [
{
"aggregator": "count",
"field": ""
}
],
"filter":
{ "conditions":
[
{
"field": "user.HasByGold",
"function": "isTrue",
"params": []
}
]
},
"by_fields":
[ "user.IncomeLevel
", "user.Gender"
],
"sampling_factor": null,
"x_axis_field": "user.IncomeLevel",
"request_id": 1495433768121,
"use_cache": false
}
''
用户明细查询
用户明细系列接口用于查询某一个特定分析报告中的具体用户列表，请求的大部分参数与分析报告相同，新增的参数会在每个接口里具体说明。用户列表也
支持 JSON 和 CSV 两种格式，默认式 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析的用户列表对应的 CSV 格式的
URL 为: /events/user/list?format=csv。
事件分析用户明细报告
[POST /events/user/list]
{
"measures": [
{
"aggregator": "unique",
"event_name": "SaleGold"
}
],
"filter":
{ "conditions":
[
{
"field": "event.SaleGold.$city",
"function": "equal",
"params":
[ ""
]
},
{
"field": "event.SaleGold.$app_version",
"function": "equal",
"params": [
"1.7"
]
}
]
},
"by_fields":
[ "event.SaleGold.$app_version
",
"event.SaleGold.$screen_width"
],
"rollup_date": false,
"unit": "week",
// "slice_by_values":
[
"1.7",1080
],
// ,2015818
"slice_date": "2015-08-18 00:00:00",
// true profile false id
"detail": true,
// 30
"num_per_page": 10,
//
"page":1,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1, // /
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
漏斗分析用户明细报告
[POST /funnels/user/list]
{
"funnel_id": 158,
"from_date": "2015-04-17",
"to_date": "2015-07-16",
"filter": {
"conditions": [{
"field": "event.$Anything.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
},
{
"field": "event.$Anything.$lib",
"function": "contain", "params":
[
"python"
]
},
{
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},
"by_field": "event.SaleGold.$lib_version",
//
"slice_by_value": "0.1.0",
// "slice_step":
0,
// true false
"slice_wastage_user": false,
// true profile false id
"detail": true,
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
留存分析用户明细报告
[POST /retentions/user/list]
{
"first_event":
{ "event_name":
"BuyGold", "filter": {
"conditions": [
{
"field": "event.BuyGold.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
}
]
}
},
"second_event":
{ "event_name":
"StartApp"
},
//
"is_wastage": false,
//
"profiles": [],
"duration": 7,
"from_date": "2015-07-21",
"to_date": "2015-07-24",
"unit": "day",
"by_field": "event.SaleGold.$lib_version",
//
"slice_by_value": "0.1.0",
// 0 null
// "slice_interval":
1,
// true profile false id
"detail": true,
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
分布分析用户明细报告
[POST /addictions/user/list]
{
"event_name": "BuyGold",
"filter": {
"conditions": [
{
"field": "event.BuyGold.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
}
]
},
"rollup_date": false,
"from_date": "2015-04-22",
"to_date": "2015-04-22",
"unit": "day",
"by_field": "event.SaleGold.$lib_version",
//
"slice_by_value": "0.1.0",
// "slice_freq":
2, "detail":
true,
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits": ["Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
用户列表明细报告
[POST /users/list]
{
"filter":
{ "conditions":
[
{
//
// ''user.fenqun1''
// ''user.birthday''
//
"field": "user.test",
"function": "isTrue"
}
]
},
"profiles": [
//
"user.$utm_source"
],
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
这个接口也可以指定要查询的用户id，这样能获取指定用户的属性信息。
{
"filter":{ "cond
itions":[
{
"field":"user.test",
"function":"isTrue"
}
]
},
"users":["1902482830", "3834577070"],
"profiles":[ "user.$
utm_source"
]
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
用户路径用户明细报告
[POST /users/list]
{
"slice_element_filter": [
{
"slice_event_name": "StartApp",
"slice_by_value": "8.1"
}
],
"next_slice_element_filter": [
{
"slice_event_name": "SaleGold",
"slice_by_value": "1"
}
], //
"session_level": "0", //
"source_type": "initial_event",
"source_event": {
"event_name": "StartApp",
"filter": {
"conditions": [
{
"field": "event.StartApp.$wifi",
"function": "isTrue"
}
]
}
},
"event_names":
[ "BuyBullion",
"BuyGold",
"SaleGold",
"StartApp"
],
"by_fields":
[ "event.SaleGold.$wifi",
"event.StartApp.$os_version"
],
"session_interval": "1200",
"from_date": "2017-05-01","to_date": "2017-05-22",
"detail": true,
"col_limit": "20",
"row_limit": "7",
"sampling_factor": 64,
"is_aggregate": "false", //
"edge_type": "ALL", // WASTAGERETENTIONALL
"is_next_aggregate": "false", //
"num_per_page": 50,
"all_page": true,
"filter": {},
"use_cache": false
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
自定义查询和用户行为列表
自定义查询
[POST /sql/query]
通过 SQL 进行自定义查询，表结构及自定义查询方法详见 自定义查询 功能的介绍。
Parametersq: 查询的 SQL，例如 SELECT event,time,user_id FROM events LIMIT 10。
format: 可能的值包括
csv： 默 认 格 式
json：每行一个 JSON
event_json：导出可以用于直接导入神策系统的 Event Track 格式的 Json（1.*.3338 之后的版本支持） profile_json：
导出可以用于直接导入神策系统的 Profile Set/Track Signup 格式的 Json（1.*.3338 之后的版本支持）item_json:
导出可以用户直接导入神策系统的 item_set 格式的 Json（1.15.1646 及之后的版本才支持） sql：不直接返回数
据，而是翻译为一条可以直接在 Spark/Impala/Hive 里执行的 SQL
event time user_id
RechargeCash 2015-09-02 13:01:00.125336 1731174795
RechargeCash 2015-09-02 02:02:48.133002 1751664241
RechargeCash 2015-09-02 13:01:53.308174 1784316911
RechargeCash 2015-09-02 09:09:07.784417 1793667170
RechargeCash 2015-09-02 09:09:42.420781 1807294808
RechargeCash 2015-09-02 16:04:06.211421 1808422371
RechargeCash 2015-09-02 08:08:44.646672 1810351186
RechargeCash 2015-09-02 00:12:20.456509 1874214895
RechargeCash 2015-09-02 02:02:38.494175 1897237370
RechargeCash 2015-09-02 15:03:08.338102 2012805794
该接口和其它 API 的调用方式有所不同，q 参数直接用 GET/POST 参数传递即可，csv 格式返回的数据为 \t 分隔。一个使用 curl 的例子如下:
curl ''https://saasdemo.cloud.sensorsdata.cn/api/sql/query?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-X POST \
--data-urlencode "q=SELECT * FROM events LIMIT 10" \
--data-urlencode "format=csv"
注意： （1）如果查询的事件是预置事件，那么 $ 符号需要使用 \ 进行转义。 （2）如果是导出 items 表中的数据，需要保证神策系
统版本为 1.15.1646 及之后的版本。
用户行为列表
[POST /users/event/list]
获取一个或者多个用户在某一段时间内的详细行为信息。
{
"users":
[ 8601519
0,
81952822,
87961512
],
"from_date": "2015-04-22",
"to_date": "2015-04-22",
// false users user_idtrue distinct_id
"distinct_id": false
}
{
"events": [
{
"user_id": "422337220",
"event": "SaleGold",
"time": 1432822231055,
"properties":
{ "$province": "",
"$screen_height": 640.0,
"$city": "",
"$os": "iOS",
"$screen_width": 320.0,
"$model": "iPhone 5",
"$lib_version": "0.1.0",
"$app_version": "1.3",
"$manufacturer": "Apple",
"$os_version": "7.0",
"$wifi": 1.0,
"$lib": "python","SaleStep": 1.0
}
},
{
"user_id": "422337220",
"event": "SaleGold",
"time": 1432822232022,
"properties":
{ "$province": "",
"$screen_height": 640.0,
"$city": "",
"$os": "iOS",
"$screen_width": 320.0,
"$model": "iPhone 5",
"$lib_version": "0.1.0",
"$app_version": "1.3",
"$manufacturer": "Apple",
"$os_version": "7.0",
"$wifi": 1.0,
"$lib": "python",
"GoldPrice": 240.34,
"GoldWeight": 16153.0,
"SaleStep": 2.0
}
}
]
}
常见问题
查询 API 提示 {"error":"没有访问权限，请检查 project 和 token"} ？
首先：检查下数据接收地址的域名是不是客户系统自己环境登录系统的域名（注意，不是数据接收地址的域名哦）
其次：检查 project 和 token 是不是同一个项目的参数
最后：检查 token 是 admin 账号下的 API Secret 还是通过自己的账号密码获取的 Access token。如果是 API Secret ，token 直接放在 url 链接后面。如
果是 Access token ，token 参数不能直接放在 url 链接后面 ，需要放在 Header 参数中，即添加参数：
-H ''sensorsdata-token: {获取的 Access token}''
具体可参考此文档：功能 API
查询引擎错误
可以检查下查询的 API 接口和参数名是否对应，以及设置的参数格式是否正确。
报错API return 422
API SQL 查询时，$ 符号需要转译
API 查询或者下载用户列表等使用后台分析服务时，504报错
服务转发配置没有配置连接超时时间或者超时时间设置较短，让客户修改超时时间即可。一般我们建议数据接收地址超时时间为 60 ，后台分析服务超时时
间为 1800。
是否可以使用查询 API ，将查询结果返回到客户线上业务/用于实时分析？/ 查询 API 的请求频次有什么限制？
1. 神策查询 API 只适合低频调用，相应速度取决如下两方面：
实际的查询场景：如数据量、查询数据的时间范围、所用的分析模型或 SQL 的复杂度等；
2. 硬件和网络配置：如 CPU、内存、网卡、硬盘等
在查询场景和神策服务器配置匹配的前提下，神策建议 API 调用频率保持在分钟级，单次查询的数据范围在 1 天以内，同一时间最大并发请求量不超过 10
个，以确保查询相应和神策服务性能稳定。如条件超出如上描述范围，可能出现无法响应/查询慢/甚至神策服务性能不稳定情况。
如上为神策根据历史对接经验给出，考虑到不同客户查询调用的场景各有差异，建议以实测为准，根据实际测试结果合理调整查询条件和调用频次。订阅实时数据.订阅实时数据 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
神策分析设计为开放的架构，让用户可以订阅实时数据来满足更多使用场景。服务端接到一条 SDK 发来的数据后，会对数据做一些预处理并将数据写入到消
息队列 Kafka 供下游各类计算模块使用。本文将介绍订阅 Kafka 数据的方法。
1. 一些要求
订阅数据需要满足以下要求：
1. 启动订阅的机器需与部署神策分析的机器在同一个内网，且必须可以解析神策分析服务器的 host；
2. 请选用兼容的 Kafka 客户端版本，高版本服务端兼容低版本客户端，反之则可能存在兼容性问题。神策 Kafka 服务端版本一部分早期用户为 0.8.2.
x，后期新用户为 0.10.x，具体情况可在服务器上查看；
3. 仅私有部署版支持通过 Kafka 订阅数据；
4. 如果在自己的机器上订阅数据,需要先在自己机器上 hosts 中配上神策的服务器，订阅的时候 zookeeper 填写所有机器的 hostname，例如：
hostname1:2181,hostname2:2181,hostname3:2181；
2. 订阅参数
参数名称 参数值
topic event_topic
partition 单机 3 个/集群 10 个
zookeeper hostname1:2181,hostname2:2181,hostname3:2181
broker hostname1:9092,hostname2:9092,hostname3:9092
3. 订阅数据
订阅有多种方式，可以选择一种适合使用场景的方式。
下面给出两种 Shell 方式启动订阅的示例，使用 Shell 方式可以通过重定向标准输出将数据写入文件后处理或直接用管道作为其他进程的输入，可以对接各种
编程语言实现的处理程序。当然也可以使用原生 API 实现订阅，参数与 Shell 方式的一样，这里不再介绍。
3.1. 使用 Kafka Console Consumer
可以使用 Kafka 自带的 Kafka Console Consumer 通过命令行方式订阅，例如从最新数据开始订阅：
bin/kafka-console-consumer.sh --zookeeper hostname:2181 --topic event_topic
可以将 stdout 输出到文件或作为其他数据处理进程的输入数据。
3.2. 使用 Simple Consumer Shell
使用 Simple Consumer Shell 可以实现更灵活的订阅，可参考 Kafka 相关文档: Simple Consumer Shell，例如：
bin/kafka-run-class.sh kafka.tools.SimpleConsumerShell \
--broker-list hostname:9092 \
--offset 12345 \
--partition 2 \
--topic event_topic \
--print-offsets
4. 数据格式
订阅的数据的格式与 数据格式 基本一致。使用 JDBC 进行数据访问.使用 JDBC 进行数据访问 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
在神策分析的单机和集群版中，我们提供了更加高效、稳定的 SQL 查询方式，即直接使用 JDBC 或者 impala-shell 进行数据查询。关于具体如何使用
JDBC 连接 Impala 可以直接参考官方文档。
1. 获取 JDBC 地址
登录任意的神策服务器
切换至 sa_cluster 账户
su - sa_cluster
使用以下命令获取地址
monitor_tools get_config -t client -m impala
例如输出是：
{
"hive_url_list": [
"jdbc:hive2://192.168.1.2:21050/rawdata;auth=noSasl",
"jdbc:hive2://192.168.1.3:21050/rawdata;auth=noSasl",
],
"hive_user": "sa_cluster"
}
其中，hive_url_list 中的任意一个地址都可用于连接。
如果使用代码访问，我们建议使用 1.1.0 版本的 Hive JDBC Driver 来进行访问，Maven 的依赖定义如下：
<dependency>
<groupId>org.apache.hive</groupId>
<artifactId>hive-jdbc</artifactId>
<version>1.1.0</version>
</dependency>
注意：实际代码运行中， Hive JDBC Driver 会依赖其他 jar 包，主要有 hadoop-common 、hive-service、hive-common 和 libthrift。正常这些 jar 包会
自动获取，如果没有自动获取，需要再添加相应的 jar 包。
另外，Impala 也支持使用官方的 Impala JDBC Driver 进行访问，不过为了兼容神策分析系统，请使用的时候务必开启 Native SQL 的选项，例如：
jdbc:impala://192.168.1.1:21050/rawdata;UseNativeQuery=1
注意：使用不同 Driver 访问时使用的 JDBC URI 也会有所不同。
2. 数据表结构
目前，神策分析的所有数据都映射到事件表（events） 和用户表（users） 这两张数据表，但连接 JDBC 进行数据访问时，会显示 `event_ros_p*`、
`event_view_p*` 等底层表，查询数据不需要关注这些底层表，按照此文档下方的例子，使用事件表（events） 和用户表（users）即可查询所有的事件数据
和用户数据。表结构可参考文档 [数据表]。
具体项目对应的表结构，也可在神策分析的自定义查询中查看：3. 使用 impala-shell 进行查询
除了直接使用 JDBC 接口之外，也可以直接使用 impala-shell 工具进行查询。通常有两种使用方式：
1. 直接登录任意的神策服务器，运行 impala-shell 命令即可。
2. 使用任意 2.6.0 以上的 impala-shell 客户端，连接到上面 hive_url_list 中的地址（无需指定端口）。
3. 神策使用的库名是 rawdata, 注意切换过去后再做查询或导出数据。
4. 常规使用
为了区分查询神策的数据与一般的 Impala 数据，需要在 SQL 中使用特殊的注解来进行标识，例如查询默认项目的 events 数据：
SELECT user_id,distinct_id,event,time,$lib as lib FROM events WHERE `date` = CURRENT_DATE() LIMIT 10 /*SA*/;
其中的 `/*SA*/` 表示当前 SQL 是一个发给神策系统的查询。类似的，如果想看 events 表有哪些字段，可以使用：
DESC events /*SA*/;
如果不是查询默认项目，则需要指定项目名称，例如：
SELECT id,first_id,second_id FROM users LIMIT 10 /*SA(test_project)*/;
最后，我们还可以让一个 SQL 的一部分使用神策的查询，其它部分使用正常的 Impala 查询，例如：
CREATE TABLE test_data AS
/*SA_BEGIN(test_project)*/ SELECT id, first_id, $city AS city FROM users LIMIT 10 /*SA_END*/
使用这种方式，也可以很容易的实现把神策的数据和其它外部数据表进行 JOIN。5. 数据导出
如果想把神策的数据导出成文本格式，用于备份或者其它用途，那可以使用以下方案：
创建一个文本格式的数据表，把待导出的数据插入此表。
CREATE TABLE default.export_data AS
/*SA_BEGIN(production)*/
SELECT user_id,time,event, $os AS _os FROM events WHERE date=CURRENT_DATE() LIMIT 10
/*SA_END*/
注意：普通 Impala/Hive 表不支持带 $ 的字段，因此如果导出这类字段需要使用 AS 重命名。
获取该数据表的 HDFS 路径
SHOW TABLE STATS default.export_data
其中输出的 Location 列即是导出文件所在的 HDFS 目录，例如:
hdfs://data01:8020/user/hive/warehouse/export_data/
可以使用 hadoop 命令将 HDFS 文件取到本地：
hadoop fs -get hdfs://data01:8020/user/hive/warehouse/export_data/
上述目录里的文件是以 Hive 默认分隔符（即 \001）进行列分隔的文本文件。
按需拷⻉走上面路径下的文件即可。
6. 和 Spark 集成
这里以 Python API 为例，使用 Spark 的 JDBC Connector 直接访问神策的原始数据，Driver 使用 2.6.3 或以上版本：
from pyspark.sql import SparkSession
jdbc_url= "jdbc:impala://localhost:21050/rawdata;UseNativeQuery=1"
spark = SparkSession.builder.appName("sa-test").getOrCreate()
df = spark.read.jdbc(url=jdbc_url, table="(/*SA(default)*/ SELECT date, event, count(*) AS c FROM events WHERE
date=CURRENT_DATE() GROUP BY 1,2) a")
df.select(df[''date''], df[''event''], df[''c''] * 10000).show()
也可以使用 spark-shell 执行的同样的例子，注意要把对应的 Driver 加载进来，Driver 使用 2.6.3 或以上版本：
spark-shell --driver-class-path ImpalaJDBC41.jar --jars ImpalaJDBC41.jar
var test_jdbc = spark.sqlContext.read.format("jdbc").option("url", "jdbc:impala://localhost:21050/rawdata;
UseNativeQuery=1").option("driver", "com.cloudera.impala.jdbc41.Driver").option("dbtable", "(/*SA(default)*/
SELECT date, event, count(*) AS c FROM events WHERE date=CURRENT_DATE() GROUP BY 1,2) a").load();
test_jdbc.show
注意：该方式仅在 Spark 2.2 版本测试通过。另外，这种方式会使用单线程的方式从 Impala 获取数据，因此不适用于 SQL 会返回大量数据内容
的方式，请尽量用 Impala SQL 做完预处理之后再引入 Spark 进行后续处理。数据迁移.数据迁移 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经
验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 概述
神策分析开始为用户提供数据自助迁移的功能，即通过 API 导出原始神策分析环境中的历史数据，然后通过导入工具把历史数据导入到新建神策分析环境
中。
通过 API 导出可以直接用于导入的数据格式，神策分析版本号需大于 1.*.3338 。如果低于此版本的用户仍想自助迁移数据，需联系神策的技术支持人员。
2. 数据导出
使用查询 API 通过编写 SQL 的方式，导出 users 表（含 Track Signup 数据）和 events 表中的数据 1.15.1646 items items ，另外需要注意的
是，SQL 在执行过程中，默认超过 10 分钟之后会被系统强制杀死，
如果希望增大超时时间可以在 SQL 语句之后添加 MAX_QUERY_EXECUTION_TIME 参数控制（时间单位为秒， 建议最大超时时长不要超过 1800，以免影
响系统稳定性 ）。
使用 curl 导出 users 表的例子如下：
curl ''https://saasdemo.cloud.sensorsdata.cn/api/sql/query?token=******&project=default'' \
-X POST \
--data-urlencode "q=SELECT * FROM users /*MAX_QUERY_EXECUTION_TIME=1800*/" \
--data-urlencode "format=profile_json" \
>> profile.json
在导出 events 表数据时，建议通过 date 字段按天导出，这样可以提高 SQL 的查询速度。
使用 curl 导出 events 表的例子如下：
curl ''https://saasdemo.cloud.sensorsdata.cn/api/sql/query?token=******&project=default'' \
-X POST \
--data-urlencode "q=SELECT * FROM events where date = ''2017-01-01'' /*MAX_QUERY_EXECUTION_TIME=1800*/" \
--data-urlencode "format=event_json" \
>> event.json
3. 数据导入
在导入数据的过程中，应遵循以下步骤，否则会导致 Track Signup 逻辑混乱。
先导入 users 表中的数据
再导入 events 表中的数据
3.1. 导入 users 表中的数据
对于私有部署版用户，请使用 BatchImporter 进行 users 数据导入；
对于云版用户，请使用 FormatImporter 或 LogAgent 进行 users 数据导入；
请不要将文件内容顺序打乱。
3.2. 导入 events 表中的数据
使用任意一种导入工具导入即可。辅助工具.辅助工具 v1.13
神策分析提供一些辅助工具帮助您实现一些自定义功能或方便的运维。
数据清理工具使用说明
数据清理工具用于清理神策分析中导入的用户行为数据( event 数据)和用户属性数据( profile 数据)。
多项目管理工具使用说明
神策分析在 1.5 版本里面推出了多项目功能。多项目管理工具用于项目的创建、删除等操作。
元数据创建工具使用说明
神策分析在 1.6 版本中添加了创建、导出和导入元数据的命令行工具。
环境检测工具使用说明
神策检测工具主要用于检测服务器是否满足部署神策分析的要求。数据清理工具使用说明.数据清理工具使用说明 v1.13
1. 概述
数据清理工具既可用于清理神策分析中导入的行为事件数据，也可用于对导入的行为事件数据去重。
该工具 不提供 的功能如下：
1. 删除指定属性的数据。
2. 删除某次批量导入的数据。
3. 删除某个时间段导入的数据。
4. 将某个事件定义删除。但是元数据管理中可以对事件进行隐藏，管理员可以操作。
数据清理为 不可逆操作，频繁或大量的清理数据将导致碎片过多可能会 影响导入进度，请谨慎操作。
除了 HdfsImporter 导入工具之外，其他导入数据的方式，导入的数据都是会先经过 Kudu，达到一定条件之后，事件数据才会转换到 Hdfs 中存储。
如您的神策分析版本在 1.13 及以下且为集群版环境，需要注意，数据清理工具默认只会删除 Hdfs 中的数据，不会清除 Kudu 中的数据。如需要清除最近导入
的数据，请不要停止导入数据并等候 4 小时以上，以确保最近导入的数据顺利进入到 Hdfs中。
2. 使用方法
请先 ssh 到部署了神策服务的任意一台机器，在 sa_cluster 账户下使用数据清理工具。从 root 切换到 sa_cluster 账户：
su - sa_cluster
请注意 su 与 sa_cluster 中间的减号。
2.1. 事件删除
该方法可以清理一个项目指定时间段内 所有事件或者某些指定事件 的行为事件数据。
该时间段为 事件行为 的时间，非导入数据的时间段。
该方法会保留事件、事件属性的定义。
单机版：不会立即释放磁盘，后台会缓慢释放，如果删除的是指定事件的数据那么释放的时间可能会很长。
集群版：不会立即释放磁盘，每天凌晨会例行清理。注意 ： 集群版事件删除一般需要消耗大量时间和资源，尽量不要指定过大的时间范围。另外支
持使用 -m 参数加快执行速度。
参数列表：
参数名 必 说明 格式 样例 备注
须
begin √ 删除数据的起始日期（包含这一天） yyyy-MM-dd 2015-12-21
end √ 删除数据的结束日期（包含这一天） yyyy-MM-dd 2015-12-22
events 指定删除数据的 event，集群版可同时指定多个事件，使用逗号分隔 事件名称 ButtonClick
project 操作对应的项目，默认为“默认项目” 项目名 my_project
hours 指定删除数据所属的小时数或范围，多个不连续的时间之间使用逗号分 [0-23] 0,[3-5] 仅集群版支持
max_tasks 指定 event 进行删除时，可以通过该参数设置任务的并发度，从而加快执行速度，默认为1。 正整数 2 仅集群版支持
libs 删除的事件来源，多个来源之间使用逗号分隔。 LIBS LIBS 仅集群版支持
清除 default 项目下 2015 年 12 月 22 日这 1 天的行为事件数据：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --project default
清除 production 项目下 2015 年 12 月 20 日 到 22 日这 3 天的行为事件数据：
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --project production
清除 my_project 项目下 ButtonClick 这个事件 2015 年 12 月 20 日 到 22 日这 3 天的行为事件数据，其他事件无改动：
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --events ButtonClick --project my_project注：如果 events 对应的事件名带 "$" 符号，则 events 后的事件名需要加单引号:
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --events ''$AppStart'' --project my_project
清除 my_project 项目 ButtonClick 这个事件 2015 年 12 月 22 日 0 点、3 点、4 点、5 点的行为事件数据，其他事件无改动：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --events ButtonClick --hours 0,[3-5] --project
my_project
清除 my_project 项目 ButtonClick 这个事件 2015 年 12 月 22 日 0 点、3 点、4 点、5 点的来自于 scala 和 python 的行为事件数据，其他事件
无改动：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --events ButtonClick --hours 0,[3-5] --project
my_project --libs scala,python
2.2. 支持GDPR欧盟标准 ，删除底层用户数据 (目前仅支持1.13.5169+单机版)
方案一： 使用用户 id 直接删除 (目前 events 和 users 表中的数据均被删除)
参数列表：
参数名 必 说明 格式 样例 备注
须
filename √ 包含 id set 的文件 filename user_id.txt 默认为 user_id
is_distinct_id id set 的文件中包含的是否是 distinct_id 若 id set 中的数据是 distinct_id, 需指定此参数
project 操作对应的项目，默认为“默认项目” 项目名 my_project
1. 创建用户文本，每行一个用户（user_id 或者 distinct_id）（USER_ID_SET_FILENAME或者DISTINCT_ID_SET_FILENAME）
2. 使用如下指令删除
使用 user_id 删除的指令
sa_clean clean_event_and_profile_by_id_list --project PROJECT_NAME --filename USER_ID_SET_FILENAME
使用 distinct_id 删除的指令
sa_clean clean_event_and_profile_by_id_list --project PROJECT_NAME --filename DISTINCT_ID_SET_FILENAME --
is_distinct_id
注：如果使用 distinct_id 删除的指令删除用户的事件数据和用户数据，必须要保证 events 表中有该用户的事件数据，才能找到该用户在 users 表中的信
息，并删除。否则删除不成功，需要使用 user_id 删除指令才能删除。
方案二：使用 profile_delete 标记删除
参数列表：
参数名 必须 说明 格式 样例 备注
only_profile 是否只删除 profile 表中的数据 指定后，仅删除 profile 数据
project 操作对应的项目，默认为“默认项目” 项目名 my_project
1. 用户调用 profile_delete 接口标记数据为删除状态
2. 使用如下命令删除数据 删除 events 和 users 表中的所有数据
sa_clean clean_event_and_profile_by_is_deleted --project PROJECT_NAME
仅删除 users 表中的用户数据sa_clean clean_event_and_profile_by_is_deleted --project PROJECT_NAME --only_profile
2.3. 事件去重
该方法会去重重复导入的数据，目前仅集群私有环境支持此方法。
参数列表：
参数名 必须 说明 格式 样例 备注
begin √ 删除数据的起始日期（包含这一天） yyyy-MM- 2015-12-21
dd
end √ 删除数据的结束日期（包含这一天） yyyy-MM- 2015-12-22
dd
project 操作对应的项目，默认为“默认项目” 项目名 my_project
skip_properties 去重时需要忽略的属性，多个属性之间使用逗号分隔 属性名 $ip,$city 1.13及之后支持，请先小版本升级
去重 my_project 项目 2016 年 1 月 2 号全天的数据，忽略 $ip 属性
sa_clean distinct_event_by_date --project my_project --begin ''2016-01-02'' --end ''2016-01-02'' --skip_properties
''$ip'',''$city''
注：可以指定忽略某个事件属性属性去重，即不校验该属性的值是否一样。目前不支持指定忽略 time 删除重复数据
3. 其他
由于删除是不可逆操作，所以执行过程中需要用户键入 yes 并回车才会进行实际删除操作。如果在执行前已经确认操作是正确的（主要用于自动化脚本），
那么可以加 --yes 参数，将不会再要求键入 yes 才能执行。.数据清理工具使用说明 v1.14
1. 概述
数据清理工具既可用于清理神策分析中导入的行为事件数据，也可用于对导入的行为事件数据去重。
该工具 不提供 的功能如下：
1. 删除指定属性的数据。
2. 删除某次批量导入的数据。
3. 删除某个时间段导入的数据。
4. 将某个事件定义删除。但是元数据管理中可以对事件进行隐藏，管理员可以操作。
数据清理为 不可逆操作，频繁或大量的清理数据将导致碎片过多可能会 影响导入进度，请谨慎操作。
除了 HdfsImporter 导入工具之外，其他导入数据的方式，导入的数据都是会先经过 Kudu，达到一定条件之后，事件数据才会转换到 Hdfs 中存储。
如您的神策分析版本在 1.13 及以下且为集群版环境，需要注意，数据清理工具默认只会删除 Hdfs 中的数据，不会清除 Kudu 中的数据。如需要清除最近导入
的数据，请不要停止导入数据并等候 4 小时以上，以确保最近导入的数据顺利进入到 Hdfs中。
2. 使用方法
请先 ssh 到部署了神策服务的任意一台机器，在 sa_cluster 账户下使用数据清理工具。从 root 切换到 sa_cluster 账户：
su - sa_cluster
请注意 su 与 sa_cluster 中间的减号。
2.1. 事件删除
该方法可以清理一个项目指定时间段内 所有事件或者某些指定事件 的行为事件数据。
该时间段为 事件行为 的时间，非导入数据的时间段。
该方法会保留事件、事件属性的定义。
单机版：不会立即释放磁盘，后台会缓慢释放，如果删除的是指定事件的数据那么释放的时间可能会很长。
集群版：不会立即释放磁盘，每天凌晨会例行清理。注意 ： 集群版事件删除一般需要消耗大量时间和资源，尽量不要指定过大的时间范围。另外支
持使用 -m 参数加快执行速度。
参数列表：
参数名 必 说明 格式 样例 备注
须
begin √ 删除数据的起始日期（包含这一天） yyyy-MM-dd 2015-12-21
end √ 删除数据的结束日期（包含这一天） yyyy-MM-dd 2015-12-22
events 指定删除数据的 event，集群版可同时指定多个事件，使用逗号分隔 事件名称 ButtonClick
project 操作对应的项目，默认为“默认项目” 项目名 my_project
hours 指定删除数据所属的小时数或范围，多个不连续的时间之间使用逗号分 [0-23] 0,[3-5] 仅集群版支持
max_tasks 指定 event 进行删除时，可以通过该参数设置任务的并发度，从而加快执行速度，默认为1。 正整数 2 仅集群版支持
libs 删除的事件来源，多个来源之间使用逗号分隔。 LIBS LIBS 仅集群版支持
清除 default 项目下 2015 年 12 月 22 日这 1 天的行为事件数据：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --project default
清除 production 项目下 2015 年 12 月 20 日 到 22 日这 3 天的行为事件数据：
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --project production
清除 my_project 项目下 ButtonClick 这个事件 2015 年 12 月 20 日 到 22 日这 3 天的行为事件数据，其他事件无改动：
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --events ButtonClick --project my_project注：如果 events 对应的事件名带 "$" 符号，则 events 后的事件名需要加单引号:
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --events ''$AppStart'' --project my_project
清除 my_project 项目 ButtonClick 这个事件 2015 年 12 月 22 日 0 点、3 点、4 点、5 点的行为事件数据，其他事件无改动：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --events ButtonClick --hours 0,[3-5] --project
my_project
清除 my_project 项目 ButtonClick 这个事件 2015 年 12 月 22 日 0 点、3 点、4 点、5 点的来自于 scala 和 python 的行为事件数据，其他事件
无改动：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --events ButtonClick --hours 0,[3-5] --project
my_project --libs scala,python
2.2. 支持GDPR欧盟标准 ，删除底层用户数据 (目前仅支持1.13.5169+单机版)
方案一： 使用用户 id 直接删除 (目前 events 和 users 表中的数据均被删除)
参数列表：
参数名 必 说明 格式 样例 备注
须
filename √ 包含 id set 的文件 filename user_id.txt 默认为 user_id
is_distinct_id id set 的文件中包含的是否是 distinct_id 若 id set 中的数据是 distinct_id, 需指定此参数
project 操作对应的项目，默认为“默认项目” 项目名 my_project
1. 创建用户文本，每行一个用户（user_id 或者 distinct_id）（USER_ID_SET_FILENAME或者DISTINCT_ID_SET_FILENAME）
2. 使用如下指令删除
使用 user_id 删除的指令
sa_clean clean_event_and_profile_by_id_list --project PROJECT_NAME --filename USER_ID_SET_FILENAME
使用 distinct_id 删除的指令
sa_clean clean_event_and_profile_by_id_list --project PROJECT_NAME --filename DISTINCT_ID_SET_FILENAME --
is_distinct_id
注：如果使用 distinct_id 删除的指令删除用户的事件数据和用户数据，必须要保证 events 表中有该用户的事件数据，才能找到该用户在 users 表中的信
息，并删除。否则删除不成功，需要使用 user_id 删除指令才能删除。
方案二：使用 profile_delete 标记删除
参数列表：
参数名 必须 说明 格式 样例 备注
only_profile 是否只删除 profile 表中的数据 指定后，仅删除 profile 数据
project 操作对应的项目，默认为“默认项目” 项目名 my_project
1. 用户调用 profile_delete 接口标记数据为删除状态
2. 使用如下命令删除数据 删除 events 和 users 表中的所有数据
sa_clean clean_event_and_profile_by_is_deleted --project PROJECT_NAME
仅删除 users 表中的用户数据sa_clean clean_event_and_profile_by_is_deleted --project PROJECT_NAME --only_profile
2.3. 事件去重
该方法会去重重复导入的数据，目前仅集群私有环境支持此方法。
参数列表：
参数名 必须 说明 格式 样例 备注
begin √ 删除数据的起始日期（包含这一天） yyyy-MM- 2015-12-21
dd
end √ 删除数据的结束日期（包含这一天） yyyy-MM- 2015-12-22
dd
project 操作对应的项目，默认为“默认项目” 项目名 my_project
skip_properties 去重时需要忽略的属性，多个属性之间使用逗号分隔 属性名 $ip,$city 1.13及之后支持，请先小版本升级
去重 my_project 项目 2016 年 1 月 2 号全天的数据，忽略 $ip 属性
sa_clean distinct_event_by_date --project my_project --begin ''2016-01-02'' --end ''2016-01-02'' --skip_properties
''$ip'',''$city''
注：可以指定忽略某个事件属性属性去重，即不校验该属性的值是否一样。目前不支持指定忽略 time 删除重复数据
3. 其他
由于删除是不可逆操作，所以执行过程中需要用户键入 yes 并回车才会进行实际删除操作。如果在执行前已经确认操作是正确的（主要用于自动化脚本），
那么可以加 --yes 参数，将不会再要求键入 yes 才能执行。.数据清理工具使用说明 v1.15
1. 概述
数据清理工具既可用于清理神策分析中导入的行为事件数据，也可用于对导入的行为事件数据去重。
该工具 不提供 的功能如下：
1. 删除指定属性的数据。
2. 删除某次批量导入的数据。
3. 删除某个时间段导入的数据。
4. 将某个事件定义删除。但是元数据管理中可以对事件进行隐藏，管理员可以操作。
数据清理为 不可逆操作，频繁或大量的清理数据将导致碎片过多可能会 影响导入进度，请谨慎操作。
除了 HdfsImporter 导入工具之外，其他导入数据的方式，导入的数据都是会先经过 Kudu，达到一定条件之后，事件数据才会转换到 Hdfs 中存储。
如您的神策分析版本在 1.13 及以下且为集群版环境，需要注意，数据清理工具默认只会删除 Hdfs 中的数据，不会清除 Kudu 中的数据。如需要清除最近导入
的数据，请不要停止导入数据并等候 4 小时以上，以确保最近导入的数据顺利进入到 Hdfs中。
2. 使用方法
请先 ssh 到部署了神策服务的任意一台机器，在 sa_cluster 账户下使用数据清理工具。从 root 切换到 sa_cluster 账户：
su - sa_cluster
请注意 su 与 sa_cluster 中间的减号。
2.1. 事件删除
该方法可以清理一个项目指定时间段内 所有事件或者某些指定事件 的行为事件数据。
该时间段为 事件行为 的时间，非导入数据的时间段。
该方法会保留事件、事件属性的定义。
单机版：不会立即释放磁盘，后台会缓慢释放，如果删除的是指定事件的数据那么释放的时间可能会很长。
集群版：不会立即释放磁盘，每天凌晨会例行清理。注意 ： 集群版事件删除一般需要消耗大量时间和资源，尽量不要指定过大的时间范围。另外支
持使用 -m 参数加快执行速度。
参数列表：
参数名 必 说明 格式 样例 备注
须
begin √ 删除数据的起始日期（包含这一天） yyyy-MM-dd 2015-12-21
end √ 删除数据的结束日期（包含这一天） yyyy-MM-dd 2015-12-22
events 指定删除数据的 event，集群版可同时指定多个事件，使用逗号分隔 事件名称 ButtonClick
project 操作对应的项目，默认为“默认项目” 项目名 my_project
hours 指定删除数据所属的小时数或范围，多个不连续的时间之间使用逗号分 [0-23] 0,[3-5] 仅集群版支持
max_tasks 指定 event 进行删除时，可以通过该参数设置任务的并发度，从而加快执行速度，默认为1。 正整数 2 仅集群版支持
libs 删除的事件来源，多个来源之间使用逗号分隔。 LIBS LIBS 仅集群版支持
清除 default 项目下 2015 年 12 月 22 日这 1 天的行为事件数据：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --project default
清除 production 项目下 2015 年 12 月 20 日 到 22 日这 3 天的行为事件数据：
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --project production
清除 my_project 项目下 ButtonClick 这个事件 2015 年 12 月 20 日 到 22 日这 3 天的行为事件数据，其他事件无改动：
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --events ButtonClick --project my_project注：如果 events 对应的事件名带 "$" 符号，则 events 后的事件名需要加单引号:
sa_clean clean_event_by_date --begin 2015-12-20 --end 2015-12-22 --events ''$AppStart'' --project my_project
清除 my_project 项目 ButtonClick 这个事件 2015 年 12 月 22 日 0 点、3 点、4 点、5 点的行为事件数据，其他事件无改动：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --events ButtonClick --hours 0,[3-5] --project
my_project
清除 my_project 项目 ButtonClick 这个事件 2015 年 12 月 22 日 0 点、3 点、4 点、5 点的来自于 scala 和 python 的行为事件数据，其他事件
无改动：
sa_clean clean_event_by_date --begin 2015-12-22 --end 2015-12-22 --events ButtonClick --hours 0,[3-5] --project
my_project --libs scala,python
2.2. 支持GDPR欧盟标准 ，删除底层用户数据 (目前仅支持1.13.5169+单机版)
方案一： 使用用户 id 直接删除 (目前 events 和 users 表中的数据均被删除)
参数列表：
参数名 必 说明 格式 样例 备注
须
filename √ 包含 id set 的文件 filename user_id.txt 默认为 user_id
is_distinct_id id set 的文件中包含的是否是 distinct_id 若 id set 中的数据是 distinct_id, 需指定此参数
project 操作对应的项目，默认为“默认项目” 项目名 my_project
1. 创建用户文本，每行一个用户（user_id 或者 distinct_id）（USER_ID_SET_FILENAME或者DISTINCT_ID_SET_FILENAME）
2. 使用如下指令删除
使用 user_id 删除的指令
sa_clean clean_event_and_profile_by_id_list --project PROJECT_NAME --filename USER_ID_SET_FILENAME
使用 distinct_id 删除的指令
sa_clean clean_event_and_profile_by_id_list --project PROJECT_NAME --filename DISTINCT_ID_SET_FILENAME --
is_distinct_id
注：如果使用 distinct_id 删除的指令删除用户的事件数据和用户数据，必须要保证 events 表中有该用户的事件数据，才能找到该用户在 users 表中的信
息，并删除。否则删除不成功，需要使用 user_id 删除指令才能删除。
方案二：使用 profile_delete 标记删除
参数列表：
参数名 必须 说明 格式 样例 备注
only_profile 是否只删除 profile 表中的数据 指定后，仅删除 profile 数据
project 操作对应的项目，默认为“默认项目” 项目名 my_project
1. 用户调用 profile_delete 接口标记数据为删除状态
2. 使用如下命令删除数据 删除 events 和 users 表中的所有数据
sa_clean clean_event_and_profile_by_is_deleted --project PROJECT_NAME
仅删除 users 表中的用户数据sa_clean clean_event_and_profile_by_is_deleted --project PROJECT_NAME --only_profile
2.3. 事件去重
该方法会去重重复导入的数据，目前仅集群私有环境支持此方法。
参数列表：
参数名 必须 说明 格式 样例 备注
begin √ 删除数据的起始日期（包含这一天） yyyy-MM- 2015-12-21
dd
end √ 删除数据的结束日期（包含这一天） yyyy-MM- 2015-12-22
dd
project 操作对应的项目，默认为“默认项目” 项目名 my_project
skip_properties 去重时需要忽略的属性，多个属性之间使用逗号分隔 属性名 $ip,$city 1.13及之后支持，请先小版本升级
去重 my_project 项目 2016 年 1 月 2 号全天的数据，忽略 $ip 属性
sa_clean distinct_event_by_date --project my_project --begin ''2016-01-02'' --end ''2016-01-02'' --skip_properties
''$ip'',''$city''
注：可以指定忽略某个事件属性属性去重，即不校验该属性的值是否一样。目前不支持指定忽略 time 删除重复数据
3. 其他
由于删除是不可逆操作，所以执行过程中需要用户键入 yes 并回车才会进行实际删除操作。如果在执行前已经确认操作是正确的（主要用于自动化脚本），
那么可以加 --yes 参数，将不会再要求键入 yes 才能执行。多项目管理工具使用说明.多项目管理工具使用说明 v1.13
1. 概述
神策分析在 1.5 版本里面推出了“ 多项目 ”功能。本文介绍多项目管理工具的使用方法。
多项目管理工具提供如下几个功能：
1. 列出所有项目
2. 新建项目
3. 更新项目显示名
4. 删除项目
5. 回收已删除项目的资源
6. 重置登录系统的密码
此外：
关于项目重置功能请参见 多项目;
云版多项目相关操作请联系值班同学处理;
2. 使用方法
请在 sa_cluster 账户下使用该工具。从 root 切换到 sa_cluster 账户的方法：
su - sa_cluster
请注意 su 与 sa_cluster 中间的减号。
2.1. 列出所有项目
执行以下命令可以列出所有项目：
project_tools -m list
运行输出样例如下：
project.id: 1
name: default
cname:
status: AVAILABLE
super_token: FFNJ24C31
normal_token: 8FWI1GN1F
create_time: 2016-06-29 23:46:39.0
1 project.
2 .
其中 status 共有 3 种取值，分别含义如下：
CREATED: 已经创建，不能导入数据，一般出现在刚创建项目的前 1 分钟内，之后转为 PREPARED；
PREPARED: 可以导入，但还不能查询，该状态一般出现在新项目创建还没有导入数据；
AVAILABLE: 可以查询，即已经导入行为事件数据；
2.2. 新建项目
执行以下命令可以新建项目：
project_tools -m create -n <> [-c <>] -p <admin> [--normal_token < Normal Token>] [--super_token < Super
Token>]参数解释：
-n, --name: 项目名称，需要是一个合法的变量名，即英文大小写字母、数字以及下划线组成，第一个字符不能为数字；
-p, --password: 新项目的admin帐号的密码；
-c, --cname: 项目显示名，可以是中文名，用于界面显示。此参数可选，若不输入则项目显示名同项目名称；
--normal_token: 1.6 新增配置项，项目的 Normal Token。可选参数，若不设置则值为空；
--super_token: 1.6 新增配置项，项目的 Super Token。可选参数，若不设置则值为空；
例子：
project_tools -m create -n my_project -c -p PasswordTest123
执行以上命令即可创建名为 my_project ，显示名为“我的项目”的新项目，登录时使用帐号 admin，密码 PasswordTest123。在
创建这个账号之后，就可以使用这个账号登录相应的项目，然后再在界面上创建账号和分配权限了。
若当前项目个数已达到许可所限制的项目数最大值，则无法再创建新项目。您可以删除项目或更换许可后再创建新项目。
2.3. 更新项目配置
执行以下命令可以更新项目配置：
project_tools -m update -n <> [-c <>] [--normal_token < Normal Token>] [--super_token < Super Token>] [--
clear_normal_token] [--clear_super_token]
参数解释：
-n, --name: 要修改配置的项目名;
-c, --cname: 设置项目显示名，可选参数；
--normal_token: 1.6 新增配置项，设置项目的 Normal Token，可选参数；
--super_token: 1.6 新增配置项，设置项目的 Super Token，可选参数；
--clear_normal_token: 1.6 新增配置项，将 Normal Token 设置为空值，可选参数；
--clear_super_token: 1.6 新增配置项，将 Super Token 设置为空值，可选参数；
例子：
project_tools -m update -n my_project -c
2.4. 删除项目
执行以下命令可以删除项目：
project_tools -m delete -n <>
参数解释：
-n, --name: 删除项目的项目名称；
例子：
project_tools -m delete -n my_project
请注意：项目删除后不可恢复，请谨慎操作！
默认项目 default 不能删除，但可以重置。关于重置功能请参见 多项目。
2.5. 回收已删除项目的资源执行以下命令可以回收已删除项目的资源：
project_tools -m purge
请注意：该操作运行时间较长，请耐心等待！
2.6. 用户工具（神策分析版本 < 1.14）
使用这个工具可以重置 admin 密码：
user_tools -username admin -password PASSWORD -project default
参数解释：
-username: 指定用户名（无限制），若指定用户不存在则创建，权限为管理员；
-password: 指定用户密码（无限制）；
-project: 指定项目英文名；
2.7. 用户工具（神策分析版本 >= 1.14）
使用这个工具可以重置 admin 密码：
spadmin account -u admin -P PASSWORD -p default -r analyst
参数解释：
-u: 指定用户名（必须为邮箱格式），必选；
-P: 指定用户密码（必须使用 8 至 30 个字母、数字和符号的组合），必选；
-p: 指定项目英文名，必选；
-r: 指定角色英文名，修改密码非必选，创建新用户必选。默认有 admin（管理员）、analyst（分析师）、guest（普通用户）三种，如果要指定自
定义角色，请联系值班同学处理。
-g: 指定是否为平台账号，默认为 false（仅限 1.15）元数据创建工具使用说明.元数据创建工具使用说明 v1.13
1. 概述
神策分析数据模型元数据主要包括事件定义、事件属性定义、用户属性定义等，通过神策分析可以查看、管理当前项目的元数据。
在默认情况下，系统会根据数据所属的事件、包含的属性或用户属性来创建元数据。若不希望任何数据都可以创建元数据，可以通过设置项目的
SuperToken 来实现限制。但是设置了 SuperToken 后，若想创建元数据，必须使用设置 SuperToken 的数据进行导入，这又带来了一些其他的麻烦，所以我
们提供了元数据创建工具，可以直接通过命令行创建元数据。
元数据创建工具有如下几个功能:
创建事件;
创建事件属性;
创建用户属性;
创建物品属性；
绑定事件与事件属性;
导出元数据;
导入元数据;
本文将分别介绍每个功能。
使用前请先执行如下命令切换系统账户:
sudo su - sa_cluster
请注意，元数据一旦创建无法删除，请创建前确认无误。可以在前端使用管理员帐号登录后在元数据界面隐藏不需要的事件或属性;
每次操作必须指定 `--project` 参数，表示本次元数据操作的项目;
一个使用实践：
步骤 1: 为 正式项目(区别于测试项目) 的项目设置 SuperToken (设置方法请见多项目管理工具使用说明，实际使用时不使用 SuperToken。这样除
非特意指定 SuperToken，否则不会根据数据创建事件、事件属性、用户属性或物品属性;
步骤 2: 在 测试项目中创建需要的元数据，创建方法可以是通过导入数据创建，或使用本工具创建;
步骤 3: 使用本工具导出 测试项目 的元数据，适当编辑后，再将其导入 正式项目 中;
步骤 4: 在 正式项目中使用（导入、查询）新的事件或属性;
该实践的优点是新建元数据的操作都在 测试项目中经过检验，无误后才在 正式项目 中使用。
2. 创建事件
schema_tools -m create_event \
--project <> \
--name <> \
[--cname <>] \
[--properties <>] \
[--bucket <>] \
[--yes]
project: 必须参数，操作的项目名，默认项目请使用 default;
name: 必须参数，事件名须是合法的变量名，即不能以数字开头，且只能包含：大小写字母、数字、_ 和
$ cname: 可选参数，可在界面上配置，不加该参数显示名默认同事件名;
properties: 可选参数，导入数据时可与事件属性自动绑定，与在这里指定效果相同; 多个属性名使用英文逗号分隔。若属性不存在则创建失败，请先
创建事件属性;
bucket: 可选参数，事件分桶选项，若无特殊情况请勿指定，可选值: new 表示使用新分桶，event:xxx 表示与 xxx 事件同分桶，或直接给出分桶
ID;
yes: 可选参数，如参数指定则不需要再额外确定;
例如在 MyProject 项目中创建事件 BuyGold，显示名是“购买黄金”:schema_tools -m create_event \
--project MyProject \
--name BuyGold \
--cname
例如在 MyProject 项目中创建事件 BuyGold，显示名是“购买黄金”，且事件包含两个属性 Weight,Price:
schema_tools -m create_event \
--project MyProject \
--name BuyGold \
--cname \
--properties Weight,Price
若 name 相同或 cname 相同的事件已经存在，则会创建失败;
若指定了 properties 字段但最终绑定事件属性失败（例如事件属性不存在），这时事件也不会创建成功；
3. 创建事件属性
schema_tools -m create_event_property \
--project <> \
--name <> \
--data_type <> \
[--cname <>] \
[--yes]
project: 必须参数，操作的项目名，默认项目请使用 default;
name: 必须参数，属性名须是合法的变量名，即不能以数字开头，且只能包含：大小写字母、数字、_ 和 $
data_type: 必须参数，代表这个数据的数据类型，可选值包括 NUMBER / BOOL / STRING / LIST / DATE / DATETIME, 请参考 数据格式
cname: 可选参数，可在界面上配置，不加该参数显示名默认同属性名;
yes: 可选参数，如参数指定则不需要再额外确定;
例如在 MyProject 项目中创建属性 Price, 显示名是“价格”:
schema_tools -m create_event_property \
--project MyProject \
--name Price \
--cname \
--data_type NUMBER
若 name 相同或 cname 相同的事件已经存在，则会创建失败;
4. 创建用户属性
除了-m 外其他参数与 创建事件属性 参数相同。
例如在 MyProject 项目中创建属性 PhoneNumber, 显示名是“电话号码”:
schema_tools -m create_profile_property \
--project MyProject \
--name PhoneNumber \
--cname \
--data_type STRING5. 创建物品属性
除了 -m 外其他参数与 创建事件属性 参数相同。
例如在 MyProject 项目中创建属性 itemProperty, 显示名是“物品属性”:
item
6. 绑定事件与事件属性
schema_tools -m bind_event_properties \
--project <> \
--event <> \
--properties <>
[--yes]
project: 必须参数，操作的项目名，默认项目请使用 default;
event: 必须参数，进行绑定的事件名;
properties: 必须参数，绑定的属性名，多个时使用英文逗号分隔;
yes: 可选参数，如参数指定则不需要再额外确定;
例如在 MyProject 项目中将 BuyGold 事件与 Price 和 Weight 绑定:
schema_tools -m bind_event_properties \
--project MyProject \
--event BuyGold \
--properties Price,Weight
7. 导出元数据
使用本工具导出的元数据可以直接用于导入(下一节介绍)。
schema_tools -m export \
--project <> \
[--file <>]
project: 必须参数，操作的项目名，默认项目请使用 default;
file: 可选参数，不指定则输出到标准输出;
运行后会导出指定项目的元数据信息，例如:
schema_tools -m export \
--project MyProject \
--file meta.json
导出的样例格式如下:
{
"events" : [
{
"name" : "BuyGold",
"cname" : "",
"visible" : true
},{
"name" : "PageView",
"cname" : "",
"visible" : true
}
],
"event_properties" : [
{
"name" : "Price",
"cname" : "",
"data_type" : "NUMBER",
"visible" : true
},
{
"name" : "Weight",
"cname" : "Weight",
"data_type" : "NUMBER",
"visible" : true
}
],
"profile_properties" : [
{
"name" : "PhoneNumber",
"cname" : "",
"data_type" : "STRING",
"visible" : true
}
],
"item_properties" : [
{
"name" : "itemProperty",
"cname" : "",
"data_type" : "STRING",
"visible" : true
}
],
"bound_event_properties" : [
{
"event" : "BuyGold",
"properties" :
[ "Price",
"Weight"
]
},
{
"event" : "PageView",
"properties" :
[ "Weight"
]
}
]
}
8. 导入元数据
导入的元数据格式请见 6.导出元数据 中输出的 JSON;
使用本工具导出的元数据可以直接用于导入。
schema_tools -m import \
--project production \
--file <>
project: 必须参数，操作的项目名，默认项目请使用 default;
file: 必须参数，指定导入的元数据所在文件;其他说明 ：
若导入的数据中包含的事件已经存在，那么忽略该事件继续导入;
若导入的数据中包含的事件或用户属性已经存在，那么对比其数据类型，若相同则忽略该属性继续导入，若类型不相同则全部导入失败;
（20170414之后的版本支持）若事件或属性已存在，且指定了显示名，将使用新的显示名覆盖旧的显示名;
如果导入失败，本次导入失败前的操作都不生效;
目前导入元数据工具仅支持修改元事件和属性的显示名，不支持修改元事件和属性的可见/隐藏状态。环境检测工具使用说明.环境检测工具使用说明 v1.13
1. 概述 1. 概述
2. 检测步骤
2.1. 获取检测程序
神策环境检测工具主要用于检测服务器是否满足部署神策分析的要求。 2.2. 解压并进入程序目录
2.3. 复制配置模板并编辑配置
主要检测项目有： 2.3.1. 配置参数说明
硬件：cpu 核数、内存大小、磁盘容量、磁盘读写速率等； 2.4. 执行检测
系统：发行版本、内核版本、防火墙设置、当前运行的服务等； 2.5. 查看检测结果
其他：集群之间带宽、是否可正常访问 ntp 服务器、python 标 2.6. 提交检测结果
准的 paramiko 库是否可用等。 3. 其他使用方法
2. 检测步骤
若检测集群，只需在其中一台机器上下载、配置并运行即可。
2.1. 获取检测程序
wget http://update.sensorsdata.cn/release/devops/sa-env_checker-2.0.tar.gz
2.2. 解压并进入程序目录
tar zxf sa-env_checker-2.0.tar.gz && cd sa-env_checker-2.0
2.3. 复制配置模板并编辑配置
cp env.yml.example env.yml
vim env.yml
2.3.1. 配置参数说明
所有符号均需为半角，即英文输入法下的符号；
需遵循 yaml 语法，如冒号后面必需要有空格。
ips： ip 地址，多个以逗号分隔。不可为空；
hosts：正式部署时要修改为的主机名，多个以逗号分隔，需与 ips 一一对应，需符合 FQDN 要求。不可为空；
ssh_port：ssh 端口，默认为 22。不可为空；
password：ssh 密码，若所有节点密码相同，则只需填写一个字符串，如 Password；若节点之间密码不同，则以列表形式填写，如
[''Passwd1'', ''Passwd2'', ''Passwd3'']。不可为空；
meta_disk_path：元数据盘挂载点，目前只支持一块，做了 raid 的 ssd 磁盘。不可为空；
data_disk_paths：数据盘挂载点，多块以逗号分隔，一般未做 raid 的裸盘。若为单机版则与 meta_disk_path 保持一致即可。不可为空； ntp：
ntp server 地址，不能连接外网的客户必须填写，默认检测 0.cn.pool.ntp.org；
sudo_need_password：非 root 用户执行 sudo 需要输入密码时，则更改为 True，默认为 False；
ex_ips：已有环境的已有主机的 ip 地址，用于增加节点时，测试与已存在主机之间的带宽，非必选；
2.4. 执行检测
检测全部
./env_checker env.yml若数据盘太多，可并行检测 n 块数据盘以缩短检测时间，但需满足 1 <= n <= 6，且 n <= 数据盘数量。例如同时检测 3 块数据盘
./env_checker env.yml --disk_thread 3
2.5. 查看检测结果
全部合格输出结果
Check done, you can view the results via https://www.json.cn
Get the results by:
cat /data/sa-env_checker-2.0/runtime/all_results.json
cat /data/sa-env_checker-2.0/runtime/all_unmatch.json
Congratulations~ All matched
有不合格项目输出结果
Check done, you can view the results via https://www.json.cn
Get the results by:
cat /data/sa-env_checker-2.0/runtime/all_results.json
cat /data/sa-env_checker-2.0/runtime/all_unmatch.json
10.10.10.10.unmatch:
cpu count 4 < 16
2.6. 提交检测结果
所有检测结果及日志都保存在运行目录的 runtime/ 下，需把 all_results.json 和 all_unmatch.json 提交给神策的同学.
检测结果的绝对路径如检测结果输出中的
/data/sa-env_checker-2.0/runtime/all_results.json
/data/sa-env_checker-2.0/runtime/all_unmatch.json
3. 其他使用方法
获取使用帮助
./env_checker -h
不分发包直接检测 用于第 n 次检测时使用 n > 1
./env_checker env.yml -s
只检测集群间带宽
./env_checker env.yml --only_bw不检测集群间带宽
./env_checker env.yml --no_bw
只检测磁盘
./env_checker env.yml --only_disks
不检测磁盘
./env_checker env.yml --no_disks
不检测当前运行服务
./env_checker env.yml --no_services
不检测 ntp server 等服务的可连接性，用于服务器未配置 dns 时检测
./env_checker env.yml --no_connections
不检测安装包下载速度，用于无外网环境
./env_checker env.yml --no_check_download高级功能.高级功能 v1.13
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本章节包括了一系列高级使用功能，涉及较多技术细
节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
数据接入 API
App 消息推送
虚拟属性和维度表
数据预处理模块
服务转发配置
使用 HTTPS 的数据接入
API
第三方登录
数据归档数据接入 API.数据接入 API v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
神策分析 数据采集 一般使用各语言的 SDK 或我们提供的批量或流式数据导入工具来完成。
在一些特殊情况下，如果用户希望实现自己的接入工具，可以参考本文档。
若无特殊需求，建议使用我们的 SDK 或工具来进行数据接入，以避免未知的问题，并方便以后新功能的使用。例如当使用的编程语言
没有对应的 SDK 时，可以考虑使用 LogAgent 或其他批量导入工具。
外部数据接入神策分析分为几个步骤：
1. 生成数据
在神策分析数据接入过程中，每条数据（包括任何事件行为和用户属性数据）都是一个符合 数据格式 的 JSON。
例如：
{
"distinct_id":"2b0a6f51a3cd6775",
"time":1434556935000,
"type":"track",
"event":"ViewProduct",
"properties":{
"$manufacturer":"Apple",
"$model":"iPhone 5",
"$os":"iOS",
"$os_version":"7.0",
"$app_version":"1.3",
"$wifi":true,
"$ip":"180.79.35.65",
"$province":"",
"$city":"",
"$screen_width":320,
"$screen_height":640,
"product_id":12345,
"product_name":"",
"product_classify":"",
"product_price":14
}
}
当希望一次发送多条数据时，可以构造一个 Json 数组，每个元素是一个完整的 Json。
建议一次最多不超过 50 条数据；
仅发送一条可以使用长度为 1 的 Json 数组。
例如：
[
{
"distinct_id":"2b0a6f51a3cd6775",
"time":1434556935000,
"type":"track",
"event":"ViewProduct",
"properties":{
"product_name":"",
"product_classify":"",
"product_price":14
}
},
{
"distinct_id":"12345",
"type":"profile_set","time":1435290195610,
"properties":{
"Age":33,
"IncomeLevel":"3000~5000"
}
}
]
2. 编码
本步骤主要是将 1.生成数据 中的 JSON 或 JSON 数组 进行编码。其下几个子步骤需要顺次执行。
请使用 UTF-8 编码；
2.1. 进行 Gzip 压缩（可选）
为了优化数据传输，可以先对数据进行 Gzip 压缩。
此为可选步骤，可以不压缩。
2.2. 进行 Base64 编码（必须）
为了更好的兼容各种传输方式，需要对数据进行 Base64 编码。若进行了 2.1 进行 Gzip 压缩，则将压缩后的数据进行 Base64 编码；否则直接将要传输的
JSON 或 JSON 数组 进行 Base64 编码。
2.3. 进行 UrlEncode 编码（必须）
由于需要兼容数据作为 URL 参数传输，故需要对 2.2 进行 Base64 编码 得到的结果进行 UrlEncode，这个步骤可能是由浏览器或数据发送框架完成的。
2.4. 拼装 request
2.4.1. 一条 Json 数据
如果处理的是一条 Json 数据，request 格式如下：
data=xxxxx&gzip=1
data：即为 2.3 进行 UrlEncode 得到的编码结果；
gzip：是否进行了 Gzip 压缩；
2.4.2. 多条 Json 构成的数组
如果是一次发送多条 Json 构成的数组，request 格式如下：
data_list=xxxxx&gzip=1
data_list：即为 2.3 进行 UrlEncode 得到的编码结果； gzip：
是否进行了 Gzip 压缩；
2.5. 编码例子
本节演示对样例数据进行编码，假设数据已经写入到了 data.json 文件中：
[
{
"distinct_id":"2b0a6f51a3cd6775",
"time":1434556935000,
"type":"track",
"event":"ViewProduct",
"properties":{
"product_name":"",
"product_classify":"",
"product_price":14
}},
{
"distinct_id":"12345",
"type":"profile_set",
"time":1435290195610,
"properties":{
"Age":33,
"IncomeLevel":"3000~5000"
}
}
]
1. 先对数据进行 Gzip 并进行 Base64 编码，在 Linux 下可使用如下命令：
cat data.json | gzip | base64 -w 0
得到结果：
H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAW
aWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7
CgKDMZ7A24dC2YVauDP2QMjYD+VsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO+Zl5yfm+oDDMwcoJ3GwKCvA4W
/EronuGIBDY0g6OEBAAA=
2. 再对数据进行 UrlEncode 编码，如使用 在线工具样例数据 UrlEncode 编码得到：
H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAW
aWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7
CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%
2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d
3. 拼装 request：
gzip=1&data_list=H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqam
ZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5i
cXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%
2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d
3. 发送数据
即将编码后的数据发送到神策分析接收数据的 API。
API 地址：如果使用神策分析 Cloud 服务，则:
数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
（注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）
如果用户使用集群版私有部署的神策分析，默认的配置信息为：
数据接收地址: http://{$host_name}:8106/sa?project={$project_name}
其中 {$host_name} 可以是集群中任意一台机器。
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
例如，以 Cloud 服务为例，使用 curl 发送：
curl -v \
--data
''gzip=1&data_list=H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpg
YGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNm
zBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%
2fEronuGIBDY0g6OEBAAA%3d'' \
http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
4. 其他
如果没有特殊情况，不建议自己实现上面的接入流程，而是使用 SDK 或工具的方式接入数据。
神策分析是异步处理接收的数据，所以发送完成后需要等待片刻才能查询到。
本地反编码一条数据查看内容可以通过：
UrlDecode > data # UrlDecode bash
cat data | base64 -d | gzip -dApp 消息推送.App 消息推送 v1.13
注意：此文档不适用于神策智能运营（Sensors Focus）
神策智能运营对接请参考这里
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文
档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
App 消息推送是一种常用的运营手段，国内已有多家公司向 Android 和 iOS 开发者提供推送服务。神策分析 1.6 版本中提供了如下的方案，以便使用极光推
送和小米推送等第三方推送服务的开发者，能够将神策分析的分析结果同步到推送服务中，以便向定向的人群推送特定的消息，从而将用户行为分析能力与
推送服务结合，提高 App 的运营效果。
开发者将神策分析的结果同步到第三方推送服务的大致步骤如下：
开发者在第三方推送平台注册账号、添加应用；
在 App 中集成神策分析和第三方推送服务：
在 App 集成第三方推送平台的 SDK 和神策分析的 SDK，在 App 中获取第三方推送平台的设备推送 ID，并将该 ID 保存在神策分析的用
户 Profile 中；
在 App 中处理推送消息，并使用神策分析追踪推送结果；
在神策分析中添加推送相关配置，如 AppKey、保存设备推送 ID 的 Profile 名称等；
在神策分析中通过用户分群等功能使用 App 推送。
以下详细说明如何集成第三方推送服务。
1. 在 iOS 中集成第三方推送系统
1.1. 获取设备推送 ID
首先，开发者需要在 App 中集成第三方推送系统的 SDK，并在 App 初始化过程中获取设备推送 ID，并保存在神策分析的用户 Profile 中。以下简要说明集
成第三方推送系统的集成方式。
1.1.1. 极光推送
开发者请参考极光推送《iOS SDK 文档》，将极光推送的 SDK 集成到 App 中。请参考 神策 iOS SDK 将神策分析 SDK 集成到 App 中。
在 iOS App 中，获得 APNs 的Device Token 后，需要向极光推送注册，注册成功后极光推送会推送 kJPFNetworkDidLoginNotification 通知，开发者需
要监听该通知，并从极光推送中获取 Registration Id：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// App
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions {
// SDK Registration Id
[JPUSHService registrationIDCompletionHandler:^(int resCode, NSString *registrationID)
{ if (resCode == 0) {
// Registration Id Profile "jgId"
[SensorsAnalyticsSDK.sharedInstance profilePushKey:@"jgId" pushId:registrationID];}}];
}
// App APNs Device Token
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
// Device Token
[JPUSHService registerDeviceToken:deviceToken];
}
为了保证 Registration Id 能成功绑定到最新的用户上，需要在登录\切换用户时，重新绑定 Registration Id。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
[[SensorsAnalyticsSDK sharedInstance] login:account];
[JPUSHService registrationIDCompletionHandler:^(int resCode, NSString *registrationID)
{ if (resCode == 0) {
// Registration Id Profile "jgId"
[SensorsAnalyticsSDK.sharedInstance profilePushKey:@"jgId" pushId:registrationID];
}
}];
1.1.2. 小米推送
开发者请参考小米推送 iOS SDK 文档，将小米推送的 SDK 集成到 App 中。请参考 iOS SDK 将神策分析 SDK 集成到 App 中。
在 App启动时注册小米推送服务，注册成功后获取 APNs 的 Device Token
,注册时需要添加 MiPushSDKDelegate 协议。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
@interface AppDelegate ()<MiPushSDKDelegate,UNUserNotificationCenterDelegate>
@end
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
// APNS, deviceToken
[MiPushSDK bindDeviceToken:deviceToken];
}
实现 MiPushSDKDelegate 协议中的方法获取 regId。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
#pragma mark MiPushSDKDelegate
- (void)miPushRequestSuccWithSelector:(NSString *)selector data:(NSDictionary *)data {
//
// regId
if ([selector isEqualToString:@"bindDeviceToken:"]) {
// regId Profile "xmId"
[SensorsAnalyticsSDK.sharedInstance profilePushKey:@"xmId" pushId:data[@"regid"]];
}
}
1.1.3. 个推
请参考个推《iOS SDK 文档》，将个推的 SDK 集成到 App 中。开发者需要将 App 的设备推送 ID 保存在神策分析的用户 Profile 中。神策分析的用户分群
等分析功能会使用该设备推送 ID 进行用户关联。请参考 iOS SDK 将神策分析 SDK 集成到 App 中。
开发者在 GeTuiSdkDelegate 的 -GeTuiSdkDidRegisterClient: 中获取 clientId 保存在神策分析的用户 Profile 中：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId {
// clientId gtId
[SensorsAnalyticsSDK.sharedInstance profilePushKey:@"gtId" pushId:clientId];
}1.2. App 推送效果追踪
开发者可以使用神策分析追踪推送效果。当用户通过点击推送消息打开 App 时，通过神策分析 SDK 上报打开推送消息事件，并通过漏斗分析等功能，将用
户在点击推送消息打开 App 前后的行为关联起来。
您可以在 App 中监听第三方消息推送服务的广播或代理方法，当用户点击消息打开 App 或执行其他行为时，调用 track 接口记录 App 消息打开事件。假
设 App 打开消息成功事件的名称为 AppOpenNotification，中文名称为 App 打开消息，包含事件属性:
msg_title - 消息标题
msg_id - 消息唯一ID
以下简要介绍如何在 App 中记录上述 App 打开消息 事件，追踪极光推送的推送效果。
1.2.1. 极光推送
根据极光推送文档所述，需要为 AppDelegate 添加 Delegate，代码如下：
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
@interface AppDelegate ()<JPUSHRegisterDelegate>
@end
用户需要在 AppDelegate.m 中实现以下回调方法并在回调方法中调用神策分析 SDK 追踪打开消息的事件。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// iOS 10 Support
- (void)jpushNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:
(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
// Required
NSDictionary * userInfo = response.notification.request.content.userInfo;
if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
[JPUSHService handleRemoteNotification:userInfo];
}
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification"
withProperties:@{@"msg_title":[NSString
stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"msg_id":
[NSString stringWithFormat:@"%@",userInfo[@"_j_msgid"]]}];
//
[[SensorsAnalyticsSDK sharedInstance] flush];
completionHandler(); //
}
// Required, iOS 7 Support
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[JPUSHService handleRemoteNotification:userInfo];
if (application.applicationState == UIApplicationStateActive) {
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification"
withProperties:@{@"msg_title":[NSString
stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"
msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_j_msgid"]]}];
} else if (application.applicationState == UIApplicationStateBackground) {
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification"
withProperties:@{@"msg_title":[NSString
stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"
msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_j_msgid"]]}];
} else if (application.applicationState == UIApplicationStateInactive) {
// "App "
}
//
[[SensorsAnalyticsSDK sharedInstance] flush];
completionHandler(UIBackgroundFetchResultNewData);
}
1.2.2. 小米推送
用户需要在 AppDelegate.m 中实现以下回调方法并在回调方法中调用神策分析 SDK 追踪推送成功的事件。呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// iOS 10 Support
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:
(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
// Required
NSDictionary * userInfo = response.notification.request.content.userInfo;
if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
[JPUSHService handleRemoteNotification:userInfo];
}
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification" withProperties:@{@"msg_title":
[NSString stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_j_msgid"]]
}];
//
[[SensorsAnalyticsSDK sharedInstance] flush];
completionHandler(); //
}
// Required, iOS 7 Support
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[JPUSHService handleRemoteNotification:userInfo];
if (application.applicationState == UIApplicationStateActive) {
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification"
withProperties:@{@"msg_title":[NSString
stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"
msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_id_"]]}];
} else if (application.applicationState == UIApplicationStateBackground) {
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification"
withProperties:@{@"msg_title":[NSString
stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"
msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_id_"]]}];
} else if (application.applicationState == UIApplicationStateInactive) {
// "App "
}
//
[[SensorsAnalyticsSDK sharedInstance] flush];
completionHandler(UIBackgroundFetchResultNewData);
}
1.2.3. 个推
用户需要在 AppDelegate.m 中实现以下回调方法并在回调方法中调用神策分析 SDK 打开消息的事件。
呈现代码宏出错: 参数''com.atlassian.confluence.ext.code.render.InvalidValueException''的值无效
// Required, iOS 7 Support
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
if (application.applicationState == UIApplicationStateActive) {
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification" withProperties:@{@"msg_title":
[NSString stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_id_"]]
}];
} else if (application.applicationState == UIApplicationStateBackground) {
// "App "
[[SensorsAnalyticsSDK sharedInstance] track:@"AppOpenNotification" withProperties:@{@"msg_title":
[NSString stringWithFormat:@"%@",userInfo[@"aps"][@"alert"]],
@"msg_id":[NSString stringWithFormat:@"%@",userInfo[@"_id_"]]}];
} else if (application.applicationState == UIApplicationStateInactive) {
// "App "
}
//
[[SensorsAnalyticsSDK sharedInstance] flush];
completionHandler(UIBackgroundFetchResultNewData);
}
- (void)GeTuiSdkDidReceivePayloadData:(NSData *)payloadData andTaskId:(NSString *)taskId andMsgId:(NSString *)
msgId andOffLine:(BOOL)offLine fromGtAppId:(NSString *)appId {//
NSString *payloadMsg = nil;
if (payloadData) {
payloadMsg = [[NSString alloc] initWithBytes:payloadData.bytes length:payloadData.length encoding:
NSUTF8StringEncoding];
}
NSString *msg = [NSString stringWithFormat:@"taskId=%@,messageId:%@,payloadMsg:%@%@",taskId,msgId,
payloadMsg,offLine ? @"<>" : @""];
NSLog(@"\n>>>[GexinSdk ReceivePayload]:%@\n\n", msg);
[[SensorsAnalyticsSDK sharedInstance] track:@"AppReceivedGetuiNotification" withProperties:@{@"msg":msg}];
}
2. 在 Android 中集成第三方推送系统
2.1. 获取设备推送 ID
首先，开发者需要在 App 中集成第三方推送系统的 SDK，并在 App 初始化过程中获取设备推送 ID，并保存在神策分析的用户 Profile 中。以下简要说明集
成第三方推送系统的集成方式。
2.1.1. 极光推送
请参考极光推送《Android SDK 文档》，将极光推送的 SDK 集成到 App 中。开发者需要将 App 的设备推送 ID 保存在神策分析的用户 Profile 中。神策分
析的用户分群等分析功能会使用该设备推送 ID 进行用户关联。请参考 Android SDK 将神策分析 SDK 集成到 App 中。
极光推送使用唯一的 Registration Id 标示设备。开发者需要在 Manifest 中定义 Receiver 接受极光推送的广播，通过 cn.jpush.android.intent.
REGISTRATION 消息获取 Registration Id。
<receiver
android:name="Your Receiver"
android:enabled="true">
<intent-filter>
<action android:name="cn.jpush.android.intent.REGISTRATION" />
<action android:name="cn.jpush.android.intent.MESSAGE_RECEIVED" />
<action android:name="cn.jpush.android.intent.NOTIFICATION_RECEIVED" />
<action android:name="cn.jpush.android.intent.NOTIFICATION_OPENED" />
<category android:name="You package Name" />
</intent-filter>
</receiver>
广播 cn.jpush.android.intent.REGISTRATION 的 Intent 参数中JPushInterface.EXTRA_REGISTRATION_ID 为 Registration Id ，开发者在极光推送初始化
完成后，在广播中获取 Registration Id 保存在神策分析的用户 Profile 中：
public void onReceive(Context context, Intent intent) {
//
if (JPushInterface.ACTION_REGISTRATION_ID.equals(intent.getAction())) {
// RegistrationId
final String registrationId = intent.getExtras().getString(JPushInterface.
EXTRA_REGISTRATION_ID);
// ID
SensorsDataAPI.sharedInstance().profilePushId("jgId",registrationId);
}
}
由于极光 SDK 只会在第一次初始化成功时，发出 JPushInterface.ACTION_REGISTRATION_ID 广播，为确保已安装 App 的老用户也能把推送
ID 保存到神策分析的用户表中，可以在调用 login 方法后再次保存推送 ID：
// / login jgId
String registrationId=JPushInterface.getRegistrationID(this);
SensorsDataAPI.sharedInstance().profilePushId("jgId",registrationId);2.1.2. 小米推送
请参考小米推送服务《Android SDK 文档》，将小米推送的 SDK 集成到 App 中。开发者需要将 App 的设备推送 ID 保存在神策分析的用户 Profile 中。神
策分析的用户分群等分析功能会使用该设备推送 ID 进行用户关联。请参考 《神策分析 Android SDK 使用说明》将神策分析 SDK 集成到 App 中。
开发者在小米推送初始化完成后，在广播中获取 Registration Id 保存在神策分析的用户 Profile 中：
@Override
public void onReceiveRegisterResult(Context context, MiPushCommandMessage message)
{ String command = message.getCommand();
List<String> arguments = message.getCommandArguments();
String mRegId = ((arguments != null && arguments.size() > 0) ? arguments.get(0) : null);
if (MiPushClient.COMMAND_REGISTER.equals(command)) {
if (message.getResultCode() == ErrorCode.SUCCESS) {
//, ID
SensorsDataAPI.sharedInstance().profilePushId("xmId",mRegId);
}
}
}
2.1.3. 个推
请参考个推《Android SDK 文档》，将个推的 SDK 集成到 App 中。开发者需要将 App 的设备推送 ID 保存在神策分析的用户 Profile 中。神策分析的用户
分群等分析功能会使用该设备推送 ID 进行用户关联。请参考 《神策分析 Android SDK 使用说明》将神策分析 SDK 集成到 App 中。
开发者在 GTIntentService 的 onReceiveClientId 中获取 ClientId 保存在神策分析的用户 Profile 中：
@Override
public void onReceiveClientId(Context context, String clientid) {
// clientid gtId
SensorsDataAPI.sharedInstance().profilePushId("gtId",clientid);
}
在Android SDK 3.2.5版本及之后，可以调用 profileUnsetPushId(String pushTypeKey) 删除用户表的推送 id，pushTypeKey 为设置的用户属性的 key
值，如示例中的 gtId 等
2.2. App 推送效果追踪
开发者可以使用神策分析追踪推送效果。当用户收到推送消息时，通过神策分析 SDK 上报消息推送成功事件，并通过漏斗分析等功能，将用户在推送前的行
为和推送后的行为关联起来。
我们可以在 App 中监听第三方消息推送服务的广播，当收到消息时调用神策分析的 track 接口记录 App 推送成功事件；当用户点击消息打开 App 或执行其他
行为时，调用 track 接口记录 App 消息打开事件。
假设 App 推送成功事件的名称为 AppReceivedNotification，中文名称为 App 消息推送成功，包含事件属性:
msg_title - 消息标题
msg_id - 消息唯一ID
以下简要介绍如何在 App 中记录上述 App 消息推送成功 事件，追踪极光推送的推送效果。
2.2.1. 极光推送
如极光推送文档所述，用户需要在 Receiver 中处理极光推送的广播，并在收到消息时使用神策分析 SDK 追踪推送成功的事件。
public void onReceive(Context context, Intent intent) {
if (JPushInterface.ACTION_REGISTRATION_ID.equals(intent.getAction())) {
// Registration Id Profile
} else if (JPushInterface.ACTION_MESSAGE_RECEIVED.equals(intent.getAction())) {
// App
} else if (JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals(intent.getAction())) {
// "App "
Bundle message = intent.getExtras();
try {
JSONObject properties = new JSONObject();
// msg_title
properties.put("msg_title", message.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE));// ID msg_id
properties.put("msg_id", message.getString(JPushInterface.EXTRA_MSG_ID));
// "App "
SensorsDataAPI.sharedInstance().track("AppReceivedNotification", properties);
} catch (InvalidDataException e)
{ e.printStackTrace();
} catch (JSONException e)
{ e.printStackTrace(
);
}
} else if (JPushInterface.ACTION_NOTIFICATION_OPENED.equals(intent.getAction())) {
// "App "
}
2.2.2. 小米推送
如小米推送文档所述，用户需要在 Receiver 中处理小米推送的广播，并在收到消息时使用神策分析 SDK 追踪推送成功的事件。
@Override
public void onNotificationMessageArrived(Context context, MiPushMessage message)
{ try {
JSONObject properties = new JSONObject();
// msg_title
properties.put("msg_title", message.getTitle());
// ID msg_id
properties.put("msg_id", message.getMessageId());
// "
SensorsDataAPI.sharedInstance().track("AppReceivedNotification", properties);
} catch (Exception e) {
e.printStackTrace();
}
}
@Override
public void onNotificationMessageClicked(Context context, MiPushMessage message) {
// "App "
}
@Override
public void onReceivePassThroughMessage(Context context, MiPushMessage message) {
// App
}
2.2.3. 个推
如个推文档所述，用户需要在 GTIntentService 中处理推送消息，可以在透传消息到达时使用神策分析 SDK 追踪消息到达事件。
@Override
public void onReceiveMessageData(Context context, final GTTransmitMessage gtTransmitMessage)
{ try {
JSONObject properties = new JSONObject();
// ID msg_id
properties.put("msg_id", gtTransmitMessage.getMessageId());
// ""
SensorsDataAPI.sharedInstance().track("AppReceivedNotification", properties);
} catch (Exception e) {
e.printStackTrace();
}
}
3. 在神策分析中使用推送服务(以极光推送为例)
3.1. 填写推送配置开发在第三方推送平台注册了 App 后，使用管理员账户进入神策分析的推送服务管理界面。
新建推送服务，选择第三方推送服务商，填入 App Key、Secret Key 等配置信息，特别地，开发者需要填写保存设备推送 ID 的 Profile 名称，如前文的例
子中，我们在 jgId 中保存极光推送 Android App 的设备推送 ID。
成功添加推送服务后，将可以使用该推送配置，在用户分群、留存用户分析等分析功能中使用消息推送功能。
3.2. 用户分群
在神策分析中，可以按照用户的事件所体现的过往的行为特征和用户的 Profile 所体现的用户自然属性特征，来对整个用户群体进行分群。开发者可以根据分
群结果，对群体中的用户推送消息。如图，当用户编辑用户分群规则时，勾选推送渠道：当用户分群执行成功后，会自动在第三方推送渠道中为满足分群条件的用户标记 Tag，Tag 名称为用户分群的**英文名**。特别地，当开发者拥有多款 App
的多个推送渠道时，可以同时将推送结果同步到多个推送渠道的 Tag 中。
3.3. 第三方推送平台进行消息推送
开发者可以在第三方推送系统的后台，使用用户分群的英文名对应的 Tag 进行消息推送，例如在极光推送中：
更多关于如何使用神策分析用户分群，可以参考文档用户分群。
3.4. 用户列表
在神策分析的各种数据分析功能中，都可以根据分析结果获取对应的用户列表，如留存分析中，开发者可以获得第一天留存的用户列表：在用户列表中，可以根据用户列表的生成规则创建用户分群，此时我们也可以为该分群配置消息推送：
进而，在用户分群执行成功后，开发者可以在第三方推送系统的后台使用用户分群的英文名对应的 Tag 进行消息推送。
4. 推送效果追踪
如前文所述，开发者在 App 中集成第三方消息推送服务后，可以使用神策分析追踪推送效果。我们对一些常用的推送效果分析，做简单的介绍。
4.1. 统计推送成功的用户数
可以直接在事件分析中，统计 App 消息推送成功 事件的触发用户数，并筛选对应的消息唯一 ID 属性。
4.2. 分析推送成功的用户的转化
想查看某一段时间内，推送成功的用户的转化，可以在漏斗分析中新建漏斗，第一个步骤为 App 消息推送成功，第二个步骤为下订单等行为。
4.3. 分析推送成功的用户的留存
想查看某一段时间内，推送成功的用户的留存，可以在留存分析中，把初始行为设置为 App 消息推送成功，后续行为设置为 任意事件，或者某个表示用户
留存的核心行为。虚拟属性和维度表.虚拟属性和维度表 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
自 1.11 版本开始，神策分析已经支持虚拟属性功能，同时还支持使用第三方的维度表来对已接入的事件和属性进行进一步的扩展，该功能可以大大的增强神
策分析对于复杂业务需求的处理能力。
创建虚拟属性和维度表均需要在部署神策系统的服务器上操作。
请先 ssh 到部署了神策服务的任意一台机器，在 sa_cluster 账户下执行创建虚拟属性或者维度表的命令。
虚拟属性
所谓虚拟属性，是指在数据入库之后通过 SQL 表达式对已有的事件属性和用户属性进行二次加工，产生一个新的属性值。
注意：
1. events 表中的 time 和 event 属于特殊字段，目前支持对 time 字段二次加工，具体可参考应用场景 5 举例。不支持对 event 字段二次
加工提取虚拟属性。
2. 创建虚拟属性时 SQL 表达式最长不能超过 1024 个字符。
应用场景 1：属性抽取
创建虚拟属性需要用到 sa_view_tools 这个工具。例如我们现在有一个事件属性是 $url，希望从 $url 中抽取出 q= 的属性，作为 search_keyword 来进行分
析，那么我们可以这么做：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n search_keyword \
-c '''' \
-e "parse_url(events.\$url, ''QUERY'', ''q'')" \
-t STRING
其中，-p 是神策系统的项目名称, -n 是外部属性在神策系统中的英文名称，-c 是中文名称，-e 是对应的 SQL 表达式，-t 表示数据类型。
我们在 -e 参数中使用了一个 parse_url 的 SQL 函数来进行参数提取，这样在分析的时候使用 search_keyword 属性即可实现相关的分析需求。
应用场景 2：属性合并
假设我们在埋点的时候埋了两个属性：item_id 和 item_id_1，但实际上它们是一个含义，希望在使用的时候进行合并，也可以使用虚拟属性功能来定义：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n new_item_id \
-c ''Item Id'' \
-e "coalesce(events.item_id, events.item_id_1)" \
-t STRING
这里的 coalesce 是一个标准 SQL 函数，返回所有参数中第一个非 NULL 的值，这样我们在使用的时候只要使用 new_item_id 来进行分析就可以达到属性
合并的目的。
应用场景 3：高精度小数
默认情况下，神策分析的 NUMBER 类型只支持小数点之后 3 位，如果需要支持高精度类型，可以使用扩展属性的方式来实现。具体做法如下：
将需要支持高精度的内容以字符串的类型来发送给神策分析，以避免精度丢失，以 Java SDK 为例：Map<String, Object> properties = new HashMap<String, Object>();
properties.put("big_number", "123.12312345");
sa.track(distinctId, true, "TestBigNumber", properties);
创建一个高精度类型的虚拟属性
# big_number big_number_decimal
# decimal 38 16
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n big_number_decimal \
-c '''' \
-e ''cast(events.big_number as decimal(38,16))'' \
-t number
使用 big_number_decimal 属性进行相关的分析
应用场景 4：联合去重
在神策分析中，我们支持对某个属性进行去重数的计算，但是不直接支持对两个或者更多的属性进行去重。如果有这类需求，也可以使用虚拟属性的方式来
实现，即定义一个新的属性，它的值是需要去重的多个属性的组合。
例如，我们想计算不同用户浏览不同商品的去重次数（即一个用户浏览同一个商品不重复计数，但是浏览不同的商品需要计数），那么可以定义一个虚拟属
性如下：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n user_and_product \
-c ''ID + ID'' \
-e "concat(cast(events.user_id as string), events.product_id)" \
-t STRING
然后在神策分析中，查看这个属性的去重数即可得到对应的指标。
应用场景 5：时间聚合
默认情况下，神策分析支持天、周、月等时间聚合方式，如果想要其它的时间聚合方式，也可以使用虚拟属性实现。例如，如果想要按照 "周X" 来对数据进
行分析，可以从 time 属性中提取出一个 day_of_week 的属性：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n day_of_week \
-e ''dayofweek(time)'' \
-t NUMBER
dayofweek 函数求得的数值，1 表示星期天，7 表示星期六，2-6 表示星期一至星期五。类似的，也可以用 extract(hour from time) 表达式来提取时间中
的小时部分。
应用场景 6：
神策支持使用 users 表中的用户属性提取虚拟属性，比如根据用户属性 Birthday ，得到用户的年龄属性，可参考如下示例：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n user_age \
-u true \
-c "" \
-e "cast (extract(year FROM now()) -extract(year FROM EPOCH_TO_TIMESTAMP(users.Birthday)) as int)" \
-t NUMBER注意：
-u
user
更多应用
由于 external_property add 命令的 -e 参数支持任意的 Impala SQL 表达式，因此，可以很灵活的根据实际的业务需求来创建虚拟属性。
维度表
除了基于已经埋点的属性来直接创建虚拟属性之外，我们还可以结合第三方维度表来创建更复杂的虚拟属性应用。
假设我们在神策分析中有一个 pay_order 事件，同时该事件有 product_id、product_name 等属性。现在我们希望在分析的时候使用 product 的更多其它维
度来进行分析（例如 product_manufacturer），但是这些维度并没有在埋点的时候打入神策系统中，这个时候就可以引入维度表来满足这个需求。
使用 items 表作为维度表
注意：神策分析 1.14 及之后版本才支持此方式。之前的版本请参考 2.2 的方法。
如果希望启用 items 表，首先需要通过 SDK 提供的 itemSet 接口进行 Item 信息的上报。以 Java SDK 为例：
Map<String, Object> properties = new LinkedHashMap<>();
properties.put("product_name", "iPhone 8");
properties.put("product_manufacturer", "Apple");
properties.put("price", 998.88);
// item_typeitem_id
sensorsAnalytics.itemSet("product", "T12345", properties);
注意：item_type 可以用于区分不同的 item 类型，比如 movie、muisic 等，item_id 区分同一个 item 类型下面的不同的 Item。
然后，我们就可以在自定义查询功能中使用这个表：
SELECT * FROM items LIMIT 10
接下来我们建立 items 和 events 表的关联：
spadmin external_view external_dimension_table add \
-p default \
-t items \
-e "events.product_id = items.item_id AND items.item_type = ''product''"
注意：
1. 这里是使用 product_id 字段进行关联，同时限定了 item_type。如果同时存在多种 item_type，那么需要建立多次不同的关联，具体请
参考 一张维度表使用不同的关联条件。
2. 维度表关联的字段必须为主键，若不是主键且维度表数据有重复的情况下，会导致在神策分析查询的数据增多。
3. items 表关联时，必须同时使用 item_id 和 item_type 进行关联。若只指定 item_id ，没有指定 item_type，item_id 有重复的情况下，
会导致在神策分析查询的数据增多。
最后，使用 items 表中的 product_manufacturer 来创建虚拟属性即可：
spadmin external_view external_property add \
-p default \
-n product_manufacturer \-c '''' \
-e items.product_manufacturer \
-t STRING
至此，我们已经可以在神策系统的所有分析功能中使用 pay_order 进行分析的时候，看到 product_manufacturer 属性，并使用这个属性进行任意的分析工
作。
如果需要对维度表和虚拟属性进行删除、更新等管理操作，可以直接执行不带参数的命令查看相关的帮助：
~/sa/web/bin/sa_view_tools.sh external_property
自定义维度表
除了引用 items 表之外，我们也可以手动创建维度表。在这个例子中，我们使用一张 product_info 的维度表来作为例子。
登录任意的神策服务器
切换至 sa_cluster 账户
su - sa_cluster
输入 impala-shell 命令进入 impala，首先在 impala 中创建这样一张表：
注意：这里的维度表必须使用 Kudu 或者 HDFS 的 Parquet 文件格式来存储，否则无法支持全部特性。
CREATE DATABASE dimensions;
CREATE TABLE dimensions.product_info
( product_id STRING NOT NULL,
product_manufacturer STRING NULL,
PRIMARY KEY (product_id)
)
PARTITION BY HASH (product_id) PARTITIONS 3
STORED AS KUDU TBLPROPERTIES (''kudu.master_addresses''=''${kudu_master_host}:7051'');
可以通过此命令获取 kudu master 的地址。
# master_address value
monitor_tools get_config -t client -m kudu
然后，我们需要准备好这张维度表的数据，通常应该是从其它业务数据库或者数据仓库中导入进来。具体可以使用 impala-shell 导入 SQL 文件，或者
JDBC 等多种方式来进行，例如我们可以直接插入几条数据：
INSERT INTO dimensions.product_info VALUES (''124'', ''Xiaomi''), (''123'', ''Apple'');
如果需要插入的数据量比较大，建议使用批量文件导入的方式。首先需要创建一个文本格式的表，并指定分隔符:
CREATE TABLE dimensions.raw_csv_product_info
( product_id STRING,
product_manufacturer STRING
) ROW FORMAT DELIMITED FIELDS TERMINATED by '','' LOCATION ''/tmp/raw_csv_product_info/'';
然后上传已经准备好的逗号分隔的文本数据文件：
hdfs dfs -put data.csv /tmp/raw_csv_product_info/
刷新 CSV 表，并执行 INSERT 把数据导入 Kudu 即可。REFRESH dimensions.raw_csv_product_info;
INSERT INTO dimensions.product_info SELECT * FROM dimensions.raw_csv_product_info;
在准备好维度表数据之后，我们用 sa_view_tools 工具来把该维度表加入神策系统中：
~/sa/web/bin/sa_view_tools.sh external_dimension_table add \
-p default \
-t dimensions.product_info \
-e ''events.product_id = dimensions.product_info.product_id''
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称， -e 参数表示该维度表和事件表（events）的关联关系，即 SQL 中进行 JOIN 的条件。
注意：维度表关联的字段必须为主键，若不是主键且维度表数据有重复的情况下，会导致在神策分析查询的数据增多。
在定义了维度表之后，我们就可以把该维度表（即 product_info）中的具体字段作为一个虚拟属性加入神策系统中：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n product_manufacturer \
-c '''' \
-e dimensions.product_info.product_manufacturer \
-t STRING
至此，我们已经可以在神策系统的所有分析功能中使用 pay_order 进行分析的时候，看到 product_manufacturer 属性，并使用这个属性进行任意的分析工
作。
一张维度表使用不同的关联条件
如果同一张维度表需要使用不同的关联条件，那么需要在新增维度表的时候使用别名。具体的方式为在原有的表面后面加上 #1 或者其它标识符。例如：
~/sa/web/bin/sa_view_tools.sh external_dimension_table add \
-p default \
-t dimensions.product_info#1 \
-e ''events.item_id = dimensions.product_info#1.item_id''
添加完成之后，后面在其它命令引用这张表时也需要使用 dimensions.product_info#1。
限制与约束
查询性能
由于关联维度表需要使用 JOIN，虽然神策的查询引擎已经对这个类型的 JOIN 做了一定程度的优化，但是相比直接使用原始的事件属性依然会有比较显著的
性能降低，具体的性能和维度表的大小、JOIN 的条件等都有关系。因此，我们建议在直接使用事件属性可以满足需求的情况下，不要使用维度表；同时，应当
保证维度表的行数在百万以内，以尽量降低 JOIN 带来的额外性能损耗。
缓存一致性
目前为止，神策系统的缓存机制依然是基于事件数据的变更来实现的，这个机制中暂时没有考虑到维度表的数据变化带来的影响。因此，如果维度表的数据
发生了变更（例如进行 Update 或者 Insert），查询结果可能还会使用旧的缓存数据，这个时候需要强制刷新才能得到正确的结果。
常见问题
新增的虚拟属性在页面不可见在添加完虚拟属性之后，可能会发现在某些事件的属性选择界面无法看到对应的虚拟属性，但是在自定义查询里确可以看到。出现这种情况，是因为默认情
况下虚拟属性只会和包含了所有引用属性的事件进行绑定。
例如，在应用场景 2 中，new_item_id 这个虚拟属性引用了 item_id 和 item_id_1，所以也只有同时包含这两个属性的事件才能看到 new_item_id 属性。
在 1.14 版本之后，如果有特殊需求，也可以在添加虚拟属性时单独指定一个关联属性，例如 item_name，这样在任何包含了 item_name 的事件里，都可
以看到新的 new_item_id 属性。例如：
spadmin external_view external_property add \
-p default \
-n new_item_id \
-c ''Item Id'' \
-e "coalesce(events.item_id, events.item_id_1)" \
-r "item_name" \
-t STRING
其中，-r不填写是默认情况（这样虚拟属性只会和包含了所有引用属性的事件进行绑定），-r具体属性值的时候（设置关联属性-r就是包含该属性的事件会
添加虚拟属性），-r为空("")的时候（这种情况下所有事件里都可以看到这个虚拟属性）
新增虚拟属性之后隐藏原属性
例如在属性合并的场景中，我们把 item_id 和 item_id_1 合并成了 new_item_id，这个时候可能希望隐藏旧的 item_id、item_id_1。那么只需要直接在元数
据管理中隐藏即可，引用的属性隐藏之后并不会影响虚拟属性的正常工作。
如何创建日期(DATETIME)类型虚拟属性
创建虚拟属性是时间类型的字段，要求创建虚拟属性的表达式（-e）得到的结果是一个 bigint 类型的时间戳，再设置虚拟属性类型 (-t) 为 DATETIME 类型。
例如，原本记录了一个 oldtimestamp 是数值类型，存储的是时间戳，为了便于分析，可以使用虚拟属性来新建一个 datetime 类型的属性方便进行日期比较的
分析。如果是上传维度表再设置虚拟属性，那么要求上传的维度表里存储的就是时间戳。
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n newdate \
-c ''newdate'' \
-e "cast(events.oldtimestamp as bigint)" \
-t DATETIME
如何创建布尔(BOOL)类型虚拟属性
创建虚拟属性是布尔类型的字段，要求创建虚拟属性的表达式（-e）得到的结果是一个 bigint 类型且值为 0、1 ,再设置虚拟属性类型 (-t) 为 BOOL 类型。
例如，针对所有的支付记录直接区分是否是“有效支付”和“无效支付” ,“无效支付”指得是支付金额值为 0 或者 null 的订单，其他归为“有效支付”。
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n is_valueable_paid \
-c '''' \
-e "cast((case when (events.ActualPaidAmount is not null or events.ActualPaidAmount=0) then ''1'' else ''0''
end) as bigint)" \
-t BOOL
如何创建集合(LIST) 类型虚拟属性
维度表中的属性类型对应 STRING 类型，虚拟属性设置为 LIST 类型。LIST 类型虚拟属性创建举例：
创建维度表的时候，设置 list_name 为 STRING 类型：
CREATE DATABASE dimensions;
CREATE TABLE dimensions.listceshi
( list_id STRING NOT NULL,
list_name STRING NULL,
...PRIMARY KEY (list_id)
)
PARTITION BY HASH (product_id) PARTITIONS 3
STORED AS KUDU TBLPROPERTIES (''kudu.master_addresses''=''${kudu_master_host}:7051'');
传值时如果 LIST 的值有多个值，需要用换行符号\n 分割：
INSERT INTO dimensions.listceshi VALUES (''124'', ''apple\nbanana\npeer''), (''123'', ''apple\nbanana\nbeer'')
退出 impala，用工具建立好维度表和 events 表的关联关系后，再创建 LIST 类型虚拟属性：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n list_name \
-c '''' \
-e dimensions.listceshi.list_name \
-t LIST
测试维度表的关联条件
注意：1.14 版本之后可用
对于比较复杂的关联条件，建议先使用 impala-shell 执行 SQL 来进行测试，以保证结果的正确性。可以直接使用 JOIN 语法进行，例如：
/*sa(test_project)*/
SELECT dimensions.product_info.product_manufacturer FROM
events
LEFT JOIN dimensions.product_info
ON events.product_id = dimensions.product_info.product_id
WHERE date = CURRENT_DATE()
LIMIT 100
如何更新虚拟属性/维度表
更新虚拟属性
~/sa/web/bin/sa_view_tools.sh external_property update\
-p default \
-n new_item_id \
-c ''Item Id'' \
-e "coalesce(events.item_id, events.item_id_1)" \
-r "item_name" \
-t STRING
其中，-p 是神策系统的项目名称, -n 是外部属性在神策系统中的英文名称，-c 是中文名称，-e 是对应的 SQL 表达式，-t 表示数据类型。更
新维度表
~/sa/web/bin/sa_view_tools.sh external_dimension_table update\
-p default \
-t dimensions.product_info \
-e ''events.product_id = dimensions.product_info.product_id''
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称， -e 参数表示该维度表和事件表（events）的关联关系，即 SQL 中进行 JOIN 的条件。如何删除虚拟属性/维度表
删除虚拟属性
~/sa/web/bin/sa_view_tools.sh external_property remove\
-p default \
-n new_item_id
其中，-p 是神策系统的项目名称, -n 是外部属性在神策系统中的英文名称。
删除维度表
~/sa/web/bin/sa_view_tools.sh external_dimension_table remove\
-p default \
-t dimensions.product_info
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称。.虚拟属性和维度表 v1.17
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
自 1.11 版本开始，神策分析已经支持虚拟属性功能，同时还支持使用第三方的维度表来对已接入的事件和属性进行进一步的扩展，该功能可以大大的增强神
策分析对于复杂业务需求的处理能力。
1.17 版本以前，创建虚拟属性和维度表均需要在部署神策系统的服务器上操作，1.17 及之后版本，支持在元数据管理内创建虚拟属性。
请先 ssh 到部署了神策服务的任意一台机器，在 sa_cluster 账户下执行创建虚拟属性或者维度表的命令。
虚拟属性
所谓虚拟属性，是指在数据入库之后通过 SQL 表达式对已有的事件属性和用户属性进行二次加工，产生一个新的属性值。
注意：
1. events 表中的 time 和 event 属于特殊字段，目前支持对 time 字段二次加工，具体可参考应用场景 5 举例。不支持对 event 字段二次
加工提取虚拟属性。
2. 创建虚拟属性时 SQL 表达式最长不能超过 1024 个字符。
应用场景 1：属性抽取
创建虚拟属性需要用到 sa_view_tools 这个工具。例如我们现在有一个事件属性是 $url，希望从 $url 中抽取出 q= 的属性，作为 search_keyword 来进行分
析，那么我们可以这么做：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n search_keyword \
-c '''' \
-e "parse_url(events.\$url, ''QUERY'', ''q'')" \
-t STRING
其中，-p 是神策系统的项目名称, -n 是外部属性在神策系统中的英文名称，-c 是中文名称，-e 是对应的 SQL 表达式，-t 表示数据类型。
我们在 -e 参数中使用了一个 parse_url 的 SQL 函数来进行参数提取，这样在分析的时候使用 search_keyword 属性即可实现相关的分析需求。
应用场景 2：属性合并
假设我们在埋点的时候埋了两个属性：item_id 和 item_id_1，但实际上它们是一个含义，希望在使用的时候进行合并，也可以使用虚拟属性功能来定义：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n new_item_id \
-c ''Item Id'' \
-e "coalesce(events.item_id, events.item_id_1)" \
-t STRING
这里的 coalesce 是一个标准 SQL 函数，返回所有参数中第一个非 NULL 的值，这样我们在使用的时候只要使用 new_item_id 来进行分析就可以达到属性
合并的目的。
应用场景 3：高精度小数
默认情况下，神策分析的 NUMBER 类型只支持小数点之后 3 位，如果需要支持高精度类型，可以使用扩展属性的方式来实现。具体做法如下：
将需要支持高精度的内容以字符串的类型来发送给神策分析，以避免精度丢失，以 Java SDK 为例：Map<String, Object> properties = new HashMap<String, Object>();
properties.put("big_number", "123.12312345");
sa.track(distinctId, true, "TestBigNumber", properties);
创建一个高精度类型的虚拟属性
# big_number big_number_decimal
# decimal 38 16
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n big_number_decimal \
-c '''' \
-e ''cast(events.big_number as decimal(38,16))'' \
-t number
使用 big_number_decimal 属性进行相关的分析
应用场景 4：联合去重
在神策分析中，我们支持对某个属性进行去重数的计算，但是不直接支持对两个或者更多的属性进行去重。如果有这类需求，也可以使用虚拟属性的方式来
实现，即定义一个新的属性，它的值是需要去重的多个属性的组合。
例如，我们想计算不同用户浏览不同商品的去重次数（即一个用户浏览同一个商品不重复计数，但是浏览不同的商品需要计数），那么可以定义一个虚拟属
性如下：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n user_and_product \
-c ''ID + ID'' \
-e "concat(cast(events.user_id as string), events.product_id)" \
-t STRING
然后在神策分析中，查看这个属性的去重数即可得到对应的指标。
应用场景 5：时间聚合
默认情况下，神策分析支持天、周、月等时间聚合方式，如果想要其它的时间聚合方式，也可以使用虚拟属性实现。例如，如果想要按照 "周X" 来对数据进
行分析，可以从 time 属性中提取出一个 day_of_week 的属性：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n day_of_week \
-e ''dayofweek(time)'' \
-t NUMBER
dayofweek 函数求得的数值，1 表示星期天，7 表示星期六，2-6 表示星期一至星期五。类似的，也可以用 extract(hour from time) 表达式来提取时间中
的小时部分。
应用场景 6：
神策支持使用 users 表中的用户属性提取虚拟属性，比如根据用户属性 Birthday ，得到用户的年龄属性，可参考如下示例：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n user_age \
-u true \
-c "" \
-e "cast (extract(year FROM now()) -extract(year FROM EPOCH_TO_TIMESTAMP(users.Birthday)) as int)" \
-t NUMBER注意：
-u
user
更多应用
由于 external_property add 命令的 -e 参数支持任意的 Impala SQL 表达式，因此，可以很灵活的根据实际的业务需求来创建虚拟属性。
维度表
除了基于已经埋点的属性来直接创建虚拟属性之外，我们还可以结合第三方维度表来创建更复杂的虚拟属性应用。
假设我们在神策分析中有一个 pay_order 事件，同时该事件有 product_id、product_name 等属性。现在我们希望在分析的时候使用 product 的更多其它维
度来进行分析（例如 product_manufacturer），但是这些维度并没有在埋点的时候打入神策系统中，这个时候就可以引入维度表来满足这个需求。
使用 items 表作为维度表
注意：神策分析 1.14 及之后版本才支持此方式。之前的版本请参考 2.2 的方法。
如果希望启用 items 表，首先需要通过 SDK 提供的 itemSet 接口进行 Item 信息的上报。以 Java SDK 为例：
Map<String, Object> properties = new LinkedHashMap<>();
properties.put("product_name", "iPhone 8");
properties.put("product_manufacturer", "Apple");
properties.put("price", 998.88);
// item_typeitem_id
sensorsAnalytics.itemSet("product", "T12345", properties);
注意：item_type 可以用于区分不同的 item 类型，比如 movie、muisic 等，item_id 区分同一个 item 类型下面的不同的 Item。
然后，我们就可以在自定义查询功能中使用这个表：
SELECT * FROM items LIMIT 10
接下来我们建立 items 和 events 表的关联：
spadmin external_view external_dimension_table add \
-p default \
-t items \
-e "events.product_id = items.item_id AND items.item_type = ''product''"
注意：
1. 这里是使用 product_id 字段进行关联，同时限定了 item_type。如果同时存在多种 item_type，那么需要建立多次不同的关联，具体请
参考 一张维度表使用不同的关联条件。
2. 维度表关联的字段必须为主键，若不是主键且维度表数据有重复的情况下，会导致在神策分析查询的数据增多。
3. items 表关联时，必须同时使用 item_id 和 item_type 进行关联。若只指定 item_id ，没有指定 item_type，item_id 有重复的情况下，
会导致在神策分析查询的数据增多。
最后，使用 items 表中的 product_manufacturer 来创建虚拟属性即可：
spadmin external_view external_property add \
-p default \
-n product_manufacturer \-c '''' \
-e items.product_manufacturer \
-t STRING
至此，我们已经可以在神策系统的所有分析功能中使用 pay_order 进行分析的时候，看到 product_manufacturer 属性，并使用这个属性进行任意的分析工
作。
如果需要对维度表和虚拟属性进行删除、更新等管理操作，可以直接执行不带参数的命令查看相关的帮助：
~/sa/web/bin/sa_view_tools.sh external_property
自定义维度表
除了引用 items 表之外，我们也可以手动创建维度表。在这个例子中，我们使用一张 product_info 的维度表来作为例子。首先我们需要在 impala 中创建这样
一张表：
注意：这里的维度表必须使用 Kudu 或者 HDFS 的 Parquet 文件格式来存储，否则无法支持全部特性。
CREATE DATABASE dimensions;
CREATE TABLE dimensions.product_info
( product_id STRING NOT NULL,
product_manufacturer STRING NULL,
PRIMARY KEY (product_id)
)
PARTITION BY HASH (product_id) PARTITIONS 3
STORED AS KUDU TBLPROPERTIES (''kudu.master_addresses''=''${kudu_master_host}:7051'');
可以通过此命令获取 kudu master 的地址。
# master_address value
monitor_tools get_config -t client -m kudu
然后，我们需要准备好这张维度表的数据，通常应该是从其它业务数据库或者数据仓库中导入进来。具体可以使用 impala-shell 导入 SQL 文件，或者
JDBC 等多种方式来进行，例如我们可以直接插入几条数据：
INSERT INTO dimensions.product_info VALUES (''124'', ''Xiaomi''), (''123'', ''Apple'');
如果需要插入的数据量比较大，建议使用批量文件导入的方式。首先需要创建一个文本格式的表，并指定分隔符:
CREATE TABLE dimensions.raw_csv_product_info
( product_id STRING,
product_manufacturer STRING
) ROW FORMAT DELIMITED FIELDS TERMINATED by '','' LOCATION ''/tmp/raw_csv_product_info/'';
然后上传已经准备好的逗号分隔的文本数据文件：
hdfs dfs -put data.csv /tmp/raw_csv_product_info/
刷新 CSV 表，并执行 INSERT 把数据导入 Kudu 即可。
REFRESH dimensions.raw_csv_product_info;
INSERT INTO dimensions.product_info SELECT * FROM dimensions.raw_csv_product_info;
在准备好维度表数据之后，我们用 sa_view_tools 工具来把该维度表加入神策系统中：~/sa/web/bin/sa_view_tools.sh external_dimension_table add \
-p default \
-t dimensions.product_info \
-e ''events.product_id = dimensions.product_info.product_id''
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称， -e 参数表示该维度表和事件表（events）的关联关系，即 SQL 中进行 JOIN 的条件。
注意：维度表关联的字段必须为主键，若不是主键且维度表数据有重复的情况下，会导致在神策分析查询的数据增多。
在定义了维度表之后，我们就可以把该维度表（即 product_info）中的具体字段作为一个虚拟属性加入神策系统中：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n product_manufacturer \
-c '''' \
-e dimensions.product_info.product_manufacturer \
-t STRING
至此，我们已经可以在神策系统的所有分析功能中使用 pay_order 进行分析的时候，看到 product_manufacturer 属性，并使用这个属性进行任意的分析工
作。
一张维度表使用不同的关联条件
如果同一张维度表需要使用不同的关联条件，那么需要在新增维度表的时候使用别名。具体的方式为在原有的表面后面加上 #1 或者其它标识符。例如：
~/sa/web/bin/sa_view_tools.sh external_dimension_table add \
-p default \
-t dimensions.product_info#1 \
-e ''events.item_id = dimensions.product_info#1.item_id''
添加完成之后，后面在其它命令引用这张表时也需要使用 dimensions.product_info#1。
限制与约束
查询性能
由于关联维度表需要使用 JOIN，虽然神策的查询引擎已经对这个类型的 JOIN 做了一定程度的优化，但是相比直接使用原始的事件属性依然会有比较显著的
性能降低，具体的性能和维度表的大小、JOIN 的条件等都有关系。因此，我们建议在直接使用事件属性可以满足需求的情况下，不要使用维度表；同时，应当
保证维度表的行数在百万以内，以尽量降低 JOIN 带来的额外性能损耗。
缓存一致性
目前为止，神策系统的缓存机制依然是基于事件数据的变更来实现的，这个机制中暂时没有考虑到维度表的数据变化带来的影响。因此，如果维度表的数据
发生了变更（例如进行 Update 或者 Insert），查询结果可能还会使用旧的缓存数据，这个时候需要强制刷新才能得到正确的结果。
常见问题
新增的虚拟属性在页面不可见
在添加完虚拟属性之后，可能会发现在某些事件的属性选择界面无法看到对应的虚拟属性，但是在自定义查询里确可以看到。出现这种情况，是因为默认情
况下虚拟属性只会和包含了所有引用属性的事件进行绑定。
例如，在应用场景 2 中，new_item_id 这个虚拟属性引用了 item_id 和 item_id_1，所以也只有同时包含这两个属性的事件才能看到 new_item_id 属性。
在 1.14 版本之后，如果有特殊需求，也可以在添加虚拟属性时单独指定一个关联属性，例如 item_name，这样在任何包含了 item_name 的事件里，都可
以看到新的 new_item_id 属性。例如：spadmin external_view external_property add \
-p default \
-n new_item_id \
-c ''Item Id'' \
-e "coalesce(events.item_id, events.item_id_1)" \
-r "item_name" \
-t STRING
其中，-r不填写是默认情况（这样虚拟属性只会和包含了所有引用属性的事件进行绑定），-r具体属性值的时候（设置关联属性-r就是包含该属性的事件会
添加虚拟属性），-r为空("")的时候（这种情况下所有事件里都可以看到这个虚拟属性）
新增虚拟属性之后隐藏原属性
例如在属性合并的场景中，我们把 item_id 和 item_id_1 合并成了 new_item_id，这个时候可能希望隐藏旧的 item_id、item_id_1。那么只需要直接在元数
据管理中隐藏即可，引用的属性隐藏之后并不会影响虚拟属性的正常工作。
如何创建日期(DATETIME)类型虚拟属性
创建虚拟属性是时间类型的字段，要求创建虚拟属性的表达式（-e）得到的结果是一个 bigint 类型的时间戳，再设置虚拟属性类型 (-t) 为 DATETIME 类型。
例如，原本记录了一个 oldtimestamp 是数值类型，存储的是时间戳，为了便于分析，可以使用虚拟属性来新建一个 datetime 类型的属性方便进行日期比较的
分析。如果是上传维度表再设置虚拟属性，那么要求上传的维度表里存储的就是时间戳。
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n newdate \
-c ''newdate'' \
-e "cast(events.oldtimestamp as bigint)" \
-t DATETIME
如何创建布尔(BOOL)类型虚拟属性
创建虚拟属性是布尔类型的字段，要求创建虚拟属性的表达式（-e）得到的结果是一个 bigint 类型且值为 0、1 ,再设置虚拟属性类型 (-t) 为 BOOL 类型。
例如，针对所有的支付记录直接区分是否是“有效支付”和“无效支付” ,“无效支付”指得是支付金额值为 0 或者 null 的订单，其他归为“有效支付”。
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n is_valueable_paid \
-c '''' \
-e "cast((case when (events.ActualPaidAmount is not null or events.ActualPaidAmount=0) then ''1'' else ''0''
end) as bigint)" \
-t BOOL
如何创建集合(LIST) 类型虚拟属性
维度表中的属性类型对应 STRING 类型，虚拟属性设置为 LIST 类型。LIST 类型虚拟属性创建举例：
创建维度表的时候，设置 list_name 为 STRING 类型：
CREATE DATABASE dimensions;
CREATE TABLE dimensions.listceshi
( list_id STRING NOT NULL,
list_name STRING NULL,
...
PRIMARY KEY (list_id)
)
PARTITION BY HASH (product_id) PARTITIONS 3
STORED AS KUDU TBLPROPERTIES (''kudu.master_addresses''=''${kudu_master_host}:7051'');
传值时如果 LIST 的值有多个值，需要用换行符号\n 分割：INSERT INTO dimensions.listceshi VALUES (''124'', ''apple\nbanana\npeer''), (''123'', ''apple\nbanana\nbeer'')
退出 impala，用工具建立好维度表和 events 表的关联关系后，再创建 LIST 类型虚拟属性：
~/sa/web/bin/sa_view_tools.sh external_property add \
-p default \
-n list_name \
-c '''' \
-e dimensions.listceshi.list_name \
-t LIST
测试维度表的关联条件
注意：1.14 版本之后可用
对于比较复杂的关联条件，建议先使用 impala-shell 执行 SQL 来进行测试，以保证结果的正确性。可以直接使用 JOIN 语法进行，例如：
/*sa(test_project)*/
SELECT dimensions.product_info.product_manufacturer FROM
events
LEFT JOIN dimensions.product_info
ON events.product_id = dimensions.product_info.product_id
WHERE date = CURRENT_DATE()
LIMIT 100
如何更新虚拟属性/维度表
更新虚拟属性
~/sa/web/bin/sa_view_tools.sh external_property update\
-p default \
-n new_item_id \
-c ''Item Id'' \
-e "coalesce(events.item_id, events.item_id_1)" \
-r "item_name" \
-t STRING
其中，-p 是神策系统的项目名称, -n 是外部属性在神策系统中的英文名称，-c 是中文名称，-e 是对应的 SQL 表达式，-t 表示数据类型。更
新维度表
~/sa/web/bin/sa_view_tools.sh external_dimension_table update\
-p default \
-t dimensions.product_info \
-e ''events.product_id = dimensions.product_info.product_id''
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称， -e 参数表示该维度表和事件表（events）的关联关系，即 SQL 中进行 JOIN 的条件。
如何删除虚拟属性/维度表
删除虚拟属性
~/sa/web/bin/sa_view_tools.sh external_property remove\
-p default \
-n new_item_id其中，-p 是神策系统的项目名称, -n 是外部属性在神策系统中的英文名称。
删除维度表
~/sa/web/bin/sa_view_tools.sh external_dimension_table remove\
-p default \
-t dimensions.product_info
其中，-p 是神策系统的项目名称，-t 参数是维度表的完整名称。数据预处理模块.数据预处理模块 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 概述
神策分析从 1.6 开始为用户开放自定义“数据预处理模块”，即为 SDK 等方式接入的数据（不包括批量导入工具方式）提供一个简单的 ETL 流程，使数据接
入更加灵活。该功能仅支持私有部署版。
可以使用“数据预处理模块”处理的数据来源包括：
SDK（各语言 SDK 直接发送的数据，包括可视化埋点的数据。使用 LoggingConsumer 将数据写到文件再使用批量导入工具除外）;
LogAgent;
Logstash;
FormatImporter;
数据预处理模块的工作流程如下：
SDK------------------------------------- >
数据预处理模块可以：
修改数据内容: 添加、删除、修改字段值，修改事件名等;
抛弃数据: 处理结果可直接返回 null 将一条数据抛弃;
添加数据: 由一条数据衍生出多条数据;
由于数据预处理模块可以对数据进行较大改变，请谨慎使用！
处理函数抛异常将导致整条数据被抛弃，请谨慎处理，例如空指针异常。
关于实现“数据预处理模块”，1.13 或 1.13 之前的版本可参考 sensorsdata/ext-processor-sample。
1.14 之后的版本可参考 sensorsdata/preprocessor-sample。
新嵌入神策 App 端 SDK 后，将老用户的设备激活过滤 的例子可参考 sensorsdata/ext-processor-identify-old-users;
在服务端记录激活设备，解决重装后激活数重复计算 的例子可参考 sensorsdata/ext-processor-find-new-user;
以上两个示例的功能已经集成到神策分析，示例的代码仅供参考。
本文当将提供一些场景举例。
2. 修改数据内容
2.1. 解析 URL 参数
当一些字段不方便在客户端解析，可通过“数据预处理模块”在服务端解析。例
如 SDK 发来一条数据，传入“数据预处理模块”时格式如下：
{
"distinct_id": "2b0a6f51a3cd6775",
"time": 1434556935000,
"type": "track",
"event": "ViewProduct",
"project": "sample_project",
"ip": "123.123.123.123",
"properties": {
...
"$referrer":"http://www.kbyte.cn/view?title=abc&act=click",
...
}
}现在需将 $referrer 中的 title，act 等字段解析出来并设置为单独字段。
这个需求可通过实现一个“数据预处理模块”来实现，将数据处理成如下结果并返回：
{
"distinct_id": "2b0a6f51a3cd6775",
"time": 1434556935000,
"type": "track",
"event": "ViewProduct",
"project": "sample_project",
"properties": {
...
"$referrer":"http://www.kbyte.cn/view?title=abc&act=click",
"source_title":"abc",
"source_act":"click",
...
}
}
2.2. JOIN 外部字段
当期望的数据中有一部分需要在后端才能获取到时，可通过“数据预处理模块” JOIN 补全数据。例
如 SDK 发来一条浏览商品数据，其中包含字段 product_id (商品 ID)，传入数据如下：
{
"distinct_id": "2b0a6f51a3cd6775",
"time": 1434556935000,
"type": "track",
"event": "ViewProduct",
"project": "sample_project",
"ip": "123.123.123.123",
"properties": {
...
"product_id":"ABCDE-12345",
...
}
}
现在需要根据 product_id (商品 ID) 在服务端查询到商品的中文名，且中文名英文名映射关系存储在 redis 中。
这时可以实现“数据预处理模块”，在处理过程中查询 redis，将查询结果填入数据：
{
"distinct_id": "2b0a6f51a3cd6775",
"time": 1434556935000,
"type": "track",
"event": "ViewProduct",
"project": "sample_project",
"properties": {
...
"product_id":"ABCDE-12345",
"product_name":"",
...
}
}
3. 抛弃数据
当一些数据符合期望抛弃的条件，可以直接返回 null 将其抛弃。
例如抛弃指定 ip 发来的数据。
对于1.14 之后的版本，可以选择不执行发送数据的命令来抛弃数据。4. 添加数据
“数据处理模块”输入为一条数据，输出可以是多条数据。
返回多条数据时，返回值需要是一个 JSON 数组，数组中每一个元素都为一条符合 **神策分析** 数据格式的数据。
例如，当用户触发了 ViewProduct 事件后，我们标记其为 VIP 用户，输入数据为：
{
"distinct_id": "2b0a6f51a3cd6775",
"time": 1434556935000,
"type": "track",
"event": "ViewProduct",
"project": "sample_project",
"ip": "123.123.123.123",
"properties": {
...
}
}
可以返回多条数据：
[
{
"distinct_id":"2b0a6f51a3cd6775",
"time":1434556935000,
"type":"track",
"event":"ViewProduct",
"project": "sample_project",
"properties":{
...
}
},
{
"distinct_id":"2b0a6f51a3cd6775",
"type":"profile_set",
"time":1434556935000,
"project": "sample_project",
"properties":{
"is_vip":true
}
}
]
对于1.14 之后的版本，可以通过如上的办法返回多条数据。也可以通过多次调用发送的函数来返回多条数据。服务转发配置.服务转发配置 v1.13
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 快速指引
当神策分析处于私有部署的模式时，用户出于安全、负载均衡、高可用等方面的考虑，通常会需要把神策分析对外的端口进行二次转发，再使
用自定义的域名和端口来访问神策服务，以符合各方面的需求。
在转发配置的同时一般也需要配置 HTTPS，神策建议需要通过公网的情况下都使用 HTTPS 协议，可以参考 HTTPS 接入文档。
神策支持多种转发配置方式：.服务转发配置 v1.13#使用云厂商的负载均衡或者硬件负载设备进行服务转发、.服务转发配置 v1.13#使用神策服
务的 Nginx 进行服务转发 (仅推荐单机版使用)，也可以选择.服务转发配置 v1.13#独立部署其它开源应用进行服务转发。以上几种方式 任选一
种 即可。
完成上述操作后请 务必 进行 .服务转发配置 v1.13#更新神策后台配置 操作，并 验证转发正确性。
转发流程图解：
2. 什么时候需要进行转发配置
当部署神策分析集群版时，必须进行转发配置，以保证数据接入服务的高可用和负载均衡。
当部署神策分析单机版时，如果希望修改接入数据的端口，或者开启 HTTPS，那么也可以通过转发配置来实现。
3. 如何进行转发配置
下面小节将介绍各种转发的参考配置，请根据实际情况 选择其中一种配置方式 即可。推荐使用云厂商的负载均衡 或者 硬件负载设备，如有其它特殊情
况请联系神策技术支持。
1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
2. 使用神策服务的 Nginx 进行服务转发
3. 独立部署其它开源应用进行服务转发
神策分析对外提供服务端口列表如下：
协议 端口 作用 注意
默认 HTTP 8106 数据接入服务 通常情况下都需要允许公网访问（如果不使用任何客户端的 SDK 也可以禁止公网访问），且需要考虑带宽和并发连接数
的影响
默认 HTTP 8107 后台分析服务 通常情况下可以只允许办公网访问，以便最大限度的保证系统的安全性
3.1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
下文将给出使用负载设备的通用配置，可根据通用配置来配置不同厂商的 LB 或硬件负载设备。
如果是第一次使用云商的负载均衡，建议查看 各厂商的官方文档参考，必要时可以给相应厂商提工单询问。
如果依然无法完成转发配置请联系神策技术支持。
3.1.1. 数据接入服务
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。2. 前端监听端口建议选择 80(HTTP) 或者 443(HTTPS)，有特殊需求也可选择其它自定义的端口。
3. 调度算法选择轮询或者加权轮询。
4. 开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为粘性会话 “Sticky Sessions”），
建议会话保持超时时间设置 3600 秒。
5. 选择通过 X-Forwarded-For 头字段获取客户端真实 IP（各厂商一般默认为启用）。
6. 后端服务器选择单机或集群版的所有机器 8106 端口。
7. 健康检查一般使用默认配置即可。
使用 Logagent 导入工具需要了解
若 Logagent 数据接收地址使用负载均衡地址，例如：公网接入的 Logagent 则负载均衡算法需要选择 ip_hash（各云厂商算法命名方式
可能存在差异，以云厂商实际情况为准。例如： UCLoud 的 ULB 对应的 ip_hash 算法名称为“源地址”）。
在某些情况下，开启 ip_hash 会导致转发后接收的数据不均衡，所以 Logagent 尽量不通过负载均衡地址，同一个内网下可以配置所有接
收机器的内网 IP
3.1.2. 后台分析服务
由于一个域名的同一个端口无法重复监听，所以如果数据接入和后台分析服务都想使用相同默认端口(例如：HTTPS 的 443)情况下，只能配置两个
域名都指向负载均衡，并在负载均衡处通过 HOST 来区分转发。
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。
2. 前端监听端口按实际需求选择。
3. 调度算法选择轮询或者加权轮询。
4. 需要开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为“粘性会话 Sticky
Sessions”）。
5. 由于存在部分长耗时请求，建议会话保持超时时间设置 1800 秒。
6. 后端服务器选择单机或集群版的所有机器 8107 端口。
7. 健康检查一般使用默认配置即可。
3.1.3. 云厂商负载均衡配置官方文档参考
阿 里 云 ：SLB
腾 讯 云 ：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
3.1.4. 参考本章第四节：更新神策后台配置。
3.1.5. 校验配置是否正确
3.2. 使用神策服务的 Nginx 进行服务转发
若为 单机版 部署，可直接在神策分析的 Nginx 上配置服务转发。
此方案可能会对机器造成性能压力，注意评估服务器负载情况。建议优先选用云厂商的负载均衡或者硬件负载设备进行服务转发。
3.2.1. QuickStart
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster
2. 切换到部署 Nginx 的配置目录：
cd $SENSORS_ANALYTICS_HOME/nginx/conf.d
3. cp -a ${根据下表选择相应的配置文件}.conf.default ${根据下表选择相应的配置文件}.conf
模版文件名 描述sensors_api_http.conf.default http 协议的数据接入服务转发配置参考模版
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
sensors_web_http.conf.default http 协议的后台分析服务转发配置参考模版
sensors_web_https.conf.default https 协议的后台分析服务转发配置参考模版
4. vim 按照配置文件中的注释修改即可，注意数据接入和后台分析都需要配置。
使用神策 Nginx 进行转发时，端口选择的注意事项
建议数据接入服务、后台分析服务分别对应两个域名；
为避免与已有的神策服务端口冲突，数据接入服务、后台分析服务域名不同的情况下，访问端口建议选择默认端口：http
协议默认端口为 80，https 协议默认端口为 443；
数据接入服务、后台分析服务域名相同的情况下，不同服务需要对应不同端口。选定端口前，请先检查端口是否已被神策服
务占用。检查方法：netstat -na |grep 端口号 ，若无结果输出则端口未被占用。
5. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
6. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -s reload
3.2.2. 参考本章第四节：更新神策后台配置。
3.2.3. 校验配置是否正确
3.3. 独立部署其它开源应用进行服务转发
使用前需注意
从机器成本和人力成本考虑，如非必要神策不建议采用此方案。
需要额外一台或多台（确保高可用）机器来部署开源负载均衡应用，不能部署在神策的机器上。
请自行规划负载均衡应用所在机器的配置、高可用和监控方案。
下面两小节将提供基于 Nginx 做负载均衡的 server 段配置，其它配置段请按实际情况自行配置。若使用其他开源应用可以此作为参考配置。
3.3.1. 数据接入服务
Nginx server 段参考配置如下：
# server
# 8106
upstream sensors_data_api
{ # server ip
server 10.0.0.1:8106; # : 10.0.0.1 ip
server 10.0.0.2:8106; # : 10.0.0.2 ip
server 10.0.0.3:8106; # : 10.0.0.3 ip
# ip_hash
ip_hash;
keepalive 100;
}#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-
SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-
SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-
RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-
ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:
AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://sensors_data_api;
proxy_ignore_client_abort on;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
3.3.2. 后台分析服务
Nginx server段参考配置如下：
# server
# 8107
upstream sensors_data_web
{ # server , ip
server 10.0.0.1:8107; # : 10.0.0.1 ip
server 10.0.0.2:8107; # : 10.0.0.2 ip
server 10.0.0.3:8107; # : 10.0.0.3 ip
ip_hash;
}
#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-
GCM- SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-
AES128- SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-
SHA:ECDHE- ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-
GCM-SHA384: AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1800s;
proxy_redirect http://sensors_data_web:8107 .;
proxy_pass http://sensors_data_web;
proxy_ignore_client_abort on;
}
}
3.3.3. 参考本章第四节：更新神策后台配置。
3.3.4. 校验配置是否正确
4. 更新神策后台配置
在进行服务转发配置之后，神策后台需要知道转发之后的地址，否则会影响部分功能的使用，包括：
埋点代码生成功能
渠道管理功能
假设进行转发配置之后的地址是（以下地址仅为示例，请以自己环境实际的地址为准）：
数据接入地址：http://datasink.cloud.sensorsdata.cn:8106/ （不含任何二级路径或参数）。
后台分析地址：http://web.cloud.sensorsdata.cn:8107/ （不含任何二级路径或参数）。
配置了 HTTPS 还需要配置相应 HTTPS URL:
数据接入地址：https://datasink.cloud.sensorsdata.cn/
后台分析地址：https://web.cloud.sensorsdata.cn/
那么更新相关配置的操作方式如下：
注意：以下所有地址均为示例地址，需要根据您真实的数据接收地址进行配置
#
su - sa_cluster
# HTTP
monitor_tools set_config -t global -n data_sink_url -v "http://datasink.cloud.sensorsdata.cn:8106/"
# HTTP
monitor_tools set_config -t global -n web_url -v "http://web.cloud.sensorsdata.cn:8107/"
# HTTPS
monitor_tools set_config -t global -n secure_data_sink_url -v "https://datasink.cloud.sensorsdata.cn/"
# HTTPS
monitor_tools set_config -t global -n secure_web_url -v "https://web.cloud.sensorsdata.cn/"
#
sa_admin restart -m web
检查相关配置的操作方式如下，注意 HTTP 和 HTTPS 的区别：
#
su - sa_cluster
# HTTP
monitor_tools get_config -t global -n data_sink_url
# HTTP
monitor_tools get_config -t global -n web_url
# HTTPS
monitor_tools get_config -t global -n secure_data_sink_url
# HTTPS
monitor_tools get_config -t global -n secure_web_url5. 如何验证转发配置是否正确
浏览器直接访问转发到 8107 的 URL，如果能正常返回神策登录的界面，证明 8107 转发配置正确。
获取数据接收地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）在浏览器中直接访问，如返回“Sensors Analytics is
ready to receive your data!” ，证明 8106 转发配置正确。.服务转发配置 v1.14
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 快速指引
当神策分析处于私有部署的模式时，用户出于安全、负载均衡、高可用等方面的考虑，通常会需要把神策分析对外的端口进行二次转发，再使
用自定义的域名和端口来访问神策服务，以符合各方面的需求。
在转发配置的同时一般也需要配置 HTTPS，神策建议需要通过公网的情况下都使用 HTTPS 协议，可以参考 HTTPS 接入文档。
神策支持多种转发配置方式：.服务转发配置 v1.13#使用云厂商的负载均衡或者硬件负载设备进行服务转发、.服务转发配置 v1.13#使用神策服
务的 Nginx 进行服务转发 (仅推荐单机版使用)，也可以选择.服务转发配置 v1.13#独立部署其它开源应用进行服务转发。以上几种方式 任选一
种 即可。
完成上述操作后请 务必 进行 .服务转发配置 v1.13#更新神策后台配置 操作，并 验证转发正确性。
转发流程图解：
2. 什么时候需要进行转发配置
当部署神策分析集群版时，必须进行转发配置，以保证数据接入服务的高可用和负载均衡。
当部署神策分析单机版时，如果希望修改接入数据的端口，或者开启 HTTPS，那么也可以通过转发配置来实现。
3. 如何进行转发配置
下面小节将介绍各种转发的参考配置，请根据实际情况 选择其中一种配置方式 即可。推荐使用云厂商的负载均衡 或者 硬件负载设备，如有其它特殊情
况请联系神策技术支持。
1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
2. 使用神策服务的 Nginx 进行服务转发
3. 独立部署其它开源应用进行服务转发
神策分析对外提供服务端口列表如下：
协议 端口 作用 注意
默认 HTTP 8106 数据接入服务 通常情况下都需要允许公网访问（如果不使用任何客户端的 SDK 也可以禁止公网访问），且需要考虑带宽和并发连接数
的影响
默认 HTTP 8107 后台分析服务 通常情况下可以只允许办公网访问，以便最大限度的保证系统的安全性
3.1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
下文将给出使用负载设备的通用配置，可根据通用配置来配置不同厂商的 LB 或硬件负载设备。
如果是第一次使用云商的负载均衡，建议查看 各厂商的官方文档参考，必要时可以给相应厂商提工单询问。
如果依然无法完成转发配置请联系神策技术支持。
3.1.1. 数据接入服务
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。2. 前端监听端口建议选择 80(HTTP) 或者 443(HTTPS)，有特殊需求也可选择其它自定义的端口。
3. 调度算法选择轮询或者加权轮询。
4. 开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为粘性会话 “Sticky Sessions”），
建议会话保持超时时间设置 3600 秒。
5. 选择通过 X-Forwarded-For 头字段获取客户端真实 IP（各厂商一般默认为启用）。
6. 后端服务器选择单机或集群版的所有机器 8106 端口。
7. 健康检查一般使用默认配置即可。
使用 Logagent 导入工具需要了解
若 Logagent 数据接收地址使用负载均衡地址，例如：公网接入的 Logagent 则负载均衡算法需要选择 ip_hash（各云厂商算法命名方式
可能存在差异，以云厂商实际情况为准。例如： UCLoud 的 ULB 对应的 ip_hash 算法名称为“源地址”）。
在某些情况下，开启 ip_hash 会导致转发后接收的数据不均衡，所以 Logagent 尽量不通过负载均衡地址，同一个内网下可以配置所有接
收机器的内网 IP
3.1.2. 后台分析服务
由于一个域名的同一个端口无法重复监听，所以如果数据接入和后台分析服务都想使用相同默认端口(例如：HTTPS 的 443)情况下，只能配置两个
域名都指向负载均衡，并在负载均衡处通过 HOST 来区分转发。
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。
2. 前端监听端口按实际需求选择。
3. 调度算法选择轮询或者加权轮询。
4. 需要开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为“粘性会话 Sticky
Sessions”）。
5. 由于存在部分长耗时请求，建议会话保持超时时间设置 1800 秒。
6. 后端服务器选择单机或集群版的所有机器 8107 端口。
7. 健康检查一般使用默认配置即可。
3.1.3. 云厂商负载均衡配置官方文档参考
阿 里 云 ：SLB
腾 讯 云 ：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
3.1.4. 参考本章第四节：更新神策后台配置。
3.1.5. 校验配置是否正确
3.2. 使用神策服务的 Nginx 进行服务转发
若为 单机版 部署，可直接在神策分析的 Nginx 上配置服务转发。
此方案可能会对机器造成性能压力，注意评估服务器负载情况。建议优先选用云厂商的负载均衡或者硬件负载设备进行服务转发。
3.2.1. QuickStart
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster
2. 切换到部署 Nginx 的配置目录：
cd $SENSORS_ANALYTICS_HOME/nginx/conf.d
3. cp -a ${根据下表选择相应的配置文件}.conf.default ${根据下表选择相应的配置文件}.conf
模版文件名 描述sensors_api_http.conf.default http 协议的数据接入服务转发配置参考模版
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
sensors_web_http.conf.default http 协议的后台分析服务转发配置参考模版
sensors_web_https.conf.default https 协议的后台分析服务转发配置参考模版
4. vim 按照配置文件中的注释修改即可，注意数据接入和后台分析都需要配置。
使用神策 Nginx 进行转发时，端口选择的注意事项
建议数据接入服务、后台分析服务分别对应两个域名；
为避免与已有的神策服务端口冲突，数据接入服务、后台分析服务域名不同的情况下，访问端口建议选择默认端口：http
协议默认端口为 80，https 协议默认端口为 443；
数据接入服务、后台分析服务域名相同的情况下，不同服务需要对应不同端口。选定端口前，请先检查端口是否已被神策服
务占用。检查方法：netstat -na |grep 端口号 ，若无结果输出则端口未被占用。
5. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
6. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -s reload
3.2.2. 参考本章第四节：更新神策后台配置。
3.2.3. 校验配置是否正确
3.3. 独立部署其它开源应用进行服务转发
使用前需注意
从机器成本和人力成本考虑，如非必要神策不建议采用此方案。
需要额外一台或多台（确保高可用）机器来部署开源负载均衡应用，不能部署在神策的机器上。
请自行规划负载均衡应用所在机器的配置、高可用和监控方案。
下面两小节将提供基于 Nginx 做负载均衡的 server 段配置，其它配置段请按实际情况自行配置。若使用其他开源应用可以此作为参考配置。
3.3.1. 数据接入服务
Nginx server 段参考配置如下：
# server
# 8106
upstream sensors_data_api
{ # server ip
server 10.0.0.1:8106; # : 10.0.0.1 ip
server 10.0.0.2:8106; # : 10.0.0.2 ip
server 10.0.0.3:8106; # : 10.0.0.3 ip
# ip_hash
ip_hash;
keepalive 100;
}#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-
SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-
SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-
RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-
ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:
AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://sensors_data_api;
proxy_ignore_client_abort on;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
3.3.2. 后台分析服务
Nginx server段参考配置如下：
# server
# 8107
upstream sensors_data_web
{ # server , ip
server 10.0.0.1:8107; # : 10.0.0.1 ip
server 10.0.0.2:8107; # : 10.0.0.2 ip
server 10.0.0.3:8107; # : 10.0.0.3 ip
ip_hash;
}
#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-
GCM- SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-
AES128- SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-
SHA:ECDHE- ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-
GCM-SHA384: AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1800s;
proxy_redirect http://sensors_data_web:8107 .;
proxy_pass http://sensors_data_web;
proxy_ignore_client_abort on;
}
}
3.3.3. 参考本章第四节：更新神策后台配置。
3.3.4. 校验配置是否正确
4. 更新神策后台配置
在进行服务转发配置之后，神策后台需要知道转发之后的地址，否则会影响部分功能的使用，包括：
埋点代码生成功能
渠道管理功能
假设进行转发配置之后的地址是（以下地址仅为示例，请以自己环境实际的地址为准）：
数据接入地址：http://datasink.cloud.sensorsdata.cn:8106/ （不含任何二级路径或参数）。
后台分析地址：http://web.cloud.sensorsdata.cn:8107/ （不含任何二级路径或参数）。
配置了 HTTPS 还需要配置相应 HTTPS URL:
数据接入地址：https://datasink.cloud.sensorsdata.cn/
后台分析地址：https://web.cloud.sensorsdata.cn/
那么更新相关配置的操作方式如下：
注意：以下所有地址均为示例地址，需要根据您真实的数据接收地址进行配置
#
su - sa_cluster
# HTTP
spadmin config set global -n data_sink_url -v "http://datasink.cloud.sensorsdata.cn:8106/"
# HTTP
spadmin config set global -n web_url -v "http://web.cloud.sensorsdata.cn:8107/"
# HTTPS
spadmin config set global -n secure_data_sink_url -v "https://datasink.cloud.sensorsdata.cn/"
# HTTPS
spadmin config set global -n secure_web_url -v "https://web.cloud.sensorsdata.cn/"
#
spadmin restart -m web -p sa
检查相关配置的操作方式如下，注意 HTTP 和 HTTPS 的区别：
#
su - sa_cluster
# HTTP
spadmin config get global -n data_sink_url
# HTTP
spadmin config get global -n web_url
# HTTPS
spadmin config get global -n secure_data_sink_url
# HTTPS
spadmin config get global -n secure_web_url5. 如何验证转发配置是否正确
浏览器直接访问转发到 8107 的 URL，如果能正常返回神策登录的界面，证明 8107 转发配置正确。
获取数据接收地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）在浏览器中直接访问，如返回“Sensors Analytics is
ready to receive your data!” ，证明 8106 转发配置正确。.服务转发配置 v1.15
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 快速指引
当神策分析处于私有部署的模式时，用户出于安全、负载均衡、高可用等方面的考虑，通常会需要把神策分析对外的端口进行二次转发，再使
用自定义的域名和端口来访问神策服务，以符合各方面的需求。
在转发配置的同时一般也需要配置 HTTPS，神策建议需要通过公网的情况下都使用 HTTPS 协议，可以参考 HTTPS 接入文档。
神策支持多种转发配置方式：.服务转发配置 v1.13#使用云厂商的负载均衡或者硬件负载设备进行服务转发、.服务转发配置 v1.13#使用神策服
务的 Nginx 进行服务转发 (仅推荐单机版使用)，也可以选择.服务转发配置 v1.13#独立部署其它开源应用进行服务转发。以上几种方式 任选一
种 即可。
完成上述操作后请 务必 进行 .服务转发配置 v1.13#更新神策后台配置 操作，并 验证转发正确性。
转发流程图解：
2. 什么时候需要进行转发配置
当部署神策分析集群版时，必须进行转发配置，以保证数据接入服务的高可用和负载均衡。
当部署神策分析单机版时，如果希望修改接入数据的端口，或者开启 HTTPS，那么也可以通过转发配置来实现。
3. 如何进行转发配置
下面小节将介绍各种转发的参考配置，请根据实际情况 选择其中一种配置方式 即可。推荐使用云厂商的负载均衡 或者 硬件负载设备，如有其它特殊情
况请联系神策技术支持。
1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
2. 使用神策服务的 Nginx 进行服务转发
3. 独立部署其它开源应用进行服务转发
神策分析对外提供服务端口列表如下：
协议 端口 作用 注意
默认 HTTP 8106 数据接入服务 通常情况下都需要允许公网访问（如果不使用任何客户端的 SDK 也可以禁止公网访问），且需要考虑带宽和并发连接数
的影响
默认 HTTP 8107 后台分析服务 通常情况下可以只允许办公网访问，以便最大限度的保证系统的安全性
3.1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
下文将给出使用负载设备的通用配置，可根据通用配置来配置不同厂商的 LB 或硬件负载设备。
如果是第一次使用云商的负载均衡，建议查看 各厂商的官方文档参考，必要时可以给相应厂商提工单询问。
如果依然无法完成转发配置请联系神策技术支持。
3.1.1. 数据接入服务
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。2. 前端监听端口建议选择 80(HTTP) 或者 443(HTTPS)，有特殊需求也可选择其它自定义的端口。
3. 调度算法选择轮询或者加权轮询。
4. 开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为粘性会话 “Sticky Sessions”），
建议会话保持超时时间设置 3600 秒。
5. 选择通过 X-Forwarded-For 头字段获取客户端真实 IP（各厂商一般默认为启用）。
6. 后端服务器选择单机或集群版的所有机器 8106 端口。
7. 健康检查一般使用默认配置即可。
使用 Logagent 导入工具需要了解
若 Logagent 数据接收地址使用负载均衡地址，例如：公网接入的 Logagent 则负载均衡算法需要选择 ip_hash（各云厂商算法命名方式
可能存在差异，以云厂商实际情况为准。例如： UCLoud 的 ULB 对应的 ip_hash 算法名称为“源地址”）。
在某些情况下，开启 ip_hash 会导致转发后接收的数据不均衡，所以 Logagent 尽量不通过负载均衡地址，同一个内网下可以配置所有接
收机器的内网 IP
3.1.2. 后台分析服务
由于一个域名的同一个端口无法重复监听，所以如果数据接入和后台分析服务都想使用相同默认端口(例如：HTTPS 的 443)情况下，只能配置两个
域名都指向负载均衡，并在负载均衡处通过 HOST 来区分转发。
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。
2. 前端监听端口按实际需求选择。
3. 调度算法选择轮询或者加权轮询。
4. 需要开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为“粘性会话 Sticky
Sessions”）。
5. 由于存在部分长耗时请求，建议会话保持超时时间设置 1800 秒。
6. 后端服务器选择单机或集群版的所有机器 8107 端口。
7. 健康检查一般使用默认配置即可。
3.1.3. 云厂商负载均衡配置官方文档参考
阿 里 云 ：SLB
腾 讯 云 ：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
3.1.4. 参考本章第四节：更新神策后台配置。
3.1.5. 校验配置是否正确
3.2. 使用神策服务的 Nginx 进行服务转发
若为 单机版 部署，可直接在神策分析的 Nginx 上配置服务转发。
此方案可能会对机器造成性能压力，注意评估服务器负载情况。建议优先选用云厂商的负载均衡或者硬件负载设备进行服务转发。
3.2.1. QuickStart
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster
2. 切换到部署 Nginx 的配置目录：
cd $SENSORS_ANALYTICS_HOME/nginx/conf.d
3. cp -a ${根据下表选择相应的配置文件}.conf.default ${根据下表选择相应的配置文件}.conf
模版文件名 描述sensors_api_http.conf.default http 协议的数据接入服务转发配置参考模版
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
sensors_web_http.conf.default http 协议的后台分析服务转发配置参考模版
sensors_web_https.conf.default https 协议的后台分析服务转发配置参考模版
4. vim 按照配置文件中的注释修改即可，注意数据接入和后台分析都需要配置。
使用神策 Nginx 进行转发时，端口选择的注意事项
建议数据接入服务、后台分析服务分别对应两个域名；
为避免与已有的神策服务端口冲突，数据接入服务、后台分析服务域名不同的情况下，访问端口建议选择默认端口：http
协议默认端口为 80，https 协议默认端口为 443；
数据接入服务、后台分析服务域名相同的情况下，不同服务需要对应不同端口。选定端口前，请先检查端口是否已被神策服
务占用。检查方法：netstat -na |grep 端口号 ，若无结果输出则端口未被占用。
5. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
6. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -s reload
3.2.2. 参考本章第四节：更新神策后台配置。
3.2.3. 校验配置是否正确
3.3. 独立部署其它开源应用进行服务转发
使用前需注意
从机器成本和人力成本考虑，如非必要神策不建议采用此方案。
需要额外一台或多台（确保高可用）机器来部署开源负载均衡应用，不能部署在神策的机器上。
请自行规划负载均衡应用所在机器的配置、高可用和监控方案。
下面两小节将提供基于 Nginx 做负载均衡的 server 段配置，其它配置段请按实际情况自行配置。若使用其他开源应用可以此作为参考配置。
3.3.1. 数据接入服务
Nginx server 段参考配置如下：
# server
# 8106
upstream sensors_data_api
{ # server ip
server 10.0.0.1:8106; # : 10.0.0.1 ip
server 10.0.0.2:8106; # : 10.0.0.2 ip
server 10.0.0.3:8106; # : 10.0.0.3 ip
# ip_hash
ip_hash;
keepalive 100;
}#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-
SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-
SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-
RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-
ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:
AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://sensors_data_api;
proxy_ignore_client_abort on;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
3.3.2. 后台分析服务
Nginx server段参考配置如下：
# server
# 8107
upstream sensors_data_web
{ # server , ip
server 10.0.0.1:8107; # : 10.0.0.1 ip
server 10.0.0.2:8107; # : 10.0.0.2 ip
server 10.0.0.3:8107; # : 10.0.0.3 ip
ip_hash;
}
#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-
GCM- SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-
AES128- SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-
SHA:ECDHE- ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-
GCM-SHA384: AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1800s;
proxy_redirect http://sensors_data_web:8107 .;
proxy_pass http://sensors_data_web;
proxy_ignore_client_abort on;
}
}
3.3.3. 参考本章第四节：更新神策后台配置。
3.3.4. 校验配置是否正确
4. 更新神策后台配置
在进行服务转发配置之后，神策后台需要知道转发之后的地址，否则会影响部分功能的使用，包括：
埋点代码生成功能
渠道管理功能
假设进行转发配置之后的地址是（以下地址仅为示例，请以自己环境实际的地址为准）：
数据接入地址：http://datasink.cloud.sensorsdata.cn:8106/ （不含任何二级路径或参数）。
后台分析地址：http://web.cloud.sensorsdata.cn:8107/ （不含任何二级路径或参数）。
配置了 HTTPS 还需要配置相应 HTTPS URL:
数据接入地址：https://datasink.cloud.sensorsdata.cn/
后台分析地址：https://web.cloud.sensorsdata.cn/
那么更新相关配置的操作方式如下：
注意：以下所有地址均为示例地址，需要根据您真实的数据接收地址进行配置
#
su - sa_cluster
# HTTP
spadmin config set global -n data_sink_url -v "http://datasink.cloud.sensorsdata.cn:8106/"
# HTTP
spadmin config set global -n web_url -v "http://web.cloud.sensorsdata.cn:8107/"
# HTTPS
spadmin config set global -n secure_data_sink_url -v "https://datasink.cloud.sensorsdata.cn/"
# HTTPS
spadmin config set global -n secure_web_url -v "https://web.cloud.sensorsdata.cn/"
#
spadmin restart -m web -p sa
检查相关配置的操作方式如下，注意 HTTP 和 HTTPS 的区别：
#
su - sa_cluster
# HTTP
spadmin config get global -n data_sink_url
# HTTP
spadmin config get global -n web_url
# HTTPS
spadmin config get global -n secure_data_sink_url
# HTTPS
spadmin config get global -n secure_web_url5. 如何验证转发配置是否正确
浏览器直接访问转发到 8107 的 URL，如果能正常返回神策登录的界面，证明 8107 转发配置正确。
获取数据接收地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）在浏览器中直接访问，如返回“Sensors Analytics is
ready to receive your data!” ，证明 8106 转发配置正确。.服务转发配置 v1.16
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 快速指引
当神策分析处于私有部署的模式时，用户出于安全、负载均衡、高可用等方面的考虑，通常会需要把神策分析对外的端口进行二次转发，再使
用自定义的域名和端口来访问神策服务，以符合各方面的需求。
在转发配置的同时一般也需要配置 HTTPS，神策建议需要通过公网的情况下都使用 HTTPS 协议，可以参考 HTTPS 接入文档。
神策支持多种转发配置方式：.服务转发配置 v1.13#使用云厂商的负载均衡或者硬件负载设备进行服务转发、.服务转发配置 v1.13#使用神策服
务的 Nginx 进行服务转发 (仅推荐单机版使用)，也可以选择.服务转发配置 v1.13#独立部署其它开源应用进行服务转发。以上几种方式 任选一
种 即可。
完成上述操作后请 务必 进行 .服务转发配置 v1.13#更新神策后台配置 操作，并 验证转发正确性。
转发流程图解：
2. 什么时候需要进行转发配置
当部署神策分析集群版时，必须进行转发配置，以保证数据接入服务的高可用和负载均衡。
当部署神策分析单机版时，如果希望修改接入数据的端口，或者开启 HTTPS，那么也可以通过转发配置来实现。
3. 如何进行转发配置
下面小节将介绍各种转发的参考配置，请根据实际情况 选择其中一种配置方式 即可。推荐使用云厂商的负载均衡 或者 硬件负载设备，如有其它特殊情
况请联系神策技术支持。
1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
2. 使用神策服务的 Nginx 进行服务转发
3. 独立部署其它开源应用进行服务转发
神策分析对外提供服务端口列表如下：
协议 端口 作用 注意
默认 HTTP 8106 数据接入服务 通常情况下都需要允许公网访问（如果不使用任何客户端的 SDK 也可以禁止公网访问），且需要考虑带宽和并发连接数
的影响
默认 HTTP 8107 后台分析服务 通常情况下可以只允许办公网访问，以便最大限度的保证系统的安全性
3.1. 使用云厂商的负载均衡或者硬件负载设备进行服务转发
下文将给出使用负载设备的通用配置，可根据通用配置来配置不同厂商的 LB 或硬件负载设备。
如果是第一次使用云商的负载均衡，建议查看 各厂商的官方文档参考，必要时可以给相应厂商提工单询问。
如果依然无法完成转发配置请联系神策技术支持。
3.1.1. 数据接入服务
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。2. 前端监听端口建议选择 80(HTTP) 或者 443(HTTPS)，有特殊需求也可选择其它自定义的端口。
3. 调度算法选择轮询或者加权轮询。
4. 开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为粘性会话 “Sticky Sessions”），
建议会话保持超时时间设置 3600 秒。
5. 选择通过 X-Forwarded-For 头字段获取客户端真实 IP（各厂商一般默认为启用）。
6. 后端服务器选择单机或集群版的所有机器 8106 端口。
7. 健康检查一般使用默认配置即可。
使用 Logagent 导入工具需要了解
若 Logagent 数据接收地址使用负载均衡地址，例如：公网接入的 Logagent 则负载均衡算法需要选择 ip_hash（各云厂商算法命名方式
可能存在差异，以云厂商实际情况为准。例如： UCLoud 的 ULB 对应的 ip_hash 算法名称为“源地址”）。
在某些情况下，开启 ip_hash 会导致转发后接收的数据不均衡，所以 Logagent 尽量不通过负载均衡地址，同一个内网下可以配置所有接
收机器的内网 IP
3.1.2. 后台分析服务
由于一个域名的同一个端口无法重复监听，所以如果数据接入和后台分析服务都想使用相同默认端口(例如：HTTPS 的 443)情况下，只能配置两个
域名都指向负载均衡，并在负载均衡处通过 HOST 来区分转发。
1. 协议默认为 HTTP，如果开启了 HTTPS，选择 HTTPS。
2. 前端监听端口按实际需求选择。
3. 调度算法选择轮询或者加权轮询。
4. 需要开启会话保持（各云厂商功能命名可能存在差异，以云厂商实际情况为准。例如：AWS 的 ELB 该功能名称为“粘性会话 Sticky
Sessions”）。
5. 由于存在部分长耗时请求，建议会话保持超时时间设置 1800 秒。
6. 后端服务器选择单机或集群版的所有机器 8107 端口。
7. 健康检查一般使用默认配置即可。
3.1.3. 云厂商负载均衡配置官方文档参考
阿 里 云 ：SLB
腾 讯 云 ：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
3.1.4. 参考本章第四节：更新神策后台配置。
3.1.5. 校验配置是否正确
3.2. 使用神策服务的 Nginx 进行服务转发
若为 单机版 部署，可直接在神策分析的 Nginx 上配置服务转发。
此方案可能会对机器造成性能压力，注意评估服务器负载情况。建议优先选用云厂商的负载均衡或者硬件负载设备进行服务转发。
3.2.1. QuickStart
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster
2. 切换到部署 Nginx 的配置目录：
cd $SENSORS_PLATFORM_HOME/nginx/conf.d
3. cp -a ${根据下表选择相应的配置文件}.conf.default ${根据下表选择相应的配置文件}.conf
模版文件名 描述sensors_api_http.conf.default http 协议的数据接入服务转发配置参考模版
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
sensors_web_http.conf.default http 协议的后台分析服务转发配置参考模版
sensors_web_https.conf.default https 协议的后台分析服务转发配置参考模版
4. vim 按照配置文件中的注释修改即可，注意数据接入和后台分析都需要配置。
使用神策 Nginx 进行转发时，端口选择的注意事项
建议数据接入服务、后台分析服务分别对应两个域名；
为避免与已有的神策服务端口冲突，数据接入服务、后台分析服务域名不同的情况下，访问端口建议选择默认端口：http
协议默认端口为 80，https 协议默认端口为 443；
数据接入服务、后台分析服务域名相同的情况下，不同服务需要对应不同端口。选定端口前，请先检查端口是否已被神策服
务占用。检查方法：netstat -na |grep 端口号 ，若无结果输出则端口未被占用。
5. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_PLATFORM_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
6. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_PLATFORM_HOME/nginx/
sudo sbin/nginx -s reload
3.2.2. 参考本章第四节：更新神策后台配置。
3.2.3. 校验配置是否正确
3.3. 独立部署其它开源应用进行服务转发
使用前需注意
从机器成本和人力成本考虑，如非必要神策不建议采用此方案。
需要额外一台或多台（确保高可用）机器来部署开源负载均衡应用，不能部署在神策的机器上。
请自行规划负载均衡应用所在机器的配置、高可用和监控方案。
下面两小节将提供基于 Nginx 做负载均衡的 server 段配置，其它配置段请按实际情况自行配置。若使用其他开源应用可以此作为参考配置。
3.3.1. 数据接入服务
Nginx server 段参考配置如下：
# server
# 8106
upstream sensors_data_api
{ # server ip
server 10.0.0.1:8106; # : 10.0.0.1 ip
server 10.0.0.2:8106; # : 10.0.0.2 ip
server 10.0.0.3:8106; # : 10.0.0.3 ip
# ip_hash
ip_hash;
keepalive 100;
}#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-
SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-
SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-
RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-
ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:
AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://sensors_data_api;
proxy_ignore_client_abort on;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
3.3.2. 后台分析服务
Nginx server段参考配置如下：
# server
# 8107
upstream sensors_data_web
{ # server , ip
server 10.0.0.1:8107; # : 10.0.0.1 ip
server 10.0.0.2:8107; # : 10.0.0.2 ip
server 10.0.0.3:8107; # : 10.0.0.3 ip
ip_hash;
}
#
server
{ #
listen 80;
#
server_name xxx.yyy.zzz;
access_log off;
# ssl
# ssl on; # ssl
# ssl_certificate /etc/ssl/server.crt; # ssl
# ssl_certificate_key /etc/ssl/server.key; # ssl
# ssl https://mozilla.github.io/server-side-tls/ssl-config-generator/
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
# ssl_ciphers ''ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-
GCM- SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-
AES128- SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-
SHA:ECDHE- ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-
GCM-SHA384: AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS'';
# ssl_prefer_server_ciphers on;
# ssl_session_timeout 5m;
# ssl_session_cache shared:SSL:50m;
# ssl
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 1800s;
proxy_redirect http://sensors_data_web:8107 .;
proxy_pass http://sensors_data_web;
proxy_ignore_client_abort on;
}
}
3.3.3. 参考本章第四节：更新神策后台配置。
3.3.4. 校验配置是否正确
4. 更新神策后台配置
在进行服务转发配置之后，神策后台需要知道转发之后的地址，否则会影响部分功能的使用，包括：
埋点代码生成功能
渠道管理功能
假设进行转发配置之后的地址是（以下地址仅为示例，请以自己环境实际的地址为准）：
数据接入地址：http://datasink.cloud.sensorsdata.cn:8106/ （不含任何二级路径或参数）。
后台分析地址：http://web.cloud.sensorsdata.cn:8107/ （不含任何二级路径或参数）。
配置了 HTTPS 还需要配置相应 HTTPS URL:
数据接入地址：https://datasink.cloud.sensorsdata.cn/
后台分析地址：https://web.cloud.sensorsdata.cn/
那么更新相关配置的操作方式如下：
注意：以下所有地址均为示例地址，需要根据您真实的数据接收地址进行配置
#
su - sa_cluster
# HTTP
spadmin config set global -n data_sink_url -v "http://datasink.cloud.sensorsdata.cn:8106/"
# HTTP
spadmin config set global -n web_url -v "http://web.cloud.sensorsdata.cn:8107/"
# HTTPS
spadmin config set global -n secure_data_sink_url -v "https://datasink.cloud.sensorsdata.cn/"
# HTTPS
spadmin config set global -n secure_web_url -v "https://web.cloud.sensorsdata.cn/"
#
spadmin restart -m web -p sa
检查相关配置的操作方式如下，注意 HTTP 和 HTTPS 的区别：
#
su - sa_cluster
# HTTP
spadmin config get global -n data_sink_url
# HTTP
spadmin config get global -n web_url
# HTTPS
spadmin config get global -n secure_data_sink_url
# HTTPS
spadmin config get global -n secure_web_url5. 如何验证转发配置是否正确
浏览器直接访问转发到 8107 的 URL，如果能正常返回神策登录的界面，证明 8107 转发配置正确。
获取数据接收地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）在浏览器中直接访问，如返回“Sensors Analytics is
ready to receive your data!” ，证明 8106 转发配置正确。使用 HTTPS 的数据接入.使用 HTTPS 的数据接入 v1.13
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 什么时候需要使用 HTTPS 的数据接入
默认情况下，数据接入 API 使用的是 HTTP 协议
若有以下需求，均可以参考本文档配置 HTTPS 数据接入：
1）希望进一步提高数据传输层的安全性；
2）需要在 HTTPS 站点上部署神策分析 JavaScript SDK 正常发送数据。
神策建议：在需要通过公网的情况下都使用 HTTPS 协议。
2. 如何配置 HTTPS 的数据接入
不同版本的用户可根据实际情况选择对应的配置方式，如有其它特殊情况请联系神策技术支持。
2.1 云版客户使用 HTTPS 的数据接入方案
2.2 私有部署版客户：
1） 在云厂商的负载均衡或者硬件负载设备启用 HTTPS（推荐采用此方式）
2） 单机版可以在神策服务的 Nginx 上配置 HTTPS
2.1. 云版使用 HTTPS 的数据接入方案
神策分析云版默认已经配置了 HTTPS 数据接入，可直接获取对应的 HTTPS 数据接入地址使用。
2.1.1. 获取 HTTPS 数据接入地址
在神策分析页面获取 HTTPS 数据接入地址，需要使用 管理员 账户：
2.1.2. 云版数据接入地址格式
协议 数据接入地址
（域名以实际为准）
HTTP http://域名:8106/sa?token=xxx
HTTPS https://域名:4006/sa?token=xxx（两种类型的地址均可用，选择一种使用即可） https://域名+datasink./sa?token=xxx
示例：
HTTP 数据接入地址为：
http://test.cloud.sensorsdata.cn:8106/sa?token=xxx
它对应的 HTTPS 数据接入地址为，两个地址均可用，选择一种使用即可：
scheme HTTP HTTPS 8106 4006
https://test.cloud.sensorsdata.cn:4006/sa?token=xxx
https://test.datasink.sensorsdata.cn/sa?token=xxx
使用数据接收专用 datasink 域名，可以不显式指定端口号，即 443 为数据接收服务端口。
2.2. 私有部署版使用 HTTPS 的数据接入方案
2.2.1. 在云厂商的负载均衡或者硬件负载设备启用 HTTPS
强烈建议采用此方式。
常见的负载设备均提供 HTTPS 接入功能，可根据实际情况选择不同云厂商的 LB 或硬件负载设备来开启 HTTPS；
使用 HTTPS 加密传输需要提供 SSL 证书，神策不提供任何 SSL 证书。该证书可以通过多种渠道获取，若使用自签证书请确保客户端信任该
证书；
使用 HTTPS 请关注证书的过期时间，若证书过期可能会导致数据无法发送成功；
如果是第一次使用云厂商的负载均衡，建议查看各厂商负载均衡配置官方文档，必要时可以给相应厂商提工单询问；
如果依然无法完成转发配置请联系神策技术支持。
云厂商负载均衡配置官方文档参考 ：
阿里云：SLB
腾讯云：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
2.2.2. 在神策服务的 Nginx 上配置 HTTPS
仅单机版可用，一般不建议采用此方式。
对于 单机版 ，这里也提供直接在神策服务的 Nginx 上配置 HTTPS 的方案；
该方案需要将 SSL 私钥放置于部署神策服务的机器上，且加密算法的选择受限于使用的 Nginx 二进制编译时的 OpenSSL 版本；
使用 HTTPS 加密传输需要提供 SSL 证书，神策不提供任何 SSL 证书。该证书可以通过多种渠道获取，若使用自签证书请确保客户端信任该
证书;
使用 HTTPS 请关注证书的过期时间，若证书过期可能会导致数据无法发送成功;
HTTPS 的 TLS/SSL 层需要消耗额外 CPU、带宽资源。
在神策服务的 Nginx 上配置 HTTPS 可以参考以下步骤:
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster2. 切换到部署 Nginx 的目录：
cd $SENSORS_ANALYTICS_HOME/nginx
3. 创建证书目录：
mkdir -p $SENSORS_ANALYTICS_HOME/nginx/cert
4. 将配置好的 SSL 证书公钥和私钥放置到创建的 cert 目录下;
5. 切换到部署 Nginx 的配置目录：
Nginx 启动时会加载 conf.d 目录下的所有配置文件，这些配置文件内应该只包含 server 代码块;
cd $SENSORS_ANALYTICS_HOME/nginx/conf.d
6. 复制模版文件
cp -a sensors_api_https.conf.default sensors_api_https.conf
模版文件名 描述
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
7. vim 按照配置文件中的注释修改即可
8. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
9. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -s reload
3. 如何验证配置是否正确
获取 HTTPS 数据接入地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）
在浏览器中直接访问，如返回“Sensors Analytics is ready to receive your data!” ，证明配置正确。.使用 HTTPS 的数据接入 v1.14
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 什么时候需要使用 HTTPS 的数据接入
默认情况下，数据接入 API 使用的是 HTTP 协议
若有以下需求，均可以参考本文档配置 HTTPS 数据接入：
1）希望进一步提高数据传输层的安全性；
2）需要在 HTTPS 站点上部署神策分析 JavaScript SDK 正常发送数据。
神策建议：在需要通过公网的情况下都使用 HTTPS 协议。
2. 如何配置 HTTPS 的数据接入
不同版本的用户可根据实际情况选择对应的配置方式，如有其它特殊情况请联系神策技术支持。
2.1 云版客户使用 HTTPS 的数据接入方案
2.2 私有部署版客户：
1） 在云厂商的负载均衡或者硬件负载设备启用 HTTPS（推荐采用此方式）
2） 单机版可以在神策服务的 Nginx 上配置 HTTPS
2.1. 云版使用 HTTPS 的数据接入方案
神策分析云版默认已经配置了 HTTPS 数据接入，可直接获取对应的 HTTPS 数据接入地址使用。
2.1.1. 获取 HTTPS 数据接入地址
在神策分析页面获取 HTTPS 数据接入地址，需要使用 管理员 账户：
2.1.2. 云版数据接入地址格式
协议 数据接入地址
（域名以实际为准）
HTTP http://域名:8106/sa?token=xxx
HTTPS https://域名:4006/sa?token=xxx（两种类型的地址均可用，选择一种使用即可） https://域名+datasink./sa?token=xxx
示例：
HTTP 数据接入地址为：
http://test.cloud.sensorsdata.cn:8106/sa?token=xxx
它对应的 HTTPS 数据接入地址为，两个地址均可用，选择一种使用即可：
scheme HTTP HTTPS 8106 4006
https://test.cloud.sensorsdata.cn:4006/sa?token=xxx
https://test.datasink.sensorsdata.cn/sa?token=xxx
使用数据接收专用 datasink 域名，可以不显式指定端口号，即 443 为数据接收服务端口。
2.2. 私有部署版使用 HTTPS 的数据接入方案
2.2.1. 在云厂商的负载均衡或者硬件负载设备启用 HTTPS
强烈建议采用此方式。
常见的负载设备均提供 HTTPS 接入功能，可根据实际情况选择不同云厂商的 LB 或硬件负载设备来开启 HTTPS；
使用 HTTPS 加密传输需要提供 SSL 证书，神策不提供任何 SSL 证书。该证书可以通过多种渠道获取，若使用自签证书请确保客户端信任该
证书；
使用 HTTPS 请关注证书的过期时间，若证书过期可能会导致数据无法发送成功；
如果是第一次使用云厂商的负载均衡，建议查看各厂商负载均衡配置官方文档，必要时可以给相应厂商提工单询问；
如果依然无法完成转发配置请联系神策技术支持。
云厂商负载均衡配置官方文档参考 ：
阿里云：SLB
腾讯云：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
2.2.2. 在神策服务的 Nginx 上配置 HTTPS
仅单机版可用，一般不建议采用此方式。
对于 单机版 ，这里也提供直接在神策服务的 Nginx 上配置 HTTPS 的方案；
该方案需要将 SSL 私钥放置于部署神策服务的机器上，且加密算法的选择受限于使用的 Nginx 二进制编译时的 OpenSSL 版本；
使用 HTTPS 加密传输需要提供 SSL 证书，神策不提供任何 SSL 证书。该证书可以通过多种渠道获取，若使用自签证书请确保客户端信任该
证书;
使用 HTTPS 请关注证书的过期时间，若证书过期可能会导致数据无法发送成功;
HTTPS 的 TLS/SSL 层需要消耗额外 CPU、带宽资源。
在神策服务的 Nginx 上配置 HTTPS 可以参考以下步骤:
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster2. 切换到部署 Nginx 的目录：
cd $SENSORS_ANALYTICS_HOME/nginx
3. 创建证书目录：
mkdir -p $SENSORS_ANALYTICS_HOME/nginx/cert
4. 将配置好的 SSL 证书公钥和私钥放置到创建的 cert 目录下;
5. 切换到部署 Nginx 的配置目录：
Nginx 启动时会加载 conf.d 目录下的所有配置文件，这些配置文件内应该只包含 server 代码块;
cd $SENSORS_ANALYTICS_HOME/nginx/conf.d
6. 复制模版文件
cp -a sensors_api_https.conf.default sensors_api_https.conf
模版文件名 描述
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
7. vim 按照配置文件中的注释修改即可
8. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
9. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_ANALYTICS_HOME/nginx/
sudo sbin/nginx -s reload
3. 如何验证配置是否正确
获取 HTTPS 数据接入地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）
在浏览器中直接访问，如返回“Sensors Analytics is ready to receive your data!” ，证明配置正确。.使用 HTTPS 的数据接入 v1.16
神策分析致力于帮助客户搭建开放的数据平台，便于客户更深入的利用数据。本节文档涉及较多技术细节，适用于对相关功能有
经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。
1. 什么时候需要使用 HTTPS 的数据接入
默认情况下，数据接入 API 使用的是 HTTP 协议
若有以下需求，均可以参考本文档配置 HTTPS 数据接入：
1）希望进一步提高数据传输层的安全性；
2）需要在 HTTPS 站点上部署神策分析 JavaScript SDK 正常发送数据。
神策建议：在需要通过公网的情况下都使用 HTTPS 协议。
2. 如何配置 HTTPS 的数据接入
不同版本的用户可根据实际情况选择对应的配置方式，如有其它特殊情况请联系神策技术支持。
2.1 云版客户使用 HTTPS 的数据接入方案
2.2 私有部署版客户：
1） 在云厂商的负载均衡或者硬件负载设备启用 HTTPS（推荐采用此方式）
2） 单机版可以在神策服务的 Nginx 上配置 HTTPS
2.1. 云版使用 HTTPS 的数据接入方案
神策分析云版默认已经配置了 HTTPS 数据接入，可直接获取对应的 HTTPS 数据接入地址使用。
2.1.1. 获取 HTTPS 数据接入地址
在神策分析页面获取 HTTPS 数据接入地址，需要使用 管理员 账户：
2.1.2. 云版数据接入地址格式
协议 数据接入地址
（域名以实际为准）
HTTP http://域名:8106/sa?token=xxx
HTTPS https://域名:4006/sa?token=xxx（两种类型的地址均可用，选择一种使用即可） https://域名+datasink./sa?token=xxx
示例：
HTTP 数据接入地址为：
http://test.cloud.sensorsdata.cn:8106/sa?token=xxx
它对应的 HTTPS 数据接入地址为，两个地址均可用，选择一种使用即可：
scheme HTTP HTTPS 8106 4006
https://test.cloud.sensorsdata.cn:4006/sa?token=xxx
https://test.datasink.sensorsdata.cn/sa?token=xxx
使用数据接收专用 datasink 域名，可以不显式指定端口号，即 443 为数据接收服务端口。
2.2. 私有部署版使用 HTTPS 的数据接入方案
2.2.1. 在云厂商的负载均衡或者硬件负载设备启用 HTTPS
强烈建议采用此方式。
常见的负载设备均提供 HTTPS 接入功能，可根据实际情况选择不同云厂商的 LB 或硬件负载设备来开启 HTTPS；
使用 HTTPS 加密传输需要提供 SSL 证书，神策不提供任何 SSL 证书。该证书可以通过多种渠道获取，若使用自签证书请确保客户端信任该
证书；
使用 HTTPS 请关注证书的过期时间，若证书过期可能会导致数据无法发送成功；
如果是第一次使用云厂商的负载均衡，建议查看各厂商负载均衡配置官方文档，必要时可以给相应厂商提工单询问；
如果依然无法完成转发配置请联系神策技术支持。
云厂商负载均衡配置官方文档参考 ：
阿里云：SLB
腾讯云：CLB
亚马逊云：ELB
UCloud：ULB
华为云：ELB
2.2.2. 在神策服务的 Nginx 上配置 HTTPS
仅单机版可用，一般不建议采用此方式。
对于 单机版 ，这里也提供直接在神策服务的 Nginx 上配置 HTTPS 的方案；
该方案需要将 SSL 私钥放置于部署神策服务的机器上，且加密算法的选择受限于使用的 Nginx 二进制编译时的 OpenSSL 版本；
使用 HTTPS 加密传输需要提供 SSL 证书，神策不提供任何 SSL 证书。该证书可以通过多种渠道获取，若使用自签证书请确保客户端信任该
证书;
使用 HTTPS 请关注证书的过期时间，若证书过期可能会导致数据无法发送成功;
HTTPS 的 TLS/SSL 层需要消耗额外 CPU、带宽资源。
在神策服务的 Nginx 上配置 HTTPS 可以参考以下步骤:
1. 登录部署神策分析机器：
# sa_cluster
su - sa_cluster2. 切换到部署 Nginx 的目录：
cd $SENSORS_PLATFORM_HOME/nginx
3. 创建证书目录：
mkdir -p $SENSORS_PLATFORM_HOME/nginx/cert
4. 将配置好的 SSL 证书公钥和私钥放置到创建的 cert 目录下;
5. 切换到部署 Nginx 的配置目录：
Nginx 启动时会加载 conf.d 目录下的所有配置文件，这些配置文件内应该只包含 server 代码块;
cd $SENSORS_PLATFORM_HOME/nginx/conf.d
6. 复制模版文件
cp -a sensors_api_https.conf.default sensors_api_https.conf
模版文件名 描述
sensors_api_https.conf.default https 协议的数据接入服务转发配置参考模版
7. vim 按照配置文件中的注释修改即可
8. 检查 Nginx 配置，在 Nginx 目录下执行如下命令测试配置是否正确：
cd $SENSORS_PLATFORM_HOME/nginx/
sudo sbin/nginx -t
如果出现如下提示说明配置正确：
nginx: the configuration file ./conf/nginx.conf syntax is ok
nginx: configuration file ./conf/nginx.conf test is successful
若有报错请按照报错提示修改后重新检测。
9. 配置测试并检查无误后，在 Nginx 目录下执行如下命令使 Nginx 重新加载配置：
cd $SENSORS_PLATFORM_HOME/nginx/
sudo sbin/nginx -s reload
3. 如何验证配置是否正确
获取 HTTPS 数据接入地址加 /debug （例如：https://datasink.cloud.sensorsdata.cn/debug）
在浏览器中直接访问，如返回“Sensors Analytics is ready to receive your data!” ，证明配置正确。API.API v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您
的数据咨询顾问获取一对一的协助。
神策分析除了强大的 UI 分析界面，还提供了完善的 API。
API 大致可以分为两类:
1. 查询 API: 主要用于获取各种数据分析报告;
2. 功能 API: 主要用于配置与其他功能;
1. 调用方法
API 采 用 标 准 的 HTTP 方 式 ， 调 用 的 URL 为 :
http://$WEB_URL/api/$API_URL?token=$API_SECRET&project=$PROJECT
其中 $WEB_URL 即网站的 URL，$API_URL 则表示具体的 API，如果使用神策分析 Cloud 服务，则对应的 URL 为:
http://{$service_name}.cloud.sensorsdata.cn
如果用户使用单机版私有部署的神策分析，默认的配置信息为：
http://{$host_name}:8107
如果用户使用集群版私有部署的神策分析，默认的配置信息如下，其中 host_name 可以是集群中任意一台机器：
http://{$host_name}:8107
如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。
$API_SECRET 用于认证，用于认证，可以使用 admin 账户登录系统之后，在右上角点击用户名，点击“权限管理”界面获取（如果是 1.11 及之前的旧版本没
有这个界面，请联系技术支持人员获取），1.11 至 1.13 版本获取方式如下图：
1.15 及之后版本获取 API_Secret 的方式如下图所示：修改 admin 帐号的密码会使 API Secret 发生改变。
1.11 以及之前的系统版本，默认项目的 API Secret 可以访问任意项目的数据；非默认项目的 API Secret 仅能访问该项目的数据；
1.12 版本以及之后的版本，所有项目的 API Secret 仅能访问该项目的数据。
API Secret 和导入数据使用的 Token 没有任何关联。
project 是可选参数，$PROJECT 是 API 操作对应的项目名，默认值为 default，即默认项目。
例如访问 Demo 环境默认项目的事件分析报告的完整地址是:
http://demo.sensorsdata.cn/api/events/report?token=9c283f5711ef03e61e2a67c007100fce
访问 Demo 环境 new_project 项目的事件分析报告的完整地址是:
http://demo.sensorsdata.cn/api/events/report?token=9c283f5711ef03e61e2a67c007100fce&project=new_project
有了地址之后，就可以使用任意 HTTP Client 进行 API 调用，例如使用 curl 工具访问 SaaS Demo 的事件分析报告的一个例子如下
curl ''https://saasdemo.cloud.sensorsdata.cn/api/events/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d'' \
-H ''Content-Type: application/json'' \
--data-binary ''{
"measures":[
{
"event_name":"FinalConvert",
"aggregator":"SUM",
"field":"event.FinalConvert.contract_value"
}
],
"unit":"day",
"by_fields":[
"event.FinalConvert.product_type"
],
"to_date":"2016-08-14",
"from_date":"2016-08-14"
}''2. 如何快速获取请求参数
因为大部分查询 API 的参数结构都比较复杂，在使用的时候往往不好组织。这里建议大家可以通过浏览器访问神策分析平台来获取需要的参数。方法如下：
以 Chrome 浏览器获取事件分析报告 /events/report 请求参数为例：
1. 打开开发者工具
在浏览器中右上角的 更多（竖着的三个点）——> 更多工具 ——> 开发者工具，或者 MAC 用户按 option+command+i，Windows 用户使用 F12 快捷键。
打开后如图所示：
2. 在开发者工具中点击 A 处（Network），进入网络选项卡。
3. 之后在页面中按照自己的需求添加任意指标和过滤参数。这时候我们可以看到在 C 处（请求栏）中出现了很多地址选项，这些都是浏览器向服务器发送的
请求。
4. 用户直接点击相应的请求就可以查看到此次请求所附带的参数。
如果请求较多不好筛选，可以在 B 处（过滤栏）中输入所需要的 API 地址 ,如 “/events/report”，进行过滤筛选。功能 API.功能 API v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您
的数据咨询顾问获取一对一的协助。
查询 API 主要用于获取各种数据分析报告。
神策分析提供一系列功能 API，利用这些 API 可以：
1. 配置数据概览;
2. 配置用户分群;
3. 获取埋点统计报告;
4. 获取某个用户的访问 TOKEN;
1. 调用方法
请参见 API 中的调用方法描述。
2. 数据概览
2.1. 增加数据概览
> [POST /dashboards]
+ Request (application/json)
{
"name": ""
"is_public": 0 // 01
}
+ Response 200 (application/json)
{
"id": 2 // dashboard id
}
2.2. 删除数据概览
> [DELETE /dashboards/{dashboardId}]
+ 使用 curl 示例
// $ID id API
curl ''https://golddemo.cloud.sensorsdata.cn/api/dashboards/$ID?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default''
2.3. 获取所有数据概览
> [GET /dashboards]
+ Response 200 (application/json)
[
{
"id": 1,
"name": "",
"create_time": "2015-11-04 16:34:33",
"user_id": 1,"is_default": 0,
"is_public": 1,
"username": "admin",
"project_id": 1,
"config": "{\"widgetTime\":\"0 week\",\"widgetUnit\":\"minute\"}"
},
{
"id": 3,
"name": "",
"create_time": "2015-11-04 17:38:29",
"user_id": 1,
"is_default": 0,
"is_public": 1,
"username": "admin",
"project_id": 1
}
]
2.4. 获取某个数据概览的详情
>［GET /dashboards/{dashboardId}］
+ Response 200 (application/json)
{
"id": 1, // id
"name": "", //
"create_time": "2015-11-04 16:34:33", //
"user_id": 1,
"is_default": 0,
"is_public": 1,
"username": "admin",
"items": [
{
"bookmark": {
"id": 1, // id
"type": "/segmentation/",
"name": "",
"data": "{\"measures\":[{\"event_name\":\"views\",\"aggregator\":\"unique\"}],\"unit\":\"day\",\"
by_fields\":[\"user.first_visit_channel\"],\"chartsType\":\"line\",\"sampling_factor\":64,\"from_date\":\"2016-
06-20\",\"to_date\":\"2016-06-26\",\"bookmarkid\":\"1\",\"bookmarktime\":\"7 day\",\"rollup_date\":\"false\",\"
filter\":{}}",
"time": "7 day",
"create_time": "2015-11-04 04:35:44",
"user_id": 1,
"dashboards": [],
"related_events": [
"views"
],
"project_id": 1
},
"config": "{\"widgetIndex\":2,\"widgetByValues\":[\"\",\"36kr\",\"\"],\"widgetType\":\"column\",\"
widgetTime\":\"7 day\",\"widgetUnit\":\"day\",\"widgetRememberType\":{\"unit\":\"column\"}}",
"bookmark_id": 0
},
{
"bookmark": {
"id": 183,
"type": "/segmentation/",
"name": "",
"data": "{\"measures\":[{\"event_name\":\"applies\",\"aggregator\":\"unique\"}],\"unit\":\"month\",\"
by_fields\":[\"user.first_visit_channel\"],\"chartsType\":\"line\",\"sampling_factor\":64,\"from_date\":\"2016-
01-01\",\"to_date\":\"2016-06-20\",\"filter\":{}}",
"time": "7 day",
"create_time": "2016-06-27 07:24:23",
"user_id": 1,
"dashboards": [],"related_events":
[ "applies"
],
"project_id": 1
},
"config": "{\"widgetIndex\":3,\"widgetByValues\":[\"\",\"36kr\",\"\"],\"widgetType\":\"line\",\"
widgetTime\":\"7 day\",\"widgetUnit\":\"day\",\"widgetRememberType\":{\"unit\":\"line\"}}",
"bookmark_id": 0
}
],
"project_id": 1,
"config": "{\"widgetTime\":\"0 week\",\"widgetUnit\":\"minute\"}"
}
2.5. 保存书签到数据概览
> [POST /bookmarks/bookmark]
保存书签到数据概览时，书签类型可以是事件分析，漏斗分析，留存分析，分布分析，对应的 type 分别是 /segmentation/, /funnel/, /retention/,
/addiction/。data 是对应的 request，request 写法参考第三节。
+ Request (application/json)
{
"related_events":
[ "Share"
],
"name": "", //
"dashboards": [
2 // id
],
"type": "/segmentation/",
"data": "{\"measures\":[{\"event_name\":\"Share\",\"aggregator\":\"general\"}],\"unit\":\"day\",\"
chartsType\":\"line\",\"sampling_factor\":64,\"rangeText\":\"\",\"from_date\":\"2016-10-17\",\"to_date\":\"2016-
10-20\",\"filter\":{}}"
}
+ Response 200 (application/json)
{
"id": 1 //id
}
2.6. 获取书签配置
> [GET /bookmarks/bookmark/{bookmarkId}]
书签配置包括类型、名称和具体的查询条件。
+ Response 200 (application/json)
{
"id" : 26,
"type" : "/segmentation/",
"name" : "",
"data" : "{\"unit\":\"day\",\"filter\":{},\"by_fields\":[\"event.ViewProduct.ProductType\"],\"chartsType\":\"
line\",\"to_date\":\"2015-08-28\",\"from_date\":\"2015-05-29\",\"measures\":[{\"event_name\":\"ViewProduct\",\"
aggregator\":\"general\"}]}",
"time" : "1 week",
"create_time" : "2015-08-29 04:09:24",
"user_id" : 1,
"dashboards" : [ 5 ],
"project_id" : 1
}2.7. 删除一个数据概览中的书签
> ［DELETE /bookmarks/bookmark/{bookmarkId}］
3. 用户分群
1.13 的分群 API 相对于 1.12 版本，有不兼容的改动。详情请参考两个版本各自的文档。
用户分群
4. 埋点统计
埋点统计 API
5. 用户 TOKEN
使用 API_SECRET 可以满足各种查询需求，但如果希望获取与某个唯一用户对应的 ACCESS_TOKEN 可以参考本节的方法。当获取到 ACCESS_TOKEN
后，请求不需要再使用 API_SECRET。该 ACCESS_TOKEN 与每个项目中的用户账号唯一对应，可使用的权限与该用户在这个项目中分配角色所授予的数
据查看和事件使用权限保持一致。
仅当需要进行“与某个用户相关的操作”时才需使用“用户 TOKEN”，例如为某个用户设置概览。若仅使用查询 API，请参考 [API 文档](api.md) 的
1. 调用方法 使用 `$API_SECRET` 即可；
对于每个用户，最多同时有效的 ACCESS_TOKEN 为 20 个。当一个用户已经有 20 个 ACCESS_TOKEN 时，再获取新的 ACCESS_TOKEN 将使该
用户之前有效的 ACCESS_TOKEN 里面获取时间最早的一个失效；
使用浏览器通过神策界面进行登录获取的 ACCESS_TOKEN 与通过该 API 获取的等价，上一条的 20 个限制同样适用，例如通过 API 获取时触发
20 个上限，淘汰了用界面登录保存在浏览器里的 ACCESS_TOKEN，则将导致浏览器的登录失效；
5.1. 获取 ACCESS_TOKEN
5.1.1. 使用 API_SECRET 并指定用户名来获取该用户的 ACCESS_TOKEN，使用 curl 访问：
curl -v ''http://$WEB_URL/api/auth/login?token=$API_SECRET&project=$PROJECT'' \
-X POST -H ''Content-Type: application/json'' \
--data ''{"username":"user1"}''
Response 样例:
{
"role":0,
"user_id":7,
"token":"
de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f002
2c851df846b0401b",
"username":"user1",
"event_permission":{
"type":"ALL",
"events":[]
}
}
5.1.2. 神策系统版本 < 1.15 时，使用用户名和密码模拟登录获取该用户的 ACCESS_TOKEN，使用 curl 请求
命令如下：
curl -v ''http://$WEB_URL/api/auth/login?project=$PROJECT'' \
-X POST -H ''Content-Type: application/json'' \
--data ''{"username":"user1","password":"123456"}''
Response 样例:{
"role":0,
"user_id":7,
"token":"
de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f002
2c851df846b0401b",
"username":"user1",
"event_permission":{
"type":"ALL"
"events":[]
}
}
注意：
1. 1.13.5619 及之后某个版本支持开通验证码的方式登录，如果客户开启验证码的方式的登录，通过上述方式获取 ACCESS_TOKEN 时会提示“验证
码错误或者已过期”。建议直接用 API_SECRET 的方式获取 ACCESS_TOKEN。
2. 目前仅支持项目账号通过此方式获取Token.
5.1.3. 神策系统版本 >= 1.15 时，使用用户名和密码模拟登录获取该用户的 ACCESS_TOKEN，使用 curl 请求
命令如下：
curl -v ''http://$WEB_URL/api/v2/auth/login?project=$PROJECT'' \
-X POST -H ''Content-Type: application/json'' \
--data ''{"account_name":"user1","password":"123456", "expired_interval": 259200}''
Response 样例:
{
"account_name":0,
"account_id":7,
"session_id":"
de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f002
2c851df846b0401b"
}
注意：
1. 1.13.5619 及之后某个版本支持开通验证码的方式登录，如果客户开启验证码的方式的登录，通过上述方式获取 ACCESS_TOKEN 时会提示“验证
码错误或者已过期”。建议直接用 API_SECRET 的方式获取 ACCESS_TOKEN。
2. 如果使用的是平台账号，务必在请求的 URL 中增加参数"is_global=true".
5.1.4. 指定 ACCESS_TOKEN 的过期时间
在 1.13 以及之前的版本，access_token 的有效期默认是 7 天。（这个 7 天是指距离最后一次访问时的时间间隔）。1.14 版本及之后的版本，
access_token 的有效期默认是 30 分钟。
在 1.12 以及之后的版本中，可通过指定时间来延长 access_token 的过期时间，最长可延长到六个月的时间。请求样例如下：
curl -v ''http://$WEB_URL/api/auth/login?token=$API_SECRET&project=$PROJECT'' \
-X POST -H ''Content-Type: application/json'' \
--data ''{"username":"user1", "expired_interval": 259200}''
返回结果与普通的获取 ACCESS_TOKEN 相同。其中请求的参数中，通过 expired_interval 指定过期时间，单位为分钟。示例中 259200 分钟即为最长的过
期时间: 180 天。这个过期时间，是指 距离最后一次 请求的时间，并不是生成 ACCESS_TOKEN 的时间。也就是说，只有 你180 天没有使用该账号访问过
系统，或者没有使用这个 ACCESS_TOKEN 请求数据，才会过期。
注意：删除账号或者修改账号密码，之前获取的 ACCESS_TOKEN 都会失效。
5.1.5. 使用 ACCESS_TOKEN上一节的 Response 中的 token 字段即该用户的 ACCESS_TOKEN，其他 API 请求使用该 ACCESS_TOKEN 可通过指定 Header `sensorsdata-token`，
例如查询事件分析报告使用 ACCESS_TOKEN:
curl -v ''https://saasdemo.cloud.sensorsdata.cn/api/events/report'' \
-H ''sensorsdata-token:
de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f002
2c851df846b0401b'' \
-H ''Content-Type: application/json'' \
--data-binary ''{
"measures":[
{
"event_name":"FinalConvert",
"aggregator":"SUM",
"field":"event.FinalConvert.contract_value"
}
],
"unit":"day",
"by_fields":[
"event.FinalConvert.product_type"
],
"to_date":"2016-08-14",
"from_date":"2016-08-14"
}''分群 API.分群 API v1.13
Ver 1.13 版本的分群 API
Ver >=1.14 标签及用户群 API
Ver <= 1.12 版本的分群 APIVer 1.13 版本的分群 API.Ver 1.13 版本的分群 API v1.13
分群规则描述
规则描述部分是可嵌套的结构，较为复杂，此处单独进行描述。
在 “添加” 分群时，会用到规则描述。
rules\_relation\_node: 规则之间的逻辑关系
//
{
"type": "rules_relation"
"relation": string; // and/or
"rules":[] // type "rules_relation"
}
rule\_node: 规则节点，分三种
//
{
"type": "profile_rule",
"field": string, //
"function": string, //
"params": [] // List<Object>
}
//
{
"type": "event_rule",
"measure": {
"type": "event_measure",
"event_name": string, //
"aggregator": string, // count, sum
"field": string // optional. field
},
"time_function": string, //
"time_params": [], //
"function": string, //
"params": [], //
"filters": [] // filter_relation_nodefilter_node
}
//
{
"type": "event_sequence_rule",
"time_function": string, //
"time_params": [], //
"steps":
[
{
"event": string, // 11
"filters": [] //
},
{
"event": string, // 22
"filters": [] //
}
]
}
filter\_realtion\_node: 同一事件的筛选条件的逻辑关系
{
"type": "filters_relation",
"relation": string; // and/or
"subfilters":[] // typefilters_relationfilter
}filter\_node: 事件或事件型指标的数据约束
{
"type": "filter"
"field": string, //
"function": string, //
"params": [] //
}
添加一个分群
[POST /segmenter/rule]
Request (application/json)
{
"id": 0, // 0
"name": "last_30_days_apply",
"cname": "last_30_days_apply",
"type": 0, // 0 1 2 query_result 5 6
"app_push_list": [
0 // app push
],
"scheduler": { //
"running": true, // true false
"cron": "string" // cron 0 0 3 2,3,4 * ? *
},
"content":
{ "type":
"string",
"relation": "string",
"rules": [
{}
]
}
}
Response 200 (application/json)
{
"id": 0, // ID
"base_time": "string" // partition base_time2018-01-02 10:00:00
}
执行一个分群
［POST /segmenter/execute］
Request (application/json)
[
{
"id": 0, // ID
"base_time_list": [
"string" // 2018-08-28 10:00:00
]
}
]Response 200 (application/json)
{}
获取一个分群的执行状态
[POST /segmenter/status]
Request (application/json)
[
{
"id": 0, // id
"base_time_list": [
"string" // base_time , 2018-08-28 10:00:00
]
}
]
Response 200 (application/json)
[
{
"id": 0, // ID
"result": [
{
"base_time": "string", // 2018-08-28 10:00:00
"count": 0, //
"status": "string", // newcomputingsucceedfailed
"finished_time": "string", //
"error_code": 0 //
}
]
}
]
删除一个分群
［DELETE /segmenter/rule/{id}］
Response 200 (application/json)
{}
获取所有分群
[GET /segmenter/rule/all]
Response (application/json)
{
"total": 0, //"result": [
{
"id": 0, // ID
"name": "string", //
"cname": "string", //
"user_name": "string", //
"create_time": "string", //
"type": 0, // 0 1 2 query_result 5 6 7 SQL
"dir_id": 0, // ID
"scheduler": {
"running": true, // true false
"cron": "string", // cron 0 0 3 2,3,4 * ? *
"execute_cron": "string" // execute_cron 0 0 3 2,3,4 * ? *
},
"failed_partition_count": 0, // partition
"content": {
"type": "string", // rules_relation
"relation": "string", // and/or
"rules": [ //
{}
]
},
"last_partition": {
"base_time": "string", // 2018-08-28 11:00:00
"finished_time": "string", //
"count": 0, //
"app_push_list": [ //
0 // ID
],
"status": "string", // Partition newcomputingfinishfailed
"content": { //
"type": "string", // rules_relation
"relation": "string", // and/or
"rules": [ //
{}
]
}
}
}
]
}.Ver 1.13 版本的分群 API v1.14
1. 分群规则描述
规则描述部分是可嵌套的结构，较为复杂，此处单独进行描述。
在 “添加” 分群时，会用到规则描述。
rules\_relation\_node: 规则之间的逻辑关系
//
{
"type": "rules_relation"
"relation": string; // and/or
"rules":[] // type "rules_relation"
}
rule\_node: 规则节点，分三种
//
{
"type": "profile_rule",
"field": string, //
"function": string, //
"params": [] // List<Object>
}
//
{
"type": "event_rule",
"measure": {
"type": "event_measure",
"event_name": string, //
"aggregator": string, // count, sum
"field": string // optional. field
},
"time_function": string, //
"time_params": [], //
"function": string, //
"params": [], //
"filters": [] // filter_relation_nodefilter_node
}
//
{
"type": "event_sequence_rule",
"time_function": string, //
"time_params": [], //
"steps":
[
{
"event": string, // 11
"filters": [] //
},
{
"event": string, // 22
"filters": [] //
}
]
}
filter\_realtion\_node: 同一事件的筛选条件的逻辑关系
{
"type": "filters_relation",
"relation": string; // and/or
"subfilters":[] // typefilters_relationfilter
}filter\_node: 事件或事件型指标的数据约束
{
"type": "filter"
"field": string, //
"function": string, //
"params": [] //
}
2. 添加一个分群
[POST /segmenter/rule]
Request (application/json)
{
"id": 0, // 0
"name": "last_30_days_apply",
"cname": "last_30_days_apply",
"type": 0, // 0 1 2 query_result 5 6
"app_push_list": [
0 // app push
],
"scheduler": { //
"running": true, // true false
"cron": "string" // cron 0 0 3 2,3,4 * ? *
},
"content":
{ "type":
"string",
"relation": "string",
"rules": [
{}
]
}
}
Response 200 (application/json)
{
"id": 0, // ID
"base_time": "string" // partition base_time2018-01-02 10:00:00
}
3. 执行一个分群
［POST /segmenter/execute］
Request (application/json)
[
{
"id": 0, // ID
"base_time_list": [
"string" // 2018-08-28 10:00:00
]
}
]Response 200 (application/json)
{}
4. 获取一个分群的执行状态
[POST /segmenter/status]
Request (application/json)
[
{
"id": 0, // id
"base_time_list": [
"string" // base_time , 2018-08-28 10:00:00
]
}
]
Response 200 (application/json)
[
{
"id": 0, // ID
"result": [
{
"base_time": "string", // 2018-08-28 10:00:00
"count": 0, //
"status": "string", // newcomputingsucceedfailed
"finished_time": "string", //
"error_code": 0 //
}
]
}
]
5. 删除一个分群
［DELETE /segmenter/rule/{id}］
Response 200 (application/json)
{}
6. 获取所有分群
[GET /segmenter/rule/all]
Response (application/json)
{
"total": 0, //"result": [
{
"id": 0, // ID
"name": "string", //
"cname": "string", //
"user_name": "string", //
"create_time": "string", //
"type": 0, // 0 1 2 query_result 5 6 7 SQL
"dir_id": 0, // ID
"scheduler": {
"running": true, // true false
"cron": "string", // cron 0 0 3 2,3,4 * ? *
"execute_cron": "string" // execute_cron 0 0 3 2,3,4 * ? *
},
"failed_partition_count": 0, // partition
"content": {
"type": "string", // rules_relation
"relation": "string", // and/or
"rules": [ //
{}
]
},
"last_partition": {
"base_time": "string", // 2018-08-28 11:00:00
"finished_time": "string", //
"count": 0, //
"app_push_list": [ //
0 // ID
],
"status": "string", // Partition newcomputingfinishfailed
"content": { //
"type": "string", // rules_relation
"relation": "string", // and/or
"rules": [ //
{}
]
}
}
}
]
}Ver 1.14 标签及用户群 API.Ver 1.14 标签及用户群 API v1.13
1. 标签/用户群规则描述
规则描述部分是可嵌套的结构，较为复杂，此处单独进行描述。
在 “添加” 标签/用户群时，会用到规则描述。
rules\_relation\_node: 规则之间的逻辑关系
//
{
"type": "rules_relation"
"relation": string; // and/or
"rules":[] // type "rules_relation"
}
rule\_node: 规则节点，分三种
//
{
"type": "profile_rule",
"field": string, // //
"function": string, //
"params": [] // List<Object>
}
//
{
"type": "event_rule",
"measure": {
"type": "event_measure",
"event_name": string, //
"aggregator": string, // count, sum
"field": string // optional. field
},
"time_function": string, //
"time_params": [], //
"function": string, //
"params": [], //
"filters": [] // filter_relation_nodefilter_node
}
//
{
"type": "event_sequence_rule",
"time_function": string, //
"time_params": [], //
"steps":
[
{
"event": string, // 11
"filters": [] //
},
{
"event": string, // 22
"filters": [] //
}
]
}
filter\_realtion\_node: 同一事件的筛选条件的逻辑关系
{
"type": "filters_relation",
"relation": string; // and/or
"subfilters":[] // typefilters_relationfilter
}filter\_node: 事件或事件型指标的数据约束
{
"type": "filter"
"field": string, //
"function": string, //
"params": [] //
}
2. 分群 API 全部下线，1.14 分群升级为用户群
以下接口的 request 和response 都是application/json 格式
公共字段 字段名、字段含义、字段类型及可选值：
字段名 字段含义 字段 是否 可选值 其他说明
类型 必填
name 标签/用户群英文名 string 否 创建时不填写则不校验（默认给个不冲突的 name），如果填写了则会进行重名校
验
cname 标签/用户群中文名 string 是
comment 标签/用户群备注 string 否
cron 调度周期 string 否 cron 表达式 如：0 0 0 * * ? * 表示每天 0 点计算，如果是单次标签/用户群则可缺省
is_routine 是否是例行标签/用 boolean 否 如果是例行标签/用户群，则上面的 cron 必填
户群
app_push app push 配置列表 list 否
_list
base_time 标签/用户群计算的 string 否 创建时不需填写（填写也无效）格式如："2019-03-05 00:00:00"
基准时间
unit 标签/用户群更新周 string 是 DAY 目前只支持 DAY
期
data_type 标签/用户群数据类 string 是 BOOL, NUMBER, STRING, 参考 数据格式
型 DATETIME
source_t 标签/用户群类型 string 是 1 source_type 的可选值：1，7。1 -规则创建的标签/用户群，7 -使用 SQL 创建
ype 用户标签（无法创建分群） 。
目前 API 的方式不支持通过上传文件的方式创建分群。
2.1. 创建一个用户群
[POST /segmenter/rule 创建分群] 替换为 [PUT /v2/user_groups 创建一个用户群]
Request
{
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size = 1
{
"type": "string",
"relation": "string",
"rules": [
{}]
}
]
}
Response 200
{
"id": 0,
"name": "string",
"cname": "string",
"user_name": "string",
"create_time": "string", //
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"status": "PENDING",
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
, Typeint
"failed_partition_count": 0, // partition
"last_succeed_partition": { // partition
"base_time": "string",
"start_time": "string", //
"finished_time": "string", //
"user_count": 0, //
"status": "SUCCEED", // partition
"rule_content_list": [
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0, base_time
"status": "NEW",
} "next_partition_base_time": "string" //
}
2.2. 获取用户群列表
[GET/segmenter/rule/all 获取分群列表] 替换为 [GET /v2/user_groups 获取用户群列表]
Responses 200[
{
"id": 0,
"name": "string",
"cname": "string",
"user_name": "string",
"create_time": "string", //
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"status": "PENDING",
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
],
"failed_partition_count": 0, // partition Typeint
"last_succeed_partition": { // partition
"base_time": "string",
"start_time": "string", //
"finished_time": "string", //
"user_count": 0, //
"status": "SUCCEED", // partition
"rule_content_list": [
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
},
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string" // base_time
}
}
]
2.3. 执行用户群
[POST /segmenter/execute 执行分群] 替换为 [POST /v2/user_tags/{id}/execute 执行标签]
Request（In Path）：
base_time_list：Partition 的 base_time。 Type ：List<String>，可缺省。缺省计算最近一次 Partition
Response 200
{}2.4. 获取用户群信息
[GET /segmenter/rule/{id} 获取分群详情] 替换为 [GET /v2/user_groups/{id} 获取用户群信息]
Response 200
{
"id": 0,
"name": "string",
"cname": "string",
"user_name": "string",
"create_time": "string", //
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"status": "PENDING",
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
, Typeint
"failed_partition_count": 0, // partition
"last_succeed_partition": { // partition
"base_time": "string",
"start_time": "string", //
"finished_time": "string", //
"user_count": 0, //
"status": "SUCCEED", // partition
"rule_content_list": [
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0, base_time
"status": "NEW",
} "next_partition_base_time": "string" //
}
2.5. 删除用户群
[DELETE /segmenter/rule/{id} 删除分群] 替换为 [DELETE /v2/user_groups/{id} 删除用户群]
Response 200{}
2.6. 检查用户群执行状态
[POST /segmenter/status 检查分群执行状态] 替换为 [GET /v2/user_tags/{id}/status 检查标签执行状态]
Request（In Path）：
base_time_list：用户群的 Partition 对应的 base_time，Type：List<String>，缺省则返回最新一个 Partition 的状态
Response 200
[
{
"base_time": "string",
"user_count": 0, // partition
"status": "NEW", // partition
"start_time": "string", // partition
"finished_time": "string" // partition
}
]
3. 标签 API（新增）
3.1. 创建一个标签
[PUT /v2/user_tags 创建标签]
Request：
{
"dir_id": 0, // idType: int
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true, // Typeboolean
"comment": "string", //
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ //
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}Response 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
],
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
},
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
}
}
3.2. 更新标签配置
[PUT /v2/user_tags/{id} 更新标签配置]
Request：
{
"dir_id": 0, // idType: int
"name": "string","cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true, // Typeboolean
"comment": "string", //
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ //
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
Response 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
,
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string","rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
} }
3.3. 获取标签列表
[GET /v2/user_tags 获取标签列表]
Response 200
[
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
,
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
}
}
]
3.4. 获取标签元信息
[GET /v2/user_tags/{id} 获取标签元信息]
Response 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
],
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
},
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW","next_partition_base_time": "string"
}
}
3.5. 删除标签
DELETE /v2/user_tags/{id} 删除标签
Response 200
{}
3.6. 修改标签调度状态
[PATCH /v2/user_tags/{id} 修改标签的调度状态]
Request：
{
"status": TypeStringAvailable ValuesPENDING, RUNNING, SUSPENDPENDING RUNNING SUSPEND
// RUNNING PENDING
}
Resonse 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 1,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
,
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
} }
3.7. 执行标签
[POST /v2/user_tags/{id}/execute 执行标签]
Request（In Path 可 缺 省 ， 缺 省 则 执 行 最 近 一 个 partition）：
base_time_list：Type: List<String>，Partition 的 base_time 列表
Response 200
{}
3.8. 检查标签执行状态
[GET /v2/user_tags/{id}/status]
Request（In Path 可缺省）：
base_time_list：Type：List<String>，Partition 对应的 base_time 列表，缺省则返回最后一个的执行状态
Response 200
[
{
"base_time": "string",
"user_count": 0,
"status": "NEW",
"start_time": "string",
"finished_time": "string"
}
]
3.9. 获取标签详情
[POST /v2/user_tags/{id}/report] 获取标签详情
Request：
{
"from_date": "string",
"to_date": "string",
"bucket_param": [ // NUMBER LIST bucket_param
// bucket_param [1]// bucket_param [null]
//
0
],
"limit": 0
}
Response 200
{
"aggregate_result": { //
"series": [
"string"
],
"rows": [
{
"by_value": "string",
"partition_values": [
{
"user_count": 0,
"percent": 0,
"base_time": "string",
"finished_time": "string"
}
]
}
]
},
"non_aggregate_result": { //
"series": [
"string"
],
"rows": [
{
"by_value": "string",
"partition_values": [
{
"user_count": 0,
"percent": 0,
"base_time": "string",
"finished_time": "string"
}
]
}
]
}
}
3.10. 获取标签的完整目录结构
[GET /v2/user_tags/dirs]
Response 200
[
{
"type": "string",
"id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"is_default": true,
"items": [
null
]}
]
3.11. 更新标签的目录结构
[PUT /v2/user_tags/dirs]
Request
[
{
"type": "string",
"id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"is_default": true,
"items": [
null
]
}
]
Response 200
{}
3.12. 删除目录，只能进行目录的删除
[DELETE /v2/user_tags/dirs]
Request：
[
id ****
]
Response
{}.Ver >=1.14 标签及用户群 API v1.14
1. 标签/用户群规则描述
规则描述部分是可嵌套的结构，较为复杂，此处单独进行描述。
在 “添加” 标签/用户群时，会用到规则描述。
rules\_relation\_node: 规则之间的逻辑关系
//
{
"type": "rules_relation"
"relation": string; // and/or
"rules":[] // type "rules_relation"
}
rule\_node: 规则节点，分三种
//
{
"type": "profile_rule",
"field": string, // //
"function": string, //
"params": [] // List<Object>
}
//
{
"type": "event_rule",
"measure": {
"type": "event_measure",
"event_name": string, //
"aggregator": string, // count, sum
"field": string // optional. field
},
"time_function": string, //
"time_params": [], //
"function": string, //
"params": [], //
"filters": [] // filter_relation_nodefilter_node
}
//
{
"type": "event_sequence_rule",
"time_function": string, //
"time_params": [], //
"steps":
[
{
"event": string, // 11
"filters": [] //
},
{
"event": string, // 22
"filters": [] //
}
]
}
filter\_realtion\_node: 同一事件的筛选条件的逻辑关系
{
"type": "filters_relation",
"relation": string; // and/or
"subfilters":[] // typefilters_relationfilter
}filter\_node: 事件或事件型指标的数据约束
{
"type": "filter"
"field": string, //
"function": string, //
"params": [] //
}
2. 分群 API 全部下线，1.14 分群升级为用户群
以下接口的 request 和response 都是application/json 格式
公共字段 字段名、字段含义、字段类型及可选值：
字段名 字段含义 字段类 是否必 可选值 其他说明
型 填
name 标签/用户群英文名 string 否 创建时不填写则不校验（默认给个不冲突的 name），如果填写了则会
进行重名校验
cname 标签/用户群中文名 string 是
comment 标签/用户群备注 string 否
cron 调度周期 string 否 cron 表达式 如：0 0 0 ? * 表示每天 0 点计算，如果是单次标签/用户群
则可缺省
is_routine 是否是例行标签/用户 boolean 否 如果是例行标签/用户群，则上面的 cron 必填
群
app_push_l app push 配置列表 list 否
ist
base_time 标签/用户群计算的基 string 否 创建时不需填写（填写也无效）格式如："2019-03-05 00:00:00"
准时间
unit 标签/用户群更新周期 string 是 DAY 目前只支持 DAY
data_type 标签/用户群数据类型 string 是 BOOL, NUMBER, STRING, 参考 数据格式
DATETIME
source_type 标签/用户群类型 string 是 1 规则创建的标签/用户群
2.1. 创建一个用户群
[POST /segmenter/rule 创建分群] 替换为 [PUT /v2/user_groups 创建一个用户群]
Request
{
"cname": "string",
"data_type": "BOOL",
"unit": "DAY",
"source_type": 0,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size = 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}]
}
Response 200
{
"id": 0,
"name": "string",
"cname": "string",
"user_name": "string",
"create_time": "string", //
"data_type": "BOOL",
"unit": "DAY",
"source_type": 0,
"is_routine": true,
"status": "PENDING",
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
, Typeint
"failed_partition_count": 0, // partition
"last_succeed_partition": { // partition
"base_time": "string",
"start_time": "string", //
"finished_time": "string", //
"user_count": 0, //
"status": "SUCCEED", // partition
"rule_content_list": [
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0, base_time
"status": "NEW",
} "next_partition_base_time": "string" //
}
2.2. 获取用户群列表
[GET/segmenter/rule/all 获取分群列表] 替换为 [GET /v2/user_groups 获取用户群列表]
Responses 200
[
{"id": 0,
"name": "string",
"cname": "string",
"user_name": "string",
"create_time": "string", //
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"status": "PENDING",
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
],
"failed_partition_count": 0, // partition Typeint
"last_succeed_partition": { // partition
"base_time": "string",
"start_time": "string", //
"finished_time": "string", //
"user_count": 0, //
"status": "SUCCEED", // partition
"rule_content_list": [
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
},
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string" // base_time
}
}
]
2.3. 执行用户群
[POST /segmenter/execute 执行分群] 替换为 [POST /v2/user_tags/{id}/execute 执行标签]
Request（In Path）：
base_time_list：Partition 的 base_time。 Type ：List<String>，可缺省。缺省计算最近一次 Partition
Response 200
{}
2.4. 获取用户群信息[GET /segmenter/rule/{id} 获取分群详情] 替换为 [GET /v2/user_groups/{id} 获取用户群信息]
Response 200
{
"id": 0,
"name": "string",
"cname": "string",
"user_name": "string",
"create_time": "string", //
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"status": "PENDING",
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ // list size 1
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
, Typeint
"failed_partition_count": 0, // partition
"last_succeed_partition": { // partition
"base_time": "string",
"start_time": "string", //
"finished_time": "string", //
"user_count": 0, //
"status": "SUCCEED", // partition
"rule_content_list": [
{
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0, base_time
"status": "NEW",
} "next_partition_base_time": "string" //
}
2.5. 删除用户群
[DELETE /segmenter/rule/{id} 删除分群] 替换为 [DELETE /v2/user_groups/{id} 删除用户群]
Response 200
{}2.6. 检查用户群执行状态
[POST /segmenter/status 检查分群执行状态] 替换为 [GET /v2/user_tags/{id}/status 检查标签执行状态]
Request（In Path）：
base_time_list：用户群的 Partition 对应的 base_time，Type：List<String>，缺省则返回最新一个 Partition 的状态
Response 200
[
{
"base_time": "string",
"user_count": 0, // partition
"status": "NEW", // partition
"start_time": "string", // partition
"finished_time": "string" // partition
}
]
3. 标签 API（新增）
3.1. 创建一个标签
[PUT /v2/user_tags 创建标签]
Request：
{
"dir_id": 0, // idType: int
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true, // Typeboolean
"comment": "string", //
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ //
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}Response 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
],
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
},
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
}
}
3.2. 更新标签配置
[PUT /v2/user_tags/{id} 更新标签配置]
Request：
{
"dir_id": 0, // idType: int
"name": "string",
"cname": "string",
"data_type": "BOOL","unit": "HOUR",
"source_type": 0,
"is_routine": true, // Typeboolean
"comment": "string", //
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [ //
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
{
"value": {}, //
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
Response 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
,
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
} }
3.3. 获取标签列表
[GET /v2/user_tags 获取标签列表]
Response 200
[
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
,
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
}
}
]
3.4. 获取标签元信息
[GET /v2/user_tags/{id} 获取标签元信息]
Response 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
],
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
},
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW","next_partition_base_time": "string"
}
}
3.5. 删除标签
DELETE /v2/user_tags/{id} 删除标签
Response 200
{}
3.6. 修改标签调度状态
[PATCH /v2/user_tags/{id} 修改标签的调度状态]
Request：
{
"status": TypeStringAvailable ValuesPENDING, RUNNING, SUSPENDPENDING RUNNING SUSPEND
// RUNNING PENDING
}
Resonse 200
{
"id": 0,
"dir_id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"unit": "HOUR",
"source_type": 0,
"is_routine": true,
"comment": "string",
"cron": "string",
"app_push_list": [
0
],
"rule_content_list": [
{
"sql": "string",
"value": {},
"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
,
"last_succeed_partition":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"rule_content_list": [
{
"sql": "string",
"value": {},"type": "string",
"relation": "string",
"rules": [
{}
]
}
]
}
,
"last_partition_info":
{ "base_time": "string",
"start_time": "string",
"finished_time": "string",
"user_count": 0,
"status": "NEW",
"next_partition_base_time": "string"
} }
3.7. 执行标签
[POST /v2/user_tags/{id}/execute 执行标签]
Request（In Path 可 缺 省 ， 缺 省 则 执 行 最 近 一 个 partition）：
base_time_list：Type: List<String>，Partition 的 base_time 列表
Response 200
{}
3.8. 检查标签执行状态
[GET /v2/user_tags/{id}/status]
Request（In Path 可缺省）：
base_time_list：Type：List<String>，Partition 对应的 base_time 列表，缺省则返回最后一个的执行状态
Response 200
[
{
"base_time": "string",
"user_count": 0,
"status": "NEW",
"start_time": "string",
"finished_time": "string"
}
]
3.9. 获取标签详情
[POST /v2/user_tags/{id}/report] 获取标签详情
Request：
{
"from_date": "string",
"to_date": "string",
"bucket_param": [ // NUMBER LIST bucket_param
// bucket_param [1]// bucket_param [null]
//
0
],
"limit": 0
}
Response 200
{
"aggregate_result": { //
"series": [
"string"
],
"rows": [
{
"by_value": "string",
"partition_values": [
{
"user_count": 0,
"percent": 0,
"base_time": "string",
"finished_time": "string"
}
]
}
]
},
"non_aggregate_result": { //
"series": [
"string"
],
"rows": [
{
"by_value": "string",
"partition_values": [
{
"user_count": 0,
"percent": 0,
"base_time": "string",
"finished_time": "string"
}
]
}
]
}
}
3.10. 获取标签的完整目录结构
[GET /v2/user_tags/dirs]
Response 200
[
{
"type": "string",
"id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"is_default": true,
"items": [
null
]}
]
3.11. 更新标签的目录结构
[PUT /v2/user_tags/dirs]
Request
[
{
"type": "string",
"id": 0,
"name": "string",
"cname": "string",
"data_type": "BOOL",
"is_default": true,
"items": [
null
]
}
]
Response 200
{}
3.12. 删除目录，只能进行目录的删除
[DELETE /v2/user_tags/dirs]
Request：
[
id ****
]
Response
{}Ver <= 1.12 版本的分群 API.Ver <= 1.12 版本的分群 API v1.13
分群规则描述
规则描述部分是可嵌套的结构，较为复杂，此处单独进行描述。
在 “添加” 分群时，会用到规则描述。
举例说明：
"content": [
{
"type": 0, // 0
"profile_filter": { //
"filter":
{ "conditions":
[
{
"field": "user.first_visit_channel",
"function": "equal",
"params":
[ ""
]
}
]
}
}
},
{
"type": 1, // 1
"event_filter": { // ,type1
"event_name": "ViewHomepage",
"filter": {
"relation": "",
"conditions": []
}
},
"min_repeated_times": 5, //
"max_repeated_times": 0, //
"relative_time_range": "", // : ''0 week''
"absolute_time_range": [ // [''2018-01-02''''2018-01-04'']
"2016-10-17 00:00:00",
"2016-10-20 00:00:00"
],
"relation": "and"
},
{
"type": 2, // 2
"event_filter_sequence": [ //
{
"event_name": "ContactCustomerService",
"filter": {
"conditions": [
{
"field": "event.ContactCustomerService.service_type",
"function": "equal",
"params":
[ ""
]
}
]
}
},
{
"event_name": "ViewFunction",
"filter": {}
}
],
"absolute_time_range":
[ "2016-10-17
00:00:00",
"2016-10-20 00:00:00"],
"relative_time_range": ""
}
]
添加一个分群
［POST /segmenter/rule］
Request (application/json)
{
"name": "last_30_days_apply",
"cname": "last_30_days_apply",
"status": "new", // new
"statusClass": "icon-new",
"type": 0, // 0, 1, 4
"content": [
{
"type": 0, // 0
"profile_filter": {
"filter":
{ "conditions": [
{
"field": "user.first_visit_channel",
"function": "equal",
"params":
[ ""
]
}
]
}
}
},
{
"type": 1, / 1
"event_filter": {
"event_name": "ViewHomepage",
"filter": {
"relation": "",
"conditions": []
}
},
"min_repeated_times": 5,
"max_repeated_times": 0,
"relative_time_range": "",
"absolute_time_range": [
"2016-10-17 00:00:00",
"2016-10-20 00:00:00"
],
"relation": "and"
},
{
"type": 2, // 2
"event_filter_sequence": [
{
"event_name": "ContactCustomerService",
"filter": {
"conditions": [
{
"field": "event.ContactCustomerService.service_type",
"function": "equal",
"params":
[ ""]
}
]
}
},
{
"event_name": "ViewFunction",
"filter": {}
}
]
,
"absolute_time_range":
[ "2016-10-17
00:00:00",
"2016-10-20 00:00:00"
} ],
]
}
Response 200 (application/json)
{
"id": 1 // id
}
执行一个分群
[POST /segmenter/execute/{segmenterId}]
获取一个分群的执行状态
[POST /segmenter/status]
Request (application/json)
[
1 // id
]
Response 200 (application/json)
[
{
"num_values": 12,
"id": 10,
"success_time": "2016-10-20 00:53:24",
"status": "preparing", // preparingfinishfailed
"last_partition": "2016-10-19 00:00:00"
}
]
删除一个分群
[DELETE /segmenter/rule/{segmenterId}]获取所有分群
[GET /segmenter/rule/all]
Response (application/json)
[
{
"num_values": 10,
"name": "last_30_days_apply",
"cname": "30",
"id": 2,
"success_time": "2016-10-20 00:53:24",
"type": 1,
"content": [
{
"type": 0,
"profile_filter": {
"filter":
{ "conditions":
[
{
"field": "user.first_visit_channel",
"function": "equal",
"params":
[ ""
]
}
]
}
}
},
{
"type": 1,
"relation": "and",
"event_filter": {
"event_name": "ViewHomepage",
"filter": {
"relation": "",
"conditions": []
}
},
"min_repeated_times": 5,
"max_repeated_times": 0,
"absolute_time_range": [],
"relative_time_range": "30 day"
},
{
"type": 2,
"event_filter_sequence": [
{
"event_name": "ContactCustomerService",
"filter": {
"conditions": [
{
"field": "event.ContactCustomerService.service_type",
"function": "equal",
"params":
[ ""
]
}
]
}
},
{
"event_name": "ViewFunction",
"filter": {}}
],
"absolute_time_range": [],
"relative_time_range": "0 week"
}
],
"status": "finish",
"last_partition": "2016-10-19 00:00:00"
},
{
"num_values": 1015,
"name": "last_week_full",
"cname": "7",
"id": 3,
"success_time": "2016-10-20 00:53:24",
"type": 1,
"content": [
{
"type": 2,
"event_filter_sequence": [
{
"event_name": "ViewHomepage",
"filter": {}
},
{
"event_name": "ViewFunction",
"filter": {}
},
{
"event_name": "ApplyDemo",
"filter": {}
}
],
"absolute_time_range": [],
"relative_time_range": "7 day"
}
],
"status": "finish",
"last_partition": "2016-10-19 00:00:00"
}
].Ver <= 1.12 版本的分群 API v1.14
1. 分群规则描述
规则描述部分是可嵌套的结构，较为复杂，此处单独进行描述。
在 “添加” 分群时，会用到规则描述。
举例说明：
"content": [
{
"type": 0, // 0
"profile_filter": { //
"filter":
{ "conditions":
[
{
"field": "user.first_visit_channel",
"function": "equal",
"params":
[ ""
]
}
]
}
}
},
{
"type": 1, // 1
"event_filter": { // ,type1
"event_name": "ViewHomepage",
"filter": {
"relation": "",
"conditions": []
}
},
"min_repeated_times": 5, //
"max_repeated_times": 0, //
"relative_time_range": "", // : ''0 week''
"absolute_time_range": [ // [''2018-01-02''''2018-01-04'']
"2016-10-17 00:00:00",
"2016-10-20 00:00:00"
],
"relation": "and"
},
{
"type": 2, // 2
"event_filter_sequence": [ //
{
"event_name": "ContactCustomerService",
"filter": {
"conditions": [
{
"field": "event.ContactCustomerService.service_type",
"function": "equal",
"params":
[ ""
]
}
]
}
},
{
"event_name": "ViewFunction",
"filter": {}
}
],
"absolute_time_range":
[ "2016-10-17
00:00:00",
"2016-10-20 00:00:00"],
"relative_time_range": ""
}
]
2. 添加一个分群
［POST /segmenter/rule］
Request (application/json)
{
"name": "last_30_days_apply",
"cname": "last_30_days_apply",
"status": "new", // new
"statusClass": "icon-new",
"type": 0, // 0, 1, 4
"content": [
{
"type": 0, // 0
"profile_filter": {
"filter":
{ "conditions": [
{
"field": "user.first_visit_channel",
"function": "equal",
"params":
[ ""
]
}
]
}
}
},
{
"type": 1, / 1
"event_filter": {
"event_name": "ViewHomepage",
"filter": {
"relation": "",
"conditions": []
}
},
"min_repeated_times": 5,
"max_repeated_times": 0,
"relative_time_range": "",
"absolute_time_range": [
"2016-10-17 00:00:00",
"2016-10-20 00:00:00"
],
"relation": "and"
},
{
"type": 2, // 2
"event_filter_sequence": [
{
"event_name": "ContactCustomerService",
"filter": {
"conditions": [
{
"field": "event.ContactCustomerService.service_type",
"function": "equal",
"params":
[ ""]
}
]
}
},
{
"event_name": "ViewFunction",
"filter": {}
}
]
,
"absolute_time_range":
[ "2016-10-17
00:00:00",
"2016-10-20 00:00:00"
} ],
]
}
Response 200 (application/json)
{
"id": 1 // id
}
3. 执行一个分群
[POST /segmenter/execute/{segmenterId}]
4. 获取一个分群的执行状态
[POST /segmenter/status]
Request (application/json)
[
1 // id
]
Response 200 (application/json)
[
{
"num_values": 12,
"id": 10,
"success_time": "2016-10-20 00:53:24",
"status": "preparing", // preparingfinishfailed
"last_partition": "2016-10-19 00:00:00"
}
]
5. 删除一个分群
[DELETE /segmenter/rule/{segmenterId}]6. 获取所有分群
[GET /segmenter/rule/all]
Response (application/json)
[
{
"num_values": 10,
"name": "last_30_days_apply",
"cname": "30",
"id": 2,
"success_time": "2016-10-20 00:53:24",
"type": 1,
"content": [
{
"type": 0,
"profile_filter": {
"filter":
{ "conditions":
[
{
"field": "user.first_visit_channel",
"function": "equal",
"params":
[ ""
]
}
]
}
}
},
{
"type": 1,
"relation": "and",
"event_filter": {
"event_name": "ViewHomepage",
"filter": {
"relation": "",
"conditions": []
}
},
"min_repeated_times": 5,
"max_repeated_times": 0,
"absolute_time_range": [],
"relative_time_range": "30 day"
},
{
"type": 2,
"event_filter_sequence": [
{
"event_name": "ContactCustomerService",
"filter": {
"conditions": [
{
"field": "event.ContactCustomerService.service_type",
"function": "equal",
"params":
[ ""
]
}
]
}
},
{
"event_name": "ViewFunction",
"filter": {}}
],
"absolute_time_range": [],
"relative_time_range": "0 week"
}
],
"status": "finish",
"last_partition": "2016-10-19 00:00:00"
},
{
"num_values": 1015,
"name": "last_week_full",
"cname": "7",
"id": 3,
"success_time": "2016-10-20 00:53:24",
"type": 1,
"content": [
{
"type": 2,
"event_filter_sequence": [
{
"event_name": "ViewHomepage",
"filter": {}
},
{
"event_name": "ViewFunction",
"filter": {}
},
{
"event_name": "ApplyDemo",
"filter": {}
}
],
"absolute_time_range": [],
"relative_time_range": "7 day"
}
],
"status": "finish",
"last_partition": "2016-10-19 00:00:00"
}
]埋点统计 API.埋点统计 API v1.13
此文档适用于神策分析版本大于等于 1.12 。
1. 获取埋点来源
GET /data_source/category
使用该 API 获取当前埋点数据(一般只有最近7天的数据)的来源信息：APP 版本号、导入方式。
后续可以根据来源信息获取指定 APP 版本和指定导入方式的埋点报告信息。
Request GET /data_source/category
Response 200 (application/json)
{
"lib":[ //
"python",
"LogAgent"
],
"app_version":[ // APP
"1.0",
"1.1",
"2.0",
"2.1",
"1.2"
]
}
2. 获取埋点统计报告
POST /data_source/report
使用该 API 可以获取埋点统计报告。一般情况下，埋点数据仅保存最近 7 天数据。
若不指定查询区间，默认查询最近 1 小时的埋点统计。查询的运行时间与查询区间正相关，请合理配置查询区间，不要设置过大。
出现已导入大于已读取有可能是正常的，因为这是不同模块的统计结果，有可能这段时间没有读取和校验数据，但另一个模块正在导入之前校验成功的数
据。
埋点统计的时间是实际进行导入的时间，如今天导入了前天的一条数据，这条数据会被统计到今天的报告里。
Request (application/json)
{
"from":"1527056400000", //
"to":"1532499600000", //
"app_version":"all", // APP "all"
"status":"storage", // "storage" = ; "error" =
"lib":"python" //
}
Response 200 (application/json)
{
"read_update_time":1481711426000, //
"read":194, //
"send_update_time":1481711426000, //
"send":192, //
"write_update_time":1481711407000, //
"write":192, //
"detail_last":1481711426000, //
"detail":{
"read":19775, //
"send":19775, //
"write":19775, //
"err":0, //
"payload":[ //
{
"event":"taskOperation",
"read":961,
"send":961,
"write":961,
"err":0,
"last":0,"payload":[ //
{
"lib":"python",
"lib_version":"1.7.1",
"app_version":"2.0",
"lib_method":"code",
"lib_detail":"normal_mode##normal_mode##simulator.py##582",
"read":961,
"send":961,
"write":961,
"err":0,
"last":0
}
]
}
]
}
}埋点统计 API Ver <= 1.11.埋点统计 API Ver <= 1.11 v1.13
##
### 1 获取埋点统计报告
> [GET /data_source/report]
使用该 API 可以获取埋点统计报告。一般情况下，埋点数据仅保存最近 7 天数据。
若不指定查询区间，默认查询最近 1 小时的埋点统计。查询的运行时间与查询区间正相关，请合理配置查询区间，不要设置过大。
出现已导入大于已读取有可能是正常的，因为这是不同模块的统计结果，有可能这段时间没有读取和校验数据，但另一个模块正在导入之前校验成功的数
据。
埋点统计的时间是实际进行导入的时间，如今天导入了前天的一条数据，这条数据会被统计到今天的报告里。
+ Request (application/json) <button class="section" target="data_source_request_111" show="查看示例" hide="隐藏示例"></button>
<!--sec data-title="title" data-id="data_source_request_111" data-show=false ces-->
```json
{
"from":"1527056400000", // 查询时间区间开始时间
"to":"1532499600000" // 查询时间区间结束时间
}
```
<!--endsec-->
+ Response 200 (application/json) <button class="section" target="d_data_source_response_111" show="查看示例" hide="隐藏示例"></button>
<!--sec data-title="title" data-id="d_data_source_response_111" data-show=false ces-->
```json
{
"read_update_time": 1546674220000, // 上次更新读取条数时间
"read": 28114950, // 项目一共读取条数
"send_update_time": 1546674220000, // 上次更新发送条数时间
"send": 27322056, // 项目一共发送条数
"write_update_time": 1546674559000, // 上次更新导入条数时间
"write": 25404328, // 项目一共导入条数
"detail": {
"js": { // 根据来源端进行分类
"nginx_time_origin": 0,
"read": 182, // 读取条数
"send": 182, // 发送条数
"write": 182, // 入库条数
"err": 130, // 错误条数"last":
0,
"payload": [ // 根据应用版本分类的详细信息
{
"app_version": "all",
"nginx_time_origin": 0,
"read": 182,
"send": 182,
"write": 182,
"err": 130,
"last": 0,
"payload": [
{
"event": "$WebClick",
"nginx_time_origin": 0,
"read": 26,
"send": 26,
"write": 26,
"err": 0,
"last": 0,
"payload": [ // 事件的详细来源信息
{
"lib": "js",
"lib_version": "1.10.3",
"app_version": "unknown",
"lib_method": "code",
"lib_detail": "unknown","nginx_time_origin": 0,
"read": 26,
"send": 26,
"write": 26,
"err": 0,
"last": 0
}
]
}
]
}
]
}
}
}
```
<!--endsec-->埋点统计 API Ver >= 1.12.埋点统计 API Ver >= 1.12 v1.13标签api.标签api v1.16.标签api v1.17.标签API v1.13
1. 创建标签
[PUT /user_tags]
Request (application/json)
1.1. 自定义标签值标签
{
"id":0,
"cname":"",
"name":"user_tag_xianshimingcheng",
"source_type":1,//1-- 9-- 10-- 11-- 12-- 7--sql
"is_routine":true,//
"unit":"DAY",//
"dir_id":1,// ID
"data_type":"STRING",// BOOL, NUMBER, STRING, DATETIME, LIST
"cron":"0 0 0 * * ? *",// cron
"rule_content_list":[//
{
"value":"1",//
"type":"rules_relation",//
"relation":"and",// and/or
"rules":[//
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
},
{
"value":"2",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$update_time","function":"equal",
"params":[
"10"
]
}
]
}
]
}
],
"app_push_list":null,
"comment":""
}
1.2. 基础指标值标签
{
......
"rule_content_list":[
{
"type":"basic_measures",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"general",// --generalSUMMAXMINAVGuniqCount
"field":""
},
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"simple_event_rule",
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]
}
],
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
]
}
],
......
}
1.3. 首次末次特征标签
{
......
"rule_content_list":[
{
"type":"first_last_time_feature",
"measure":{
"type":"event_measure","event_name":"ClickBanner",
"aggregator":"first_time", // first_time, last_time, first_time_interval, last_time_interval
"field":"event.ClickBanner.$time"
},
"rules":
[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"simple_event_rule",
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]
}
],
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
} ]
],
......
}
1.4. 事件偏好属性标签
{
......
"rule_content_list":[
{
"type":"event_property_preferences",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"group_concat",
"field":"event.BuyGold.$city"
},
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_rule",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"rank_desc",
"field":"event.BuyGold.GoldPrice"
},
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]}
],
"params":[
20
],
"function":"most",
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
]
}
],
......
}
1.5. 行为分布结果
{
......
"rule_content_list":[
{
"type":"behavior_distribution_result",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"uniqcount", // uniqcount COUNT(DISTINCT)
"field":"",
"unit":"day" // day hour
},
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"simple_event_rule",
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]
}
],
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
]
}
],
......
}
1.6. SQL计算结果标签{
"id":0,
"cname":"5",
"name":"user_tag_biaoqian5",
"source_type":7,
"is_routine":true,
"unit":"DAY",
"dir_id":38,
"data_type":"STRING",
"cron":"0 0 0 * * ? *",
"sql":"select id as id,first_id as distinct_id, $city as value from users"
}
Response 200 (application/json)
JSONJSON
2. 获取标签元信息
[GET /user_tags/{id}]
Response 200 (application/json)
{
"id":15,
"dir_id":1,// id
"name":"user_tag_biaoqian12", //
"cname":"12", //
"user_name":"xxx@qq.com", //
"create_time":"2019-12-05 20:46:56",
// "data_type":"STRING", //
"unit":"DAY", // UIAPI
"source_type":1, // 1 rule 2 query_result 5 upload 6 import 7 SQL sql 034 6 1.13 6
"is_routine":true, // source_type rule/sql source_type Partition Partition
"status":"RUNNING",// pending running suspend
"comment":"",//
"cron":"0 0 0 * * ? *",//
"rule_content_list":[//
{
"value":"1",//
"type":"rules_relation",//
"relation":"and",// and/or
"rules":[//
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time",
"function":"equal",
"params":[
"2019-12-10 00:00:00:00"
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{"measure":{ "aggregator":
"general", "field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}
],
"failed_partition_count":0,// partition
"last_succeed_partition":{//partition
"base_time":"2019-12-18 00:00:00",// 2018-08-28 11:00:00
"start_time":"2019-12-18 01:00:26",// partition
"finished_time":"2019-12-18 01:00:30",// partition
"user_count":0, // partition
"status":"SUCCEED", // Partition newcomputingsucceedfailed
"rule_content_list":[//
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time","function":"equal",
"params":[
"2019-12-10 00:00:00:00"
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{ "aggregator":
"general", "field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}
]
},
"last_partition_info":{ "base_time":
"2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:26",
"finished_time":"2019-12-18 01:00:30",
"user_count":0,
"status":"SUCCEED",
"next_partition_base_time":"2019-12-19 00:00:00" // base_time}
}
3. 获取标签详情
[POST /user_tags/{id}/report]
Request (application/json)
{
"from_date": "2019-12-16",// 2019-12-16
"to_date": "2019-12-18",// 2019-12-18
"bucket_param": [// data_type timestamp number
0
],
"limit": 0 // value 1000
}
Response 200 (application/json)
{
"aggregate_result":{//
"series":[
"2019-12-16 00:00:00",
"2019-12-17 00:00:00",
"2019-12-18 00:00:00"
],
"rows":[
{
"by_value":"$ALL",
"partition_values":[
{
"user_count":0, //
"percent":100, //
"base_time":"2019-12-16 00:00:00", //
partition "finished_time":"2019-12-16
01:01:37"//
},
{
"user_count":0,
"percent":100,
"base_time":"2019-12-17 00:00:00",
"finished_time":"2019-12-17 01:00:34"
},
{
"user_count":0,
"percent":100,
"base_time":"2019-12-18 00:00:00",
"finished_time":"2019-12-18 01:01:02"
}
]
}
]
}
,
"non_aggregate_result":{//
"series":[
"2019-12-16 00:00:00",
"2019-12-17 00:00:00",
"2019-12-18 00:00:00"
],
"rows":[
{
"by_value":"2",
{"user_count":0,
"percent":0,
"base_time":"2019-12-16 00:00:00",
"finished_time":"2019-12-16 01:01:37"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-17 00:00:00",
"finished_time":"2019-12-17 01:00:34"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-18 00:00:00",
"finished_time":"2019-12-18 01:01:02"
}
]
}
,
{
"by_value":"1",
"partition_values":[
{
"user_count":0,
"percent":0,
"base_time":"2019-12-16 00:00:00",
"finished_time":"2019-12-16 01:01:37"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-17 00:00:00",
"finished_time":"2019-12-17 01:00:34"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-18 00:00:00",
"finished_time":"2019-12-18 01:01:02"
}
]
] }
}
}
4. 更新标签配置
[PUT /user_tags/{id}]
Request (application/json)
// Response
{
"id":21,
"dir_id":1,
"name":"user_tag_xianshimingcheng",
"cname":"",
"user_name":"xxx@qq.com",
"create_time":"2019-12-18
14:42:41", "data_type":"STRING",
"unit":"DAY",
"source_type":1,
"is_routine":true,
"status":"PENDING","comment":"",
"cron":"0 0 0 * * ? *",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
},
{
"value":"2",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$update_time",
"function":"equal",
"params":[
"10"
]
}
]
}
]
}
],
"failed_partition_count":0,
"last_succeed_partition":{
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
},
{
"value":"2",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$update_time",
"function":"equal",
"params":[
"10"
]
}
]
}
]
}
]
},
"last_partition_info":{ "base_time":"2
019-12-18 00:00:00",
"start_time":"2019-12-18 14:42:41",
"finished_time":"2019-12-18 14:42:41",
"user_count":0,
"status":"NEW",
"next_partition_base_time":"2019-12-19 00:00:00"
}
}
Response 200 (application/json)
JSONJSON
5. 删除标签
[DELETE /user_tags/{id}]6. 修改标签的调度状态
[PATCH /user_tags/{id}]
Request (application/json)
{
"status":"SUSPEND"// RUNNING SUSPEND
}
Response 200 (application/json)
JSONJSON
7. 获取所有/部分 partition
[GET /user_tags/{id}/partitions]
Request
/user_tags/{id}/partitions?from_date=2019-12-17&to_date=2019-12-18&start=1&count=10
参数名 是否必填 类型 描述
from_date 否 String
同时存在from_date 和 to_date 两个参数按照时间的范围查询
to_date 否 String 如果传递其中一个参数，系统会提示异常
没有传递参数则查询全量partition
order 否 String 可以传递desc 返回base_time倒序
start 否 Integer 查询结果截取参数，start 从1 开始计数，从start开始返回count条数据
count 否 Integer 如果数量不足这返回start开始之后的全量数据
Response 200 (application/json)
[
{
"base_time":"2019-12-17 00:00:00",
"start_time":"2019-12-17 01:00:46",
"finished_time":"2019-12-17 01:00:49",
"user_count":0,
"status":"SUCCEED",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time",
"function":"equal",
"params":[
"2019-12-10 00:00:00:00"]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}
]
},
{
"base_time":"2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:26",
"finished_time":"2019-12-18 01:00:30",
"user_count":0,
"status":"SUCCEED",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation","relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time",
"function":"equal",
"params":[
"2019-12-10 00:00:00:00"
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}]
}
]
8. 新增指定时间区间内的所有partition
[PUT /user_tags/{id}/partitions]
参数名 是否必填 类型 描述
from_date 是 String 设定时间范围，开始时间（含）
格式：2018-05-04 04:00:00 或者 2018-05-04 均可
from_data 不能晚于 to_date
to_date 是 String 设定时间范围，结束时间（含）
格式：2018-05-06 04:00:00 或者 2018-05-06 均可
参数不能晚于今天
Response 200
/user_tags/{id}/partitions?from_date=2019-12-16&to_date=2019-12-18
9. 检查标签执行状态
[GET /user_tags/{id}/status]
Request
/user_tags/{id}/status?base_time_list=2019-12-16%2000:00:00
Response 200 (application/json)
[
{
"base_time": "2019-12-16 00:00:00",
"user_count": 0,
"status": "SUCCEED",
"start_time": "2019-12-16 01:01:02",
"finished_time": "2019-12-16 01:01:02"
}
]
10. 执行一个标签的指定 partition
[PATCH /user_tags/{id}/execute]
Request
/user_tags/{id}/execute?base_time_list=2019-12-13%2000:00:0011. 获取标签完整的目录结构
[GET /user_tags/dirs]
Request
/user_tags/dirs?need_user_tag=false
参数名 是否 类 描述
必填 型
need_user_tag 否 Strin 目录结构内默认包含目录下的所有标签信息，设为 false 则只返回目录结构. 只在获取目录结构时使用
g
tag_status 否 String 标签状态，PENDING 待审批，RUNNING 正常运行，SUSPEND 已暂停
unit 否 String 标签更新周期, 取值范围：HOUR 按小时更新, DAY 每日更新，WEEK 每周更新，MONTH 每月更新，YEAR 按年更新
source_type 否 Integ 标签类型, 取值范围：1 rule 筛选规则，2 query_result 查询结果，5 upload 上传创建，6 import 外部导入，7 SQL sql创建（不使用0，
er 3，4是为了避免升级操作，用 6 是因为 1.13 的 6 没有用到）
last_partition 否 String 状态，新建标签还未执行：NEW、执行中：COMPUTING、执行成功：SUCCEED、执行失败：FAILED
_status
is_routine 否 Integ 是否例行标签或用户群 1是 0否
er
Response 200 (application/json)
[
{
"type": "DIR",
"id": 1,
"cname": "",
"is_default": true,
"items": [
{
"type": "USER_TAG",
"id": 12,
"name": "user_tag_biaoqian3",
"cname": "3",
"data_type": "STRING",
"is_permitted": false
},
{
"type": "USER_TAG",
"id": 13,
"name": "user_tag_biaoqian4",
"cname": "4",
"data_type": "STRING",
"is_permitted": false
}
]
}
,
{
"type": "DIR",
"id": 8,
"cname": "1",
"items": [
{
"type": "USER_TAG",
"id": 2,
"name": "user_tag_xxx1_1","data_type": "STRING",
"is_permitted": true
},
]
}
,
{
"type": "DIR",
"id": 9,
"cname": "2",
"items": [
{
"type": "USER_TAG",
"id": 4,
"name": "user_tag_xxx2_2",
"cname": "xxx2_2",
"data_type": "STRING",
"is_permitted": false
}
]
] }
12. 删除目录，只进行目录的删除
[DELETE /user_tags/dirs]
Request (application/json)
[ids] //ID
13. 获取标签列表
[GET /user_tags]
Request (application/json)
/user_tags?invisible=false
参数名 是否必填 类型 描述
start 否 Integer 从第几个开始取数据
count 否 Integer 取多少个
invisible 否 Boolean 是否展示隐藏目录的标签(目前是是否显示用户画像的标签 false 为不显示)
Response 200 (application/json)
[
{
"id":2,
"dir_id":8,
"name":"user_tag_xionghuacheng1_1",
"cname":"xionghuacheng1_1",
"user_name":"xionghuacheng1@qq.com"
, "create_time":"2019-11-27
12:02:24", "data_type":"STRING",
"unit":"DAY","source_type":1,
"is_routine":true,
"status":"RUNNING",
"comment":"",
"cron":"0 0 0 * * ? *",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
}
],
"failed_partition_count":0,
"last_succeed_partition":{
"base_time":"2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:59",
"finished_time":"2019-12-18 01:01:02",
"user_count":0,
"status":"SUCCEED",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1],
"function":"least",
"filters":[
]
}
]
}
]
}
]
},
"last_partition_info":{ "base_time":"
2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:59",
"finished_time":"2019-12-18 01:01:02",
"user_count":0,
"status":"SUCCEED",
"next_partition_base_time":"2019-12-19
00:00:00"
} }
]
14. 导出标签用户
[POST /reports/user_analytics/users]
Request (application/json)
{
"filter":{//
"conditions":[
{
"field":"user.user_group_fenqun24@2019-12-18 00:00:00",//
"function":"isSet"//
}
]
},
"measures":[
{
"aggregator":"count",
"field":""
}
],
"from":"user_tags",
"num_per_page":50,
"page":0,//
"all_page":false,//
"profiles":[//
"user.viplevel",
"user.$device_id_list",
"user.$name",
"user.city",
"user.province",
"user.user_group_fenqun24"
],
"limit":1000,//
"request_id":"1576665438553:312117",
"use_cache":false
}
Response 200 (application/json){
"page_num":1,//
"size":2,//
"column_name":[//
"viplevel",
"$device_id_list",
"$name",
"city",
"province",
"behaviorGender"
],
"permitted_properties":[//
"viplevel",
"$device_id_list",
"$name",
"city",
"province",
"behaviorGender"
],
"users":[//
{
"id":"-8730216594566797645",
"first_id":"00023177fb8b1c65",
"profiles":{
"$name":"",
"province":"",
"city":"",
"behaviorGender":"",
"viplevel":""
}
},
{
"id":"-8832516550883297125",
"first_id":"00144ec2ba6496ec",
"profiles":{
"$name":"",
"province":"",
"city":"",
"behaviorGender":"",
"viplevel":""
}
}
]
}
15. 导出csv格式标签用户
[POST /reports/user_analytics/users/csv]
Request (application/json)
{
"filter":{
"conditions":[
{
"field":"user.user_group_fenqun24@2019-12-18 00:00:00",
"function":"isSet"
}
]
},
"all_page":true
}
Response 200csv.标签API v1.14
创建标签
[PUT /user_tags]
Request (application/json)
自定义标签值标签
{
"id":0,
"cname":"",
"name":"user_tag_xianshimingcheng",
"source_type":1,//1-- 9-- 10-- 11-- 12-- 7--sql
"is_routine":true,//
"unit":"DAY",//
"dir_id":1,// ID
"data_type":"STRING",// BOOL, NUMBER, STRING, DATETIME, LIST
"cron":"0 0 0 * * ? *",// cron
"rule_content_list":[//
{
"value":"1",//
"type":"rules_relation",//
"relation":"and",// and/or
"rules":[//
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
},
{
"value":"2",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$update_time","function":"equal",
"params":[
"10"
]
}
]
}
]
}
],
"app_push_list":null,
"comment":""
}
基础指标值标签
{
......
"rule_content_list":[
{
"type":"basic_measures",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"general",// --generalSUMMAXMINAVGuniqCount
"field":""
},
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"simple_event_rule",
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]
}
],
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
]
}
],
......
}
首次末次特征标签
{
......
"rule_content_list":[
{
"type":"first_last_time_feature",
"measure":{
"type":"event_measure","event_name":"ClickBanner",
"aggregator":"first_time", // first_time, last_time, first_time_interval, last_time_interval
"field":"event.ClickBanner.$time"
},
"rules":
[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"simple_event_rule",
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]
}
],
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
} ]
],
......
}
事件偏好属性标签
{
......
"rule_content_list":[
{
"type":"event_property_preferences",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"group_concat",
"field":"event.BuyGold.$city"
},
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_rule",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"rank_desc",
"field":"event.BuyGold.GoldPrice"
},
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]}
],
"params":[
20
],
"function":"most",
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
]
}
],
......
}
行为分布结果
{
......
"rule_content_list":[
{
"type":"behavior_distribution_result",
"measure":{
"type":"event_measure",
"event_name":"ClickBanner",
"aggregator":"uniqcount", // uniqcount COUNT(DISTINCT)
"field":"",
"unit":"day" // day hour
},
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"simple_event_rule",
"filters":[
{
"type":"filter",
"field":"event.WithdrawCash.WithdrawDate",
"function":"greaterequal",
"params":[
"2015-04-01 00:03:00"
]
}
],
"time_function":"relative_time",
"time_params":[
"1,0,hour"
]
}
]
}
]
}
],
......
}
SQL计算结果标签{
"id":0,
"cname":"5",
"name":"user_tag_biaoqian5",
"source_type":7,
"is_routine":true,
"unit":"DAY",
"dir_id":38,
"data_type":"STRING",
"cron":"0 0 0 * * ? *",
"sql":"select id as id,first_id as distinct_id, $city as value from users"
}
Response 200 (application/json)
JSONJSON
获取标签元信息
[GET /user_tags/{id}]
Response 200 (application/json)
{
"id":15,
"dir_id":1,// id
"name":"user_tag_biaoqian12", //
"cname":"12", //
"user_name":"xxx@qq.com", //
"create_time":"2019-12-05 20:46:56",
// "data_type":"STRING", //
"unit":"DAY", // UIAPI
"source_type":1, // 1 rule 2 query_result 5 upload 6 import 7 SQL sql 034 6 1.13 6
"is_routine":true, // source_type rule/sql source_type Partition Partition
"status":"RUNNING",// pending running suspend
"comment":"",//
"cron":"0 0 0 * * ? *",//
"rule_content_list":[//
{
"value":"1",//
"type":"rules_relation",//
"relation":"and",// and/or
"rules":[//
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time",
"function":"equal",
"params":[
"2019-12-10 00:00:00:00"
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{"measure":{ "aggregator":
"general", "field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}
],
"failed_partition_count":0,// partition
"last_succeed_partition":{//partition
"base_time":"2019-12-18 00:00:00",// 2018-08-28 11:00:00
"start_time":"2019-12-18 01:00:26",// partition
"finished_time":"2019-12-18 01:00:30",// partition
"user_count":0, // partition
"status":"SUCCEED", // Partition newcomputingsucceedfailed
"rule_content_list":[//
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time","function":"equal",
"params":[
"2019-12-10 00:00:00:00"
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{ "aggregator":
"general", "field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}
]
},
"last_partition_info":{ "base_time":
"2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:26",
"finished_time":"2019-12-18 01:00:30",
"user_count":0,
"status":"SUCCEED",
"next_partition_base_time":"2019-12-19 00:00:00" // base_time}
}
获取标签详情
[POST /user_tags/{id}/report]
Request (application/json)
{
"from_date": "2019-12-16",// 2019-12-16
"to_date": "2019-12-18",// 2019-12-18
"bucket_param": [// data_type timestamp number
0
],
"limit": 0 // value 1000
}
Response 200 (application/json)
{
"aggregate_result":{//
"series":[
"2019-12-16 00:00:00",
"2019-12-17 00:00:00",
"2019-12-18 00:00:00"
],
"rows":[
{
"by_value":"$ALL",
"partition_values":[
{
"user_count":0, //
"percent":100, //
"base_time":"2019-12-16 00:00:00", //
partition "finished_time":"2019-12-16
01:01:37"//
},
{
"user_count":0,
"percent":100,
"base_time":"2019-12-17 00:00:00",
"finished_time":"2019-12-17 01:00:34"
},
{
"user_count":0,
"percent":100,
"base_time":"2019-12-18 00:00:00",
"finished_time":"2019-12-18 01:01:02"
}
]
}
]
}
,
"non_aggregate_result":{//
"series":[
"2019-12-16 00:00:00",
"2019-12-17 00:00:00",
"2019-12-18 00:00:00"
],
"rows":[
{
"by_value":"2",
{"user_count":0,
"percent":0,
"base_time":"2019-12-16 00:00:00",
"finished_time":"2019-12-16 01:01:37"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-17 00:00:00",
"finished_time":"2019-12-17 01:00:34"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-18 00:00:00",
"finished_time":"2019-12-18 01:01:02"
}
]
}
,
{
"by_value":"1",
"partition_values":[
{
"user_count":0,
"percent":0,
"base_time":"2019-12-16 00:00:00",
"finished_time":"2019-12-16 01:01:37"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-17 00:00:00",
"finished_time":"2019-12-17 01:00:34"
},
{
"user_count":0,
"percent":0,
"base_time":"2019-12-18 00:00:00",
"finished_time":"2019-12-18 01:01:02"
}
]
] }
}
}
更新标签配置
[PUT /user_tags/{id}]
Request (application/json)
// Response
{
"id":21,
"dir_id":1,
"name":"user_tag_xianshimingcheng",
"cname":"",
"user_name":"xxx@qq.com",
"create_time":"2019-12-18
14:42:41", "data_type":"STRING",
"unit":"DAY",
"source_type":1,
"is_routine":true,
"status":"PENDING","comment":"",
"cron":"0 0 0 * * ? *",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
},
{
"value":"2",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$update_time",
"function":"equal",
"params":[
"10"
]
}
]
}
]
}
],
"failed_partition_count":0,
"last_succeed_partition":{
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
},
{
"value":"2",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$update_time",
"function":"equal",
"params":[
"10"
]
}
]
}
]
}
]
},
"last_partition_info":{ "base_time":"2
019-12-18 00:00:00",
"start_time":"2019-12-18 14:42:41",
"finished_time":"2019-12-18 14:42:41",
"user_count":0,
"status":"NEW",
"next_partition_base_time":"2019-12-19 00:00:00"
}
}
Response 200 (application/json)
JSONJSON
删除标签
[DELETE /user_tags/{id}]修改标签的调度状态
[PATCH /user_tags/{id}]
Request (application/json)
{
"status":"SUSPEND"// RUNNING SUSPEND
}
Response 200 (application/json)
JSONJSON
获取所有/部分 partition
[GET /user_tags/{id}/partitions]
Request
/user_tags/{id}/partitions?from_date=2019-12-17&to_date=2019-12-18&start=1&count=10
参数名 是否必填 类型 描述
from_date 否 String
同时存在from_date 和 to_date 两个参数按照时间的范围查询
to_date 否 String 如果传递其中一个参数，系统会提示异常
没有传递参数则查询全量partition
order 否 String 可以传递desc 返回base_time倒序
start 否 Integer 查询结果截取参数，start 从1 开始计数，从start开始返回count条数据
count 否 Integer 如果数量不足这返回start开始之后的全量数据
Response 200 (application/json)
[
{
"base_time":"2019-12-17 00:00:00",
"start_time":"2019-12-17 01:00:46",
"finished_time":"2019-12-17 01:00:49",
"user_count":0,
"status":"SUCCEED",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time",
"function":"equal",
"params":[
"2019-12-10 00:00:00:00"]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}
]
},
{
"base_time":"2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:26",
"finished_time":"2019-12-18 01:00:30",
"user_count":0,
"status":"SUCCEED",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation","relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"profile_rule",
"field":"user.$first_visit_time",
"function":"equal",
"params":[
"2019-12-10 00:00:00:00"
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
},
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"event_sequence_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"steps":[
{
"event":"buy",
"filters":[
]
},
{
"event":"buy",
"filters":[
]
}
]
}
]
}
]
}]
}
]
新增指定时间区间内的所有partition
[PUT /user_tags/{id}/partitions]
参数名 是否必填 类型 描述
from_date 是 String 设定时间范围，开始时间（含）
格式：2018-05-04 04:00:00 或者 2018-05-04 均可
from_data 不能晚于 to_date
to_date 是 String 设定时间范围，结束时间（含）
格式：2018-05-06 04:00:00 或者 2018-05-06 均可
参数不能晚于今天
Response 200
/user_tags/{id}/partitions?from_date=2019-12-16&to_date=2019-12-18
检查标签执行状态
[GET /user_tags/{id}/status]
Request
/user_tags/{id}/status?base_time_list=2019-12-16%2000:00:00
Response 200 (application/json)
[
{
"base_time": "2019-12-16 00:00:00",
"user_count": 0,
"status": "SUCCEED",
"start_time": "2019-12-16 01:01:02",
"finished_time": "2019-12-16 01:01:02"
}
]
执行一个标签的指定 partition
[PATCH /user_tags/{id}/execute]
Request
/user_tags/{id}/execute?base_time_list=2019-12-13%2000:00:00获取标签完整的目录结构
[GET /user_tags/dirs]
Request
/user_tags/dirs?need_user_tag=false
参数名 是否 类 描述
必填 型
need_user_tag 否 Strin 目录结构内默认包含目录下的所有标签信息，设为 false 则只返回目录结构. 只在获取目录结构时使用
g
tag_status 否 String 标签状态，PENDING 待审批，RUNNING 正常运行，SUSPEND 已暂停
unit 否 String 标签更新周期, 取值范围：HOUR 按小时更新, DAY 每日更新，WEEK 每周更新，MONTH 每月更新，YEAR 按年更新
source_type 否 Integ 标签类型, 取值范围：1 rule 筛选规则，2 query_result 查询结果，5 upload 上传创建，6 import 外部导入，7 SQL sql创建（不使用0，
er 3，4是为了避免升级操作，用 6 是因为 1.13 的 6 没有用到）
last_partition 否 String 状态，新建标签还未执行：NEW、执行中：COMPUTING、执行成功：SUCCEED、执行失败：FAILED
_status
is_routine 否 Integ 是否例行标签或用户群 1是 0否
er
Response 200 (application/json)
[
{
"type": "DIR",
"id": 1,
"cname": "",
"is_default": true,
"items": [
{
"type": "USER_TAG",
"id": 12,
"name": "user_tag_biaoqian3",
"cname": "3",
"data_type": "STRING",
"is_permitted": false
},
{
"type": "USER_TAG",
"id": 13,
"name": "user_tag_biaoqian4",
"cname": "4",
"data_type": "STRING",
"is_permitted": false
}
]
}
,
{
"type": "DIR",
"id": 8,
"cname": "1",
"items": [
{
"type": "USER_TAG",
"id": 2,
"name": "user_tag_xxx1_1","data_type": "STRING",
"is_permitted": true
},
]
}
,
{
"type": "DIR",
"id": 9,
"cname": "2",
"items": [
{
"type": "USER_TAG",
"id": 4,
"name": "user_tag_xxx2_2",
"cname": "xxx2_2",
"data_type": "STRING",
"is_permitted": false
}
]
] }
删除目录，只进行目录的删除
[DELETE /user_tags/dirs]
Request (application/json)
[ids] //ID
获取标签列表
[GET /user_tags]
Request (application/json)
/user_tags?invisible=false
参数名 是否必填 类型 描述
start 否 Integer 从第几个开始取数据
count 否 Integer 取多少个
invisible 否 Boolean 是否展示隐藏目录的标签(目前是是否显示用户画像的标签 false 为不显示)
Response 200 (application/json)
[
{
"id":2,
"dir_id":8,
"name":"user_tag_xionghuacheng1_1",
"cname":"xionghuacheng1_1",
"user_name":"xionghuacheng1@qq.com"
, "create_time":"2019-11-27
12:02:24", "data_type":"STRING",
"unit":"DAY","source_type":1,
"is_routine":true,
"status":"RUNNING",
"comment":"",
"cron":"0 0 0 * * ? *",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1
],
"function":"least",
"filters":[
]
}
]
}
]
}
],
"failed_partition_count":0,
"last_succeed_partition":{
"base_time":"2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:59",
"finished_time":"2019-12-18 01:01:02",
"user_count":0,
"status":"SUCCEED",
"rule_content_list":[
{
"value":"1",
"type":"rules_relation",
"relation":"and",
"rules":[
{
"type":"rules_relation",
"relation":"and",
"rules":[
{
"measure":{
"aggregator":"general",
"field":"",
"type":"event_measure",
"event_name":"buy"
},
"type":"event_rule",
"time_function":"relative_time",
"time_params":[
"1 day"
],
"params":[
1],
"function":"least",
"filters":[
]
}
]
}
]
}
]
},
"last_partition_info":{ "base_time":"
2019-12-18 00:00:00",
"start_time":"2019-12-18 01:00:59",
"finished_time":"2019-12-18 01:01:02",
"user_count":0,
"status":"SUCCEED",
"next_partition_base_time":"2019-12-19
00:00:00"
} }
]
导出标签用户
[POST /reports/user_analytics/users]
Request (application/json)
{
"filter":{//
"conditions":[
{
"field":"user.user_group_fenqun24@2019-12-18 00:00:00",//
"function":"isSet"//
}
]
},
"measures":[
{
"aggregator":"count",
"field":""
}
],
"from":"user_tags",
"num_per_page":50,
"page":0,//
"all_page":false,//
"profiles":[//
"user.viplevel",
"user.$device_id_list",
"user.$name",
"user.city",
"user.province",
"user.user_group_fenqun24"
],
"limit":1000,//
"request_id":"1576665438553:312117",
"use_cache":false
}
Response 200 (application/json){
"page_num":1,//
"size":2,//
"column_name":[//
"viplevel",
"$device_id_list",
"$name",
"city",
"province",
"behaviorGender"
],
"permitted_properties":[//
"viplevel",
"$device_id_list",
"$name",
"city",
"province",
"behaviorGender"
],
"users":[//
{
"id":"-8730216594566797645",
"first_id":"00023177fb8b1c65",
"profiles":{
"$name":"",
"province":"",
"city":"",
"behaviorGender":"",
"viplevel":""
}
},
{
"id":"-8832516550883297125",
"first_id":"00144ec2ba6496ec",
"profiles":{
"$name":"",
"province":"",
"city":"",
"behaviorGender":"",
"viplevel":""
}
}
]
}
导出csv格式标签用户
[POST /reports/user_analytics/users/csv]
Request (application/json)
{
"filter":{
"conditions":[
{
"field":"user.user_group_fenqun24@2019-12-18 00:00:00",
"function":"isSet"
}
]
},
"all_page":true
}
Response 200csv查询 API..查询 API v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
查询 API 主要用于获取各种数据分析报告。
1. 调用方法
请参见 API 文档 中的调用方法描述。
2. 通用参数
2.1. 属性表达式
几乎所有的 API 都会用到属性表达式，例如按照某个属性进行过滤、分组或者聚合等等。属性包括事件属性和用户属性，事件属性使用 event.事件名.属性名的
方式，例如表示 注册渠道 这个属性的表达式如下:
event.Signup.Channel
用户属性类似，例如表示 用户性别:
user.Gender
2.2. 筛选表达式
筛选表达式同样适用于绝大多数 API，用于表示对某些事件或者用户的筛选操作，使用如下格式的 JSON 表示:
{
// conditions
"relation": "and",
//
"conditions": [{
//
"field": "event.BuyGold.$os",
//
"function": "equal",
//
"params": [
"iOS"
]
}, {
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}]
}
目前支持的操作符如下:
equal / notEqual
表示等于/不等于，对字符串、数值类型有效。如果 Params 有多个，则相当于 In 或者 Not In。例如想筛选出来自北京或者上海的用户:
{
"field": "user.$city","function": "equal",
"params": ["", ""]
}
isTrue / isFalse
只对布尔类型有效。
isSet / notSet
某个属性是否有值，对字符串、数值类型有效。
include
针对集合的操作，表示包含某个元素，例如筛选出所有喜欢苹果的用户:
{
"field": "user.FavoriteFruits",
"function": "include",
"params": ["Apple"]
}
less / greater / between：表示小于/大于/小于且大于，其中 between 是前闭后闭的区间，只对数值类型有效。例如筛选买入黄金的价格在 230
和 232 之间的所有事件:
{
"field": "event.BuyGold.GoldPrice",
"function": "between",
"params": [230, 232]
}
contain / notContain
包含或者不包含，表示字符串的部分匹配，只对字符串类型有效。
absoluteBetween / relativeBefore / relativeWithin
针对日期类型的操作符，分别表示在一个绝对日期范围/在 N 天之前/在 N 天之内。例如想筛选所有注册时间在 3 天之内的用户:
{
"field": "user.$signup_time",
"function": "relativeWithin",
"params": [3]
}
或者筛选所有在 2015-1-1~2015-1-10 注册的用户:
{
"field": "user.$signup_time",
"function": "absoluteBetween",
"params": ["2015-01-01", "2015-01-10"]
}
3. 行为分析报告
所有的分析报告均有 JSON 和 CSV 两种格式，默认是 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析报告对应的 CSV
格式的 URL 为: /events/report?format=csv 。
3.1. 事件分析报告
[POST /events/report]{
"measures":[
{
// $Anything
"event_name":"payOrder",
//
"aggregator":"uniq_count",
// "filter":
{
"conditions": [
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
]
}
}
],
//
"from_date":"2018-04-30",
//
"to_date":"2018-05-02",
// hour/day/week/month
"unit":"day",
//
"filter":{
"relation":"and",
"conditions":[
{
"field":"event.payOrder.$lib_version",
"function":"equal",
"params":[
"1.6.18"
]
},
{
"field":"event.payOrder.$lib",
"function":"equal",
"params":[
"Android"
]
}
]
},
//
"by_fields":[ "event.payOrder.$sc
reen_width",
"event.payOrder.$screen_height"
],
//
"bucket_params":{
"event.payOrder.$screen_width":[2000,3000],
"event.payOrder.$screen_height":[2000]
},
//
"detail_and_rollup":true,
//643221
"sampling_factor":64,
//
"approx":true,
//hyperloglog12
"hll_precision":12,
//“approx”true“approx_total”true“approx”false“approx_total”true
"approx_total":false,
//
"limit":1000,
//
"use_cache":true
}
{
"by_fields":[ "event.$Anything.$sc
reen_width",
"event.$Anything.$screen_height"
],
"series":[
"2018-04-30 00:00:00",
"2018-05-01 00:00:00",
"2018-05-02 00:00:00"
],
"rows":[{
"values":[
[57],
[60],
[38]
],
"by_values":[
"-INF~2000",
"-INF~2000"
]
},
{
"values":[
[7],
[7],
[2]
],
"by_values":[
"2000~3000",
"-INF~2000"
]
}
],
"num_rows": 2,
"total_rows": 2,
"report_update_time": "2018-05-02 13:51:08.356",
"data_update_time": "2018-05-02 16:03:32.000",
"data_sufficient_update_time": "2018-05-02 16:03:32.000",
"truncated": false
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/events/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"measures": [
{
"event_name": "payOrder",
"aggregator": "unique",
"filter": {
"conditions": [
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
]
}
}
],
"from_date": "2018-04-30",
"to_date": "2018-05-02",
"unit": "day",
"filter": {
"relation": "and",
"conditions": [
{
"field": "event.payOrder.$lib_version",
"function": "equal",
"params": [
"1.6.18"
]
},
{
"field": "event.payOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
]
},
"by_fields":
[ "event.payOrder.$screen_width
",
"event.payOrder.$screen_height"
],
"bucket_params":
{ "event.payOrder.$screen_width":
[
2000,
3000],
"event.payOrder.$screen_height":
[ 2000
]
},
"unit":"day",
"detail_and_rollup": true,
"sampling_factor": 64,
"approx": true,
"hll_precision": 12,
"approx_total": false,
"limit": 1000, "use_cache":
true
}
''
关键参数说明：
**aggregator: **聚合操作符，可取值为：
general:事件触发次数
unique:触发用户数
average/uniqAvg:人均次数/人均值
sum: 数值总和
max:数值最大值
min:数值最小值
avg:数值平均值
**field: **若aggregator为sum/max/min/avg，需要添加field字段，即聚合的字段名，与aggregator同级，例如：“field" :
"event.payOrder.discountAmount"
**bucket_params: **分桶条件，对数值型属性进行分组时，可以自定义分桶条件，分桶条件里所包含的属性必须全包含在分
组属性“by_fields”
**limit: **最大分组个数，如果limit较大（超过1W），建议使用stream模式下载（仅对于事件分析）。stream模式开启：添
加参数“downloadOriginalFormat” : true。如果不传入该字段，返回的分组数量将根据以下规则计算：10000 / 时间段个数
/ 指标个数，时间段个数为 from_date 和 to_date 包含多少个单位为 unit 的时间段，指标个数即 measures 数组个数
3.2. 漏斗分析报告
[POST /funnels/report]
{
// ID "funnel_id":
158,
//
"from_date": "2015-04-17",
//
"to_date": "2015-04-19",
// "filter":
{
"conditions": [
{
"field": "event.$AppStart.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
},
{
"field": "event.$AppEnd.$lib",
"function": "contain",
"params": [
"python"
]
},
{
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}
],"relation": "and"
},
//
"by_field": "event.$AppStart.$os",
// true:false:
"extend_over_end_date": true,
// id -1 /0 ”by_field” / ”by_field”
"by_field_step": -1,
//
"sampling_factor": 64,
// 0 -1 / "filter" "conditions" “field””filter_field_steps” “field”
"filter_field_steps": [
0
1
-1
]
}
在 1.13 及以上的版本中，我们支持 "from_date" 与 "to_date" 使用"秒级精度"或"天级精度"进行筛选
示例：
//
"from_date": "2015-04-17 22:00:00",
"to_date" : "2015-04-18 22:00:00",
系统将会匹配出时间范围为 2015-04-17 22:00:00.000 至 2015-04-18 22:00:00.999 的全部数据
//
"from_date": "2015-04-17",
"to_date" : "2015-04-18",
系统将会匹配出时间范围为 2015-04-17 00:00:00.000 至 2015-04-18 23:59:59.999 的全部数据
{
"date_list": [
"$ALL",
"2017-04-17",
"2017-04-18",
"2017-04-19"
],
"funnel_detail": [
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 98726,
"conversion_rate": 100,
"rows": [
{
"converted_user": 76110,
"conversion_rate": 77.09,
"wastage_user": 22616,
"median_converted_time": 1505
},
{
"converted_user": 76110,
"conversion_rate": 77.09,
"wastage_user": 22616,
"median_converted_time": 1505
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 76110,
"conversion_rate": 77.09,
"rows": [
{
"converted_user": 21266,
"conversion_rate": 27.94,
"wastage_user": 54844,
"median_converted_time": 2530
},
{
"converted_user": 21266,
"conversion_rate": 27.94,
"wastage_user": 54844,
"median_converted_time": 2530
}]
},
{
"event_name": "SubmitOrder",
"converted_user": 21266,
"conversion_rate": 27.94,
"rows": [
{
"converted_user": 17522,
"conversion_rate": 82.39,
"wastage_user": 3744,
"median_converted_time": 939
},
{
"converted_user": 17522,
"conversion_rate": 82.39,
"wastage_user": 3744,
"median_converted_time": 939
}
]
},
{
"event_name": "PayOrder",
"converted_user": 17522,
"conversion_rate": 82.39,
"rows": []
}
],
"completion_rate": 17.75,
"overview": [
[
{
"converted_user": 98726,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 76110,
"conversion_rate": 77.09,
"completion_rate": 77.09
},
{
"converted_user": 21266,
"conversion_rate": 27.94,
"completion_rate": 21.54
},
{
"converted_user": 17522,
"conversion_rate": 82.39,
"completion_rate": 17.75
}
],
[
{
"converted_user": 98726,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 76110,
"conversion_rate": 77.09,
"completion_rate": 77.09
},
{
"converted_user": 21266,
"conversion_rate": 27.94,
"completion_rate": 21.54
},
{
"converted_user": 17522,
"conversion_rate": 82.39,
"completion_rate": 17.75
}
]
]
},
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 34099,
"conversion_rate": 100,
"rows": [
{"converted_user": 26813,
"conversion_rate": 78.63,
"wastage_user": 7286,
"median_converted_time": 1537
},
{
"converted_user": 26813,
"conversion_rate": 78.63,
"wastage_user": 7286,
"median_converted_time": 1537
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 26813,
"conversion_rate": 78.63,
"rows": [
{
"converted_user": 7787,
"conversion_rate": 29.04,
"wastage_user": 19026,
"median_converted_time": 2710
},
{
"converted_user": 7787,
"conversion_rate": 29.04,
"wastage_user": 19026,
"median_converted_time": 2710
}
]
},
{
"event_name": "SubmitOrder",
"converted_user": 7787,
"conversion_rate": 29.04,
"rows": [
{
"converted_user": 6449,
"conversion_rate": 82.82,
"wastage_user": 1338,
"median_converted_time": 942
},
{
"converted_user": 6449,
"conversion_rate": 82.82,
"wastage_user": 1338,
"median_converted_time": 942
}
]
},
{
"event_name": "PayOrder",
"converted_user": 6449,
"conversion_rate": 82.82,
"rows": []
}
],
"completion_rate": 18.91,
"overview": [
[
{
"converted_user": 34099,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26813,
"conversion_rate": 78.63,
"completion_rate": 78.63
},
{
"converted_user": 7787,
"conversion_rate": 29.04,
"completion_rate": 22.84
},
{
"converted_user": 6449,
"conversion_rate": 82.82,
"completion_rate": 18.91
}
],
[
{"converted_user": 34099,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26813,
"conversion_rate": 78.63,
"completion_rate": 78.63
},
{
"converted_user": 7787,
"conversion_rate": 29.04,
"completion_rate": 22.84
},
{
"converted_user": 6449,
"conversion_rate": 82.82,
"completion_rate": 18.91
}
]
]
},
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 34445,
"conversion_rate": 100,
"rows": [
{
"converted_user": 26701,
"conversion_rate": 77.52,
"wastage_user": 7744,
"median_converted_time": 1521
},
{
"converted_user": 26701,
"conversion_rate": 77.52,
"wastage_user": 7744,
"median_converted_time": 1521
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 26701,
"conversion_rate": 77.52,
"rows": [
{
"converted_user": 7407,
"conversion_rate": 27.74,
"wastage_user": 19294,
"median_converted_time": 2594
},
{
"converted_user": 7407,
"conversion_rate": 27.74,
"wastage_user": 19294,
"median_converted_time": 2594
}
]
},
{
"event_name": "SubmitOrder",
"converted_user": 7407,
"conversion_rate": 27.74,
"rows": [
{
"converted_user": 6111,
"conversion_rate": 82.5,
"wastage_user": 1296,
"median_converted_time": 956
},
{
"converted_user": 6111,
"conversion_rate": 82.5,
"wastage_user": 1296,
"median_converted_time": 956
}
]
},
{
"event_name": "PayOrder",
"converted_user": 6111,"conversion_rate": 82.5,
"rows": []
}
],
"completion_rate": 17.74,
"overview": [
[
{
"converted_user": 34445,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26701,
"conversion_rate": 77.52,
"completion_rate": 77.52
},
{
"converted_user": 7407,
"conversion_rate": 27.74,
"completion_rate": 21.5
},
{
"converted_user": 6111,
"conversion_rate": 82.5,
"completion_rate": 17.74
}
],
[
{
"converted_user": 34445,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 26701,
"conversion_rate": 77.52,
"completion_rate": 77.52
},
{
"converted_user": 7407,
"conversion_rate": 27.74,
"completion_rate": 21.5
},
{
"converted_user": 6111,
"conversion_rate": 82.5,
"completion_rate": 17.74
}
]
]
},
{
"steps": [
{
"event_name": "ViewHomePage",
"converted_user": 33579,
"conversion_rate": 100,
"rows": [
{
"converted_user": 25271,
"conversion_rate": 75.26,
"wastage_user": 8308,
"median_converted_time": 1485
},
{
"converted_user": 25271,
"conversion_rate": 75.26,
"wastage_user": 8308,
"median_converted_time": 1485
}
]
},
{
"event_name": "ViewProduct",
"converted_user": 25271,
"conversion_rate": 75.26,
"rows": [
{
"converted_user": 6845,
"conversion_rate": 27.09,
"wastage_user": 18426,
"median_converted_time": 2469
},{
"converted_user": 6845,
"conversion_rate": 27.09,
"wastage_user": 18426,
"median_converted_time": 2469
}
]
},
{
"event_name": "SubmitOrder",
"converted_user": 6845,
"conversion_rate": 27.09,
"rows": [
{
"converted_user": 5599,
"conversion_rate": 81.8,
"wastage_user": 1246,
"median_converted_time": 928
},
{
"converted_user": 5599,
"conversion_rate": 81.8,
"wastage_user": 1246,
"median_converted_time": 928
}
]
},
{
"event_name": "PayOrder",
"converted_user": 5599,
"conversion_rate": 81.8,
"rows": []
}
],
"completion_rate": 16.67,
"overview": [
[
{
"converted_user": 33579,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 25271,
"conversion_rate": 75.26,
"completion_rate": 75.26
},
{
"converted_user": 6845,
"conversion_rate": 27.09,
"completion_rate": 20.38
},
{
"converted_user": 5599,
"conversion_rate": 81.8,
"completion_rate": 16.67
}
],
[
{
"converted_user": 33579,
"conversion_rate": 100,
"completion_rate": 100
},
{
"converted_user": 25271,
"conversion_rate": 75.26,
"completion_rate": 75.26
},
{
"converted_user": 6845,
"conversion_rate": 27.09,
"completion_rate": 20.38
},
{
"converted_user": 5599,
"conversion_rate": 81.8,
"completion_rate": 16.67
}
]
]
}
],
"by_field": "event.$Anything.$os","by_values": [
"$ALL",
"iOS"
],
"event_names":
[ "ViewHomePage
",
"ViewProduct",
"SubmitOrder",
"PayOrder"
],
"report_update_time": "2017-04-21 11:13:47.703",
"data_update_time": "2017-04-21 11:12:56.000",
"data_sufficient_update_time": "2017-04-21 11:12:56.000"
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/funnels/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary
''{ "from_date":"2015-04-
17",
"to_date":"2015-04-19",
"funnel_id":"158",
"filter":{
"conditions":[
{
"field":"event.$AppStart.$lib_version",
"function":"equal",
"params":[
"0.1.0"
]
},
{
"field":"event.$AppEnd.$libe",
"function":"equal",
"params":[
"python"
]
}
{
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}
],
"relation":"and"
},
"by_field":"event.$AppStart.$os"
}''
3.3. 留存分析报告
[POST /retentions/report]
{
//
"from_date": "2018-04-30",
//
"to_date": "2018-05-02",
// N "duration":
"7",
// "first_event":
{
//
"event_name": "login"
},
// "second_event":
{
//
"event_name": "submitOrder",
//"filter":
{ "conditions":
[
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation":"and"
}
},
//
"measures": [
{
"event_name": "payOrder",
"aggregator": "unique"
}
],
//
"user_filter":
{ "conditions":
[
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation":"and"
},
// from_date to_date
"rangeText": ""
// day/week/month
"unit": "day",
//
"extend_over_end_date": true,
// 643221
"sampling_factor": 64,
// falsetrue
"is_wastage": false,
"use_cache": true
}
{
"by_field": "",
"has_first_day": false,
"rows": [
{
"by_value": "2018-04-30",
"total_people": 95,
"cells": [
{
"people": 36,
"percent": 37.89,
// values
"values": [
0
]
},
{
"people": 6,
"percent": 6.32,
"values":
[ 5
]
}
]
},
{
"by_value": "2018-05-01",
"total_people": 91,
"cells": [
{
"people": 25,
"percent": 27.47,
"values":
[ 0
]
},
{
"people": 1,"percent": 1.1,
"values":
[ 1
]
}
]
},
{
"by_value": "2018-05-02",
"total_people": 62,
"cells": [
{
"people": 25,
"percent": 40.32,
"values":
[ 0
]
}
]
}
],
"report_update_time": "2018-05-02 17:00:21.355",
"data_update_time": "2018-05-02 16:59:43.000",
"data_sufficient_update_time": "2018-05-02 16:59:43.000",
"truncated": false
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/retentions/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"from_date": "2018-04-30",
"to_date": "2018-05-02",
"duration": "7",
"first_event": {
"event_name": "login"
},
"second_event": { "event_name":
"submitOrder", "filter": {
"conditions": [
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation": "and"
}
},
"measures": [
{
"event_name": "payOrder",
"aggregator": "unique"
}
],
"user_filter":
{ "conditions":
[
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},
"unit": "day",
"extend_over_end_date": true,
"sampling_factor": 64,
"is_wastage": false,
"use_cache": true
}
''
3.4. 分布分析报告[POST /addictions/report]
{
//
"event_name": "submitOrder",
//
"from_date": "2018-04-30",
//
"to_date": "2018-05-02",
// "filter":
{
"conditions": [
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation":"and"
},
// "user_filter":
{
"conditions": [
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation":"and"
},
// from_dateto_date
"rangeText":"",
// 643221
"sampling_factor":64,
// day/week/month
"unit": "day",
// ,times/period, period
"measure_type":"times",
//times
"result_bucket_param": [
2,
3
]
}
{
"by_field": "",
"rows": [
{
"by_value": "2018-04-30",
"total_people": 455,
"cells": [
{
"people": 436,
"percent": 95.82,
"bucket_end": 2
},
{
"people": 19,
"percent": 4.18,
"bucket_start": 2,
"bucket_end": 3
}
]
},
{
"by_value": "2018-05-01",
"total_people": 499,
"cells": [
{
"people": 484,
"percent": 96.99,
"bucket_end": 2
},
{
"people": 15,"percent": 3.01,
"bucket_start": 2,
"bucket_end": 3
}
]
},
{
"by_value": "2018-05-02",
"total_people": 280,
"cells": [
{
"people": 273,
"percent": 97.5,
"bucket_end": 2
},
{
"people": 7,
"percent": 2.5,
"bucket_start": 2,
"bucket_end": 3
}
]
}
],
"report_update_time": "2018-05-02 17:15:26.739",
"data_update_time": "2018-05-02 17:14:10.000",
"data_sufficient_update_time": "2018-05-02 17:14:10.000",
"truncated": false
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/addictions/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"event_name": "submitOrder",
"from_date": "2018-04-30",
"to_date": "2018-05-02",
"filter": {
"conditions": [
{
"field": "event.submitOrder.$lib",
"function": "equal",
"params":
[ "Androi
d"
]
}
],
"relation": "and"
},
"user_filter":
{ "conditions":
[
{
"field": "user.sex",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},
"sampling_factor": 64,
"unit": "day",
"measure_type": "times",
"result_bucket_param": [
2,
3
]
}
''
3.5. 用户路径分析报告
[POST /path/analytics/report]
{
// initial_event, termination_event"source_type": "initial_event",
// "source_event":
{
"event_name": "StartApp",
"filter": {
"conditions": [
{
"field": "event.StartApp.$wifi",
"function": "isTrue",
"params": []
}
]
}
},
"event_names":
[ "BuyBullion",
"BuyGold",
"SaleGold",
"StartApp"
],
"by_fields":
[ "event.BuyBullion.$countr
y"
],
//
"col_limit": 20,
// "row_limit":
7,
"from_date": "2017-05-01",
"to_date": "2017-05-22",
"user_filter": {},
"bucket_params": {},
"sampling_factor": 64,
"session_interval": 1200,
"use_cache": true
}
{
"nodes":
[ [
{
"id": "0_StartApp",
"event_name": "StartApp",
"times": 27336
}
],
[
{
"id": "1_StartApp",
"event_name": "StartApp",
"times": 163
},
{
"id": "1_BuyGold",
"event_name": "BuyGold",
"times": 118
},
{
"id": "1_SaleGold",
"event_name": "SaleGold",
"times": 104
},
{
"id": "1_BuyBullion_$country_3392903",
"event_name": "BuyBullion",
"times": 37
}
],
[
{
"id": "2_SaleGold",
"event_name": "SaleGold",
"times": 68
},
{
"id": "2_BuyGold",
"event_name": "BuyGold",
"times": 50
},
{
"id": "2_BuyBullion_$country_3392903",
"event_name": "BuyBullion",
"times": 18
},
{"id": "2_StartApp",
"event_name": "StartApp",
"times": 2
}
],
[
{
"id": "3_SaleGold",
"event_name": "SaleGold",
"times": 39
},
{
"id": "3_BuyGold",
"event_name": "BuyGold",
"times": 23
},
{
"id": "3_BuyBullion_$country_3392903",
"event_name": "BuyBullion",
"times": 1
}
],
[
{
"id": "4_StartApp",
"event_name": "StartApp",
"times": 1
}
]
],
"links":
[ [
{
"source": "0_StartApp",
"target": "1_wastage",
"is_wastage": true,
"times": 26914
},
{
"source": "0_StartApp",
"target": "1_StartApp",
"times": 163
},
{
"source": "0_StartApp",
"target": "1_BuyGold",
"times": 118
},
{
"source": "0_StartApp",
"target": "1_SaleGold",
"times": 104
},
{
"source": "0_StartApp",
"target": "1_BuyBullion_$country_3392903",
"times": 37
}
],
[
{
"source": "1_StartApp",
"target": "2_wastage",
"is_wastage": true,
"times": 160
},
{
"source": "1_StartApp",
"target": "2_StartApp",
"times": 2
},
{
"source": "1_StartApp",
"target": "2_BuyBullion_$country_3392903",
"times": 1
},
{
"source": "1_BuyGold",
"target": "2_wastage",
"is_wastage": true,
"times": 68
},
{
"source": "1_BuyGold","target": "2_BuyGold",
"times": 50
},
{
"source": "1_SaleGold",
"target": "2_SaleGold",
"times": 68
},
{
"source": "1_SaleGold",
"target": "2_wastage",
"is_wastage": true,
"times": 36
},
{
"source": "1_BuyBullion_$country_3392903",
"target": "2_wastage",
"is_wastage": true,
"times": 20
},
{
"source": "1_BuyBullion_$country_3392903",
"target": "2_BuyBullion_$country_3392903",
"times": 17
}
],
[
{
"source": "2_SaleGold",
"target": "3_SaleGold",
"times": 39
},
{
"source": "2_SaleGold",
"target": "3_wastage",
"is_wastage": true,
"times": 29
},
{
"source": "2_BuyGold",
"target": "3_wastage",
"is_wastage": true,
"times": 27
},
{
"source": "2_BuyGold",
"target": "3_BuyGold",
"times": 23
},
{
"source": "2_BuyBullion_$country_3392903",
"target": "3_wastage",
"is_wastage": true,
"times": 17
},
{
"source": "2_BuyBullion_$country_3392903",
"target": "3_BuyBullion_$country_3392903",
"times": 1
},
{
"source": "2_StartApp",
"target": "3_wastage",
"is_wastage": true,
"times": 2
}
],
[
{
"source": "3_SaleGold",
"target": "4_wastage",
"is_wastage": true,
"times": 38
},
{
"source": "3_SaleGold",
"target": "4_StartApp",
"times": 1
},
{
"source": "3_BuyGold",
"target": "4_wastage",
"is_wastage": true,
"times": 23},
{
"source": "3_BuyBullion_$country_3392903",
"target": "4_wastage",
"is_wastage": true,
"times": 1
}
],
[
{
"source": "4_StartApp",
"target": "5_wastage",
"is_wastage": true,
"times": 1
}
]
],
"truncate_row": [],
"truncate_col": false,
"report_update_time": "2017-05-22 11:07:40.544",
"data_update_time": "2017-05-22 11:06:54.000",
"data_sufficient_update_time": "2017-05-22 11:06:54.000"
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/path/analytics/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"source_type": "initial_event",
"source_event": {
"event_name": "StartApp",
"filter": {
"conditions": [
{
"field": "event.StartApp.$wifi",
"function": "isTrue",
"params": []
}
]
}
},
"event_names":
[ "BuyBullion",
"BuyGold",
"SaleGold",
"StartApp"
],
"by_fields":
[ "event.BuyBullion.$countr
y"
],
"col_limit": 20,
"row_limit": 7,
"from_date": "2017-05-01",
"to_date": "2017-05-22",
"user_filter": {},
"bucket_params": {},
"sampling_factor": 64,
"session_interval": 1200,
"use_cache": true
}
''
3.6. 属性分析报告
[POST /user/analytics/report]
{
"measures": [
{
"aggregator": "count",
"field": ""
}
],
"filter":
{ "conditions":
[
{
"field": "user.HasByGold","function": "isTrue",
"params": []
}
]
},
"by_fields":
[ "user.IncomeLevel
", "user.Gender"
],
"sampling_factor": null,
//
"x_axis_field": "user.IncomeLevel",
"use_cache": false
}
{
"by_fields":
[ "user.Gende
r"
],
"series":
[ "5000~10000",
"3000~5000",
"10000~20000",
"0~3000",
null
],
"rows": [
{
"values":
[ [
83169
],
[
27776
],
[
55699
],
[
27892
],
[
36106
]
],
"by_values":
[ ""
]
},
{
"values":
[ [
55363
],
[
18208
],
[
37030
],
[
18668
],
[
24090
]
],
"by_values":
[ ""
]
},
{
"values":
[ [
25864
],
[
8490
],
[
17327
],
[
8628],
[
17353
]
],
"by_values":
[ null
]
}
],
"num_rows": 3,
"report_update_time": "2017-05-22 14:16:03.595",
"data_update_time": "1970-01-01 08:00:00.000",
"data_sufficient_update_time": "1970-01-01 08:00:00.000"
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/user/analytics/report?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"measures": [
{
"aggregator": "count",
"field": ""
}
],
"filter":
{ "conditions":
[
{
"field": "user.HasByGold",
"function": "isTrue",
"params": []
}
]
},
"by_fields":
[ "user.IncomeLevel
", "user.Gender"
],
"sampling_factor": null,
"x_axis_field": "user.IncomeLevel",
"request_id": 1495433768121,
"use_cache": false
}
''
4. 用户明细查询
用户明细系列接口用于查询某一个特定分析报告中的具体用户列表，请求的大部分参数与分析报告相同，新增的参数会在每个接口里具体说明。用户列表也
支持 JSON 和 CSV 两种格式，默认式 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析的用户列表对应的 CSV 格式的
URL 为: /events/user/list?format=csv。
4.1. 事件分析用户明细报告
[POST /events/user/list]
{
"measures": [
{
"aggregator": "unique",
"event_name": "SaleGold"
}
],
"filter":
{ "conditions":
[
{
"field": "event.SaleGold.$city",
"function": "equal",
"params":
[ ""
]
},
{
"field": "event.SaleGold.$app_version","function": "equal",
"params": [
"1.7"
]
}
]
},
"by_fields":
[ "event.SaleGold.$app_version
",
"event.SaleGold.$screen_width"
],
"rollup_date": false,
"unit": "week",
// "slice_by_values":
[
"1.7",
1080
],
// ,2015818
"slice_date": "2015-08-18 00:00:00",
// true profile false id
"detail": true,
// 30
"num_per_page": 10,
//
"page":1,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1, // /
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city","$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/events/user/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"measures":[
{
"aggregator":"unique",
"event_name":"SaleGold"
}
],
"filter":{
"conditions":[
{
"field":"event.SaleGold.$city",
"function":"equal",
"params":[
"厦门市"
]
},
{
"field":"event.SaleGold.$app_version",
"function":"equal",
"params":[
"1.7"
]
}
]
},
"by_fields":[ "event.SaleGold.$app_ver
sion",
"event.SaleGold.$screen_width"
],
"rollup_date":false,
"unit":"week",
"slice_by_values":[
"1.7",
1080
],
"slice_date":"2015-08-18 00:00:00",
"detail":true,
"num_per_page":10,
"page":1,
"limit":100000,
"all_page":true
}
''
4.2. 漏斗分析用户明细报告
[POST /funnels/user/list]
{
"funnel_id": 158,
"from_date": "2015-04-17",
"to_date": "2015-07-16",
"filter": {
"conditions": [
{
"field": "event.$Anything.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
},
{
"field": "event.$Anything.$lib","function": "contain",
"params": [
"python"
]
},
{
"field": "user.Gender",
"function": "equal",
"params": [
""
]
}
],
"relation": "and"
},
"by_field": "event.SaleGold.$lib_version",
//
"slice_by_value": "0.1.0",
// "slice_step":
0,
// true false
"slice_wastage_user": false,
// true profile false id
"detail": true,
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city","$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/funnels/user/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"funnel_id":158,
"from_date":"2015-04-17",
"to_date":"2015-07-16",
"filter":{
"conditions":[
{
"field":"event.$Anything.$lib_version",
"function":"contain",
"params":[
"0.1.0"
]
},
{
"field":"event.$Anything.$lib",
"function":"contain",
"params":[
"python"
]
},
{
"field":"user.Gender",
"function":"equal",
"params":[
"男"
]
}
],
"relation":"and"
},
"by_field":"event.SaleGold.$lib_version",
"slice_by_value":"0.1.0",
"slice_step":0,
"slice_wastage_user":false,
"detail":true,
"page":1,
"num_per_page":30,
"limit":100000,
"all_page":true
}
''
4.3. 留存分析用户明细报告
[POST /retentions/user/list]
{
"first_event":
{ "event_name":
"BuyGold", "filter": {
"conditions": [
{
"field": "event.BuyGold.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
}
]
}
},
"second_event":
{ "event_name":
"StartApp"
},
//"is_wastage": false,
//
"profiles": [],
"duration": 7,
"from_date": "2015-07-21",
"to_date": "2015-07-24",
"unit": "day",
"by_field": "event.SaleGold.$lib_version",
//
"slice_by_value": "0.1.0",
// 0 null
// "slice_interval":
1,
// true profile false id
"detail": true,
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/retentions/user/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''{
"first_event":{ "event_name":"B
uyGold", "filter":{
"conditions":[
{
"field":"event.BuyGold.$lib_version",
"function":"contain",
"params":[
"0.1.0"
]
}
]
}
},
"second_event":{ "event_name":
"StartApp"
},
"is_wastage":false,
"profiles":[
],
"duration":7,
"from_date":"2015-07-21",
"to_date":"2015-07-24",
"unit":"day",
"by_field":"event.SaleGold.$lib_version",
"slice_by_value":"0.1.0",
"slice_interval":1,
"detail":true,
"page":1,
"num_per_page":30,
"limit":100000,
"all_page":true
}
''
4.4. 分布分析用户明细报告
[POST /addictions/user/list]
{
"event_name": "BuyGold",
"filter": {
"conditions": [
{
"field": "event.BuyGold.$lib_version",
"function": "contain",
"params": [
"0.1.0"
]
}
]
},
"rollup_date": false,
"from_date": "2015-04-22",
"to_date": "2015-04-22",
"unit": "day",
"by_field": "event.SaleGold.$lib_version",
//
"slice_by_value": "0.1.0",
// "slice_freq":
2, "detail":
true,
//
"page":1,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/addictions/user/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"event_name":"BuyGold",
"filter":{
"conditions":[
{
"field":"event.BuyGold.$lib_version",
"function":"contain",
"params":[
"0.1.0"
]
}
]
},
"rollup_date":false,
"from_date":"2015-04-22",
"to_date":"2015-04-22",
"unit":"day",
"by_field":"event.SaleGold.$lib_version",
"slice_by_value":"0.1.0",
"slice_freq":2,
"detail":true,"page":1,
"num_per_page":30,
"limit":100000,
"all_page":true
}
''
4.5. 用户列表明细报告
[POST /users/list]
{
"filter":
{ "conditions":
[
{
//
// ''user.fenqun1''
// ''user.birthday''
//
"field": "user.test",
"function": "isTrue"
}
]
},
"profiles": [
//
"user.$utm_source"
],
// 0 0
"page":0,
//
"num_per_page": 30,
//
"limit": 100000,
// true
"all_page": true
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/users/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"filter":{
"conditions":[
{
"field":"user.test",
"function":"isTrue"
}
]
},
"profiles":[ "user.$utm
_source"
],
"page":0,
"num_per_page":30,
"limit":100000,
"all_page":true
}
''
这个接口也可以指定要查询的用户id，这样能获取指定用户的属性信息。
{
"filter":{ "cond
itions":[
{
"field":"user.test",
"function":"isTrue"
}
]
},
"users":["1902482830", "3834577070"],
"profiles":[ "user.$
utm_source"
]
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry","Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/users/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"filter":{ "cond
itions":[
{
"field":"user.test",
"function":"isTrue"
}
]
},
"users":["1902482830", "3834577070"],
"profiles":[ "user.$
utm_source"
]
}
''
4.6. 用户路径用户明细报告
[POST /users/list]
{
"slice_element_filter": [
{
"slice_event_name": "StartApp",
"slice_by_value": "8.1"
}
],
"next_slice_element_filter": [
{
"slice_event_name": "SaleGold",
"slice_by_value": "1"
}
], //
"session_level": "0", //
"source_type": "initial_event",
"source_event": {
"event_name": "StartApp",
"filter": {
"conditions": [
{
"field": "event.StartApp.$wifi",
"function": "isTrue"
}
]
}
},
"event_names": ["BuyBullion",
"BuyGold",
"SaleGold",
"StartApp"
],
"by_fields":
[ "event.SaleGold.$wifi",
"event.StartApp.$os_version"
],
"session_interval": "1200",
"from_date": "2017-05-01",
"to_date": "2017-05-22",
"detail": true,
"col_limit": "20",
"row_limit": "7",
"sampling_factor": 64,
"is_aggregate": "false", //
"edge_type": "ALL", // WASTAGERETENTIONALL
"is_next_aggregate": "false", //
"num_per_page": 50,
"all_page": true,
"filter": {},
"use_cache": false
}
{
"users": [
{
"id": "1902482830",
"first_id": "23e3ff2a3ff1e1bc",
"second_id": "1696144579",
"profiles": {
"FavoriteFruits":
[ "Raspberry",
"Orange"
],
"$name": "", "IncomeLevel":
"3000~5000", "$city": "",
"$province": "",
"$signup_time": 1.432805251963E12,
"Gender": "",
"Age": 20.0
}
},
{
"id": "3834577070",
"first_id": "51b0fecc44b5c75b",
"second_id": "1602971488",
"profiles": {
"FavoriteFruits":
[ "Cranberry",
"Guava",
"cantaloupe"
],
"$name": "",
"IncomeLevel": "10000~20000",
"$city": "",
"$province": "",
"$signup_time": 1.432799799529E12,
"Gender": "",
"Age": 20.0
}
}
],
"size": 2,
"page_num": 1,
"column_name":[
"FavoriteFruits",
"$name",
"Age",
"Gender",
"IncomeLevel",
"$signup_time",
"$city",
"$province"
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/users/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''{
"slice_element_filter":[
{
"slice_event_name":"StartApp",
"slice_by_value":"8.1"
}
],
"next_slice_element_filter":[
{
"slice_event_name":"SaleGold",
"slice_by_value":"1"
}
],
"session_level":"0",
"source_type":"initial_event",
"source_event":{
"event_name":"StartApp",
"filter":{
"conditions":[
{
"field":"event.StartApp.$wifi",
"function":"isTrue"
}
]
}
},
"event_names":[ "BuyB
ullion", "BuyGold",
"SaleGold",
"StartApp"
],
"by_fields":[ "event.SaleGold.$wif
i", "event.StartApp.$os_version"
],
"session_interval":"1200",
"from_date":"2017-05-01",
"to_date":"2017-05-22",
"detail":true,
"col_limit":"20",
"row_limit":"7",
"sampling_factor":64,
"is_aggregate":"false",
"edge_type":"ALL",
"is_next_aggregate":"false",
"num_per_page":50,
"all_page":true,
"filter":{
},
"use_cache":false
}
''
5. 自定义查询和用户行为列表
5.1. 自定义查询
[POST /sql/query]
通过 SQL 进行自定义查询，表结构及自定义查询方法详见 自定义查询 功能的介绍。
Parameters
q: 查询的 SQL，例如 SELECT event,time,user_id FROM events LIMIT 10。
format: 可能的值包括
csv： 默 认 格 式
json：每行一个 JSON
event_json：导出可以用于直接导入的 Event Track 格式的 Json（1.*.3338 之后的版本支持）profile_json：导出可以用于直接导入的 Profile Set/Track Signup 格式的 Json（1.*.3338 之后的版本支持）
item_json: 导出可以用户直接导入神策系统的 item_set 格式的 Json（1.15.1646 及之后的版本才支持） sql：
不直接返回数据，而是翻译为一条可以直接在 Spark/Impala/Hive 里执行的 SQL
q=SELECT * FROM events LIMIT 10
format=csv
event time user_id
RechargeCash 2015-09-02 13:01:00.125336 1731174795
RechargeCash 2015-09-02 02:02:48.133002 1751664241
RechargeCash 2015-09-02 13:01:53.308174 1784316911
RechargeCash 2015-09-02 09:09:07.784417 1793667170
RechargeCash 2015-09-02 09:09:42.420781 1807294808
RechargeCash 2015-09-02 16:04:06.211421 1808422371
RechargeCash 2015-09-02 08:08:44.646672 1810351186
RechargeCash 2015-09-02 00:12:20.456509 1874214895
RechargeCash 2015-09-02 02:02:38.494175 1897237370
RechargeCash 2015-09-02 15:03:08.338102 2012805794
该接口和其它 API 的调用方式有所不同，q 参数直接用 GET/POST 参数传递即可，csv 格式返回的数据为 \t 分隔。一个使用 curl 的例子如下:
curl ''https://saasdemo.cloud.sensorsdata.cn/api/sql/query?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-X POST \
--data-urlencode "q=SELECT * FROM events LIMIT 10" \
--data-urlencode "format=csv"
注意： （1）如果查询的事件是预置事件，那么 $ 符号需要使用 \ 进行转义。 （2）如果是导出 items 表中的数据，需要保证神策系
统版本为 1.15.1646 及之后的版本。
5.2. 用户行为列表
[POST /users/event/list]
获取一个或者多个用户在某一段时间内的详细行为信息。
{
"users":
[ 8601519
0,
81952822,
87961512
],
"from_date": "2015-04-22",
"to_date": "2015-04-22",
// false users user_idtrue distinct_id
"distinct_id": false
}
{
"events": [
{
"user_id": "422337220",
"event": "SaleGold",
"time": 1432822231055,
"properties":
{ "$province": "",
"$screen_height": 640.0,
"$city": "",
"$os": "iOS",
"$screen_width": 320.0,
"$model": "iPhone 5",
"$lib_version": "0.1.0",
"$app_version": "1.3",
"$manufacturer": "Apple",
"$os_version": "7.0",
"$wifi": 1.0,
"$lib": "python",
"SaleStep": 1.0}
},
{
"user_id": "422337220",
"event": "SaleGold",
"time": 1432822232022,
"properties":
{ "$province": "",
"$screen_height": 640.0,
"$city": "",
"$os": "iOS",
"$screen_width": 320.0,
"$model": "iPhone 5",
"$lib_version": "0.1.0",
"$app_version": "1.3",
"$manufacturer": "Apple",
"$os_version": "7.0",
"$wifi": 1.0,
"$lib": "python",
"GoldPrice": 240.34,
"GoldWeight": 16153.0,
"SaleStep": 2.0
}
}
]
}
curl ''https://golddemo.cloud.sensorsdata.cn/api/users/event/list?
token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'' \
-H ''Content-Type: application/json'' \
--data-binary ''
{
"users":[
86015190,
81952822,
87961512
],
"from_date":"2015-04-22",
"to_date":"2015-04-22",
"distinct_id":false
}
''
6. 常见问题
6.1. 查询 API 提示 {"error":"没有访问权限，请检查 project 和 token"} ？
首先：检查下数据接收地址的域名是不是客户系统自己环境登录系统的域名（注意，不是数据接收地址的域名哦）
其次：检查 project 和 token 是不是同一个项目的参数
最后：检查 token 是 admin 账号下的 API Secret 还是通过自己的账号密码获取的 Access token。如果是 API Secret ，token 直接放在 url 链接后面。如
果是 Access token ，token 参数不能直接放在 url 链接后面 ，需要放在 Header 参数中，即添加参数：
-H ''sensorsdata-token: {获取的 Access token}''
具体可参考此文档：http://manual.sensorsdata.cn/sa/latest/page-1573880.html#id-.%E5%8A%9F%E8%83%BDAPIv1.13-%E8%8E%B7%E5%
8F%96ACCESS_TOKEN
6.2. 查询引擎错误
可以检查下查询的 API 接口和参数名是否对应，以及设置的参数格式是否正确。
6.3. 报错API return 422
API SQL 查询时，$ 符号需要转译
6.4. API 查询或者下载用户列表等使用后台分析服务时，504报错
服务转发配置没有配置连接超时时间或者超时时间设置较短，让客户修改超时时间即可。一般我们建议数据接收地址超时时间为 60 ，后台分析服务超时时
间为 1800。6.5. 是否可以使用查询 API 将查询结果返回到客户线上的业务用于实时分析？查询 API 的请求频
次有什么限制？
神策查询 API 只适合低频调用，相应速度取决如下两方面：
1. 实际的查询场景：如数据量、查询数据的时间范围、所用的分析模型或 SQL 的复杂度等；
2. 硬件和网络配置：如 CPU、内存、网卡、硬盘等
在查询场景和神策服务器配置匹配的前提下，神策建议 API 调用频率保持在分钟级，单次查询的数据范围在 1 万条以内，同一时间最大并发请求量不超过
10 个，以确保查询相应和神策服务性能稳定。如条件超出如上描述范围，可能出现无法响应/查询慢/甚至神策服务性能不稳定情况。
如上为神策根据历史对接经验给出，考虑到不同客户查询调用的场景各有差异，建议以实测为准，根据实际测试结果合理调整查询条件和调用频次。第三方登录.第三方登录 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
神策分析目前支持以下两种第三方登录方式：
1. OAuth2.0 登录：支持标准的 OAuth 2.0 协议，需要神策分析版本 >= 1.7。
2. LDAP 登录：支持 LDAP 协议，可以适配常见的如 OpenLDAP、AdLDAP 等 LDAP 服务，需要神策分析版本 >= 1.13。
1. 认证方式
1.1. 自动创建用户模式（默认）
默认行为，在该方式之下，第三方系统认证的用户首次登录神策时都会自动在神策分析系统中创建对应的用户，因此默认为所有通过认证的用户都有登录神
策分析的权限。
开启方式（默认就是该行为，不需要主动开启）：
monitor_tools set_config -t server -m web -n enable_oauth_auto_create_user -v true
1.2. 手动创建用户模式
开启该方式之后，必须由管理员用户手动在神策系统当中创建了同名的用户之后，该用户才能够通过第三方系统登录神策系统。
开启方式：
monitor_tools set_config -t server -m web -n enable_oauth_auto_create_user -v false
2. 权限控制
OAuth2.0 登录时，可以通过 UserInfo API 返回角色信息，该角色信息会在首次登录创建用户时生效。如果没有返回角色信息或者使用 LDAP 登录时，系统都
会使用默认的角色信息，默认为普通用户角色。
修改默认的角色信息：
monitor_tools set_config -t server -m web -n api_user_default_role -v analyst
已经登录过的用户，如果需要修改权限信息，需要由管理员用户在成员与角色管理中进行修改。OAuth2.0 登录.OAuth2.0 登录 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
神策分析从 1.6.5 版开始支持通过 OAuth2.0 进行登录，大致登录流程如下：
1. 用户打开神策分析登录页面，点击 “OAuth 登录” 按钮（仅配置后才有该按钮），浏览器会跳转到配置的登录页面（第三方登录页面，如企业内的权
限系统）
2. 用户使用该权限系统的用户名密码或其他方式完成验证登录，登录成功后，页面将跳转回神策分析页面并以权限系统上配置的用户信息给予用户在
神策分析上的权限
实现 OAuth2.0 登录有如下要求：
1. 第三方权限系统支持 OAuth 2.0 Authentication Code 方式授权
2. 第三方权限系统可以根据 Access Token 获取用户信息（用户名和在神策某个项目中的角色）
1. 配置信息
如需配置 OAuth2.0 登录，需要提供如下配置信息：
配置项 配置说明
oauth_authorize_url OAuth 2.0 的授权地址
oauth_access_token_request_uri OAuth 2.0 使用 Authentication Code 换取 Access Token 的地址
oauth_client_id OAuth 2.0 服务端为神策登录配置的应用 ID
oauth_client_secret OAuth 2.0 服务端为神策登录配置的应用密钥
oauth_redirect_uri 授权回调的 URI，即神策后端登录地址
oauth_scope 获取用户信息需要的权限列表，非必须参数
default_fetcher_request_uri 使用 Access Token 获取该用户信息的 API，即 UserInfo API
一个完整的配置示例如下：
monitor_tools set_config -t server -m web -n oauth_authorize_url -v "https://openapi.example.com/oauth/2.0
/authorize"
monitor_tools set_config -t server -m web -n oauth_client_id -v ABCDEFG1234
monitor_tools set_config -t server -m web -n oauth_redirect_uri -v ''https://SA_HOST:8107''
monitor_tools set_config -t server -m web -n oauth_client_secret -v "XYZ00000"
monitor_tools set_config -t server -m web -n oauth_access_token_request_uri -v ''https://openapi.baidu.com
/oauth/2.0/token''
monitor_tools set_config -t server -m web -n default_fetcher_request_uri -v ''https://openapi.example.com
/userinfo''
monitor_tools set_config -t server -m web -n oauth_scope -v "openid email profile"
配置完成后需要重启 web 生效：
sa_admin restart -m web
2. 登录流程
2.1. 用户点击 OAuth 登录后跳转到第三方登录页面
用户打开神策分析登录页面，点击 “OAuth 登录” 链接（仅配置后才有该按钮），浏览器会跳转到配置的登录页面（第三方登录页面，如企业内的权限系
统）:例如 OAuth Authorize Url 的地址是 https://openapi.example.com/oauth/2.0/authorize，跳转时会带上以下参数:
1. response_type: 此值固定为 code
2. client_id: OAuth Client Id，例如该值为 ABCDEFG1234
3. scope: OAuth Scope，非必须参数，值根据需求配置，例如该值为空
4. state: 服务端生成的随机码，例如该值为 RWB23NQ1
5. redirect_uri: OAuth Redirect Uri 并加上 project 和 oauth_type 两个参数，例如该值为 https://SA_HOST:8107/?
project=production&oauth_type=oauth
按样例描述最终会以如下地址访问 OAuth2 Authorize 页面：
https://openapi.example.com/oauth/2.0/authorize?
response_type=code&
client_id=ABCDEFG1234&
state=RWB23NQ1&
redirect_uri=https%3A%2F%2FSA_HOST%3A8107%2F%3Fproject%3Dproduction%26oauth_type%3Doauth
如果登录失败不需要进行回调。
2.2. 用户在第三方认证系统完成登录验证
用户使用该权限系统的用户名密码或其他方式完成验证登录，登录成功后，页面将跳转回神策分析页面:
用户登录成功后，用户的浏览器将按如下地址跳转:
HTTP/1.1 302 Found
Location: https://SA_HOST:8107/?project=production&oauth_type=oauth&code=ANXxSNjwQDugOnqe
跳转地址即 redirect_uri 加上 code 字段，值为 Authorization Code;
2.3. 获取 Access Token
第三方权限系统上配置的用户信息给予用户在神策分析上的权限:
1. 用户浏览器跳转回神策系统页面后，神策系统后端取到 Authorization Code
2. 神策系统后端通过 Authorization Code 获取 Access Token
例如 OAuth2 Token 地址为 https://openapi.example.com/oauth/2.0/token，将带上如下参数并使用 POST 方式访问:
1. grant_type: 此值固定为 authorization_code
2. code: 上面获取到的 Authorization Code，例如 ANXxSNjwQDugOnqe
3. client_id: OAuth Client Id，例如该值为 ABCDEFG1234
4. client_secret: OAuth Client Secret，例如该值为 XYZ00000
5. redirect_uri: OAuth Redirect Uri，例如该值为 https://SA_HOST:8107/?project=production&oauth_type=oauth
按样例描述最终会以如下地址访问 OAuth2 Token 地址：
https://openapi.example.com/oauth/2.0/token?
grant_type=authorization_code&
code=ANXxSNjwQDugOnqe&
client_id=ABCDEFG1234&
client_secret=XYZ00000&
redirect_uri=https%3A%2F%2FSA_HOST%3A8107%2F%3Fproject%3Dproduction%26oauth_type%3Doauth
服务端响应数据包应返回 Access Token，例如响应包为:
{
"access_token": "a6b7dbd48f731035f771b8d63f6",
"refresh_token": "385d55f8615dfd9edb7c4b5ebd",
"expires_in": 86400,
}
其中会用到的仅有 access_token 字段，该 Access Token 应该仅会使用一次。
默认情况下，获取 access_token 的请求会将所有的请求参数放在 Uri 中，如果需要将请求的参数放在 request body 中，需要修改如下配置：monitor_tools set_config -t server -m web -n oauth_token_request_impl -v param_in_request_body
2.4. 获取用户信息
神策分析将使用 Access Token 去获取 UserInfo，默认情况下神策支持两种格式的 UserInfo 接口定义：
2.4.1. 使用神策定义的 UserInfo 接口格式（默认）
例如 User Info API 地址为 https://openapi.example.com/userinfo，将带上如下参数并使用 POST 方式访问:
access_token: 上面获取到的 Access Token, 例如 a6b7dbd48f731035f771b8d63f6
project: 登录用户访问的神策项目英文名，例如 production
最终将以如下地址发起请求：
https://openapi.example.com/userinfo?
access_token=a6b7dbd48f731035f771b8d63f6&
project=production
服务端根据 Access Token 和项目名将该用户在这个项目中的用户名和权限返回给神策后端，例如：
{
"username":"xiaoming",
"user_cname":"",
"role":"analyst"
}
username 的值为用户在神策中的登录用户名，是登录时的必须字段，该值不能存在中文字符及其他特殊字符，可以为邮箱格式或纯数字；
user_cname 的值为用户在神策中的显示用户名，是可选值，如果不返回时会和 username 保持一致。
role 字段为在神策中的角色，是可选字段。role 可取值为 admin（管理员），analyst（分析师） 和guest（普通用户）, 若取其他值则按普通用户处理，用
户角色描述请见 权限管理。若返回字段有值，那么设置该用户角色为该值对应角色，然后登录；
当没有返回 role 字段时：若该用户名在神策中已存在，那么使用其之前的角色；若该用户不存在，则角色是普通用户。
如果返回的 JSON 中没有 username 字段，则认为用户不存在，即如果该用户在神策系统没有权限，直接返回空 JSON 即可。
2.4.2. 使用 OpenID 标准 UserInfo 接口格式
API 格式参考：OpenID UserInfo 接口
与神策定义的 UserInfo 接口的区别是请求是请求时不区分神策的项目信息，而且返回的 response 里面没有角色信息，例如：
{
"sub": "248289761001",
"name": "Jane Doe",
"given_name": "Jane",
"family_name": "Doe",
"preferred_username": "j.doe",
"email": "janedoe@example.com",
"picture": "http://example.com/janedoe/me.jpg"
}
神策分析会使用 preferred_username 字段作为 username，同时使用默认的角色（即普通用户）进行登录。如
需使用该格式的 UserInfo 接口，需要开启如下配置：
monitor_tools set_config -t server -m web -n use_open_id_user_info_fetcher -v true2.5. 登录成功
用户登录神策系统成功，并以 UserInfo 接口返回的用户名和角色使用神策系统LDAP 登录.LDAP 登录 v1.13
本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑
惑，请咨询您的数据咨询顾问获取一对一的协助。
神策分析从 1.13 版本开始集成了 LDAP 登录认证，大致登录流程如下：
1. 用户在神策分析系统中正常使用用户名和密码进行登录
2. 神策系统会使用用户填写的用户名和密码去后台配置的 LDAP 系统当中进行登录认证，登录成功之后用户就可以正常使用神策分析系统
3. 在 LDAP 系统中新建的用户，默认会在神策系统中自动创建
1. 配置项说明
参数 是 参数说明
否
必
填
ldap_type 是 支持的 LDAP 类型，例如：OpenLDAP、AdLDAP
ldap_url 是 LDAP 服务的地址，ldap://ip:port 格式
ldap_account 是 登录的用户名格式，常用的例如：uid=${username} 或者 ${username}@email.com 等。其中 ${username} 是必须的宏格
_pattern 式，会在登录时使用正在的用户名进行替换。
ldap_base_dn 是 LDAP Base DN，进行LDAP 用户名检索的 Base Dn。例如：ou=people,dc=example,dc=com
bind_ldap_ad 否 进行 LDAP search 是否绑定管理员账号，默认为 false。一般在 LDAP 禁止了匿名访问的时候需要设置为 true 并配置管理员信
min 息。
ldap_bind_us 否 当 LDAP 配置了禁止匿名访问的时候需要绑定的管理员账号，等同于 Bind DN。
er
ldap_bind_pa 否 当 LDAP 配置了禁止匿名访问的时候需要绑定的管理员密码
ssword
ldap_search_ 否 在 LDAP 中查找用户时是否按照指定的 filter 进行筛选
filter
ldap_email_s 否 登录后的用户名添加邮箱后缀。主要使用场景是接入 LDAP 之前已经使用了邮箱格式的用户名，接入 LDAP 之后使用的是不需
uffix 要邮箱后缀的用户名，但仍然希望登录后和之前保持是同一个账号。
2. 配置方式
2.1. 修改单个配置
在 sa_cluster 账户下执行下列 shell 命令修改单个配置项：
monitor_tools set_config -t server -m web -n -v
2.2. 删除单个配置
monitor_tools del_config -t server -m web -n -v
2.3. 查看当前所有配置项
monitor_tools get_config -t server -m web2.4. 一个完整的配置示例
monitor_tools set_config -t server -m web -n ldap_type -v OpenLDAP
monitor_tools set_config -t server -m web -n ldap_url -v ldap://123.1.2.111:389/
monitor_tools set_config -t server -m web -n ldap_account_pattern -v ''uid=${username}''
monitor_tools set_config -t server -m web -n ldap_base_dn -v ''ou=people,dc=example,dc=com''
monitor_tools set_config -t server -m web -n bind_ldap_admin -v true
monitor_tools set_config -t server -m web -n ldap_bind_user -v uid=ldap_admin
monitor_tools set_config -t server -m web -n ldap_bind_password -v xxxxxx
monitor_tools set_config -t server -m web -n ldap_search_filter -v ''(memberOf=cn=xxx,ou=people,dc=example,
dc=com)''
monitor_tools set_config -t server -m web -n ldap_email_suffix -v ''@email.com''
3. 测试方式
3.1. 方式一：使用 ldapsearch 命令行工具进行验证
ldapsearch -p -h IP -D ${ldap_bind_user} -w ${ldap_bind_password} -b ${ldap_base_dn} -x ${ldap_account_pattern}
3.2. 方式二：使用神策脚本进行验证
sh ~/sa/web/bin/run_ldap_login_test.sh "" ""
执行后通过 tail 文件 ~/sa/logs/web/ldap_test.log 查看命令执行结果。
4. 上线
测试成功后，重启 web 生效：
sa_admin restart -m web数据归档.数据归档 v1.13
1. 数据归档
数据归档，也叫冷数据转储，是指把一些过老的，访问次数很低的数据迁移归档（转储）到廉价的存储系统里，如 Amazon S3。
神策分析在 1.14 版本开始提供数据归档功能，为客户减少使用成本。
1.1. 什么时候需要数据归档
当满足如下条件时，可进行数据归档：
1. 当用户使用了较长时间的神策服务，集群中存储的数据越来越多，需要定期扩大集群的存储大小
2. 当用户使用了较长时间的神策服务，对于过老的数据，访问次数较低
1.2. 数据归档预期效果
进行数据归档之后，会有如下的预期效果：
1. 大量旧数据会存储在更低廉的存储系统，降低使用成本。
2. 转储之后不影响旧数据的查询，但查询速度会比存储在原集群中会慢一些。
3. 已进行数据归档的日期不可再进行导入。
1.3. 前期了解
目前，数据归档提供三种不同存储协议：
协议 说明 使用场景
hdfs:// hadoop 集群文件系统 若有廉价的 hdfs 存储环境，可使用此协议进行数据归档
s3a:// Amazon S3 云存储 若通过直接创建 Amazon S3 bucket 的形式建立归档文件服务器
file:// 公有云全托管式 POSIX 可以基于任意公有云(包含 AWS) 建立归档文件服务
分布式文件系统，如
JuiceFS
参考文档：
Amazon S3 官方文档
JuiceFs 官方文档
1.4. 开启功能
开启数据归档功能，请联系神策技术支持，神策技术团队会给出最合理的归档方案，并开启归档服务。
1.5. 如何删除已归档数据
如需要将已归档的数据清除，不能在 nas 盘直接删除，需要使用 数据清理工具。
删除命令不能指定事件名，否则删除数据会报错。历史归档数据删除后，已删除的数据不可再查询，且神策分析中上线至今对应的开始的日期也会
自动调整。最佳实践.最佳实践 v1.13
这个章节里，我们将从三个角度为大家呈现神策分析从最基础的获取指标数据到解决复杂问题的范例。
此外，我们一直在倾听客户意见及需求，持续迭代产品、优化功能 。所以，除了以下介绍的指标实现方法及适用的场景外，也欢迎大家深入地探索神策分
析，神策分析将持续带给大家惊喜。
功能应用示例
复杂分析场景功能应用示例事件分析功能应用示例.事件分析功能应用示例 v1.13
我们以电商一次典型的促销类活动为例，业务人员可以按以下步骤查询活动相关数据。
1. 步骤1：查询活动页面 PV
在这里，将“事件”设定为“浏览相关”，指标则设定为“总次数”。
2. 步骤2：查询活动页面 UV
如果运营人员也想查看活动页面的触发用户数。这时可以在操作上新增一个“触发用户数”指标。3. 步骤3：比较不同渠道效果
当运营人员想要比较不同渠道带来的流量时，可以点选按“渠道”查看，对前两个步骤所产生的数值进行分组查询。
4. 步骤4：设定高级筛选条件
如果想对分析结果依照特定条件进行筛选查看时，可以点选“筛选条件”。以“累积消费金额”为例，可以选择分析累积消费在“10000-20000”的消费群体。漏斗分析功能应用示例.漏斗分析功能应用示例 v1.13
以电商为例，典型的用户购买行为由以下连续的行为构成： 浏览首页、浏览商品、提交订单、支付订单。
当我们期望观察各步骤间及总体转化率，可按以下步骤进行：
1. 步骤1：新建漏斗
若想分析广东省地区的用户购买行为，首先点击“创建漏斗”按钮，并将漏斗名称命名为“电商转化漏斗”
2. 步骤2：添加第一步骤
在下拉表单中，依序创建想要分析的购买步骤。在创建漏斗的第一个步骤时，将事件点选为“浏览首页”3. 步骤3：添加筛选条件
点击“触发限制条件”按钮，在下拉选单中选择“省份”等于“广东省”4. 步骤4：添加其他步骤
重复步骤二和步骤三，为漏斗添加其他步骤，形成完整行为漏斗。
第二个步骤：将事件点选为“浏览商品”； 第三个步骤：将事件点选为“提交订单”； 第四个步骤：将事件点选为“支付订单”。
那么，这个漏斗的分析结果就可以解决使用者对于电商用户连续性行为的转化分析需求。5. 步骤5：获得转化率数据
到此，用户就可以在此漏斗转化页面进一步查看和分析整体和各步骤间的转化和流失数据。.功能应用示例 v1.13
这里，我们介绍神策分析基础分析功能的使用示例，简要说明独立使用该功能时可获取的指标数据或解决的问题。
事件分析功能应用示例
漏斗分析功能应用示例
留存分析功能应用示例
分布分析常见应用场景
间隔分析功能应用示例
用户分群功能应用示例
用户行为序列功能应用示例
自定义查询场景留存分析功能应用示例.留存分析功能应用示例 v1.13
当前，各产品获客成本飙升，增加用户黏性的重要性愈发凸显。
为评估产品更新效果或渠道推广效果，我们常常需要对同期进入产品或同期使用了产品某个功能的用户的后续行为表现进行评估，即进行断代分析（也称为
同期群分析）。
此时，我们使用神策分析的留存分析进行评估。
1. 步骤一：设置留存的初始行为及后续行为
假设我们把完成了“注册”行为的用户才视为产品的新客，且进行了“支付订单”的行为才视为用户留存。 那么，我们在神策分析的留存分析中这么设置：将用户
的初始行为设定为“注册”，后续行为设定为“支付订单的商品细节”。
2. 步骤二：获得同期群用户的留存数据
然后根据客户注册的时间按日或按月进行分组，得到同期群，观察该群体用户发生购买的留存/流失情况； 通过比较不同的同期群留存表现，可以推断初始
行为发生时段内的产品/运营/渠道动作是否对用户留存表现产生了影响。
值得一提的是，请务必将有价值的用户行为设置为后续行为，进行留存分析，才能对产品的优化和改进提供实质性指导建议。分布分析常见应用场景.分布分析常见应用场景 v1.13
以电商为例，重复购买次数是比较常用的衡量用户忠诚度的指标，下面我们将示例如何通过分布分析查看重复购买次数并进行分维度下钻。
1. 查看用户重复购买次数分布
根据以上分析结果，我们希望进一步挖掘复购率高的人群的共同特点，了解他们是否在某些维度上呈现明显集中的分布，接下来我们进行分维度下钻。
2. 按城市查看复购次数分布
在以上分析的基础上，按用户所在城市分组。
3. 按渠道查看复购次数分布在总体基础上，按用户注册时的渠道分组。
这样，我们就清晰的了解了哪个城市的，哪个渠道的用户忠诚度比较高。间隔分析功能应用示例.间隔分析功能应用示例 v1.13
这里，我们用两个不同行业产品的例子来说明间隔分析的使用场景。
1. 金融投资类产品应用示例
为激励新用户投资，金融投资类产品通常为“注册成功”的新用户发放新手红包，同时设置了多种红包发放策略（表现为发放日期不同，发放群体不同等）。
这里，我们期望获得“注册成功”到“投资成功”两个行为间的时间间隔及时长分布。
具体操作方法是：
步骤一：选择“注册成功”、“投资成功”作为间隔分析的两个目标事件，选择日期，按总体查看时间间隔及分布；
步骤二：对事件属性配置筛选条件，分析各项策略对转化时长的影响。
详细见下图：
2. 短视频类产品应用示例
假设我们认为用户完整看过一个短视频即该用户体验了产品的核心价值，那么我们选择新用户从“启动 App ”到“完成播放”所花费的时长情况作为分析对象。如
果用户普遍需要较长的时长才能完成转化，说明用户需要付出的视频筛选的成本较高，用户极有可能流失。因此我们选取新用户从“启动 App ”到“完成播 放”
的时间间隔作为优化的目标。
详细见下图：间隔分析通常是业务情况的反应，帮助我们探索可能存在的问题，而不设为直接优化的指标对象。
例如产品用户中提交订单到支付订单间隔时长中位数过长，反应出其中可能存在问题，需要结合事件分析，漏斗分析等功能定位具体问题。用户分群场景.用户分群功能应用示例 v1.13
以互联网金融网站为例，运营常见的需求包含针对具有某类特征的用户群体进行理财项目推荐。 我们通过以下几个步骤完成：
1. 步骤一：获得特定分群的用户名单
通过用户分群筛选出对基金项目和P2P项目感兴趣的风险投资偏好为激进型的用户群，如下图。
2. 步骤二：提取用户账号或手机信息实现精准营销
根据分群结果，可以提取出这类用户群体的信息，通过用户账号或者手机号为其推荐高风险高回报的P2P或者基金项目，如下图。用户行为序列功能应用示例.用户行为序列功能应用示例 v1.13
电商网站中一个典型的用户购买转化流程由如下几个事件构成: 浏览页面、浏览商品、提交订单、支付订单。电商网站常常需要分析其核心转化流程中用户流
失的原因。
我们通过以下几个步骤查看用户行为序列并最终获得结论。
1. 步骤一：创建漏斗
如下图
2. 步骤二：获得流失用户列表
我们发现用户在浏览商品后流失的比例较大，那么点击 a 处箭头可查看流失用户数，点击 b 处用户数可提取具体的用户列表信息，如下图
3. 步骤三：查看流失用户行为序列
进入用户列表，点击某个用户的id，查看当前用户的行为序列，可快速验证流失原因，如下图4. 分析结论
我们发现大量用户在反复浏览商品中，而没有产生购物行为，这说明用户没有找到真正满意的商品。 这时可以根据用户历史行为进行商品的个性化推荐或者
发放优惠券刺激其消费。自定义查询场景.自定义查询场景 v1.13
以下列举常用的使用自定义查询满足的需求：
1. 根据用户的 distinct_id 查询
直接使用 distinct_id 查询这个用户在某天的具体行为:
SELECT * FROM events WHERE distinct_id = ''wahaha'' AND date = ''2015-09-10'' LIMIT 100
2. 查询每天上午 10 点至 11 点的下单用户数
使用标准的 SQL 日期函数 EXTRACT 来取出小时信息。
SELECT date, COUNT(*) FROM events
WHERE EXTRACT(HOUR FROM time) IN (10, 11) AND event = ''SubmitOrder''
GROUP BY 1
3. 查询一段时间内的用户下单次数分布情况
首先计算每个用户的下单次数，然后使用 CASE..WHEN 语法来分组。
SELECT
CASE
WHEN c < 10 THEN ''<10''
WHEN c < 20 THEN ''<20''
WHEN c < 100 THEN ''<100''
ELSE ''>100''
END,
COUNT(*)
FROM (
SELECT user_id, COUNT(*) AS c FROM events
WHERE date BETWEEN ''2015-09-01'' AND ''2015-09-20'' AND event = ''SubmitOrder''
GROUP BY 1
)a
GROUP BY 1
4. 查询做了行为 A 而没有做行为 B 的用户数
使用 LEFT OUTER JOIN 计算差集。
SELECT a.user_id FROM (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''BuyGold''
) a
LEFT OUTER JOIN (
SELECT DISTINCT user_id FROM events WHERE date=''2015-10-1'' AND event = ''SaleGold''
) b
ON a.user_id = b.user_id
WHERE b.user_id IS NULL
5. 计算用户的使用时长
使用分析函数，根据每个用户相邻的两个事件的间隔估算累计使用时长，如果两次使用间隔超出10分钟则不计算。SELECT
user_id,
SUM(
CASE WHEN
end_time - begin_time < 600
THEN
end_time - begin_time
ELSE
0
END
) FROM
( SELECT
user_id,
EXTRACT(EPOCH FROM time) AS end_time,
LAG(EXTRACT(EPOCH FROM time), 1, NULL) OVER (PARTITION BY user_id ORDER BY time asc) AS begin_time
FROM events
WHERE date=''2015-5-1''
) a
GROUP BY 1复杂分析场景
定位商品销量变化原因
这里我们以“定位商品销量下降的原因”为例，展示如何将功能组合使用解决实际工作中遇到的复杂分析问题。
1. 分析任务
追查核心商品销量下降原因
2. 任务难点
需关注转化环节中各前向环节基本量及转化率变化，下钻定位原因
3. 神策对策
神策8大分析模型结合强大的聚合、分组、筛选功能，快速定位原因
4. 分析方法
第一步：使用事件分析，查看核心关注商品销量趋势，找出异常日期 第二步：使用漏斗分析，查看异常日期从商品详情页浏览到下单流程中重点关注环节指
标以及转化率 第三步：使用间隔分析，为漏斗合理设置窗口期时长 第四步：回到漏斗分析，定位异常环节 第五步：使用事件分析，设置商品详情页流量按
推广位来源分组查看，判断是否推广位效果导致异常 第六步：使用事件分析，查看全站流量变化趋势是否与订单量变化趋势相符
5. 分析结论
商品销量下跌的主要原因为全站流量异常，并非受推广位因素影响
6. 具体操作
选取指标：选择事件“提交订单详情”的总次数 设置筛选条件：事件属性“商品ID”等于“321332” 设置时间：选择“本月”，并按“天”查看 分析得到：7月12
日销量暴跌 跌幅74%，需追查原因
创建漏斗 设置漏斗步骤：将“浏览商品详情页”、“加入购物车”“提交订单详情”事件作为漏斗的三个步骤 添加触发限制条件：“商品ID”等于“321332"，只提取
关注商品的数据
导出数据，使用excel看总体，观察均值是否呈现较稳定的分布，取间隔时间中位数 分析得到：上线至今的数据得到人均间隔时间的中位数波动较小，取间
隔中位数的中位数1818秒，估算从该商品浏览到下单转化时间为30分钟；所以当用漏斗分析订单波动转化率时，窗口期设置为30-1个小时较为合理，用于
估算。即在分析3月2日的下单波动时，漏斗开始的日期设置为当天即可。设置日期7月12日所在一周，按天观察转化率波动 分析得到：各环节转化率并无异常，通过观察浏览商品详情页总次数变化发现，浏览商品详情页次数7月
12日下降了75%，是下单下降的主因。
选取指标：选择事件“浏览商品详情页”的总次数 设置筛选条件：事件属性“商品ID”等于“321332” 设置分组属性：按“前向来源”查看； 设置时间：选择“本
月”，并按“天”查看 分析得到：各个前来模块来源均大幅下跌，推断为网站整体流量变化导致，而非单个推广位变动导致。分别看 Web 浏览页面 总次数、App 浏览页面总次数变化趋势 Web 浏览页面总次数App 浏览页面总次数.复杂分析场景 v1.13
1. 定位商品销量变化原因
这里我们以“定位商品销量下降的原因”为例，展示如何将功能组合使用解决实际工作中遇到的复杂分析问题。
1.1. 分析任务
追查核心商品销量下降原因
1.2. 任务难点
需关注转化环节中各前向环节基本量及转化率变化，下钻定位原因
1.3. 神策对策
神策 8 大分析模型结合强大的聚合、分组、筛选功能，快速定位原因
1.4. 分析方法
1. 使用事件分析，查看核心关注商品销量趋势，找出异常日期
2. 使用漏斗分析，查看异常日期从商品详情页浏览到下单流程中重点关注环节指标以及转化率
3. 使用间隔分析，为漏斗合理设置窗口期时长
4. 回到漏斗分析，定位异常环节
5. 使用事件分析，设置商品详情页流量按推广位来源分组查看，判断是否推广位效果导致异常
6. 使用事件分析，查看全站流量变化趋势是否与订单量变化趋势相符
1.5. 分析结论
商品销量下跌的主要原因为全站流量异常，并非受推广位因素影响
1.6. 具体操作
1.6.1. 第一步：使用事件分析，查看核心关注商品销量趋势，找出异常日期
选取指标：选择事件“提交订单详情”的总次数
设置筛选条件：事件属性“商品ID”等于“321332”
设置时间：选择“本月”，并按“天”查看分析得到：7 月 12 日销量暴跌 跌幅 74%，需追查原因
1.6.2. 第二步：使用漏斗分析，查看异常日期从商品详情页浏览到下单流程中重点关注环节指标以及转化率
创建漏斗
设置漏斗步骤：将“浏览商品详情页”、“加入购物车”“提交订单详情”事件作为漏斗的三个步骤
添加触发限制条件：“商品ID”等于“321332"，只提取关注商品的数据
1.6.3. 第三步：使用间隔分析，为漏斗合理设置窗口期时长
导出数据，使用 excel 看总体，观察均值是否呈现较稳定的分布，取间隔时间中位数
分析得到：上线至今的数据得到人均间隔时间的中位数波动较小，取间隔中位数的中位数 1818 秒，估算从该商品浏览到下单转化时间为 30 分钟；所以当
用漏斗分析订单波动转化率时，窗口期设
为 30-1 个小时较为合理，用于估算。即在分析 3 月 2 日的下单波动时，漏斗开始的日期设置为当天即可。1.6.4. 第四步：回到漏斗分析，定位异常环节
设置日期 7 月 12 日所在一周，按天观察转化率波动
分析得到：各环节转化率并无异常，通过观察浏览商品详情页总次数变化发现，浏览商品详情页次数 7 月 12 日下降了 75%，是下单下降的主因。
1.6.5. 第五步：使用事件分析，设置商品详情页流量按推广位来源分组查看，判断是否推广位效果导致异常选取指标：选择事件“浏览商品详情页”的总次数
设置筛选条件：事件属性“商品ID”等于“321332”
设置分组属性：按“前向来源”查看；
设置时间：选择“本月”，并按“天”查看
分析得到：各个前来模块来源均大幅下跌，推断为网站整体流量变化导致，而非单个推广位变动导致。
1.6.6. 第六步：使用事件分析，查看全站流量变化趋势是否与订单量变化趋势相符
分别看 Web 浏览页面 总次数、App 浏览页面总次数变化趋势
Web 浏览页面总次数App 浏览页面总次数
分析得到：确定为全站流量导致该商品销量下跌，而非单个推广位因素导致常见问题.常见问题 v1.13
产品问题
数据 & 技术问题
费用&服务问题产品问题.产品问题 v1.13
1. 如何查看每日的 PV 和 UV ？
如果是 App 端产品，可使用神策的全埋点事件 App 启动事件查看每日的 PV，UV。（App 启动事件的触发时机为在开启全埋点的情况下，每次打开 App 或者
从后台唤醒 App 时，都会触发一次 App 启动事件）
如果是网页端的产品，可使用网页端全埋点事件 Web页面浏览事件查看 PV，UV。（ Web页面浏览事件的采集时机是在开启全埋点的情况下，打开页面时，
即会采集一个 Web页面浏览事件）2. 怎么查看页面停留时长？
神策预置的 Web 页面浏览／App 页面浏览/小程序页面浏览事件，默认是不采集每个页面的浏览时长。如果想分析每个页面的浏览时长，有两个办法：
1. 客户需要自定义埋点采集每个页面浏览时长属性，这样计算的结果更精确，但是埋点比较耗时。
2. 使用 Session 分析，通过 Session 的定义，大致计算出每个页面的浏览时长（大致的含义是 session 定义不同，每个事件的时长计算结果也可能不
同），然后再分析时长相关的指标。下面以 Session 分析，介绍如何分析 Web 端页面浏览时长。（App 端和小程序端的分析类似，Session 包含
的事件需要换成 App 页面浏览/小程序页面浏览事件）
首先定义一个 Session ，包含的事件为 Web 页面浏览事件，切割时间设置为 30 分钟（经验值）。
其次，按如下截图查询页面的平均访问时长3. 如何查看 App 使用时长？
神策全埋点事件 App 退出默认会采集本次访问 App 的使用时长（从 App 启动到 App 退出的访问时间间隔），可以通过查看 App 退出的事件时长均值查看
访问 App 的使用时长均值。
4. 如何创建购买转化漏斗？
选择漏斗分析模型，创建一个新的漏斗，在漏斗内选择你定义的购买转化行为事件，比如定义漏斗转化的步骤为：浏览商品详情—>加入购物车—>提交订单
详情—>支付订单详情 ，创建完成之后，即可查看到对应漏斗的转化过程。5. 为什么神策查询的数据和第三方平台/自己业务数据库统计的数据不一样？
5.1. 和第三方平台的数据对比
由于不同平台的采集数据的逻辑和计算规则可能不同，单纯只对比统计结果的意义不大。在对比神策分析的统计数据和第三方平台统计的数据进行对比时，
可先确认两个平台采集数据的逻辑和计算规则是否相同。
目前神策支持的对比平台包含 百度分析，谷歌分析，友盟。其他平台不建议对比，如需对比，需提供第三方平台的采集数据的逻辑说明、计算规则说明、以
及对应的查询条件和查询结果，让神策值班同学协助排查。
5.2. 和自己业务数据库中的数据对比
比如，神策分析采集的注册事件的用户数和客户自己业务平台的用户数对比有差异。可按如下思路查询: a.
首先确认神策分析采集的事件和客户自己业务库数据的采集逻辑是否一致，采集数据的逻辑不一致，则无法对比数据是否一致。
b.其次确认查询的计算规则和标记用户的规则是否一致，计算规则和标记用户的方式都直接影响统计结果。神策分析各指标的计算规则和用户标记方式可参
考神策的官方文档。
c.然后确认是差异的占比是多少，是否每天都有差异，以及差异是否稳定。 d.
让客户根据用户信息，查询具体哪个用户在神策系统/客户自己业务数据库中有缺失，然后再查询这个用户在神策系统中是否数据。
6. 事件分析页面为什么今天查看过去某一天的数据和昨天查看的数据不一样？原因：首先确认下是否为 App 端采集的事件数据，App 端默认会接收 10 天之内的数据。因为 App 会存在数据延迟上报的情况（比如在数据发送之前，用
户强杀了 APP，数据会先存储在本地，等下次启动 APP 时，会继续上报），如果查询 10 天之内的数据，强制刷新缓存，可能会有少量变化。
建议：可以查看下 10 天之前的数据，且第一次查询时，需点击分析页面右上角的刷新缓存按钮，更新缓存。然后再对比下不同时间查询的数据是否一致。
7. 如何识别用户是通过百度的具体哪个关键词过来的？
用户通过百度的搜索结果跳转到自己的网站主要有两种情形：
一种是通过自己购买的关键词点击推广结果（一般被称为 sem）过来，对于这种场景，我们建议在做关键词投放的时候，对于不同的关键词，在投放的
URL 上做一个区分，例如，网站首页是http://www.example.com，那么，对于关键词 keyword1，则投放的 URL 是 http://www.example.com/?
utm_source=baidu&utm_term=keyword1，在实际展现页面的时候，依然是展现首页，但是却可以从 URL 中知道用户是通过哪个关键词过来的了；
另一种，是通过自然搜索结果（一般被称为 seo）过来，由于百度在 2015 年，已经去掉了 referer 中的关键词显示，所以目前第三方并没有好的方式获得
具体跳转过来的关键词。
8. 我们在使用时，想帮助不同的同事配置不同的报表，应该如何实现？
神策分析目前提供了比较完整的权限模型，其中的管理员可以配置好数据概览并且共享给其他人。具体来说，默认帐号一共分为三类，支持自定义分类，分
别具有如下功能：
管理员：
权限管理：有“帐号管理”功能，也可以进行“报表授权”；
数据分析：所有的数据分析功能都可以使用；
概览：可以察看自己和别人共享而来的概览，创建概览，编辑自己所创建的概览；并且可以通过“概览授权”功能将概览共享给其他用户；
漏斗：管理员可以创建漏斗和删除自己的漏斗，创建的漏斗全局可见；
分析师：
数据分析：所有的数据分析功能都可以使用；
概览：可以察看自己和别人共享而来的概览，创建概览，编辑自己所创建的概览；由于没有“权限管理”功能中的“概览授权”功能，所以概
览只能自用；
漏斗：分析师可以创建漏斗和删除自己的漏斗，创建的漏斗只有自己可见；
普通用户：
概览：可以察看别人共享而来的概览；并且，概览点击进去后，只能调整时间区间，不能做其它筛选和分组的调整。技术问题.数据 & 技术问题 v1.13
1. 数据导入后怎么查看不到数据？
1.1. App/Web/小程序 端 SDK 上报数据，埋点管理页面看不到接收数据排查思路：
1. 确认数据接收地址是否是通的，可以通过浏览器中打开数据接收地址使用 /debug ,查看下浏览器中是否有“Sensors Analytics is ready to receive
your data!” 打印出来。如果不通，可以先让客户使用神策服务器的 ip 地址测试下，是否是通的，排除掉是神策服务不可用导致的数据接收不到。然
后在排查转发层导致的数据接收地址不可用。
2. 如果数据接收地址是通的，确认下神策页面查看的项目和数据接收地址中写的项目是否一致。
3. （App 端数据）如果数据地址是通的，并且查看的项目和数据地址中的项目也是一致的，确认 SDK 中使用的模式是否为 debug 模式。（注：如果
App 端使用了 debugAndtrack 模式但是埋点管理看不到数据，可以和客户确认下是否对神策的 debug 接口做了禁用处理。）
4. 建议在本地打印log，查看数据是否采集成功。
a. iOS 端本地打印数据采集日志的方式：iOS 调试日志设置方式
b. Android 端本地打印数据采集日志的方式：在 SDK 初始化之后调用 SensorsDataAPI.sharedInstance().enableLog(true);
c. Web 端本地打印数据采集日志的方式：初始化 SDK 是，添加 show_log:true （该参数和 server_url 同等级，没有设置该参数时，默认为
ture）
d. 小程序端本地打印数据采集日志的方式：初始化 SDK 是，添加 show_log:true （该参数和 server_url 同等级，没有设置该参数时，默认
为 ture）
5. 如果数据接收地址通，项目一致，非 debug 模式，仍然看不到数据，可以确认下 license 是否到期或者是数据条数超过上线导致的停止导入。
6. 如果客户使用的是 https 的数据接收地址，也可以确认下证书是否过期，如果证书过期或者证书不合法也会影响数据发送。
1.2. 服务端 SDK 上报数据，埋点管理页面看不到接收数据排查思路：
1. 确认 SDK 使用的 consumer 是 BatchConsumer 还是 ConcurrentLoggingConsumer？
2. 如果是 BatachConsumer 确认是否到达了设置的缓存条数，是否满足发送条件。
3. 如果是 BatachConsumer 并且满足了发送条件，确认数据接收地址是否可用（可参考 App 端 SDK 上报数据排查思路中第 1，2，3步）
4. 如果使用的 ConcurrentLoggingConsumer 和客户确认本地日志是否已经打印，如果没有打印和客户确认下初始化 SDK 相关配置，是否指定了文件
的写的路径，是否到达设置的缓存条数（默认到达 8k 会写日志文件）。
5. 如果使用的 ConcurrentLoggingConsumer 并且本地已经打印了日志，和客户确认是否在 SDK 的机器上安装了 LogAgent，LogAgent 配置是否
正确。LogAgent 是否有报错，可以进一步排查下 LogAgent 相关问题。LogAgent参考文档：LogAgent 导入工具
1.3. 埋点管理有接收但是事件分析或者自定义查询页面查不到数据，排查思路：
1. 可以让客户提供埋点管理截图，确认对应的埋点数据是否有报错，如果有报错，可以根据错误原因协助客户确认埋点问题
2. 如果有接收校验数据，但是没有入库。可以先确认下导入模块是否正常，只有数据入库之后才可以查询。
1.4. 埋点管理里显示数据已经入库，自定义查询页面也可以查到对应的埋点数据，但是事件分析
里查不到数据，排查思路：
1. 可以让客户先尝试强制刷新，排除因为缓存原因导致数据查不到。
2. 如果强制刷新之后，仍然看不到，可以和客户确认是否开启了抽样或者近似查询导致没有查询到。
2. 如何查看调试日志？
初始化 SDK 后，通过调用以下代码，开启调试日志，通过 SA. 关键字筛选，可点击此 链接 查看更多详情。
//
SensorsDataAPI.sharedInstance().enableLog(true);
3. 如何在神策分析中查看我测试的数据？
方式一：通过调试查看数据，可参考此 文档 配置 （如果是业务人员建议使用此方法）
方式二：在本地代码中，开启调试日志后，查看日志中的 distinct_id 字段，即为神策标识用户 ID 的字段，然后在神策分析中通过搜索用户定位到具体
的用户。如何搜索用户，可查看文档
开启了全埋点，为什么应用退到后台，没有退出事件？
在 2.0.3 版本加入了 30 秒的 session 机制，用户退出 App 到后台 30 秒的时候，才会触发退出事件， 之后再启动 App，才会触发启动事件，可点击此链
接查看更多详情。
4. 神策 SDK 支持第三方框架的采集吗？目前 SDK 支持 RN、Flutter 等第三方框架，可点击此 链接 查看更多详情。
5. 如何查看 SDK 源码及更新日志？
可在 GitHub 上查看源码及更新日志。
6. 我们应该如何接入数据？
我们提供了多种不同的数据接入方式：使用批量导入工具 batch_importer 导入历史数据；使用 log_agent 监控日志文件增量实时导入数据；或者使用各个
SDK 来实时导入数据。可以根据不同的阶段和不同的需要来选择。具体可以参考这部分的 说明。
7. 你们的产品非常强大，那么除了分析用户数据以外，还可以分析哪些其它类
型的数据呢？
A：神策分析提供的 event 和 profile 模型中，用户除了可以是互联网用户以外，还可以是其他类型的实体。例如，对于一个上门服务类型的产品来说，
除了关心用户的行为，也会关心提供服务的技师的行为。那么，对于这一类需求，可以单独部署一套神策分析，或者在已有的系统内创建一部分单
独的事件，这些事件的“用户”就是技师，而这些事件记录技师接受订单，上门服务等信息，然后据此也可以创建一系列分析技师的核心指标和 转化
漏斗等。
8. 我调试的时候程序写得有bug，数据导入错了，能不能把导错的这些数据给
删掉？
A：我们并不建议使用者因为这种原因而频繁地删除数据，当然，如果真有删除数据的需要，可以联系 Sensors Data 的技术支持人员进行操作。同
时，为了帮助用户顺利地完成数据导入，神策分析提供了以下一系列的手段：
批量导入工具提供格式校验功能；
产品界面上也提供了格式校验，并且可以根据校验的结果来创建元数据；
可以申请短时间的云版试用环境，用于调试导入程序，在试用环境使用过程中，界面上会显示导入的进度，同时也会对导入数据的错误进
行提示。因此，我们建议客户可以在云版试用环境上完成调试后，再在私有的生成环境中进行数据接入；
如果由于业务发展，导致以前有意义的事件现在不需要了，则一方面可以停止导入这类事件，另一方面可以通过神策分析提供的隐藏事件
功能，将之隐藏。
9. 有些分析和查询，我们想集成到自己的后台系统中，应该如何实现？
A：神策分析是客户完全私有的数据分析系统，因此，专门开放了 查询 API.，使用者可以在任何需要的地方获得数据，然后进行任意形式的展现和
集成。除此之外， 神策分析实质上也帮助客户搭建了一个完全私有的数据平台，客户传入的任何数据都完全开放给客户，可以通过批量和流式两种
方式进行使用，具体可以联系 Sensors Data 的技术支持人员。
10. 神策分析后台是怎么实现的？查询层用得啥？
A：神策分析主要用到了一些主流的开源社区技术，例如 Hadoop/Impala/Kafka/MySQL/Redis/jQuery/ECharts/Kudu/Parquet 等，以及一些我
们自己开发的核心组件。
神策分析主要用到了 Hadoop、Impala 等开源的分布式存储和计算套件，并结合业务的具体场景，对他们的代码做了很多针对性的修改和优化。
11. 你们的 Demo 为啥不能导入数据？
A：Demo 环境主要是给大家展示神策分析的查询、可视化、分析等方面的信息，导入的数据是我们后台模拟生成自动导入的数据。如果想尝试导入自己
的数据进行查询和分析，可以联系我们获取相应的试用环境。
12. 删除数据和隐藏事件有什么区别？
A：删除数据是真正地将数据删除了，而隐藏事件，只是在界面上将数据隐藏，并且在计算“任意事件”时，不统计这个事件。
13. 神策分析的数据是否支持修改/更新/Update？
A：神策分析中的数据分为两类：对于 Profile 类数据，由于它描述的是用户的状态，是可能发生改变的，所以我们通过 profile_set、profile_unset、profile_delete 等接口，
提供了完整的数据修改和删除的功能；
对于 Event 类数据，由于它描述的是用户在过去所做的事情，从语义上它应该是在发生后就不能够改变的，同时为了保证最好的查询性
能，目前不支持对 Event 数据的修改；
如果使用者担心由于代码错误或者数据传输错误等原因，导致传入数据有误，我们提供了如下方案来解决此类问题：
我们的数据分析师会根据客户的需求帮助客户制定完善的数据接入方案，我们的技术人员会在客户数据接入过程中提供完善的技
术支持；
我们所有的 SDK 和导入工具都提供了 debug 模式，用于数据接入过程中的调试；
我们可以为客户提供测试环境，事实上在神策分析 1.5 多 Project 功能上线后，客户可以自己开一个 Project 来进行测试；
如果在以上方案之下，依然由于某些原因导致有错误数据进入，则我们建议客户按照如下步骤先删除数据再重新导入数据：
使用 sa_clean 工具删除出错的那些 Event 在出错的时间段内的数据；
在之前出错的原始数据的基础上，完成对数据的修改，修改后再重新导入；
如果之前出错的原始数据客户没有备份，我们可以酌情协助从系统中还原导出。
14. 导入到神策分析中的属性，在导入后是否可以修改类型：
A：为了保证导入到神策分析中数据的正确性以及相应的最优的存储方案，神策分析是坚持强类型校验的，导入到神策分析中的属性类型不能修改，
但是，使用者可以按照如下方式来解决类似的需求：
首先在测试的时候应该使用单独的测试项目，尽量避免测试数据导致的类型错误。而对于测试项目则可以通过直接重置项目来还原所有类
型定义；
如果已经是正式项目了，那么可以导入一个新的属性，使用正确的类型，在属性命名上与旧的属性区分，显示名上，新属性可以使用旧属
性原本的显示名，同时隐藏旧的属性；
如果真的有非常强烈的需求，可以寻求神策分析技术支持人员的帮助，在不修改属性名的情况下进行属性类型的修改，但是无法保留该属
性的历史数据，且需要停止导入。
15. 神策分析 iOS、Android SDK 如何发送数据？是否会影响 App 的用户体
验？
A: 默认情况下，iOS、Android SDK 都采用非常保守的发送策略，以保证用户体验为核心，具体策略如下：
普通模式 (非 Debug)
1. 除 login 外，所有 track / profile_set / profile_append 等操作，均先缓存在本地，当缓存的数据量满足以下任一条
件，且当前网络为 3G/4G/Wifi 时，发送数据；
2. 本地缓存的数据量积累到一定数目（默认为 100 条）；
3. 离上次发送间隔了一定时间（默认为 15 秒）；
4. 对于 login 操作，当网络为 3G/4G/Wifi 时立即发送所有数据，否则缓存在本地；
5. 当 App 进入后台时，会尝试发送数据；
6. Android SDK 在 onPause 中尝试发送；
7. iOS SDK 在 didEnterBackground 中尝试发送；
Debug 模式
1. 对于任何操作，无论什么网络条件，都会立即发送数据，并校验返回的验证结果。
注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线
上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。
用户可以在任何时候，调用 flush 发送数据。当数据发送失败时，会继续缓存在本地，直到发送成功。当缓存数据量过多时，会删除最旧的 100 条数据，
然后再存入新的数据。其中 Android 默认缓存数据量阈值为 32MB，iOS 为 10000 条。
在 iOS 或 Android SDK 初始化后，用户可以调用 API 修改发送条件，如设定缓存累积条目数、发送时间间隔以及是否在 App 进入后台时发送数据，具体请
参考 iOS、Android SDK 的文档。费用&服务.费用&服务问题 v1.13
1. 神策分析单机版对机器配置的要求？
单机版对机器的配置有如下要求：
CPU: 4 核或更高（不含超线程），支持 SSSE3 和 AVX 指令集；
内存: 24G 或更高；
操作系统: 建议使用 CentOS 7.x 或 RHEL 7.x, 也支持满足内核版本要求的 CentOS 6.x 或 RHEL 6.x
内核版本：>= 2.6.32-674
文件系统：ext4/xfs
硬盘：机器 home 分区可用空间大于 30G，数据盘容量大于 500G，要求如下
如果是物理磁盘，做 RAID1 或更高级别的配置，以保证数据安全；
如果是云磁盘，需要 SSD 云盘或者其它吞吐在 150MB/s 以上的磁盘；
不支持与其它服务混合部署；
安装需要 root 权限。
2. 神策分析集群版对机器配置的要求？
集群版对于机器的配置有如下要求：
最少 3 个节点；
CPU: 16 核或更高（不含超线程，测试用可降至 8 核），支持 SSSE3 和 AVX 指令集；
内存: 64G 或更高；
硬盘: 每台机器 home 分区可用空间大于 30G，数据盘要求如下
如果是物理磁盘：
2 块系统盘/元数据盘：采用 RAID1 或更高级别，单盘容量 600G 以上，且顺序读写在 150 MB/s 以上，建议采用
SSD 盘；
4 块或以上数据盘：不做 RAID 或 LVM，单盘容量 2T 以上，且总吞吐在 600MB/s 以上；
如果是云磁盘：
1 块元数据盘：SSD 云盘，或其它 IOPS 在 1000 以上的磁盘，容量 600G 以上；
多块数据盘：SSD 云盘，或其它总吞吐在 600MB/s 以上的磁盘，单盘容量 1TB 以上；
操作系统: 建议使用 CentOS 7.x 或 RHEL 7.x, 也支持满足内核版本要求的 CentOS 6.x 或 RHEL 6.x
内核版本：>= 2.6.32-674
文件系统: ext4/xfs
网络：千兆（>= 5 个节点，需使用万兆），所有机器在一个交换机下，并且可以互相 ssh 登录。如果是云服务器尽量开启网络优化。
负载均衡：需要提供独立的前置负载均衡系统。
不支持与其它服务混合部署；
安装需要 root 权限。
3. 神策分析中存储用户行为数据需要多大磁盘？
按经验，1 亿条用户行为数据，在压缩前约 40GB，压缩后约 10GB。特别地，在集群版中默认使用三副本，则 1 亿条数据压缩前约 120GB，压缩
后约 30GB。
4. 使用神策分析采集用户行为数据，需要多大带宽？
服务器带宽主要受峰值在线用户数影响，数据采集服务对服务器下行带宽要求远高于上行带宽。对于 App 采集数据，默认每 15 秒压缩并上报一
次，按经验，每个用户平均每 5 秒产生一条事 件，则服务器 10Mbps 下行带宽／1Mbps 上行带宽能支持约 5 万峰值在线；对于 JavaScript 采
集，由于数据实时上报且无压缩，服务器 10Mbps 下行带宽／1Mbps 上行带宽能支持约 2 万峰值在线。
5. 是否还可以提供数据方面的技术服务？
我们在提供产品以外，还有偿提供如下的技术服务：帮助客户分解数据需求，确定核心指标；帮助客户根据数据需求理清数据源，生成规范的日志
数据；帮助客户基于我们的产品产生 Dashboard，监控各个核心指标；应客户需求，协助完成一些具体的数据分析工作。
6. 你们的 Demo 为啥不能导入数据？
A：Demo 环境主要是给大家展示神策分析的查询、可视化、分析等方面的信息，导入的数据是我们后台模拟生成自动导入的数据。如果想尝试导入自己
的数据进行查询和分析，可以联系我们获取相应的试用环境。
7. 神策分析如何保证客户数据的可靠性？
A：神策分析的集群版和单机版，都采用了各种方案，保证数据的高可靠性：集群版：
神策分析的集群版采用了分布式的存储方案，每份数据都有三倍冗余存储，保证了数据的高可靠性；
单机版：
对于采用云主机的客户，我们推荐客户使用 IaaS 提供的云磁盘（例如 UCloud 的云 SSD 盘）保证磁盘的高可靠性；
对于使用物理机器的客户，我们也建议客户采用至少 RAID10 的底层存储方案，来保证磁盘的高可靠性；
神策分析也建议，客户在应用层能够对短期的数据进行打包和备份；
结合以上的种种方案，可以相信我们为客户的数据提供了很高的可靠性。
8. 神策分析如何保证客户数据的安全性？
A：我们从私有部署和云版两种部署来回答这个问题：
私有部署：
从数据存储上，这部分数据是存储在客户自己的机器上，不存在安全顾虑；
从查询接口上，可以只对内网提供查询服务，并且也是有登录权限认证的；
从数据传输上，如果选择后端传输数据，则是内网到内网的传输，不存在安全顾虑，如果是前端埋点，我们支持 https 上报数据
然后再内网转发；
云版：
从数据存储上，我们提供的是单租户的部署方案，不同客户之间数据是完全物理隔离的；
从查询接口上，不同客户是不同的权限账号体系，也有不同的查询 token；
从数据传输上，不同客户使用不同数据上报 token，我们也支持 https 上报数据。
9. 私有部署版的神策分析应该如何选择服务器的配置：
A：神策分析支持在不同配置、不同规模的服务器上运行，而影响服务器配置选择的因素其实是非常复杂的，包括但不限于以下这些：
每天导入的数据量：例如每天约需要导入 1000w 用户行为，且往后每月约增长 20%。
历史积累的数据量：例如已经有 3 年，累计 100 亿的历史数据，且希望在一周之内完成导入。
查询分析场景：例如大部分查询分析都使用最近一个月的数据，希望能够在 10 秒内得出结果；少数查询分析使用几个月或更长的数据，
希望在一分钟内得出结果；可以接受在一些场景下使用抽样查询。
平台使用场景：例如需要和 CRM、营销推送系统等进行对接，或者需要基于神策分析的数据进行离线数据挖掘等。
神策分析的咨询顾问会根据以上信息为使用者进行详细的评估并给出最合适的服务器配置建议，而如果使用者暂时不能提供足够的信息，我们会按
照典型的使用场景来进行推荐。由于神策分析可以非常容易的支持数百万至数千亿数据规模的平滑扩容，因此我们通常会建议先用较低的配置开始
部署，之后再根据系统实际的使用情况按需随时进行调整，以最大限度的节约使用者的成本。
10. 神策分析的查询性能是由哪些因素影响的？如何提升查询性能？
A：神策分析的查询性能，是由以下一些因素影响的：
单次查询所扫描的数据量越少，查询会越快。需要注意的是，系统里面存储的总的数据量，并不会影响神策分析的查询速度，查询速度只
与该次查询所涉及的数据量有关。一般而言，一个时间横跨 40 天，涉及到 6 个事件的漏斗分析，要比只横跨 7 天，涉及 1 个事件的事件
分析要慢得多。
机器的磁盘读性能越好，查询也会越快。在不考虑应用层 cache 的情况下，神策分析的每次查询都需要从磁盘中扫描数据，因此，磁盘的
扫描性能会直接影响查询速度。
机器的 CPU 性能越好，查询也会越快。一个完整的查询，在磁盘中读取数据以后，还需要完成一些聚合类型的计算，因此，CPU 性能越
好，查询也会越快。
集群版机器数量越多，查询也会越快。在其它硬件相同的情况下，机器数量增多，相当于直接提升了磁盘的读取以及 CPU 的计算性能，因
此也会让查询更快。
而如果需要提升神策分析的查询性能，可以从以下几种方案入手：
使用抽样查询，减少单次查询扫描的数据量。可以通过抽样查询快速发现和验证一些问题，然后在需要的时候，再关闭抽样获取最准确的数据。
提升机器性能。这个包括更换更好的磁盘，换更好的 CPU，以及在集群版中直接增加机器节点数量，对于查询性能，都会有立竿见影的效果。产品更新日志.产品更新日志 v1.13
1.16 ：2019年11月21日发布
更新列表：
新特性
概览中增加公共概览功能组，建立企业数据看板的公共空间，支持授权的多个成员共同管理。
公共概览全面支持复制、排序、分组、共享设置等操作。
原「预置概览」更名为「基础数据概览」。
可通过角色权限支持成员是否可查看公共概览功能组。
支持在公共概览中单独创建的概览进行分角色、职位、个体成员进行灵活授权（使用职位授权需先在「成员管理」-「职务管理」
中创建对应职务）。
在我的概览模块支持复制当前已有概览到「公共概览」或存至「我的概览」帮助企业快速迁移已有概览到「公共概览」中。
在「单个概览」中支持添加多组描述，可拖动排序；对于长期不使用，但需要保留最后一次分析结果的概览，可使用「停止更新」来暂停
此概览的自动计算，以确保计算资源的有效释放。
新增场景库功能组，神策将沉淀的结合业务场景的分析方法「一键应用」到「公共概览」中，客户可结合所需与场景库的数据解读方法实
现快速的业务分析。
支持下载场景中对应所需的「事件设计」，为客户提供快速的事件设计方案。
支持线上自定义匹配对应事件，实现已有事件的快速应用。
成员与角色，功能模块全面实现灵活权限可配置。
在成员管理中增加「职务管理」，概览可对指定职务的成员实现动态的查看授权。
支持更细颗粒度的授权配置：
概览：「查看公告概览」、「管理公共概览」、「管理我的概览」的分别授权。
漏斗：「可用漏斗」、「管理漏斗」的分别授权。
支持「分析」、「元数据管理」、「预警管理」、「渠道管理」、「成员与角色」的分别授权。
为了确保项目的安全、稳定和数据的准确，我们在「基本设置」中，新增了「下载资源使用报告」、「平台安全设置」、「数据校验」功
能。
Admin 账号可下载「资源使用报告」，其中完整展示当前项目中功能模块、事件上报、用户使用情况明细。
Admin 账号可配置「平台安全设置」包括登录账号是否开启验证码验证、登录试错次数限制等。
有权限使用「数据校验」的成员可上传已有的「事件设计方案」后，系统自动完成与库内数据的对比，来进行数据质量的校验。
元数据中的「Session 管理」新增事件的「开始」和「退出」的事件定义。
重要变更
如果升级上来的客户，是已经使用的「预置概览」并且需要用其英文版。那么请删除已有的「预置概览」后，在场景库中重新添加「基础
分析概览」后即可正常使用。
1.15 ：2019年07月15日发布
更新列表：
新特性
概览中的预置概览模块
新增用户活跃等概览事件的配置入口。
预置概览默认为全埋点事件，另支持可调整为已有的其他事件进行统计，让预置概览更加贴合业务需求。
新增用户生命周期概览，直观可见用户构成（新用户、连续活跃用户、回流用户、沉默用户、流失用户、流入流失比），且支持
自定义配置调整。
概览中的我的概览模块
增加复制概览功能
在管理我的概览的功能，支持同时增加多个概览的可访问成员；支持批量重置概览访问成员；支持批量停止分享概览。
在概览排序功能中，支持将多张概览批量移动到指定概览组内；
新增隐藏概览组，隐藏概览组默认收起，可将不常查看的概览移动到隐藏概览。
在成员与角色模块中
账号管理、角色权限整合为「成员与角色」模块
账号类型中新增「平台账号」
企业有多个项目时，不再需要重复创建账号；
每个项目均支持创建「平台账号」，平台账号成员在不同项目中支持拥有不同角色权限；
每个项目均支持「邀请平台账号成员」，邀请后，平台账号成员支持登陆项目并进行数据分析。
在成员管理中新增「转交工作」功能，当成员工作发生变更是，支持一键转交此成员创建的所有书签、概览。
优化角色管理授权方式
在「可用事件」的授权中，增加「按标签动态授权」事件
优化「可用事件属性」权限，在分析模型中，不可使用未授权的属性进行筛选、分组查看；用户行为序列详情页均不显
示未授权的信息。
优化「可用用户属性」「可用用户群」权限，在分析模型中，不可使用未授权的属性进行筛选、分组查看；用户列表和
详情页均不显示未授权的信息。新增「基本设置」模块
支持修改项目名称
支持可以查看项目的限额、已用额度、内存、到期时间等基础信息，
支持使用更新授权、在线升级、充值项目、数据接入、推送管理、查看 API seceret 等功能。
新增「个人中心」
支持查看个人的帐号名、手机号、登陆账号、角色、邮箱等基础信息；
可查看自己在数据权限、数据分析等权限明细。当发现不能查看指定数据时，可通过个人中心查看自己是否有权限。
自定义查询新增函数 url_decode
优化
系统结构导航栏
将左侧导航优化为顶部导航，结构更加清晰。
导航包含：概览、分析、书签、用户分群、用户标签、元数据、埋点管理、基本设置、渠道管理、预警管理、成员与角色等模
块。
支持根据角色的权限，展示可以查看的模块。
书签增加管理功能
书签作为单独的模块，添加到顶部导航中。
支持查看书签被添加到哪些概览中。
支持查看书签的分析模型类型。
支持管理书签，进行编辑、删除等操作。
重要变更
必须使用多语言切换的客户，建议使用 1.14 版本。
因支持「平台账号」，所以使用 LDAP 特殊的单点登录服务的客户，在升级时，请提前跟您的客户成功经理确认是否升级后有异常。
1.14 ：2019年04月29日发布
更新列表：
新特性
推出归因分析分析模型
通过时序还原用户在产品中的行为，挖掘“运营位”与“目标事件”之间的关系
分析多个“运营位”与“目标事件”之间的贡献度，通过可视化图形展示每个“运营位”带来的贡献度
支持多种归因模型，包含：首次触点归因、末次触点归因、线性归因、位置归因和时间衰减归因 5 种归因模型
查看详细
推出全新权限系统
支持自定义用户角色，并为角色分配对应的登录账号
用户角色支持自定义配置“数据资源权限”及“功能模块使用权限”
查看详细
推出可视化全埋点功能
将 app 界面同步显示在神策分析网页端中，并标识出 app 中的元素
点击每个元素，可在界面上为其进行“重命名”，在分析模型中，使用该事件参与分析
iOS 需要 SDK 版本为 v1.11.0+，Android 需要 SDK 版本为 v3.1.0+
查看详细
对数据模型做了进一步的升级优化，从原有的 Event-User 模型升级为 Event-Item-User 模型，现在可以使用 Item 表做为 Event 事件的
易变属性的补充了，具体请参考 Item 实体；
现在可以方便地对冷数据进行数据归档了，以便在节省存储空间的同时也保存好数据资产；
优化
单机版的数据清理工具（sa_clean）现在也支持按照用户 ID（user_id / distinct_id）来删除 Event 表和 Profile 表中的数据了；
现在可以支持同时添加多个逻辑不同的预处理模块（ExtProcesser）了；
集群版的数据清理工具（sa_clean） 优化了按 Event, Lib 等条件删除的逻辑，支持删除缓存中数据；
对于数据迁移工具的可用性与效率进行了改进。
重要变更
分群 API 接口变更，不向前兼容
查看详细
分群的计算规则变更
分群表结构调整
原用户分群表新增了 base_time 字段对分群/标签的表命名规则进行了调整
查看详细
新产品
推出用户标签系统，详细请垂询神策数据工作人员
1.13 ：2018年11月19日发布
更新列表：
新特性
支持一个用户关联多个设备，极大地提升了用户关联的能力；
发布神策分析移动端掌上神策分析 1.0 版本
面向管理层，提供更好的数据解读；
提供每日「策报」，通过订阅概览，自动挖掘异常的数据，以日报的形式推送至移动端；
随时随地查看数据概览；
重新设计并实现了用户分群模块；
20 倍以上的计算性能提升；
重新设计了用户分群的 UI，可以更方便地管理分群；
可更好地帮助追踪不同分群的生命周期变化。例行分群的每次计算都有历史记录，并支持重新计算分群历史结果；
支持通过上传用户 ID 创建分群；
支持复制分群；
增强了分群规则条件的描述能力；
提供了更方便的渠道管理，可以在神策分析统一管理、追踪并分析推广效果，形成闭环
支持在产品中创建、管理渠道追踪链接；
支持更多渠道，陆续新增；
支持创建推广活动，并分析推广活动效果；
提供了自动生成的预置概览
管理员可创建一系列场景化的预置概览，通过全埋点生成用户生命周期过程所需要关注的数据指标，包括：整体概况、用户获
取、活跃与留存、事件转化、用户特征等模块；
上线客户服务中心，提供了提交服务反馈、问题的入口，支持用户以工单的方式提交工单，方便追踪问题；
全面支持 GDPR；
重要变更
预置属性 event_duration 更名为 $event_duration，且与之前版本不兼容。如果使用查询 API 、SQL 或者从 Kafka 订阅数据时使
用到此字段，需要变更字段名；
分群 API 有不兼容的变更。
1.12 ：2018年8月4日发布
更新列表：
新特性：
可在概览中添加渠道对比组件，支持对多个渠道的流量、新客占比、留存、事件转化等指标进行对比，帮助快速定位优质渠道；
可对每个概览做性能设置，包括计算精度、数据更新时间和抽样系数等，提升概览的查询体验；
可在登录后进行项目快速切换；
可在用户界面下载事件分析的全量数据；
维度字典支持多对一，针对已经存在的事件属性和用户属性，可以上传属性值的自定义多对一映射关系；
支持新的属性类型——列表，用于保存一个有序的字符串序列。原有的 LIST 类型更名为 SET 类型；若创建 SET 类型需用属性创建工具
创建后传入；
提供了数据校验工具，优化数据格式核对的效率；
微信小程序 SDK 更新，支持了分享的监测，可以对分享的次数、层级、页面等维度进行分析;
新增了支付宝小程序 SDK;
优化：
导航的体验优化调整；
概览中事件分析组件支持展示单指标分组前三的数值，留存分析组件新增以日期为横轴的留存趋势图；
留存分析新增第 0 天，用于分析在第 0 天同时进行了初始和后续行为的“共现用户”；
刷新操作调整为点击按钮刷新概览或分析页面中失效数据，按住 Shift 点击，刷新全部数据；
优化了留存导出 csv 的格式；当查询超过一定时间，提示查询进度与当前查询负载等信息，并可开启抽样或近似查询；
1.11.3954 ：2018年5月14日发布
更新列表：
新特性
指标预警可设置监控时间段，可设置指标区间；
新增监控历史查询。诊断工具中“监控历史查询”可进入。集群版默认开启，单机版需要根据配置确定是否可以开启；
优化
概览中图表（组件）与左侧导航支持新窗口打开。可右键新标签打开，或按住 Command 或 Ctrl 点击链接；
下载的文件文件名优化；
事件分析中，事件下拉框搜索支持拼音与原事件名搜索（支持元事件与虚拟事件）；
优化概览中组件的拖拽；
1.11 ：2018年3月25日发布
更新列表：
新特性
【分析模型增强】新增间隔分析模型，可分析任意两个事件之间的时间间隔分布情况和变化趋势，以优化关键事件之间的转化效率。例
如：分析首次投资到复投的间隔分布情况、注册到付费转化的间隔分布情况；
【数据概览重构】升级了数据概览的信息架构、流程、可视化能力，支持多尺寸图表、多指标表格、自定义时间筛选器等诸多特性，极大
增强了概览的可扩展性、灵活性；
【埋点管理重构】大幅优化了埋点管理的性能；时间区间统一为数据接收时间，减少误解；
【数据接入】支持通过维度表和属性扩展的能力，使用第三方的维度表对已接入的事件和属性进行扩展，极大增强对于复杂业务需求的处
理能力；
【更便捷地查看数据】可通过搜索用户，搜索用户 ID、属性值，直接查看特定用户列表和用户行为序列；
【分析能力增强】事件分析中，可对自定义指标中各子项添加属性筛选条件；
【渠道管理】可通过上传 csv、xls 格式文件批量生成 UTM 链接与短链；
【分析能力增强】LIST 类型的属性可以按“LIST 内的细项”进行统计；
【动态数据类型】可在神策技术支持协助下，修改属性类型；
【数据类型精简】取消 DATE 类型，将其作为 DATETIME 的一种格式处理；
提供了在线升级的能力；
优化
【网页热力分析】网页热力分析结果可生成二维码和链接，方便分享；
【漏斗分析】优化了漏斗的窗口期的计算能力，窗口期默认为当天内；
【APP 点击分析】持续优化 APP 点击分析功能的系统兼容性；
表格中的触发用户数可以直接查看用户列表，或快捷保存为用户分群，减少操作成本；
【虚拟事件管理】虚拟事件支持批量添加和事件排除；
【数据下载】优化了数据下载方式，可按表格中展示数据或源表数据分别下载需要的数据。
1.10 ：2017年11月15日发布
更新列表：
新特性
新增 APP 点击分析模块，可以通过可视化的方式对 APP 的用户行为进行分析；
点击分析升级为网页热力分析，新增了触达率分析图，可对用户在网页中的触达深度进行分析；优化了工具栏；
重构了事件选择的下拉菜单，支持个性化的事件二级分类、顺序调整、隐藏，可以根据业务线、产品结构等组织方式，更方便地整理事
件、指标的结构；
元数据管理可以对（虚拟）事件批量添加标签、更改显示状态，更方便地命名显示名，并优化了排序、分页等一系列体验，可以更方便的
管理事件；
元数据管理中事件可以添加备注了；
数据概览导航支持二级分类，可以更方便的整理概览的结构；
优化
可以联系神策技术支持开启分析师角色组“创建虚拟事件”、“创建分群”、“创建 Session”的权限；
大幅优化了多个分析功能中使用了用户属性时的查询性能；
漏斗、虚拟事件、 Session 和分群可查看创建信息（创建人、创建时间和修改时间）；
优化了下载 CSV 的时间格式；
强力优化了点击图的多个功能（如 a 链接里有多层嵌套，input 元素自定义采集，对自动采集的元素自定义是否采集，map/area 的采集支
持，优化选择器，等多个功能）；
渠道来源优化、单页面时候手动发送 $pageview 等等多个小功能的优化。
兼容性改动HdfsImporter 导入工具不再兼容直接使用 hadoop jar 命令运行的方式；
1.9 ：2017年8月19日发布
更新列表：
新功能：
可以对重点指标设置预警，当指标达到设定的某一绝对或相对值后，触发提醒通知责任人，支持小时、天等级别的实时监控；
增强了事件分析的对比能力，可对任意一个指标添加任意筛选条件，同时对比相同事件的不同维度指标；
增强了留存分析的分析能力，除了统计留存人数之外，还可以统计如消费总金额、人均消费额、停留总时长等更多指标，并可导出对应格
式的 CSV；
编辑漏斗时可另存为新漏斗，支持快速复制漏斗；
现在可以对接 AppsFlyer 了，从而使得渠道追踪支持多达数千家海内外投放渠道；
优化：
事件分析分组值过多时有了友好提醒，准确描述数据情况；
数据导入出现延时有了友好提醒，方便更及时了解数据延迟情况；
页面出现异常时有了更详细的报错信息，方便用户向神策技术支持提供问题定位信息，提高定位问题的效率；
版本成功更新后有了友好提醒；
点击分析新增“返回上一页”按钮，返回上一页无需通过浏览器进行后退操作；
点击分析刷新数据按钮可拖动，解决遮盖数据问题；
漏斗步骤前新增了步骤数表示；
优化了表格分页导航设计；
实时导入数据增加了对“用户ID”的说明；
优化了概览发送邮件的测试发送时的体验；
优化了用户行为序列的部分界面。
1.8 ：2017年7月21日发布
更新列表：
新功能：
私有部署单机版的架构进行了整体重构，为今后单机版无缝扩展为集群版打下基础；
iOS 和 Android 的全埋点功能兼容性大大提高，对于自定义控件、Fragment、RN 框架等有了更好的支持；
产品现在有了英文界面了；
现在通过邮件发送概览可以在界面上进行配置了；
时间类型的属性进行分桶时，有了更多的选择，不仅可以选择分钟、季度等，还可以选择按照时段汇总进行分桶；
漏斗分析按分组查看时，表格里面可以展开分组按日期、步骤查看；
iOS 和 Anroid SDK 的本地缓存改用 ContentProvider，有效的处理了多进程访问的问题；
大大增强了客户端 SDK 中对混合开发模式下 H5 与 App 的打通能力；
现在可以开启由服务端来判断某个用户 ID 是否是新用户了；
创建漏斗时可以选择前后步骤之间的关联属性了；
现在可以支持通过广点通进行分发的效果追踪了；
现在构建渠道追踪链接时可以提供短链的支持了；
现在部分可以累加的指标支持累积图了；
JS SDK 在进行流量采集时，会有字段用以区分流量来源类型是付费广告流量、自然搜索流量、社交网站流量、引荐流量和直接流量，并
且对于付费广告流量和部分可以解析的搜索流量，则会将搜索关键词也进行记录；
对于 触发用户数、人均次数 等指标，现在提供更加快速的非精确预估算法了；
现在各个客户端 SDK 都增加了 CRC 校验，可以有效甄别网络传输过程中的数据错误；
优化：
对 HDFSImporter 导入单天数据的导入速度进行了优化；
多项目情况下的登录界面体验进行了优化；
多指标、合计等情况下的查询效率进行了优化；
维度字典现在可以下载查看了；
对虚拟事件较多的情况下的编辑体验进行了优化；
浏览器窗口放大缩小时的体验进行了优化；
JS SDK 现在可以自定义埋点信息，在埋点管理里面进行追踪和管理；
在分组和筛选时可以更好地区分事件、用户和 Session 三种不同的属性了；
对于下载的查询结果表格的内容进行了优化；
漏斗分析进行趋势查看、对比时表格可读性进行了优化；
查看实时导入数据的界面上，现在可以全局进行格式 Format 了；
可视化方面进行了较多优化，包括饼图改为环图、线图柱图比例调整等；
点击图的体验进行了大幅优化；
分析师权限的账号可以查看元数据了。
1.7 ：2017年3月30日发布
更新列表：
新功能：
iOS、安卓、JS SDK 现在 Autotrack 功能做了进一步的强化，可以默认采集页面上各个元素的交互行为了；增加了 Web 页面的点击分析功能；
对漏斗分析功能进行了重构，例如，现在可以按照日期查询转化率变化曲线，可以对比两个不同分组值下的漏斗转化情况，现在对事件属
性进行筛选和分组时以实际转化的事件的属性为准，在漏斗转化的前后多个步骤中支持设置一个转化 ID 作为转化的条件等；
现在可以将数据概览的内容通过邮件发送到指定邮箱了，暂时需要在后台通过工具进行配置；
对权限体系重新进行了梳理，例如，现在分析师可以分享自己的概览，并且查看事件和属性的元数据了；
时间和日期类型的属性进行筛选时，现在可以设置与事件发生时间的相对关系了；
分析数据时提供了数据及时性提示，鼠标浮动在强制刷新按钮上会给出相应提示，以方便使用者更好地解读分析结果；
渠道链接生成工具，现在可以批量生成链接了；
优化点：
优化了数据概览的缓存策略，以便改进察看数据概览的体验；
优化了判断新增用户的策略，以规避部分由于用户卸载重装 App 带来的识别错误；
集群版的 Profile 导入时效性进行了显著优化；
放开了留存分析对于初始日期的限制；
留存分析中流失用户的定义重新进行了梳理，现在是连续多“天”没有发生后续事件才认为是流失用户；
对用户分群功能进行了优化，在用户“做过”的情况下，可以添加用户“没做过”的条件了，同时也支持只有用户属性筛选的用户分群了；
分析功能在有书签时，展现的标题以书签名称为准；
现在概览的顺序可以全局调整了；
对筛选框的拷⻉、粘贴的体验进行了优化；
现在安卓、iOS 和 JS SDK 在 Debug 模式下，改用弹窗来对错误进行提示；
现在安卓和 iOS SDK 默认也会把设备 ID 作为一个属性进行采集了；
优化了在有分组的情况下，合计和非合计分组展示不一致的问题；
事件分析功能中，当含有多个指标时，对两个坐标轴与折线的对应关系可以进行更进一步的设置了；
优化各模块中事件选择下拉框的展示性能，避免事件过多时出现卡顿现象；
创建 Session 现在支持切分粒度到秒了；
支持系统在浏览器隐私模式下使用了；
表格左侧维度列现在是固定的了；
推送功能增加了所支持的第三方推送服务；
数据概览中含有多个指标的 Widget，现在可以点击单个指标以查看详情了；
漏斗分析和留存分析中可以设置结束日期是否延展了；
留存分析的文案和折线图进行了优化；
用户路径分析，现在可以添加书签了，以便保存查询条件；
对 UserAgent 的解析策略进行了优化，现在可以兼容更多的手机机型了；
用户分群的名称设置环节做了优化；
API 兼容性改动：
由于漏斗分析功能的整体重构，API 也进行了相关修改，且与之前的版本不兼容，新的协议请参考API。
1.6.5 ：2016年12月20日发布
更新列表：
新功能：
埋点管理中增加了一个新的导入实时察看界面，用于实时察看当前系统正在被接入的数据；
事件提供了标签管理功能，在事件比较多的时候，更加方便管理和查询；
用户路径分析中，初始事件和结束事件也会按照事件的分组条件来进行分析；
用户路径分析的结果，现在也可以点击进去察看具体的人群明细了；
与极光推送的对接，现在可以完全在可视化界面上完成了，从而方便非技术人员自主进行消息推送；
针对各种应用场景，进一步完善了 iOS 和安卓的渠道追踪方案，例如，增加了对今日头条这一投放渠道的追踪等；
JS SDK 现在可以默认采集所有元素的点击了；
实现了 OAuth2.0 协议来支持用户使用第三方帐号系统登录系统并控制权限；
iOS 和安卓 SDK 支持 APICloud 这一开发框架了；
对数据预处理模块进行了开放，客户可以自己编写代码在 ETL 阶段对数据进行更进一步的处理；
专门提供了 schema_tools 这一工具，用于在后台增加事件和属性的定义；
集群版客户现在可以直接使用 JDBC 从系统中查询数据了；
留存分析中不仅仅可以察看留存的用户，也可以察看流失的用户了；
提供了 C# SDK，支持 LoggingConsumer，可以在服务器端把日志打到文件中，然后使用 LogAgent 发送给系统；
优化点：
对行为事件分析结果的表格展现进行了重构，当然，为了照顾老客户的使用习惯，也保留了切换回老样式的入口；
重构了用户行为序列页面的展现样式，加快了查询速度，并且可以更方便地按天进行选择；
对场景化数据概览功能进行了优化，对于新客户，使用了我们客户端 SDK 的默认采集功能时，将会自动为客户增加对应的数据概览了；
事件分析，在时间粒度选择分钟和小时时，时间控件也可以选择小时了；
为了降低客户使用 track_signup 的难度，现在专门提供了 login 接口，使用场景更加简单；
HDFSImporter 目前可以支持使用 gzip 压缩的数据了；
在查询时，如果是由于事件被隐藏而查询失败时，会有更加友好的错误提示；
进一步优化了预测模块，使得任务运行稳定性得到进一步提高；
漏斗的下拉列表增加了搜索框，方便在漏斗很多的时候快速选择相应的漏斗；
现在在“关于”里面会显示更加详细的版本信息了；
优化了“埋点管理”的打开速度，并且“埋点管理”也对外提供 API 了，方便与客户的系统集成；
使用了维度字典的属性，现在在筛选时支持“为空”和“不为空”了，并且维度字典里面也可以对空值进行定义；
浏览器直接访问数据接入地址，现在会有更加友好的提示了。
1.6 ：2016年9月25日发布热烈庆祝神策分析 1.0 版本发布一周年。
更新列表：
新功能：
增加了用户列表功能，可以通过分组、筛选等方式察看用户的 Profile 的分布；
增加了用户路径分析功能，可以分析整体或者指定用户群体的访问路径的特征；
增加了Session 分析功能，提供了一系列的 Session 级别的指标和维度，用以满足使用者在 Session 分析方面的需求；
增加了场景化数据概览功能，可以非常简单地导入我们预先定制好的一系列数据概览模板；
回访分析升级成了分布分析，不仅可以按照某个事件发生的“次数”、“小时数”、“天数”来分析用户群体的分布，还可以按照任意指标来分
析用户群体的分布了；
在用户分群功能中，增加了预测功能，用于预测用户流失或者完成某个事件的概率；
现在数据概览可以整体调整时间区间了，当然，我们也保留了对数据概览中单个 widget 调整时间的功能；
安卓和 iOS SDK 现在增加了对于例如“App 启动”、“App 进入后台”、“App 进入某个页面”这些默认事件的采集了；
提供了一个专门的可视化界面，用于自动生成 JS SDK 的初始化代码；
将导入 token 的权限做了划分，设置 Normal Token 时数据可以导入，但不能创建事件、属性等元数据；设置 Super Token 时数据可以导
入并也可以创建相关元数据。
优化点：
SDK 增加了一系列新接口，用于在混合模式开发的 App 中，使得 iOS 或者安卓 App 可以与嵌入的 H5 页面交换 distinct_id 等信息；
优化了对 UserAgent 的解析效果，并且现在会根据 UserAgent 判断是否是 spider 了；
字符串类型的筛选，现在支持“为空”和“不为空”了；
JS SDK 现在在采集默认的“页面浏览”事件时，也会加上对“最近一次站外访问来源”的收集，以便从这个角度分析用户来源；
LogAgent 现在可以兼容 Windows 服务器了；
LogAgent 支持通过配置文件的方式传递参数了；
调整了元数据管理功能的界面布局；
现在可以在通过可视化界面上传维度字典了；
优化了时间控件的设计；
优化了漏斗的查询速度；
优化了用户行为序列的查询速度；
优化了数据概览的缓存策略。
1.5 ：2016年6月30日发布
更新列表：
新功能：
神策分析支持多项目了，多个项目之间，权限、数据完全隔离，互不干扰；
增加了统一的埋点管理功能，可以看到各个端、各个事件、各个版本下的各个埋点的数据导入情况以及相应的错误日志，同时，还可以禁
用埋点；
提供了完整的渠道追踪方案，其中，iOS 渠道分析功能进一步加强，除了精准的渠道追踪方案以外，还提供了基于设备指纹的模糊匹配方
案，可以一起使用；
提供了推荐分享功能，使用者可以将神策分析推荐给朋友，从而享受相应的专属优惠；
事件分析中支持自定义指标，可以用多个指标的四则运算来生成一个新的指标；
事件分析中多指标支持图形化展示了；
事件分析功能，时间粒度可以细化到分钟了；
事件分析中，可以计算某个属性的独立去重数了；
JSSDK 现在提供了默认采集“页面访问”事件的能力，并且会自动采集包括 URL、标题、UTM相关标记、是否首日访问等预置属性；
JS SDK 现在可以支持回调了；
JS SDK 的可视化埋点现在可以支持 iFrame 了；
JS SDK 现在可以支持以服务端时间为准，以避免客户端的时间异常问题；
元数据管理中，现在可以隐藏某个事件或者用户属性了；
现在可以在界面上来给分析师授予不同事件的访问权限了；
现在每个账户都可以修改自己的密码了；
优化点：
大幅度提升了集群版的数据导入的时效性；
时间类型的属性在筛选功能中，支持细到分钟的选择；
时间类型的属性在进行分组时，支持自定义分桶方式了；
优化了 iOS 和安卓 SDK 的数据发送策略；
优化了 iOS 和安卓 SDK 在 Debug 模式下的异常抛出策略；
JS、iOS、安卓 SDK，对于操作系统和终端的取值进行了统一；
优化了用户行为序列的展现样式；
优化了各个分析功能中筛选框的 suggestion 的样式，增加了提示，避免误解；
list 类型的属性在筛选中，“匹配”可以支持多选了，并且增加了“不匹配”；
用户分群中，“用户做过”某些事件，现在这些事件之间可以是“或”的关系了；
用户分群中，在“相对时间”中可以支持自定义时间区间了；
事件分析的折线图，当时间点很多时，对时间轴的操作做了优化；
FormatImporter 的功能增强。
1.4 ：2016年4月18日发布
更新列表：新功能：
增加了用户分群功能；
增加了用户行为序列，可以浏览分析结果中的用户列表和单个用户的行为序列；
在安卓和 iOS SDK 中，增加了渠道追踪相关的接口，并且提供了一套针对 iOS9 及以上版本的 iOS 环境下 App 的精准渠道追踪的方案；
后台可以设置分析师的权限，让分析师只能访问部分事件的数据；
优化点：
现在回访和留存分析的事件和用户属性过滤都可以添加多个筛选条件了；
安卓和 iOS SDK，都可以设置成当积累一定条目的数据后自动触发发送；
漏斗的窗口期可以自定义时间了；
漏斗的步骤可以自定义别名了；
漏斗添加步骤时，事件的筛选条件可以选择是“或”的关系了；
当事件选择是“任意事件”时，会将所有事件中都出现过的字段作为“任意事件”的属性出现在筛选和分组的下拉框中；
可以使用“用户 ID”作为事件的过滤条件了；
增加了数据接入引导页面；
优化了 Web 端可视化埋点的用户体验；
增强了 Android 端可视化埋点对于各类 App 的兼容性；
现在可以选择，当所有查询条件设置好之后，再手动触发查询了。
1.3 ：2016年1月31日发布
更新列表：
新功能：
增加了“可视化埋点”功能，用可视化的方式，在 iOS、Android、Web 三个前端平台增加事件追踪记录；关于神策分析对数据接入的整体考
虑，可以参照这里；
各个 SDK（1.3.1 以后的版本） 和导入工具增加了调试模式，用于使用者调试代码和数据；
增加了维度字典功能，以便使用者对某个属性增加对应的字典映射关系；
自定义查询支持漏斗和留存回访的用户明细了；
优化：
大幅度优化了集群版的抽样查询的性能；
现在，用作分组的属性如果是个数值类型的属性，则可以选择按照”离散值“来进行分桶了；
1.2 ：2015年12月23日发布
更新列表：
新功能：
对于首次使用的用户，增加了“功能引导”，帮助用户更好地使用产品；
增加了隐藏事件的功能，不再使用的事件，可以选择隐藏，并且“任意事件”也不包含被隐藏的事件了；
回访频率支持按“次数”进行分析；
字符串类型的字段筛选，支持正则匹配了；
创建漏斗时，每个步骤支持多个筛选条件了；
在事件分析功能中，数值类型字段的“人均值”也可以作为分析指标了；
新增强制刷新功能，点击页面右上角的刷新按钮会忽略查询缓存，强制重新查询计算；
增加了查询抽样功能，在数据量很大的时候，可以通过抽样少部分用户来快速验证猜想；
增加了数据删除工具；
增加了 profile_set_once 接口，调用这个接口设置某个 profile 时，如果直接有值，则会忽略，在设置注册渠道等场景时非常有效；
优化：
去除了取值超过2000的字符串类型属性不能进行分组的限制；
SDK和导入工具，增加了对 property 名称的限定，一些保留字段不能作为 property 的名称：id、first_id、second_id、users、events、
event、user_id、date、datetime、distinct_id、original_id、time、properties，之前如果有这类字段作为 property 名称，则在升级时会自
动进行重命名，如 users 会自动重命名为 _users；
重新梳理了属性与事件的关系，现在明确属性是全局唯一的，同名属性在不同事件中都是同样的类型，并且设置了一次显示名就全部生
效；
大幅度提升了留存分析的查询性能；
大幅度提升了批量导入工具的处理性能；
大幅度优化了集群版本的可运维性；
大幅度优化了内存占用，避免了因为数据过多导致内存超限的问题。
1.1 ：2015年10月31日发布
更新列表：
增加了“账号管理”和“概览授权”功能；
账号一共分为三类，分别具有如下功能：
管理员：
权限管理：有“账号管理”功能，也可以进行“报表授权”；
数据分析：所有的数据分析功能都可以使用；
概览：可以察看自己和别人共享而来的概览，创建概览，编辑自己所创建的概览；并且可以通过“概览授权”功能将概览共享给其
他用户；漏斗：管理员可以创建漏斗和删除自己的漏斗，创建的漏斗全局可见；
分析师：
数据分析：所有的数据分析功能都可以使用；
概览：可以察看自己和别人共享而来的概览，创建概览，编辑自己所创建的概览；由于没有“权限管理”功能中的“概览授权”功 能，
所以概览只能自用；
漏斗：分析师可以创建漏斗和删除自己的漏斗，创建的漏斗只有自己可见；
普通用户：
概览：可以察看别人共享而来的概览；并且，概览点击进去后，只能调整时间区间，不能做其它筛选和分组的调整。
增加了三个针对特定数据源 (CSV、MySQL、Nginx 日志)的导入工具 FormatImporter;
大幅度提升了对 profile 的各类操作的处理速度;
交互体验升级：
改善了在手机上使用Safari浏览数据概览时偶尔比较卡、滚动不太灵敏的问题；
改善了在手机上切换柱状图时间时的滑动体验；
改善了数据查询时过滤条件输入过程中的输入体验;
修复了一些交互体验和功能模块的 bug。
1.0 ：2015年9月25日发布
更新列表：
增加了“自定义查询”功能，使用者可以使用标准 SQL 对神策分析的所有数据进行查询；
在事件分析中增加了“多指标分析”功能，可以对同一个事件的多个指标，或者多个事件的多个指标进行对比分析，并且可以保存到“书签”和“数据概
览”中；
在行为事件分析、漏斗分析、留存分析、回访频率中使用分组查看功能时，当分组字段是数字类型时，可以自定义分组区间；
在“数据管理”功能中，增加了“虚拟事件”的管理功能，使用者可以自由组合多个元事件和筛选条件，配置虚拟的事件类型；
增加了“用户明细下载”功能：
在“行为事件分析”、“漏斗分析”、“留存分析”和“回访频率”等任意一个分析中，只要查询结果是用户数，则可以以 CSV 的形式下载这些
用户的明细数据；
明细数据包括用户 ID、用户 Profile 等；
优化了“数据概览”的展现形式；
增加了“数据校验”功能，使用者可以检查数据是否符合要求，并且在校验合格的基础上，可以主动创建相应的事件和属性；
在四种分析种，数值类型的属性分组时，可以编辑分组区间；
增加了“导入状态察看”功能，使用者可以察看导入的数据的错误以及导入的进度；
修复了一些影响导入的bug；
修复了前端一些影响使用的bug。
0.2 ：2015年8月15日发布
更新列表：
增加了“书签”功能，使用者可以将一些常用查询保存下来；
增加了“数据概览”功能，使用者可以将保存的书签可视化地展示出来；
增加了“数据管理”功能，使用者可以自己命名事件和属性的展示名；
修复了前端一些影响使用的 bug。
0.1 ：2015年7月1日发布
更新列表：
“行为事件分析”功能上线；
“漏斗分析”功能上线；
“留存分析”和“回访频率”功能上线。.产品更新日志 v1.17
1.17 ：2020 年 3 月 10 日发布
更新列表：
新功能
新增「Schema 强校验」数据入库模式，从根源解决错误数据上报入库的问题。将需要上报的事件先更新到项目中后，按照设置进行数据
入库的强校验
支持设置「设备 ID」和「登录 ID」用户信息格式规则自定义；
支持下载当前项目中已有的事件、事件属性、用户属性的配置文件；
支持对元事件相关信息进行批量更新；
支持对事件属性、用户属性的显示名进行批量重命名；
支持在线协同新建与管理元事件、事件属性和用户属性；
支持对无用事件进行整个事件的「停止入库」操作（Extractor 不导入，Nginx 正常接收）；
概览新增以下功能：
支持使用用户属性、事件属性进行概览的全局筛选；
支持全屏模式，可设置定时刷新；
支持将路径分析和间隔分析保存的书签添加至概览中；
支持漏斗按趋势展示；
支持留存按表格展示；
权限与成员管理扩展：
权限扩展，支持对成员进行多角色授权；
支持在角色内指定加密事件属性和用户属性；
可自定义授权创建虚拟事件和管理全部虚拟事件的权限；
支持一键下载成员账号信息与角色配置，便于进行授权审核；
事件分析表格升级（3 月 27 日发布）：
多维下钻时，支持按照维度的层级进行聚合展示，更加结构化地拆解指标，满足多维分组时的大部分场景，同时支持切换旧版的
平铺展示；
按层级展示的表格，新增「其他」「子合计」「总计」等指标；
支持导出 Excel 表格，自带透视表；同时对数据格式做了优化，更方便用户对数据进行二次加工；
表格支持筛选功能，同时支持每天（分钟、小时、天、月）的切片数据查看；
优化多指标与对比的展示方式；
用户分群新增以下特性：
分析模型中增加对使用分群的历史版本给予提示；
支持基于入库数据自动触发用户分群计算；
支持对用户分群进行指定资源池、指定时段的自定义划分、配置；
事件分析中支持选择历史版本分群用户【仅购买神策用户画像的客户可使用】；
对于各分析模型，支持用户自主选择是否使用异步查询（手动加入到查询列队，排队等待计算结果）；
在路径分析中，选择参与分析事件包含虚拟事件，结果以虚拟事件为统计结果，并支持一键下载用户路径分析结果图；
支持在界面创建和管理虚拟属性，字符串与数值类型的虚拟属性支持添加字典；
物品类型（维度表）可在元数据管理中查看；
在渠道管理中，在生成「微信小程序通用渠道链接」时，支持同时生成对应的「小程序码」；
新增「通知助手」，当概览发生变更或查询被强制暂停、完成加入列队的查询任务、完成导出数据的文件生成时，系统自动通知；
支持查看当前项目的成员在系统内的操作日志以及使用情况统计；
优化
查询性能全面优化，大幅提升查询速度；
用户列表、事件分组交互体验升级；
概览的分享设置与复制操作，移入概览右上角的更多操作中；增加计算中未使用今日分群计算结果的提示，优化概览中缺少事件、属性报
错等提示；
埋点管理中，改进了错误数据原因的可读性，实时导入与 Debug 导入数据中支持筛选来源与应用版本；
支持异步导出数据文件，保证大数据量文件的稳定生成；
支持自定义企业 Logo，并可自定义登录系统后的底部信息；
支持安全相关的自定义配置：
用户首次登录时应强制修改初始密码；
修改密码时候应验旧密码，至少和前一次密码不同；
用户密码应定期修改，更改周期不超过 90 天；
可配置 Web 界面自动登出的超时时间；
重要变更
OAuth 登录支持配置使用平台账号（1.15 版本以上均支持）；
老版本升级到 1.17 如需要使用「Schema 强校验」数据入库模式，请联系神策服务同学进行开启。启用后，数据将严格按照预定义的规则
进行上报，错误数据将不允许入库，可基于历史情况决定是否保留允许使用 supertoken，如不需要可关闭；
Impala 从 2.12 版本升级到 3.2，有少量的不兼容语法变化，GROUP BY、HAVING、ORDER BY 中的别名替换逻辑与标准 SQL 行为更
一致，新增了一系列的保留字段，查看详细。
1.16 ：2019 年 11 月 21 日发布
更新列表：
新特性
概览中增加公共概览功能组，建立企业数据看板的公共空间，支持授权的多个成员共同管理。公共概览全面支持复制、排序、分组、共享设置等操作。
原「预置概览」更名为「基础数据概览」。
可通过角色权限支持成员是否可查看公共概览功能组。
支持在公共概览中单独创建的概览进行分角色、职位、个体成员进行灵活授权（使用职位授权需先在「成员管理」-「职务管理」
中创建对应职务）。
在我的概览模块支持复制当前已有概览到「公共概览」或存至「我的概览」帮助企业快速迁移已有概览到「公共概览」中。
在「单个概览」中支持添加多组描述，可拖动排序；对于长期不使用，但需要保留最后一次分析结果的概览，可使用「停止更新」来暂停
此概览的自动计算，以确保计算资源的有效释放。
新增场景库功能组，神策将沉淀的结合业务场景的分析方法「一键应用」到「公共概览」中，客户可结合所需与场景库的数据解读方法实
现快速的业务分析。
支持下载场景中对应所需的「事件设计」，为客户提供快速的事件设计方案。
支持线上自定义匹配对应事件，实现已有事件的快速应用。
成员与角色，功能模块全面实现灵活权限可配置。
在成员管理中增加「职务管理」，概览可对指定职务的成员实现动态的查看授权。
支持更细颗粒度的授权配置：
概览：「查看公告概览」、「管理公共概览」、「管理我的概览」的分别授权。
漏斗：「可用漏斗」、「管理漏斗」的分别授权。
支持「分析」、「元数据管理」、「预警管理」、「渠道管理」、「成员与角色」的分别授权。
为了确保项目的安全、稳定和数据的准确，我们在「基本设置」中，新增了「下载资源使用报告」、「平台安全设置」、「数据校验」功
能。
Admin 账号可下载「资源使用报告」，其中完整展示当前项目中功能模块、事件上报、用户使用情况明细。
Admin 账号可配置「平台安全设置」包括登录账号是否开启验证码验证、登录试错次数限制等。
有权限使用「数据校验」的成员可上传已有的「事件设计方案」后，系统自动完成与库内数据的对比，来进行数据质量的校验。
元数据中的「Session 管理」新增事件的「开始」和「退出」的事件定义。
重要变更
如果升级上来的客户，是已经使用的「预置概览」并且需要用其英文版。那么请删除已有的「预置概览」后，在场景库中重新添加「基础
分析概览」后即可正常使用。
1.15 ：2019 年 7 月 15 日发布
更新列表：
新特性
概览中的预置概览模块
新增用户活跃等概览事件的配置入口。
预置概览默认为全埋点事件，另支持可调整为已有的其他事件进行统计，让预置概览更加贴合业务需求。
新增用户生命周期概览，直观可见用户构成（新用户、连续活跃用户、回流用户、沉默用户、流失用户、流入流失比），且支持
自定义配置调整。
概览中的我的概览模块
增加复制概览功能
在管理我的概览的功能，支持同时增加多个概览的可访问成员；支持批量重置概览访问成员；支持批量停止分享概览。
在概览排序功能中，支持将多张概览批量移动到指定概览组内；
新增隐藏概览组，隐藏概览组默认收起，可将不常查看的概览移动到隐藏概览。
在成员与角色模块中
账号管理、角色权限整合为「成员与角色」模块
账号类型中新增「平台账号」
企业有多个项目时，不再需要重复创建账号；
每个项目均支持创建「平台账号」，平台账号成员在不同项目中支持拥有不同角色权限；
每个项目均支持「邀请平台账号成员」，邀请后，平台账号成员支持登录项目并进行数据分析。
在成员管理中新增「转交工作」功能，当成员工作发生变更是，支持一键转交此成员创建的所有书签、概览。
优化角色管理授权方式
在「可用事件」的授权中，增加「按标签动态授权」事件
优化「可用事件属性」权限，在分析模型中，不可使用未授权的属性进行筛选、分组查看；用户行为序列详情页均不显
示未授权的信息。
优化「可用用户属性」「可用用户群」权限，在分析模型中，不可使用未授权的属性进行筛选、分组查看；用户列表和
详情页均不显示未授权的信息。
新增「基本设置」模块
支持修改项目名称
支持可以查看项目的限额、已用额度、内存、到期时间等基础信息，
支持使用更新授权、在线升级、充值项目、数据接入、推送管理、查看 API seceret 等功能。
新增「个人中心」
支持查看个人的帐号名、手机号、登录账号、角色、邮箱等基础信息；
可查看自己在数据权限、数据分析等权限明细。当发现不能查看指定数据时，可通过个人中心查看自己是否有权限。
自定义查询新增函数 url_decode
优化
系统结构导航栏将左侧导航优化为顶部导航，结构更加清晰。
导航包含：概览、分析、书签、用户分群、用户标签、元数据、埋点管理、基本设置、渠道管理、预警管理、成员与角色等模
块。
支持根据角色的权限，展示可以查看的模块。
书签增加管理功能
书签作为单独的模块，添加到顶部导航中。
支持查看书签被添加到哪些概览中。
支持查看书签的分析模型类型。
支持管理书签，进行编辑、删除等操作。
重要变更
必须使用多语言切换的客户，建议使用 1.14 版本。
因支持「平台账号」，所以使用 LDAP 特殊的单点登录服务的客户，在升级时，请提前跟您的客户成功经理确认是否升级后有异常。
1.14 ：2019 年 4 月 29 日发布
更新列表：
新特性
推出归因分析分析模型
通过时序还原用户在产品中的行为，挖掘“运营位”与“目标事件”之间的关系
分析多个“运营位”与“目标事件”之间的贡献度，通过可视化图形展示每个“运营位”带来的贡献度
支持多种归因模型，包含：首次触点归因、末次触点归因、线性归因、位置归因和时间衰减归因 5 种归因模型
查看详细
推出全新权限系统
支持自定义用户角色，并为角色分配对应的登录账号
用户角色支持自定义配置“数据资源权限”及“功能模块使用权限”
查看详细
推出可视化全埋点功能
将 app 界面同步显示在神策分析网页端中，并标识出 app 中的元素
点击每个元素，可在界面上为其进行“重命名”，在分析模型中，使用该事件参与分析
iOS 需要 SDK 版本为 v1.11.0+，Android 需要 SDK 版本为 v3.1.0+
查看详细
对数据模型做了进一步的升级优化，从原有的 Event-User 模型升级为 Event-Item-User 模型，现在可以使用 Item 表做为 Event 事件的
易变属性的补充了，具体请参考 Item 实体；
现在可以方便地对冷数据进行数据归档了，以便在节省存储空间的同时也保存好数据资产；
优化
单机版的数据清理工具（sa_clean）现在也支持按照用户 ID（user_id / distinct_id）来删除 Event 表和 Profile 表中的数据了；
现在可以支持同时添加多个逻辑不同的预处理模块（ExtProcesser）了；
集群版的数据清理工具（sa_clean） 优化了按 Event, Lib 等条件删除的逻辑，支持删除缓存中数据；
对于数据迁移工具的可用性与效率进行了改进。
重要变更
分群 API 接口变更，不向前兼容
查看详细
分群的计算规则变更
分群表结构调整
原用户分群表新增了 base_time 字段
对分群/标签的表命名规则进行了调整
查看详细新产品
推出用户标签系统，详细请垂询神策数据工作人员
1.13 ：2018 年 11 月 19 日发布
更新列表：
新特性
支持一个用户关联多个设备，极大地提升了用户关联的能力；
发布神策分析移动端掌上神策分析 1.0 版本
面向管理层，提供更好的数据解读；
提供每日「策报」，通过订阅概览，自动挖掘异常的数据，以日报的形式推送至移动端；
随时随地查看数据概览；
重新设计并实现了用户分群模块；
20 倍以上的计算性能提升；
重新设计了用户分群的 UI，可以更方便地管理分群；
可更好地帮助追踪不同分群的生命周期变化。例行分群的每次计算都有历史记录，并支持重新计算分群历史结果；
支持通过上传用户 ID 创建分群；
支持复制分群；
增强了分群规则条件的描述能力；
提供了更方便的渠道管理，可以在神策分析统一管理、追踪并分析推广效果，形成闭环
支持在产品中创建、管理渠道追踪链接；
支持更多渠道，陆续新增；
支持创建推广活动，并分析推广活动效果；
提供了自动生成的预置概览
管理员可创建一系列场景化的预置概览，通过全埋点生成用户生命周期过程所需要关注的数据指标，包括：整体概况、用户获
取、活跃与留存、事件转化、用户特征等模块；
上线客户服务中心，提供了提交服务反馈、问题的入口，支持用户以工单的方式提交工单，方便追踪问题；
全面支持 GDPR；
重要变更
预置属性 event_duration 更名为 $event_duration，且与之前版本不兼容。如果使用查询 API 、SQL 或者从 Kafka 订阅数据时使
用到此字段，需要变更字段名；
分群 API 有不兼容的变更。
1.12 ：2018 年 8 月 4 日发布
更新列表：
新特性：
可在概览中添加渠道对比组件，支持对多个渠道的流量、新客占比、留存、事件转化等指标进行对比，帮助快速定位优质渠道；
可对每个概览做性能设置，包括计算精度、数据更新时间和抽样系数等，提升概览的查询体验；
可在登录后进行项目快速切换；
可在用户界面下载事件分析的全量数据；
维度字典支持多对一，针对已经存在的事件属性和用户属性，可以上传属性值的自定义多对一映射关系；
支持新的属性类型——列表，用于保存一个有序的字符串序列。原有的 LIST 类型更名为 SET 类型；若创建 SET 类型需用属性创建工具
创建后传入；
提供了数据校验工具，优化数据格式核对的效率；
微信小程序 SDK 更新，支持了分享的监测，可以对分享的次数、层级、页面等维度进行分析;
新增了支付宝小程序 SDK;
优化：
导航的体验优化调整；
概览中事件分析组件支持展示单指标分组前三的数值，留存分析组件新增以日期为横轴的留存趋势图；
留存分析新增第 0 天，用于分析在第 0 天同时进行了初始和后续行为的“共现用户”；
刷新操作调整为点击按钮刷新概览或分析页面中失效数据，按住 Shift 点击，刷新全部数据；
优化了留存导出 csv 的格式；
当查询超过一定时间，提示查询进度与当前查询负载等信息，并可开启抽样或近似查询；
1.11.3954 ：2018 年 5 月 14 日发布更新列表：
新特性
指标预警可设置监控时间段，可设置指标区间；
新增监控历史查询。诊断工具中“监控历史查询”可进入。集群版默认开启，单机版需要根据配置确定是否可以开启；
优化
概览中图表（组件）与左侧导航支持新窗口打开。可右键新标签打开，或按住 Command 或 Ctrl 点击链接；
下载的文件文件名优化；
事件分析中，事件下拉框搜索支持拼音与原事件名搜索（支持元事件与虚拟事件）；
优化概览中组件的拖拽；
1.11 ：2018 年 3 月 25 日发布
更新列表：
新特性
【分析模型增强】新增间隔分析模型，可分析任意两个事件之间的时间间隔分布情况和变化趋势，以优化关键事件之间的转化效率。例
如：分析首次投资到复投的间隔分布情况、注册到付费转化的间隔分布情况；
【数据概览重构】升级了数据概览的信息架构、流程、可视化能力，支持多尺寸图表、多指标表格、自定义时间筛选器等诸多特性，极大
增强了概览的可扩展性、灵活性；
【埋点管理重构】大幅优化了埋点管理的性能；时间区间统一为数据接收时间，减少误解；
【数据接入】支持通过维度表和属性扩展的能力，使用第三方的维度表对已接入的事件和属性进行扩展，极大增强对于复杂业务需求的处
理能力；
【更便捷地查看数据】可通过搜索用户，搜索用户 ID、属性值，直接查看特定用户列表和用户行为序列；
【分析能力增强】事件分析中，可对自定义指标中各子项添加属性筛选条件；
【渠道管理】可通过上传 csv、xls 格式文件批量生成 UTM 链接与短链；
【分析能力增强】LIST 类型的属性可以按“LIST 内的细项”进行统计；
【动态数据类型】可在神策技术支持协助下，修改属性类型；
【数据类型精简】取消 DATE 类型，将其作为 DATETIME 的一种格式处理；
提供了在线升级的能力；
优化
【网页热力分析】网页热力分析结果可生成二维码和链接，方便分享；
【漏斗分析】优化了漏斗的窗口期的计算能力，窗口期默认为当天内；
【APP 点击分析】持续优化 APP 点击分析功能的系统兼容性；
表格中的触发用户数可以直接查看用户列表，或快捷保存为用户分群，减少操作成本；
【虚拟事件管理】虚拟事件支持批量添加和事件排除；
【数据下载】优化了数据下载方式，可按表格中展示数据或源表数据分别下载需要的数据。
1.10 ：2017 年 11 月 15 日发布
更新列表：
新特性
新增 APP 点击分析模块，可以通过可视化的方式对 APP 的用户行为进行分析；
点击分析升级为网页热力分析，新增了触达率分析图，可对用户在网页中的触达深度进行分析；优化了工具栏；
重构了事件选择的下拉菜单，支持个性化的事件二级分类、顺序调整、隐藏，可以根据业务线、产品结构等组织方式，更方便地整理事
件、指标的结构；
元数据管理可以对（虚拟）事件批量添加标签、更改显示状态，更方便地命名显示名，并优化了排序、分页等一系列体验，可以更方便的
管理事件；
元数据管理中事件可以添加备注了；
数据概览导航支持二级分类，可以更方便的整理概览的结构；
优化
可以联系神策技术支持开启分析师角色组“创建虚拟事件”、“创建分群”、“创建 Session”的权限；
大幅优化了多个分析功能中使用了用户属性时的查询性能；
漏斗、虚拟事件、 Session 和分群可查看创建信息（创建人、创建时间和修改时间）；
优化了下载 CSV 的时间格式；
强力优化了点击图的多个功能（如 a 链接里有多层嵌套，input 元素自定义采集，对自动采集的元素自定义是否采集，map/area 的采集支
持，优化选择器，等多个功能）；
渠道来源优化、单页面时候手动发送 $pageview 等等多个小功能的优化。
兼容性改动
HdfsImporter 导入工具不再兼容直接使用 hadoop jar 命令运行的方式；
1.9 ：2017 年 8 月 19 日发布更新列表：
新功能：
可以对重点指标设置预警，当指标达到设定的某一绝对或相对值后，触发提醒通知责任人，支持小时、天等级别的实时监控；
增强了事件分析的对比能力，可对任意一个指标添加任意筛选条件，同时对比相同事件的不同维度指标；
增强了留存分析的分析能力，除了统计留存人数之外，还可以统计如消费总金额、人均消费额、停留总时长等更多指标，并可导出对应格
式的 CSV；
编辑漏斗时可另存为新漏斗，支持快速复制漏斗；
现在可以对接 AppsFlyer 了，从而使得渠道追踪支持多达数千家海内外投放渠道；
优化：
事件分析分组值过多时有了友好提醒，准确描述数据情况；
数据导入出现延时有了友好提醒，方便更及时了解数据延迟情况；
页面出现异常时有了更详细的报错信息，方便用户向神策技术支持提供问题定位信息，提高定位问题的效率；
版本成功更新后有了友好提醒；
点击分析新增“返回上一页”按钮，返回上一页无需通过浏览器进行后退操作；
点击分析刷新数据按钮可拖动，解决遮盖数据问题；
漏斗步骤前新增了步骤数表示；
优化了表格分页导航设计；
实时导入数据增加了对“用户ID”的说明；
优化了概览发送邮件的测试发送时的体验；
优化了用户行为序列的部分界面。
1.8 ：2017 年 7 月 21 日发布
更新列表：
新功能：
私有部署单机版的架构进行了整体重构，为今后单机版无缝扩展为集群版打下基础；
iOS 和 Android 的全埋点功能兼容性大大提高，对于自定义控件、Fragment、RN 框架等有了更好的支持；
产品现在有了英文界面了；
现在通过邮件发送概览可以在界面上进行配置了；
时间类型的属性进行分桶时，有了更多的选择，不仅可以选择分钟、季度等，还可以选择按照时段汇总进行分桶；
漏斗分析按分组查看时，表格里面可以展开分组按日期、步骤查看；
iOS 和 Anroid SDK 的本地缓存改用 ContentProvider，有效的处理了多进程访问的问题；
大大增强了客户端 SDK 中对混合开发模式下 H5 与 App 的打通能力；
现在可以开启由服务端来判断某个用户 ID 是否是新用户了；
创建漏斗时可以选择前后步骤之间的关联属性了；
现在可以支持通过广点通进行分发的效果追踪了；
现在构建渠道追踪链接时可以提供短链的支持了；
现在部分可以累加的指标支持累积图了；
JS SDK 在进行流量采集时，会有字段用以区分流量来源类型是付费广告流量、自然搜索流量、社交网站流量、引荐流量和直接流量，并
且对于付费广告流量和部分可以解析的搜索流量，则会将搜索关键词也进行记录；
对于 触发用户数、人均次数 等指标，现在提供更加快速的非精确预估算法了；
现在各个客户端 SDK 都增加了 CRC 校验，可以有效甄别网络传输过程中的数据错误；
优化：
对 HDFSImporter 导入单天数据的导入速度进行了优化；
多项目情况下的登录界面体验进行了优化；
多指标、合计等情况下的查询效率进行了优化；
维度字典现在可以下载查看了；
对虚拟事件较多的情况下的编辑体验进行了优化；
浏览器窗口放大缩小时的体验进行了优化；
JS SDK 现在可以自定义埋点信息，在埋点管理里面进行追踪和管理；
在分组和筛选时可以更好地区分事件、用户和 Session 三种不同的属性了；
对于下载的查询结果表格的内容进行了优化；
漏斗分析进行趋势查看、对比时表格可读性进行了优化；
查看实时导入数据的界面上，现在可以全局进行格式 Format 了；
可视化方面进行了较多优化，包括饼图改为环图、线图柱图比例调整等；
点击图的体验进行了大幅优化；
分析师权限的账号可以查看元数据了。
1.7 ：2017 年 3 月 30 日发布
更新列表：
新功能：
iOS、安卓、JS SDK 现在 Autotrack 功能做了进一步的强化，可以默认采集页面上各个元素的交互行为了；
增加了 Web 页面的点击分析功能；
对漏斗分析功能进行了重构，例如，现在可以按照日期查询转化率变化曲线，可以对比两个不同分组值下的漏斗转化情况，现在对事件属
性进行筛选和分组时以实际转化的事件的属性为准，在漏斗转化的前后多个步骤中支持设置一个转化 ID 作为转化的条件等；
现在可以将数据概览的内容通过邮件发送到指定邮箱了，暂时需要在后台通过工具进行配置；
对权限体系重新进行了梳理，例如，现在分析师可以分享自己的概览，并且查看事件和属性的元数据了；
时间和日期类型的属性进行筛选时，现在可以设置与事件发生时间的相对关系了；分析数据时提供了数据及时性提示，鼠标浮动在强制刷新按钮上会给出相应提示，以方便使用者更好地解读分析结果；
渠道链接生成工具，现在可以批量生成链接了；
优化点：
优化了数据概览的缓存策略，以便改进察看数据概览的体验；
优化了判断新增用户的策略，以规避部分由于用户卸载重装 App 带来的识别错误；
集群版的 Profile 导入时效性进行了显著优化；
放开了留存分析对于初始日期的限制；
留存分析中流失用户的定义重新进行了梳理，现在是连续多“天”没有发生后续事件才认为是流失用户；
对用户分群功能进行了优化，在用户“做过”的情况下，可以添加用户“没做过”的条件了，同时也支持只有用户属性筛选的用户分群了；
分析功能在有书签时，展现的标题以书签名称为准；
现在概览的顺序可以全局调整了；
对筛选框的拷⻉、粘贴的体验进行了优化；
现在安卓、iOS 和 JS SDK 在 Debug 模式下，改用弹窗来对错误进行提示；
现在安卓和 iOS SDK 默认也会把设备 ID 作为一个属性进行采集了；
优化了在有分组的情况下，合计和非合计分组展示不一致的问题；
事件分析功能中，当含有多个指标时，对两个坐标轴与折线的对应关系可以进行更进一步的设置了；
优化各模块中事件选择下拉框的展示性能，避免事件过多时出现卡顿现象；
创建 Session 现在支持切分粒度到秒了；
支持系统在浏览器隐私模式下使用了；
表格左侧维度列现在是固定的了；
推送功能增加了所支持的第三方推送服务；
数据概览中含有多个指标的 Widget，现在可以点击单个指标以查看详情了；
漏斗分析和留存分析中可以设置结束日期是否延展了；
留存分析的文案和折线图进行了优化；
用户路径分析，现在可以添加书签了，以便保存查询条件；
对 UserAgent 的解析策略进行了优化，现在可以兼容更多的手机机型了；
用户分群的名称设置环节做了优化；
API 兼容性改动：
由于漏斗分析功能的整体重构，API 也进行了相关修改，且与之前的版本不兼容，新的协议请参考API。
1.6.5 ：2016 年 12 月 20 日发布
更新列表：
新功能：
埋点管理中增加了一个新的导入实时察看界面，用于实时察看当前系统正在被接入的数据；
事件提供了标签管理功能，在事件比较多的时候，更加方便管理和查询；
用户路径分析中，初始事件和结束事件也会按照事件的分组条件来进行分析；
用户路径分析的结果，现在也可以点击进去察看具体的人群明细了；
与极光推送的对接，现在可以完全在可视化界面上完成了，从而方便非技术人员自主进行消息推送；
针对各种应用场景，进一步完善了 iOS 和安卓的渠道追踪方案，例如，增加了对今日头条这一投放渠道的追踪等；
JS SDK 现在可以默认采集所有元素的点击了；
实现了 OAuth2.0 协议来支持用户使用第三方帐号系统登录系统并控制权限；
iOS 和安卓 SDK 支持 APICloud 这一开发框架了；
对数据预处理模块进行了开放，客户可以自己编写代码在 ETL 阶段对数据进行更进一步的处理；
专门提供了 schema_tools 这一工具，用于在后台增加事件和属性的定义；
集群版客户现在可以直接使用 JDBC 从系统中查询数据了；
留存分析中不仅仅可以察看留存的用户，也可以察看流失的用户了；
提供了 C# SDK，支持 LoggingConsumer，可以在服务器端把日志打到文件中，然后使用 LogAgent 发送给系统；
优化点：
对行为事件分析结果的表格展现进行了重构，当然，为了照顾老客户的使用习惯，也保留了切换回老样式的入口；
重构了用户行为序列页面的展现样式，加快了查询速度，并且可以更方便地按天进行选择；
对场景化数据概览功能进行了优化，对于新客户，使用了我们客户端 SDK 的默认采集功能时，将会自动为客户增加对应的数据概览了；
事件分析，在时间粒度选择分钟和小时时，时间控件也可以选择小时了；
为了降低客户使用 track_signup 的难度，现在专门提供了 login 接口，使用场景更加简单；
HDFSImporter 目前可以支持使用 gzip 压缩的数据了；
在查询时，如果是由于事件被隐藏而查询失败时，会有更加友好的错误提示；
进一步优化了预测模块，使得任务运行稳定性得到进一步提高；
漏斗的下拉列表增加了搜索框，方便在漏斗很多的时候快速选择相应的漏斗；
现在在“关于”里面会显示更加详细的版本信息了；
优化了“埋点管理”的打开速度，并且“埋点管理”也对外提供 API 了，方便与客户的系统集成；
使用了维度字典的属性，现在在筛选时支持“为空”和“不为空”了，并且维度字典里面也可以对空值进行定义；
浏览器直接访问数据接入地址，现在会有更加友好的提示了。
1.6 ：2016 年 9 月 25 日发布
热烈庆祝神策分析 1.0 版本发布一周年。
更新列表：
新功能：
增加了用户列表功能，可以通过分组、筛选等方式察看用户的 Profile 的分布；增加了用户路径分析功能，可以分析整体或者指定用户群体的访问路径的特征；
增加了Session 分析功能，提供了一系列的 Session 级别的指标和维度，用以满足使用者在 Session 分析方面的需求；
增加了场景化数据概览功能，可以非常简单地导入我们预先定制好的一系列数据概览模板；
回访分析升级成了分布分析，不仅可以按照某个事件发生的“次数”、“小时数”、“天数”来分析用户群体的分布，还可以按照任意指标来分
析用户群体的分布了；
在用户分群功能中，增加了预测功能，用于预测用户流失或者完成某个事件的概率；
现在数据概览可以整体调整时间区间了，当然，我们也保留了对数据概览中单个 widget 调整时间的功能；
安卓和 iOS SDK 现在增加了对于例如“App 启动”、“App 进入后台”、“App 进入某个页面”这些默认事件的采集了；
提供了一个专门的可视化界面，用于自动生成 JS SDK 的初始化代码；
将导入 token 的权限做了划分，设置 Normal Token 时数据可以导入，但不能创建事件、属性等元数据；设置 Super Token 时数据可以导
入并也可以创建相关元数据。
优化点：
SDK 增加了一系列新接口，用于在混合模式开发的 App 中，使得 iOS 或者安卓 App 可以与嵌入的 H5 页面交换 distinct_id 等信息；
优化了对 UserAgent 的解析效果，并且现在会根据 UserAgent 判断是否是 spider 了；
字符串类型的筛选，现在支持“为空”和“不为空”了；
JS SDK 现在在采集默认的“页面浏览”事件时，也会加上对“最近一次站外访问来源”的收集，以便从这个角度分析用户来源；
LogAgent 现在可以兼容 Windows 服务器了；
LogAgent 支持通过配置文件的方式传递参数了；
调整了元数据管理功能的界面布局；
现在可以在通过可视化界面上传维度字典了；
优化了时间控件的设计；
优化了漏斗的查询速度；
优化了用户行为序列的查询速度；
优化了数据概览的缓存策略。
1.5 ：2016 年 6 月 30 日发布
更新列表：
新功能：
神策分析支持多项目了，多个项目之间，权限、数据完全隔离，互不干扰；
增加了统一的埋点管理功能，可以看到各个端、各个事件、各个版本下的各个埋点的数据导入情况以及相应的错误日志，同时，还可以禁
用埋点；
提供了完整的渠道追踪方案，其中，iOS 渠道分析功能进一步加强，除了精准的渠道追踪方案以外，还提供了基于设备指纹的模糊匹配方
案，可以一起使用；
提供了推荐分享功能，使用者可以将神策分析推荐给朋友，从而享受相应的专属优惠；
事件分析中支持自定义指标，可以用多个指标的四则运算来生成一个新的指标；
事件分析中多指标支持图形化展示了；
事件分析功能，时间粒度可以细化到分钟了；
事件分析中，可以计算某个属性的独立去重数了；
JSSDK 现在提供了默认采集“页面访问”事件的能力，并且会自动采集包括 URL、标题、UTM相关标记、是否首日访问等预置属性；
JS SDK 现在可以支持回调了；
JS SDK 的可视化埋点现在可以支持 iFrame 了；
JS SDK 现在可以支持以服务端时间为准，以避免客户端的时间异常问题；
元数据管理中，现在可以隐藏某个事件或者用户属性了；
现在可以在界面上来给分析师授予不同事件的访问权限了；
现在每个账户都可以修改自己的密码了；
优化点：
大幅度提升了集群版的数据导入的时效性；
时间类型的属性在筛选功能中，支持细到分钟的选择；
时间类型的属性在进行分组时，支持自定义分桶方式了；
优化了 iOS 和安卓 SDK 的数据发送策略；
优化了 iOS 和安卓 SDK 在 Debug 模式下的异常抛出策略；
JS、iOS、安卓 SDK，对于操作系统和终端的取值进行了统一；
优化了用户行为序列的展现样式；
优化了各个分析功能中筛选框的 suggestion 的样式，增加了提示，避免误解；
list 类型的属性在筛选中，“匹配”可以支持多选了，并且增加了“不匹配”；
用户分群中，“用户做过”某些事件，现在这些事件之间可以是“或”的关系了；
用户分群中，在“相对时间”中可以支持自定义时间区间了；
事件分析的折线图，当时间点很多时，对时间轴的操作做了优化；
FormatImporter 的功能增强。
1.4 ：2016 年 4 月 18 日发布
更新列表：
新功能：
增加了用户分群功能；
增加了用户行为序列，可以浏览分析结果中的用户列表和单个用户的行为序列；
在安卓和 iOS SDK 中，增加了渠道追踪相关的接口，并且提供了一套针对 iOS9 及以上版本的 iOS 环境下 App 的精准渠道追踪的方案；
后台可以设置分析师的权限，让分析师只能访问部分事件的数据；
优化点：现在回访和留存分析的事件和用户属性过滤都可以添加多个筛选条件了；
安卓和 iOS SDK，都可以设置成当积累一定条目的数据后自动触发发送；
漏斗的窗口期可以自定义时间了；
漏斗的步骤可以自定义别名了；
漏斗添加步骤时，事件的筛选条件可以选择是“或”的关系了；
当事件选择是“任意事件”时，会将所有事件中都出现过的字段作为“任意事件”的属性出现在筛选和分组的下拉框中；
可以使用“用户 ID”作为事件的过滤条件了；
增加了数据接入引导页面；
优化了 Web 端可视化埋点的用户体验；
增强了 Android 端可视化埋点对于各类 App 的兼容性；
现在可以选择，当所有查询条件设置好之后，再手动触发查询了。
1.3 ：2016 年 1 月 31 日发布
更新列表：
新功能：
增加了“可视化埋点”功能，用可视化的方式，在 iOS、Android、Web 三个前端平台增加事件追踪记录；关于神策分析对数据接入的整体考
虑，可以参照这里；
各个 SDK（1.3.1 以后的版本） 和导入工具增加了调试模式，用于使用者调试代码和数据；
增加了维度字典功能，以便使用者对某个属性增加对应的字典映射关系；
自定义查询支持漏斗和留存回访的用户明细了；
优化：
大幅度优化了集群版的抽样查询的性能；
现在，用作分组的属性如果是个数值类型的属性，则可以选择按照”离散值“来进行分桶了；
1.2 ：2015 年 12 月 23 日发布
更新列表：
新功能：
对于首次使用的用户，增加了“功能引导”，帮助用户更好地使用产品；
增加了隐藏事件的功能，不再使用的事件，可以选择隐藏，并且“任意事件”也不包含被隐藏的事件了；
回访频率支持按“次数”进行分析；
字符串类型的字段筛选，支持正则匹配了；
创建漏斗时，每个步骤支持多个筛选条件了；
在事件分析功能中，数值类型字段的“人均值”也可以作为分析指标了；
新增强制刷新功能，点击页面右上角的刷新按钮会忽略查询缓存，强制重新查询计算；
增加了查询抽样功能，在数据量很大的时候，可以通过抽样少部分用户来快速验证猜想；
增加了数据删除工具；
增加了 profile_set_once 接口，调用这个接口设置某个 profile 时，如果直接有值，则会忽略，在设置注册渠道等场景时非常有效；
优化：
去除了取值超过2000的字符串类型属性不能进行分组的限制；
SDK和导入工具，增加了对 property 名称的限定，一些保留字段不能作为 property 的名称：id、first_id、second_id、users、events、
event、user_id、date、datetime、distinct_id、original_id、time、properties，之前如果有这类字段作为 property 名称，则在升级时会自
动进行重命名，如 users 会自动重命名为 _users；
重新梳理了属性与事件的关系，现在明确属性是全局唯一的，同名属性在不同事件中都是同样的类型，并且设置了一次显示名就全部生
效；
大幅度提升了留存分析的查询性能；
大幅度提升了批量导入工具的处理性能；
大幅度优化了集群版本的可运维性；
大幅度优化了内存占用，避免了因为数据过多导致内存超限的问题。
1.1 ：2015 年 10 月 31 日 发 布
更新列表：
增加了“账号管理”和“概览授权”功能；
账号一共分为三类，分别具有如下功能：
管理员：
权限管理：有“账号管理”功能，也可以进行“报表授权”；
数据分析：所有的数据分析功能都可以使用；
概览：可以察看自己和别人共享而来的概览，创建概览，编辑自己所创建的概览；并且可以通过“概览授权”功能将概览共享给其
他用户；
漏斗：管理员可以创建漏斗和删除自己的漏斗，创建的漏斗全局可见；
分析师：
数据分析：所有的数据分析功能都可以使用；
概览：可以察看自己和别人共享而来的概览，创建概览，编辑自己所创建的概览；由于没有“权限管理”功能中的“概览授权”功 能，
所以概览只能自用；
漏斗：分析师可以创建漏斗和删除自己的漏斗，创建的漏斗只有自己可见；普通用户：
概览：可以察看别人共享而来的概览；并且，概览点击进去后，只能调整时间区间，不能做其它筛选和分组的调整。
增加了三个针对特定数据源 (CSV、MySQL、Nginx 日志)的导入工具 FormatImporter;
大幅度提升了对 profile 的各类操作的处理速度;
交互体验升级：
改善了在手机上使用Safari浏览数据概览时偶尔比较卡、滚动不太灵敏的问题；
改善了在手机上切换柱状图时间时的滑动体验；
改善了数据查询时过滤条件输入过程中的输入体验;
修复了一些交互体验和功能模块的 bug。
1.0 ：2015 年 9 月 25 日发布
更新列表：
增加了“自定义查询”功能，使用者可以使用标准 SQL 对神策分析的所有数据进行查询；
在事件分析中增加了“多指标分析”功能，可以对同一个事件的多个指标，或者多个事件的多个指标进行对比分析，并且可以保存到“书签”和“数据概
览”中；
在行为事件分析、漏斗分析、留存分析、回访频率中使用分组查看功能时，当分组字段是数字类型时，可以自定义分组区间；
在“数据管理”功能中，增加了“虚拟事件”的管理功能，使用者可以自由组合多个元事件和筛选条件，配置虚拟的事件类型；
增加了“用户明细下载”功能：
在“行为事件分析”、“漏斗分析”、“留存分析”和“回访频率”等任意一个分析中，只要查询结果是用户数，则可以以 CSV 的形式下载这些
用户的明细数据；
明细数据包括用户 ID、用户 Profile 等；
优化了“数据概览”的展现形式；
增加了“数据校验”功能，使用者可以检查数据是否符合要求，并且在校验合格的基础上，可以主动创建相应的事件和属性；
在四种分析种，数值类型的属性分组时，可以编辑分组区间；
增加了“导入状态察看”功能，使用者可以察看导入的数据的错误以及导入的进度；
修复了一些影响导入的bug；
修复了前端一些影响使用的bug。
0.2 ：2015 年 8 月 15 日 发 布
更新列表：
增加了“书签”功能，使用者可以将一些常用查询保存下来；
增加了“数据概览”功能，使用者可以将保存的书签可视化地展示出来；
增加了“数据管理”功能，使用者可以自己命名事件和属性的展示名；
修复了前端一些影响使用的 bug。
0.1 ：2015 年 7 月 1 日 发 布
更新列表：
“行为事件分析”功能上线；
“漏斗分析”功能上线；
“留存分析”和“回访频率”功能上线。"></div>
<div>To view the full page, please visit: <a href=/products/56680002/sgcmfw00026541.html?innerSource=search target="_blank">Sensors Analytics Product Userguide</a> </div>
</div>
<div class="store" id="store">
<div class="buy-model store-item-model">
<a href="#" class="logo">
<img src=https://sg-photogallery.oss-ap-southeast-1.aliyuncs.com/photo/5529537052316390/20541bd8580b533e44a3986fbe8fb9582a9e1.png />
</a>
<div class="info">
<h2 class="info-title">Sensors Analytics</h2>
<span class="info-description">Enterprises can easily get started with 10 data analysis models with flexibly combination and second-level response. Data analysts can explore key behaviors and gain insights into the various growth.</span>
</div>
<a class="btn btn-primary buy-now" data-spm="ibuy" href=/products/56680002/sgcmfw00026541.html?innerSource=search target="_blank">Buy now</a>
</div>
<div class="related-product store-item-model" id="related-product">
<div class="related-product-title">Related Products</div>
<div class="related-product-item">
<a href="/products/56680002/sgcmfw00035934.html?innerSource=detailRecommend" target="_blank">
<div class="logo">
<img src="https://sg-photogallery.oss-ap-southeast-1.aliyuncs.com/photo/5230741938457655/29934f1fbc1dee3cb4af281beb6ce93ded6dd.png" alt="AI Support (Advance - Chat & Email)icon"/>
</div>
<span class="related-product-item-title" title="AI Support (Advance - Chat & Email)">AI Support (Advance - Chat & Email)</span>
</a>
<a class="related-product-item-description" href="/store/3246973.html" target="_blank">VisionTech Pte Ltd</a>
<span class="related-product-item-price">Starting from or $36000/year</span>
<span class="related-product-item-fees">+ Alibaba Cloud Usage Fees</span>
</div>
<div class="related-product-item">
<a href="/products/56680002/sgcmfw00035915.html?innerSource=detailRecommend" target="_blank">
<div class="logo">
<img src="https://sg-photogallery.oss-ap-southeast-1.aliyuncs.com/photo/5230741938457655/299151dcfad24c49142439404ccf7b9bccef3.png" alt="AI Commerce (Starter)icon"/>
</div>
<span class="related-product-item-title" title="AI Commerce (Starter)">AI Commerce (Starter)</span>
</a>
<a class="related-product-item-description" href="/store/3246973.html" target="_blank">VisionTech Pte Ltd</a>
<span class="related-product-item-price">Starting from or $6000/year</span>
<span class="related-product-item-fees">+ Alibaba Cloud Usage Fees</span>
</div>
<div class="related-product-item">
<a href="/products/56680002/sgcmfw00035911.html?innerSource=detailRecommend" target="_blank">
<div class="logo">
<img src="https://sg-photogallery.oss-ap-southeast-1.aliyuncs.com/photo/5230741938457655/299115b30695cd0cb40c889b63cca113f99a6.png" alt="AI Sales (Email)icon"/>
</div>
<span class="related-product-item-title" title="AI Sales (Email)">AI Sales (Email)</span>
</a>
<a class="related-product-item-description" href="/store/3246973.html" target="_blank">VisionTech Pte Ltd</a>
<span class="related-product-item-price">Starting from or $18000/year</span>
<span class="related-product-item-fees">+ Alibaba Cloud Usage Fees</span>
</div>
<div class="related-product-item">
<a href="/products/56680002/sgcmfw00035916.html?innerSource=detailRecommend" target="_blank">
<div class="logo">
<img src="https://sg-photogallery.oss-ap-southeast-1.aliyuncs.com/photo/5230741938457655/29916a6675e676a3a4f639caa2ccddcb6c1a1.png" alt="AI Commerce (Advance)icon"/>
</div>
<span class="related-product-item-title" title="AI Commerce (Advance)">AI Commerce (Advance)</span>
</a>
<a class="related-product-item-description" href="/store/3246973.html" target="_blank">VisionTech Pte Ltd</a>
<span class="related-product-item-price">Starting from or $18000/year</span>
<span class="related-product-item-fees">+ Alibaba Cloud Usage Fees</span>
</div>
<div class="related-product-item">
<a href="/products/56680002/sgcmfw00035920.html?innerSource=detailRecommend" target="_blank">
<div class="logo">
<img src="https://sg-photogallery.oss-ap-southeast-1.aliyuncs.com/photo/5230741938457655/299204eae877a956a44078a371f68712480bf.png" alt="AI Customer Service (Starter - Chat & Email)icon"/>
</div>
<span class="related-product-item-title" title="AI Customer Service (Starter - Chat & Email)">AI Customer Service (Starter - Chat & Email)</span>
</a>
<a class="related-product-item-description" href="/store/3246973.html" target="_blank">VisionTech Pte Ltd</a>
<span class="related-product-item-price">Starting from or $18000/year</span>
<span class="related-product-item-fees">+ Alibaba Cloud Usage Fees</span>
</div>
</div>
</div>
</div>
</div>
</div>
<script type="text/javascript">
window.onload = function () {
const doc = document.querySelector("#text-content");
doc.innerHTML = doc.getAttribute('data-value');
}
</script>
</body>
</html>