iOS SDK v2

Releases
Setup
- Initializing with Development and Production keys
Example Calls
Optional Automated Tracking
Changes from v1

This page describes version 2 of our official iOS SDK. For documention for version 1, see here.

Releases

https://github.com/kissmetrics/KISSmetrics-iOS-SDK/releases

Setup

Add the KISSmetricsSDK.framework to your project.
Within AppDelegate.m, import the framework like so:

#import <KISSmetricsSDK/KISSmetricsAPI.h>

Still in the AppDelegate.m file, find the didFinishLaunching or didFinishLaunchingWithOptions method and add the following code as the first line in that method. Be sure to apply your API key.

[KISSmetricsAPI sharedAPIWithKey:@"xxxxxxxxxxxxxxxxxxxxxxxxxxxx"];

Initializing with Development and Production keys

#ifndef DEBUG
	[KISSmetricsAPI sharedAPIWithKey:@"yourDevelopmentProductKeyHere"];
#elif RELEASE
	[KISSmetricsAPI sharedAPIWithKey:@"yourProductionProductKeyHere"];
#endif

Example Calls

// Initialize the API
[KISSmetricsAPI sharedAPIWithKey:@"xxxxxxxxxxxxxxxxxxxxxxxxxxxx"];

// Identifying Users
[[KISSmetricsAPI sharedAPI] identify:@"name@email.com"]; // Replace @"name@email.com" with code that gets the identity of your user!

// Track Event
[[KISSmetricsAPI sharedAPI] record:@"My Event"];
[[KISSmetricsAPI sharedAPI] recordEvent:@"My Event"];	// recordEvent() is being deprecated

// Track Event with Properties
NSDictionary *myEventProperties = [[NSDictionary alloc]
  initWithObjectsAndKeys:@"Value", @"My Property", nil];
[[KISSmetricsAPI sharedAPI] record:@"My Event With Properties"
  withProperties:myEventProperties];

// Set Properties
NSDictionary *myEventProperties = [[NSDictionary alloc]
  initWithObjectsAndKeys:@"Value", @"My Property", nil];
[[KISSmetricsAPI sharedAPI] set:myEventProperties];
[[KISSmetricsAPI sharedAPI] setProperties:myEventProperties];  // setProperties() is being deprecated

/* New Functions as of v2 */
// Track an event only once per set identity. After an identity is cleared or a new identity is set, the condition will pass once again.
[[KISSmetricsAPI sharedAPI] record:@"Viewed feature" onCondition:KMARecordOncePerIdentity];

// Track an event only once per install
[[KISSmetricsAPI sharedAPI] record:@"Installed App" onCondition:KMARecordOncePerInstall];

// Set user properties only if they have changed on the device
[[KISSmetricsAPI sharedAPI] setDistinct:@"7.1" forKey:"OS version"];

Optional Automated Tracking

`autoRecordInstalls()`

Calling this records two events:

Installed App
Updated App

`autoSetAppProperties()`

Calling this sets the following properties:

App Version : 1.0.0
App Build : 101

`autoSetHardwareProperties()`

Calling this sets the following properties:

Device Manufacturer: Apple
Device Platform: iPhone
Device Model: iPhone 5s
System Name: iOS
System Version: 7.0.4

Changes from v1

The identify method now works the same as it does in our JavaScript library. That is, recording identities no longer aliases known identities to one another.
- For example, if a user has been given a known identity such as “user@example.com” and a second call is made to identify: “another@example.com”, the SDK no longer assumes that this a second known identity for the same user and these identities will no longer be aliased to one another automatically.
Now, if there are 2 or more known identities of a user, a call to alias these two identities must be made.
Previously, a call to clearIdentity() was required before a new users’s identity was set. Though, it’s still a good idea to call clearIdentity() when a user signs out.
The KISSMetrics class is deprecated. Use KISSmetrics.

Performance

In the new SDK, all calls to record events, properties, identities and aliases are immediately passed onto a background thread for processing and delivery.

In our version 1, the processing of these calls was handled by the same thread that made the call to record before being delivered asynchronously. This wasn’t optimal as an application’s main thread is responsible for view updates and user interactions.

As a third party addition to our customers’ apps, we should use as little of the main thread as possible to ensure that our SDK doesn’t contribute to any lag in the users’ experience of their apps.

Send Queue Archiving

The SDK will archive all activity in a send queue and attempt to deliver from that queue as connectivity permits.

iOS v2 SDK specs

Size (compiled): 942kb
Memory Overhead
- idle: 330.32kb (under iOS 7)
- per avg. event with properties: estimated at < 500 bytes (< 200 for required params plus assumed < 300 bytes for average event with properties). During archiving of each event with properties, approximately 3kb of memory is allocated and quickly released.
iOS version support: iOS 5.1 (>99% of iOS devices)

Kissmetrics