Snowplow

Iteratively supports Snowplow as a first-class destination.

Support

✅ SDK support for Browser—JavaScript and Browser—TypeScript

  • Iteratively wraps the Snowplow's tracker SDK similarly to other destinations
  • Iteratively's codegen'd SDK exposes strongly-typed methods for all tracking plan events and tracks them as Snowplow custom unstructured events (self-describing JSONs)
  • Iteratively's SDK abstracts away implementation details related to forming valid self-describing JSONs associated with appropriate schemas, contexts, etc. Iglu-compatible registry
  • Iteratively exposes its registry to Iglu-compatible clients so no additional schema synchronization is required between Iteratively and Iglu

🚨 The following features are not currently supported:

  1. SDK support for other runtimes — support for Android—Kotlin and iOS—Swift is in progress
  2. Source templates — none are permitted on sources that send data to Snowplow

Usage Guide

To begin using Snowplow with Iteratively:

  1. Create a new destination and set the Analytics Provider to Snowplow (Beta)

  2. Create a Browser—JavaScript or Browser—TypeScript source and link it to your new destination

  3. Create new templates and events as usual and associate them with your new source

  4. Publish your changes as a new version of your tracking plan

  5. In your project, run itly init/itly pull as usual

  6. Update your call to itly.init() to specify required Snowplow configuration options

    itly.init({
    destinations: {
    snowplow: {
    url: 'your-snowplow-host', // required
    config: {}, // optional
    },
    },
    });
  7. Instrument your tracking as usual

Technical Details

  • Every codegen'd SDK is generated against a specific tracking plan version, which is associated with specific event versions. The SDK's Snowplow adapter creates self-describing JSON objects by:
    • Placing the event payload into data
    • Setting schema to iglu:ly.iterative.{companyId}/{eventId}/jsonschema/{version}
  • Events in Iteratively are versioned according to SchemaVer
    • Iteratively also supports parallel tracking plans versions, so-called branches. In non-master branches, the SchemaVer representation will diverge from the spec and include the branch identifier as well, e.g. 1-0-1-develop-180f17ca
  • If an event has one or more templates associated with it, the templates' properties will be merge into the event's properties and appear as a single unified list in the event's schema

Iglu API

Iteratively fully supports the Iglu schema service APIs as defined in Iglu server. This means that an Iglu client can retrieve schemas referenced by all incoming self-describing JSON objects and use them to validate and shred incoming events.

To enable this in your Snowplow installation:

  1. Generate an API Token in your Iteratively account. This is the apikey that the Iglu client will use to authenticate itself to the Iteratively Iglu-compatible schema repository
    1. Browse to Settings, select the API Tokens page, and create a new token
  2. Add another repository to your Iglu configuration file (e.g. iglu.json in Snowplow Micro):
{
"name": "Iteratively",
"priority": 0,
"vendorPrefixes": [ "ly.iterative" ],
"connection": {
"http": {
"uri": "https://api.iterative.ly/iglu",
"apikey": "{your-api-key}"
}
}
}

To retrieve all schemas ever created in your tracking plan:

curl 'https://api.iterative.ly/iglu/schemas/ly.iterative.{your-company-id}/' --header 'apikey: {your-api-key}'