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
+147
@@ -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<void>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"identify","type":"(`data`: [IdentifyAnalyticsEventDTO](../../../types/types/types.IdentifyAnalyticsEventDTO/page.mdx)) => 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
|
||||
|
||||
```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<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
|
||||
|
||||
```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<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"/>
|
||||
+365
@@ -0,0 +1,365 @@
|
||||
---
|
||||
slug: /references/analytics/provider
|
||||
keywords:
|
||||
- analytics
|
||||
- provider
|
||||
- integration
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# How to Create an Analytics Module Provider
|
||||
|
||||
In this document, you’ll learn how to create an Analytics Module Provider and the methods you must implement in its main service.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Example
|
||||
|
||||
As you implement your Analytics Module Provider, it can be useful to refer to an existing provider and how it's implemeted.
|
||||
|
||||
If you need to refer to an existing implementation as an example, check the [PostHog Analytics Module Provider in the Medusa repository](https://github.com/medusajs/medusa/tree/develop/packages/modules/providers/analytics-posthog).
|
||||
|
||||
---
|
||||
|
||||
## Create Module Provider Directory
|
||||
|
||||
Start by creating a new directory for your module provider.
|
||||
|
||||
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-analytics`.
|
||||
|
||||
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-analytics`.
|
||||
|
||||
<Note>
|
||||
|
||||
The rest of this guide always uses the `src/modules/my-analytics` directory as an example.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 2. Create the Analytics Module Provider's Service
|
||||
|
||||
Create the file `src/modules/my-analytics/service.ts` that holds the implementation of the module provider's main service. It must extend the `AbstractAnalyticsProviderService` class imported from `@medusajs/framework/utils`:
|
||||
|
||||
```ts title="src/modules/my-analytics/service.ts"
|
||||
import { AbstractAnalyticsProviderService } from "@medusajs/framework/utils"
|
||||
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
// TODO implement methods
|
||||
}
|
||||
|
||||
export default MyAnalyticsProviderService
|
||||
```
|
||||
|
||||
### constructor
|
||||
|
||||
The constructor allows you to access resources from the module's container using the first parameter,
|
||||
and the module's options using the second parameter.
|
||||
|
||||
If you're creating a client or establishing a connection with a third-party service, do it in the constructor.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
import { Logger } from "@medusajs/framework/types"
|
||||
import { AbstractAnalyticsProviderService } from "@medusajs/framework/utils"
|
||||
|
||||
type InjectedDependencies = {
|
||||
logger: Logger
|
||||
}
|
||||
|
||||
type Options = {
|
||||
apiKey: string
|
||||
}
|
||||
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
protected logger_: Logger
|
||||
protected options_: Options
|
||||
static identifier = "my-analytics"
|
||||
// assuming you're initializing a client
|
||||
protected client
|
||||
|
||||
constructor (
|
||||
{ logger }: InjectedDependencies,
|
||||
options: Options
|
||||
) {
|
||||
super()
|
||||
|
||||
this.logger_ = logger
|
||||
this.options_ = options
|
||||
|
||||
// assuming you're initializing a client
|
||||
this.client = new Client(options)
|
||||
}
|
||||
}
|
||||
|
||||
export default MyAnalyticsProviderService
|
||||
```
|
||||
|
||||
### identifier
|
||||
|
||||
Each analytics provider has a unique ID used to identify it. The provider's ID
|
||||
will be stored as `aly_{identifier}_{id}`, where `{id}` is the provider's `id`
|
||||
property in the `medusa-config.ts`.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
static identifier = "my-analytics"
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### identify
|
||||
|
||||
This method identifies an actor or group in the third-party analytics provider. The Analytics Module
|
||||
will use this method in its `identify` method if your provider is configured in `medusa-config.ts`.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
// ...
|
||||
async identify(
|
||||
data: ProviderIdentifyAnalyticsEventDTO
|
||||
): Promise<void> {
|
||||
// identify actor or group in the analytics provider
|
||||
// or using custom logic
|
||||
// for example:
|
||||
this.client.identify(data)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 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<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"/>
|
||||
|
||||
### shutdown
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used to shutdown the analytics provider, and flush all data before shutting down.
|
||||
|
||||
This method is called by the Analytics Module when the Medusa application is shutting down.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
// ...
|
||||
async shutdown(): Promise<void> {
|
||||
// perform any cleanup or shutdown logic
|
||||
// in the analytics provider or using custom logic
|
||||
// for example:
|
||||
await this.client.shutdown()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the provider is shutdown successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="shutdown"/>
|
||||
|
||||
### track
|
||||
|
||||
This method tracks an event with the third-party analytics provider. The Analytics Module
|
||||
will use this method in its `track` method if your provider is configured in `medusa-config.ts`.
|
||||
|
||||
You can send the event to the third-party provider based on its semantics.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
// ...
|
||||
async track(
|
||||
data: ProviderTrackAnalyticsEventDTO
|
||||
): Promise<void> {
|
||||
// track event to third-party provider
|
||||
// or using custom logic
|
||||
// for example:
|
||||
this.client.track(data)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 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<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"/>
|
||||
|
||||
---
|
||||
|
||||
## 3. Create Module Provider Definition File
|
||||
|
||||
Create the file `src/modules/my-analytics/index.ts` with the following content:
|
||||
|
||||
```ts title="src/modules/my-analytics/index.ts"
|
||||
import MyAnalyticsProviderService from "./service"
|
||||
import {
|
||||
ModuleProvider,
|
||||
Modules
|
||||
} from "@medusajs/framework/utils"
|
||||
|
||||
export default ModuleProvider(Modules.ANALYTICS, {
|
||||
services: [MyAnalyticsProviderService],
|
||||
})
|
||||
```
|
||||
|
||||
This exports the module provider's definition, indicating that the `MyAnalyticsProviderService` is the module provider's service.
|
||||
|
||||
---
|
||||
|
||||
## 4. Use Module Provider
|
||||
|
||||
To use your Analytics Module Provider, add it to the `providers` array of the Analytics Module in `medusa-config.ts`:
|
||||
|
||||
<Note>
|
||||
|
||||
The Analytics Module accepts one provider only.
|
||||
|
||||
</Note>
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/analytics",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
// if module provider is in a plugin, use `plugin-name/providers/my-analytics`
|
||||
resolve: "./src/modules/my-analytics",
|
||||
id: "my-analytics",
|
||||
options: {
|
||||
// provider options...
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Test it Out
|
||||
|
||||
To test the module out, you'll track in your third-party provider 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:
|
||||
|
||||
```ts title="src/workflows/track-order-created.ts"
|
||||
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 your 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 in your third-party provider if the event was tracked successfully.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [How to Use the Analytics Module](/references/analytics/service)
|
||||
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# analytics
|
||||
|
||||
## Interfaces
|
||||
|
||||
- [IAnalyticsModuleService](../../analytics/interfaces/analytics.IAnalyticsModuleService/page.mdx)
|
||||
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# analytics-provider
|
||||
|
||||
## Classes
|
||||
|
||||
- [AbstractAnalyticsProviderService](../../analytics_provider/classes/analytics_provider.AbstractAnalyticsProviderService/page.mdx)
|
||||
@@ -0,0 +1,71 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# IAnalyticsModuleService
|
||||
|
||||
## 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.TrackAnalyticsEventDTO/page.mdx)) => Promise<void>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"identify","type":"(`data`: [IdentifyAnalyticsEventDTO](../../types/types.IdentifyAnalyticsEventDTO/page.mdx)) => 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"/>
|
||||
|
||||
### 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.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<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"/>
|
||||
|
||||
### 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.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<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"/>
|
||||
@@ -0,0 +1,60 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# IAnalyticsProvider
|
||||
|
||||
## Methods
|
||||
|
||||
### track
|
||||
|
||||
This method is used to track an event in the analytics provider
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[TrackAnalyticsEventDTO](../types.TrackAnalyticsEventDTO/page.mdx)","description":"The data for the event.","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<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"/>
|
||||
|
||||
### identify
|
||||
|
||||
This method is used to identify an actor or group in the analytics provider
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[IdentifyAnalyticsEventDTO](../../types/types.IdentifyAnalyticsEventDTO/page.mdx)","description":"The data for 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<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="identify"/>
|
||||
|
||||
### shutdown
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used to shutdown the analytics provider, and flush all data before shutting down.
|
||||
|
||||
This method is called by the Analytics Module when the Medusa application is shutting down.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
|
||||
// ...
|
||||
async shutdown(): Promise<void> {
|
||||
// perform any cleanup or shutdown logic
|
||||
// in the analytics provider or using custom logic
|
||||
// for example:
|
||||
await this.client.shutdown()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the provider is shutdown successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="shutdown"/>
|
||||
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# IdentifyActorDTO
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"name":"actor_id","type":"`string`","description":"The actor of the event, if there is any.","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="IdentifyActorDTO"/>
|
||||
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# IdentifyGroupDTO
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"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":"actor_id","type":"`string`","description":"When identifying a group, the actor can potentially be passed as well as metadata.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"properties","type":"`Record<string, any>`","description":"The properties of the group. 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="IdentifyGroupDTO"/>
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# LocalAnalyticsServiceOptions
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# PosthogAnalyticsServiceOptions
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"name":"posthogEventsKey","type":"`string`","description":"The key for the posthog events","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"posthogHost","type":"`string`","description":"The endpoint for the posthog server","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="PosthogAnalyticsServiceOptions"/>
|
||||
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# TrackAnalyticsEventDTO
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"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="TrackAnalyticsEventDTO"/>
|
||||
@@ -0,0 +1,3 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# AnalyticsTypes
|
||||
@@ -0,0 +1,7 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# IdentifyAnalyticsEventDTO
|
||||
|
||||
**IdentifyAnalyticsEventDTO**: [IdentifyActorDTO](../../interfaces/types.IdentifyActorDTO/page.mdx) \| [IdentifyGroupDTO](../../interfaces/types.IdentifyGroupDTO/page.mdx)
|
||||
|
||||
Either the `actor_id` or the `group` property must be set.
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# ProviderIdentifyAnalyticsEventDTO
|
||||
|
||||
**ProviderIdentifyAnalyticsEventDTO**: [IdentifyAnalyticsEventDTO](../types.IdentifyAnalyticsEventDTO/page.mdx)
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# ProviderTrackAnalyticsEventDTO
|
||||
|
||||
**ProviderTrackAnalyticsEventDTO**: [TrackAnalyticsEventDTO](../../interfaces/types.TrackAnalyticsEventDTO/page.mdx)
|
||||
Reference in new issue
Block a user