Analytics-Kotlin Plugin Architecture

Segment's plugin architecture lets you modify and augment how the analytics client works. From modifying event payloads to changing analytics functionality, plugins help to speed up the process of getting things done.

Plugins are run through a timeline, which executes in order of insertion based on their types. Segment has these five types:

There are three basic types of plugins that you can use as a foundation for modifying functionality. They are: Plugin, EventPlugin, and DestinationPlugin.

Plugin acts on any event payload going through the timeline.

For example, if you want to add something to the context object of any event payload as an enrichment:

1
class SomePlugin: Plugin {
2
    override val type = Plugin.Type.Enrichment
3

4
    override lateinit var analytics: Analytics
5

6
    override fun execute(event: BaseEvent): BaseEvent? {
7
        event.putInContext("foo", "bar")
8
        return event
9
    }
10
}

EventPlugin is a plugin interface that acts on specific event types. You can choose the event types by only overriding the event functions you want.

For example, if you only want to act on Track and Identify events:

1
class SomePlugin: EventPlugin {
2
    override fun track(event: TrackEvent): BaseEvent? {
3
        // code to modify track event
4
        return event
5
    }
6
    override fun identify(event: TrackEvent): BaseEvent? {
7
        // code to modify identify event
8
        return event
9
    }
10
}

The DestinationPlugin interface is commonly used for device-mode destinations. This plugin contains an internal timeline that follows the same process as the analytics timeline, enabling you to modify and augment how events reach a particular destination.

For example, if you want to implement a device-mode destination plugin for Amplitude, you can use this:

1
class AmplitudePlugin: DestinationPlugin() {
2
    override val key = "Amplitude" // This is the name of the destination plugin, it is used to retrieve settings internally
3

4
    val amplitudeSDK: Amplitude // This is an instance of the partner SDK
5

6
    init { // Initializing the partner SDK and setting things up
7
        amplitudeSDK = Amplitude.instance
8
        amplitudeSDK.initialize(applicationContext, "API_KEY");
9
    }
10

11
    /*
12
    * Implementing this function allows this plugin to hook into any track events
13
    * coming into the analytics timeline
14
    */
15
    override fun track(event: TrackEvent): BaseEvent? {
16
        amplitudeSDK.logEvent(event.name)
17
        return event
18
    }
19
}

• setup(Analytics): Use this function to setup your plugin. This implicitly calls once the plugin registers.
• update(Settings): Use this function to react to any settings updates. This implicitly calls when settings update. You can force a settings update by calling analytics.checkSettings().
• AndroidLifecycle hooks Plugins can also hook into AndroidLifecycle functions by implementing an interface. These functions call implicitly as the lifecycle events process.
• DestinationPlugin timeline: The destination plugin contains an internal timeline that follows the same process as the analytics timeline, enabling you to modify/augment how events reach the particular destination. For example if you only wanted to add a context key when sending an event to Amplitude:

1
val amplitudePlugin = AmplitudePlugin()
2
analytics.add(amplitudePlugin) // add amplitudePlugin to the analytics client
3

4
val amplitudeEnrichment = object: Plugin {
5
    override val type = Plugin.Type.Enrichment
6

7
    override lateinit var analytics: Analytics
8

9
    override fun execute(event: BaseEvent): BaseEvent? {
10
        event.putInContext("foo", "bar")
11
        return event
12
    }
13
}
14

15
amplitudePlugin.add(amplitudeEnrichment) // add enrichment plugin to amplitude timeline

Adding plugins enable you to modify your analytics implementation to best fit your needs. You can add a plugin using this:

1
val yourPlugin = SomePlugin()
2
analytics.add(yourPlugin)

Though you can add plugins anywhere in your code, it's best to implement your plugin when you configure the client.

Here's an example of adding a plugin to the context object of any event payload as an enrichment:

1
class SomePlugin: Plugin {
2
    override val type = Plugin.Type.Enrichment
3

4
    override lateinit var analytics: Analytics
5

6
    override fun execute(event: BaseEvent): BaseEvent? {
7
        event.putInContext("foo", "bar")
8
        return event
9
    }
10
}
11
val yourPlugin = SomePlugin()
12
analytics.add(yourPlugin)

If Segment doesn't support your Kotlin destination, you can build your own with the template Segment provides.

To build your own Kotlin destination using a plugin template:

1. Go to the Kotlin Destination Plugin Template.
2. Click Use this template.
3. Enter a name for the repository.
4. Click Create repository from template.
5. Go to lib > src > main > java/dmn/your/pkg/destination in your repository.
6. Click the MyDestination.kt.
7. Complete the TODO sections in the sample code with the appropriate information for your destination. Segment recommends you to change the package name before you finalize your build.
8. Commit your changes.

You can unit test your destination to make sure it works. Segment recommends you to use the testing template as a starter and to build upon it to get test coverage of most scenarios.

To test your destination:

1. Go to lib > src > test > java/dmn/your/pkg/destination.
2. Click MyDestinationTests.kt.
3. Complete the TODO sections in the sample code with the appropriate information for your destination.
4. Commit your changes.

Segment recommends that you test your destination implementation end-to-end. Send some sample analytics events and ensure that they reach the destination.