指标设计理论概述

1、 基于用户旅程和用户生命周期阶段的指标事件设计。

1.1 用户的某一次 APP 登录使用，功能跳转到退出，称之为用户旅程。可以用于产品的优化改版、功能设计、

活动引动等。

1.2 用户日积月累在小程序、APP 中发生的所有行为，可以划分为跟我们品牌的关联关系。我们可以用 AIPL

模型刻画区分这些人群，并实施监控人群健康度。(Awareness 品牌认知；Interest 兴趣；Purchase 购买； Loyalty

忠诚)。不同品牌的划分方式根据用户行为不同，品牌客单、消费频次不同，划分方法都要具体探讨。

有了 AIPL 各阶段的定义(通常是依据用户某短时间的某些行为频率、次数)，企业还需要随时掌握私域人群

资产的数量与质量，以及时发现问题，对症下药。

过横向对比不同时间段内的人群资产增长，纵向观察人群资产跃迁，衡量品牌在某一时间段内的人群资产健康

度。围绕人群资产健康度及用户对品牌关联度的升级路径，可以拆分出以下的指标模型。

基于 AIPL 人群资产的指标模型

2、神策围绕第一关键指标搭建增长模型，搭建指标体系

2.1 本次分析结合 AIPL 模型与实际业务需求场景，以 GMV(成交总额)作为第一关键指标(One Metric that Matters)

建立小程序、APP 的增长模型(Growth Model)和指标体系(Metrics System)，对不同主题场景进行具体分析，

对当前数据质量进行说明，并提出后续相关工作计划与建议。

以第一指标 GMV 为例，指标拆解方法如上图

3、综合考虑 AIPL 模型和第一指标金字塔式向下拆解的方式，我们会跟客户反复过会，梳理确认所需的指标，

以此来指导后续的事件设计和埋点设计。

以下是某消费电子企业的指标体系样例：

数据平台规划与数据治理方案

1.1 数据模型

数据采集是构建数据平台的核心要素，数据采集是否丰富、完整，采集的数据是否准确，采集的数据能否关联打通，

都直接影响用户行为采集分析项目的应用效果。

神策认为，数据采集的基本原则是大、全、细、时：

• 大：充分考虑用户规模与数据规模的增长，做好数据资产积累的准备；

• 全：从多个数据源完整采集用户行为，并关联打通。例如 促销活动-浏览商品-购买 的一系列行为中，需

要从 HTML5 的活动页面采集用户参与活动，从 Android／iOS App 采集浏览商品并添加到购物车等，从

后端采集支付行为及商品的业务数据等；

• 细：多维度精细刻画用户行为，详细记录事件发生的一系列维度信息，比如订单运费、成本价格等，用于

后续多维分析；

• 时：在技术条件与成本允许的情况下，尽可能地提高数据采集的时效性，从而提高后续数据应用的时效性。

神策通过 “事件 (Event)模型” 来描述用户在线上、线下的各种行为，这也是神策所有的功能设计的核心依据。

神策数据提供多种数据源采集方案，可以从 App、Web 等客户端中“埋点”采集用户行为，可以从 Java、PHP 等

后端应用的日志中采集用户行为，可以从 MySQL 等数据库中采集用户行为，也可以回溯历史文件中所提现的用户

行为。正因为支持这么多种不同的数据采集方案，才可以保证对线上用户行为、业务系统数据和线下用户行为的采

集。

事件模型包括事件(Event)和用户(User)两个核心实体，一个事件描述了一个用户在某个时间点、 以某种方式

完成了某个事情，一个完整的事件通常包含如下的几个关键因素：

1) Who：参与事件的用户。在神策中，使用 Distinct Id 这个概念唯一标识用户。特别地，对于多数据源采集

的用户行为数据，需使用相同的 Distinct Id 进行行为贯通。

2) When：事件发生的时间。即这个事件发生的实际时间。在我们的数据接口中，使用 time 字段来记录精确

到毫秒的事件发生时间。如果调用者不主动设置，则各个 SDK 会自动获取当前时间作为 time 字段的取

值。

3) Where：即事件发生的地点。使用者可以设置 properties 中的 $ip 属性，这样系统会自动根据 ip 来解析相

应的省份和城市，当然，使用者也可以根据应用的 GPS 定位结果，或者其它方式来获取地理位置信息，

然后手动设置 $city 和 $province。除了 $city 和 $province 这两个预置字段以外，也可以自己设置一些其

它地域相关的字段。例如，某个从事社区 O2O 的产品，可能需要关心每个小区的情况，则可以添加自定

