ActionScript 3 & Adobe Air API Reference

CalqClient constructors

Initializes a new instance of the Calq client.

Syntax

public function CalqClient( writeKey:String, options:Object = null )

Arguments

writeKey	String	Required	The write key of the project that will receive data from this client.
options	Object	Optional	An object containing additional custom options. Advanced users. These options are documented in the source code only.

Example

var calq:CalqClient = new CalqClient("bfff14a4e0225789be3d9d22c4bb42a1");

CalqClient.getInstance

Gets the singleton shared instance of a CalqClient. This must have been previously created with a new CalqClient(...).

Syntax

public static function getInstance() : CalqClient

Arguments

None

Example

var calq:CalqClient = CalqClient.getInstance();

track

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

Syntax

public function track( action:String, properties:Object ) : void

Arguments

action	String	Required	The name of the action to track. This will be shown in the reporting interface.
properties	Object	Optional	An object containing additional data to associate with this event. Objects can contain sub objects but not arrays.

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

trackSale

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

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

Syntax

public function trackSale( action:String, properties:Object, currency:String, value:Number ) : void

Arguments

action	String	Required	The name of the action to track. This will be shown in the reporting interface.
properties	Object	Optional	An object containing additional data to associate with this event. Objects can contain sub objects but not arrays.
currency	currency	Required	A 3 letter currency code for the currency being used. Can be fictional if using own internal currency or credits system.
value	Number	Required	The value of the sale. Can be negative to indicate a loss or refund.

Example

// Track a sale action worth 9.99 USD
calq.trackSale(
    "Product Sale",
    { "Product Id": 149, "Product Name": "Dinosaur T-Shirt XL" },
    "USD", 
    9.99
);

setGlobalProperty

Sets a new global property that will be automatically included in calls to track and trackSale. Properties will be persisted to the client in the form of a cookie.

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

Syntax

public function setGlobalProperty( name:String, value:* ) : void

Arguments

name	String	Required	The name of the property to set.
value	Object	Required	The value of the property being set. Should be a single value (such as a number or string).

Example

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

Extra

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

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 function identify( actor:String ) : void

Arguments

actor

String

Required

The new id of the user being tracked.

Example

// Identify the current user as 12345678
calq.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

public function clear() : void

Arguments

None

Example

// Generate a new session to track subsequent actions (logout the current user)
calq.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.

Syntax

public function profile( properties:Object ) : void

Arguments

properties

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

Special action properties

The following are special properties that can be sent when tracking actions using track or 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 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.