You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

Live Plugins

Live Plugins let you modify analytics events in real time, directly on user devices, without rebuilding or redeploying your app. They're JavaScript snippets that you publish from your Segment workspace, where they run on your users' mobile devices to filter or transform data before it's sent to Segment.

Live Plugins work alongside Auto-Instrumentation to give you flexible control over your event data.

On this page, you'll learn how to set up your mobile app to support Live Plugins, create and deploy custom plugins, and explore examples for common use cases.

(information)

Live Plugins is in Public Beta

Live Plugins is in public beta for Swift and Kotlin and available to select Business Tier Customers only. To enable this feature for your workspace, contact your CSM.

Live Plugins overview

You can use JavaScript Live Plugins with Analytics-Swift and Analytics-Kotlin to modify or filter event data directly on user devices. This lets you make real-time updates to your tracking logic without redeploying your app, helping you maintain data quality and consistency across your mobile users.

Because Live Plugins run before data leaves the device, you can apply the same logic to all destinations or target specific destinations as needed.

Setup

To use Live Plugins, you first need to set up your mobile app with a one-time configuration.

To configure Live Plugins:

Include Analytics-Live for Swift plugin and Analytics-Live for Kotlin in your project.
Add the plugin to your instance of Analytics, using the following code:

SwiftKotlin

1// Import the live plugin
2import AnalyticsLive
3// Instantiate Analytics
4// Add LivePlugins to Analytics
5analytics.add(plugin: LivePlugins(null))

After you've completed setup, you can deploy your apps to the Apple App Store and Google Play Store. You can then add new JavaScript plugin code to your mobile apps through the Segment website, and perform updates as often as needed.

Create your own Live Plugin

To access Live Plugins for your Swift and Kotlin sources:

In your Segment workspace, go to Connections > Sources.
Select your Swift or Kotlin source (or create a new one).
From the source's overview page, click the Live Plugin tab..

Access Live Plugins from the Source overview tab.

Follow the steps in this section to create and deploy your own Live Plugin.

1. Subclass the `LivePlugin` class

To create your own live plugin, you'll start by subclassing the LivePlugin class and overloading one (or more) of the event-related functions.

For example, suppose you want to correct a field-naming inconsistency in your event data:

1// This UserIdLivePlugin corrects a naming inconsistency in the event data by renaming "user_id" to "userId."
2
3class UserIdLivePlugin extends LivePlugin {
4   // The execute function is called for every event.
5   execute(event) {
6       // Correct the field naming inconsistency from "user_id" to "userId."
7       event.userId = event.user_id;
8       delete event.user_id;
9       return event;
10   }
11}
12
13// Add the UserIdLivePlugin to the Analytics instance without specifying a target destination (null).
14analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, null));

In this example, you've created a UserIdLivePlugin by subclassing LivePlugin and implementing the execute() function. This function gets applied to every event.

2. Add your Live Plugin to the Analytics instance

After you define your custom Live Plugin, you need to add it to the Analytics instance. The Analytics object is globally accessible, and you can use the add() method to include your Live Plugin.

When you adding a new instance, you specify the LivePluginType and the destination to which it applies, or use null to apply it to all destinations.

Here's how you can add the UserIdLivePlugin to your Analytics instance:

analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, "adobe"));

3. Use the `LivePluginType` enums

To control when your custom Live Plugin runs during the event lifecycle, you can use LivePluginType enums, which define different timing options for your Live Plugin. Here are the available types:

1const LivePluginType = {
2   before: "before",
3   enrichment: "enrichment",
4   after: "after",
5   utility: "utility"
6}

With these enums, you can select the timing that best fits your custom Live Plugin's target use case. These types align with categories used for Native Plugins.

Live Plugin examples

The following live plugin examples address common use cases:

Anonymize eventsDrop eventsModify eventsDown sample eventsChain multiple functions

1
2// This PrivacyLivePlugin anonymizes events by removing user IDs and device IDs
3
4class PrivacyLivePlugin extends LivePlugin {
5   // The execute function is called for every event.
6   execute(event) {
7       // Remove the user ID and device ID from the event to anonymize it.
8       event.userId = null;
9       delete event.context.device.id;
10       return event;
11   }
12}
13
14analytics.add(new PrivacyLivePlugin(LivePluginType.Enrichment, null));

1// This DropEventsLivePlugin filters and drops all events targeted for a specific destination.
2
3class DropEventsLivePlugin extends LivePlugin {
4   // The execute function is called for every event.
5   execute(event) {
6       // Drop all events by returning null.
7       return null;
8   }
9}
10
11// Add the DropEventsLivePlugin to the Analytics instance, applying it only to the Adobe destination.
12
13analytics.add(new DropEventsLivePlugin(LivePluginType.Enrichment, "adobe"));
14