义字段“HousingEstate”；或者某个从事跨国业务的产品，需要关心不同国家的情况，则可以添加自定义

字段“Country”。

4) What：事件的名称，用于描述用户所做的行为。

5) How：事件的属性，用户发生行为的方式及相关信息。

每个用户(User)实体对应一个真实的用户，用 Distinct Id 进行标识，描述用户的长期属性(也即 Profile)，并且

通过 Distinct Id 与该用户的行为，也即事件进行关联。用户属性记录的是用户的基本固定不变的属性，如性别、年

收入、首次购买理财产品的时间等。

在 Event-User 模型中，出于性能和可解释性等各方面的考虑，Event 是被设计为不可变的。从逻辑上看似乎没有

问题，因为 Event 代表的是历史上已经发生过的事件，一般来说不应该需要进行更新。但是，在实际的应用过程中，

并不一定是这么理想的状态。如，在采集和分析中会发现：Event 实体中一些基本信息中会有许多是不断变化的、

埋点采集中，发现某些 Event 在最初的阶段采集到的数据不完善。

这时，可通过 Item 实体对 Event-User 模型进行补充。支持使用第三方的维度表来对已接入的事件和属性进行进

一步的扩展，该功能可以大大的增强神策分析对于复杂业务需求的处理能力。

为完整、准确地采集用户行为数据，满足用户行为采集分析项目的需求，神策的分析师会和客户的分析师共同梳理

需要采集的事件，并据此做好事件的划分和事件属性字段设计。

1.2 数据采集与治理

神策具备有多种数据源采集方式，包括：实时采集线上用户行为数据和定期批量导入业务系统中的相关信息。线上

数据源包含网站、App(Android 和 iOS)、微信等前后端常规的数据来源，需提供 iOS SDK、Android SDK、JavaScript

SDK、Java SDK、Python SDK、PHP SDK 等多种 SDK，支持历史数据、业务数据库、日志数据的实时及批量导入多

种方式。所采集数据的存放方式能支持今后进行多维度的统计分析。

同时神策还提供埋点管理功能，能够统一管理不同数据来源端的埋点以及查看数据导入进度和错误数据说明。

本次为客户采集的数据包括手机 APP、小程序、H5 页面终端涉及到的相关业务系统，采集的数据包括用户行为数

据、内容数据、以及相应的业务数据等。

1.2.1 客户端(Web iOS Android)数据采集

客户端包括 Web、H5、 App(Android 和 iOS)C++、APICloud 和微信小程序、支付宝小程序、百度小程序等，开

发者通常会根据分析需求在 App 操作流程中 “埋点” 采集用户行为数据。在 Web、Android App 和 iOS App 中，

神策的提供两种数据采集方法：

 全埋点：在 App 或 Web 页面集成神策 SDK，无需埋点，即可采集：App 启动、退出／控件点击／浏览

页面 等用户行为，同时也可以通过写少量代码的方式采集页面控件内容；

o 优点：实施成本较低，适用于例如 首次快速体验神策的功能、新增 App/H5 营销活动页面的快速集

成、查看 App 旧版本中未埋点的按钮点击事件 等场景；

o 缺点：无法精细采集用户行为数据及相关特征，无法实现精细化分析；数据量较大，浪费存储资源；

 代码埋点：开发者在需要采集用户行为的流程中，编写代码按需采集用户行为及相关特征；

o 优点：采集丰富的多维数据，提供精细化分析能力；除基本的页面浏览、按钮点击行为外，按业务逻

辑需要自定义埋点方案；按需采集，节约流量；

o 缺点：实施成本较高，需持续维护埋点；

 可视化全埋点

o 优点：实施成本低，业务人员可根据业务需求自行对 APP 的按钮进行埋点，在分析模型中使用便捷，

使用方法与虚拟事件一致；

o 缺点：无法采集后端事件，无法采集某些较复杂的自定义属性

综上所述，神策建议客户在实际场景中，根据分析需求、开发排期等因素，综合使用多种埋点方式采集用户行为数

据。

神策支持原生 App 与 H5 混合开发(包括 React Native 、MUI、 Flutter、Weex 等框架，下面有详细描述)。对 App

中内嵌的 H5 页面，神策支通过原生 App 进行桥接、转发，这种方式的优点包括：

 避免 H5 页面由于页面跳转、网络状况不佳等原因导致的数据丢失，保证数据发送的完整性与可靠性；

 App 与 H5 使用同一套账号体系，H5 采集的行为数据与 App 用户自动关联。

