iOS Client Reference

initSharedInstanceWithKey:

Initializes a shared CalqClient instance. This will read any cookie data previously set and populate the new client instance accordingly. The result is saved as a singleton to be accessed using [CalqClient sharedInstance].

This is the recommended way of creating using CalqClient instances.

Syntax

+ (CalqClient *) initSharedInstanceWithKey:(NSString *)writeKey

Arguments

writeKey NSString * Required The write key of the project that will receive data from this client.

Example

// Initialise Calq
[CalqClient initSharedInstanceWithKey:@"bfff14a4e0225789be3d9d22c4bb42a1"];

sharedInstance

Gets the singleton shared instance of a CalqClient. This must have been previously created with [CalqClient initSharedInstanceWithKey:].

Syntax

+ (CalqClient *) sharedInstance

Arguments

None

Example

// Get existing CalqClient instance
CalqClient * calq = [CalqClient sharedInstance];

initWithKey:

Initializes a new instance of the Calq client. Typically users would want to create clients using [CalqClient initSharedInstanceWithKey:] instead.

Syntax

- (instancetype) initWithKey:writeKey
- (instancetype) initWithKey:(NSString *)writeKey loadState:(BOOL)loadState

Arguments

writeKey NSString * Required The write key of the project that will receive data from this client.
loadState BOOL Optional A flag indicating whether or not to load existing client state (identity, super properties etc). This is primarily used for unit tests. Default value is YES if not specified.

Example

// Create a new CalqClient
CalqClient * calq = [[CalqClient alloc] initWithKey:@"bfff14a4e0225789be3d9d22c4bb42a1"];

track:properties:

Tracks a new action. This informs Calq that a user has taken an action.

Syntax

- (void) track:(NSString *)action properties:(NSDictionary *)properties

Arguments

action NSString * Required The name of the action to track. This will be shown in the reporting interface.
properties NSDictionary * Optional A dictionary containing additional data to associate with this event. Can be nil or an empty dictionary.

Property values (i.e. values in the properties dictionary) must be one of NSString, NSNumber, NSNull, NSDictionary, NSDate or NSURL. Property keys must be NSString.

To group action names into categories you can separate the name into parts with a . (for example "Products.Product Review")

Example

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

trackSale:properties:currency:value

Tracks a new special kind of action which includes revenue information.

Internally this function calls track:properties: with the reserved properties $sale_value and $sale_currency correctly set.

Syntax

- (void) trackSale:(NSString *)action properties:(NSDictionary *)properties currencyCode:(NSString *)currency value:(NSDecimalNumber *)value

Arguments

action NSString * Required The name of the action to track. This will be shown in the reporting interface.
properties NSDictionary * Optional An object containing additional data to associate with this event. Can be nil or an empty dictionary.
currency NSString * Required A 3 letter currency code for the currency being used. Can be fictional if using own internal currency or credits system.
value NSDecimalNumber * Required The value of the sale. Can be negative to indicate a loss or refund.

Example

// 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]];

setGlobalProperty:value:

Sets a new global property that will be automatically included in calls to track:properties: and trackSale:properties:currency:value. Properties will be persisted to the client.

There are special reserved properties that start with the $ symbol. Your custom properties should not start with a $.

Syntax

- (void) setGlobalProperty:(NSString *)property value:(id)value

Arguments

property NSString * Required The name of the property to set.
value id Required The value of the property being set. Type must be one of NSString, NSNumber, NSNull, NSDictionary, NSDate or NSURL.

Example

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

Extra

The Calq client will automatically add the following useful global properties automatically:

$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).
$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).

identify:

Sets the unique identity of the currently active user. This is typically called after a user registers or logs in. This ensures new tracked actions are attributed to this user Id.

If a user id is changed (i.e. the user was previously using an anonymous random Calq generated Id, and you specify a new one) then the client will ask the Calq API server to attribute previous actions with the old user Id to the newer Id. This looks back a max period of 14 days. If you require a longer period then you will need to manage identities yourself. Typically this involves either setting an Id which you control before a user registers, or alternatively reading the Calq generated Id server side and associating that with the user's account.

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.

Syntax

- (void) identify:(NSString *)actor;

Arguments

actor NSString * Required The new id of the user being tracked.

Example

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

clear

