We are pleased to announce a new release of the Snowplow Python Tracker. We detail the new features, along with examples, below.
Version 0.9.0 includes a community contribution (many thanks @vicrep), which allows for a custom JSON encoder to be passed as a Tracker initialization parameter.
It also introduces a new way to track multiple subjects, by making
event_subject an optional parameter supported by all track methods.
Additionally it allows the optional timestamp argument to only set the
true_tstamp of the event, in accordance with the Snowplow Tracker Protocol.
Similar to the
on_failure callback, the argument being passed to the
on_success callback is now the array of successfully sent events, in order to allow users to inspect it if required.
Redis and Celery are now extras, so that users who don’t use the related functionality do not need to install them as dependencies.
Finally, this release adds support for Unicode, publishes a Python 3 wheel in PyPI and increases the test coverage.
Read on below for:
- Customizing JSON encoder
- Tracking multiple subjects
- Setting the true_tstamp
- On_success callback
- Installation – Redis, Celery as extras
- Documentation and help
1.Customizing the JSON encoder
It is now possible to customize the JSON encoder used to serialize objects added to the payload. This happens through an additional optional parameter for Tracker initialization.
from datetime import date from json.encoder import JSONEncoder def date_encoder(o): if isinstance(o,date): return o.isoformat() return JSONEncoder.default(o) t = Tracker(my_emitter, json_encoder=date_encoder)
2. Tracking multiple subjects
With Version 0.9.0, it is now possible to set the subject per event. This allows you to track multiple subjects with a fine-grained control over the information you may want to add as your users’ journeys evolve. Prior to v0.9.0 this was only possible by mutating the Tracker-level subject, which made it problematic for multi-threaded applications (GitHub issue #158).
Now, the Tracker-level subject will only be used for events that don’t specify an event subject as an optional argument.
You can specify an
event_subject in all track methods. For example:
evSubject = Subject().set_platform("srv").set_user_id("tester") t.track_page_view("www.example.com", event_subject=evSubject)
3. Setting the true_tstamp
true_tstamp is the exact timestamp of when the event occurred that is set by the user using the optional timestamp argument in all track methods. If this timestamp is set, it will be the one used for determining the
derived_tstamp of an event.
As described in GitHub issue #251, prior to v0.9.0:
- Setting the
true_tstampresulted in the
dvce_created_tstampnot being set
- The user could also set the
With this release:
- The user can only set the
true_tstampof an event.
dvce_created_timestampis set in all cases independently.
You can set the
true_tstamp of an event by providing the optional timestamp argument in the track methods. This should be the Unix timestamp in milliseconds, for example:
import time time_in_millis = time.time() * 1000 t.track_page_view("example.com", tstamp=time_in_millis)
If you migrate from the previous version, make sure to replace any references to Timestamp objects, since the Timestamp class (along with the TrueTimestamp and DeviceTimestamp subclasses) have been removed.
4. on_success callback argument
on_success is an optional callback that will execute on successfully sent events. Prior to v0.9.0, this callback function would receive the number of successfully sent events. With this release (GitHub issue #228), the
on_success callback function will be passed the array of successfully sent events themselves, in order to augment this functionality.
def success_callback(arr): for event_dict in arr: print(event_dict) e = Emitter("my.collector.endpoint”, on_success=success_callback)
5. Installation – Redis, Celery as extras
Through pip, you can install the Snowplow Python Tracker v0.9.0 as:
$ pip install snowplow-tracker==0.9.0
The above will not install the Redis and Celery extras. If you want to use the functionality of the RedisEmitter or RedisWorker or the CeleryEmitter, you need to install the tracker as:
$ pip install snowplow-tracker[redis] $ pip install snowplow-tracker[celery]
As described in the corresponding sections above, in order to upgrade from the previous version, you only need to take special care if you:
- require the extras [redis,celery] as dependencies
- set the optional timestamp argument in the track methods
- use the
7. Documentation and help
For help on integrating the tracker please have a look at the Setup guide. Information about how to use the tracker can be found in the Python Tracker Documentation. If you have any questions or run into any problems, please visit our Discourse forum.
If you are interested in the full release notes, you can find them here. Please raise any bugs in the Python Tracker’s issues on GitHub.