diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/.posthog-wizard b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/.posthog-wizard new file mode 100644 index 00000000..e69de29b diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/SKILL.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/SKILL.md new file mode 100644 index 00000000..d09f9628 --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/SKILL.md @@ -0,0 +1,64 @@ +--- +name: integration-fastapi +description: PostHog integration for FastAPI applications +metadata: + author: PostHog + version: dev +--- + +# PostHog integration for FastAPI + +This skill helps you add PostHog analytics to FastAPI applications. + +## Workflow + +Follow these steps in order to complete the integration: + +1. `references/1-begin.md` - PostHog Setup - Begin ← **Start here** +2. `references/2-edit.md` - PostHog Setup - Edit +3. `references/3-revise.md` - PostHog Setup - Revise +4. `references/4-conclude.md` - PostHog Setup - Conclusion + +## Reference files + +- `references/EXAMPLE.md` - FastAPI example project code +- `references/1-begin.md` - Start the event tracking setup process by analyzing the project and creating an event tracking plan +- `references/2-edit.md` - Implement PostHog event tracking in the identified files, following best practices and the example project +- `references/3-revise.md` - Review and fix any errors in the PostHog integration implementation +- `references/4-conclude.md` - Review and fix any errors in the PostHog integration implementation +- `references/python.md` - Python - docs +- `references/identify-users.md` - Identify users - docs + +The example project shows the target implementation pattern. Consult the documentation for API details. + +## 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. + +## Framework guidelines + +- Initialize PostHog in the lifespan context manager on startup using posthog.api_key and posthog.host +- Call posthog.flush() in the lifespan shutdown to ensure all events are sent before the app exits +- Use Pydantic Settings with @lru_cache decorator on get_settings() for caching and easy test overrides +- Use FastAPI dependency injection (Depends) for accessing current_user and settings in route handlers +- Use the same context API pattern as Flask/Django (with new_context(), identify_context(user_id), then capture()) +- 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 + +## 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. + +## Error tracking + +Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries. diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/1-begin.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/1-begin.md new file mode 100644 index 00000000..55f0a832 --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/1-begin.md @@ -0,0 +1,56 @@ +--- +title: PostHog Setup - Begin +description: Start the event tracking setup process by analyzing the project and creating an event tracking plan +--- + +We're making an event tracking plan for this project. + +This is the first of several phases — plan the events, implement them, revise and validate changes, then conclude by creating a dashboard and writing a setup report. + +## Task list + +As soon as you've read this description and have a rough sense of the work, make a single **call `TaskCreate` immediately** before reading any reference file or beginning analysis. The user is watching the task pane and shouldn't see it sit empty. + +It's fine if your first list is incomplete or imprecise. Seed it with whatever high-level items you can infer from the overview above, then call `TaskCreate` again (or `TaskUpdate` to refine existing items) every time your understanding sharpens: after a phase reveals work you didn't anticipate, after planning surfaces concrete sub-items, after you hit something new. Use `TaskUpdate` to mark items `in_progress` when you start them and `completed` when you finish. Keeping the list current matters more than getting it right on the first call. + +Keep task titles broad and job-oriented. Describe the purpose or area of work with wording like "Planning event tracking", "Identifying users", "Installing PostHog", "Capturing events", or "Creating dashboards", not the specific files, paths, or symbols involved. Adjust the task names according to the user's project and context. + +Before proceeding, find any existing `posthog.capture()` code. Make note of event name formatting. + +From the project's file list, select between 10 and 15 files that might have interesting business value for event tracking, especially conversion and churn events. Also look for additional files related to login that could be used for identifying users, along with error handling. Read the files. If a file is already well-covered by PostHog events, replace it with another option. Do not spawn subagents. + +Look for opportunities to track client-side events. + +**IMPORTANT: Server-side events are REQUIRED** if the project includes any instrumentable server-side code. If the project has API routes (e.g., `app/api/**/route.ts`) or Server Actions, you MUST include server-side events for critical business operations like: + + - Payment/checkout completion + - Webhook handlers + - Authentication endpoints + +Do not skip server-side events - they capture actions that cannot be tracked client-side. + +Create a new file with a JSON array at the root of the project: .posthog-events.json. It should include one object for each event we want to add with these exact field names: `event_name` (the event name), `event_description` (one sentence), and `file` (the file path the event goes in). The wizard reads this file to surface the plan in the UI. If events already exist, don't duplicate them; supplement them. + +Track actions only, not pageviews. These can be captured automatically. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel. + +As you review files, make an internal note of opportunities to identify users and catch errors. We'll need them for the next step. + +## Status + +Before beginning a phase of the setup, you will send a status message with the exact prefix '[STATUS]', as in: + +[STATUS] Checking project structure. + +Status to report in this phase: + +- Checking project structure +- Verifying PostHog dependencies +- Generating events based on project + +## Abort statuses + +If and only if the instructions have `[ABORT]` states specified, and you clearly match the conditions for an abort, emit the abort message. Do NOT attempt to exit or halt yourself — the wizard's middleware catches `[ABORT]` and terminates the run for you. + +--- + +**Upon completion, continue with:** [2-edit.md](2-edit.md) \ No newline at end of file diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/2-edit.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/2-edit.md new file mode 100644 index 00000000..e5f7ffd1 --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/2-edit.md @@ -0,0 +1,36 @@ +--- +title: PostHog Setup - Edit +description: Implement PostHog event tracking in the identified files, following best practices and the example project +--- + +For each of the files and events noted in .posthog-events.json, make edits to capture events using PostHog. Make sure to set up any helper files needed. Carefully examine the included example project code: your implementation should match it as closely as possible. Do not spawn subagents. + +Use environment variables for PostHog keys. Do not hardcode PostHog keys. + +If a file already has existing integration code for other tools or services, don't overwrite or remove that code. Place PostHog code below it. + +For each event, add useful properties, and use your access to the PostHog source code to ensure correctness. You also have access to documentation about creating new events with PostHog. Consider this documentation carefully and follow it closely before adding events. Your integration should be based on documented best practices. Carefully consider how the user project's framework version may impact the correct PostHog integration approach. + +Remember that you can find the source code for any dependency in the node_modules directory. This may be necessary to properly populate property names. There are also example project code files available via the PostHog MCP; use these for reference. + +Where possible, add calls for PostHog's identify() function on the client side upon events like logins and signups. Use the contents of login and signup forms to identify users on submit. If there is server-side code, pass the client-side session and distinct ID to the server-side code to identify the user. On the server side, make sure events have a matching distinct ID where relevant. + +It's essential to do this in both client code and server code, so that user behavior from both domains is easy to correlate. + +You should also add PostHog exception capture error tracking to these files where relevant. + +Remember: Do not alter the fundamental architecture of existing files. Make your additions minimal and targeted. + +Remember the documentation and example project resources you were provided at the beginning. Read them now. + +## Status + +Status to report in this phase: + +- Inserting PostHog capture code +- A status message for each file whose edits you are planning, including a high level summary of changes +- A status message for each file you have edited + +--- + +**Upon completion, continue with:** [3-revise.md](3-revise.md) \ No newline at end of file diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/3-revise.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/3-revise.md new file mode 100644 index 00000000..3b07f506 --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/3-revise.md @@ -0,0 +1,22 @@ +--- +title: PostHog Setup - Revise +description: Review and fix any errors in the PostHog integration implementation +--- + +Check the project for errors. Read the package.json file for any type checking or build scripts that may provide input about what to fix. Remember that you can find the source code for any dependency in the node_modules directory. Do not spawn subagents. + +Ensure that any components created were actually used. + +Once all other tasks are complete, run any linter or prettier-like scripts found in the package.json, but ONLY on the files you have edited or created during this session. Do not run formatting or linting across the entire project's codebase. + +## Status + +Status to report in this phase: + +- Finding and correcting errors +- Report details of any errors you fix +- Linting, building and prettying + +--- + +**Upon completion, continue with:** [4-conclude.md](4-conclude.md) \ No newline at end of file diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/4-conclude.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/4-conclude.md new file mode 100644 index 00000000..d876d435 --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/4-conclude.md @@ -0,0 +1,57 @@ +--- +title: PostHog Setup - Conclusion +description: Review and fix any errors in the PostHog integration implementation +--- + +Use the PostHog MCP to create a new dashboard named "Analytics basics (wizard)" based on the events created here. Keep the `(wizard)` tag with that exact casing so anyone browsing PostHog can see the wizard created this dashboard, and so a quick search for `(wizard)` surfaces every wizard-created artifact in one go. Make sure to use the exact same event names as implemented in the code. Populate it with up to five insights, with special emphasis on things like conversion funnels, churn events, and other business critical insights. + +Once the dashboard exists, emit its URL on its own line in your assistant message using this exact marker: `[DASHBOARD_URL] `. The wizard parses this marker from your visible message and surfaces the link in the success summary. Mentioning the URL only in thinking or in prose without the marker means the link is dropped. + +Search for a file called `.posthog-events.json` and read it for available events. + +Do not spawn subagents. + +Create the file posthog-setup-report.md. It should include a summary of the integration edits, a table with the event names, event descriptions, and files where events were added, a list of links for the dashboard and insights created, and a "Verify before merging" checklist (see below). Follow this format: + + +# PostHog post-wizard report + +The wizard has completed a deep integration of your project. [Detailed summary of changes] + +[table of events/descriptions/files] + +## Next steps + +We've built some insights and a dashboard for you to keep an eye on user behavior, based on the events we just instrumented: + +[links] + +## Verify before merging + +[checklist] + +### Agent skill + +We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code. This will help ensure the model provides the most up-to-date approaches for integrating PostHog. + + + +For the "Verify before merging" checklist, write GitHub-style checkboxes (`- [ ] ...`) covering what the developer (or their coding agent) still needs to do to take this from "wizard finished" to "merged". Include ONLY the items that actually apply to the integration you just performed — judge each against the code you changed in this run, and drop any that don't fit. Phrase each item as a concrete, checkable action. Candidate items, with the condition for including each: + +- Always: "Run a full production build (the wizard only verified the files it touched) and fix any lint or type errors introduced by the generated code." +- Always: "Run the test suite — call sites that were rewritten or instrumented may need updated mocks or fixtures." +- If you added environment variables: "Add the exact PostHog env var names you added to `.env.example` and any monorepo/bootstrap scripts so collaborators know what to set." +- If this integration ships a minified production browser bundle (most SPA/SSR web frameworks — e.g. Next.js, Nuxt, SvelteKit, Astro, Vite-based apps): "Wire source-map upload (`posthog-cli sourcemap` or your bundler's upload step) into CI so production stack traces de-minify." +- If LLM analytics was set up in this run: "Trigger the LLM call path(s) you instrumented and confirm `$ai_generation` events appear in PostHog AI Observability." +- If the app has user auth and an `identify` call was added: "Confirm the returning-visitor path also calls `identify` — a handler that only identifies on fresh login can leave returning sessions on anonymous distinct IDs." + +Do not invent items beyond what applies. If only the two "Always" items apply, the checklist is just those two. + +Upon completion, remove .posthog-events.json. + +## Status + +Status to report in this phase: + +- Configured dashboard: [insert PostHog dashboard URL] +- Created setup report: [insert full local file path] \ No newline at end of file diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/EXAMPLE.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/EXAMPLE.md new file mode 100644 index 00000000..45f03968 --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/EXAMPLE.md @@ -0,0 +1,1583 @@ +# PostHog FastAPI Example Project + +Repository: https://github.com/PostHog/context-mill +Path: example-apps/fastapi + +--- + +## README.md + +# PostHog FastAPI Example + +A FastAPI application demonstrating PostHog integration for analytics, feature flags, and error tracking. + +## Features + +- User registration and authentication with cookie-based sessions +- SQLite database persistence with SQLAlchemy +- User identification and property tracking +- Custom event tracking +- Feature flags with payload support +- Error tracking with manual exception capture + +## Quick Start + +1. Create and activate a virtual environment: + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` + +2. Install dependencies: + ```bash + pip install -r requirements.txt + ``` + +3. Copy the environment file and configure: + ```bash + cp .env.example .env + # Edit .env with your PostHog project key + ``` + +4. Run the application: + ```bash + python run.py + ``` + +5. Open http://localhost:5002 and either: + - Login with default credentials: `admin@example.com` / `admin` + - Or click "Sign up here" to create a new account + +## PostHog Integration Points + +### User Registration +New users are identified and tracked on signup using the context-based API: +```python +with new_context(): + identify_context(user.email) + tag('email', user.email) + tag('is_staff', user.is_staff) + capture('user_signed_up', properties={'signup_method': 'form'}) +``` + +### User Identification +Users are identified on login with their properties: +```python +with new_context(): + identify_context(user.email) + tag('email', user.email) + tag('is_staff', user.is_staff) + capture('user_logged_in', properties={'login_method': 'password'}) +``` + +### Event Tracking +Custom events are captured throughout the app: +```python +with new_context(): + identify_context(current_user.email) + capture('burrito_considered', properties={'total_considerations': count}) +``` + +### Feature Flags +The dashboard demonstrates feature flag checking: +```python +show_new_feature = posthog.feature_enabled( + 'new-dashboard-feature', + current_user.email, + person_properties={'email': current_user.email, 'is_staff': current_user.is_staff} +) +feature_config = posthog.get_feature_flag_payload('new-dashboard-feature', current_user.email) +``` + +### Error Tracking + +The example demonstrates two approaches to error tracking: + +Manual capture for specific critical operations** (`app/routers/api.py`). + +```python +try: + # Critical operation that might fail + result = process_payment() +except Exception as e: + # Manually capture this specific exception + with new_context(): + identify_context(current_user.email) + event_id = posthog.capture_exception(e) + + return JSONResponse({ + "error": "Operation failed", + "error_id": event_id, + "message": f"Error captured in PostHog. Reference ID: {event_id}" + }, status_code=500) +``` + +The `/api/test-error` endpoint demonstrates manual exception capture. Use `?capture=true` to capture in PostHog, or `?capture=false` to skip tracking. + +## Project Structure + +``` +basics/fastapi/ +├── app/ +│ ├── __init__.py # Package marker +│ ├── config.py # Pydantic Settings configuration +│ ├── database.py # SQLAlchemy setup +│ ├── dependencies.py # FastAPI dependency injection +│ ├── main.py # Application factory and lifespan +│ ├── models.py # User model (SQLAlchemy) +│ ├── routers/ +│ │ ├── __init__.py # Routers package +│ │ ├── main.py # Page routes (HTML) +│ │ └── api.py # API endpoints (JSON) +│ └── templates/ # Jinja2 templates +├── .env.example +├── .gitignore +├── requirements.txt +├── README.md +└── run.py # Entry point (uvicorn) +``` + +--- + +## .env.example + +```example +POSTHOG_PROJECT_TOKEN= +POSTHOG_HOST=https://us.i.posthog.com +SECRET_KEY=your-secret-key-here +DEBUG=True +POSTHOG_DISABLED=False + +``` + +--- + +## app/__init__.py + +```py +"""FastAPI PostHog example application.""" + +``` + +--- + +## app/config.py + +```py +"""FastAPI application configuration using Pydantic Settings.""" + +from functools import lru_cache + +from pydantic_settings import BaseSettings, SettingsConfigDict + + +class Settings(BaseSettings): + """Application settings loaded from environment variables.""" + + model_config = SettingsConfigDict( + env_file=".env", + env_file_encoding="utf-8", + extra="ignore", + ) + + # Application + secret_key: str = "dev-secret-key-change-in-production" + debug: bool = True + + # Database (SQLite like Flask example) + database_url: str = "sqlite:///./db.sqlite3" + + # PostHog + posthog_project_token: str = "" + posthog_host: str = "https://us.i.posthog.com" + posthog_disabled: bool = False + + +@lru_cache +def get_settings() -> Settings: + """Get cached settings instance.""" + return Settings() + +``` + +--- + +## app/database.py + +```py +"""Database configuration with SQLAlchemy.""" + +from sqlalchemy import create_engine +from sqlalchemy.orm import DeclarativeBase, sessionmaker + +from app.config import get_settings + +settings = get_settings() + +engine = create_engine( + settings.database_url, + connect_args={"check_same_thread": False}, # Required for SQLite +) + +SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine) + + +class Base(DeclarativeBase): + """Base class for SQLAlchemy models.""" + + pass + + +def get_db(): + """Dependency that provides a database session.""" + db = SessionLocal() + try: + yield db + finally: + db.close() + + +def init_db(): + """Create all database tables.""" + Base.metadata.create_all(bind=engine) + +``` + +--- + +## app/dependencies.py + +```py +"""Authentication dependencies for FastAPI.""" + +from typing import Annotated, Optional + +from fastapi import Cookie, Depends, HTTPException, status +from itsdangerous import BadSignature, URLSafeSerializer +from sqlalchemy.orm import Session + +from app.config import get_settings +from app.database import get_db +from app.models import User + +settings = get_settings() +serializer = URLSafeSerializer(settings.secret_key) + + +def get_session_user_id(session_token: Annotated[Optional[str], Cookie()] = None) -> Optional[int]: + """Extract user ID from session cookie.""" + if not session_token: + return None + try: + data = serializer.loads(session_token) + return data.get("user_id") + except BadSignature: + return None + + +def get_current_user( + db: Annotated[Session, Depends(get_db)], + user_id: Annotated[Optional[int], Depends(get_session_user_id)], +) -> Optional[User]: + """Get the current authenticated user, or None if not authenticated.""" + if user_id is None: + return None + return User.get_by_id(db, user_id) + + +def require_auth( + current_user: Annotated[Optional[User], Depends(get_current_user)], +) -> User: + """Require authentication - raises 401 if not authenticated.""" + if current_user is None: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Authentication required", + ) + return current_user + + +def create_session_token(user_id: int) -> str: + """Create a signed session token for the user.""" + return serializer.dumps({"user_id": user_id}) + + +# Type aliases for cleaner dependency injection +CurrentUser = Annotated[Optional[User], Depends(get_current_user)] +RequiredUser = Annotated[User, Depends(require_auth)] +DbSession = Annotated[Session, Depends(get_db)] + +``` + +--- + +## app/main.py + +```py +"""FastAPI application with PostHog integration.""" + +from contextlib import asynccontextmanager +from pathlib import Path + +import posthog +from fastapi import FastAPI, Request +from fastapi.responses import HTMLResponse, JSONResponse +from fastapi.staticfiles import StaticFiles +from fastapi.templating import Jinja2Templates + +from app.config import get_settings +from app.database import SessionLocal, init_db +from app.middleware import PostHogMiddleware +from app.models import User +from app.routers import api, main + +settings = get_settings() + +# Setup templates +templates_dir = Path(__file__).parent / "templates" +templates = Jinja2Templates(directory=str(templates_dir)) + + +@asynccontextmanager +async def lifespan(app: FastAPI): + """Application lifespan events for startup/shutdown.""" + # Startup: Initialize PostHog + if not settings.posthog_disabled: + posthog.api_key = settings.posthog_project_token + posthog.host = settings.posthog_host + posthog.debug = settings.debug + + # Initialize database and seed default user + init_db() + db = SessionLocal() + try: + if not User.get_by_email(db, "admin@example.com"): + User.create_user( + db, + email="admin@example.com", + password="admin", + is_staff=True, + ) + finally: + db.close() + + yield + + # Shutdown: Flush PostHog events + if not settings.posthog_disabled: + posthog.flush() + + +app = FastAPI( + title="PostHog FastAPI Example", + description="Example application demonstrating PostHog integration with FastAPI", + lifespan=lifespan, +) + +app.add_middleware(PostHogMiddleware) + +# Include routers +app.include_router(main.router) +app.include_router(api.router, prefix="/api") + + +# Error handlers +@app.exception_handler(404) +async def not_found_handler(request: Request, exc): + """Handle 404 errors.""" + if request.url.path.startswith("/api/"): + return JSONResponse({"error": "Not found"}, status_code=404) + return templates.TemplateResponse( + request, "errors/404.html", status_code=404 + ) + + +@app.exception_handler(500) +async def internal_error_handler(request: Request, exc): + """Handle 500 errors.""" + if request.url.path.startswith("/api/"): + return JSONResponse({"error": "Internal server error"}, status_code=500) + return templates.TemplateResponse( + request, "errors/500.html", status_code=500 + ) + +``` + +--- + +## app/middleware.py + +```py +"""PostHog middleware for automatic context and user identification. + +Uses pure ASGI middleware instead of BaseHTTPMiddleware for better performance/best practices. +""" + +from http.cookies import SimpleCookie +from typing import Callable, Optional + +from posthog import identify_context, new_context, tag + +from app.config import get_settings +from app.database import SessionLocal +from app.dependencies import serializer +from app.models import User + + +class PostHogMiddleware: + """Pure ASGI middleware that wraps each request in a PostHog context. + + If the user is authenticated, identifies them in the context so routes + can just call capture() without needing to set up context each time. + + Uses pure ASGI interface for better performance than BaseHTTPMiddleware. + """ + + def __init__(self, app): + self.app = app + self.settings = get_settings() + + async def __call__(self, scope, receive, send): + if scope["type"] != "http" or self.settings.posthog_disabled: + await self.app(scope, receive, send) + return + + user = self._get_user_from_scope(scope) + + with new_context(): + if user: + identify_context(user.email) + tag("email", user.email) + tag("is_staff", user.is_staff) + + await self.app(scope, receive, send) + + def _get_user_from_scope(self, scope) -> Optional[User]: + """Extract authenticated user from session cookie in ASGI scope.""" + headers = dict(scope.get("headers", [])) + cookie_header = headers.get(b"cookie", b"").decode("utf-8") + + if not cookie_header: + return None + + cookies = SimpleCookie() + cookies.load(cookie_header) + + session_cookie = cookies.get("session_token") + if not session_cookie: + return None + + session_token = session_cookie.value + + try: + data = serializer.loads(session_token) + user_id = data.get("user_id") + except Exception: + return None + + if not user_id: + return None + + db = SessionLocal() + try: + return User.get_by_id(db, user_id) + finally: + db.close() + +``` + +--- + +## app/models.py + +```py +"""User model with SQLite persistence (similar to Flask example).""" + +from datetime import datetime, timezone +from typing import Optional + +from sqlalchemy import Boolean, DateTime, Integer, String +from sqlalchemy.orm import Mapped, Session, mapped_column +from werkzeug.security import check_password_hash, generate_password_hash + +from app.database import Base + + +class User(Base): + """User model with SQLite persistence.""" + + __tablename__ = "users" + + id: Mapped[int] = mapped_column(Integer, primary_key=True) + email: Mapped[str] = mapped_column(String(254), unique=True, nullable=False) + password_hash: Mapped[str] = mapped_column(String(256), nullable=False) + name: Mapped[Optional[str]] = mapped_column(String(100), nullable=True) + is_staff: Mapped[bool] = mapped_column(Boolean, default=False) + is_active: Mapped[bool] = mapped_column(Boolean, default=True) + login_count: Mapped[int] = mapped_column(Integer, default=0) + date_joined: Mapped[datetime] = mapped_column( + DateTime, default=lambda: datetime.now(timezone.utc) + ) + + def set_password(self, password: str) -> None: + """Hash and set the user's password.""" + self.password_hash = generate_password_hash(password, method="pbkdf2:sha256") + + def check_password(self, password: str) -> bool: + """Verify the password against the hash.""" + return check_password_hash(self.password_hash, password) + + @classmethod + def create_user( + cls, db: Session, email: str, password: str, is_staff: bool = False + ) -> "User": + """Create and save a new user.""" + user = cls(email=email, is_staff=is_staff) + # nosemgrep: python.django.security.audit.unvalidated-password.unvalidated-password + user.set_password(password) + db.add(user) + db.commit() + db.refresh(user) + return user + + @classmethod + def get_by_id(cls, db: Session, user_id: int) -> Optional["User"]: + """Get user by ID.""" + return db.query(cls).filter(cls.id == user_id).first() + + @classmethod + def get_by_email(cls, db: Session, email: str) -> Optional["User"]: + """Get user by email.""" + return db.query(cls).filter(cls.email == email).first() + + @classmethod + def authenticate(cls, db: Session, email: str, password: str) -> Optional["User"]: + """Authenticate user with email and password.""" + user = cls.get_by_email(db, email) + if user and user.check_password(password): + return user + return None + + def record_login(self, db: Session) -> bool: + """Record a login and return whether this is the user's first login.""" + is_first_login = self.login_count == 0 + self.login_count += 1 + db.commit() + return is_first_login + + def update_profile(self, db: Session, name: Optional[str] = None) -> list: + """Update user profile and return list of changed fields.""" + changed_fields = [] + if name is not None and name != self.name: + self.name = name + changed_fields.append("name") + if changed_fields: + db.commit() + return changed_fields + + def __repr__(self) -> str: + return f"" + +``` + +--- + +## app/routers/__init__.py + +```py +"""FastAPI routers package.""" + +``` + +--- + +## app/routers/api.py + +```py +"""API endpoints demonstrating PostHog integration patterns.""" + +from typing import Annotated + +import posthog +from fastapi import APIRouter, Cookie, Form, Query +from fastapi.responses import JSONResponse +from posthog import capture + +from app.dependencies import RequiredUser + +router = APIRouter() + +MAX_BURRITO_COUNT = 10000 + + +@router.post("/burrito/consider") +async def consider_burrito( + current_user: RequiredUser, + burrito_count: Annotated[int, Cookie()] = 0, +): + """Track burrito consideration event.""" + safe_count = max(0, min(burrito_count, MAX_BURRITO_COUNT)) + new_count = safe_count + 1 + + capture("burrito_considered", properties={"total_considerations": new_count}) + + response = JSONResponse({"success": True, "count": new_count}) + response.set_cookie( + key="burrito_count", + value=str(new_count), + httponly=True, + samesite="lax", + ) + return response + + +@router.post("/test-error") +async def test_error( + current_user: RequiredUser, + capture_param: Annotated[str, Query(alias="capture")] = "true", +): + """Test endpoint demonstrating manual exception capture in PostHog.""" + should_capture = capture_param.lower() == "true" + + try: + raise Exception("Test exception from critical operation") + except Exception as e: + if should_capture: + event_id = posthog.capture_exception(e) + return JSONResponse( + { + "error": "Operation failed", + "error_id": event_id, + "message": f"Error captured in PostHog. Reference ID: {event_id}", + }, + status_code=500, + ) + else: + return JSONResponse({"error": "Operation failed"}, status_code=500) + + +@router.post("/trigger-error") +async def trigger_error( + current_user: RequiredUser, + error_type: Annotated[str, Form()] = "generic", +): + """Trigger different error types for testing error tracking.""" + error_messages = { + "value": "Invalid value provided", + "key": "Missing required key", + "generic": "Generic test error", + } + + safe_error_type = error_type if error_type in error_messages else "generic" + error_message = error_messages[safe_error_type] + + try: + if safe_error_type == "value": + raise ValueError(error_message) + elif safe_error_type == "key": + raise KeyError("missing_key") + else: + raise Exception(error_message) + except Exception as e: + posthog.capture_exception(e) + capture( + "error_triggered", + properties={"error_type": safe_error_type, "error_message": error_message}, + ) + + return JSONResponse( + { + "success": True, + "message": "Error captured in PostHog", + "error": error_message, + } + ) + + +@router.post("/reports/activity") +async def generate_activity_report( + current_user: RequiredUser, + report_type: Annotated[str, Form()] = "summary", +): + """Generate user activity report.""" + valid_report_types = {"summary", "detailed", "export"} + safe_report_type = report_type if report_type in valid_report_types else "summary" + + report_data = { + "user": current_user.email, + "name": current_user.name, + "date_joined": current_user.date_joined.isoformat(), + "login_count": current_user.login_count, + "is_staff": current_user.is_staff, + } + + if safe_report_type == "detailed": + report_data["account_age_days"] = ( + __import__("datetime").datetime.now(__import__("datetime").timezone.utc) + - current_user.date_joined + ).days + + row_count = len(report_data) + + capture( + "report_generated", + properties={ + "report_type": safe_report_type, + "row_count": row_count, + "username": current_user.email, + }, + ) + + return JSONResponse( + { + "success": True, + "report_type": safe_report_type, + "row_count": row_count, + "data": report_data, + } + ) + +``` + +--- + +## app/routers/main.py + +```py +"""Main routes demonstrating PostHog integration patterns.""" + +from pathlib import Path +from typing import Annotated + +import posthog +from fastapi import APIRouter, Cookie, Depends, Form, Request +from fastapi.responses import HTMLResponse, RedirectResponse +from fastapi.templating import Jinja2Templates +from posthog import capture + +from app.dependencies import ( + CurrentUser, + DbSession, + RequiredUser, + create_session_token, +) +from app.models import User + +router = APIRouter() + +# Setup templates +templates_dir = Path(__file__).parent.parent / "templates" +templates = Jinja2Templates(directory=str(templates_dir)) + + +@router.get("/", response_class=HTMLResponse) +async def home(request: Request, current_user: CurrentUser, db: DbSession): + """Home/login page.""" + if current_user: + return RedirectResponse(url="/dashboard", status_code=302) + + return templates.TemplateResponse( + request, "home.html", {"current_user": current_user} + ) + + +@router.post("/", response_class=HTMLResponse) +async def login( + request: Request, + db: DbSession, + email: Annotated[str, Form()], + password: Annotated[str, Form()], +): + """Handle login form submission.""" + user = User.authenticate(db, email, password) + + if user: + is_new_user = user.record_login(db) + posthog.identify(user.email, {"email": user.email, "is_staff": user.is_staff}) + posthog.capture( + user.email, + "user_logged_in", + properties={ + "username": user.email, + "is_new_user": is_new_user, + }, + ) + + # Create session and redirect + response = RedirectResponse(url="/dashboard", status_code=302) + response.set_cookie( + key="session_token", + value=create_session_token(user.id), + httponly=True, + samesite="lax", + ) + return response + + # Login failed + return templates.TemplateResponse( + request, + "home.html", + {"current_user": None, "error": "Invalid email or password"}, + ) + + +@router.get("/signup", response_class=HTMLResponse) +async def signup_page(request: Request, current_user: CurrentUser): + """User registration page.""" + if current_user: + return RedirectResponse(url="/dashboard", status_code=302) + + return templates.TemplateResponse( + request, "signup.html", {"current_user": current_user} + ) + + +@router.post("/signup", response_class=HTMLResponse) +async def signup( + request: Request, + db: DbSession, + email: Annotated[str, Form()], + password: Annotated[str, Form()], + password_confirm: Annotated[str, Form()], +): + """Handle signup form submission.""" + error = None + + if not email or not password: + error = "Email and password are required" + elif password != password_confirm: + error = "Passwords do not match" + elif User.get_by_email(db, email): + error = "Email already registered" + + if error: + return templates.TemplateResponse( + request, "signup.html", {"current_user": None, "error": error} + ) + + # Create new user + user = User.create_user(db, email=email, password=password, is_staff=False) + + posthog.identify(user.email, {"email": user.email, "is_staff": user.is_staff}) + posthog.capture( + user.email, + "user_signed_up", + properties={ + "username": user.email, + "signup_method": "form", + }, + ) + + # Create session and redirect + response = RedirectResponse(url="/dashboard", status_code=302) + response.set_cookie( + key="session_token", + value=create_session_token(user.id), + httponly=True, + samesite="lax", + ) + return response + + +@router.get("/logout") +async def logout(current_user: RequiredUser): + """Logout and capture event.""" + capture("user_logged_out") + + response = RedirectResponse(url="/", status_code=302) + response.delete_cookie(key="session_token") + return response + + +@router.get("/dashboard", response_class=HTMLResponse) +async def dashboard( + request: Request, + current_user: RequiredUser, +): + """Dashboard with feature flag demonstration.""" + capture("dashboard_viewed", properties={"is_staff": current_user.is_staff}) + + # Check feature flag + show_new_feature = posthog.feature_enabled( + "new-dashboard-feature", + current_user.email, + person_properties={ + "email": current_user.email, + "is_staff": current_user.is_staff, + }, + ) + + # Get feature flag payload + feature_config = posthog.get_feature_flag_payload( + "new-dashboard-feature", current_user.email + ) + + return templates.TemplateResponse( + request, + "dashboard.html", + { + "current_user": current_user, + "show_new_feature": show_new_feature, + "feature_config": feature_config, + }, + ) + + +@router.get("/burrito", response_class=HTMLResponse) +async def burrito( + request: Request, + current_user: RequiredUser, + burrito_count: Annotated[int, Cookie()] = 0, +): + """Burrito consideration tracker page.""" + return templates.TemplateResponse( + request, + "burrito.html", + {"current_user": current_user, "burrito_count": burrito_count}, + ) + + +@router.get("/profile", response_class=HTMLResponse) +async def profile(request: Request, current_user: RequiredUser): + """User profile page.""" + capture("profile_viewed") + + return templates.TemplateResponse( + request, "profile.html", {"current_user": current_user} + ) + + +@router.post("/profile", response_class=HTMLResponse) +async def update_profile( + request: Request, + db: DbSession, + current_user: RequiredUser, + name: Annotated[str, Form()], +): + """Handle profile update.""" + fields_changed = current_user.update_profile(db, name=name) + + if fields_changed: + capture( + "profile_updated", + properties={ + "username": current_user.email, + "fields_changed": fields_changed, + }, + ) + + return templates.TemplateResponse( + request, + "profile.html", + { + "current_user": current_user, + "success": "Profile updated" if fields_changed else None, + }, + ) + +``` + +--- + +## app/templates/base.html + +```html + + + + + + {% block title %}PostHog FastAPI Example{% endblock %} + + + + {% if current_user %} + + {% endif %} + +
+ {% if error %} +
+
{{ error }}
+
+ {% endif %} + {% if success %} +
+
{{ success }}
+
+ {% endif %} + + {% block content %}{% endblock %} +
+ + {% block scripts %}{% endblock %} + + + +``` + +--- + +## app/templates/burrito.html + +```html +{% extends "base.html" %} + +{% block title %}Burrito - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

