We are pleased to announce a new release of the Snowplow iOS Tracker. Version 1.3.0 is an important release that introduces Global Contexts, GDPR contexts and support for the Swift Package Manager thanks to the contribution of @vauxhall. Swift Package Manager completes the list of supported dependency managers, which already includes Cocoapods and Carthage.
Read on below for:
- Global Contexts
- Tracking GDPR basis for processing with the GDPR context
- Swift Package Manager support
- Deprecated methods
- Updates and bug fixes
- Getting help
1. Global Contexts
We are happy to announce the integration of the Global Contexts feature in the iOS tracker (#357).
1.1 A quick recap on contexts
Contexts are entities tracked across multiple events. They are particularly important as they add value to the event through tracking extra information according to a related schema. The schema will specify the kind of data tracked with the context. Typical contexts are: session, geolocation, page and screen views, device informations, user details.
Some of the contexts are tracked out-of-the-box but it’s possible to add custom context tracking to other domain specific events. There is no limit to the number of contexts attached to the events. Not all contexts suit every event. Some of the contexts only make sense on specific events and it’s up to the developer to handle these cases.
1.2 Introducing Global Contexts
Prior to this release, developers needed to programmatically attach custom contexts to each specific event. The global contexts feature helps the developer by making this operation declarative. The developer can declare which contexts have to be attached to which events and the tracker will take care of attaching the contexts to the events when required as declared by the developer.
- It makes it easier for developers to implement very rich data tracking with Snowplow.
- It makes the tracking less error-prone - it is less likely that an event will accidentally be sent without a required context attached.
- That in turn makes it easier for analysts and developers consuming the data, because they can be confident to expect certain events from particular platforms to always have the required contexts attached.
1.3 Getting started with Global Contexts
As explained above, the global contexts are particularly helpful when the developer wants to associate specific contexts to all the events or a subset of them, rather than adding the contexts manually to each event tracked. This can be done at tracker setup declaring the contexts generator and the suitable subset of events.
setGlobalContextGenerators: can be used to set up the generators which are able to create contexts. Each context generator is associated a tag string. The tag string can be used to remove a generator at runtime using the method
nil in case the there aren’t global contexts stored with the specified tag, otherwise it returns the removed SPGlobalContext instance.
It’s possible to add global contexts at runtime with the method
1.3.1 Context primitives
Context primitive is a term for anything that can be used as a context. A context primitive is a self-describing JSON, or a callback that creates a self-describing JSON.
This is useful in cases where the context is static and it’s always the same.
Context Generator Callback
A context generator callback returns an array of self describing JSONs, representing contexts. They are evaluated each time an event is sent, hence they meet the case where we would like to send a context based on event information.
SPInspectableEvent is an interface that exposes internal data of the event processed: event name, schema and payload.
1.3.2 Conditional Context Providers
The previous examples described the generation of contexts that are associated to every event. However, there are cases where the contexts should only be applied to certain events.
A filter callback is used to discriminate between events so we can attach global contexts only to certain events.
A ruleset provider is used when you want to attach a global context to certain events based on the schema URI.
A ruleset provider has a ruleset which has a list of allowed schemas and a list of denied schemas. Both lists contain Iglu URIs which can be modified based on some syntactic rules.
In this example, the ruleset provider will attach the generated contexts (as described in the previous section) to events with the schema
iglu:com.acme.*/*/jsonschema/*-*-*, but not to
RuleSet’s rules are the strings used to match against certain schemas, such as
They follow the same five-part format as an Iglu URI:
with the exception that a wildcard can be used to refer to all cases.
The parts of a rule are wildcarded with certain guidelines:
asterisks cannot be used for the protocol (i.e. schemas always start with
version matching must be specified like so: --, where any part of the versioning can be defined, e.g. 1--, but only sequential parts can be wildcarded, e.g. 1--1 is invalid but 1-- is valid.</li><li>at least two parts:
com.acme.*is valid, while
vendors cannot be defined with non-wildcarded parts between wildcarded parts: com.acme..marketing. is invalid, while com.acme.. is valid.
In case the logic for filter and generator callbacks are too complex, it’s possible to specify them in a class that implements
In this case the logic for filtering and generation is encapsulated behind a context generator class.
It can be passed to the tracker as usual:
2. Tracking GDPR basis for processing with the GDPR context
This release introduces the
gdprContext and the
enableGdprContext methods, which append a GDPR context to all events once enabled (#425). This allows users to easily record the basis for data collection and relevant documentation, and enables a straightforward audit flow for all events.
It takes the following arguments:
| ||GDPR Basis for processing||Yes||Enum String|
| ||ID of a GDPR basis document||No||String|
| ||Version of the document||No||String|
| ||Description of the document||No||String|
The required basisForProcessing accepts only the following literals:
legitimate_interests - in accordance with the five legal bases for processing.
The GDPR context is enabled by calling the
setGdprContextWithBasis:documentId:documentVersion:documentDescription: method of the tracker builder or by calling the
enableGdprContextWithBasis:documentId:documentVersion:documentDescription: method once the tracker has been initialised.
It is called as follows:
3. Swift Package Manager support
The Swift Package Manager is the official Apple dependency manager designed for Swift libraries. Since Xcode 11, SPM is compatible with the iOS build system. Thanks to the important contribution from @vauxall, we have introduced the support of Swift Package Manager for our iOS tracker (#474). At the moment it supports only the iOS platform due to some limitations that we will resolve in future releases, but it is a great option for adding our mobile tracker and a great contribution from our active community.
To install Snowplow Tracker with SPM:
- In Xcode, select File > Swift Packages > Add Package Dependency
- Add the repository of: https://github.com/snowplow/snowplow-objc-tracker
- Add the modules to your project’s targets in the General tab > Frameworks, Libraries & Embedded Content section
4. Deprecated methods
In this release we’ve marked a few methods as deprecated:
eventId: This shouldn’t be used as it can cause ambiguity about event duplication. This property will be set only by the tracker. If your code sets its own eventId we suggest to record your custom event ID in a custom context associated to all the events.
timestamp: In a future major version we will remove the ability to override the timestamp of the event. That will be set only by the tracker. A custom timestamp can be eventually added using a different method or parameter in a future release.
addDefaultParamsToPayload:: This shouldn’t be used as it’s an internal method used by the tracker and it can be subject to future changes.
Other methods have also been marked as deprecated because they are related to internal logic of the tracker. We strongly suggest avoiding the use of these methods marked deprecated as they will be substituted or removed in the next major version.
5. Updates and bug fixes
Internal events refactoring (#489).
As always, information about how to use the tracker can be found in the iOS Tracker documentation.
You can find the full release notes on GitHub as Snowplow iOS Tracker v1.3.0 release.
7. Getting help
For help on integrating the tracker please have a look at the setup guide. If you have any questions or run into any problems, please visit our Discourse forum. Please raise any bugs in the iOS Tracker’s issues on GitHub.