Tracker plugins

note

Tracker plugins are only available since version 5 of the mobile trackers.

The mobile trackers provide a plugin architecture that allows new functionality to be added to the trackers. There are several Snowplow maintained plugins, however you are also free to build your own or leverage community plugins too.

Plugins provide the ability to intercept tracked events in order to enrich them with additional entities, filter them or just to inspect them. To implement this, they contain three extension points:

1. entities callback which can return context entities to enrich events before they are tracked. The callback is passed the tracked event object to be enriched.
2. filter callback that returns true or false in order to decide whether to track a given event or not. The callback is passed the tracked event object.
3. afterTrack callback which can be used to inspect final tracked events. The passed event object contains all its properties as well as context entities.

Creating a custom plugin

In order to build your own plugin, you can instantiate the PluginConfiguration class. It requires you to pass a unique identifier. There can only be a single plugin for a given identifier registered with the tracker.

iOS

let plugin = PluginConfiguration(identifier: "myPlugin")

Android (Kotlin)

val plugin = PluginConfiguration("myPlugin")

Android (Java)

PluginConfiguration plugin = new PluginConfiguration("myPlugin");

Adding context entities

To enrich events with additional context entities, you can make use of the entities callback. This function accepts an optional list of schemas of self-describing events to subscribe to. To filter primitive (not self-describing events) such as structured events, you can pass their event names in the schemas list (se for structured events). When no list of schemas is passed, the callback is called for all tracked events.

The following code will add a specific entity, with URI "iglu:xx" (not a valid URI, for example only), to all Structured and ScreenView events.

iOS

plugin.entities(schemas: [
    // The list of schemas to call the closure for is optional. If not passed, the callback is called for all events.
    "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0", // screen view events
    "se" // structured events
]) { event in
    return [
        SelfDescribingJson(schema: "iglu:xx", andData: ["yy": true])
    ]
}

Android (Kotlin)

plugin.entities(
    schemas = listOf(
        // The list of schemas to call the closure for is optional. If not passed, the callback is called for all events.
        "iglu:com.google.analytics.measurement-protocol/screen_view/jsonschema/1-0-0", // screen view events
        "se" // structured events
    )
) {
    listOf(SelfDescribingJson("iglu:xx", hashMapOf("yy" to true)))
}

Android (Java)

plugin.entities(
        Arrays.asList(
                // The list of schemas to call the closure for is optional. If not passed, the callback is called for all events.
                "iglu:com.google.analytics.measurement-protocol/screen_view/jsonschema/1-0-0", // screen view events
                "se" // structured events
        ),
        event -> Collections.singletonList(new SelfDescribingJson("iglu:xx", Collections.singletonMap("yy", true)))
);

Filtering events

The filter callback enables you to add custom logic that decides whether a given event should be tracked or not. This can for example enable you to intercept events automatically tracked by the tracker and skip some of them. The callback returns true in case the event should be tracked and false otherwise. It also accepts the same optional schemas array as the entities callback to only be applied to events with those schemas.

The following code will apply to all screen view events and only accept ones with the name "Home Screen", other screen view events will be discarded:

iOS

plugin.filter(schemas: [
    "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0", // screen view events
]) { event in
    return event.payload["name"] as? String == "Home Screen"
}

Android (Kotlin)

plugin.filter(
    schemas = listOf(
        "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0", // screen view events
    )
) { event ->
    event.payload["name"] == "Home Screen"
}

Android (Java)

plugin.filter(
        Collections.singletonList(
                "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0", // screen view events
        ),
        event -> event.getPayload().get("name") == "Home Screen"
);

Inspecting events after they are tracked

To inspect events after they are tracked, you can make use of the afterTrack callback. It also accepts the same optional schemas array as the entities and filter callbacks to filter events.

iOS

plugin.afterTrack { event in
    print("Tracked event with \(event.entities.count) entities")
}

Android (Kotlin)

plugin.afterTrack {
    println("Tracked event with ${it.entities.count()} entities")
}

Android (Java)

plugin.afterTrack(
        null,
        event -> System.out.printf("Tracked event with %d entities%n", event.getEntities().size())
);

Registering a plugin in the tracker

Once you have a plugin configuration, you can register it when creating a new tracker:

iOS

// the plugin is supplied to the tracker as a configuration
let tracker = Snowplow.createTracker(namespace: "namespace",
                                     network: networkConfig,
                                     configurations: [plugin])

Android (Kotlin)

// the plugin is supplied to the tracker as a configuration
val tracker = Snowplow.createTracker(
    applicationContext,
    "namespace",
    networkConfiguration,
    plugin
)

Android (Java)

TrackerController tracker = Snowplow.createTracker(
        getApplicationContext(),
        "namespace",
        networkConfiguration,
        plugin
);

You will be able to list the registered plugin identifiers:

iOS

// one can inspect the enabled plugins and get the list of their identifiers
let pluginIdentifiers = tracker?.plugins.identifiers

Android (Kotlin)

// one can inspect the enabled plugins and get the list of their identifiers
val pluginIdentifiers = tracker.plugins.identifiers

Android (Java)

// one can inspect the enabled plugins and get the list of their identifiers
List<String> identifiers = tracker.getPlugins().getIdentifiers();

You can also add new plugins to an already instantiated tracker object:

iOS

tracker?.plugins.add(plugin: otherPlugin)

Android (Kotlin)

tracker.plugins.addPlugin(otherPlugin)

Android (Java)

tracker.getPlugins().addPlugin(otherPlugin);

And remove a plugin from a tracker instance:

iOS

tracker?.plugins.remove(identifier: "myPlugin")

Android (Kotlin)

tracker.plugins.removePlugin("myPlugin")

Android (Java)

tracker.getPlugins().removePlugin("myPlugin");