Snowplow Objective-C Tracker 0.6.0 released


We are pleased to release version 0.6.0 of the Snowplow Objective-C Tracker. This release refactors the event tracking API, introduces tvOS support and fixes an important bug with client sessionization (#257). Many thanks to community member Jason for his contributions to this release!
In the rest of this post we will cover:
- Event batching
- Event creation
- API updates
- Geolocation context
- iOS 9.0 and XCode 7 changes
- tvOS support
- Demonstration app
- Other changes
- Upgrading
- Getting help
1. Event batching
Historically, the Objective-C Tracker used 10 events as a hard upper-limit to the number of events to send to a Snowplow collector at a time in a single POST
.
As of this release, we are replacing this with a limit on the number of bytes in a single POST
. This defaults to 40,000 bytes, but you can override it like so:
SPEmitter *emitter = [SPEmitter build:^(id<SPEmitterBuilder> builder) { [...] [builder setByteLimitGet:52000]; // Default is 40000 [builder setByteLimitPost:52000]; // Default is 40000 }];
As you can see, this release also implements a byte limit for GET
s, which always contain only 1 event.
In the case that a single event exceeds the byte limit, the tracker will attempt to send that event on its own, but won’t attempt to resend the event in the case of a failure (i.e. won’t write that event to the event store). In other words, the tracker will “fire and forget” outsized events.
2. Event creation
Following from the Android Tracker we have now implemented builder patterns for all of the events available to the Tracker. This is quite a large API change but one which will allow future customization with much greater ease.
To illustrate the change we will send a PageView event under the old and new styles:
// Deprecated [tracker trackPageView:@"DemoPageUrl" title:nil referrer:@"DemoPageReferrer"]; // New SPPageView *event = [SPPageView build:^(id<SPPageViewBuilder> builder) { [builder setPageUrl:@"DemoPageUrl"]; [builder setReferrer:@"DemoPageReferrer"]; }]; [tracker trackPageViewEvent:event];
While the builder pattern introduces some verbosity, it has several key advantages:
- No need to set
nil
values for fields that are not required and that you do not want to fill - Allows us to extend the API without having to introduce breaking API changes in the future
- Allows you to build an event ahead of time without having to send it instantly
Please refer to the technical documentation for other examples.
3. API updates
With the aforementioned performance updates the SPEmitter
has undergone some important updates:
- Added
setProtocol
builder function for choosing between HTTP and HTTPS. It defaults to HTTPS - Changed
setUrlEndpoint
builder function to accept anNSString
instead of an NSURL- You now only need to set the resource name for the collector (i.e.
host/path
, nothttp(s)://host/path
) - If your endpoint uses unsecured HTTP (not HTTPS), then you must
setProtocol
toSPHttp
- If your application is running on iOS 9, tvOS 9 or OS X 10.11 or later you will need to use
SPHttps
as per Apple’s Application Transport Security
- You now only need to set the resource name for the collector (i.e.
- Removed
setBufferOption
builder function in favour ofsetByteLimitX
, below - Added
setByteLimitGet
builder function for setting aGET
request byte maximum - Added
setByteLimitPost
builder function for setting aPOST
request byte maximum
The tracking functions within SPTracker
have all been updated to fit the new builder pattern for event creation. Each tracking function now accepts only a single variable in the form of the event object created. Here is a table of the updated tracking functions:
Old function name | New function name | New argument type |
---|---|---|
trackPageView |
trackPageViewEvent |
SPPageView |
trackStructuredEvent |
trackStructuredEvent |
SPStructured |
trackUnstructuredEvent |
trackUnstructuredEvent |
SPUnstructured |
trackScreenView |
trackScreenViewEvent |
SPScreenView |
trackTimingWithCategory |
trackTimingEvent |
SPTiming |
trackEcommerceTransaction |
trackEcommerceEvent |
SPEcommerce |
To access the new builders (SPPageViewBuilder
et al), make sure to import this new file into your code:
import "SPEvent.h"
4. Geolocation context
We have also a
dded support for Snowplow’s geolocation context. During SPSubject
creation you can now specify if you intend to use this context:
SPSubject * subject = [[SPSubject alloc] initWithPlatformContext:YES andGeoContext:YES];
Whereas in the JavaScript and Android Trackers we can automatically fetch the geo-location data for you, in this tracker you need to supply the geo-location data yourself. At a minimum you must populate the latitude and longitude fields:
[subject setGeoLatitude:123.123] [subject setGeoLongitude:-123.123]
The context will then be automatically added to all of your subsequent events. If you don’t set the latitude and longitude, then the geolocation context will not be added.
5. iOS 9.0 and XCode 7 changes
With the release of iOS 9.0 we have updated the Tracker as follows:
- We have removed the ability to use OpenIDFA under iOS 9.0+ (this is still functional for older versions) (#175)
With the release of XCode 7 we have updated the Tracker as follows:
- We have fixed a classname collision between
SPUtils
andWatchKit.framework
(#228) - We have handled the deprecation of OpenIDFA’s calendar in iOS 8 (#230)
Many thanks to Jason for bringing both of these issues to our attention!
6. tvOS support
We have also added the ability to use the Tracker from within a tvOS application in concert with the release of XCode 7.1.
Simply add the SnowplowTracker dependency to your podfile as you would normally:
pod 'SnowplowTracker', '~> 0.6'
Please note that to use tvOS
you will need version 0.39.+ of CocoaPods.
7. Demonstration app
The demo application has again been updated to reflect all of the changes that have taken place. If you are unsure about your own implementation or need any sample code please do review the code available here and here.
8. Other changes
Other updates include:
- Fixed a bug where the first
client_session
was passing an empty string instead of a null value (#257) - Added precondition checks to all core object construction (#117)
- Added a SelfDescribingJson class to ensure we build objects correctly (#119)
- Upgraded the client_session schema to 1-0-1 and started recording the firstEventId (#194)
- Added tests to assert that all generated schemas are valid using SnowplowIgluClient (#222)
- Fixed floats and doubles not being correctly shortened to two decimal places (#232)
9. Upgrading
To add the Snowplow Objective-C Tracker as a dependency to your own app, add the following into your Podfile:
pod 'SnowplowTracker', '~> 0.6'
If you prefer, you can manually add the tracker’s source code and dependencies into your project’s codebase, or use the Static Framework for iOS.
10. Getting help
Useful links:
- The technical documentation
- The setup guide
- The 0.6.0 release notes
If you have an idea for a new feature or want help getting things set up, please get in touch. And raise an issue if you spot any bugs!