integration-django

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for Django

适用于Django的PostHog集成

This skill helps you add PostHog analytics to Django applications.

本技能可帮助你为Django应用添加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
```
- Django example project code
```
references/django.md
```
- Django - 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
```
- Django示例项目代码
```
references/django.md
```
- Django文档
```
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

框架指南

Add 'posthog.integrations.django.PosthogContextMiddleware' to MIDDLEWARE it auto-extracts tracing headers and captures exceptions
Initialize PostHog in AppConfig.ready() with api_key and host from environment variables
Use the context API pattern with new_context(), identify_context(user_id), then capture()
For login/logout views, create a new context since user state changes during the request
Do NOT create custom middleware, distinct_id helpers, or conditional checks - the SDK handles these
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

将
```
posthog.integrations.django.PosthogContextMiddleware
```
添加到MIDDLEWARE中，它会自动提取追踪头并捕获异常
在AppConfig.ready()中使用环境变量中的api_key和host初始化PostHog
使用上下文API模式：先调用new_context()，再调用identify_context(user_id)，最后调用capture()
对于登录/登出视图，由于请求期间用户状态会变化，需创建新的上下文
不要创建自定义中间件、distinct_id辅助工具或条件检查——这些由SDK处理
请记住源代码位于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边界附近的文件。