Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

11.9 KB
Raw Blame
/**
 * The declarative model the onboarding spins off from. A use case defines which products it contains,
 * which extras go to the sidebar, and (through each product's `options`) which team settings must be
 * on for self-driving to actually see data. Product display (name, icon) resolves from the products
 * registry via `productPath`, so the flow can't drift from the sidebar.
 */
import { getTreeItemsProducts } from '~/products'
import { FileSystemIconType, ProductKey } from '~/queries/schema/schema-general'

export type OnboardingUseCaseKey =
    | 'find_problems'
    | 'improve_experience'
    | 'ship_changes'
    | 'maintain_ai'
    | 'connect_context'
    | 'ai_app'

/** A team setting a product needs to produce data. Keys are ours; each maps to a `Team` field. */
export type TeamOption =
    | 'session_recording' // session_recording_opt_in
    | 'replay_masking_floor' // session_recording_masking_config, only if unset
    | 'console_log_capture' // capture_console_log_opt_in (admin-gated)
    | 'network_performance' // capture_performance_opt_in (admin-gated)
    | 'exception_autocapture' // autocapture_exceptions_opt_in
    | 'heatmaps' // heatmaps_opt_in (admin-gated)
    | 'dead_clicks' // capture_dead_clicks (admin-gated)
    | 'web_vitals' // autocapture_web_vitals_opt_in

export type OnboardingProductKey =
    | 'product_analytics'
    | 'session_replay'
    | 'error_tracking'
    | 'web_analytics'
    | 'ai_observability'

export interface OnboardingProduct {
    productPath: string
    displayName?: string
    productKey: ProductKey
    /** One line: what the product contributes to the self-driving loop. */
    benefit: string
    /** Everything that must be on for this product to work. */
    options: TeamOption[]
}

export const ONBOARDING_PRODUCTS: Record<OnboardingProductKey, OnboardingProduct> = {
    product_analytics: {
        productPath: 'Product analytics',
        productKey: ProductKey.PRODUCT_ANALYTICS,
        benefit: 'Events, trends, and funnels. Understand how users use your product.',
        options: ['heatmaps', 'dead_clicks'],
    },
    session_replay: {
        productPath: 'Session replay',
        productKey: ProductKey.SESSION_REPLAY,
        benefit: 'Real sessions recorded, so agents can watch what users did.',
        options: ['session_recording', 'replay_masking_floor', 'console_log_capture', 'network_performance'],
    },
    error_tracking: {
        productPath: 'Error tracking',
        productKey: ProductKey.ERROR_TRACKING,
        benefit: 'Exceptions grouped into issues that feed your agents.',
        options: ['exception_autocapture'],
    },
    web_analytics: {
        productPath: 'Web analytics',
        productKey: ProductKey.WEB_ANALYTICS,
        benefit: 'Traffic, sources, and conversion on a live dashboard.',
        options: ['web_vitals', 'heatmaps', 'network_performance'],
    },
    ai_observability: {
        productPath: 'LLM analytics',
        displayName: 'AI observability',
        productKey: ProductKey.AI_OBSERVABILITY,
        benefit: 'Traces, costs, and failures from your LLM features.',
        options: [],
    },
}

export const SUPPORTED_ONBOARDING_PRODUCTS = [
    ...Object.values(ONBOARDING_PRODUCTS).map((product) => product.productKey),
    ProductKey.FEATURE_FLAGS,
    ProductKey.EXPERIMENTS,
    ProductKey.SURVEYS,
    ProductKey.LOGS,
    ProductKey.DATA_WAREHOUSE,
    ProductKey.WORKFLOWS,
    ProductKey.MCP_ANALYTICS,
    ProductKey.CONVERSATIONS,
]

