import { TypeList } from "docs-ui"

How to Use Analytics Module

In this document, you’ll learn about the different methods in the Analytics Module's service and how to use them.

:::note

The Analytics Module is available starting Medusa v2.8.3.

:::

Configure Analytics Module Provider

To use the Analytics Module, you need to configure it along with an Analytics Module Provider.

Medusa provides two Analytics Module Providers: Local and PostHog module providers.

To configure the Analytics Module and its provider, add it to the list of modules in your medusa-config.ts file. For example:

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.

Resolve Analytics Module's Service

In your workflow's step, you can resolve the Analytics Module's service from the Medusa container:

import { Modules } from "@medusajs/framework/utils"
import { createStep } from "@medusajs/framework/workflows-sdk"

const step1 = createStep(
  "step-1",
  async ({}, { container }) => {
    const analyticsModuleService = container.resolve(
      Modules.Analytics
    )
    
    // TODO use analyticsModuleService
  } 
)

You can then use the Analytics Module's service's methods in the step, which would use the underlying provider's logic. The rest of this guide details these methods.

getProvider

This method returns the service of the configured Analytics Module Provider in medusa-config.ts. This is useful if you want to execute custom methods defined in the provider's service or you need direct access to it.

Example

const postHogProviderService = analyticsModuleService.getProvider()
// TODO: perform custom actions with the provider

Returns

<TypeList types={[{"name":"track","type":"(data: TrackAnalyticsEventDTO) => Promise<void>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"identify","type":"(data: IdentifyAnalyticsEventDTO) => Promise<void>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shutdown","type":"() => Promise<void>","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getProvider"/>

identify

This method identifies an actor or group in the analytics provider. The Analytics Module will use the identify method of the underlying provider configured in medusa-config.ts to identify the actor or group.

Example

await analyticsModuleService.identify({
  actor_id: "123",
  properties: {
    name: "John Doe"
  }
})

Parameters

<TypeList types={[{"name":"data","type":"IdentifyAnalyticsEventDTO","description":"The details of the actor or group.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"actor_id","type":"string","description":"The actor of the event, if there is any.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"group","type":"object","description":"The group that the event is for, such as an organization or team.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"type","type":"string","description":"The name of the group.","optional":false,"defaultValue":"","example":""organization"","expandable":false,"children":[]},{"name":"id","type":"string","description":"The group's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"properties","type":"Record<string, any>","description":"The properties of the actor. The format and content is dynamic and depends on the integrated provider.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="identify"/>

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the actor or group is identified successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="identify"/>

track

This method tracks an event in the analytics provider. The Analytics Module will use the track method of the underlying provider configured in medusa-config.ts to track the event.

Example

await analyticsModuleService.track({
  event: "order_placed",
  properties: {
    order_id: "order_123",
    customer_id: "customer_456",
    total: 100,
  }
})

Parameters

<TypeList types={[{"name":"data","type":"TrackAnalyticsEventDTO","description":"The event's details.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"event","type":"string","description":"The event name","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"actor_id","type":"string","description":"The actor of the event, if there is any","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"group","type":"object","description":"The group that the event is for, such as an organization or team.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"type","type":"string","description":"The name of the group.","optional":true,"defaultValue":"","example":""organization"","expandable":false,"children":[]},{"name":"id","type":"string","description":"The group's ID.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"properties","type":"Record<string, any>","description":"The properties of the event. The format and content is dynamic and depends on the integrated provider.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="track"/>

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the event is tracked successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="track"/>