Android Client

Installation (Android Studio & Gradle)

The Calq library is available via the Maven central repository. To use Calq's Android library simply add it as a dependency to your build.gradle file.

dependencies {
    /* ... */ 
    compile 'io.calq:library:1.1.+'
}

If Android Studio is unable to find the Calq library then you may also need to ensure that the Maven central repository is included in your build.gradle file.

buildscript {
    repositories {
        mavenCentral()
    }
    /* ... */ 
}

You may need to press the "Sync Project with Gradle Files" toolbar button if Android Studio does not automatically detect your changes.

Installation (Eclipse)

Please see our Eclipse installation instructions if you wish to use Calq under Eclipse.

Configuration

Calq needs a few changes to your application's AndroidManifest.xml file.

Your app must have the INTERNET permission. This is needed so the Calq client can send analytics data back to our servers.

<uses-permission android:name="android.permission.INTERNET" />

You also need to add your Calq write key to the manifest within your application node. You can find your key inside the Calq reporting interface. Remember to replace the text 'YOUR_WRITE_KEY_HERE' with your real key.

<application ...>

    <!-- ... normally <activity ...> and other config here ... -->

    <meta-data
        android:name="io.calq.android.config.writeKey"
        android:value="YOUR_WRITE_KEY_HERE" />
    
</application>

The CalqClient can also take a write key parameter during creation if you want finer control over how your API keys are specified.

Getting a client instance

The easiest way to get an instance of the client is to use the static CalqClient.getOrCreateClient method. This will create a client and load any existing user information or properties that have been previously set. If this is the first time the client has been used then new data is generated.

// Get an instance using previous data if possible
CalqClient calq = CalqClient.getOrCreateClient(context);

You can also create new CalqClient instances directly.

Tracking actions

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

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

The extras Hashtable 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 CalqClient.trackSale. This includes the same parameters as CalqClient.track but includes 2 extra for a currency code and revenue amount.

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

Using the CalqClient.trackSale 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 CalqClient.setGlobalProperty. Global properties are saved to the device so they will also persist between sessions.

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

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

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

// Identify the current user as 12345678
CalqClient calq = CalqClient.getOrCreateClient(context);
calq.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 with an error. 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 CalqClient.clear.

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

Using CalqClient.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 CalqClient.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 CalqClient.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 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);

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

Queuing

The Android Calq client will queue API calls and send them in batches. This minimises battery use when sending data.

When your application exits there may be API calls which have not yet been sent. You can force them to be sent by calling CalqClient.flushQueue. If you do not then your API calls will be sent the next time the application opens. The recommended way of calling CalqClient.flushQueue is in your application's onDestroy method. Example as follows:

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

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.