You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/connections/sources/catalog/libraries/mobile/apple/live-plugins.md
+29-77Lines changed: 29 additions & 77 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,27 +3,29 @@ title: Live Plugins
3
3
strat: swift
4
4
---
5
5
6
-
Live plugins are JavaScript code snippets published to your Segment workspace and then downloaded directly to the mobile devices of end users. Live plugins let you perform real-time modifications to events before they leave the mobile device.
6
+
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.
7
7
8
-
On this page, you'll learn how to set up live plugins and how to create your own live plugins. You'll also see example live plugins that address common use cases.
8
+
Live Plugins work alongside [Auto-Instrumentation](/docs/connections/auto-instrumentation/)to give you flexible control over your event data.
9
9
10
-
> info "Live Plugins is in pilot"
11
-
> Live Plugins is currently in Pilot and available to select Business Tier Customers only. To enable this feature for your workspace, contact your CSM.
10
+
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.
12
11
13
-
## Live plugins overview
12
+
> info "Live Plugins is in Public Beta"
13
+
> 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.
14
14
15
-
You can use JavaScript live plugins with Analytics-Swift and Analytics-Kotlin to filter and modify data remotely. As a result, you can filter and modify analytics events without having to deploy updates to the app store for each change, ensuring data quality and consistency for all your mobile users.
15
+
## Live Plugins overview
16
16
17
-
Because live plugins let you modify event data before it leaves a mobile device, you can use the same function to modify data meant for all your cloud-mode and device-mode destinations.
17
+
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.
18
+
19
+
Because Live Plugins run before data leaves the device, you can apply the same logic to all destinations or target specific destinations as needed.
18
20
19
21
## Setup
20
22
21
-
To use live plugins, you first need to set up your mobile app with a one-time configuration.
23
+
To use Live Plugins, you first need to set up your mobile app with a one-time configuration.
22
24
23
-
To configure live plugins:
25
+
To configure Live Plugins:
24
26
25
-
1. Include the [AnalyticsLive for Swift plugin](https://github.com/segment-integrations/analytics-swift-live){:target="_blank"}
26
-
and [AnalyticsLive for Kotlin plugin](https://github.com/segment-integrations/analytics-kotlin-live){:target="_blank"}
27
+
1. Include [Analytics-Live for Swift plugin](https://github.com/segment-integrations/analytics-swift-live){:target="_blank"}
28
+
and [Analytics-Live for Kotlin](https://github.com/segment-integrations/analytics-kotlin-live){:target="_blank"}
27
29
in your project.
28
30
2. Add the plugin to your instance of Analytics, using the following code:
29
31
@@ -49,68 +51,18 @@ analytics.add(LivePlugins())
49
51
{% endcodeexampletab %}
50
52
{% endcodeexample %}
51
53
52
-
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 CLI and perform updates as often as needed.
53
-
54
-
## Live plugin tutorial
55
-
56
-
This section walks you through a sample live plugin implementation.
57
-
58
-
### 1. Write a live plugin in JavaScript
59
-
60
-
Copy and save the following file, which anonymizes events by removing user IDs and device IDs:
61
-
62
-
```js
63
-
classPrivacyLivePluginextendsLivePlugin {
64
-
// The execute function is called for every event.
65
-
execute(event) {
66
-
// Remove the user ID and device ID from the event to anonymize it.
67
-
event.userId=null;
68
-
deleteevent.context.device.id;
69
-
returnevent;
70
-
}
71
-
}
72
-
```
73
-
74
-
Note the name of your saved file. You'll need it in the next step.
75
-
76
-
### 2. Deploy the plugin with the Live Plugin CLI
77
-
78
-
With your plugin saved, you'll next deploy the plugin with Segment's Live Plugin CLI. Follow these steps:
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.
105
55
106
-
You've now successfully attached your live plugin(s) to your mobile source. The next time your users launch your app, their Segment SDK will download the latest live plugins, which will run every time new events are generated.
56
+
## Create your own Live Plugin
107
57
108
-
> info ""
109
-
> Because the CDN settings object takes a few minutes to rebuild, your live plugins might not be available immediately.
58
+
To access Live Plugins for your Swift and Kotlin sources:
110
59
111
-
## Create your own live plugin
60
+
1. In your Segment workspace, go to **Connections > Sources**.
61
+
2. Select your Swift or Kotlin source (or create a new one).
62
+
3. From the source's overview page, click the Live Plugin tab..
63
+
<imgalt="Access Live Plugins from the Source overview tab"src="https://github.com/user-attachments/assets/e228bddb-4cb8-4469-9ac6-8a2c322edcbc" />
112
64
113
-
Follow the steps in this section to create your own live plugin.
65
+
Follow the steps in this section to create and deploy your own Live Plugin.
In this example, you've created a `UserIdLivePlugin` by subclassing `LivePlugin` and implementing the `execute()` function. This function gets applied to every event.
139
91
140
-
### 2. Add your live plugin to the Analytics instance
92
+
### 2. Add your Live Plugin to the Analytics instance
141
93
142
-
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.
94
+
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.
143
95
144
96
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.
To control when your custom live plugin runs during event processing, you can use `LivePluginType` enums, which define different timing options for your live plugin. Here are the available types:
106
+
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:
155
107
156
108
```js
157
109
constLivePluginType= {
@@ -162,9 +114,9 @@ const LivePluginType = {
162
114
}
163
115
```
164
116
165
-
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.
117
+
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.
166
118
167
-
## Live plugin examples
119
+
## Live Plugin examples
168
120
169
121
The following live plugin examples address common use cases:
Live plugins follow an interface that let you intercept Segment events and modify their data. This interface includes several functions that you can implement for custom behavior:
256
+
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:
305
257
306
258
```js
307
259
// Interface for Live Plugins:
@@ -325,7 +277,7 @@ This section covers the primary event callbacks.
325
277
326
278
#### The `execute` callback
327
279
328
-
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`.
280
+
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`.
329
281
330
282
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.
331
283
@@ -351,4 +303,4 @@ There's one non-event function:
0 commit comments