客户端可以采集和实现的基础数据如下：

 客户端的基本信息：应用信息、设备信息、系统信息、网络信息、位置信息等。

 客户的行为数据：客户标识、会话信息、点击事件信息、页面相关信息。

 自定义事件信息：自定义事件名称、参数名、参数值等。

 跨屏信息：用户多个设备上的行为信息进行汇总。

此外，神策研发的 Java Script SDK 适配目前市场上所有主流浏览器以及相关内核(最低适配 IE6 )，客户端全埋点

默认采集的预置属性如下。

1.2.1.1 Web 端全埋点预置属性

1.2.1.1.1 所有事件都会有的预置属性

字段名称 类型 说明

$lib 字符串 SDK 类型

$lib_version 字符串 SDK 版本

$screen_height 数值 屏幕高度

$screen_width 数值 屏幕宽度

$is_first_day 布尔值 是否首日访问

$latest_referrer 字符串

$latest_referrer_host 字符串 最近一次站外地址(只要前向域名不是当前

$latest_utm_source 页面的域名，就会重置)

$latest_utm_medium

最近一次站外域名

字符串 最近一次付费广告系列来源(只要有来源参

数，就会重置)

字符串 最近一次付费广告系列媒介

$latest_utm_term 字符串 最近一次付费广告系列字词

$latest_utm_content 字符串 最近一次付费广告系列内容

$latest_utm_campaign 字符串 最近一次付费广告系列名称

$latest_search_keyword 字符串 最近一次搜索引擎关键词

$latest_traffic_source_type 字符串 最近一次流量来源类型

注意：

(1)其中 $latest_search_keyword 最近一次搜索引擎关键词由于各搜索引擎策略不同，可能有获取不到的情况。

(2)其中 $latest_traffic_source_type 这个的属性值包括：付费广告流量、自然搜索流量、社交网站流量、引荐流量、

直接流量。

(3)最近一次付费广告相关参数是一个事件属性，且不需要做任何配置，会在所有事件中都存在。这个属性会保

存最近一次有效的 utm_source 。

1.2.1.1.2 Web 浏览页面($pageview)

字段名称 类型 说明

$referrer 字符串 前向地址

$referrer_host 字符串 前向域名

$url 字符串 页面地址

$url_path 字符串 页面路径

$title 字符串 页面标题

$is_first_time 布尔值 是否首次访问

$utm_source 字符串 广告系列来源

$utm_medium 字符串 广告系列媒介

$utm_term 字符串 广告系列字词

$utm_content 字符串 广告系列内容

$utm_campaign 字符串 广告系列名称

1.2.1.1.3 Web 元素点击($WebClick)

字段名称 类型 说明

$element_id 字符串 元素 ID

$element_content 字符串 元素内容

$element_name 字符串 元素名字

$element_class_name 字符串 元素样式名

$element_type 字符串 元素类型

$element_selector 字符串 元素选择器

$element_target_url 字符串 元素链接地址

$url 字符串 页面地址

$title 字符串 页面标题

$url_path 字符串 页面路径

$viewport_width 数值 视区宽度

1.2.1.1.4 Web 视区停留($WebStay)

字段名称 类型 说明

$viewport_width 数值 视区宽度

$viewport_position 数值 视区距顶部的位置

$viewport_height 数值 视区高度

event_duration 数值 视区停留时间

$url 字符串 页面地址

$title 字符串 页面标题

$url_path 字符串 页面路径

1.2.1.1.5 预置的用户属性 类型 说明

Datetime 首次访问时间

字段名称 字符串 首次前向地址

$first_visit_time 字符串 首次前向域名

$first_referrer 字符串 首次使用的浏览器语言

$first_referrer_host 字符串 首次浏览器字符类型(1.8 支持)

$first_browser_language 字符串 首次搜索引擎关键词(1.8 支持)

$first_browser_charset 字符串 首次流量来源类型(1.8 支持)

$first_search_keyword

$first_traffic_source_type

1.2.1.2 iOS 端全埋点预置属性

1.2.1.2.1 所有事件都会有的预置属性

字段名称 类型 显示名 说明

$app_version 字符串 应用版本 应用的版本

$lib 字符串 SDK 类型 例如 iOS

$lib_version 字符串 SDK 版本

$manufacturer 字符串 设备制造商 例如 Apple

$model 字符串 设备型号 例如 iPhone9,2

$os 字符串 操作系统 例如 iOS

$os_version 字符串 操作系统版本 例如 8.1.1

$screen_height 数值 屏幕高度 例如 1920