export const ADDITIONAL_PRODUCT_DETAILS: Partial<Record<ProductKey, { description: string; docsUrl: string }>> = {
    [ProductKey.FEATURE_FLAGS]: {
        description: 'Roll out changes gradually and safely.',
        docsUrl: 'https://posthog.com/docs/feature-flags',
    },
    [ProductKey.EXPERIMENTS]: {
        description: 'Measure whether a product change works.',
        docsUrl: 'https://posthog.com/docs/experiments',
    },
    [ProductKey.SURVEYS]: {
        description: 'Collect feedback from users in your product.',
        docsUrl: 'https://posthog.com/docs/surveys',
    },
    [ProductKey.LOGS]: {
        description: 'Search and investigate application logs.',
        docsUrl: 'https://posthog.com/docs/logs',
    },
    [ProductKey.METRICS]: {
        description: 'Monitor service metrics and alerts.',
        docsUrl: 'https://posthog.com/docs/metrics',
    },
    [ProductKey.DATA_WAREHOUSE]: {
        description: 'Query product and business data together.',
        docsUrl: 'https://posthog.com/docs/data-warehouse',
    },
    [ProductKey.WORKFLOWS]: {
        description: 'Automate work from product activity.',
        docsUrl: 'https://posthog.com/docs/workflows',
    },
    [ProductKey.MCP_ANALYTICS]: {
        description: 'Monitor MCP tool calls and failures.',
        docsUrl: 'https://posthog.com/docs/mcp-analytics',
    },
    [ProductKey.CONVERSATIONS]: {
        description: 'Manage support conversations with customers.',
        docsUrl: 'https://posthog.com/docs/support',
    },
}

/** Docs pages, keyed by products-registry path - covers products and sidebar-only extras alike. */
export const DOCS_URL_BY_PRODUCT_PATH: Record<string, string> = {
    'Product analytics': 'https://posthog.com/docs/product-analytics',
    'Session replay': 'https://posthog.com/docs/session-replay',
    'Error tracking': 'https://posthog.com/docs/error-tracking',
    'Web analytics': 'https://posthog.com/docs/web-analytics',
    'LLM analytics': 'https://posthog.com/docs/llm-analytics',
    'Feature flags': 'https://posthog.com/docs/feature-flags',
    Experiments: 'https://posthog.com/docs/experiments',
    Surveys: 'https://posthog.com/docs/surveys',
    Logs: 'https://posthog.com/docs/logs',
    Metrics: 'https://posthog.com/docs/metrics',
    'Data warehouse': 'https://posthog.com/docs/data-warehouse',
    Workflows: 'https://posthog.com/docs/workflows',
    'MCP analytics': 'https://posthog.com/docs/mcp-analytics',
    Support: 'https://posthog.com/docs/support',
    Dashboards: 'https://posthog.com/docs/product-analytics/dashboards',
}

export function productIconType(product: OnboardingProduct): FileSystemIconType {
    const item = getTreeItemsProducts().find((i) => i.path === product.productPath)
    return item?.iconType ?? 'product_analytics'
}

/** A flow step only some use cases need; the flow maps each id to its step component. */
export type OnboardingExtraStepId = 'authorized-urls' | 'ai-observability'

/** What a selection sets up, shared by the use cases and the no-use-case default. */
export interface OnboardingSetup {
    /** Registered as the primary product intent. */
    primaryProduct: ProductKey
    /** Shown and configured on the products step. */
    products: OnboardingProductKey[]
    /** Intent-only ProductKeys shown on the products step. */
    additionalProducts?: ProductKey[]
    /** Intent-only ProductKeys: populate the sidebar (via the products registry's `intents`)
     * without appearing in the onboarding UI. */
    sidebarExtras: ProductKey[]
    /** Team settings needed beyond the products' own options. */
    extraOptions?: TeamOption[]
    /** Steps after install that this setup can't reach its finish line without. */
    extraSteps?: OnboardingExtraStepId[]
}

export function productKeysForSetup(setup: OnboardingSetup): ProductKey[] {
    return Array.from(
        new Set([
            setup.primaryProduct,
            ...setup.products.map((key) => ONBOARDING_PRODUCTS[key].productKey),
            ...(setup.additionalProducts ?? []),
            ...setup.sidebarExtras,
        ])
    )
}

export interface OnboardingUseCase extends OnboardingSetup {
    key: OnboardingUseCaseKey
    icon: FileSystemIconType
    title: string
    /** One sentence: how agents get there, ending in the deliverable (the finish line). */
    description: string
    /** The achievement criterion (measurement spec, not rendered). */
    done: string
}

// Dashboards for everyone: it answers to the PRODUCT_ANALYTICS intent in the products registry.
const SHARED_SIDEBAR: ProductKey[] = [ProductKey.PRODUCT_ANALYTICS]

