iOS Client

Installation (CocoaPods)

The easiest way to use the Calq iOS SDK is with CocoaPods.

  1. If you have not already done so, install CocoaPods using gem install cocoapods followed by pod setup to create a local mirror.
  2. Create a file in your Xcode project called Podfile with the following line included:

    pod 'CalqClient-iOS'
  3. Run pod install from your Xcode project directory to import the Calq library.

Installation (Manually)

Please see our Xcode manual installation instructions if you wish to download and use the library source directly.

Setup shared instance

First you should initialize the client library using [CalqClient initSharedInstanceWithKey:]. This will create a client and load any existing user information or properties that have been previously set.

The recommended way to do this is in applicationDidFinishLaunching: or application:didFinishLaunchingWithOptions in your Application delegate:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{    
    // Override point for customization after application launch.
    [CalqClient initSharedInstanceWithKey:@"YOUR_WRITE_KEY_HERE"];

    // ...
}

You will need to add your Calq project's write key to the snippet where it says YOUR_WRITE_KEY_HERE. You can find your write key from the project settings option inside Calq.

After initializing the shared instance you can use Calq anywhere using [CalqClient sharedInstance].

Tracking actions

Calq performs analytics based on actions that user's take. You can track an action using track:properties:. Specify the action and any associated data you wish to record.

// Track a new action called "Product Review" with a custom rating
[[CalqClient sharedInstance] track:@"Product Review" properties:@{ @"Rating": @9.0 }];

The properties parameter allows you to send additional custom data about the action. This extra data can be used to make advanced queries within Calq.

Tracking revenue actions

Actions sometimes have revenue amount associated with them such as an item sale or sponsored banner click. Calq provides a special method for these actions called trackSale:properties:currency:value. This includes the same parameters as track:properties: but includes 2 extra for a currency code and revenue amount.

// Track a sale action worth 9.99 USD
[[CalqClient sharedInstance] trackSale:@"Product Sale"
    properties:@{ @"Product Id": @149, @"Product Name": @"Dinosaur T-Shirt XL" }
    currency:@"USD"
    value:[[NSDecimalNumber alloc] initWithDouble:9.99]];

Using trackSale:properties:currency:value method will accurately attribute revenue to the current user. This allows Calq to produce revenue reports including user lifetime values (LTV).

If you want to track a refund then specify a negative sale amount.

Global action properties

There are often properties that you will want to include with every action you send to Calq. These properties are normally information about the environment, such as the device being used, or information about the user, such as age, gender, or referrer.

To save you specifying this information with each action, Calq lets you set global properties with setGlobalProperty:value:. Global properties are saved to the device so they will also persist between sessions (and cross device if the user has iCloud enabled).

// Set the "Referral Source" property for all new actions
[[CalqClient sharedInstance] setGlobalProperty:@"Referral Source" value:@"Google Campaign"];

The iOS client will also automatically add the following useful global properties with each action:

$device_agent The user agent of the browser being used.
$device_mobile Whether the device is a mobile device such as a phone or tablet.
$device_os The operating system running on the device (Windows, OSX, iOS, Android etc).
$device_resolution The screen size of the device being used.
$country The user's current country (from IP address).
$region The user's region within their country (from IP address).
$city The user's estimated city (from IP address - not always accurate particularly on mobile carriers).

Note that properties starting with a $ are special properties. Your custom properties should not start with a $.

Identifying users

All users are assigned a unique identifier by the Calq client. You may however want to assign a different ID, such as your own user ID from your database. A common case for this is when a user registers or logs in.

To assign a new ID to the current client session use identify:.

// Identify the current user as 12345678
[[CalqClient sharedInstance] identify:@"12345678"];

A user may have sent actions before you call identify. In this case the previous actions will be automatically associated with the new ID (going back a max of 14 days). This means if a user performs some actions in your application, and then logs in after, those actions are correctly attributed.

Once you have called identify you should not attempt to assign a different ID to the same user again. Calq will deliberately reject this. Calling identify with the existing Id is allowed and will be silently ignored.

Logging out

When users logout of your website you normally want to stop associating tracked actions with that user. To do this you will need to clear the Calq session using clear.

// Generate a new session to track subsequent actions (logout the current user)
[[CalqClient sharedInstance] clear];

Using clear generates a new session. Actions performed after calling clear will be tracked as a new user, although if the same user logs back in again they can be correctly associated using identify:.

User information

In addition to sending data about actions, you can also send properties about users themselves. This allows you to analyze your audience based on who they are, rather than what they did.

You can set user properties using profile:. User properties are free-form so you can store whatever matters to you. However, just like actions, there are also some special properties too.

// Set some persistent profile properties for the current user
[[CalqClient sharedInstance] profile:@{ @"Company": @"MegaCorp", @"$email": @"super_customer1@notarealemail.com" }];

You must call identify: before you can store profile information.

Queuing

The iOS Calq client will queue API calls and send them in batches. This minimises battery use when sending data. You can force outstanding calls to be sent immeditately by calling flushQueue.

If a client goes offline (normally due to signal loss) then API calls will continue to be queued. They will be sent when connectivity is regained. If the application is exited before data is sent, then the data will be sent the next time the application is opened.

flushQueue will be called automatically when your application is terminated.