ActionScript 3 & Adobe Air API Client

Installation (Flash Builder)

Grab the latest release from GitHub and extract it.

To add the library within Flash Builder use the following steps:

  1. Create a /libs folder for your project if you don't yet have one.
  2. Copy the extracted CalqClient.swc to your new libs folder.
  3. Select your project in Flash Builder, right click, and choose Properties...
  4. Select ActionScript Build Path (or Flex Build Path for Flex projects) from the dialog.
  5. Make sure the Library path tab is selected, and choose Add SWC... to add CalqClient.swc.

Alternatively you can download the complete source from GitHub and include it in your project.

Getting a client instance

Create a client instance using new CalqClient("YOUR_WRITE_KEY_HERE") 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. You may need to import io.calq.CalqClient.

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.

// Create a CalqClient instance
var calq:CalqClient = new CalqClient("YOUR_WRITE_KEY_HERE");

After creating a client instance you can access the same CalqClient instance from anywhere in your application using the singleton.

// Get previously created instance
var calq:CalqClient = CalqClient.getInstance();

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
calq.track(
    "Product Review",
    { "Rating": 9.0 }
);

The second parameter is free-form and lets you send additional 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",
    { "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 so they will also persist between sessions.

// Set the "Referral Source" property for all new actions
calq.setGlobalProperty("Referral Source", "Google Campaign");

The Calq ActionScript 3 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
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(
    { "Company": "MegaCorp", "$email": "super_customer1@notarealemail.com" }
);

You must call identify before you can store profile information.