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 or just to inspect them. To implement this, they contain two 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. 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");

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)))
);

To inspect events after they are tracked, you can make use of the afterTrack callback. It also accepts the optional schemas array as the entities callback 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");