Burrito Consideration Tracker

+

This page demonstrates custom event tracking with PostHog.

+ +
{{ burrito_count }}
+

Times you've considered a burrito

+ +
+ +
+
+ +
+

Code Example

+ 
+# API endpoint captures the event
+with new_context():
+    identify_context(current_user.email)
+    capture('burrito_considered', properties={
+        'total_considerations': burrito_count
+    })
+
+{% endblock %} + +{% block scripts %} + +{% endblock %} + +``` + +--- + +## app/templates/dashboard.html + +```html +{% extends "base.html" %} + +{% block title %}Dashboard - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

Dashboard

+

Welcome back, {{ current_user.email }}!

+
+ +
+

Feature Flags

+ + {% if show_new_feature %} +
+ New Feature Enabled! +

You're seeing this because the new-dashboard-feature flag is enabled for you.

+ {% if feature_config %} +

Feature Configuration:

+ 
{{ feature_config | tojson(indent=2) }}
+ {% endif %} +
+ {% else %} +

The new-dashboard-feature flag is not enabled for your account.

+ {% endif %} + +

Code Example

+ 
+# Check if feature flag is enabled
+show_new_feature = posthog.feature_enabled(
+    'new-dashboard-feature',
+    user_id,
+    person_properties={
+        'email': current_user.email,
+        'is_staff': current_user.is_staff
+    }
+)
+
+# Get feature flag payload
+feature_config = posthog.get_feature_flag_payload(
+    'new-dashboard-feature',
+    user_id
+)
+
+{% endblock %} + +``` + +--- + +## app/templates/errors/404.html + +```html +{% extends "base.html" %} + +{% block title %}Page Not Found - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

