Snowplow

Iteratively supports Snowplow as a first-class destination.

Support

✅ SDK support for Browser—JavaScript, Browser—TypeScript, and Python-*

  • 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

Getting Started#

To begin using Snowplow with Iteratively:

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

  2. Create a 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 ampli pull as usual

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

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

Schema Vendor Name#

By default, Iteratively will generate a unique vendor name (ly.iterative.{your-company-id}) and use it when generating Iglu-compatible schemas and self-describing JSONs. To set your own vendor name, navigate to the Snowplow section of your account's settings.

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:{vendor-name}/{event-name}/jsonschema/{event-version}
  • Events in Iteratively are versioned according to SchemaVer
    • Iteratively also supports parallel tracking plans versions, so-called branches. In branches other than main, the SchemaVer representation will diverge from the spec and include the branch identifier in the vendor name, e.g. {vendor-name}-feature-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/{vendor-name}/' --header 'apikey: {your-api-key}'