Conversion Attribution

Attribute purchases to Loops AI using either UTM parameters or event-based attribution with the loops_ref custom dimension.

When a shopper clicks a product recommended by Loops AI, that click can be attributed back to the agent so you can measure the revenue it drives. There are two options, and you pick exactly one per agent — they are never combined.

The two options

Option	How it tags clicks	When to use it
UTM-based attribution	Appends standard `utm_source` / `utm_medium` / `utm_campaign` parameters to product links.	The default. Works with any analytics tool that already reports on UTM / session source.
Loops AI event-based attribution	Appends a single `loops_ref` parameter to product links and reports through a GA4 custom dimension.	Source-safe: it never overwrites the shopper's original traffic source, so your acquisition channels stay intact.

The mode is controlled by the UTM tracking switch on the agent's web channel (utmTracking.enabled):

enabled: true (default) → UTM mode.
enabled: false → Event mode.

The two modes are mutually exclusive. In UTM mode Loops AI emits only utm_* parameters and no loops_ref. In event mode Loops AI emits only loops_ref and no utm_* parameters. Loops AI never emits both signals at once.

UTM-based attribution

This is the status quo and requires no extra setup. With UTM tracking enabled, product links carry:

utm_source — your attribution label (default loopsai).
utm_medium, utm_campaign, utm_content, utm_term.

Your GA4 property reports these clicks under the standard Session source / medium dimensions, so any existing UTM dashboard already picks them up. Nothing further is required.

Loops AI event-based attribution

Event mode keeps the shopper's original traffic source untouched. Instead of UTM parameters, Loops AI appends a single query parameter to each product link:

https://store.example.com/products/blue-shoe?loops_ref=loopsai

The loops_ref value is your attribution label (the same value as analyticsConfig.channels.web.searchSourceValue, default loopsai). To report on it, you register a GA4 event-scoped custom dimension and capture the parameter on your conversion events.

Set it up

Register the `loops_ref` custom dimension in GA4

In GA4 go to Admin → Custom definitions → Custom dimensions → Create custom dimension:

Dimension name: loops_ref
Scope: Event
Event parameter: loops_ref

Save it. GA4 now reports this dimension as customEvent:loops_ref.

Capture the `loops_ref` URL parameter in GTM

In Google Tag Manager, create a URL variable that reads the loops_ref query parameter:

Variables → New → URL → Component Type: Query → Query Key: loops_ref.
Name it e.g. url - loops_ref.

Persist it for the session

A shopper may land via the loops_ref link but convert a few pages later, after the parameter has dropped off the URL. Persist the value so it survives navigation:

On a Page View trigger, when url - loops_ref is non-empty, write it to sessionStorage (for example with a small Custom HTML or Custom JavaScript variable).
Create a second variable that reads the persisted value back out of sessionStorage, falling back to the URL variable.

Attach `loops_ref` as an event parameter on GA4 events

On your GA4 event tags, add an event parameter named loops_ref whose value is the persisted variable from the previous step. At a minimum attach it to:

add_to_cart
purchase

This is what populates the customEvent:loops_ref dimension in your reports.

(Optional) Register the item-scoped `recommended_by` dimension

Loops AI also stamps each item in the ecommerce items[] array with recommended_by set to your attribution label. This field is additive and safe in both modes. If you want item-level attribution, register a second custom dimension:

Dimension name: recommended_by
Scope: Item
Item parameter: recommended_by

This lets you break conversions down to the individual products Loops AI recommended.

Custom dimensions in GA4 are forward-only: data is collected from the moment you register the dimension. Historical events are not backfilled, so register loops_ref (and recommended_by) before you start measuring.

Mobile / SDK

The same loops_ref mechanism works inside the iOS and Android SDKs — as long as the link opens in a web context that runs your GTM. By default the SDK opens outbound links in an in-app browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android), which is exactly such a context.

The SDK forwards the tapped link with its full query string intact, so the loops_ref parameter arrives unchanged and the GTM recipe above fires with no mobile-specific setup. Your existing custom dimension keeps collecting.

If your app overrides link handling to route a product tap into a native screen instead of a web page, the URL parameter never reaches web GA4 — there is no web page load to run GTM. Event-based native attribution for that case is coming soon; reach out to your Loops AI contact if you need it today.

Without the SDK

If you host the runtime yourself in a WebView (Mobile WebView), the tagging still happens inside the runtime and the URL still reaches you with its query string intact — but there is no default in-app browser, because that default lives in the SDK. Whatever you do with the URL decides whether attribution survives, so open product links in an in-app browser (SFSafariViewController, Chrome Custom Tabs, or your framework's equivalent) as your default handler, exactly as the SDKs do. Details: Links & navigation.

Reporting

Once the dimension is collecting data, the Loops AI dashboard reads conversions back through the GA4 Data API:

UTM mode reports on the sessionSource field, matching your attribution label.
Event mode reports on the customEvent:loops_ref field, matching your attribution label.

If the custom dimension has not been registered yet, or GA4 returns no rows for it, the dashboard shows zero conversions with an integrate to see conversions prompt rather than an error.

On this page