Events from iOS Apps

See the Overview for details about setting up the Datacoral Collect Events Slice.

Step 1: Get the tracker from Datacoral instrumentation library

Following command will download the tracker

curl -Lo datacoral-slice-event-tracker-ios.tgz https://static.datacoral.io/prod/instrumentation/ios/latest/datacoral-slice-event-tracker-ios.tgz
tar -xvf datacoral-slice-event-tracker-ios.tgz

You should have following directory:

tree ios-tracker/package/
├── Snowplow
│ ├── OpenIDFA.h
│ ├── OpenIDFA.m
│ ├── SPEmitter.h
│ ├── SPEmitter.m
│ ├── SPEvent.h
│ ├── SPEvent.m
│ ├── SPEventStore.h
│ ├── SPEventStore.m
│ ├── SPPayload.h
│ ├── SPPayload.m
│ ├── SPRequestCallback.h
│ ├── SPRequestResponse.h
│ ├── SPRequestResponse.m
│ ├── SPSelfDescribingJson.h
│ ├── SPSelfDescribingJson.m
│ ├── SPSession.h
│ ├── SPSession.m
│ ├── SPSubject.h
│ ├── SPSubject.m
│ ├── SPTracker.h
│ ├── SPTracker.m
│ ├── SPUtilities.h
│ ├── SPUtilities.m
│ ├── SPWeakTimerTarget.h
│ ├── SPWeakTimerTarget.m
│ ├── Snowplow-Prefix.pch
│ ├── Snowplow.h
│ └── Snowplow.m
├── datacoral_readme.md
└── package.json

Step 2: Copy the tracker into your project (MyObjcApp)

You only need to copy the tracker's ios-tracker/package/Snowplow/ sub-folder into your XCode project's folder. The command will look something like this.

cp -r ios-tracker/package/Snowplow MyObjcApp/MyObjcApp/

Replace MyObjcApp with the name of your own app, and tweak the source code sub-folder accordingly.

Next, drag and drop the sub-folder MyObjcApp/MyObjcApp/Snowplow into your XCode project's workspace. Make sure that the suggested options for adding Snowplow are set Create groups, then click Finish.

Add the FMDB dependency

The tracker is dependent on FMDB version 2.3, an Objective-C wrapper around SQLite.

As before, git clone the dependency and copy the source into your XCode project's folder:

git clone https://github.com/ccgus/fmdb.git
cd fmdb && git checkout v2.3
cp -r src/fmdb ../MyObjcApp/MyObjcApp/

As before, drag and drop the sub-folder MyObjcApp/MyObjcApp/fmdb into your XCode project's workspace, making sure to Create groups.

Finally, you will need to edit Snowplow/SPEmitter.m and Snowplow/SPEventStore.m in X-Code and change:

#import <FMDB.h>

to

#import "FMDB.h"

Add the Reachability dependency

For iOS only, the tracker is dependent on Reachability version 3.2, a drop in replacement for Apple's Reachability class.

As before, git clone the dependency and copy the source into your XCode project's folder:

git clone https://github.com/tonymillion/Reachability.git
cd Reachability && git checkout v3.2
cp Reachability.{h,m} ../MyObjcApp/MyObjcApp/

Now add the Reachability.{h,m} files to your project by:

  • Right-clicking on your MyObjcApp folder in XCode
  • Selecting Add Files to "MyObjcApp"...
  • Selecting both Reachability files and adding them

Once you have added the .h/m files to the project:

Step 3: Import all SystemConfiguration frameworks

  • Go to Projects->TARGETS->Build Phases->Link Binary With Libraries
  • Press the plus in the lower left of the list
  • Add SystemConfiguration.framework

Linkin-Framework

Import all required frameworks

The tracker also depends on various frameworks:

$ grep 'frameworks' ../snowplow-objc-tracker/SnowplowTracker.podspec
s.ios.frameworks = 'CoreTelephony', 'UIKit', 'Foundation'
s.osx.frameworks = 'AppKit', 'Foundation'

Go to Target > General tab > Linked Frameworks and Libraries section and add:

  1. All of the frameworks for your target platform, as returned by the grep above
  2. libsqlite3.dylib

Building

Now Build your project and you should see Build Succeeded. If you get a build error, check that you added Snowplow and fmdb as Groups, not just as Folders.

You are now ready to proceed to instrumenting your app. Just remember to use quotation marks not angle brackets, and the Snowplow sub-folder as necessary when importing the tracker:

#import "SPTracker.h"
#import "SPEmitter.h"
#import "SPUtilities.h"
#import "SPSubject.h"
#import "SPRequestCallback.h"
#import "SPEvent.h"

Step 4: Creating a tracker

To instantiate a tracker in your code simply instantiate the SPTracker class with the following builder pattern after substituting the appropriate environment parameters.

URL_ENDPOINT : The URL of your Datacoral Events API gateway. Ex. events.dccustomer.datacoral.io

API_KEY : The Datacoral API key to authorize the events invocations. Ex. 1js9q5Gqmk2VDv2omx2WI3yUGV0K7b464fWUJXDX

ENVIRONMENT : Set the environment as dev or prod, based on the emitter of the events

NAMESPACE : The name of this Tracker instance to include with events sent to the collector. The namespace argument attached to every event fired by the new tracker. This allows you to later identify which tracker fired which event if you have multiple trackers running. Ex. landing_pages

APP_ID : Name of application to include with events sent to the collector. The application ID is used to distinguish different applications that are being tracked by the same Snowplow stack. Ex. "finance" or "hr"

SPEmitter *emitter = [SPEmitter build:^(id<SPEmitterBuilder> builder) {
[builder setUrlEndpoint:URL_ENDPOINT];
[builder setHttpMethod:SPRequestPost];
[builder setProtocol:SPHttps];
[builder setCallback:self];
[builder setEmitRange:500];
[builder setEmitThreadPoolSize:20];
[builder setByteLimitPost:52000];
}];
SPSubject *subject = [[SPSubject alloc] initWithPlatformContext:YES andGeoContext:NO];
SPTracker *tracker = [SPTracker build:^(id<SPTrackerBuilder> builder) {
[builder setEmitter:emitter];
[builder setAppId:APP_ID];
[builder setTrackerNamespace:NAMESPACE];
[builder setBase64Encoded:true];
[builder setSessionContext:YES];
[builder setSubject:subject];
[builder setAPIKey:@"API_KEY"];
[builder setEnvironment:@"ENVIRONMENT"];
}];

Please substitute appropriate values for URLEndpoint, APIKey, Environment and AppId.

Tracking specific events

Refer to https://github.com/snowplow/snowplow/wiki/iOS-Tracker#events

Reference

https://github.com/snowplow/snowplow/wiki/iOS-Tracker-Setup https://github.com/snowplow/snowplow/wiki/iOS-Tracker