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:

1. Event batching
2. Event creation
3. API updates
4. Geolocation context
5. iOS 9.0 and XCode 7 changes
6. tvOS support
7. Demonstration app
8. Other changes
9. Upgrading
10. 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 GETs, 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 an NSString instead of an NSURL
  • You now only need to set the resource name for the collector (i.e. host/path, not http(s)://host/path)
  • If your endpoint uses unsecured HTTP (not HTTPS), then you must setProtocol to SPHttp
  • 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
• Removed setBufferOption builder function in favour of setByteLimitX, below
• Added setByteLimitGet builder function for setting a GET request byte maximum
• Added setByteLimitPost builder function for setting a POST 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:

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 and WatchKit.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!