Skip to content

PostHog Implementation Guide

This page is a quick implementation reference for analytics and feature flags in CRED.

For complete, up-to-date details of all tracked events and available flags, refer to: - docs/posthog.md in cred-web-commercial - https://github.com/credinvest/cred-web-commercial/blob/develop/docs/posthog.md

Current Setup

PostHog is used for: - Analytics (intentional posthog.capture() events) - Feature flags (progressive rollouts by user/company)

Current integration is split by runtime: - Web app client: posthog-js - Chrome extension client: posthog-js - Server-side: posthog-node

Conventions in Current Setup

  • Prefer manual, intentional events over noisy auto-tracking
  • Keep event names in snake_case
  • Group events by feature prefix (example: people_, companies_, custom_scoring_)
  • Use typed enums/constants for event names and property keys where possible
  • Include page_path when relevant
  • Keep analytics non-blocking (do not let tracking failures break product flows)

How to Add Analytics for a New Page or Feature

  1. Define or extend an event enum for the feature area.
  2. Define property key constants/enums for repeated properties.
  3. Fire events at meaningful user actions only (not every render).
  4. Add context fields (page_path, ids, counts, action metadata).
  5. Validate naming consistency before merge.

Recommended event naming pattern: - <feature>_<action> - Examples: deals_exported, opportunities_stage_changed, ai_assistant_message_sent

Recommended property naming: - snake_case - Stable, explicit keys (entity_id, page_path, action_type, credit_cost)

Feature Flags: Current State

Feature flags are centrally defined and used to gate: - Entire pages - Navigation/menu entries - Feature-specific UI/actions

General behavior: - Flags are evaluated client-side and server-side depending on usage - In local development, flags are typically permissive for faster iteration - Page-level gating uses a wrapper/HOC pattern where applicable

How to Add a New Feature Flag

  1. Add the new flag to the canonical feature flag enum/type file.
  2. Create the same flag key in PostHog dashboard.
  3. Gate UI/page logic using the existing feature flag utilities.
  4. Handle loading state (undefined) before assuming on/off in UI code.
  5. Keep rollout scope narrow and place checks close to entry points.

PostHog Dashboard Steps (Operational)

Use this process in PostHog UI so product, engineering, and ops stay aligned:

  1. Create flag:
  2. Go to Feature Flags -> New feature flag
  3. Use the exact key from code (example: my-new-feature)
  4. Add clear name/description and owner
  5. Define rollout conditions:
  6. Start with a small rollout or restricted audience
  7. Prefer explicit targeting rules before global rollout
  8. Add or remove workspaces (targeting):
  9. In flag conditions, target by workspace/company properties used by CRED
  10. Add allowed workspaces to enable the feature
  11. Remove workspaces to disable access
  12. Keep the workspace targeting list documented in the flag description/changelog
  13. Replicate flags across environments:
  14. Use PostHog's flag copy/duplicate capability to copy the same flag setup between environments
  15. Keep flag key and rollout logic consistent across dev/staging/prod
  16. Re-check environment-specific values before saving
  17. Validate after save:
  18. Confirm flag status in PostHog
  19. Confirm app behavior with flag on/off
  20. Confirm no unexpected exposure outside intended workspaces

Team Checklist (Before Merging)

  • Event/flag names follow existing conventions
  • No duplicate event names for different behaviors
  • Required context properties included
  • Tracking wrapped safely (no user-facing impact on failure)
  • Feature is safe when flag is off
  • PostHog flag has workspace targeting reviewed
  • Flag replication across environments is completed/verified
  • Detailed reference doc link included in PR description when relevant

Detailed Reference

Use the full PostHog reference for comprehensive event and flag inventory: - docs/posthog.md - https://github.com/credinvest/cred-web-commercial/blob/develop/docs/posthog.md