Can we retrieve information from UTM campaigns?

Collect UTMs as dedicated UTM properties (event scope)

By default, UTM parameters are recognized and collected thanks to the default setting of the enableUTMTracking configuration key.

When enabled, UTMs are collected into dedicated properties:

utm_term (utm_term)
utm_source (utm_source)
utm_medium (utm_medium)
utm_content (utm_content)
utm_campaign (utm_campaign)

Important: UTMs are event-scoped by design

UTM properties are event-scoped, meaning they are only valued on events sent when the UTM parameters are present in the URL (typically the first page.display after landing on a campaign URL). During the same visit, subsequent events may have empty UTM properties if the URL no longer contains UTMs.

This is a common reason for confusion when analyzing conversions/transactions: transaction events often occur on URLs without UTMs, so the UTM properties can be empty on those events even though the visit started from a campaign link.

If you need a single, consistent campaign attribution across all events in a visit (including transactions), use visit-scoped source properties (src_…) as described below.

Use UTMs in source attribution (visit scope) with the SDK

The Piano Analytics SDK allows UTM parameters to be taken into account in the source attribution algorithm if the campaignPrefix parameter is set to take into account the UTM parameters:

CODE

pa.setConfiguration('campaignPrefix', ['at_', 'utm_']);

With this configuration, UTMs can contribute to visit-level marketing source attribution:

src_medium and src_campaign (mandatory to count a marketing source) will be valued by utm_medium and utm_campaign (when at_ parameters are not present).
If both at_ and utm_ are present, the order in campaignPrefix determines the priority. With ['at_', 'utm_'], at_ takes precedence. If you want to prioritize UTMs, place utm_ first (for example ['utm_', 'at_']).

Other UTM parameters as sources (`src_…`)

Other UTM parameters will be counted as sources if custom properties are declared with a src_ prefix (for example src_source, src_term, src_content). This is typically used to make values like utm_source, utm_term, or utm_content available as visit-scoped properties for attribution and conversion analysis.

src_ is a fixed prefix used by the source attribution mechanism.

Troubleshooting

“Unclassified campaign” or campaign not counted as a marketing source

Most often this happens when: - utm_medium and/or utm_campaign is missing from the URL, or - UTMs are collected as event properties but not mapped/configured to populate src_medium and src_campaign (visit scope).

UTMs visible on page views but missing on transactions

This is expected when UTMs are only collected as event-scoped properties. Use visit-scoped source properties (src_…) for conversion/transaction attribution analysis.

Existing visit source not replaced by a new UTM link

A visit has only one source. If a visitor clicks a UTM-tagged link while a visit is already open (for example, navigating between subdomains that share cookies), the existing visit source is not replaced unless you explicitly force it (for example with src_force: true, depending on your implementation and consent constraints).