GA4

Sends each tracking event to the page's gtag as a GA4 event, gtag('event', name, params), with GA4's items built from the SDK's lines. Vendor docs: GA4 events.

Config

Off by default. On:

CODE

<script>
  window.nextConfig = {
    analytics: {
      destinations: { ga4: { enabled: true } },
    },
  };
</script>

What loads

ga4-*.js (about 2 KB), only when it is on. The SDK never loads the Google tag: the page has gtag. Without it the SDK logs one warning and sends nothing.

Events

Tracking event	GA4 event
`page_viewed`	Not sent
`product_viewed`	`view_item`
`product_list_viewed`	`view_item_list`
`product_added_to_cart`	`add_to_cart`
`product_removed_from_cart`	`remove_from_cart`
`cart_updated`	`update_cart`
`checkout_started`	`begin_checkout`
`checkout_contact_info_submitted`	`generate_lead`
`checkout_shipping_address_submitted`	`add_shipping_info`
`checkout_shipping_method_submitted`	`add_shipping_info`
`checkout_payment_info_submitted`	`add_payment_info`
`checkout_completed`	`purchase`
`upsell_completed`	`purchase`
`upsell_viewed`	`view_upsell`
`upsell_skipped`	`skip_upsell`
`promotion_viewed`	`view_promotion`
`promotion_selected`	`select_promotion`

page_viewed is not sent: gtag('config', …) sends GA4's own page_view. checkout_completed and each upsell_completed are a purchase of their own, with the tracking event's event_id as transaction_id, so GA4 counts each once. A property tagged through GTM uses the GTM pushes instead; with both on, it gets each event twice.

view_item

A product the shopper sees. See the GA4 reference.

From product_viewed.

The fields of Ga4Ecommerce.

CODE

gtag('event', 'view_item', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
});

view_item_list

The products a page shows. See the GA4 reference.

From product_list_viewed.

The fields of Ga4Ecommerce, and:

Field	Type	Present
`item_list_id`	`string`	optional
`item_list_name`	`string`	optional

CODE

gtag('event', 'view_item_list', {
  currency: 'USD',
  value: 138,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
    {
      item_id: '2',
      item_name: 'Earbuds ×2',
      price: 44.5,
      discount: 54.5,
      quantity: 2,
      index: 1,
    },
  ],
  item_list_id: 'product_list',
  item_list_name: 'Product List',
});

add_to_cart

A product added to the cart. See the GA4 reference.

From product_added_to_cart.

The fields of Ga4Ecommerce.

CODE

gtag('event', 'add_to_cart', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
});

remove_from_cart

A product removed from the cart. See the GA4 reference.

From product_removed_from_cart.

The fields of Ga4Ecommerce.

CODE

gtag('event', 'remove_from_cart', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
});

begin_checkout

The checkout started. See the GA4 reference.

From checkout_started.

The fields of Ga4Ecommerce.

CODE

gtag('event', 'begin_checkout', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
});

generate_lead

The shopper left their contact details. See the GA4 reference.

From checkout_contact_info_submitted.

Field	Type	Present
`currency`	`string`	optional
`value`	`number`	optional
`lead_source`	`"checkout"`	always

CODE

gtag('event', 'generate_lead', {
  currency: 'USD',
  value: 49,
  lead_source: 'checkout',
});

add_shipping_info

The shipping address or method was given. See the GA4 reference.

From checkout_shipping_address_submitted, checkout_shipping_method_submitted.

The fields of Ga4Ecommerce, and:

Field	Type	Present
`shipping_tier`	`string`	optional

CODE

gtag('event', 'add_shipping_info', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
  shipping_tier: 'Standard',
});

add_payment_info

The payment details were submitted. See the GA4 reference.

From checkout_payment_info_submitted.

The fields of Ga4Ecommerce, and:

Field	Type	Present
`payment_type`	`string`	optional

CODE

