Google Analytics 4

The Google Analytics 4 app sends your store's purchases, refunds and sign-ups to Google Analytics 4 from the server, with GA4's Measurement Protocol. The events are recorded even when an ad blocker or a closed tab stops browser tracking, and they can be joined to the shopper's browser session.

Install Google Analytics 4 from the Swell App Store, and set it up in your test environment before the live one.

// Storefront: after gtag.js is loaded and the cart exists
const MEASUREMENT_ID = 'G-XXXXXXXXXX';
gtag('get', MEASUREMENT_ID, 'client_id', (clientId) => {
  gtag('get', MEASUREMENT_ID, 'session_id', (sessionId) => {
    swell.cart.update({ metadata: { ga_client_id: clientId, ga_session_id: sessionId } });
  });
});

Each order is sent once, as a purchase event, when it's paid, or when it's submitted if Send purchase when is set to Order is submitted. Drafts and canceled orders aren't sent. The event has:

When the order is less than 72 hours old, the event is dated with the order's submission time.

With Send refunds on, every successful refund of an order's payment is sent as its own refund event, with that refund's amount and the Swell refund ID as transaction_id. An order refunded several times sends several refund events. Each event also carries the custom parameters order_id and order_number. To use them in GA4 reports, register them as event-scoped custom dimensions under Admin > Custom definitions.

With Refund canceled orders on, canceling an order reports the part of its total that isn't refunded yet, with the order number as transaction_id. Refunds are only sent for orders whose purchase was sent, never add up to more than the order total, and don't list items.

With Send sign-ups on, a sign_up event with method: email is sent when a customer account is created, including accounts created at checkout.

GA4 links events through the client ID. The app uses the client and session IDs your storefront saved in the cart or account metadata. Without them, it uses swell.<customer ID>, or swell.<order ID> for guest orders, and each event starts its own session. Those events still count in reports and show in Realtime and DebugView, but they're attributed to (direct) / (not set) traffic. With Send user ID on, the Swell customer ID is also sent as user_id, so GA4 can join a customer's devices.

To send purchases that were missed, for example orders placed before you set up the app, open an order and choose Actions > Send purchase to GA4, or select up to 25 orders in the order list and choose Send to GA4. GA4 only accepts events up to 72 hours old, so older orders are skipped, along with orders that were already sent or aren't paid. The result lists the skipped orders.

Settings are in Apps > Google Analytics 4 > Settings and are saved separately for each environment. Events and Advanced settings are on their own tabs.

Each order's Google Analytics tab shows the last error the app got for it. The app also logs each event it sends. In the Swell dashboard, the logs are under Developer > Console > Logs.

Validate setup checks the saved settings. Copy the Measurement ID from your GA4 web stream, click Save settings, then run Validate setup again.

Create an API secret for the web stream in GA4, enter it, and save before you validate.

The message lists what GA4's validation server didn't accept. Check that the Measurement ID is the one from your web stream.

The validation server doesn't check the API secret. Check that the secret belongs to the same web stream as the Measurement ID and that Enable Integration is on. Turn on Debug mode and look in Admin > DebugView, since standard reports take 24 to 48 hours.

Purchases are sent when the order is paid, or submitted if you chose that, and only while the integration is on. Drafts and canceled orders aren't sent. If the order is less than 72 hours old, choose Actions > Send purchase to GA4 on the order.

GA4 doesn't accept events older than 72 hours, so these orders can't be sent.

Your storefront probably sends purchase events with gtag.js too. Turn those off.

The storefront doesn't save the shopper's GA4 client and session IDs. Add the snippet from step 5 of Set up.

Check that Send refunds is on and that the order's purchase was sent. Refunds of payments without an order aren't sent. In GA4, refunds have the Swell refund ID as their transaction ID, not the order number.

Uninstalling the app stops sending events to GA4, and removes the Google Analytics tab, the GA4 column and the Send to GA4 actions from your dashboard. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

Events already sent stay in GA4. If you no longer need the Measurement Protocol API secret, delete it in GA4.

Events are posted to https://www.google-analytics.com/mp/collect, or https://region1.google-analytics.com/mp/collect with the EU endpoint.

The app keeps its status on orders under $app.ga4: ga4_purchase_sent_at, ga4_client_id, ga4_refund_value, ga4_refunds (the amounts reported, by Swell refund ID, or canceled), ga4_refund_sent_at and ga4_error. It saves them with $events: false, so they don't trigger order events.

The storefront fields it reads are metadata.ga_client_id and metadata.ga_session_id, on the cart, which Swell copies to the order, or on the account for sign-ups.

Swell builds and maintains the Google Analytics 4 app. For help with the app, email support@swell.is. For questions about your GA4 property, see Google Analytics Help.