404 - Page Not Found

+

The page you're looking for doesn't exist.

+ Go Home +
+{% endblock %} + +``` + +--- + +## app/templates/errors/500.html + +```html +{% extends "base.html" %} + +{% block title %}Server Error - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

500 - Internal Server Error

+

Something went wrong on our end. Please try again later.

+ Go Home +
+{% endblock %} + +``` + +--- + +## app/templates/home.html + +```html +{% extends "base.html" %} + +{% block title %}Login - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

Welcome to PostHog FastAPI Example

+

This example demonstrates how to integrate PostHog with a FastAPI application.

+ +
+ + + + + + + +
+ +

+ Don't have an account? Sign up here +

+

+ Tip: Default credentials are admin@example.com/admin +

+
+ +
+

Features Demonstrated

+
    +
  • User registration and identification
    • +
  • Event tracking
    • +
  • Feature flags
    • +
  • Error tracking
    • +
  • Group analytics
    • +
+
+{% endblock %} + +``` + +--- + +## app/templates/profile.html + +```html +{% extends "base.html" %} + +{% block title %}Profile - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

Your Profile

+

This page demonstrates profile updates and report generation with PostHog.

+ + {% if success %} +
{{ success }}
+ {% endif %} + +
+ + + + + + + + + + + + + + + + + + + + + +
Email{{ current_user.email }}
Name + +
Date Joined{{ current_user.date_joined.strftime('%Y-%m-%d %H:%M') }}
Login Count{{ current_user.login_count }}
Staff Status{{ 'Yes' if current_user.is_staff else 'No' }}
+ +
+
+ +
+