$screen_width 数值 屏幕宽度 例如 1080

$wifi BOOL 是否 wifi

$carrier 字符串 运营商名称 例如 ChinaNet

$network_type 字符串 网络类型 例如 4G

$is_first_day 布尔值 是否首日访问

默认获取 IDFA，获取失败则获取

$device_id 字符串 设备 ID IDFV，获取不到 IDFV 则获取 UUID。

屏幕当前的方向

$screen_orientation 字符串 屏幕方向 1 纬度*106

$latitude 数值 GPS 信息 2 经度*106

$longitude 数值 GPS 信息 2

1.2.1.2.2 App 启动($AppStart)

字段名称 类型 显示名 说明

$is_first_time BOOL 是否首次访问 App 安装后是否首

是否首日访问 次启动

$is_first_day BOOL 是否从后台唤醒 App 安装后是否首

日访问

$resume_from_background BOOL App 是否是从后台

恢复

1.2.1.2.3 App 退出($AppEnd)

字段名称 类型 显示名 说明

event_duration 数值 event_duration 本 次 App 启 动 的 使

用时长

1.2.1.2.4 App 浏览页面($AppViewScreen)

字段名称 类型 显示名 说明

$title 字符串 页面标题 ViewController 的标题

$screen_name 字符串 页面名称 ViewController 的类名

1.2.1.2.5 App 元素点击($AppClick)

字段名称 类型 显示名 说明

$element_type 字符串 元素类型 控件的类型，例如

UIButton

$element_content 字符串 元素内容 控件的内容

$title 字符串 页面标题 ViewController 的标题

$screen_name 字符串 页面名称 ViewController 的类名

$element_position 字符串 元素位置 元素被点击时所处的

位置

1.2.1.3 Android 端全埋点预置属性

1.2.1.3.1 所有事件都会有的预置属性

字段名称 类型 显示名 说明

$app_version 字符串 应用版本 应用的版本

$lib 字符串 SDK 类型 例如 Android

$lib_version 字符串 SDK 版本

$manufacturer 字符串 设备制造商 例如 Xiaomi

$model 字符串 设备型号 例如 Redmi 4X

$os 字符串 操作系统 例如 Android

$os_version 字符串 操作系统版本 例如 6.0.1

$screen_height 数值 屏幕高度 例如 1280

$screen_width 数值 屏幕宽度 例如 720

$wifi BOOL 是否 wifi

$carrier 字符串 运营商名称 例如 中国联通

$network_type 字符串 网络类型 例如 4G

$is_first_day 布尔值 是否首日访问

$device_id 字符串 设备 ID 获取值为 AndroidId

1.2.1.3.2 App 启动($AppStart) 类型 显示名 说明

BOOL 是否首次访问 App 安装后是否首次启动

段名称 BOOL 是否从后台唤醒 App 是否是从后台恢复

$is_first_time Activity 的 标 题 ( 仅

$resume_from_background Android 端有)

Activity 的 包 名 . 类 名 ( 仅

$title 字符串 页面标题 Android 端有)

$screen_name 字符串 页面名称

1.2.1.3.3 App 退出($AppEnd)

字段名称 类型 显示名 说明

event_duration 数值 event_duration 本次 App 启动的使用时长(此字段虽没

加 $ 符，也是预置字段)

$title 字符串 页面标题 Activity 的标题(仅 Android 端有)

$screen_name 字符串 页面名称 Activity 的包名.类名(仅 Android 端有)

1.2.1.3.4 App 浏览页面($AppViewScreen)

字段名称 类型 显示名 说明

$title 字符串 页面标题 Activity 的标题

$screen_name 字符串 页面名称 Activity 的包名.类名

1.2.1.3.5 App 元素点击($AppClick)

字段名称 类型 显示名 说明

$element_id 字符串 元素 ID 控件的 ID

$element_type 字符串 元素类型 控件的类型，例如 Button

$element_content 字符串 元素内容 控件的内容

$title 字符串 页面标题 Activity 的标题

$screen_name 字符串 页面名称 Activity 的包名.类名

元素被点击时所处的位

$element_position 字符串 元素位置 置

1.2.1.4 微信小程序全埋点预置属性

1.2.1.4.1 所有事件都有的预置属性

字段名称 类型 说明

$lib 字符串 SDK 类型

$lib_version 字符串 SDK 版本

$screen_height 数值 小程序屏幕高度

$screen_width 数值 小程序屏幕宽度

$model 字符串 设备型号

$manufacturer 字符串 设备制造商

$network_type 字符串 网络类型

