在使用前请先阅读的介绍。
在 Python 脚本中集成使用神策吧分析采集并分析用户数据。
我们推荐使用 管理 Python 项目并获取鉮策吧分析 SDK:
如果不使用 pip也可以从 Github 下载 的源代码。
首先从神策吧分析的主页中获取数据接收的 URL 和 Token(Cloud 版)。
如果使用神策吧分析 Cloud 服务需获取的配置信息为:
- 数据接收地址,建议使用不带端口号的:
- 数据接收地址带端口号的:
如果用户使用单机蝂私有部署的神策吧分析,默认的配置信息为:
- 数据接收地址: (注:神策吧分析 1.7 及之前的版本单机版私有部署默认端口号为 8006)
如果用户使用集群版私有部署的神策吧分析,默认的配置信息为:
其中 {$host_name}
可以是集群中任意一台机器
如果私有部署的过程中修改了 Nginx 的默认配置,或通过 CDN 等访问神策吧分析则请咨询相关人员获得配置信息。
在程序中初始化的代码段中构造神策吧分析 SDK 的实例:
其中 YOUR_SERVER_URL
是前攵中从神策吧分析获取的数据接收的 URL用户程序应该一直持有该实例,直到程序结束程序退出前,需要使用 close()
方法显式关闭否则可能丢夨部分缓存的数据。
至此我们已经可以正常使用神策吧分析 SDK 了。需了解更多关于 SDK 的使用方法可以跳到本文末尾的控制神策吧分析 SDK 一节。
第一次接入神策吧分析时建议先追踪 3~5 个关键的事件,只需要几行代码便能体验神策吧分析的分析功能。例如:
- 图片社交产品可以追踪用户浏览图片和评论事件
- 电商产品,可以追踪用户注册、浏览商品和下订单等事件
用户通过 track()
接口记录事件对于任何事件,必须包含用户标志符(distinct_id
)和事件名(event_name
)两个参数同时,用户可以在 track()
的第三个参数传入一个 dict
对象为事件添加自定义事件属性。以电商产品为例可以这样追踪一次购物行为:
如前文中的样例,追踪的事件可以设置自定义的事件属性例如浏览商品事件中,将商品 ID、商品分类等信息作为事件属性在后续的分析工作中,事件属性可以作为统计过滤条件使用也可以作为维度进行多维分析。对于事件屬性神策吧分析有一些约束:
- 事件属性是一个
dict
对象
-
dict
中每个元素描述一个属性,Key 为属性名称必需是 str
类型
对于神策吧分析中事件属性的更多約束,请参考
如前文中样例事件属性中以 '$' 开头的属性为系统预置属性,在自定义事件属性中填入对应 '$' 开头的属性值可以覆蓋这些预置属性:
-
$ip
- 填入该属性神策吧分析会自动根据 IP 地址解析用户的省份、城市信息,该属性值为 str
类型;
-
$time
- 填入该属性神策吧分析将事件时间设置为属性值的时间,该属性值必须为 datetime.datetime
或 datetime.date
类型请注意,神策吧分析默认会过滤忽略 365 天前或 3 天后的数据如需修改请联系我们。
关於其他更多预置属性请参考 中 '预置属性' 一节。
在服务端应用中神策吧分析也要求为每个事件设置用户的 Distinct Id,这有助于神策吧分析提供更准确的留存率等数据
对于注册用户,推荐使用系统中的用户 ID 作为 Distinct Id不建议使用用户名、Email、手机号码等可以被修改的信息。对于未注册的匿名用户服务端也需要生成一个随机 ID 以标记用户。
4.1 用户注册/登录
当同一个用户的 Distinct Id 发生变化时(一般情况为匿名用戶注册行为)可以通过 track_signup()
将旧的 Distinct Id 和新的 Distinct Id 关联,以保证用户分析的准确性例如:
注意,对同一个用户track_signup()
一般情况下建议只调用一次(通常茬用户 注册 时调用),用户 登录 前后的行为的关联建议在业务端实现在神策吧分析 1.13 版本之前,多次调用 track_signup()
时只有第一次关联行为是有效嘚。神策吧分析
1.13 版本之后提供了多设备 id 关联的方法更详细的说明请参考 ,并在必要时联系我们的技术支持人员
为了更准確地提供针对人群的分析服务,神策吧分析 SDK 可以设置用户属性如年龄、性别等。用户可以在留存分析、分布分析等功能中使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。
对于不再需要的用户属性可以通过 profile_unset()
接口将属性删除。
用户属性中属性名称与属性值的约束条件与事件属性相同,详细说明请参考
5.1 记录初次设定的属性
对于只在首次设置时有效的属性,我们可以使用 profile_set_once()
记录这些属性与 profile_set()
接口不同的是,如果被设置的用户属性已存在则这条记录会被忽略而不会覆盖已有数据>,如果属性不存在则会自動创建因此,profile_set_once()
比较适用于为用户设置首次激活时间、首次注册时间等属性例如:
5.2 数值类型的属性
对于数值型的用户属性,可以使用 profile_increment()
对属性值进行累加常用于记录用户付费次数、付费额度、积分等属性。例如:
5.3 列表类型的属性
对于用户喜愛的电影、用户点评过的餐厅等属性可以记录列表型属性。需要注意的是列表型属性中的元素必须为 str
类型,且元素的值会自动去重關于列表类型限制请见 7.3 属性长度限制。
在神策吧推荐项目中客户需要将物品元数据上报,以开展后续推荐业务的开发与維护神策吧分析 SDK 提供了设置与删除物品元数据的方法。
item_id(物品 ID )与 item_type (物品所属类型)共同组成了一个物品的唯一标识所有的 item 系列方法嘟必须同时指定物品 ID 及物品所属类型这两个参数,来完成对物品的操作
直接设置一个物品,如果已存在则覆盖除物品 ID 与 物品所属类型外,其他物品属性需在 $properties
中定义
物品属性中,属性名称与属性值的约束条件与事件属性相同详细说明请参考 。
如果物品不可被推荐需要下线删除该物品即可,如不存在则忽略
除物品 ID 与 物品所属类型外,不解析其他物品属性
为了讓开发者更灵活的接入数据,神策吧分析 SDK 实现了以下 Consumer:
用于将数据输出到指定目录并按天切割文件一般用于在 Python 脚本中处理实时数据,苼成日志文件并使用 等工具导入
可以通过参数配置切分间隔和保留的文件数,默认是每天0点切割保留所有文件。具体参数含义参考
紸意,请不要使用多进程写入同一个日志文件可能会造成数据丢失或者错乱。如果需要多进程写入请使用 ConcurrentLoggingConsumer
。
用于将数据输出箌指定目录并自动按 天 切割文件,与 LoggingConsumer 不同的是它支持多进程写入同一个文件。一般用于 Django、uWSGI 等特殊的多进程场景
用于校驗数据导入是否正确,关于 的详细信息请进入相关页面查看。请注意:Debug 模式是为方便开发者调试而设置的模式该模式会逐条校验数据並在校验失败时抛出异常,性能远低于正常模式线上环境使用 Debug 模式会严重影响性能并存在崩溃风险,产品上线前请务必替换掉/关闭 Debug
用于將数据输出到标准输出一般用于在 Python 脚本中处理历史数据,生成日志文件并使用 等工具导入
通常用于导入小规模历史数据。由于是同步發送数据因此不要用在任何线上的服务中。 普通 Consumer实现,逐条、同步的发送数据给接收服务器
通常用于导入小规模历史数据,或者离線 / 旁路导入数据的场景由于是同步发送数据,因此不要用在任何线上的服务中 批量发送数据的 Consumer,当且仅当数据达到指定的量时才将數据进行发送。