medusa-store/www/apps/resources/app/infrastructure-modules/analytics/posthog/page.mdx

import { Table, Prerequisites } from "docs-ui"

export const metadata = {
  title: `PostHog Analytics Module Provider`,
}

# {metadata.title}

The PostHog Analytics Module Provider allows you to integrate [PostHog](https://posthog.com/) with Medusa.

PostHog is an open-source product analytics platform that helps you track user interactions and analyze user behavior in your commerce application.

By integrating PostHog with Medusa, you can track events such as cart additions, order completions, and user sign-ups, enabling you to gain insights into user behavior and optimize your application accordingly.

<Note>

The Analytics Module and its providers are available starting [Medusa v2.8.3](https://github.com/medusajs/medusa/releases/tag/v2.8.3).

</Note>

---

## Register the PostHog Analytics Module

<Prerequisites
  items={[
    {
      text: "PostHog account",
      link: "https://app.posthog.com/signup",
    },
    {
      text: "PostHog API Key",
      link: "https://posthog.com/docs/getting-started/api-key",
    },
  ]}
/>

Add the module into the `provider` object of the Analytics Module:

<Note>

You can use only one provider in your Medusa application.

</Note>

```ts title="medusa-config.ts"
module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/analytics",
      options: {
        providers: [
          {
            resolve: "@medusajs/analytics-posthog",
            id: "posthog",
            options: {
              posthogEventsKey: process.env.POSTHOG_EVENTS_API_KEY,
              posthogHost: process.env.POSTHOG_HOST,
            },
          },
        ],
      },
    },
  ],
})
```

### Environment Variables

Make sure to add the following environment variables:

```bash
POSTHOG_EVENTS_API_KEY=<YOUR_POSTHOG_EVENTS_API_KEY>
POSTHOG_HOST=<YOUR_POSTHOG_HOST>
```

### PostHog Analytics Module Options

<Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell>
        Option
      </Table.HeaderCell>
      <Table.HeaderCell>
        Description
      </Table.HeaderCell>
      <Table.HeaderCell>
        Default
      </Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>
        `eventsKey`
      </Table.Cell>
      <Table.Cell>
        The PostHog API key for tracking events. This is required to authenticate your requests to the PostHog API.
      </Table.Cell>
      <Table.Cell>
        \-
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `posthogHost`
      </Table.Cell>
      <Table.Cell>
        The PostHog API host URL.
      </Table.Cell>
      <Table.Cell>
        `https://eu.i.posthog.com`
      </Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

---

## Test out the Module

To test the module out, you'll track in PostHog when an order is placed.

You'll first create a [workflow](!docs!/learn/fundamentals/workflows) that tracks the order completion event. Then, you can execute the workflow in a [subscriber](!docs!/learn/fundamentals/events-and-subscribers) that listens to the `order.placed` event.

For example, create a workflow at `src/workflows/track-order-placed.ts` with the following content:

export const workflowHighlights = [
  ["14", "resolve", "Resolve the Analytics Module's service"],
  ["16", "track", "Track the event in the installed Analytics Module Provider"]
]

```ts title="src/workflows/track-order-placed.ts" highlights={workflowHighlights}
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
import { Modules } from "@medusajs/framework/utils"
import { OrderDTO } from "@medusajs/framework/types"

type StepInput = {
  order: OrderDTO
}

const trackOrderPlacedStep = createStep(
  "track-order-placed-step",
  async ({ order }: StepInput, { container }) => {
    const analyticsModuleService = container.resolve(Modules.ANALYTICS)

    await analyticsModuleService.track({
      event: "order_placed",
      actor_id: order.customer_id,
      properties: {
        order_id: order.id,
        total: order.total,
        items: order.items?.map((item) => ({
          variant_id: item.variant_id,
          product_id: item.product_id,
          quantity: item.quantity,
        })),
        customer_id: order.customer_id,
      },
    })
  }
)

type WorkflowInput = {
  order_id: string
}

export const trackOrderPlacedWorkflow = createWorkflow(
  "track-order-placed-workflow",
  ({ order_id }: WorkflowInput) => {
    const { data: orders } = useQueryGraphStep({
      entity: "order",
      fields: [
        "*",
        "customer.*",
        "items.*",
      ],
      filters: {
        id: order_id,
      },
    })
    trackOrderCreatedStep({
      order: orders[0],
    } as unknown as StepInput)
  }
)
```

This workflow retrieves the order details using the `useQueryGraphStep` and then tracks the order placement event using the `trackOrderPlacedStep`.

In the step, you resolve the service of the Analytics Module from the [Medusa container](!docs!/learn/fundamentals/medusa-container) and use its `track` method to track the event. This method will use the underlying provider configured (which is the PostHog Analytics Module Provider, in this case) to track the event.

Next, create a subscriber at `src/subscribers/order-placed.ts` with the following content:

```ts title="src/subscribers/order-placed.ts"
import type {
  SubscriberArgs,
  SubscriberConfig,
} from "@medusajs/framework"
import { trackOrderPlacedWorkflow } from "../workflows/track-order-placed"

export default async function orderPlacedHandler({
  event: { data },
  container,
}: SubscriberArgs<{ id: string }>) {
  await trackOrderPlacedWorkflow(container).run({
    input: {
      order_id: data.id,
    },
  })
}

export const config: SubscriberConfig = {
  event: "order.placed",
}
```

This subscriber listens to the `order.placed` event and executes the `trackOrderPlacedWorkflow` workflow, passing the order ID as input.

You'll now track the order placement event whenever an order is placed in your Medusa application. You can test this out by placing an order and checking your PostHog dashboard for the tracked event.

---

## Additional Resources

- [How to Use the Analytics Module](/references/analytics/service)