UserIQ Mobile SDK for iOS

Getting Started

---

Get a UserIQ Application Token

The first thing you'll need in order to get app analytics into your UserIQ account is a UserIQ account and Application Token. The application token is the same as your Site ID. You will need one Application Token per application (distinguished by bundle ID's). Once you have an Application Token, you're ready to implement the library.

Download the UserIQ iOS Static Library

The iOS static library can be downloaded here. Once you have downloaded the library, simply add it and the associated header files to your Xcode project, and you're good to go. There are no other framework dependencies that you need to add!

Start tracking

Open AppDelegate.m and add the following import statement to the top of the file:

#import "UserIQ.h"

A single line of code is needed to start tracking user sessions in your app. Inside AppDelegate.m, add the following line anywhere before the final return statement:

[UserIQ startSession:@"YOUR_APP_TOKEN"];

Obviously, you'll need to insert the Application Token you generated earlier here.

Tracking Views

---

Tracking manually

The UserIQ library comes with a few methods to track view appearance and disappearance, namely trackViewAppearance: and trackViewDisappearance:, respectively. The entire view hierarchy of a UIViewController subclass can also be tracked using the method trackViewHierarchyForViewController:. This will list every subview of the main view.

Tracking automatically

Adding a bunch of viewDidAppear: and viewDidDisappear: implementations just to track views is a bit silly. To track this automatically for your view controllers, as well as the entire view hierarchy, simply make your view controllers a subclass of UIQTrackedViewController. All of the tracking calls for appearance and disappearance will be called automatically.

Setting Session Characteristics

These days, users tend to switch between multiple applications as they interact with their phones. As such, a user backgrounding your app may not actually signal the end of their session. In order to maintain the integrity of a single session while a user moves between different apps, the UserIQ library uses a session timeout expiration. The default is 30 seconds. If you feel your users will need to leave your application for any reason and come back at a time greater or less than 30 seconds, you may use the method setSessionTimeout: to change this value. When your application has been backgrounded for longer than the session timeout time, a new session will be started when it returns to the foreground.

A session can be manually ended by called endSession. This is useful if you track sessions based on logged in users, and a user logging out of their account should signal the end of their session.

Setting User Characteristics

A user of your application can be defined in a multitude of ways. Some users have usernames. Some have full-fledged profiles. Use the method setUserID:withattributes: to set these user-specific characteristics. A User ID can be a username, password, or any other uniquely identifiable string you use to identify your users. The attributes is an NSDictionary of meta data about a user, such as their name, age, or home town. Sensitive information, such as a user's password, should not be set as an attribute.

Furthermore, it is increasingly more common for a single user to use your app from multiple devices (e.g. from an iPhone and from an iPad). In order to differentiate the same user across multiple devices, the ID of the device is automatically set at the start of each session. If you would like to use a different kind of device identifier, use the setDeviceID: method to change the default.

NOTE: Setting the UserID, user attributes, and/or device ID should be done prior to the start of a session. As an example:

[UserIQ setUserID:@"USER_ID" withAttributes:@{ @"email" : @"[e-mail]", @"age" : @26, @"user_name" : @"jordan", @"account_name" : @"jordan" }];

[UserIQ startSession:@"YOUR_APP_TOKEN"];

Debugging

---

There's no need to skew your user metrics while you are building your application. Thus, UserIQ allows you to set a global debug flag that will prevent any analytics data from being sent to UserIQ. Instead, data will be logged to the console. To turn on debug mode, simply add:

[USerIQ setDebugMode:YES]; 

to:

 application:didFinishLaunchingWithOptions:.