gtag('event', 'add_payment_info', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
  payment_type: 'Credit Card',
});

purchase

An order was paid: the order, or one accepted upsell with its own transaction_id. See the GA4 reference.

From checkout_completed, upsell_completed.

The fields of Ga4Purchase.

CODE

gtag('event', 'purchase', {
  currency: 'USD',
  value: 89,
  items: [
    {
      item_id: 'EB-2',
      item_name: 'Earbuds',
      price: 44.5,
      discount: 47.17,
      quantity: 2,
      index: 0,
    },
  ],
  transaction_id: '1001',
  shipping: 9.99,
  tax: 7.12,
});

view_promotion

A promotion was shown. See the GA4 reference.

From promotion_viewed.

Field	Type	Present
`promotion_id`	`string`	always
`promotion_name`	`string`	optional
`creative_name`	`string`	optional

CODE

gtag('event', 'view_promotion', {
  promotion_id: 'exit_intent',
  promotion_name: 'Exit offer',
  creative_name: 'exit-offer',
});

select_promotion

A promotion was clicked. See the GA4 reference.

From promotion_selected.

Field	Type	Present
`promotion_id`	`string`	always
`promotion_name`	`string`	optional
`creative_name`	`string`	optional

CODE

gtag('event', 'select_promotion', {
  promotion_id: 'exit_intent',
  promotion_name: 'Exit offer',
  creative_name: 'exit-offer',
});

update_cart

Custom: the cart after a price update.

From cart_updated.

The fields of Ga4Ecommerce.

CODE

gtag('event', 'update_cart', {
  currency: 'USD',
  value: 49,
  items: [
    {
      item_id: '1',
      item_name: 'Earbuds ×1',
      price: 49,
      discount: 50,
      quantity: 1,
      index: 0,
    },
  ],
});

view_upsell

Custom: an upsell offer was shown.

From upsell_viewed.

Field	Type	Present
`order_id`	`string`	always
`currency`	`string`	optional
`value`	`number`	optional
`items`	`Ga4Item[]`	always

CODE

gtag('event', 'view_upsell', {
  order_id: 'R1',
  currency: 'USD',
  items: [],
});

skip_upsell

Custom: an upsell offer was skipped.

From upsell_skipped.

Field	Type	Present
`order_id`	`string`	always
`currency`	`string`	optional
`value`	`number`	optional
`items`	`Ga4Item[]`	always

CODE

gtag('event', 'skip_upsell', {
  order_id: 'R1',
  currency: 'USD',
  items: [
    {
      item_id: '3',
      quantity: 1,
      index: 0,
    },
  ],
});

Types

Ga4Ecommerce

The parameters GA4's ecommerce events share.

Field	Type	Present
`currency`	`string`	optional	ISO 4217, such as `USD`.
`value`	`number`	optional	Σ `price × quantity` of `items`.
`coupon`	`string`	optional	The first code the shopper applied.
`items`	`Ga4Item[]`	always

Ga4Purchase

An order or one accepted upsell, as GA4 counts revenue.

Field	Type	Present
`coupon`	`string`	optional	The first code the shopper applied.
`items`	`Ga4Item[]`	always
`transaction_id`	`string`	always	The tracking event's `event_id`: the order number, or `<ref_id>-US<n>` for an upsell.
`value`	`number`	always	Σ `price × quantity` of `items`.
`currency`	`string`	optional	ISO 4217; left out when neither the order nor the campaign has one.
`shipping`	`number`	optional
`tax`	`number`	optional

Ga4Item

One product of a GA4 event's items.

Field	Type	Present
`item_id`	`string`	always	The line's SKU, else its package id.
`item_name`	`string`	optional
`item_variant`	`string`	optional
`price`	`number`	optional	What one unit costs, after discounts.
`discount`	`number`	optional	The discount on one unit.
`quantity`	`number`	always
`index`	`number`	always	Position in `items`, from 0.