PHP Client

Installation (Composer)

The easiest way to use Calq is to include it in your composer.json requirements and running composer update.

"require": {
    ...
    "calq/calq" : "1.*"
}

If you prefer, Composer can actually do this for you using the command composer require calq/calq from your shell.

Installation (Direct)

Although using Composer is the recommend way of using Calq, you can alternatively include the library in your project directly. Grab the latest release from GitHub and extract it.

You will need to include the CalqClient library where you intend to use it. The library requires PHP 5.2 or higher.

require_once("/path/to/Client-PHP/lib/CalqClient.php");

Getting a client instance

The easiest way to get an instance of the client is to use the static CalqClient::fromCurrentRequest method. This will create a client using any cookie already data set for the current web request. If the current user has never been seen before the client will remember them in future by writing a cookie to the response.

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

// Get an instance populated from the current request
$calq = CalqClient::fromCurrentRequest('YOUR_WRITE_KEY_HERE');

The PHP Web client is compatible with the JavaScript client. Any properties set client side using JavaScript will be read by the PHP client when using the CalqClient::fromCurrentRequest method. Likewise any properties set server side will be persisted to a cookie to be read browser side.

You can also create new CalqClient instances directly if you do not want to fill them from a web request.

Tracking actions

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

// Track a new action called 'Product Review' with a custom rating
$calq->track('Product Review', array('Rating' => 9.0));

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

// Track a sale action worth 9.99 USD
$calq->trackSale('Product Sale', array('Product Id' => 149, 'Product Name' => 'Dinosaur T-Shirt XL'), 'USD', 9.99);

Using the 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 setGlobalProperty. Global properties are saved to the client (as a cookie) so they will also persist between sessions.

// Set the 'Referral Source' property for all new actions for this user
$calq->setGlobalProperty('Referral Source', 'Google Campaign');

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

$device_agent The user agent of the browser 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).
$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).

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

// Generate a new session to track subsequent actions (logout the current user)
$calq->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
$calq->profile(array(
    'Company' => 'MegaCorp', 
    '$email' => 'super_customer1@notarealemail.com'
));

You must call identify before you can store profile information.