Plugin Architecture in Kotlin SDK

Learn about the plugins architecture in Kotlin SDK.

4 minute read

This guide covers RudderStack’s plugin architecture available for the Kotlin SDK.

Overview

RudderStack’s plugin architecture lets you extend and customize event processing without modifying the core SDK. It provides flexibility by allowing you to add custom plugins at the different stages of event handling.

Using this architecture, you can filter, enhance, or modify events (identify, track, screen, group, and alias) based on your requirement. Whether it’s pre-processing data, transforming events, or applying integration-specific modifications, you have full control over how events are handled - making the integration seamless and ensuring events are processed exactly as required.

In this architecture, the plugins execute in a defined sequence, with each stage refining the data before passing it to the next.

Supported plugin types

Plugin type	Description
`PreProcess`	Executes at the beginning to prepare data, like adding context.
`OnProcess`	Executes while applying transformations or validations early in the pipeline.
`Terminal`	Executes just before sending the events to the integrations or RudderStack backend (server).
`Utility`	Executes only when manually triggered, like with a lifecycle plugin.

Plugin

A plugin is a modular component that lets you customize, enhance, or modify event processing at different stages without changing the core SDK. The plugin interface provides three optional methods that you can override as per your requirement:

Method	Description
`setup(analytics: Analytics)`	Initializes the plugin by associating it with an `Analytics` instance. Use this method to also set up any plugin-specific logic, like configuring internal variables or loading the necessary data.
`suspend fun intercept(event: Event): Event?`	Processes and (optionally) modifies the event before it moves through the pipeline. Returns the updated event or `null` to discard it. Note: This method is not applicable for the `Utility` plugin type.
`fun teardown()`	Handles cleanup when the plugin is removed or when `Analytics` shuts down. You can override this method to reset or clear any internal states.

Custom plugins

Custom plugins are user-defined plugins that provide flexibility in extending and modifying event processing within the SDK. Unlike built-in plugins which are predefined within the SDK, custom plugins are entirely developed, managed, and added or removed by you after the SDK initialization.

How custom plugins work

You can create and register a custom plugin at runtime, allowing for dynamic modifications without altering the core SDK.
These plugins can belong to any of the existing plugin types (PreProcess, OnProcess, Terminal, or Utility) and are executed at their respective stages.
By leveraging custom plugins, you gain greater control over event handling, making it possible to apply transformations, enrich events with additional data, filter out unwanted events, or customize behavior for specific use cases.

Sample custom plugin

The following steps show how to create sample a custom plugin for filtering the track event type:

Add the plugin logic:

import com.rudderstack.sdk.kotlin.core.Analytics
import com.rudderstack.sdk.kotlin.core.internals.logger.LoggerAnalytics
import com.rudderstack.sdk.kotlin.core.internals.models.Event
import com.rudderstack.sdk.kotlin.core.internals.models.TrackEvent
import com.rudderstack.sdk.kotlin.core.internals.plugins.Plugin

class EventFilteringPlugin : Plugin {

    override val pluginType: Plugin.PluginType = Plugin.PluginType.OnProcess
    override lateinit var analytics: Analytics

    private lateinit var listOfEventsToBeFiltered: List<String>

    override fun setup(analytics: Analytics) {
        super.setup(analytics)
        listOfEventsToBeFiltered = listOf("Application Opened", "Application Backgrounded")
    }

    override suspend fun intercept(event: Event): Event? {
        if (event is TrackEvent && listOfEventsToBeFiltered.contains(event.event)) {
            LoggerAnalytics.verbose("EventFilteringPlugin: Event ${event.event} is filtered out")
            return null
        }
        return event
    }

    override fun teardown() {
        listOfEventsToBeFiltered = emptyList()
    }
}


import androidx.annotation.NonNull;
import androidx.annotation.Nullable;

import com.rudderstack.sdk.kotlin.core.Analytics;
import com.rudderstack.sdk.kotlin.core.internals.logger.LoggerAnalytics;
import com.rudderstack.sdk.kotlin.core.internals.models.Event;
import com.rudderstack.sdk.kotlin.core.internals.models.TrackEvent;
import com.rudderstack.sdk.kotlin.core.internals.plugins.Plugin;

import java.util.List;

import kotlin.coroutines.Continuation;

/**
 * A custom Java Plugin demonstrating how to perform event filtering in Java.
 */
public class JavaEventFilteringPlugin implements Plugin {
    private Analytics analytics;
    private static final Plugin.PluginType pluginType = Plugin.PluginType.OnProcess;

    List<String> listOfEventsToBeFiltered;

    @Override
    public void setAnalytics(@NonNull Analytics analytics) {
        this.analytics = analytics;
    }

    @Override
    public void setup(@NonNull Analytics analytics) {
        this.analytics = analytics;
        listOfEventsToBeFiltered = List.of("Application Opened", "Application Backgrounded");
    }

    @Nullable
    @Override
    public Object intercept(@NonNull Event event, @NonNull Continuation<? super Event> $completion) {
        if (event instanceof TrackEvent && listOfEventsToBeFiltered.contains(((TrackEvent) event).getEvent())) {
            LoggerAnalytics.INSTANCE.verbose("EventFilteringPlugin: Event " + ((TrackEvent) event).getEvent() + " is filtered out");
            return null;
        }

        return event;
    }

    @NonNull
    @Override
    public Analytics getAnalytics() {
        return this.analytics;
    }

    @NonNull
    @Override
    public Plugin.PluginType getPluginType() {
        return pluginType;
    }

    @Override
    public void teardown() {
        listOfEventsToBeFiltered = null;
    }
}

Add the plugin after initializing the SDK:

// SDK initialization snippet
analytics.add(EventFilteringPlugin())

analytics.add(new JavaEventFilteringPlugin());

You can also remove the plugin as follows:

// SDK initialization snippet
analytics.remove(EventFilteringPlugin())

analytics.remove(new JavaEventFilteringPlugin());

Workflow overview

In the above example, EventFilteringPlugin is a custom plugin that intercepts and filters the specified events before they are processed. Specifically, it filters out the Application Opened and Application Backgrounded events and prevents them from being tracked.

The high-level workflow is as follows:

While initializing the plugin, you can specify a list of events to be filtered.
When an event is received, the plugin checks if it matches any of the events specified in the filter list.
If the event is present in the filter list, the plugin logs a message and discards it by returning null. Otherwise, it forwards event for processing, as usual.
The teardown method clears the event list whenever you remove the plugin.

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack