# Ecommerce

Double Agent keeps a **basic** ecommerce picture with each session, as signals of intent: the products a visitor viewed,
whether they added to the cart, started checkout and ordered, and the order value. Field and event names are Google
Analytics 4's. Each product is recorded under **its own name**, not the page's title. HQ shows it in the session's
Visit section. It needs the script (0.12.0 or later).

## GA4 dataLayer: nothing to add

If your site already sends GA4 ecommerce events through Google Tag Manager or gtag.js, Double Agent reads them from
`window.dataLayer` as they happen:

```js
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_to_cart',
  ecommerce: { currency: 'USD', value: 129.5, items: [{ item_id: 'LMD-042', item_name: 'Linen midi dress', price: 129.5, quantity: 1 }] },
});

gtag('event', 'purchase', { transaction_id: 'T-1001', currency: 'USD', value: 259, items: [/* … */] });
```

Events pushed before the script loaded count too. Your own `push` runs first, and an error on our side never reaches
your tags.

## Or call it yourself

Same events, same payload as GA4:

```js
doubleagent.ecommerce('view_item', { items: [{ item_id: 'LMD-042', item_name: 'Linen midi dress', price: 129.5, currency: 'USD' }] });
doubleagent.ecommerce('add_to_cart', { currency: 'USD', value: 129.5, items: [{ item_id: 'LMD-042', quantity: 1 }] });
doubleagent.ecommerce('purchase', { transaction_id: 'T-1001', currency: 'USD', value: 259, items: [{ item_id: 'LMD-042', price: 129.5, quantity: 2 }] });
```

Before the script has loaded, queue the call: `doubleagent.push('ecommerce', 'add_to_cart', { … })`.

## Events and fields

| Event | When |
|---|---|
| `view_item` | The page's product. Read automatically from your product page's metadata when you send nothing |
| `add_to_cart` | A cart add. Without your data, a click on an add-to-cart button counts as one `add_to_cart` of the page's product |
| `begin_checkout` | Checkout started |
| `purchase` | An order: `transaction_id`, `value`, `currency`, items |

Item fields: `item_id`, `item_name`, `price`, `currency` and, on cart and order lines, `quantity`. Other GA4 events and
fields are ignored.

When a field comes from several places, your dataLayer wins over `ecommerce()` calls, and both win over the page's
metadata: schema.org `Product` (JSON-LD or microdata), Open Graph product tags, and Shopify's storefront product
object.

## Privacy

- **Only the fields above are read.** `user_data`, `customer`, email addresses, phone numbers, postal addresses and
  payment details in your dataLayer are never read or sent.
- Product names are redacted like site-search terms: email addresses and long digit runs become `[redacted]`.
- Order ids are stored only as a hash, used to count an order once. Order values and prices are your business data and
  are kept with the session for 90 days.
- Cart, checkout and purchase events are sent only with analytics consent. The page's product is catalogue data, sent
  like the page path.
- **Off:** `data-ecommerce="off"` on the script tag, or `init({ ecommerce: false })`.

Limits: 50 products per event, 100 events per page load.