export const ONBOARDING_USE_CASES: OnboardingUseCase[] = [
    {
        key: 'improve_experience',
        icon: 'product_analytics',
        title: 'Improve the customer experience',
        description: 'Agents study behavior, feedback, traffic, and conversions. They identify where users get stuck.',
        done: 'first experience finding or report',
        primaryProduct: ProductKey.PRODUCT_ANALYTICS,
        products: ['product_analytics', 'session_replay', 'web_analytics'],
        additionalProducts: [ProductKey.SURVEYS],
        sidebarExtras: SHARED_SIDEBAR,
        extraSteps: ['authorized-urls'],
    },
    {
        key: 'find_problems',
        icon: 'error_tracking',
        title: 'Find product problems',
        description:
            'Agents inspect errors, sessions, logs, and support context. They send findings and propose fixes.',
        done: 'first product problem finding or proposed fix',
        primaryProduct: ProductKey.ERROR_TRACKING,
        products: ['error_tracking', 'session_replay'],
        additionalProducts: [ProductKey.LOGS, ProductKey.CONVERSATIONS],
        sidebarExtras: SHARED_SIDEBAR,
    },
    {
        key: 'ship_changes',
        icon: 'feature_flag',
        title: 'Ship changes with confidence',
        description: 'Agents monitor flags and experiments. They report results before you expand a rollout.',
        done: 'first rollout or experiment result',
        primaryProduct: ProductKey.FEATURE_FLAGS,
        products: ['product_analytics'],
        additionalProducts: [ProductKey.FEATURE_FLAGS, ProductKey.EXPERIMENTS],
        sidebarExtras: SHARED_SIDEBAR,
    },
    {
        key: 'maintain_ai',
        icon: 'llm_analytics',
        title: 'Maintain an AI product',
        description: 'Agents inspect AI traces, costs, failures, and MCP tool calls. They find issues in AI features.',
        done: 'first AI product finding or report',
        primaryProduct: ProductKey.AI_OBSERVABILITY,
        products: ['ai_observability', 'product_analytics'],
        additionalProducts: [ProductKey.MCP_ANALYTICS],
        sidebarExtras: SHARED_SIDEBAR,
        extraSteps: ['ai-observability'],
    },
    {
        key: 'connect_context',
        icon: 'data_warehouse',
        title: 'Connect context and automate work',
        description: 'Agents use warehouse data and workflows to act on signals across your systems.',
        done: 'first workflow or report using connected context',
        primaryProduct: ProductKey.DATA_WAREHOUSE,
        products: ['product_analytics'],
        additionalProducts: [ProductKey.DATA_WAREHOUSE, ProductKey.WORKFLOWS],
        sidebarExtras: SHARED_SIDEBAR,
    },
]

const DEFAULT_SETUP: OnboardingSetup = {
    primaryProduct: ProductKey.PRODUCT_ANALYTICS,
    products: ['product_analytics', 'session_replay', 'error_tracking'],
    additionalProducts: [
        ProductKey.FEATURE_FLAGS,
        ProductKey.EXPERIMENTS,
        ProductKey.SURVEYS,
        ProductKey.LOGS,
        ProductKey.DATA_WAREHOUSE,
        ProductKey.WORKFLOWS,
        ProductKey.MCP_ANALYTICS,
        ProductKey.CONVERSATIONS,
        ProductKey.WEB_ANALYTICS,
        ProductKey.AI_OBSERVABILITY,
    ],
    sidebarExtras: SHARED_SIDEBAR,
}

export function resolveSetup(useCase: OnboardingUseCaseKey | null): OnboardingSetup {
    return ONBOARDING_USE_CASES.find((u) => u.key === useCase) ?? DEFAULT_SETUP
}

/** The setup's primary product - the use-case card's icon derives from it. */
export function primaryOnboardingProduct(setup: OnboardingSetup): OnboardingProduct {
    const key =
        setup.products.find((k) => ONBOARDING_PRODUCTS[k].productKey === setup.primaryProduct) ?? setup.products[0]
    return ONBOARDING_PRODUCTS[key]
}

/** Every team option the setup needs: the products' union plus the setup's extras. */
export function optionsForSetup(setup: OnboardingSetup): TeamOption[] {
    return Array.from(
        new Set([...setup.products.flatMap((key) => ONBOARDING_PRODUCTS[key].options), ...(setup.extraOptions ?? [])])
    )
}