1// This UserIdLivePlugin corrects a naming inconsistency in the event data by renaming "user_id" to "userId."
2
3class UserIdLivePlugin extends LivePlugin {
4   // The execute function is called for every event.
5   execute(event) {
6       // Correct the field naming inconsistency from "user_id" to "userId."
7       event.userId = event.user_id;
8       delete event.user_id;
9       return event;
10   }
11}
12
13// Add the UserIdLivePlugin to the Analytics instance without specifying a target destination (null).
14analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, null));

1// This DownSampleLivePlugin down-samples events to reduce overall traffic.
2
3class DownSampleLivePlugin extends LivePlugin {
4   // Edge Functions can maintain internal state and persist in memory after startup.
5   // They're cleared when the app is terminated or analytics.reset() is called.
6   counter = 0
7    // The execute function is called for every event.
8   execute(event) {
9      // Check if the event count is divisible by 10 (that is, every tenth event).
10       if (counter++ % 10 == 0) {
11         return event
12       } else {
13          // Drop 90% of event traffic by returning null for non-selected events.
14         return null
15       }
16   }
17}
18
19
20analytics.add(new DownSampleLivePlugin(LivePluginType.enrichment, null))

1// The UserIdLivePlugin corrects a field naming inconsistency by renaming "user_id" to "userId."
2
3class UserIdLivePlugin extends LivePlugin {
4   // The execute function is called for every event.
5   execute(event) {
6       // Correct the field naming inconsistency from "user_id" to "userId."
7       event.userId = event.user_id;
8       delete event.user_id;
9       return event;
10   }
11}
12
13// This DownSampleLivePlugin down-samples events to reduce overall traffic.
14
15class DownSampleLivePlugin extends LivePlugin {
16   // LivePlugins can maintain internal state, persisting in memory after startup.
17   // They are cleared when the app is terminated or when analytics.reset() is called.
18   counter = 0;
19
20   // The execute function is called for every event.
21   execute(event) {
22      // Check if the event count is divisible by 3 (that is, every third event).
23      if (this.counter++ % 3 === 0) {
24         return event; // Keep this event.
25      } else {
26         // Drop 66% of event traffic by returning null for non-selected events.
27         return null;
28      }
29   }
30
31   // The reset function resets the counter when the Analytics instance is reset.
32   reset() {
33      this.counter = 0;
34   }
35}
36
37// Chain both live plugins to the Analytics instance.
38analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, null));
39analytics.add(new DownSampleLivePlugin(LivePluginType.enrichment, null));
40

Live Plugins API

Live Plugins expose an interface that lets you intercept Segment events and modify their data. This interface includes several functions that you can implement for custom behavior:

1// Interface for Live Plugins:
2class LivePlugin {
3   // Event callbacks
4   execute(event): event
5   identify(event): event
6   track(event): event
7   group(event): event
8   alias(event): event
9   screen(event): event
10
11   // Called when the Analytics instance is being reset.
12   reset() { }
13}

Event callbacks

This section covers the primary event callbacks.

The `execute` callback

The execute callback function serves as the primary entry point for Live Plugins to intercept and modify events. When you implement the execute function in your plugin, you can decide whether to keep the event by returning it or drop it by returning null.

This callback is versatile, as you can use it for various event types when the event type itself is not critical. Additionally, execute lets you invoke more specific callbacks based on the event type.

Callback	Description
`execute(event): event`	Called for every event. Must return the event or `null` to drop it. If you do return the event, then the more specific callback based on the event type is called. Use this callback if the event type isn't important. Additionally, you can call `super.execute()` to use one of the event type callbacks for Track, Identify, Screen, Group, or Alias calls.

Additional event callbacks

The following callback functions are designed for specific event types and let you control event modification:

Callback	Description
`track(event)`	Called for a tracking event. Must return the event to keep it or return `null` to drop it.
`identify(event)`	Called for an identify event. Must return the event to keep it or return `null` to drop it.
`screen(event)`	Called for a screen event. Must return the event to keep it or return `null` to drop it.
`group(event)`	Called for a group event. Must return the event to keep it or return `null` to drop it.
`alias(event)`	Called for an alias event. Must return the event to keep it or return `null` to drop it.

Non-event functions

There's one non-event function:

Function	Description
`reset(): null`	Called when the Analytics instance is about to be reset. Nothing to return.