$os 字符串 操作系统

$os_version 字符串 操作系统版本

$is_first_day 布尔类型 是否首日访问

SDK 发送数据请求携带的属

$ip 字符串

性

$country 字符串 由 IP 解析得到

$province 字符串 由 IP 解析得到

$city 字符串 由 IP 解析得到

$latest_utm_source 字符串 最近一次付费广告系列来源

$latest_utm_medium 字符串 最近一次付费广告系列媒介

$latest_utm_term 字符串 最近一次付费广告系列字词

$latest_utm_content 字符串 最近一次付费广告系列内容

$latest_utm_campaign 字符串 最近一次付费广告系列名称

$latest_scene 字符串 最近一次启动场景值

注意：1.$screen_height 在 1.11.1 版本之前字段名称为‘小程序窗口高度’,取的值是小程序可使用窗口高度

2.$screen_width 在 1.11.1 版本之前字段名称为‘小程序窗口宽度’,取的值是小程序可使用窗口宽度

1.2.1.4.2 小程序加载($MPLaunch)

字段名称 类型 说明

$scene 字符串 启动场景

$url_path 字符串 页面路径

$utm_source 字符串 广告系列来源

$utm_medium 字符串 广告系列媒介

$utm_term 字符串 广告系列字词

$utm_content 字符串 广告系列内容

$utm_campaign 字符串 广告系列名称

$is_first_time 布尔类型 是否首次访问

$share_distinct_id 字符串 分享时的 distinct_id

$share_depth 数值 分享次数

$share_url_path 字符串 分享时的页面路径

$url_query 字符串 页面参数

1.2.1.4.3 小程序启动($MPShow) 说明

启动场景

字段名称 类型 页面路径

$scene 字符串 广告系列来源

$url_path 字符串 广告系列媒介

$utm_source 字符串 广告系列字词

$utm_medium 字符串 广告系列内容

$utm_term 字符串 广告系列名称

$utm_content 字符串 分享时的 distinct_id

$utm_campaign 字符串 分享次数

$share_distinct_id 字符串 分享时的页面路径

$share_depth 数值 页面参数

$share_url_path 字符串

$url_query 字符串 说明

时长

1.2.1.4.4 小程序进入后台($MPHide) 页面路径

字段名称 类型 说明

event_duration NUMBER 页面路径

$url_path 字符串 前向页面地址

1.2.1.4.5 小程序页面浏览($MPViewScreen)

字段名称 类型

$url_path 字符串

$referrer 字符串

$utm_source 字符串 广告系列来源

$utm_medium 字符串 广告系列媒介

$utm_term 字符串 广告系列字词

$utm_content 字符串 广告系列内容

$utm_campaign 字符串 广告系列名称

$url_query 字符串 页面参数

1.2.1.4.6 小程序分享($MPShare)

字段名称 类型 说明

分享次数

$share_depth 数值 分享时的页面路径

$url_path 字符串

1.2.1.4.7 预置的用户属性

字段名称 类型 说明

首次访问时间

$first_visit_time Datetime 首次广告系列来源

首次广告系列媒介

$utm_source 字符串 首次广告系列字词

首次广告系列内容

$utm_medium 字符串 首次广告系列名称

$utm_term 字符串

$utm_content 字符串

$utm_campaign 字符串

1.2.1.5 客户端支持的第三方框架

1.2.1.5.1 React Native

神策 react-native-sensors-analytics 模块，封装了神策 Android & iOS SDK 常用 API ，使用此模块，可以在 React

Native 开发的 App 中完成埋点的统计上报。

1.2.1.5.2 Flutter

神策 sensors_analytics_flutter_plugin 插件，封装了神策 Android & iOS SDK 常用 API ，使用此插件，可以在 Flutter

开发的 App 中完成埋点的统计上报。

1.2.1.5.3 Weex

根据官方文档集成 weex 开发环境以及神策 Android & IOS SDK 即可。

1.2.1.5.4 第三方 H5 页面嵌入 JS

如果在 App 内(Android & IOS)有加载一些第三方 H5 页面。这些页面不能直接集成神策分析 JavaScript SDK，

如果需要获取这些页面对应的埋点信息，可使用如下方式实现。具体实现原理：通过 webView 向第三方 H5 页面

自动嵌入 JavaScript sdk ,当 H5 页面触发事件时，会直接把事件发往 App 端，App 端接收到数据后保存并上报。

1.2.2 服务端数据采集

对于服务端采集的行为数据，神策提供各种服务端语言的 SDK，如 Java ／ Python ／PHP ／ Ruby / C / CSharp