Activity Reports

+

Generate a report of your account activity:

+ +
+ + +
+ + +
+ +
+

Error Tracking Demo

+

Click a button to trigger an error and see it captured in PostHog:

+ +
+ + + +
+ + +
+ +
+

Code Example

+ 
+try:
+    raise ValueError('Invalid value provided')
+except Exception as e:
+    # Capture exception and event with user context
+    with new_context():
+        identify_context(current_user.email)
+        posthog.capture_exception(e)
+        capture('error_triggered', properties={
+            'error_type': 'value',
+            'error_message': str(e)
+        })
+
+{% endblock %} + +{% block scripts %} + +{% endblock %} + +``` + +--- + +## app/templates/signup.html + +```html +{% extends "base.html" %} + +{% block title %}Sign Up - PostHog FastAPI Example{% endblock %} + +{% block content %} +
+

Create an Account

+

Sign up to explore the PostHog FastAPI integration example.

+ +
+ + + + + + + + + + +
+ +

+ Already have an account? Login here +

+
+ +
+

PostHog Integration

+

When you sign up, the following PostHog events are captured:

+
    +
  • identify_context() - Associates your email with the context
    • +
  • tag() - Sets person properties (email, etc.)
    • +
  • user_signed_up event - Tracks the signup action
    • +
+ +

Code Example

