Attribution tracking fails when configured via `autocapture.attribution`

[tmchow]

Expected Behavior

When configuring the SDK with autocapture.attribution settings, UTM parameters and other marketing
attribution data should be automatically tracked according to the documentation at
https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2

amplitude.init(apiKey, undefined, {
  autocapture: {
    attribution: {
      resetSessionOnNewCampaign: true,
    },
  },
});

This should capture UTM parameters (utm_source, utm_medium, etc.), referrer data, and click IDs when users visit with campaign parameters.

Current Behavior

Attribution tracking silently fails when configured using only the autocapture property. UTM parameters are not captured, and no attribution events are sent to Amplitude.

The only way to get attribution working is to either:

1. Use the deprecated @amplitude/plugin-web-attribution-browser plugin, OR
2. Set both autocapture AND the deprecated defaultTracking property to the same configuration

Possible Solution

The SDK has an inconsistency where some autocapture features check config.autocapture (correct) while others check the deprecated config.defaultTracking (incorrect).

Files that need to be fixed:

packages/analytics-browser/src/browser-client.ts - Update these lines to use this.config.autocapture
instead of this.config.defaultTracking:

• Line 172: Attribution tracking check
• Line 224: File download tracking check
• Line 229: Form interaction tracking check
• Line 235: Page view tracking check
• Lines 361, 381: Session tracking checks

packages/analytics-browser/src/default-tracking.ts - Update these functions:

• Lines 227-241: getAttributionTrackingConfig() should check config.autocapture instead of
  config.defaultTracking
• Lines 188-225: getPageViewTrackingConfig() should check config.autocapture instead of
  config.defaultTracking

Note: Commit 97969c3 on branch AMP-125616/refactor-sr-observer-to-use-network-observer already partially fixed this issue for network tracking but was never completed or merged.

Steps to Reproduce

1. Initialize the SDK with autocapture attribution enabled:

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

  amplitude.init('your-api-key', undefined, {
    autocapture: {
      attribution: {
        resetSessionOnNewCampaign: true,
      },
    },
  });

2. Visit your application with UTM parameters:
   https://yourapp.com?utm_source=test&utm_medium=email&utm_campaign=spring2024
3. Check the Amplitude event stream for the user
4. Observe: No UTM parameters are captured. Attribution tracking does not work.
5. Workaround: Add defaultTracking with the same config:

const config = {
  attribution: {
    resetSessionOnNewCampaign: true,
  },
};

amplitude.init('your-api-key', undefined, {
  autocapture: config,
  defaultTracking: config,  // Required for attribution to work
});

6. Repeat steps 2-3: Attribution now works correctly.

Environment

• JS SDK Version: @amplitude/analytics-browser 2.29.0 (issue exists in all 2.x versions)
• Installation Method: npm and yarn
• Browser and Version: all browsers

[daniel-graham-amplitude]

Thank you for this @tmchow ! Really good reproduction steps.

I've added this to our current sprint, I'll keep you updated on my progress.

[tmchow]

Thank you for this @tmchow ! Really good reproduction steps.

I've added this to our current sprint, I'll keep you updated on my progress.

I'm anxious to get this fix -- Here's my contribution :)
#1372

[Mercy811]

Hi @tmchow, I added some tests #1374. Setting autocapture.attribution should install the web attribution plugin. I'd suggest you follow this flowchart to see why the identify event is not tracked. You can also check you remote config if it's disabled. Another tip is set loglevel to debug to see what configuration the sdk is initialized with.

[tmchow]

Hi @tmchow, I added some tests #1374. Setting autocapture.attribution should install the web attribution plugin. I'd suggest you follow this flowchart to see why the identify event is not tracked. You can also check you remote config if it's disabled. Another tip is set loglevel to debug to see what configuration the sdk is initialized with.

@Mercy811 We have remote config disabled now, but still seeing issue where we are seeing initial hits to our website that have a query string like ?utm_source=foo but the utm_source user properties are NOT set for the user like they should be. I'm banging my head against the wall as to why and amplitude official support is flailing on this.

As soon as we add in the deprecated web attribution plugin, it works to correctly set the utm user props as we'd expect. This is why I'm suspecting there's a bug somewhere.

Our initialization is this in our NextJS app. You'll notice in the below config, we are opting into all autocapture except for Pageviews which is intentional. We fire out own custom events for pageviews for a variety of reasons. Could this be a source of the bug? (i.e. not just using a simple autocapture: { attribute: true } is somehow not correctly including the attribution plugin?

await amplitude.init(`${process.env.NEXT_PUBLIC_AMPLITUDE_ID}`, undefined, {
      flushIntervalMillis: 1000, // 1 second
      minIdLength: 1,
      remoteConfig: { fetchRemoteConfig: false },
      autocapture: {
        attribution: {
          excludeReferrers: [
            /(www|my|app|supportfort)\.bigcartel\.(com|biz)$/,
          ],
          resetSessionOnNewCampaign: false,
        },
        formInteractions: true,
        fileDownloads: true,
        pageViews: false,
        sessions: true,
        elementInteractions: {
          dataAttributePrefix: 'data-analytics-action-',
        },
      },
      cookieOptions: {
        secure: true,
        upgrade: true,
      },
      plan: { source: 'web-marketing' },
    }).promise;

    identifyUser();

I have exact links to events in our amplitude stream that shows this very clearly too, so if that helps I can provide that by email.

[Mercy811]

@tmchow could you submit a support ticket https://gethelp.amplitude.com/hc/en-us/requests/new thanks!

[tmchow]

@tmchow could you submit a support ticket https://gethelp.amplitude.com/hc/en-us/requests/new thanks!

Already done it's ticket 373836

[daniel-graham-amplitude]

I'll take a crack at reproducing it this afternoon. I just want to make 100% sure it's a bug and what the bug is because I'm just nervous about breaking backwards compatibility.

[tmchow]

I'll take a crack at reproducing it this afternoon. I just want to make 100% sure it's a bug and what the bug is because I'm just nervous about breaking backwards compatibility.

Thanks @daniel-graham-amplitude. I'm at the end of the road in terms of how to try to debug this. We are clearly seeing inconsistent behavior with UTM marketing attribution in user properties. tons of events with clearly utm props in the query string, but the user properties are not set. If i add back the deprecated web attribution plugin it just works. So that's my last resort if we can't get this sorted but i hate adding back a deprecated plugin.

If you want more details on specifics feel free to email me -- my first name at bigcartel.com :)

[tmchow]

@daniel-graham-amplitude i'm wondering whether there's harm in adding the deprecated plugin. Is there something that would break or is it deprecated because that plugin is just automatically included in the base analytics-browser sdk?

Ultimately i just want to get the proper attribution for us in near term.

[daniel-graham-amplitude]

I'm having a hard time reproducing this. When I set autocapture.attribution.resetSessionOnNewCampaign = true attribution is working fine

@tmchow I noticed you're not setting "user_id" in "init" (it's undefined). I'm guessing that's intentional right? Is the identifyUser afterwards just adding additional user metadata?

[daniel-graham-amplitude]

When we "deprecate" things like plugins or API's, what it generally means is just it won't be part of a future version of the SDK (a major version, which hopefully won't be needed for a long time), and that we won't be making additions to it.