/ Golang / Node 等。

相比采集客户端采集，服务器端数据采集会有如下一系列的优势：

 传输时效性：如前面描述的那样，为了保证用户体验，前端采集数据是不能实时向后端发送的，所以会带

来传输时效性的问题，而采集后端日志就不存在这个问题；

 数据可靠性：前端采集需要通过公网进行数据传输，肯定会存在数据可靠性的问题，采集后端日志配合私

有部署，则可以做到纯内网传输数据，这一问题大大缓解；

 能够获取的信息丰富程度：有很多信息，例如商品库存、商品成本、用户风险级别、用户潜在价值等，在

前端都采集不到的，只能在后端采集。

正因为这一点，我们建议一个行为在前端和后端都可以采集时，优先在后端进行采集，并且为此提供了一系列的后

端语言 SDK、日志采集工具和数据批量导入工具等。

1.2.3 历史数据及日志导入

对于在使用神策前，已经积累了大量用户行为数据的企业，可以通过 ETL 程序将原有数据转换为神策的事件模型

的数据日志等，并使用神策提供的导入工具导入：

 FormatImporter：批量导入少量各种标准格式(JSON、CSV、MySQL 数据库表、Oracle 数据库表、Nginx 日

志数据等)的数据；

 BatchImporter／HDFSImporter：批量导入通过 ETL 脚本生成的，大量符合神策数据协议的 JSON 文件。

 LogAgent：实时导入通过 ETL 脚本生成的，大量符合神策数据协议的 JSON 文件。

1.2.4 全端用户打通

为完整地分析一个用户在不同数据源的行为，需要将同一个用户在 Web 界面、App、App 内嵌的 H5 页面 及 后

端程序 等不同数据源中分别采集的行为数据打通。

神策的事件模型中，使用 Distinct ID 标识每个独立的用户。通过在不同的端使用逻辑上相同的 Distinct ID ，可以

打通一个用户在不同端的用户行为数据。

 账号体系成熟的产品中，建议在各端使用 注册 ID 作为 Distinct ID，打通多端采集的数据；

 对于允许匿名使用的产品中，Android／iOS SDK 默认使用 设备 ID 作为 Distinct ID，例如 iOS 的 IDFA

／IDFV，Web 的 Cookie 等；

 当用户注册或登录后，可以使用 login() 接口，传入 注册 ID 作为 Distinct ID，同时将 注册 ID 与 匿

名 ID 进行关联；关联成功后，注册前的匿名用户和注册后的注册用户，将被识别为同一个用户，并打通

其用户行为数据，具体概述如下。

1.2.5 用户关联

为完整地分析一个用户在不同数据源的行为，需要将同一个用户在 Web 界面、App、App 内嵌的 H5 页面 及 后

端程序 等不同数据源中分别采集的行为数据打通。

神策的事件模型中，使用 Distinct ID 标识每个独立的用户。通过在不同的端使用逻辑上相同的 Distinct ID ，可以

打通一个用户在不同端的用户行为数据。

 账号体系成熟的产品中，建议在各端使用 注册 ID 作为 Distinct ID，打通多端采集的数据；

 对于允许匿名使用的产品中，Android／iOS SDK 默认使用 设备 ID 作为 Distinct ID，例如 iOS 的 IDFA

／IDFV，Web 的 Cookie 等；

 当用户注册或登录后，可以使用 login() 接口，传入 注册 ID 作为 Distinct ID，同时将 注册 ID 与 匿

名 ID 进行关联；关联成功后，注册前的匿名用户和注册后的注册用户，将被识别为同一个用户，并打通

其用户行为数据。

神策提供了多种用户关联方案，并且以下各方案之间互不兼容，请务必在正式接入之前选择一个最合适的方案。

方案一：只使用设备 ID

适用场景：适合没有用户注册体系，或者极少数用户会进行多设备登录的产品，如工具类产品、搜索引擎、部

分电商等。这也是绝大多数其它数据分析产品唯一提供的方案。

局限性：

1) 同一用户在不同设备使用会被认为不同的用户(神策 ID 不同，跟设备 ID 关联)，对后续的分析统计有

影响。

2) 不同用户在相同设备使用会被认为是一个用户(神策 ID 相同，因为设备 ID 相同)，也对后续的分析统

计有影响。

3) 但如果用户跨设备使用或者多用户共用设备不是产品的常见场景的话，可以忽略上述问题。

实施方法：直接使用客户端 SDK 产生的设备 ID 作为 distinct_id 即可，不需要进行特殊处理。如果不希望使

