docs: document analytics module (#12563)

2025-05-22 15:05:04 +03:00
1 parent 5ad3615830
commit 04e0b43ed8
@@ -0,0 +1,147 @@
+---
+slug: /references/analytics/service
+tags:
+  - analytics
+  - server
+  - how to
+sidebar_label: Use Analytics Module
+---
+
+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](https://github.com/medusajs/medusa/releases/tag/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](/infrastructure-modules/analytics/local) and [PostHog](/infrastructure-modules/analytics/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:
+
+```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.
+
+---
+
+## Resolve Analytics Module's Service
+
+In your workflow's step, you can resolve the Analytics Module's service from the Medusa container:
+
+```ts
+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
+
+```ts
+const postHogProviderService = analyticsModuleService.getProvider()
+// TODO: perform custom actions with the provider
+```
+
+### Returns
+
+<TypeList types={[{"name":"track","type":"(`data`: [TrackAnalyticsEventDTO](../../../types/interfaces/types.TrackAnalyticsEventDTO/page.mdx)) => Promise&#60;void&#62;","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"identify","type":"(`data`: [IdentifyAnalyticsEventDTO](../../../types/types/types.IdentifyAnalyticsEventDTO/page.mdx)) => Promise&#60;void&#62;","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shutdown","type":"() => Promise&#60;void&#62;","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
+
+```ts
+await analyticsModuleService.identify({
+  actor_id: "123",
+  properties: {
+    name: "John Doe"
+  }
+})
+```
+
+### Parameters
+
+<TypeList types={[{"name":"data","type":"[IdentifyAnalyticsEventDTO](../../../types/types/types.IdentifyAnalyticsEventDTO/page.mdx)","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":"","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&#60;void&#62;","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
+
+```ts
+await analyticsModuleService.track({
+  event: "order_placed",
+  properties: {
+    order_id: "order_123",
+    customer_id: "customer_456",
+    total: 100,
+  }
+})
+```
+
+### Parameters
+
+<TypeList types={[{"name":"data","type":"[TrackAnalyticsEventDTO](../../../types/interfaces/types.TrackAnalyticsEventDTO/page.mdx)","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":"","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&#60;void&#62;","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"/>