docs: document analytics module (#12563)
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
5ad3615830
commit
04e0b43ed8
41 files changed
+76702
-69417
No files matched your search
@@ -0,0 +1,155 @@
|
||||
import { Table, Prerequisites } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Local Analytics Module Provider`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Local Analytics Module Provider is a simple analytics provider for Medusa that logs analytics events to the console. It's useful for development and debugging purposes.
|
||||
|
||||
<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 Local Analytics Module
|
||||
|
||||
Add the module into the `provider` object of the Analytics Module:
|
||||
|
||||
<Note>
|
||||
|
||||
You can use only one Analytics Module Provider in your Medusa application.
|
||||
|
||||
</Note>
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/analytics",
|
||||
options: {
|
||||
provider: {
|
||||
resolve: "@medusajs/analytics-local",
|
||||
id: "local",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test out the Module
|
||||
|
||||
To test the module out, you'll track in the console 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 = [
|
||||
["13", "resolve", "Resolve the Analytics Module's service"],
|
||||
["15", "track", "Track the event in the installed Analytics Module Provider"]
|
||||
]
|
||||
|
||||
```ts title="src/workflows/track-order-created.ts" highlights={workflowHighlights}
|
||||
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
|
||||
import { createStep } from "@medusajs/framework/workflows-sdk"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
import { OrderDTO } from "@medusajs/framework/types"
|
||||
|
||||
type StepInput = {
|
||||
order: OrderDTO
|
||||
}
|
||||
|
||||
const trackOrderCreatedStep = createStep(
|
||||
"track-order-created-step",
|
||||
async ({ order }: StepInput, { container }) => {
|
||||
const analyticsModuleService = container.resolve(Modules.ANALYTICS)
|
||||
|
||||
await analyticsModuleService.track({
|
||||
event: "order_created",
|
||||
userId: 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 trackOrderCreatedWorkflow = createWorkflow(
|
||||
"track-order-created-workflow",
|
||||
({ order_id }: WorkflowInput) => {
|
||||
const { data: orders } = useQueryGraphStep({
|
||||
entity: "order",
|
||||
fields: [
|
||||
"*",
|
||||
"customer.*",
|
||||
"items.*"
|
||||
],
|
||||
filters: {
|
||||
id: order_id,
|
||||
},
|
||||
})
|
||||
trackOrderCreatedStep({
|
||||
order: orders[0],
|
||||
})
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
This workflow retrieves the order details using the `useQueryGraphStep` and then tracks the order creation event using the `trackOrderCreatedStep`.
|
||||
|
||||
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 Local 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 { trackOrderCreatedWorkflow } from "../workflows/track-order-created"
|
||||
|
||||
export default async function orderPlacedHandler({
|
||||
event: { data },
|
||||
container,
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
await trackOrderCreatedWorkflow(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 `trackOrderCreatedWorkflow` workflow, passing the order ID as input.
|
||||
|
||||
You'll now track the order creation event whenever an order is placed in your Medusa application. You can test this out by placing an order and checking the console for the tracked event.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [How to Use the Analytics Module](/references/analytics/service)
|
||||
@@ -0,0 +1,189 @@
|
||||
import { CardList } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Analytics Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you'll learn about the Analytics Module and its providers.
|
||||
|
||||
<Note>
|
||||
|
||||
The Analytics Module is available starting [Medusa v2.8.3](https://github.com/medusajs/medusa/releases/tag/v2.8.3).
|
||||
|
||||
</Note>
|
||||
|
||||
## What is the Analytics Module?
|
||||
|
||||
The Analytics Module exposes functionalities to track and analyze user interactions and system events with third-party services. For example, you can track cart updates or completed orders.
|
||||
|
||||
In your Medusa application, you can use the Analytics Module to send data to third-party analytics services like PostHog or Segment, enabling you to gain insights into user behavior and system performance.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## How to Use the Analytics Module?
|
||||
|
||||
### Configure Analytics Module Provider
|
||||
|
||||
To use the Analytics Module, you need to configure it along with an Analytics Module Provider.
|
||||
|
||||
An Analytics Module Provider implements the underlying logic of sending analytics data. It integrates with a third-party analytics service to send the data collected through the Analytics Module.
|
||||
|
||||
Medusa provides two Analytics Module Providers: Local and PostHog module providers.
|
||||
|
||||
You can also [create a custom Analytics Module Provider](/references/analytics/provider) that integrates with a third-party service, like Segment.
|
||||
|
||||
<CardList
|
||||
items={[
|
||||
{
|
||||
title: "Local",
|
||||
href: "/infrastructure-modules/analytics/local",
|
||||
badge: {
|
||||
variant: "neutral",
|
||||
children: "For Development"
|
||||
}
|
||||
},
|
||||
{
|
||||
title: "PostHog",
|
||||
href: "/infrastructure-modules/analytics/posthog",
|
||||
badge: {
|
||||
variant: "green",
|
||||
children: "For Production"
|
||||
}
|
||||
}
|
||||
]}
|
||||
className='mb-1'
|
||||
/>
|
||||
|
||||
To configure the Analytics Module and its provider, add it to the list of modules in your `medusa-config.ts` file. For example:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/analytics",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/analytics-local",
|
||||
id: "local",
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
Refer to the documentation of each provider for specific configuration options.
|
||||
|
||||
### Track Events
|
||||
|
||||
To track an event, you can use the Analytics Module as part of the [workflows](!docs!/learn/fundamentals/workflows) you build for your custom features. A workflow is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
|
||||
|
||||
In a step of your workflow, you can resolve the Analytics Module's service and use its methods to track events or identify users.
|
||||
|
||||
For example, create a workflow at `src/workflows/track-order-placed.ts` with the following content:
|
||||
|
||||
export const workflowHighlights = [
|
||||
["13", "resolve", "Resolve the Analytics Module's service"],
|
||||
["15", "track", "Track the event in the installed Analytics Module Provider"]
|
||||
]
|
||||
|
||||
```ts title="src/workflows/track-order-created.ts" highlights={workflowHighlights}
|
||||
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
|
||||
import { createStep } from "@medusajs/framework/workflows-sdk"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
import { OrderDTO } from "@medusajs/framework/types"
|
||||
|
||||
type StepInput = {
|
||||
order: OrderDTO
|
||||
}
|
||||
|
||||
const trackOrderCreatedStep = createStep(
|
||||
"track-order-created-step",
|
||||
async ({ order }: StepInput, { container }) => {
|
||||
const analyticsModuleService = container.resolve(Modules.ANALYTICS)
|
||||
|
||||
await analyticsModuleService.track({
|
||||
event: "order_created",
|
||||
userId: 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 trackOrderCreatedWorkflow = createWorkflow(
|
||||
"track-order-created-workflow",
|
||||
({ order_id }: WorkflowInput) => {
|
||||
const { data: orders } = useQueryGraphStep({
|
||||
entity: "order",
|
||||
fields: [
|
||||
"*",
|
||||
"customer.*",
|
||||
"items.*"
|
||||
],
|
||||
filters: {
|
||||
id: order_id,
|
||||
},
|
||||
})
|
||||
trackOrderCreatedStep({
|
||||
order: orders[0],
|
||||
})
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
This workflow retrieves the order details using the `useQueryGraphStep` and then tracks the order creation event using the `trackOrderCreatedStep`.
|
||||
|
||||
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 in `medusa-config.ts` to track the event.
|
||||
|
||||
### Execute Analytics Workflow
|
||||
|
||||
After that, you can execute this workflow in a subscriber that runs when a product is created.
|
||||
|
||||
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 { trackOrderCreatedWorkflow } from "../workflows/track-order-created"
|
||||
|
||||
export default async function orderPlacedHandler({
|
||||
event: { data },
|
||||
container,
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
await trackOrderCreatedWorkflow(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 `trackOrderCreatedWorkflow` workflow, passing the order ID as input.
|
||||
|
||||
You'll now track the order creation event whenever an order is placed in your Medusa application. You can test this out by placing an order and checking the provider you integrated with (for example, PostHog) for the tracked event.
|
||||
@@ -0,0 +1,227 @@
|
||||
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: {
|
||||
provider: {
|
||||
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 = [
|
||||
["13", "resolve", "Resolve the Analytics Module's service"],
|
||||
["15", "track", "Track the event in the installed Analytics Module Provider"]
|
||||
]
|
||||
|
||||
```ts title="src/workflows/track-order-created.ts" highlights={workflowHighlights}
|
||||
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
|
||||
import { createStep } from "@medusajs/framework/workflows-sdk"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
import { OrderDTO } from "@medusajs/framework/types"
|
||||
|
||||
type StepInput = {
|
||||
order: OrderDTO
|
||||
}
|
||||
|
||||
const trackOrderCreatedStep = createStep(
|
||||
"track-order-created-step",
|
||||
async ({ order }: StepInput, { container }) => {
|
||||
const analyticsModuleService = container.resolve(Modules.ANALYTICS)
|
||||
|
||||
await analyticsModuleService.track({
|
||||
event: "order_created",
|
||||
userId: 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 trackOrderCreatedWorkflow = createWorkflow(
|
||||
"track-order-created-workflow",
|
||||
({ order_id }: WorkflowInput) => {
|
||||
const { data: orders } = useQueryGraphStep({
|
||||
entity: "order",
|
||||
fields: [
|
||||
"*",
|
||||
"customer.*",
|
||||
"items.*"
|
||||
],
|
||||
filters: {
|
||||
id: order_id,
|
||||
},
|
||||
})
|
||||
trackOrderCreatedStep({
|
||||
order: orders[0],
|
||||
})
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
This workflow retrieves the order details using the `useQueryGraphStep` and then tracks the order creation event using the `trackOrderCreatedStep`.
|
||||
|
||||
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 { trackOrderCreatedWorkflow } from "../workflows/track-order-created"
|
||||
|
||||
export default async function orderPlacedHandler({
|
||||
event: { data },
|
||||
container,
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
await trackOrderCreatedWorkflow(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 `trackOrderCreatedWorkflow` workflow, passing the order ID as input.
|
||||
|
||||
You'll now track the order creation 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)
|
||||
Reference in new issue
Block a user