Custom Enrichment Plugin

The Custom Enrichment plugin runs an enrichment function against every event the Browser SDK tracks, before the SDK uploads the event. Amplitude stores that function in your project's remote configuration, so you can change what it does without shipping a new build of your site.

The plugin is off by default. Enable it with the customEnrichment configuration option.

Requirements

• @amplitude/analytics-browser version 2.37.0 or later.
• Remote configuration enabled. The SDK fetches remote configuration by default. If you set remoteConfig.fetchRemoteConfig to false, the plugin loads but never receives a function, so it leaves every event unchanged. Refer to Remote configuration.
• An enrichment function defined in your project's remote configuration. The SDK doesn't read a function from your local configuration.

Enable the plugin

Set customEnrichment to true when you initialize the SDK:

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

amplitude.init(AMPLITUDE_API_KEY, {
  customEnrichment: true,
});

Amplitude's remote configuration can also turn the plugin on, with one exception: when you set customEnrichment: false at initialization, remote configuration can't re-enable it. Omit the option instead of setting it to false if you want remote configuration to control the plugin.

How the plugin works

1. On setup, the plugin subscribes to the configs.analyticsSDK.browserSDK.customEnrichment key in your project's remote configuration.
2. When remote configuration delivers a function body, the plugin evaluates it into a function that takes an event and returns an event.
3. The plugin runs that function against every event, including autocaptured events, as the event passes through the SDK's enrichment stage.
4. When remote configuration delivers no valid function body, the plugin passes every event through unchanged.

Because the plugin subscribes to remote configuration rather than reading it once, an update to the enrichment function reaches active sessions without a page reload.

Return values

What the enrichment function returns determines what Amplitude receives:

• Returns an event: the SDK uploads the returned event. This is how the function adds, changes, or removes properties.
• Returns nothing: the SDK drops the event, and the event never reaches Amplitude. An enrichment function that forgets to return the event silently drops all traffic.
• Throws an error: the SDK logs the error and uploads the original, unenriched event.

If the configured function body doesn't evaluate to a function, the plugin logs an error and passes every event through unchanged.

Content Security Policy

The plugin evaluates the enrichment function from remote configuration at runtime. If your site sets a Content Security Policy that restricts script-src, the policy must allow unsafe-eval for the plugin to build the function. Without it, the browser blocks the evaluation, the plugin logs an error, and events pass through unchanged.

Troubleshooting

Set logLevel to Debug to log what the plugin does:

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

amplitude.init(AMPLITUDE_API_KEY, {
  customEnrichment: true,
  logLevel: amplitude.Types.LogLevel.Debug,
});

If the log doesn't include Adding custom enrichment plugin, the SDK didn't enable the plugin. Confirm that customEnrichment isn't set to false in your initialization options.

Google Tag Manager