Skip to content

Commit d23d092

Browse files
pwsegpwseg
authored
Merge pull request #5986 from segmentio/live-plugins-pilot
Live Plugins Pilot [DOC-791]
2 parents 18ff0d7 + 2bfbcc8 commit d23d092

File tree

1 file changed

+354
-0
lines changed

1 file changed

+354
-0
lines changed

‎src/connections/sources/catalog/libraries/mobile/apple/live-plugins.md

Lines changed: 354 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,354 @@
1+
---
2+
title: Live Plugins
3+
strat: swift
4+
---
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.
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.
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.
12+
13+
## Live plugins overview
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.
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.
18+
19+
## Setup
20+
21+
To use live plugins, you first need to set up your mobile app with a one-time configuration.
22+
23+
To configure live plugins:
24+
25+
1. Include the [Analytics Live for Swift plugin](https://github.com/segment-integrations/analytics-swift-live){:target="_blank"}
26+
and [Analytics Live for Kotlin plugin](https://github.com/segment-integrations/analytics-kotlin-live){:target="_blank"}
27+
in your project.
28+
2. Add the plugin to your instance of Analytics, using the following code:
29+
30+
{% codeexample %}
31+
{% codeexampletab Swift %}
32+
```swift
33+
// Import the live plugin
34+
import AnalyticsLive
35+
// Instantiate Analytics
36+
// Add LivePlugins to Analytics
37+
analytics.add(plugin: LivePlugins(null))
38+
```
39+
{% endcodeexampletab %}
40+
41+
{% codeexampletab Kotlin %}
42+
```kotlin
43+
// Import the live plugin
44+
import com.segment.analytics.plugins.livePlugin
45+
// Instantiate analytics
46+
// Add LivePluginsto Analytics
47+
analytics.add(LivePlugins())
48+
```
49+
{% endcodeexampletab %}
50+
{% endcodeexample %}
51+
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+
class PrivacyLivePlugin extends LivePlugin {
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+
delete event.context.device.id;
69+
return event;
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:
79+
80+
#### Install the CLI with Homebrew
81+
82+
Run this command to install the Segment CLI:
83+
84+
```shell
85+
$ brew install segment-integrations/formulae/segmentcli
86+
```
87+
88+
#### Authenticate with Segment
89+
90+
Next, you'll authenticate with Segment to give the CLI access to your workspace:
91+
92+
1. Within your Segment workspace, navigate to **Settings > Workspace Settings > Access Management > Tokens**.
93+
2. Click **Create token** to generate a new token with the `Workspace Owner` role. Copy the token.
94+
3. Return to your command line and use your token to authenticate:
95+
96+
```shell
97+
$ segmentcli auth <ProfileName> <AuthToken>
98+
```
99+
4. Copy your source's ID. You'll find the Source ID under **Settings > API Keys > Source ID** on your source's page.
100+
7. Use your source ID and live plugin file name to upload your live plugin:
101+
102+
```shell
103+
$ segmentcli upload <SourceID> <FileName>
104+
```
105+
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.
107+
108+
> info ""
109+
> Because the CDN settings object takes a few minutes to rebuild, your live plugins might not be available immediately.
110+
111+
## Create your own live plugin
112+
113+
Follow the steps in this section to create your own live plugin.
114+
115+
### 1. Subclass the `LivePlugin` class
116+
117+
To create your own live plugin, you'll start by subclassing the `LivePlugin` class and overloading one (or more) of the event-related functions.
118+
119+
For example, suppose you want to correct a field-naming inconsistency in your event data:
120+
121+
```js
122+
// This UserIdLivePlugin corrects a naming inconsistency in the event data by renaming "user_id" to "userId."
123+
124+
class UserIdLivePlugin extends LivePlugin {
125+
// The execute function is called for every event.
126+
execute(event) {
127+
// Correct the field naming inconsistency from "user_id" to "userId."
128+
event.userId = event.user_id;
129+
delete event.user_id;
130+
return event;
131+
}
132+
}
133+
134+
// Add the UserIdLivePlugin to the Analytics instance without specifying a target destination (null).
135+
analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, null));
136+
```
137+
138+
In this example, you've created a `UserIdLivePlugin` by subclassing `LivePlugin` and implementing the `execute()` function. This function gets applied to every event.
139+
140+
### 2. Add your live plugin to the Analytics instance
141+
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.
143+
144+
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.
145+
146+
Here's how you can add the `UserIdLivePlugin` to your Analytics instance:
147+
148+
```js
149+
analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, "adobe"));
150+
```
151+
152+
### 3. Use the `LivePluginType` enums
153+
154+
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:
155+
156+
```js
157+
const LivePluginType = {
158+
before: "before",
159+
enrichment: "enrichment",
160+
after: "after",
161+
utility: "utility"
162+
}
163+
```
164+
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.
166+
167+
## Live plugin examples
168+
169+
The following live plugin examples address common use cases:
170+
171+
{% codeexample %}
172+
173+
{% codeexampletab Anonymize events %}
174+
```js
175+
176+
// This PrivacyLivePlugin anonymizes events by removing user IDs and device IDs
177+
178+
class PrivacyLivePlugin extends LivePlugin {
179+
// The execute function is called for every event.
180+
execute(event) {
181+
// Remove the user ID and device ID from the event to anonymize it.
182+
event.userId = null;
183+
delete event.context.device.id;
184+
return event;
185+
}
186+
}
187+
188+
analytics.add(new PrivacyLivePlugin(LivePluginType.Enrichment, null));
189+
```
190+
{% endcodeexampletab %}
191+
192+
{% codeexampletab Drop events %}
193+
```js
194+
// This DropEventsLivePlugin filters and drops all events targeted for a specific destination.
195+
196+
class DropEventsLivePlugin extends LivePlugin {
197+
// The execute function is called for every event.
198+
execute(event) {
199+
// Drop all events by returning null.
200+
return null;
201+
}
202+
}
203+
204+
// Add the DropEventsLivePlugin to the Analytics instance, applying it only to the Adobe destination.
205+
206+
analytics.add(new DropEventsLivePlugin(LivePluginType.Enrichment, "adobe"));
207+
208+
```
209+
{% endcodeexampletab %}
210+
211+
{% codeexampletab Modify events %}
212+
```js
213+
// This UserIdLivePlugin corrects a naming inconsistency in the event data by renaming "user_id" to "userId."
214+
215+
class UserIdLivePlugin extends LivePlugin {
216+
// The execute function is called for every event.
217+
execute(event) {
218+
// Correct the field naming inconsistency from "user_id" to "userId."
219+
event.userId = event.user_id;
220+
delete event.user_id;
221+
return event;
222+
}
223+
}
224+
225+
// Add the UserIdLivePlugin to the Analytics instance without specifying a target destination (null).
226+
analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, null));
227+
```
228+
{% endcodeexampletab %}
229+
230+
{% codeexampletab Down sample events %}
231+
```js
232+
// This DownSampleLivePlugin down-samples events to reduce overall traffic.
233+
234+
class DownSampleLivePlugin extends LivePlugin {
235+
// Edge Functions can maintain internal state and persist in memory after startup.
236+
// They're cleared when the app is terminated or analytics.reset() is called.
237+
counter = 0
238+
// The execute function is called for every event.
239+
execute(event) {
240+
// Check if the event count is divisible by 10 (that is, every tenth event).
241+
if (counter++ % 10 == 0) {
242+
return event
243+
} else {
244+
// Drop 90% of event traffic by returning null for non-selected events.
245+
return null
246+
}
247+
}
248+
}
249+
250+
251+
analytics.add(new DownSampleLivePlugin(LivePluginType.enrichment, null))
252+
```
253+
{% endcodeexampletab %}
254+
255+
{% codeexampletab Chain multiple functions %}
256+
```js
257+
// The UserIdLivePlugin corrects a field naming inconsistency by renaming "user_id" to "userId."
258+
259+
class UserIdLivePlugin extends LivePlugin {
260+
// The execute function is called for every event.
261+
execute(event) {
262+
// Correct the field naming inconsistency from "user_id" to "userId."
263+
event.userId = event.user_id;
264+
delete event.user_id;
265+
return event;
266+
}
267+
}
268+
269+
// This DownSampleLivePlugin down-samples events to reduce overall traffic.
270+
271+
class DownSampleLivePlugin extends LivePlugin {
272+
// LivePlugins can maintain internal state, persisting in memory after startup.
273+
// They are cleared when the app is terminated or when analytics.reset() is called.
274+
counter = 0;
275+
276+
// The execute function is called for every event.
277+
execute(event) {
278+
// Check if the event count is divisible by 3 (that is, every third event).
279+
if (this.counter++ % 3 === 0) {
280+
return event; // Keep this event.
281+
} else {
282+
// Drop 66% of event traffic by returning null for non-selected events.
283+
return null;
284+
}
285+
}
286+
287+
// The reset function resets the counter when the Analytics instance is reset.
288+
reset() {
289+
this.counter = 0;
290+
}
291+
}
292+
293+
// Chain both live plugins to the Analytics instance.
294+
analytics.add(new UserIdLivePlugin(LivePluginType.enrichment, null));
295+
analytics.add(new DownSampleLivePlugin(LivePluginType.enrichment, null));
296+
297+
```
298+
299+
{% endcodeexampletab %}
300+
{% endcodeexample %}
301+
302+
## Live Plugins API
303+
304+
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:
305+
306+
```js
307+
// Interface for Live Plugins:
308+
class LivePlugin {
309+
// Event callbacks
310+
execute(event): event
311+
identify(event): event
312+
track(event): event
313+
group(event): event
314+
alias(event): event
315+
screen(event): event
316+
317+
// Called when the Analytics instance is being reset.
318+
reset() { }
319+
}
320+
```
321+
322+
### Event callbacks
323+
324+
This section covers the primary event callbacks.
325+
326+
#### The `execute` callback
327+
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`.
329+
330+
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+
332+
| Callback | Description |
333+
| ----------------------- | ----------- |
334+
| `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. |
335+
336+
#### Additional event callbacks
337+
338+
The following callback functions are designed for specific event types and let you control event modification:
339+
340+
| Callback | Description |
341+
| ----------------- | --------------------------------------------------------------------------------------------- |
342+
| `track(event)` | Called for a tracking event. Must return the event to keep it or return `null` to drop it. |
343+
| `identify(event)` | Called for an identify event. Must return the event to keep it or return `null` to drop it. |
344+
| `screen(event)` | Called for a screen event. Must return the event to keep it or return `null` to drop it. |
345+
| `group(event)` | Called for a group event. Must return the event to keep it or return `null` to drop it. |
346+
| `alias(event)` | Called for an alias event. Must return the event to keep it or return `null` to drop it. |
347+
348+
#### Non-event functions
349+
350+
There's one non-event function:
351+
352+
| Function | Description |
353+
| --------------- | --------------------------------------------------------------------------- |
354+
| `reset(): null` | Called when the Analytics instance is about to be reset. Nothing to return. |

0 commit comments

Comments
 (0)