docs: document analytics module (#12563)

This commit is contained in:
Shahed Nasser authored and GitHub committed 2025-05-22 15:05:04 +03:00
1 parent 5ad3615830
commit 04e0b43ed8
41 files changed
+76702 -69417

No files matched your search

File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,473 @@
{
"id": 23,
"name": "analytics-provider",
"variant": "project",
"kind": 1,
"flags": {},
"children": [
{
"id": 24,
"name": "AbstractAnalyticsProviderService",
"variant": "declaration",
"kind": 128,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "### constructor\n\nThe constructor allows you to access resources from the module's container using the first parameter,\nand the module's options using the second parameter.\n\nIf you're creating a client or establishing a connection with a third-party service, do it in the constructor.\n\n#### Example\n\n"
},
{
"kind": "code",
"text": "```ts\nimport { Logger } from \"@medusajs/framework/types\"\nimport { AbstractAnalyticsProviderService } from \"@medusajs/framework/utils\"\n\ntype InjectedDependencies = {\n logger: Logger\n}\n\ntype Options = {\n apiKey: string\n}\n\nclass MyAnalyticsProviderService extends AbstractAnalyticsProviderService {\n protected logger_: Logger\n protected options_: Options\n static identifier = \"my-analytics\"\n // assuming you're initializing a client\n protected client\n\n constructor (\n { logger }: InjectedDependencies,\n options: Options\n ) {\n super()\n\n this.logger_ = logger\n this.options_ = options\n\n // assuming you're initializing a client\n this.client = new Client(options)\n }\n}\n\nexport default MyAnalyticsProviderService\n```"
}
]
},
"children": [
{
"id": 25,
"name": "identifier",
"variant": "declaration",
"kind": 1024,
"flags": {
"isStatic": true
},
"comment": {
"summary": [
{
"kind": "text",
"text": "Each analytics provider has a unique ID used to identify it. The provider's ID\nwill be stored as "
},
{
"kind": "code",
"text": "`aly_{identifier}_{id}`"
},
{
"kind": "text",
"text": ", where "
},
{
"kind": "code",
"text": "`{id}`"
},
{
"kind": "text",
"text": " is the provider's "
},
{
"kind": "code",
"text": "`id`"
},
{
"kind": "text",
"text": "\nproperty in the "
},
{
"kind": "code",
"text": "`medusa-config.ts`"
},
{
"kind": "text",
"text": "."
}
],
"blockTags": [
{
"tag": "@example",
"content": [
{
"kind": "code",
"text": "```ts\nclass MyAnalyticsProviderService extends AbstractAnalyticsProviderService {\n static identifier = \"my-analytics\"\n // ...\n}\n```"
}
]
}
]
},
"sources": [
{
"fileName": "abstract-analytics-provider.ts",
"line": 65,
"character": 9,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/utils/src/analytics/abstract-analytics-provider.ts#L65"
}
],
"type": {
"type": "intrinsic",
"name": "string"
}
},
{
"id": 26,
"name": "constructor",
"variant": "declaration",
"kind": 512,
"flags": {},
"signatures": [
{
"id": 27,
"name": "AbstractAnalyticsProviderService",
"variant": "signature",
"kind": 16384,
"flags": {},
"type": {
"type": "reference",
"target": 24,
"name": "AbstractAnalyticsProviderService",
"package": "@medusajs/utils"
}
}
]
},
{
"id": 30,
"name": "track",
"variant": "declaration",
"kind": 2048,
"flags": {},
"sources": [
{
"fileName": "abstract-analytics-provider.ts",
"line": 96,
"character": 8,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/utils/src/analytics/abstract-analytics-provider.ts#L96"
}
],
"signatures": [
{
"id": 31,
"name": "track",
"variant": "signature",
"kind": 4096,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "This method tracks an event with the third-party analytics provider. The Analytics Module\nwill use this method in its "
},
{
"kind": "code",
"text": "`track`"
},
{
"kind": "text",
"text": " method if your provider is configured in "
},
{
"kind": "code",
"text": "`medusa-config.ts`"
},
{
"kind": "text",
"text": ".\n\nYou can send the event to the third-party provider based on its semantics."
}
],
"blockTags": [
{
"tag": "@returns",
"content": [
{
"kind": "text",
"text": "Resolves when the event is tracked successfully."
}
]
},
{
"tag": "@example",
"content": [
{
"kind": "code",
"text": "```ts\nclass MyAnalyticsProviderService extends AbstractAnalyticsProviderService {\n // ...\n async track(\n data: ProviderTrackAnalyticsEventDTO\n ): Promise<void> {\n // track event to third-party provider\n // or using custom logic\n // for example:\n this.client.track(data)\n }\n}\n```"
}
]
}
]
},
"sources": [
{
"fileName": "abstract-analytics-provider.ts",
"line": 96,
"character": 8,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/utils/src/analytics/abstract-analytics-provider.ts#L96"
}
],
"parameters": [
{
"id": 32,
"name": "data",
"variant": "param",
"kind": 32768,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "The event's details."
}
]
},
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/analytics/mutations.ts",
"qualifiedName": "TrackAnalyticsEventDTO"
},
"name": "TrackAnalyticsEventDTO",
"package": "@medusajs/types"
}
}
],
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../node_modules/typescript/lib/lib.es5.d.ts",
"qualifiedName": "Promise"
},
"typeArguments": [
{
"type": "intrinsic",
"name": "void"
}
],
"name": "Promise",
"package": "typescript"
},
"implementationOf": {
"type": "reference",
"target": -1,
"name": "IAnalyticsProvider.track"
}
}
],
"implementationOf": {
"type": "reference",
"target": -1,
"name": "IAnalyticsProvider.track"
}
},
{
"id": 33,
"name": "identify",
"variant": "declaration",
"kind": 2048,
"flags": {},
"sources": [
{
"fileName": "abstract-analytics-provider.ts",
"line": 120,
"character": 8,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/utils/src/analytics/abstract-analytics-provider.ts#L120"
}
],
"signatures": [
{
"id": 34,
"name": "identify",
"variant": "signature",
"kind": 4096,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "This method identifies an actor or group in the third-party analytics provider. The Analytics Module\nwill use this method in its "
},
{
"kind": "code",
"text": "`identify`"
},
{
"kind": "text",
"text": " method if your provider is configured in "
},
{
"kind": "code",
"text": "`medusa-config.ts`"
},
{
"kind": "text",
"text": "."
}
],
"blockTags": [
{
"tag": "@returns",
"content": [
{
"kind": "text",
"text": "Resolves when the actor or group is identified successfully."
}
]
},
{
"tag": "@example",
"content": [
{
"kind": "code",
"text": "```ts\nclass MyAnalyticsProviderService extends AbstractAnalyticsProviderService {\n // ...\n async identify(\n data: ProviderIdentifyAnalyticsEventDTO\n ): Promise<void> {\n // identify actor or group in the analytics provider\n // or using custom logic\n // for example:\n this.client.identify(data)\n }\n}\n```"
}
]
}
]
},
"sources": [
{
"fileName": "abstract-analytics-provider.ts",
"line": 120,
"character": 8,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/utils/src/analytics/abstract-analytics-provider.ts#L120"
}
],
"parameters": [
{
"id": 35,
"name": "data",
"variant": "param",
"kind": 32768,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "The details of the actor or group."
}
]
},
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/analytics/mutations.ts",
"qualifiedName": "IdentifyAnalyticsEventDTO"
},
"name": "IdentifyAnalyticsEventDTO",
"package": "@medusajs/types"
}
}
],
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../node_modules/typescript/lib/lib.es5.d.ts",
"qualifiedName": "Promise"
},
"typeArguments": [
{
"type": "intrinsic",
"name": "void"
}
],
"name": "Promise",
"package": "typescript"
},
"implementationOf": {
"type": "reference",
"target": -1,
"name": "IAnalyticsProvider.identify"
}
}
],
"implementationOf": {
"type": "reference",
"target": -1,
"name": "IAnalyticsProvider.identify"
}
}
],
"groups": [
{
"title": "Constructors",
"children": [
26
]
},
{
"title": "Properties",
"children": [
25
]
},
{
"title": "Methods",
"children": [
30,
33
]
}
],
"sources": [
{
"fileName": "abstract-analytics-provider.ts",
"line": 53,
"character": 13,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/utils/src/analytics/abstract-analytics-provider.ts#L53"
}
],
"implementedTypes": [
{
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/analytics/provider.ts",
"qualifiedName": "IAnalyticsProvider"
},
"name": "IAnalyticsProvider",
"package": "@medusajs/types"
}
]
}
],
"groups": [
{
"title": "Classes",
"children": [
24
]
}
],
"packageName": "@medusajs/utils",
"symbolIdMap": {
"23": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": ""
},
"24": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "AbstractAnalyticsProviderService"
},
"25": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "AbstractAnalyticsProviderService.identifier"
},
"30": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "AbstractAnalyticsProviderService.track"
},
"31": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "AbstractAnalyticsProviderService.track"
},
"32": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "data"
},
"33": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "AbstractAnalyticsProviderService.identify"
},
"34": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "AbstractAnalyticsProviderService.identify"
},
"35": {
"sourceFileName": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts",
"qualifiedName": "data"
}
},
"files": {
"entries": {
"1": "../../../../packages/core/utils/src/analytics/abstract-analytics-provider.ts"
},
"reflections": {
"1": 23
}
}
}
@@ -0,0 +1,417 @@
{
"id": 0,
"name": "analytics",
"variant": "project",
"kind": 1,
"flags": {},
"children": [
{
"id": 1,
"name": "IAnalyticsModuleService",
"variant": "declaration",
"kind": 256,
"flags": {},
"children": [
{
"id": 2,
"name": "getProvider",
"variant": "declaration",
"kind": 2048,
"flags": {},
"sources": [
{
"fileName": "analytics/service.ts",
"line": 16,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L16"
}
],
"signatures": [
{
"id": 3,
"name": "getProvider",
"variant": "signature",
"kind": 4096,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "This method returns the service of the configured Analytics Module Provider in "
},
{
"kind": "code",
"text": "`medusa-config.ts`"
},
{
"kind": "text",
"text": ". This is useful\nif you want to execute custom methods defined in the provider's service or you need direct access to it."
}
],
"blockTags": [
{
"tag": "@returns",
"content": [
{
"kind": "text",
"text": "An instance of the Analytics Module Provider's service."
}
]
},
{
"tag": "@example",
"content": [
{
"kind": "code",
"text": "```ts\nconst postHogProviderService = analyticsModuleService.getProvider()\n// TODO: perform custom actions with the provider\n```"
}
]
}
]
},
"sources": [
{
"fileName": "analytics/service.ts",
"line": 16,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L16"
}
],
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/analytics/provider.ts",
"qualifiedName": "IAnalyticsProvider"
},
"name": "IAnalyticsProvider",
"package": "@medusajs/types"
}
}
]
},
{
"id": 4,
"name": "track",
"variant": "declaration",
"kind": 2048,
"flags": {},
"sources": [
{
"fileName": "analytics/service.ts",
"line": 35,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L35"
}
],
"signatures": [
{
"id": 5,
"name": "track",
"variant": "signature",
"kind": 4096,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "This method tracks an event in the analytics provider. The Analytics Module\nwill use the "
},
{
"kind": "code",
"text": "`track`"
},
{
"kind": "text",
"text": " method of the underlying provider configured in "
},
{
"kind": "code",
"text": "`medusa-config.ts`"
},
{
"kind": "text",
"text": " to track the event."
}
],
"blockTags": [
{
"tag": "@returns",
"content": [
{
"kind": "text",
"text": "Resolves when the event is tracked successfully."
}
]
},
{
"tag": "@example",
"content": [
{
"kind": "code",
"text": "```ts\nawait analyticsModuleService.track({\n event: \"order_placed\",\n properties: {\n order_id: \"order_123\",\n customer_id: \"customer_456\",\n total: 100,\n }\n})\n```"
}
]
}
]
},
"sources": [
{
"fileName": "analytics/service.ts",
"line": 35,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L35"
}
],
"parameters": [
{
"id": 6,
"name": "data",
"variant": "param",
"kind": 32768,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "The event's details."
}
]
},
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/analytics/mutations.ts",
"qualifiedName": "TrackAnalyticsEventDTO"
},
"name": "TrackAnalyticsEventDTO",
"package": "@medusajs/types"
}
}
],
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../node_modules/typescript/lib/lib.es5.d.ts",
"qualifiedName": "Promise"
},
"typeArguments": [
{
"type": "intrinsic",
"name": "void"
}
],
"name": "Promise",
"package": "typescript"
}
}
]
},
{
"id": 7,
"name": "identify",
"variant": "declaration",
"kind": 2048,
"flags": {},
"sources": [
{
"fileName": "analytics/service.ts",
"line": 52,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L52"
}
],
"signatures": [
{
"id": 8,
"name": "identify",
"variant": "signature",
"kind": 4096,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "This method identifies an actor or group in the analytics provider. The Analytics Module\nwill use the "
},
{
"kind": "code",
"text": "`identify`"
},
{
"kind": "text",
"text": " method of the underlying provider configured in "
},
{
"kind": "code",
"text": "`medusa-config.ts`"
},
{
"kind": "text",
"text": " to identify the actor or group."
}
],
"blockTags": [
{
"tag": "@returns",
"content": [
{
"kind": "text",
"text": "Resolves when the actor or group is identified successfully."
}
]
},
{
"tag": "@example",
"content": [
{
"kind": "code",
"text": "```ts\nawait analyticsModuleService.identify({\n actor_id: \"123\",\n properties: {\n name: \"John Doe\"\n }\n})\n```"
}
]
}
]
},
"sources": [
{
"fileName": "analytics/service.ts",
"line": 52,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L52"
}
],
"parameters": [
{
"id": 9,
"name": "data",
"variant": "param",
"kind": 32768,
"flags": {},
"comment": {
"summary": [
{
"kind": "text",
"text": "The details of the actor or group."
}
]
},
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/analytics/mutations.ts",
"qualifiedName": "IdentifyAnalyticsEventDTO"
},
"name": "IdentifyAnalyticsEventDTO",
"package": "@medusajs/types"
}
}
],
"type": {
"type": "reference",
"target": {
"sourceFileName": "../../node_modules/typescript/lib/lib.es5.d.ts",
"qualifiedName": "Promise"
},
"typeArguments": [
{
"type": "intrinsic",
"name": "void"
}
],
"name": "Promise",
"package": "typescript"
}
}
]
}
],
"groups": [
{
"title": "Methods",
"children": [
2,
4,
7
]
}
],
"sources": [
{
"fileName": "analytics/service.ts",
"line": 5,
"character": 17,
"url": "https://github.com/medusajs/medusa/blob/db33616cf9ea3b8bd61d60a1e601d649bdea2bdf/packages/core/types/src/analytics/service.ts#L5"
}
],
"extendedTypes": [
{
"type": "reference",
"target": {
"sourceFileName": "../../../../packages/core/types/src/modules-sdk/index.ts",
"qualifiedName": "IModuleService"
},
"name": "IModuleService",
"package": "@medusajs/types"
}
]
}
],
"groups": [
{
"title": "Interfaces",
"children": [
1
]
}
],
"packageName": "@medusajs/types",
"symbolIdMap": {
"0": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": ""
},
"1": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService"
},
"2": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService.getProvider"
},
"3": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService.getProvider"
},
"4": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService.track"
},
"5": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService.track"
},
"6": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "data"
},
"7": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService.identify"
},
"8": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "IAnalyticsModuleService.identify"
},
"9": {
"sourceFileName": "../../../../packages/core/types/src/analytics/service.ts",
"qualifiedName": "data"
}
},
"files": {
"entries": {
"1": "../../../../packages/core/types/src/analytics/service.ts"
},
"reflections": {
"1": 0
}
}
}