+ 
+# After creating the user
+with new_context():
+    identify_context(user.email)
+
+    tag('email', user.email)
+    tag('is_staff', user.is_staff)
+    tag('date_joined', user.date_joined.isoformat())
+
+    capture('user_signed_up', properties={'signup_method': 'form'})
+
+{% endblock %} + +``` + +--- + +## requirements.txt + +```txt +fastapi>=0.109.0 +uvicorn>=0.27.0 +sqlalchemy>=2.0.0 +python-dotenv>=1.0.0 +posthog>=3.0.0 +pydantic>=2.0.0 +pydantic-settings>=2.0.0 +jinja2>=3.0.0 +python-multipart>=0.0.9 +werkzeug>=3.0.0 +itsdangerous>=2.0.0 + +``` + +--- + +## run.py + +```py +"""Development server entry point.""" + +import uvicorn + +if __name__ == "__main__": + uvicorn.run("app.main:app", host="0.0.0.0", port=5002, reload=True) + +``` + +--- + diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/identify-users.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/identify-users.md new file mode 100644 index 00000000..1417e03a --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/identify-users.md @@ -0,0 +1,272 @@ +# Identify users - Docs + +Linking events to specific users enables you to build a full picture of how they're using your product across different sessions, devices, and platforms. + +This is straightforward to do when [capturing backend events](/docs/product-analytics/capture-events?tab=Node.js.md), as you associate events to a specific user using a `distinct_id`, which is a required argument. + +However, in the frontend of a [web](/docs/libraries/js/features.md#capturing-events) or [mobile app](/docs/libraries/ios.md#capturing-events), a `distinct_id` is not a required argument — PostHog's SDKs will generate an anonymous `distinct_id` for you automatically and you can capture events anonymously, provided you use the appropriate [configuration](/docs/libraries/js/features.md#capturing-anonymous-events). + +To link events to specific users, call `identify`: + +PostHog AI + +### Web + +```javascript +posthog.identify( + 'distinct_id', // Replace 'distinct_id' with your user's unique identifier + { email: 'max@hedgehogmail.com', name: 'Max Hedgehog' } // optional: set additional person properties +); +``` + +### Android + +```kotlin +PostHog.identify( + distinctId = distinctID, // Replace 'distinctID' with your user's unique identifier + // optional: set additional person properties + userProperties = mapOf( + "name" to "Max Hedgehog", + "email" to "max@hedgehogmail.com" + ) +) +``` + +### iOS + +```swift +PostHogSDK.shared.identify("distinct_id", // Replace "distinct_id" with your user's unique identifier + userProperties: ["name": "Max Hedgehog", "email": "max@hedgehogmail.com"]) // optional: set additional person properties +``` + +### React Native + +```jsx +posthog.identify('distinct_id', { // Replace "distinct_id" with your user's unique identifier + email: 'max@hedgehogmail.com', // optional: set additional person properties + name: 'Max Hedgehog' +}) +``` + +### Dart + +```dart +await Posthog().identify( + userId: 'distinct_id', // Replace "distinct_id" with your user's unique identifier + userProperties: { + 'email': 'max@hedgehogmail.com', // optional: set additional person properties + 'name': 'Max Hedgehog', + }, +); +``` + +Events captured after calling `identify` are identified events and this creates a person profile if one doesn't exist already. + +Due to the cost of processing them, anonymous events can be up to 4x cheaper than identified events, so it's recommended you only capture identified events when needed. + +## How identify works + +When a user starts browsing your website or app, PostHog automatically assigns them an **anonymous ID**, which is stored locally. + +Provided you've [configured persistence](/docs/libraries/js/persistence.md) to use cookies or `localStorage`, this enables us to track anonymous users – even across different sessions. + +By calling `identify` with a `distinct_id` of your choice (usually the user's ID in your database, or their email), you link the anonymous ID and distinct ID together. + +Thus, all past and future events made with that anonymous ID are now associated with the distinct ID. + +This enables you to do things like associate events with a user from before they log in for the first time, or associate their events across different devices or platforms. + +Using identify in the backend + +Although you can call `identify` using our backend SDKs, it is used most in frontends. This is because there is no concept of anonymous sessions in the backend SDKs, so calling `identify` only updates person profiles. + +## Best practices when using `identify` + +### 1\. Call `identify` as soon as you're able to + +In your frontend, you should call `identify` as soon as you're able to. + +Typically, this is every time your **app loads** for the first time, and directly after your **users log in**. + +This ensures that events sent during your users' sessions are correctly associated with them. + +You only need to call `identify` once per session, and you should avoid calling it multiple times unnecessarily. + +If you call `identify` multiple times with the same data without reloading the page in between, PostHog will ignore the subsequent calls. + +### 2\. Use unique strings for distinct IDs + +If two users have the same distinct ID, their data is merged and they are considered one user in PostHog. Two common ways this can happen are: + +- Your logic for generating IDs does not generate sufficiently strong IDs and you can end up with a clash where 2 users have the same ID. +- There's a bug, typo, or mistake in your code leading to most or all users being identified with generic IDs like `null`, `true`, or `distinctId`. + +PostHog also has built-in protections to stop the most common distinct ID mistakes. + +### 3\. Reset after logout + +If a user logs out on your frontend, you should call `reset()` to unlink any future events made on that device with that user. + +This is important if your users are sharing a computer, as otherwise all of those users are grouped together into a single user due to shared cookies between sessions. + +**We strongly recommend you call `reset` on logout even if you don't expect users to share a computer.** + +You can do that like so: + +PostHog AI + +### Web + +```javascript +posthog.reset() +``` + +### iOS + +```swift +PostHogSDK.shared.reset() +``` + +### Android + +```kotlin +PostHog.reset() +``` + +### React Native + +```jsx +posthog.reset() +``` + +### Dart + +```dart +await Posthog().reset(); +``` + +If you *also* want to reset the `device_id` so that the device will be considered a new device in future events, you can pass `true` as an argument: + +Web + +PostHog AI + +```javascript +posthog.reset(true) +``` + +### 4\. Person profiles and properties + +You'll notice that one of the parameters in the `identify` method is a `properties` object. + +This enables you to set [person properties](/docs/product-analytics/person-properties.md). + +Whenever possible, we recommend passing in all person properties you have available each time you call identify, as this ensures their person profile on PostHog is up to date. + +Person properties can also be set being adding a `$set` property to a event `capture` call. + +See our [person properties docs](/docs/product-analytics/person-properties.md) for more details on how to work with them and best practices. + +### 5\. Use deep links between platforms + +We recommend you call `identify` [as soon as you're able](#1-call-identify-as-soon-as-youre-able), typically when a user signs up or logs in. + +This doesn't work if one or both platforms are unauthenticated. Some examples of such cases are: + +- Onboarding and signup flows before authentication. +- Unauthenticated web pages redirecting to authenticated mobile apps. +- Authenticated web apps prompting an app download. + +In these cases, you can use a [deep link](https://developer.android.com/training/app-links/deep-linking) on Android and [universal links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) on iOS to identify users. + +1. Use `posthog.get_distinct_id()` to get the current distinct ID. Even if you cannot call identify because the user is unauthenticated, this will return an anonymous distinct ID generated by PostHog. +2. Add the distinct ID to the deep link as query parameters, along with other properties like UTM parameters. +3. When the user is redirected to the app, parse the deep link and handle the following cases: + +- The mobile app is already authenticated. In this case, call [`posthog.alias()`](/docs/libraries/js/features.md#alias) with the distinct ID from the web. This associates the two distinct IDs as a single person. +- The mobile app is unauthenticated. In this case, call [`posthog.identify()`](/docs/libraries/js/features.md#identifying-users) with the distinct ID from the web so pre-login mobile events stay connected to the web session. When the user later logs in on mobile, call `identify()` again with your canonical user ID. + +As long as you associate the distinct IDs with `posthog.identify()` or `posthog.alias()`, you can track events generated across platforms. + +Here's an example implementation for handling deep links from web to mobile: + +PostHog AI + +### iOS + +```swift +import PostHog +class DeepLinkIdentityManager { + static let shared = DeepLinkIdentityManager() + // MARK: - Deep Link Received + func handleDeepLink(_ url: URL, isAuthenticatedOnMobile: Bool) { + guard let webDistinctId = URLComponents(url: url, resolvingAgainstBaseURL: true)? + .queryItems?.first(where: { $0.name == "ph_distinct_id" })?.value else { + return + } + if isAuthenticatedOnMobile { + // The mobile app already knows the current user. + // Alias the incoming web distinct ID to that user. + PostHogSDK.shared.alias(webDistinctId) + } else { + // Reuse the web distinct ID until login on mobile. + PostHogSDK.shared.identify(webDistinctId) + } + } + // MARK: - Login/Signup + func handleLogin(canonicalUserId: String) { + // Switch from the web distinct ID (or a mobile anon ID) + // to your canonical user ID. + PostHogSDK.shared.identify(canonicalUserId) + // Set user properties, track signup event, etc. + } + func handleLogout() { + PostHogSDK.shared.reset() + } +} +``` + +### Android + +```kotlin +import android.net.Uri +import com.posthog.PostHog +object DeepLinkIdentityManager { + // Deep Link Received + fun handleDeepLink(uri: Uri, isAuthenticatedOnMobile: Boolean) { + val webDistinctId = uri.getQueryParameter("ph_distinct_id") ?: return + if (isAuthenticatedOnMobile) { + // The mobile app already knows the current user. + // Alias the incoming web distinct ID to that user. + PostHog.alias(webDistinctId) + } else { + // Reuse the web distinct ID until login on mobile. + PostHog.identify(webDistinctId) + } + } + // Login/Signup + fun handleLogin(canonicalUserId: String) { + // Switch from the web distinct ID (or a mobile anon ID) + // to your canonical user ID. + PostHog.identify(canonicalUserId) + // Set user properties, track signup event, etc. + } + fun handleLogout() { + PostHog.reset() + } +} +``` + +## Further reading + +- [Identifying users docs](/docs/product-analytics/identify.md) +- [How person processing works](/docs/how-posthog-works/ingestion-pipeline.md#2-person-processing) +- [An introductory guide to identifying users in PostHog](/tutorials/identifying-users-guide.md) + +### Community questions + +Ask a question + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/python.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/python.md new file mode 100644 index 00000000..63c0a98f --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/.claude/skills/integration-fastapi/references/python.md @@ -0,0 +1,884 @@ +# Python - Docs + +The Python SDK makes it easy to capture events, evaluate feature flags, track errors, and more in your Python apps. + +**Python 3.9 and lower** + +Python 3.9 is no longer supported for PostHog Python SDK versions `7.x.x` and higher. + +## Installation + +Terminal + +PostHog AI + +```bash +pip install posthog +``` + +**Upgrading to v6** + +Version `6.x` of the PostHog Python SDK introduces a new [contexts](/docs/libraries/python.md#contexts) API and breaking changes. If you're upgrading from `5.x` to `6.x`, read the [migration guide](/tutorials/python-v6-migration.md) first to learn more. + +In your app, import the `posthog` library and set your project token and host **before** making any calls. + +Python + +PostHog AI + +```python +from posthog import Posthog +posthog = Posthog('', host='https://us.i.posthog.com') +``` + +> **Note:** As a rule of thumb, we do not recommend having API keys or tokens in plaintext. Setting it as an environment variable is best. + +You can find your project token and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog. + +## Identifying users + +> **Identifying users is required.** Backend events need a `distinct_id` that matches the ID your frontend uses when calling `posthog.identify()`. Without this, backend events are orphaned — they can't be linked to frontend event captures, [session replays](/docs/session-replay.md), [LLM traces](/docs/ai-engineering.md), or [error tracking](/docs/error-tracking.md). +> +> See our guide on [identifying users](/docs/getting-started/identify-users.md) for how to set this up. + +## Capturing events + +You can send custom events using `capture`: + +Python + +PostHog AI + +```python +# Events captured with no context or explicit distinct_id are marked as personless and have an auto-generated distinct_id: +posthog.capture('some-anon-event') +from posthog import identify_context, new_context +# Use contexts to manage user identification across multiple capture calls +with new_context(): + identify_context('distinct_id_of_the_user') + posthog.capture('user_signed_up') + posthog.capture('user_logged_in') + # You can also capture events with a specific distinct_id + posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user') +``` + +> **Tip:** We recommend using a `[object] [verb]` format for your event names, where `[object]` is the entity that the behavior relates to, and `[verb]` is the behavior itself. For example, `project created`, `user signed up`, or `invite sent`. + +> **Tip:** You can define event schemas with typed properties and generate type-safe code using [schema management](/docs/product-analytics/schema-management.md). + +### Setting event properties + +Optionally, you can include additional information with the event by including a [properties](/docs/data/events.md#event-properties) object: + +Python + +PostHog AI + +```python +posthog.capture( + "user_signed_up", + distinct_id="distinct_id_of_the_user", + properties={ + "login_type": "email", + "is_free_trial": "true" + } +) +``` + +### Sending page views + +If you're aiming for a backend-only implementation of PostHog and won't be capturing events from your frontend, you can send `pageviews` from your backend like so: + +Python + +PostHog AI + +```python +posthog.capture('$pageview', distinct_id="distinct_id_of_the_user", properties={'$current_url': 'https://example.com'}) +``` + +## Person profiles and properties + +The Python SDK captures identified events if the current context is identified or if you pass a distinct ID explicitly. These create [person profiles](/docs/data/persons.md). To set [person properties](/docs/data/user-properties.md) in these profiles, include them when capturing an event: + +Python + +PostHog AI + +```python +# Passing a distinct id explicitly +posthog.capture( + 'event_name', + distinct_id='user-distinct-id', + properties={ + '$set': {'name': 'Max Hedgehog'}, + '$set_once': {'initial_url': '/blog'} + } +) +# Using contexts +from posthog import new_context, identify_context +with new_context(): + identify_context('user-distinct-id') + posthog.capture('event_name') +``` + +For more details on the difference between `$set` and `$set_once`, see our [person properties docs](/docs/data/user-properties.md#what-is-the-difference-between-set-and-set_once). + +To capture [anonymous events](/docs/data/anonymous-vs-identified-events.md) without person profiles, set the event's `$process_person_profile` property to `False`. Events captured with no context or explicit distinct\_id are marked as personless, and will have an auto-generated distinct\_id: + +Python + +PostHog AI + +```python +posthog.capture( + event='event_name', + properties={ + '$process_person_profile': False + } +) +``` + +## Alias + +Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend. + +In this case, you can use `alias` to assign another distinct ID to the same user. + +Python + +PostHog AI + +```python +posthog.alias(previous_id='distinct_id', distinct_id='alias_id') +``` + +We strongly recommend reading our docs on [alias](/docs/product-analytics/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method. + +## Contexts + +The Python SDK uses nested contexts for managing state that's shared across events. Contexts are the recommended way to manage things like "which user is taking this action" (through `identify_context`), rather than manually passing user state through your apps stack. + +When events (including exceptions) are captured in a context, the event uses the user [distinct ID](/docs/getting-started/identify-users.md), [session ID](/docs/data/sessions.md), and tags that are (optionally) set in the context. This is useful for adding properties to multiple events during a single user's interaction with your product. + +You can enter a context using the `with` statement: + +Python + +PostHog AI + +```python +from posthog import new_context, tag, set_context_session, identify_context +with new_context(): + tag("transaction_id", "abc123") + tag("some_arbitrary_value", {"tags": "can be dicts"}) + # Sessions are UUIDv7 values and used to track a sequence of events that occur within a single user session + # See https://posthog.com/docs/data/sessions + set_context_session(session_id) + # Setting the context-level distinct ID. See below for more details. + identify_context(user_id) + # This event is captured with the distinct ID, session ID, and tags set above + posthog.capture("order_processed") +``` + +Contexts are persisted across function calls. If you enter one and then call a function and capture an event in the called function, it uses the context tags and session ID set in the parent context: + +Python + +PostHog AI + +```python +from posthog import new_context, tag +def some_function(): + # When called from `outer_function`, this event is captured with the property some-key="value-4" + posthog.capture("order_processed") +def outer_function(): + with new_context(): + tag("some-key", "value-4") + some_function() +``` + +Contexts are nested, so tags added to a parent context are inherited by child contexts. If you set the same tag in both a parent and child context, the child context's value overrides the parent's at event capture (but the parent context won't be affected). This nesting also applies to session IDs and distinct IDs. + +Python + +PostHog AI + +```python +from posthog import new_context, tag +with new_context(): + tag("some-key", "value-1") + tag("some-other-key", "another-value") + with new_context(): + tag("some-key", "value-2") + # This event is captured with some-key="value-2" and some-other-key="another-value" + posthog.capture("order_processed") + # This event is captured with some-key="value-1" and some-other-key="another-value" + posthog.capture("order_processed") +``` + +You can disable this nesting behavior by passing `fresh=True` to `new_context`: + +Python + +PostHog AI + +```python +from posthog import new_context, tag +with new_context(fresh=True): + tag("some-key", "value-2") + # This event only has the property some-key="value-2" from the fresh context + posthog.capture("order_processed") +``` + +> **Note:** Distinct IDs, session IDs, and properties passed directly to calls to `capture` and related functions override context state in the final event captured. + +### Contexts and user identification + +Contexts can be associated with a distinct ID by calling `posthog.identify_context`: + +Python + +PostHog AI + +```python +from posthog import identify_context +identify_context("distinct-id") +``` + +Within a context associated with a distinct ID, all events captured are associated with that user. You can override the distinct ID for a specific event by passing a `distinct_id` argument to `capture`: + +Python + +PostHog AI + +```python +from posthog import new_context, identify_context +with new_context(): + identify_context("distinct-id") + posthog.capture("order_processed") # will be associated with distinct-id + posthog.capture("order_processed", distinct_id="another-distinct-id") # will be associated with another-distinct-id +``` + +It's recommended to pass the currently active distinct ID from the frontend to the backend, using the `X-POSTHOG-DISTINCT-ID` header. If you're using our Django middleware, this is extracted and associated with the request handler context automatically. + +You can read more about identifying users in the [user identification documentation](/docs/product-analytics/identify.md). + +### Contexts and sessions + +Contexts can be associated with a session ID by calling `posthog.set_context_session`. When linking backend events to frontend sessions, use the session ID from the frontend SDK (PostHog session IDs are UUIDv7 strings). + +Python + +PostHog AI + +```python +from posthog import new_context, set_context_session +with new_context(): + set_context_session(request.get_header("X-POSTHOG-SESSION-ID")) +``` + +**Using PostHog on your frontend too?** + +If you're using the PostHog JavaScript Web SDK on your frontend, it generates a session ID for you. Configure [`tracing_headers`](/docs/libraries/js/config.md#tracing-headers) for your backend hostname to add the session and distinct ID headers to browser requests automatically. + +You need to extract the header in your request handler (if you're using our Django middleware integration, this happens automatically). + +If you associate a context with a session, you'll be able to do things like: + +- See backend events on the session timeline when viewing session replays +- View session replays for users that triggered a backend exception in error tracking + +You can read more about sessions in the [session tracking](/docs/data/sessions.md) documentation. + +### Exception capture + +By default exceptions raised within a context are captured and available in the [error tracking](/docs/error-tracking.md) dashboard. You can override this behavior by passing `capture_exceptions=False` to `new_context`: + +Python + +PostHog AI + +```python +from posthog import new_context, tag +with new_context(capture_exceptions=False): + tag("transaction_id", "abc123") + tag("some_arbitrary_value", {"tags": "can be dicts"}) + # This event will be captured with the tags set above + posthog.capture("order_processed") + # This exception will not be captured + raise Exception("Order processing failed") +``` + +### Decorating functions + +The SDK exposes a function decorator. It takes the same `fresh` and `capture_exceptions` arguments as `new_context` and provides a handy way to mark a whole function as being in a new context. For example: + +Python + +PostHog AI + +```python +from posthog import scoped, identify_context +@scoped(fresh=True) +def process_order(user, order_id): + identify_context(user.distinct_id) + posthog.capture("order_processed") # Associated with the user + raise Exception("Order processing failed") # This exception is also captured and associated with the user +``` + +## Group analytics + +Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). Read the [Group Analytics](/docs/user-guides/group-analytics.md) guide for more information. + +> **Note:** This is a paid feature and is not available on the open-source or free cloud plan. Learn more on our [pricing page](/pricing.md). + +To capture an event and associate it with a group: + +Python + +PostHog AI + +```python +posthog.capture('some_event', groups={'company': 'company_id_in_your_db'}) +``` + +To update properties on a group: + +Python + +PostHog AI + +```python +posthog.group_identify('company', 'company_id_in_your_db', { + 'name': 'Awesome Inc.', + 'employees': 11 +}) +``` + +The `name` is a special property which is used in the PostHog UI for the name of the group. If you don't specify a `name` property, the group ID will be used instead. + +## Feature flags + +PostHog's [feature flags](/docs/feature-flags.md) enable you to safely deploy and roll back new features as well as target specific users and groups with them. + +There are two steps to implement feature flags in Python: + +### Step 1: Evaluate flags once + +Call `posthog.evaluate_flags()` once for the user, then read values from the returned snapshot. + +#### Boolean feature flags + +Python + +PostHog AI + +```python +flags = posthog.evaluate_flags("distinct_id_of_your_user") +if flags.is_enabled("flag-key"): + # Do something differently for this user + # Optional: fetch the payload + matched_flag_payload = flags.get_flag_payload("flag-key") +``` + +#### Multivariate feature flags + +Python + +PostHog AI + +```python +flags = posthog.evaluate_flags("distinct_id_of_your_user") +enabled_variant = flags.get_flag("flag-key") +if enabled_variant == "variant-key": # replace "variant-key" with the key of your variant + # Do something differently for this user + # Optional: fetch the payload + matched_flag_payload = flags.get_flag_payload("flag-key") +``` + +`flags.get_flag()` returns the variant string for multivariate flags, `True` for enabled boolean flags, `False` for disabled flags, and `None` when the flag wasn't returned by the evaluation. + +> **Note:** `posthog.feature_enabled()`, `posthog.get_feature_flag()`, `posthog.get_feature_flag_payload()`, and `posthog.capture(send_feature_flags=True)` still work during the migration period, but they're deprecated. Prefer `posthog.evaluate_flags()` for new code. + +### Step 2: Include feature flag information when capturing events + +If you want use your feature flag to breakdown or filter events in your [insights](/docs/product-analytics/insights.md), you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event. + +> **Note:** This step is only required for events captured using our server-side SDKs or [API](/docs/api.md). + +There are two methods you can use to include feature flag information in your events: + +#### Method 1: Pass the evaluated flags snapshot to `capture()` + +Pass the same `flags` object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another `/flags` request. + +Python + +PostHog AI + +```python +flags = posthog.evaluate_flags("distinct_id_of_your_user") +if flags.is_enabled("flag-key"): + # Do something differently for this user + pass +posthog.capture( + "event_name", + distinct_id="distinct_id_of_your_user", + flags=flags, +) +``` + +By default, this attaches every flag in the snapshot using `$feature/` properties and `$active_feature_flags`. + +To reduce event property bloat, pass a filtered snapshot: + +Python + +PostHog AI + +```python +# Attach only flags accessed with is_enabled() or get_flag() before this call +posthog.capture( + "event_name", + distinct_id="distinct_id_of_your_user", + flags=flags.only_accessed(), +) +# Attach only specific flags +posthog.capture( + "event_name", + distinct_id="distinct_id_of_your_user", + flags=flags.only(["checkout-flow", "new-dashboard"]), +) +``` + +`only_accessed()` is order-dependent. If you call it before accessing any flags with `is_enabled()` or `get_flag()`, no feature flag properties are attached. + +#### Method 2: Include the `$feature/feature_flag_name` property manually + +In the event properties, include `$feature/feature_flag_name: variant_key`: + +Python + +PostHog AI + +```python +posthog.capture( + "event_name", + distinct_id="distinct_id_of_the_user", + properties={ + # Replace feature-flag-key with your flag key and "variant-key" with the key of your variant + "$feature/feature-flag-key": "variant-key", + }, +) +``` + +### Evaluating only specific flags + +By default, `posthog.evaluate_flags()` evaluates every flag for the user. If you only need a few flags, pass `flag_keys` to request only those flags: + +Python + +PostHog AI + +```python +flags = posthog.evaluate_flags( + "distinct_id_of_your_user", + flag_keys=["checkout-flow", "new-dashboard"], +) +``` + +### Sending `$feature_flag_called` events + +Capturing `$feature_flag_called` events enables PostHog to know when a flag was accessed by a user and provide [analytics and insights](/docs/product-analytics/insights.md) on the flag. With `posthog.evaluate_flags()`, the SDK sends this event when you call `flags.is_enabled()` or `flags.get_flag()` for a flag. + +The SDK deduplicates these events per `(distinct_id, flag, value)` in a local cache. If you reinitialize the PostHog client, the cache resets and `$feature_flag_called` events may be sent again. PostHog handles duplicates, so duplicate `$feature_flag_called` events don't affect your analytics. + +`flags.get_flag_payload()` doesn't send `$feature_flag_called` events and doesn't count as an access for `only_accessed()`. + +### Advanced: Overriding server properties + +Sometimes, you may want to evaluate feature flags using [person properties](/docs/product-analytics/person-properties.md), [groups](/docs/product-analytics/group-analytics.md), or group properties that haven't been ingested yet, or were set incorrectly earlier. + +You can provide properties to evaluate the flag with by using the `person properties`, `groups`, and `group properties` arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server. + +For example: + +Python + +PostHog AI + +```python +flags = posthog.evaluate_flags( + "distinct_id_of_the_user", + person_properties={"property_name": "value"}, + groups={ + "your_group_type": "your_group_id", + "another_group_type": "your_group_id", + }, + group_properties={ + "your_group_type": {"group_property_name": "value"}, + "another_group_type": {"group_property_name": "value"}, + }, +) +if flags.is_enabled("flag-key"): + # Do something differently for this user +``` + +### Overriding GeoIP properties + +By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties. + +You can override GeoIP properties by including them in the `person_properties` parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location. + +The following GeoIP properties can be overridden: + +- `$geoip_country_code` +- `$geoip_country_name` +- `$geoip_city_name` +- `$geoip_city_confidence` +- `$geoip_continent_code` +- `$geoip_continent_name` +- `$geoip_latitude` +- `$geoip_longitude` +- `$geoip_postal_code` +- `$geoip_subdivision_1_code` +- `$geoip_subdivision_1_name` +- `$geoip_subdivision_2_code` +- `$geoip_subdivision_2_name` +- `$geoip_subdivision_3_code` +- `$geoip_subdivision_3_name` +- `$geoip_time_zone` + +Simply include any of these properties in the `person_properties` parameter alongside your other person properties when calling feature flags. + +### Request timeout + +You can configure the `feature_flags_request_timeout_seconds` parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog's servers are too slow to respond. By default, this is set to 3 seconds. + +Python + +PostHog AI + +```python +posthog = Posthog( + "", + host="https://us.i.posthog.com", + feature_flags_request_timeout_seconds=3, # Time in seconds. Defaults to 3. +) +``` + +### Local evaluation + +Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests. + +It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls. + +For details on how to implement local evaluation, see our [local evaluation guide](/docs/feature-flags/local-evaluation.md). + +#### Distributed environments + +In multi-worker or edge environments, you can implement custom caching for flag definitions using Redis, Cloudflare KV, or other storage backends. This enables sharing definitions across workers and coordinating fetches. See our guide for [local evaluation in distributed environments](/docs/feature-flags/local-evaluation/distributed-environments?tab=Python.md) for details. + +## Experiments (A/B tests) + +Since [experiments](/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code: + +Python + +PostHog AI + +```python +flags = posthog.evaluate_flags("user_distinct_id") +variant = flags.get_flag("experiment-feature-flag-key") +if variant == "variant-name": + # Do something +``` + +It's also possible to [run experiments without using feature flags](/docs/experiments/running-experiments-without-feature-flags.md). + +## AI Observability + +Our Python SDK includes a built-in AI Observability feature. It enables you to capture LLM usage, performance, and more. Check out our [analytics docs](/docs/ai-observability.md) for more details on setting it up. + +## Error tracking + +You can [autocapture exceptions](/docs/error-tracking/installation.md) by setting the `enable_exception_autocapture` argument to `True` when initializing the PostHog client. + +Python + +PostHog AI + +```python +from posthog import Posthog +posthog = Posthog("", enable_exception_autocapture=True, ...) +``` + +You can also manually capture exceptions using the `capture_exception` method: + +Python + +PostHog AI + +```python +posthog.capture_exception(e, distinct_id='user_distinct_id', properties=additional_properties) +``` + +Contexts automatically capture exceptions thrown inside them, unless disable it by passing `capture_exceptions=False` to `new_context()`. + +### Code variables capture + +The Python SDK can automatically capture the state of local variables when an exception occurs. This gives you a debugger-like view of your application state at the time of the error: + +Python + +PostHog AI + +```python +posthog = Posthog( + "", + enable_exception_autocapture=True, + capture_exception_code_variables=True, +) +``` + +You can configure which variables are captured, masked, or ignored. See the [code variables documentation](/docs/error-tracking/code-variables/python.md) for detailed configuration options. + +## GeoIP properties + +Before posthog-python v3.0, we added GeoIP properties to all incoming events by default. We also used these properties for feature flag evaluation, based on the IP address of the request. This isn't ideal since they are created based on your server IP address, rather than the user's, leading to incorrect location resolution. + +As of posthog-python v3.0, the default now is to disregard the server IP, not add the GeoIP properties, and not use the values for feature flag evaluations. + +You can go back to previous behavior by doing setting the `disable_geoip` argument in your initialization to `False`: + +Python + +PostHog AI + +```python +posthog = Posthog('api_key', disable_geoip=False) +``` + +The list of properties that this overrides: + +1. `$geoip_city_name` +2. `$geoip_country_name` +3. `$geoip_country_code` +4. `$geoip_continent_name` +5. `$geoip_continent_code` +6. `$geoip_postal_code` +7. `$geoip_time_zone` + +You can also explicitly chose to enable or disable GeoIP for a single capture request like so: + +Python + +PostHog AI + +```python +posthog.capture('test_event', disable_geoip=True|False) +``` + +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode by setting the `debug` option to `True` in the `PostHog` object. This will enable verbose logs about the inner workings of the SDK. + +Python + +PostHog AI + +```python +posthog.debug = True +``` + +## Disabling requests during tests + +You can disable requests during tests by setting the `disabled` option to `True` in the `PostHog` object. This means no events will be captured or no requests will be sent to PostHog. + +Python + +PostHog AI + +```python +if settings.TEST: + posthog.disabled = True +``` + +## Connection configuration + +The SDK uses HTTP connection pooling internally for better performance. These settings typically need not be changed, but in some environments, such as when running behind NAT gateways, pooled connections may be terminated non-gracefully, causing request failures. + +You can configure connection behavior in several ways. The following settings should be called during initialization, before any API requests are made. + +### Enable TCP keepalive + +TCP keepalive probes help prevent idle connections from being dropped by network infrastructure. This is the recommended approach for most cases where idle connections are terminated. + +Python + +PostHog AI + +```python +import posthog +posthog.enable_keep_alive() +``` + +This enables TCP keepalive with sensible defaults (60 second idle time, 60 second probe interval, 3 probes before timeout). + +### Disable connection pooling + +If you need each request to use a fresh connection, you can disable connection reuse entirely. This will incur additional overhead per request but may be desirable in some circumstances. + +Python + +PostHog AI + +```python +import posthog +posthog.disable_connection_reuse() +``` + +### Custom HTTP socket options + +For advanced use cases, you can configure arbitrary socket options on the underlying HTTP connection. + +Python + +PostHog AI + +```python +import socket +import posthog +posthog.set_socket_options([ + (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1), + # Add additional socket options as needed +]) +``` + +Pass `None` to `set_socket_options()` to reset to default behavior. + +## Filtering or modifying events before sending + +Use `before_send` to modify or drop events before they are queued for delivery. Return the modified event dictionary to send it, or `None` to drop it. + +Python + +PostHog AI + +```python +from typing import Any +import posthog +def scrub_pii(event: dict[str, Any]) -> dict[str, Any] | None: + properties = event.get("properties", {}) + if "email" in properties: + email = properties["email"] + properties["email"] = f"***@{email.split('@', 1)[1]}" if "@" in email else "***" + if event.get("event") == "test_event": + return None + return event +client = posthog.Client( + "", + before_send=scrub_pii, +) +``` + +If your callback raises an exception, the SDK logs the error and continues with the original unmodified event. + +## Historical migrations + +You can use the Python or Node SDK to run [historical migrations](/docs/migrate.md) of data into PostHog. To do so, set the `historical_migration` option to `true` when initializing the client. + +PostHog AI + +### Python + +```python +from posthog import Posthog +from datetime import datetime +posthog = Posthog( + '', + host='https://us.i.posthog.com', + debug=True, + historical_migration=True +) +events = [ + { + "event": "batched_event_name", + "properties": { + "distinct_id": "user_id", + "timestamp": datetime.fromisoformat("2024-04-02T12:00:00") + } + }, + { + "event": "batched_event_name", + "properties": { + "distinct_id": "used_id", + "timestamp": datetime.fromisoformat("2024-04-02T12:00:00") + } + } +] +for event in events: + posthog.capture( + distinct_id=event["properties"]["distinct_id"], + event=event["event"], + properties=event["properties"], + timestamp=event["properties"]["timestamp"], + ) +``` + +### Node.js + +```javascript +import { PostHog } from 'posthog-node' +const client = new PostHog( + '', + { + host: 'https://us.i.posthog.com', + historicalMigration: true + } +) +client.debug() +client.capture({ + event: "batched_event_name", + distinctId: "user_id", + properties: {}, + timestamp: "2024-04-03T12:00:00Z" +}) +client.capture({ + event: "batched_event_name", + distinctId: "user_id", + properties: {}, + timestamp: "2024-04-03T13:00:00Z" +}) +await client.shutdown() +``` + +## Serverless environments (Render/Lambda/...) + +By default, the library buffers events before sending them to the capture endpoint, for better performance. This can lead to lost events in serverless environments, if the Python process is terminated by the platform before the buffer is fully flushed. To avoid this, you can either: + +- Ensure that `posthog.shutdown()` is called after processing every request by adding a middleware to your server. This allows `posthog.capture()` to remain asynchronous for better performance. `posthog.shutdown()` is blocking. +- Enable the `sync_mode` option when initializing the client, so that all calls to `posthog.capture()` become synchronous. + +## Django + +See our [Django docs](/docs/libraries/django.md) for how to set up PostHog in Django. Our library includes a [contexts middleware](/docs/libraries/django.md#django-contexts-middleware) that can automatically capture distinct IDs, session IDs, and other properties you can set up with tags. + +## Alternative name + +As our open source project [PostHog](https://github.com/PostHog/posthog) shares the same module name, we created a special `posthoganalytics` package, mostly for internal use to avoid module collision. It is the exact same. + +## Thank you + +This library is largely based on the `analytics-python` package. + +### Community questions + +Ask a question + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/config.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/config.py index 06e27879..9cf3c156 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/config.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/config.py @@ -25,6 +25,11 @@ class Settings(BaseSettings): # Credits default_credits: int = 100 + # PostHog + posthog_project_token: str = "" + posthog_host: str = "https://us.i.posthog.com" + posthog_disabled: bool = False + class Config: env_file = ".env" env_file_encoding = "utf-8" diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/main.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/main.py index e42b7520..65228a5a 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/main.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/main.py @@ -2,12 +2,14 @@ from contextlib import asynccontextmanager +import posthog from fastapi import FastAPI, Request from fastapi.responses import HTMLResponse, JSONResponse from fastapi.templating import Jinja2Templates from app.config import get_settings from app.database import init_db +from app.middleware import PostHogMiddleware from app.routers import auth, generate, pages, api_keys, usage, settings as settings_router settings = get_settings() @@ -17,11 +19,21 @@ @asynccontextmanager async def lifespan(app: FastAPI): """Application lifespan events for startup/shutdown.""" + # Initialize PostHog + if not settings.posthog_disabled: + posthog.api_key = settings.posthog_project_token + posthog.host = settings.posthog_host + posthog.debug = settings.debug + # Initialize database init_db() yield + # Shutdown: flush PostHog events + if not settings.posthog_disabled: + posthog.flush() + app = FastAPI( title=settings.app_name, @@ -29,6 +41,8 @@ async def lifespan(app: FastAPI): lifespan=lifespan, ) +app.add_middleware(PostHogMiddleware) + # Include routers app.include_router(auth.router) app.include_router(generate.router) diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/middleware.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/middleware.py index ecc8126c..ff3e56dc 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/middleware.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/middleware.py @@ -1,3 +1,67 @@ """Middleware module for the application.""" -# Custom middleware can be added here +from http.cookies import SimpleCookie +from typing import Optional + +from posthog import identify_context, new_context, tag + +from app.config import get_settings +from app.database import SessionLocal +from app.dependencies import serializer +from app.models import User + + +class PostHogMiddleware: + """Pure ASGI middleware that wraps each request in a PostHog context. + + Identifies authenticated users so route handlers can call capture() + without setting up context manually. + """ + + def __init__(self, app): + self.app = app + self.settings = get_settings() + + async def __call__(self, scope, receive, send): + if scope["type"] != "http" or self.settings.posthog_disabled: + await self.app(scope, receive, send) + return + + user = self._get_user_from_scope(scope) + + with new_context(): + if user: + identify_context(user.email) + tag("email", user.email) + + await self.app(scope, receive, send) + + def _get_user_from_scope(self, scope) -> Optional[User]: + """Extract authenticated user from session cookie in ASGI scope.""" + headers = dict(scope.get("headers", [])) + cookie_header = headers.get(b"cookie", b"").decode("utf-8") + + if not cookie_header: + return None + + cookies = SimpleCookie() + cookies.load(cookie_header) + + session_cookie = cookies.get("session_token") + if not session_cookie: + return None + + try: + data = serializer.loads(session_cookie.value) + user_id = data.get("user_id") + except Exception: + return None + + if not user_id: + return None + + db = SessionLocal() + try: + return User.get_by_id(db, user_id) + finally: + db.close() diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/api_keys.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/api_keys.py index 988425c8..5a18331b 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/api_keys.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/api_keys.py @@ -3,6 +3,7 @@ from typing import List from fastapi import APIRouter, HTTPException, status +from posthog import capture from pydantic import BaseModel, Field from app.dependencies import DbSession, RequiredUser @@ -73,6 +74,8 @@ async def create_api_key( api_key = APIKey.create(db, user_id=current_user.id, name=request.name) + capture("api_key_created", properties={"active_key_count": active_count + 1}) + return APIKeyCreated( id=api_key.id, name=api_key.name, @@ -104,4 +107,6 @@ async def revoke_api_key( api_key.is_active = False db.commit() + capture("api_key_revoked") + return None diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/auth.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/auth.py index 2b564d1d..83ae937b 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/auth.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/auth.py @@ -5,6 +5,7 @@ from fastapi import APIRouter, Form, Request from fastapi.responses import HTMLResponse, RedirectResponse from fastapi.templating import Jinja2Templates +from posthog import capture, identify_context, tag from app.config import get_settings from app.dependencies import CurrentUser, DbSession, RequiredUser, create_session_token @@ -34,6 +35,10 @@ async def login( user = User.authenticate(db, email, password) if user: + identify_context(user.email) + tag("email", user.email) + capture("user_logged_in", properties={"login_method": "password"}) + response = RedirectResponse(url="/dashboard", status_code=302) response.set_cookie( key="session_token", @@ -71,6 +76,10 @@ async def signup( user = User.create(db, email=email, password=password, credits=settings.default_credits) + identify_context(user.email) + tag("email", user.email) + capture("user_signed_up", properties={"signup_method": "form"}) + response = RedirectResponse(url="/dashboard", status_code=302) response.set_cookie( key="session_token", @@ -84,6 +93,8 @@ async def signup( @router.get("/logout") async def logout(current_user: RequiredUser): """Logout user.""" + capture("user_logged_out") + response = RedirectResponse(url="/", status_code=302) response.delete_cookie(key="session_token") return response diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/generate.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/generate.py index 41a129d1..b51e7a37 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/generate.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/generate.py @@ -2,7 +2,9 @@ from typing import Annotated, Optional +import posthog from fastapi import APIRouter, HTTPException, status +from posthog import capture from pydantic import BaseModel, Field from app.dependencies import DbSession, RequiredUser @@ -54,6 +56,14 @@ async def generate_content( # Check credits if current_user.credits < credits_needed: + capture( + "insufficient_credits", + properties={ + "generation_type": request.generation_type, + "credits_needed": credits_needed, + "credits_available": current_user.credits, + }, + ) raise HTTPException( status_code=status.HTTP_402_PAYMENT_REQUIRED, detail=f"Insufficient credits. Need {credits_needed}, have {current_user.credits}", @@ -63,17 +73,31 @@ async def generate_content( current_user.use_credits(credits_needed) db.commit() - # Mock AI generation (would call OpenAI/Anthropic in production) - mock_content = _generate_mock_content(request.generation_type, request.prompt) - - # Record generation - generation = Generation.create( - db, - user_id=current_user.id, - generation_type=request.generation_type, - prompt=request.prompt, - result=mock_content, - credits_used=credits_needed, + try: + # Mock AI generation (would call OpenAI/Anthropic in production) + mock_content = _generate_mock_content(request.generation_type, request.prompt) + + # Record generation + generation = Generation.create( + db, + user_id=current_user.id, + generation_type=request.generation_type, + prompt=request.prompt, + result=mock_content, + credits_used=credits_needed, + ) + except Exception as e: + posthog.capture_exception(e) + raise + + capture( + "content_generated", + properties={ + "generation_type": request.generation_type, + "credits_used": credits_needed, + "credits_remaining": current_user.credits, + "prompt_length": len(request.prompt), + }, ) return GenerateResponse( diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/pages.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/pages.py index d91af9b7..9f3e24dc 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/pages.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/pages.py @@ -3,6 +3,7 @@ from fastapi import APIRouter, Request from fastapi.responses import HTMLResponse, RedirectResponse from fastapi.templating import Jinja2Templates +from posthog import capture from app.dependencies import CurrentUser, DbSession, RequiredUser from app.models import Generation, APIKey, Activity @@ -23,6 +24,8 @@ async def home(request: Request, current_user: CurrentUser): @router.get("/dashboard", response_class=HTMLResponse) async def dashboard(request: Request, current_user: RequiredUser, db: DbSession): """User dashboard showing credits and recent generations.""" + capture("dashboard_viewed", properties={"credits_remaining": current_user.credits}) + # Get recent generations recent = ( db.query(Generation) diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/settings.py b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/settings.py index d4baaaa2..6d662381 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/settings.py +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/app/routers/settings.py @@ -5,6 +5,7 @@ from fastapi import APIRouter, Form, Request, HTTPException, status from fastapi.responses import HTMLResponse, RedirectResponse from fastapi.templating import Jinja2Templates +from posthog import capture from pydantic import BaseModel, EmailStr from app.dependencies import DbSession, RequiredUser @@ -66,6 +67,7 @@ async def update_settings( else: current_user.email = email db.commit() + capture("settings_updated", properties={"fields_changed": ["email"]}) success = "Settings updated successfully" else: success = "No changes made" @@ -108,6 +110,7 @@ async def change_password( else: current_user.set_password(new_password) db.commit() + capture("password_changed") success = "Password changed successfully" api_key_count = db.query(APIKey).filter( diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/posthog-setup-report.md b/apps/basic-integration/fastapi/fastapi3-ai-saas/posthog-setup-report.md new file mode 100644 index 00000000..d804999b --- /dev/null +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/posthog-setup-report.md @@ -0,0 +1,53 @@ + +# PostHog post-wizard report + +The wizard has completed a deep integration of PostHog into the Acme AI FastAPI SaaS application. Changes were made to initialize PostHog via the lifespan context manager, add per-request user identification through ASGI middleware, and instrument ten key business events across authentication, content generation, API key management, settings, and the dashboard page. + +| Event name | Description | File | +|---|---|---| +| `user_signed_up` | Fires when a new user successfully creates an account via the signup form. | `app/routers/auth.py` | +| `user_logged_in` | Fires when a user successfully authenticates via the login form. | `app/routers/auth.py` | +| `user_logged_out` | Fires when a user explicitly logs out of the application. | `app/routers/auth.py` | +| `content_generated` | Fires when a user successfully generates AI content, recording the type and credits used. | `app/routers/generate.py` | +| `insufficient_credits` | Fires when a content generation request fails due to the user having too few credits. | `app/routers/generate.py` | +| `api_key_created` | Fires when a user creates a new API key for programmatic access. | `app/routers/api_keys.py` | +| `api_key_revoked` | Fires when a user revokes (deactivates) an existing API key. | `app/routers/api_keys.py` | +| `settings_updated` | Fires when a user successfully updates their account settings such as email. | `app/routers/settings.py` | +| `password_changed` | Fires when a user successfully changes their account password. | `app/routers/settings.py` | +| `dashboard_viewed` | Fires when an authenticated user loads the main dashboard page. | `app/routers/pages.py` | + +## Files changed + +- **`requirements.txt`** — Added `posthog>=3.0.0` dependency. +- **`.env`** — Added `POSTHOG_PROJECT_TOKEN`, `POSTHOG_HOST`, and `POSTHOG_DISABLED` environment variables. +- **`app/config.py`** — Added `posthog_project_token`, `posthog_host`, and `posthog_disabled` fields to `Settings`. +- **`app/main.py`** — Imported and registered `PostHogMiddleware`; added PostHog initialization on startup and `posthog.flush()` on shutdown in the lifespan context manager. +- **`app/middleware.py`** — Implemented `PostHogMiddleware` as a pure ASGI middleware that wraps each HTTP request in a `new_context()` and calls `identify_context(user.email)` for authenticated users. +- **`app/routers/auth.py`** — Added `user_logged_in`, `user_signed_up`, and `user_logged_out` events; uses `identify_context()` and `tag()` on login and signup so events are tied to the correct distinct ID. +- **`app/routers/generate.py`** — Added `content_generated` event with type, credits, and prompt length properties; `insufficient_credits` event as a churn signal; and `posthog.capture_exception()` around the generation logic. +- **`app/routers/api_keys.py`** — Added `api_key_created` and `api_key_revoked` events. +- **`app/routers/settings.py`** — Added `settings_updated` event (email change) and `password_changed` event. +- **`app/routers/pages.py`** — Added `dashboard_viewed` event with credits remaining property. + +## Next steps + +Dashboard creation was not completed in this run because the CI environment API key does not have `dashboard:write` scope. Once you have a PostHog personal API key with the appropriate scopes (or use the PostHog UI), create a dashboard named **"Analytics basics (wizard)"** with these suggested insights: + +1. **Signup → Login → Generate funnel** — `user_signed_up` → `user_logged_in` → `content_generated` +2. **Content generation by type** — `content_generated` broken down by `generation_type` +3. **Insufficient credits (churn signal)** — trend of `insufficient_credits` events +4. **Daily active users** — unique users who triggered `user_logged_in` +5. **API key adoption** — trend of `api_key_created` + +## Verify before merging + +- [ ] Run a full production build (the wizard only verified the files it touched) and fix any lint or type errors introduced by the generated code. +- [ ] Run the test suite — call sites that were rewritten or instrumented may need updated mocks or fixtures. +- [ ] Add `POSTHOG_PROJECT_TOKEN`, `POSTHOG_HOST`, and `POSTHOG_DISABLED` to `.env.example` and any bootstrap scripts so collaborators know what to set. +- [ ] Confirm the returning-visitor path also calls `identify` — the middleware identifies users on every authenticated request, so this should be covered, but verify that returning users show up with their email as the distinct ID rather than an anonymous ID. + +### Agent skill + +We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code. This will help ensure the model provides the most up-to-date approaches for integrating PostHog. + + diff --git a/apps/basic-integration/fastapi/fastapi3-ai-saas/requirements.txt b/apps/basic-integration/fastapi/fastapi3-ai-saas/requirements.txt index 9347f3c0..4a1766c9 100644 --- a/apps/basic-integration/fastapi/fastapi3-ai-saas/requirements.txt +++ b/apps/basic-integration/fastapi/fastapi3-ai-saas/requirements.txt @@ -8,3 +8,4 @@ jinja2>=3.0.0 python-multipart>=0.0.9 werkzeug>=3.0.0 itsdangerous>=2.0.0 +posthog>=3.0.0