pyramid-mixpanel 0.13.0

将您的 Pyramid 应用程序与 Mixpanel 集成，以了解您的用户是谁以及他们如何使用您的应用程序。

具有偏见的Mixpanel（和Customer.io）集成

此软件包存在的原因是在集成Mixpanel时提供合理的默认值。您无需追查事件名称错误并调试跟踪为何不工作，而是可以专注于了解对用户重要的事情。

• 您在Mixpanel中 永远不会出现事件名称拼写错误，因为每个事件名称都来自数据类，而不是可能错误拼写的字符串。
• 同样，属性也是如此。与事件一样，属性 硬编码为数据类。
• 所有“特殊”和“保留”事件和属性都已经提供，无需在各种 Mixpanel 文档中寻找。
• 如果你的 Mixpanel 服务器出现故障，你的应用仍然可以继续工作，但你的日志中仍然会有错误，这样你就能知道发生了什么。
• 你永远不会忘记在事件缓冲区上调用 flush()，因为 pyramid_mixpanel 将挂钩到请求生命周期，并在请求处理结束时调用 flush()。
• 你将事件发送推迟到整个请求成功处理后，即如果添加事物到数据库在请求生命周期的后期阶段失败，则永远不会发送“用户添加了事物”等事件。

注意：截至 2021 年底，Mixpanel 将停止维护他们的邮件消息功能。由于我们在Niteo上大量依赖这些功能，我们正在将 Customer.io 集成到这个库中，以替代 Mixpanel 的邮件消息功能。如果你不想使用 Customer.io，对你来说没有任何变化，只需像往常一样继续使用 pyramid_mixpanel。如果你想使用 Customer.io，那么以 pyramid_mixpanel[customerio] 的方式安装此包，并添加以下注册设置。然后，所有 profile_set 和 track 调用将自动复制到 Customer.io。其他调用，如 profile_append，将仅发送到 Mixpanel。

customerio.tracking.site_id: <secret>
customerio.tracking.api_key: <secret>
customerio.tracking.region: <eu OR us>

如果你想要跳过将某些 track 或 profile_set 调用发送到 Customer.io，请在函数参数中添加 skip_customerio=True。

功能

• 基于 https://mixpanel.github.io/mixpanel-python/ 构建。
• 提供方便的 request.mixpanel.* 辅助函数，用于发送事件和设置配置文件属性。
• 确保在请求生命周期的末尾调用 .flush()。
• 提供事件和属性的数据类，以避免输入错误。
• 你可以自己实现一个 Consumer，例如一个安排后台任务发送事件的消费者，以提高请求处理速度，因为 HTTP 请求到 Mixpanel 已经被转移到后台任务。
• 提供 MixpanelQuery 辅助函数，使用 JQL 查询 Mixpanel 数据。包括获取电子邮件的配置文件等常见查询。
• 在本地开发和单元测试中，所有消息都存储在 request.mixpanel.mocked_messages 中的普通字典中。这使得编写集成测试变得简单。默认情况下，这些字典省略了“库”属性，如 token、time、mp_lib 等，以使测试更加简洁。如果需要，将 MockedConsumer.DROP_SYSTEM_MESSAGE_PROPERTIES 设置为 True。
• 如果存在 request.user，则自动设置 Mixpanel 跟踪 distinct_id。否则，你需要手动设置它，使用 request.mixpanel.distinct_id = 'foo'。

入门

1. 在 Pyramid 项目中将 pyramid_mixpanel 声明为依赖项。

2. 包括以下行

   config.include("pyramid_mixpanel")
   

3. 告诉 mixpanel_mixpanel 你想如何使用它

   # for local development and unit testing
   # events will be stored in request.mixpanel.mocked_messages
   mixpanel.token = false
   
   # minimal configuration
   mixpanel.token = <TOKEN>
   
   # enable support for querying Mixpanel data
   mixpanel.api_secret = <SECRET>
   
   # custom events and properties
   mixpanel.events = myapp.mixpanel.Events
   mixpanel.event_properties = myapp.mixpanel.EventProperties
   mixpanel.profile_properties = myapp.mixpanel.ProfileProperties
   
   # defer sending of Mixpanel messages to a background task queue
   mixpanel.consumer = myapp.mixpanel.QueuedConsumer
   
   # enable logging with structlog
   pyramid_heroku.structlog = true
   

对于处理请求的视图代码，有一个预先配置的 request.mixpanel 可用。

设计防御

pyramid_openapi3 的作者认为，尽管 Mixpanel 允许发送无模式的数据库，这些数据库可以随着项目需求的变化而变化，但最好更精确地说明你发送的“事件”以及这些事件的属性将如何命名。同样适用于“配置文件”。以下是我们在 Niteo 使用 Mixpanel 5 年积累的一些原因

a) 事件和属性名称会有输入错误。这会弄乱你的 Mixpanel 仪表板，并减慢你的操作速度。

b) 您的代码库中不同部分发送的类似动作将有不同名称的事件。然后在您的Mixpanel仪表板上，您将看到“用户点击按钮”和“按钮点击”事件，您将不确定使用哪个，以及它们之间的区别。