用神策 SDK 默认的设备 ID 生成规则，可以直接调用 identify 接口来传入自定义的设备 ID，该方法建议在 SDK 初

始化完成之后立即调用。如果是有用户注册体系的产品，可以额外在所有 Event 里加入 login_user_id 属性标识用

户的正式 ID，这样也可以筛选出某个用户的具体行为，或者单独看登录前/登录后的用户行为

仅使用设备 ID 标识用户虽然简单，但是对于某些应用场景这种方式不够准确，因此神策分析提供了另一种关联设

备 ID 和登录 ID 的方案，在一定程度上融合设备 ID 和登录 ID，从而实现更准确的用户追踪。

方案二：关联设备 ID 和登录 ID(一对一)

适用场景：成功关联设备 ID 和登录 ID 之后，用户在该设备 ID 上或该登录 ID 下的行为就会贯通，被认为

是一个神策 ID 发生的。在进行事件、漏斗、留存等用户相关分析时也会算作一个用户。

关联设备 ID 和登录 ID 的方法虽然实现了更准确的用户追踪，但是也会增加埋点接入的复杂度。所以一般来

说，我们建议只有当同时满足以下条件时，才考虑进行 ID 关联：

1、需要贯通一个用户在一个设备上注册前后的行为。

2、需要贯通一个注册用户在不同设备上登录之后的行为。

局限性：

1) 一个设备 ID 只能和一个登录 ID 关联，而事实上一台设备可能有多个用户使用。

2) 一个登录 ID 只能和一个设备 ID 关联，而事实上一个用户可能用一个登录 ID 在多台设备上登录。

3) 如果不遵循神策接口调用顺序，可能会导致部分用户标识异常(例如历史数据导入时)，影响数据统计的

准确性。

客户端实施方法：客户端接入是指使用 iOS / Android / JavaScript 等 SDK 进行埋点，具体调用流程如下：

1) 在 SDK 初始化完成之后，神策的 SDK 会自动生成一个设备 ID 作为用户标识。

2) 在用户进行登录/注册或任何可以拿到登录 ID 的操作的时候，客户端主动调用 login(登录 ID) 接口。

3) 在用户注销的时候，有几种选择：

a) 不做任何操作，这样的话相当于神策会继续使用之前的用户标识来进行追踪。如果没有特殊情况，一

般建议选择该方式。

b) 主动调用 logout()方法，这样会清空登录 ID，重新使用设备 ID 作为用户标识，一般情况没有必要选

择此方式。

c) 对于 JavaScript SDK，还可以调用 logout(true)方法，该方法除了清空登录 ID 之外，还会重新初始化设

备 ID。

服务端实施方法：

服务端接入包括使用 Java / Python / PHP 等 SDK，以及直接使用 BatchImporter / LogAgent / FormatImporter 等工具进

行导入的情况，具体流程如下：

1) 在进行服务端埋点或者历史数据导入时，如果当前在 track 或者 profile_set 等接口里传入的 distinct_id 是

一个登录 ID，那么 is_login_id 的参数值必须为 true，来告诉神策这是一个登录 ID 产生的行为。

2) 对于任意一个登录 ID，只要导入过任意数据，那么该登录 ID 后面将不能和任何设备 ID 进行关联。因此

在进行历史数据(即接入神策之前产生的数据)的导入时，建议按照下面的方式操作：

a) 先进行正常的 SDK 接入，并且保证所有用户都正常的通过了 login/track_signup 接口进行用户关联，

在运行一段时间之后再导入历史数据，因为这个时候大部分活跃用户都应该已经成功进行了关联。

b) 如果历史数据中存在登录 ID 和其对应设备 ID 的对应关系，那么也可以先把这批数据构造

track_signup 请求进行导入，然后再导入具体的用户行为或者用户属性数据即可。

3) 由于客户端埋点存在一定的数据丢失概率，我们建议开发者也在服务端的注册接口里调用 track_signup 方

法，将新用户的 设备 ID 和登录 ID 进行关联，以实现更准确的用户识别。

方案三：关联设备 ID 和登录 ID(多对一)

适用场景：一个用户在多个设备上进行登录是一种比较常见的场景，比如 Web 端和 APP 端可能都需要进行

登录。支持一个登录 ID 下关联多设备 ID 之后，用户在多设备下的行为就会贯通，被认为是一个神策 ID 发生的。

局限性：

1) 一个设备 ID 只能和一个登录 ID 关联，而事实上一台设备可能有多个用户使用。

