[relaybell docs › Install › Google Analytics events](https://relaybell.com/docs/google-analytics) · [All docs as Markdown](https://relaybell.com/docs.md) · [Index for AI assistants](https://relaybell.com/llms.txt)

# Google Analytics events

> Use the GA4 e-commerce events your site already pushes to the dataLayer: what is recorded, consent mode, orders counted once, privacy.

If your website already sends shop events to **Google Analytics 4** (through Google Tag Manager or `gtag.js`), relaybell can use them too — no extra code. Turn on **Settings → Install → Tracking → Use your Google Analytics (GA4) e-commerce events**, and relaybell's script reads those events from the page and records them as relaybell events. They then work like events you send yourself: in [automations](https://relaybell.com/docs/events-automation) (cart reminders, thank-you messages), [segments](https://relaybell.com/docs/segments-topics), [product alerts](https://relaybell.com/docs/product-alerts) and conversion reports.

## How it works

Your pages push GA4 events into `window.dataLayer`, either as Tag Manager objects or through `gtag()`:

```js
// Google Tag Manager
dataLayer.push({ event: "view_item", ecommerce: { currency: "USD", value: 19.99, items: [{ item_id: "TEE-01", item_name: "Blue Tee", item_brand: "Acme", item_category: "Apparel", item_category2: "Tees", price: 19.99, quantity: 1 }] } });

// gtag.js
gtag("event", "purchase", { transaction_id: "1042", currency: "USD", value: 54.98, items: [/* … */] });
```

relaybell's script (`relaybell-sdk.js`, which you already have on the page) reads the events that were pushed before it loaded, once, and every event pushed after. It never changes them: Google Tag Manager and Google Analytics get exactly what they got before, whichever script loads first.

Events are recorded **only for visitors who subscribed to your notifications or who are signed in on your site** (you pass their User ID as `externalId`), like [auto-capture](https://relaybell.com/docs/events-automation#auto-capture). Nothing is recorded for anyone else.

## What is recorded

| Google Analytics event | relaybell event | Properties |
| --- | --- | --- |
| `view_item` | `product.viewed` | the first item: `productId`, `product`, `category`, `brand`, `price`, `quantity`, plus `currency`, `url` (the page, without its query string), `image` |
| `select_item` | `product.viewed` | the same |
| `add_to_cart` | `cart.updated` | the same, plus `value` (the amount added) and `items` when several were added |
| `begin_checkout` | `checkout.started` | `value`, `currency`, `orderId` (when there is one), `items`, `url` |
| `purchase` | `purchase` | `value`, `currency`, `orderId` (the `transaction_id`), `items`, `url` — only when it has a `transaction_id` |
| `view_item_list` | — | not recorded (a list isn't interest in one product) |

Each item in `items` has `productId`, `product`, `category`, `brand`, `price` and `quantity`. They come from GA4's `item_id`, `item_name`, `item_category` (joined with `item_category2` as `Apparel > Tees` when both are set), `item_brand`, `price` and `quantity`. `image` is taken from an item's `image_url` when your site adds one. Other GA4 fields (tax, coupons, list names…) are left out.

`url` is the page's address without the part after `?` or `#`, so order keys on a thank-you page (`?key=wc_order_…`) or an email address in a campaign link never reach relaybell. A `purchase` without a `transaction_id` isn't recorded: it couldn't be counted once, and every reload of the thank-you page would add another.

### Other events (optional)

Under the switch you can add other Google Analytics events and the relaybell name to record them under, for example `sign_up` as `signup` or `generate_lead` as `lead` (up to 20). Their simple parameters (text, numbers, true/false) come along, except anything that looks personal: parameters named like an email, phone, name, address or user ID, and any value that contains an email address. A `value` parameter makes the event count as a conversion with that value.

## Consent

relaybell follows **Google Consent Mode**. It reads the `consent` commands in the dataLayer (`gtag("consent", "default" | "update", …)`, also when your consent banner sets them through Tag Manager) and records nothing while `analytics_storage` is `denied`. An `update` (the visitor's choice) always wins over a `default`; a `denied` default for some regions counts as denied until the visitor grants it. A site that doesn't use Consent Mode is recorded as normal.

With `RelayBell.init({ requireConsent: true })`, nothing is recorded until your site calls `RelayBell.grantConsent()`. Events from before consent aren't sent later.

## Orders counted once

The same order may reach relaybell twice: from the visitor's browser (this feature) and from your store's server (the [WordPress plugin](https://relaybell.com/docs/install-wordpress), [Shopify webhooks](https://relaybell.com/docs/install-shopify) or your own `POST /api/v1/events`). An order event — `purchase`, `checkout.started`, `order.completed` or `checkout.completed` — with the same `orderId` within 7 days is **stored once**, so conversions and revenue count it once:

- The copy from your server is the reference: its details (such as the order total) win over the browser's, whichever arrives first. What only the browser's copy has — usually the `items` — is kept (unless that browser named a different shopper), so relaybell still knows which products were bought.
- When your server names a different shopper than the browser did, the order is moved to the shopper your server named: the browser copy's conversion and revenue are taken back, and its pending automation pushes and the journeys it started are stopped.
- A later copy that names the shopper (a subscribed browser) adds them to an order that was stored without one (a guest checkout reported by the server).
- If one browser reported the order and a **different** subscribed browser reports it too (and your server hasn't named the buyer yet), the second isn't merged into the first: it is stored for its own subscriber (once). When your server then names the second shopper, their copy becomes the order and the first browser's credit is taken back. Whoever reports an order number first can't take the order away from the real buyer.
- Anything else — a reloaded thank-you page, a webhook sent again — is not stored again. `POST /api/v1/events` then answers `202` with `duplicate: true` and the stored event's `eventId` (and `merged: true` when this copy updated it). The browser's endpoint answers `202 { "ok": true }` for every order event that has an `orderId`, new or not, so it never tells anyone which order numbers exist.

Order numbers are compared as text, so `1042` from WooCommerce and `"1042"` from the dataLayer are the same order. Events without an `orderId` are stored each time, as before.

### Custom order numbers

Most Google Analytics plugins for WooCommerce put the order **number** in `transaction_id`. Out of the box that is the order's ID, but a sequential or prefixed order number plugin (for example `WC-1001`) makes the two different. When your server knows both, send the number as `orderNumber` next to `orderId`: `{ "orderId": 1234, "orderNumber": "WC-1001" }`. relaybell then matches the order by its number, so the browser's `transaction_id: "WC-1001"` is the same order. (`orderNumber` is used only on events your server sends with an API key.) Until your server sends it, a store with custom order numbers gets the order twice: once from the browser and once from the server.

> **Note:** If your site reports orders **only** from the browser, someone could report a guessed future order number first and get credit for it. The real buyer's own copy is still counted for them, and sending orders from your server too (the WordPress plugin, Shopify webhooks or the API) takes the false credit back.

## Privacy

- The data comes from your visitors' browsers, from what your own pages put in the dataLayer — **never from Google's servers**. relaybell doesn't connect to your Google Analytics account and can't read your reports.
- Nothing is recorded for visitors who neither subscribed nor signed in, while Consent Mode denies analytics storage, or while `requireConsent` waits.
- relaybell takes only the shop fields listed above. It never takes personal details from the page.
- At most 20 events a minute are recorded per page, and the same event for the same product or order once in 10 seconds.

## Turning it on in code

The **Tracking** switch is all most sites need. The script can also be told directly:

```js
RelayBell.init({
  projectId: "YOUR_PROJECT_ID",
  dataLayer: true,                                  // read it whatever the switch says
  // or: dataLayer: { events: { sign_up: "signup" }, ecommerce: true, name: "dataLayer" }
  // or: dataLayer: false                           // never read it on this page
});
```

`name` is for a site whose Tag Manager uses a renamed data layer. With [Google Tag Manager](https://relaybell.com/docs/install-gtm), tick **Read GA4 e-commerce events** in the relaybell tag instead.