Snowplow event tracker for Python

1.1.0 · active · verified Sun Mar 29

The Snowplow Python Tracker allows you to collect and track event data from your Python applications, games, and web servers/frameworks, including Django. It provides a robust way to implement analytics by defining subjects, emitters, and trackers to send events to a Snowplow collector or custom event store. The library is actively maintained, with the current version being 1.1.0, and receives regular updates.

Warnings

gotcha When initializing the tracker, the `namespace` argument is mandatory. Failing to provide it will result in an error or default behavior that might not be desired for identifying events from specific tracker instances.
Fix: Always provide a unique `namespace` argument when calling `Snowplow.create_tracker` or directly instantiating `Tracker`.
gotcha The documentation mentions that `track_screen_view()` and `track_unstruct_event()` were not fully supported in the Snowplow data pipeline's enrichment, storage, or analytics stages in older versions (e.g., v0.2, v0.4), meaning events would be logged but not processed further.
Fix: Ensure you are using a recent version of `snowplow-tracker` (1.x.x) and that your Snowplow data pipeline is up-to-date to fully process all event types, especially custom unstructured events.
breaking The Snowplow ecosystem, particularly for mobile trackers (iOS and Android), underwent significant API changes from version 1.x to 2.0, with `Snowplow.createTracker` becoming the new entry point and the old API being deprecated. While `snowplow-tracker` for Python is currently at version 1.x.x, future major releases might introduce similar breaking changes.
Fix: Always consult the official migration guides when upgrading to a new major version of `snowplow-tracker` to understand potential API changes and necessary code adjustments. For the current 1.x.x Python tracker, refer to the 'Upgrading to newer versions' section in the Python tracker SDK documentation.

Install

pip install snowplow-tracker Install latest version

Imports

Snowplow
```
from snowplow_tracker import Snowplow
```
Preferred entry point for initializing a tracker with default emitter and subject settings.
Tracker
```
from snowplow_tracker import Tracker
```
While direct instantiation of Tracker, Emitter, and Subject is possible, Snowplow.create_tracker is recommended for most use cases as it simplifies initialization.
Emitter
```
from snowplow_tracker import Emitter
```
See note for Tracker; direct instantiation of components is an older pattern that is often replaced by `Snowplow.create_tracker`.
Subject
```
from snowplow_tracker import Subject
```
See note for Tracker; direct instantiation of components is an older pattern that is often replaced by `Snowplow.create_tracker`.

Quickstart

This quickstart demonstrates how to initialize the Snowplow tracker and send various event types, including page views, structured events, and custom self-describing events. Ensure `SNOWPLOW_COLLECTOR_ENDPOINT` is set in your environment or replace `'collector.example.com'` with your actual Snowplow collector URI.

import os
from snowplow_tracker import Snowplow, SelfDescribingJson

# Configure your Snowplow collector endpoint
COLLECTOR_ENDPOINT = os.environ.get('SNOWPLOW_COLLECTOR_ENDPOINT', 'collector.example.com')

# Initialize the Snowplow tracker
# The namespace is mandatory and helps identify events from this tracker instance.
tracker = Snowplow.create_tracker(namespace='my-app-tracker', endpoint=COLLECTOR_ENDPOINT)

# Track a page view event
tracker.track_page_view(
    page_url='http://www.example.com/home',
    page_title='Homepage',
    referrer='http://www.example.com/previous'
)

# Track a structured event
tracker.track_struct_event(
    category='engagement',
    action='click',
    label='hero-button',
    property='primary-cta',
    value=1.0
)

# Track an unstructured event (Self-Describing Event)
custom_event_schema = SelfDescribingJson(
    'iglu:com.example/my_custom_event/jsonschema/1-0-0',
    {'feature': 'new-feature', 'version': '1.0'}
)
tracker.track_self_describing_event(custom_event_schema)

print(f"Events tracked to {COLLECTOR_ENDPOINT} (check your Snowplow pipeline). ")

view raw JSON →