2) 一个设备 ID 一旦跟某个登录 ID 关联或者一个登录 ID 和一个设备 ID 关联，就不能解除(自动解除)。

实施方法：客户端和服务端的实施方法与方案二完全相同，神策服务端的处理行为会不一样：对于已经关联过

设备的登录 ID，仍然可以和新的设备 ID 进行关联，并存入 users 表新增字段 $device_id_list (关联用户 id 列表)

中。

例⾏任务每天读取 users 表中需要修复的 id 列表，即 $device_id_list。读取过去 2 天的所有 events 数据，

找到需要修复的数据。修改其中的 user_id 字段与 profile 表中对应的 id 字段保持一致。

1.2.6 第三方用户标签导入

由于国家政策与监管等原因，我们本身不直接提供第三方用户标签数据，但是支持通过相应的工具与接口，对

接提供这类数据的第三方供应商，完成相应的数据采集与处理工作。

1.2.6.1 标签导入工具

标签独立导入工具，需要先按行分隔符“\n”分隔数据，每行一个 json 串准备好数据，并存放于 HDFS 之上。

再使用导入工具进行导入。

 SPImporter：批量导入标准格式 json 格式的数据；

1.2.7 数据采集实时性

神策提供的数据采集方案可以保证数据的实时采集，数据的数据采集思路如下

 客户端 SDK

客户端 SDK 在设计的时候，优先考虑的是用户的使用体验，保证数据在发送时，不会影响到终端用

户的使用情况。

普通模式

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 中尝试发送；

8) JavaScript SDK 不会记录数据缓存，每次产生新数据都会直接进行数据发送。

Debug 模式

1) 对于任何操作，无论什么网络条件，都会立即发送数据，并校验返回的验证结果。

2) 用户可以在任何时候，调用 flush 发送数据。当数据发送失败时，会继续缓存在本地，直到发送

成功。当缓存数据量过多时，不再缓存新数据。其中 Android 默认缓存数据量阈值为 32MB，iOS

为 10000 条。

 服务端 SDK

对于服务端 SDK 来说，每种 SDK 神策都会设计多种数据发送方式，来满足服务端的数据

发送需求：

1) ConcurrentLoggingConsumer

ConcurrentLoggingConsumer 主要是用于实时的进行生产数据发送，该方式下，每产生一条系

数据，均会被实时的写入指定的日志文件，然后通过神策提供的 LogAgent 实时导入工具，对日

志文件进行实时的数据导入，同时 LogAgent 还具备断点续传功能，能够完全避免因网络故障等

原因，造成的数据在发送过程中丢失。ConcurrentLoggingConsumer 也是神策在服务端 SDK 中，

主推的数据发送方式。

2) DebugConsumer

DebugConsumer 主要是在测试阶段用于校验数据是否正确，每通过操作产生一条数据，在该

方式下均会实时的进行数据发送。

3) DefaultConsumer

DefaultConsumer 主要是用于导入小规模历史数据，每读取到一条历史数据，在该方式下均会

被实时的进行数据发送。

4) BatchConsumer

BatchConsumer 主要是用于导入小规模历史数据，与 DefaultConsumer 不同的是，

BatchConsumer 允许用户设置发送的缓存条数，只有达到条数时，数据才会被进行发送。

 导入工具

1) 实时导入工具

神策设计的 LogAgent 是一款实时 tail 日志增量的导入工具，只要读取到日志的增量，就会

进行数据发送。同时改工具还提供断点续传功能，能够保证数据在发送的过程中不会出现因为网

络故障等外力造成的数据丢失。

2) 批量导入工具

神策设计了三款批量导入工具，分别是 Formatimporter、BatchImporter、HdfsImporter。三种工具能够定时批量

的读取分布在数据库、CSV 文件

1.3 OneID 体系逻辑

神策分析支持从多端进行数据导入，并且把不同端的用户行为全部打通。

基于神策分析提供的多种 SDK 和导入工具，可以把前端，如 App、Web 等。后端，如日志、数据库等多种数

据源全部导入到神策分析当中。

借助于“用户关联“和”全端用户打通“章节介绍的功能，神策构建起了基于 ID-Mapping 的 OneID 体系，

可以把用户在登录前后、不同设备的行为进行贯通。

ID-Mapping 方案：

 不同端可以自定义唯一的用户 ID：如设备 ID、Cookie Id、注册 ID 等；

 系统内部会生成唯一的 user_id 来识别用户；

 提供一次性的 login 或 track_signup 接口，将两个 ID 贯通起来，实现用户行为的前后打通。