Android Client Reference

CalqClient constructor

Initializes a new instance of the Calq client. Typically you would want to create clients using CalqClient.getOrCreateClient instead.

Syntax

public CalqClient( Context applicationContext, String actor, String writeKey, LocalConfig config )

Arguments

applicationContext Context Required The context of your application.
actor String Required The unique ID of the current actor (user).
writeKey String Required The write key of the project that will receive data from this client.
config LocalConfig Optional A LocalConfig object containing configuration settings for the client. Will use LocalConfig singleton if null is passed.

Example

// Directly create a new CalqClient for user 16571
LocalConfig config = config = LocalConfig.getInstance(applicationContext);
CalqClient client = new CalqClient(context, "16571", "bfff14a4e0225789be3d9d22c4bb42a1", config);

CalqClient.getOrCreateClient

Utility function to get an existing or create a new instance of a CalqClient.

This method will initialize a client and attempt to load existing data from previous sessions. This method will cache the result, and calling it subsequent times will return the same client (unless the writeKey is changed).

This is the recommended way of getting CalqClient instances.

Syntax

public static CalqClient getOrCreateClient( Context applicationContext )
public static CalqClient getOrCreateClient( Context applicationContext, String writeKey )
public static CalqClient getOrCreateClient( Context applicationContext, String writeKey, LocalConfig config )

Arguments

applicationContext Context Required The context of your application.
writeKey String Optional The write key of the project that will receive data from this client. If not specified it will be read from the AndroidManifest.xml.
config LocalConfig Optional A LocalConfig object containing configuration settings for the client. Will use LocalConfig singleton if null is passed.

Example

// Get current / create a new CalqClient instance
CalqClient client = CalqClient.getOrCreateClient(context);

CalqClient.track

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

Syntax

public void track( String action, Map<String, Object> properties )

Arguments

action string Required The name of the action to track. This will be shown in the reporting interface.
properties Map<String, Object> Optional A map containing additional data to associate with this event. Can be null.

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 calq = CalqClient.getOrCreateClient(context);

Map<String, Object> extras = new Hashtable<String, Object>();
extras.put("Rating", 9.0);

calq.track("Product Review", extras);

CalqClient.trackSale

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

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

Syntax

public void trackSale( String action, Map<String, Object> properties, String currency, BigDecimal amount )

Arguments

action string Required The name of the action to track. This will be shown in the reporting interface.
properties Map<String, Object> Optional A map containing additional data to associate with this event. Can be null.
currency String Required A 3 letter currency code for the currency being used. Can be fictional if using own internal currency or credits system.
amount BigDecimal 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 calq = CalqClient.getOrCreateClient(context);

Map<String, Object> extras = new Hashtable<String, Object>();
extras.put("Product Id", 149);
extras.put("Product Name", "Dinosaur T-Shirt XL");

calq.trackSale("Product Sale", extras, "USD", 9.99);

CalqClient.setGlobalProperty

Sets a new global property that will be automatically included in calls to CalqClient.track and CalqClient.trackSale. Properties will be written locally to the device.

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

Syntax

public void setGlobalProperty( String property, Object value )

Arguments

property String Required The name of the property to set.
value Object Required The value of the property being set.

Example

// Set the "Referral Source" property for all new actions for this user
CalqClient calq = CalqClient.getOrCreateClient(context);
calq.setGlobalProperty("Referral Source", "Google Campaign");

Extra

The Calq client will automatically add the following useful global properties with each action if using CalqClient.getOrCreateClient:

$device_agent An agent string for the device including OS version.
$device_mobile Whether the device is a mobile device (for Android this is always true).
$device_os The operating system running on the device (in this case, this will always be "Android").
$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).

CalqClient.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 with an error. Calling identify with the existing Id is allowed and will be silently ignored.

Syntax

public void identify( String actor )

Arguments

actor String Required The new id of the user being tracked.

Example

// Identify the current user as 12345678
CalqClient calq = CalqClient.getOrCreateClient(context);
calq.identify("12345678");

CalqClient.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

public void clear()

Arguments

None

Example

// Generate a new session to track subsequent actions (logout the current user)
CalqClient calq = CalqClient.getOrCreateClient(context);
calq.clear();

CalqClient.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.

Syntax

public void profile( Map<String, Object> properties )

Arguments

properties Map<String, Object> Required The data to associate with this user. Existing values are overwritten if keys have the same name as before.

Example

// Set some persistent profile properties for the current user
CalqClient calq = CalqClient.getOrCreateClient(context);

Map<String, Object> data = new Hashtable<String, Object>();
data.put("Company", "MegaCorp");
data.put("$email", "super_customer1@notarealemail.com");

calq.profile(data);

CalqClient.flushQueue

Requests that any pending API calls are flushed now rather than waiting.

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.

When your application exits there may be API calls which have not yet been sent. You can force them to flush immediately using this method. If you do not then your API calls will be sent the next time the application opens. It is recommended to call flushQueue in your application's onDestroy method. See example below.

Syntax

public void flushQueue()

Arguments

None

Example

@Override
protected void onDestroy() {
    calq.flushQueue();
    super.onDestroy();
}

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.