c) 您的事件和属性名称将不会一致，因为它们将来自您的代码库的不同部分，由不同的作者发送。由于一些事件将使用过去时态（用户登录），一些将使用全部小写（生成的发票），一些仅使用动作动词（点击）等，您的Mixpanel仪表板会感觉有些“破损”。

以上所有问题都可通过使用此包得到缓解，因为所有事件和属性名称都定义为数据类，以一种单一事实来源的方式。一旦完成初始规范，就不可能出现错别字。由于所有事件和属性名称都在一个文件中，您可以立即识别出不良的命名模式。

命名最佳实践

为了拥有良好且一致的事件和属性名称，此包的作者建议在构思名称时使用以下指南：

• 使用<item> <action>格式，即过去时态，例如按钮点击、页面查看、文件下载。
• 使用标题大小写。
• 前端仅发送两个Mixpanel事件：按钮/链接点击和页面查看。然后我们根据按钮名称、URL等在Mixpanel仪表板中构建自定义事件，例如密码重置按钮点击或定价页面查看。自定义事件可以事后修改，常规事件则不能。
• 后端发送“动作”事件，当这些动作成功完成时，例如网站部署、PDF生成、备份完成。
• 更多关于https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/。

运行测试

您需要在您的机器上安装pipenv和Python 3.7。然后您可以运行：

$ make tests

相关包

这些包位于同一问题空间

• pyramid_mixpanel的旧版本由@hadrien提出了一些巧妙的思想，尽管这个项目是一个完全重写；
• 官方的mixpanel-python是一个底层库，该项目依赖于它；
• 大部分已弃用的Mixpanel-api用于查询数据，已被JQL取代；
• mixpanel-jql提供了一个Pythonic接口来编写JQL查询。

野外的使用

一些在生产中使用pyramid_mixpanel的项目

• WooCart - 管理WooCommerce服务。
• EasyBlogNetworks - PBN托管和自动维护。
• Kafkai - 人工智能生成内容。

更改日志

0.13.0 (2024-03-08)

• MixpanelQuery.profile_by_email在找到多个与给定电子邮件相关的配置文件时引发一个名为MultipleProfilesFoundException的自定义异常。异常包含电子邮件和找到的所有配置文件，以便客户端可以按需处理异常。[karantan]

0.12.0 (2022-03-22)

• 彻底重构了测试支持，以使用更易于阅读的断言。这是现有测试用例的破坏性更改。[zupo]

0.11.0 (2022-02-10)

• 支持跳过对Customer.io的任意track/profile_set调用。[zupo]

0.10.2 (2021-12-13)

• Customer.io期望主要“注册”时间戳以created_at的形式发送。[zupo]

0.10.1 (2021-12-13)

• 通过重新应用0.9.1中的修复来修复另一个brownbag发布。[zupo]

0.10.0 (2021-12-13)

• 支持 Mixpanel 和 Customer.io 之间的不同日期格式。[zupo]

0.9.1 (2021-09-24)

• 通过修复 extras 的定义来修复 brownbag 发布。[zupo]

0.9.0 (2021-09-24)

• 添加对 Customer.io 的可选支持。[zupo]

0.8.0 (2020-05-11)

• 使 structlog 可选。[am-on]

• 支持从 HTTP 头中设置事件属性。[am-on]

0.7.0 (2019-12-19)

• 添加了对 people_union() 的支持。[am-on]

• 添加了 sayanarijit/typecov。[sayanarijit]

0.6.0 (2019-08-26)

• 添加了对配置自定义 Consumer 的支持。[zupo]

0.5.0 (2019-08-25)

• 要求所有 Consumer 实现一个 flush() 方法。[zupo]

0.4.3 (2019-08-24)

• 在包中包含 py.typed，第三次是幸运的？[zupo]

0.4.2 (2019-08-24)

• 在包中包含 py.typed，现在是真的。[zupo]

0.4.1 (2019-08-24)

• 在包中包含 py.typed。[zupo]

0.4.0 (2019-08-19)

• 为重写的 PYPI 发布做准备。[zupo]

• 小的性能优化。[zupo]

0.3.0 (2019-08-09)

• 添加确保发送到 MixpanelTrack 的参数有效的保护。[zupo]

• 不要让日志充满 "mixpanel 已配置" 的消息。[zupo]

• 支持 people_append 方法。[suryasr007]

• 大量清理遗留假设。

  • profile_sync 方法已被删除。
  • request.user 不再需要。
  • MixpanelTrack 初始化现在接受 distinct_id 而不是 user。
  • state ProfileProperty 不再需要。[zupo]

0.2.1 (2019-07-28)

• 并非所有消费者都有 .flush() 方法。[zupo]

0.2.0 (2019-07-27)

• 基于 Niteo 在生产中使用 Mixpanel 5 年的经验进行重写。[@zupo, @vanclevstik, @dz0ny, @karantan, @am-on, @rokcarl]

0.1.14 - 0.1.65 (2012-2014)

• 由 @hadrien 开发的遗留版本。