Google Analytics

Medusa GA4 Plugin

A Google Analytics 4 plugin for Medusa that automatically tracks ecommerce events on your backend using Measurement Protocol. This plugin implements server-side tracking for key ecommerce events in your Medusa store.

Features

The plugin automatically tracks the following GA4 ecommerce events:

• add_to_cart - When items are added to a cart
• remove_from_cart - When items are removed from a cart
• add_shipping_info - When shipping information is added to a cart
• add_payment_info - When payment information is added
• purchase - When an order is placed

Prerequisites

• Medusa backend
• Google Analytics 4 property
• GA4 Measurement ID
• GA4 API Secret

Installation

yarn add @variablevic/google-analytics-medusa

Configuration

Add the plugin to your medusa-config.ts:

1import { defineConfig } from "@medusajs/utils";
2
3// ... other imports and environment variables
4
5export default defineConfig({
6  // ... other configurations
7  plugins: [
8    // ... other plugins
9    {
10      resolve: "@variablevic/google-analytics-medusa",
11      options: {
12        measurementId: "G-XXXXXXXX", // Your GA4 Measurement ID
13        apiSecret: "XXXXXXXXXX", // Your GA4 API Secret
14        debug: false, // Optional, enables debug mode - no events will be sent to your property when debug is active!
15      },
16    },
17  ],
18});

Client-Side Setup

This plugin handles server-side events, but some GA4 ecommerce events need to be implemented on the client side due to their nature:

• view_item - Product views
• begin_checkout - Checkout initiation
• sign_up - User registration
• login - User login

Additionally, to properly associate events with users, you need to set the GA client ID as metadata when creating a cart. Here's how to do it in the Next.js Starter:

1. Get the GA client ID from the cookie:

1export const getGaClientId = async (): Promise<string | null> => {
2  const cookies = await nextCookies();
3  const gaClientIdCookie = cookies.get("_ga")?.value;
4
5  const gaClientId = (gaClientIdCookie as string)
6    .split(".")
7    .slice(-2)
8    .join(".");
9
10  return gaClientId;
11};

1. Set the client ID as cart metadata during cart creation:

1const gaClientId = await getGaClientId();
2
3const body = {
4  region_id: region.id,
5} as Record<string, any>;
6
7if (gaClientId) {
8  body.metadata = {
9    ga_client_id: gaClientId,
10  };
11}
12
13const cartResp = await sdk.store.cart.create(body, {}, headers);

Events Data Format

The plugin automatically formats cart and order data according to GA4's ecommerce event specifications. Each event includes:

• Currency code
• Transaction value
• Item-level details (name, variant, quantity, price)
• Customer information when available

Development

1. Clone this repository
2. Install dependencies: yarn install
3. Build the project: yarn build
4. Test the plugin: yarn test

For local development and testing:

npx medusa plugin:develop

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

License

MIT