Clears the current client session and generates a new unique identifier. This ensures that any actions the user now takes are attributed to a new session. Typically this is called when a user has logged out of your website.

Syntax

- (void) clear

Arguments

None

Example

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

profile:

Saves persistent profile data for this user. This allows you to segment users later based on who they are rather than what they did.

There are some special user properties which start with a $ symbol. These have a specific meaning and are displayed separately in Calq's UI. For example, setting the property $full_name and $image_url will show this information in the Live Stream report withing Calq.

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

Syntax

- (void) profile:(NSDictionary *)properties

Arguments

params NSDictionary * Required The data to associate with this user. Existing values are overwritten if keys have the same name as before.

Property values (i.e. values in the properties dictionary) must be one of NSString, NSNumber, NSNull, NSDictionary, NSDate or NSURL. Property keys must be NSString.

Example

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

flushQueue

Requests that any pending API calls are flushed now rather than waiting. This method is called automatically when your application is terminated.

API calls are normally queued in the background and then sent in batches. This minimises battery use when sending data. They are also saved if a device loses connectivity (such as no signal) and retried again later.

Syntax

- (BOOL) flushQueue

Arguments

None

Example

// Flush queue immediately
[[CalqClient sharedInstance] flushQueue];

Special action properties

The following are special properties that can be sent when tracking actions using CalqClient.Track or CalqClient.TrackSale

.
$sale_value The amount of any sale. Marks this action as containing revenue. Must be specified if $sale_currency is also present.
$sale_currency The 3 letter currency code for any sale. Must be specified if $sale_value is also present.
$device_agent The user agent of the browser being used, or information on the device being used.
$device_os The operating system running on the device (Windows, OSX, iOS, Android etc).
$device_resolution The screen size of the device being used.
$device_mobile Whether the device is a mobile device such as a phone or tablet.
$country The user's current country (Taken from IP address if not specified manually).
$region The user's region within their country (Taken from IP address if not specified manually).
$city The user's city (Taken from IP address if not specified manually, though accuracy at city level is varied).
$gender The gender of the user (as either the string "male" or "female").
$age The age of the user. Must be an integer.
$utm_campaign The campaign name that was used to aquire this user (utm_campaign).
$utm_source The source that was used to aquire this user (utm_source).
$utm_medium The type of marketting medium that was used to aquire this user (utm_medium).
$utm_content The content source that was used to aquire this user (utm_content).
$utm_term The keywords used to aquire this user (utm_term).
$is_view Flags that this is a view (a page, or screen that contians other actions).
$is_within_view Flag whether this action occured within a view (the last set view).
$view_url The URL of this view if it's a page.
$view_name The name of this view (e.g. page title, or app screen name).

Special user properties

The following are special properties that can be set for user profiles using CalqClient.Profile.

$full_name The full name of this user.
$image_url URL to an image to display in Calq's UI when examining this user. Use a square image for best results.
$country The user's current country.
$region The user's region within their country.
$city The user's city.
$gender The gender of the user (as either the string "male" or "female").
$age The age of the user. Must be an integer.
$email The email address used to contact this user
$phone A phone number contact this user
$sms A mobile number that can be used to deliver SMS messages to this user.
$utm_campaign The campaign name that was used to aquire this user (utm_campaign).
$utm_source The source that was used to aquire this user (utm_source).
$utm_medium The type of marketting medium that was used to aquire this user (utm_medium).
$utm_content The content source that was used to aquire this user (utm_content).
$utm_term The keywords used to aquire this user (utm_term).

Platform limits

Calq has certain limits which you should factor in when modelling your actions. These limits can not be increased.

Action names
  • Maximum of 112 characters. Will be truncated if this is exceeded.
  • Names should not start with a $ symbol.
Action properties
  • Maximum of 50 registered properties per action type.
  • Maximum property name of 224 characters. Calq will reject actions with an error if this is exceeded.
  • Maximum property length of 256 bytes (factor in UTF8 size). Will be truncated if this is exceeded.
  • Property name must not start with a $ unless it's a special reserved property.
General properties
  • Maximum actor name of 128 bytes (factor in UTF8 size). Will be truncated if this is exceeded.
  • Maximum $device_agent of 1024 bytes. Will be truncated if this is exceeded.
  • All $utm_ paramters have a max size of 128 bytes, except for $utm_content which has 256. Will be truncated if this is exceeded.