integration-flask

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for Flask

Flask应用的PostHog集成

This skill helps you add PostHog analytics to Flask applications.

本技能可帮助你为Flask应用添加PostHog分析功能。

Workflow

集成流程

Follow these steps in order to complete the integration:

```
basic-integration-1.0-begin.md
```
- PostHog Setup - Begin ← Start here
```
basic-integration-1.1-edit.md
```
- PostHog Setup - Edit
```
basic-integration-1.2-revise.md
```
- PostHog Setup - Revise
```
basic-integration-1.3-conclude.md
```
- PostHog Setup - Conclusion

请按以下步骤完成集成：

```
basic-integration-1.0-begin.md
```
- PostHog设置 - 开始 ← 从此处启动
```
basic-integration-1.1-edit.md
```
- PostHog设置 - 编辑
```
basic-integration-1.2-revise.md
```
- PostHog设置 - 修订
```
basic-integration-1.3-conclude.md
```
- PostHog设置 - 总结

Reference files

参考文件

```
references/EXAMPLE.md
```
- Flask example project code
```
references/flask.md
```
- Flask - docs
```
references/identify-users.md
```
- Identify users - docs

references/basic-integration-1.0-begin.md

- PostHog setup - begin

references/basic-integration-1.1-edit.md

- PostHog setup - edit

references/basic-integration-1.2-revise.md

- PostHog setup - revise

references/basic-integration-1.3-conclude.md

- PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

```
references/EXAMPLE.md
```
- Flask示例项目代码
```
references/flask.md
```
- Flask - 文档
```
references/identify-users.md
```
- 用户识别 - 文档

references/basic-integration-1.0-begin.md

- PostHog设置 - 开始

references/basic-integration-1.1-edit.md

- PostHog设置 - 编辑

references/basic-integration-1.2-revise.md

- PostHog设置 - 修订

references/basic-integration-1.3-conclude.md

- PostHog设置 - 总结

示例项目展示了目标实现模式。如需了解API细节，请查阅相关文档。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.

环境变量：始终使用环境变量存储PostHog密钥，绝不要硬编码。
最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴近示例项目的模式。

Framework guidelines

框架指南

Initialize PostHog globally in create_app() using posthog.api_key and posthog.host (NOT per-request)
Manually capture exceptions with
```
posthog.capture_exception(e)
```
for error tracking since Flask has built-in error handlers
Blueprint registration happens AFTER PostHog initialization in create_app()
Remember that source code is available in the venv/site-packages directory
posthog is the Python SDK package name
Install dependencies with
```
pip install posthog
```
or
```
pip install -r requirements.txt
```
and do NOT use unquoted version specifiers like
```
>=
```
directly in shell commands
In CLIs and scripts: MUST call posthog.shutdown() before exit or all events are lost
Always use the Posthog() class constructor (instance-based API) instead of module-level posthog.api_key config
Always include enable_exception_autocapture=True in the Posthog() constructor to automatically track exceptions
NEVER send PII in capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content
PII belongs in identify() person properties, NOT in capture() event properties. Safe event properties are metadata like message_length, form_type, boolean flags.
Register posthog_client.shutdown with atexit.register() to ensure all events are flushed on exit
The Python SDK has NO identify() method — use posthog_client.set(distinct_id=user_id, properties={...}) to set person properties, or use identify_context(user_id) within a context

在create_app()中全局初始化PostHog，使用posthog.api_key和posthog.host（不要在每次请求时初始化）
由于Flask有内置错误处理器，需使用
```
posthog.capture_exception(e)
```
手动捕获异常以进行错误追踪
在create_app()中完成PostHog初始化后再注册Blueprint
请记住源代码位于venv/site-packages目录中
posthog是Python SDK的包名
使用
```
pip install posthog
```
或
```
pip install -r requirements.txt
```
安装依赖，请勿在shell命令中直接使用不带引号的版本说明符（如
```
>=
```
）
在CLI和脚本中：退出前必须调用posthog.shutdown()，否则所有事件都会丢失
始终使用Posthog()类构造函数（基于实例的API），而非模块级的posthog.api_key配置
在Posthog()构造函数中始终包含enable_exception_autocapture=True，以自动追踪异常
绝不要在capture()事件属性中发送PII（个人可识别信息）——包括邮箱、全名、电话号码、物理地址、IP地址或用户生成内容
PII应放在identify()用户属性中，而非capture()事件属性中。安全的事件属性是元数据，如message_length、form_type、布尔标志等
使用atexit.register()注册posthog_client.shutdown，确保退出时所有事件都能被刷新
Python SDK没有identify()方法——使用posthog_client.set(distinct_id=user_id, properties={...})设置用户属性，或在上下文内使用identify_context(user_id)

Identifying users

用户识别

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using

X-POSTHOG-DISTINCT-ID

and

X-POSTHOG-SESSION-ID

headers to maintain correlation.

在登录和注册事件中识别用户。请参考示例代码和文档，了解适用于此框架的正确识别模式。如果同时存在前端和后端代码，请使用

X-POSTHOG-DISTINCT-ID

和

X-POSTHOG-SESSION-ID

头传递客户端会话和唯一ID，以保持关联。

Error tracking

错误追踪

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

为相关文件添加PostHog错误追踪，尤其是关键用户流程和API边界相关的文件。