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. |
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 |
|
Action properties |
|
General properties |
|