Set up a persisted property

Setting up a persisted property takes two steps: make sure the event property you want to persist is actually on your events, then create the persisted property in Amplitude Data and configure how it allocates.

For what persisted properties are and when to use them, refer to Persisted properties.

Capture the event property

Persisted properties read from event properties, so the upstream question is making sure the values you want to persist arrive as event properties in the first place.

Marketing attribution (Browser SDK 2)

As of Browser SDK version 2.45.0 and GTM template version 5d7e5, attribution tracking via event properties is on by default. UTM parameters, referrer, referring domain, and click identifiers (for example gclid, fbclid) automatically attach to every event as event properties. Attribution event properties arrive immediately on Browser SDK 2.45.0+ and GTM template 5d7e5+.

First-touch attribution is tracked only with user properties. Multi-touch attribution can use either user properties or event properties, but Amplitude recommends event properties. Event properties retain the campaign context on each event and can be used as inputs to persisted properties and multi-touch attribution models.

For details about what event property tracking captures and how to configure it, refer to Event property tracking in the Browser SDK 2 documentation.

SDK versions below 2.45.0 or GTM template versions below 5d7e5

On older SDK or GTM template versions, event property tracking is opt-in. Enable it by setting trackingMethod.

SDK (direct installation)

js
import * as amplitude from '@amplitude/analytics-browser';

amplitude.init('AMPLITUDE_API_KEY', {
  autocapture: {
    attribution: {
      trackingMethod: ['userProperty', 'eventProperty'],
    },
  },
});

Google Tag Manager

Set the tracking method through a configuration variable:

  1. Update your Amplitude Analytics Browser SDK tag to the latest version when GTM shows the update. Event-property attribution requires Browser SDK 2.40.0 or later.
  2. Go to Variables > User-Defined Variables > New, search the Community Template Gallery for Amplitude Browser SDK Configuration Variable, and install it.
  3. Create a variable from that template and set Tracking method to eventProperty. To keep user-property attribution as well, set both userProperty and eventProperty. Amplitude recommends this while migrating.
  4. In the Amplitude init tag, set New configuration options to your variable ({{Your Variable}}).
  5. Publish the container.

New configuration options replaces the entire autocapture object (shallow merge), so list the autocapture features you use, not just trackingMethod. Otherwise the tag drops those features. For more information, refer to New configuration options.

For example, mirroring a typical setup:

js
{
  autocapture: {
    pageViews: true,
    sessions: true,
    formInteractions: true,
    attribution: {
      trackingMethod: ["userProperty", "eventProperty"]
    }
  }
}

Auto-captured page and interaction properties

When you enable Autocapture, Amplitude automatically captures event properties such as Page Path, Page URL, Page Title, Element Text, and File Name on the relevant events. Any of these can become an input to a persisted property — for example, persisting Page Path with Original allocation captures the entry page that started the session.

Custom event properties

You can persist any event property your team sends, including custom properties such as discovery_method, experiment_variant, or internal_search_term. As long as the value travels on at least one event for the user, persisted properties can carry it forward.

Create the persisted property

Create the persisted property in Data Settings > Properties. The Persistence and Advanced settings control how the property allocates a value and how long it lasts.

The following section contains examples for using the Persistence and Advanced settings. Review each one as they apply to different ways you can implement persisted properties.

  1. Navigate to the Properties section of Data Settings and then click to create a new persisted property. Give this persisted property a name, such as Entry Page. In the description, provide additional information such as the allocation method and expiration. The description helps make sure that anyone using this property in a chart or data table understands the configuration.
  2. Select the event property you want to persist. For this example, use Page Path.
  3. Choose an Allocation method. In the example, because you want to identify the Entry Page, select Original. Selecting Original makes sure you include the first touchpoint.
  4. Set the Expiration. By default, the persisted property expires at the end of the session.
  5. (Optional) Configure Excluded values. Add any property values you want the persisted property to ignore — for example, internal traffic markers, test values, or specific channels you don't want to overwrite the persisted source. Amplitude doesn't treat excluded values as new property values during allocation, so a previously valid value continues to persist through them. For a common use case, refer to Filter internal referrers from attribution.

If your analysis involves merchandising (item-level attribution), refer to the Advanced: Item-level attribution section. Otherwise, go to Use persisted properties across analyses.

Was this helpful?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

On this page