C# Web Client Reference

CalqClient constructors

Initializes a new instance of the Calq client. Typically web users would want to create clients using FromCurrentRequest instead.

Syntax

public CalqClient( string actor, string writeKey )
public CalqClient( string writeKey )

Arguments

writeKey string Required The write key of the project that will receive data from this client.
actor string Optional The unique ID of the current actor (user). If not specified one will be auto-generated.

Example

// Create a new CalqClient for user 16571
var client = new CalqClient("16571", "bfff14a4e0225789be3d9d22c4bb42a1");

CalqClient.FromCurrentRequest

Creates a new instance of a CalqClient populate from the current request. This will read any cookie data previously set and populate the new client instance accordingly.

This is the recommended way of creating CalqClient instances.

Syntax

public static CalqClient CalqClient.FromCurrentRequest()
public static CalqClient CalqClient.FromCurrentRequest( string writeKey )

Arguments

writeKey string Optional The write key of the project that will receive data from this client. If not specified it will be read from web.config as CalqWriteKey.

Example

// Create a new CalqClient populated from the current request
var client = CalqClient.FromCurrentRequest();

CalqClient.Track

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

Syntax

public void Track( string action, IDictionary<string, object> properties = null )

Arguments

action string Required The name of the action to track. This will be shown in the reporting interface.
properties IDictionary<string, object> Optional A dictionary containing additional data to associate with this event.

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" with a custom rating
var extras = new Dictionary<string, object>();
extras.Add("Rating", 9.0);
client.Track("Product Review", extras);

CalqClient.TrackSale

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

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

Syntax

public void TrackSale( string action, IDictionary<string, object> properties, string currency, decimal amount )

Arguments

action string Required The name of the action to track. This will be shown in the reporting interface.
properties IDictionary<string, object> Optional An object containing additional data to associate with this event. Can be null or empty.
currency string Required A 3 letter currency code for the currency being used. Can be fictional if using own internal currency or credits system.
amount 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
var extras = new Dictionary<string, object>();
extras.Add("Product Id", 149);
extras.Add("Product Name", "Dinosaur T-Shirt XL");
client.TrackSale("Product Review", extras, "USD", 9.99);

CalqClient.SetGlobalProperty

Sets a new global property that will be automatically included in calls to CalqClient.Track and CalqClient.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 void SetGlobalProperty( string property, object value )

Arguments

property string Required The name of the property to set.
value object Required The value of the property being set.

As properties are saved as cookies there is a finite length to the amount of data you can reliably store. This will vary between browsers.

Example

// Set the "Referral Source" property for all new actions for this user
client.SetGlobalProperty("Referral Source", "Google Campaign");

Extra

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

CalqClient.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 void Identify(string actor)

Arguments

actor string Required The new id of the user being tracked.

Example

// Identify the current user as 12345678
client.Identify("12345678");

CalqClient.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 void Clear()

Arguments

None

Example

// Generate a new session to track subsequent actions (logout the current user)
client.Clear();

CalqClient.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 void Profile( IDictionary<string, object> properties )

Arguments

params IDictionary<string, 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
var data = new Dictionary<string, object>();
data.Add("Company", "MegaCorp");
data.Add("$email", "super_customer1@notarealemail.com");
client.Profile(data);

Error handling

Calq raises API errors through a static event handler. When making API calls the client queues them and dispatches them in the background. Failed API calls are replayed later if there is a network failure at the time. Due to this Calq does not throw exceptions as often the original caller would no longer be valid. Instead an error event is raised which applications should listen to.

If no event handler is registered tthen you will not receive any notification that an API error has occured. Client-side exceptions (such as calling CalqClient.Identify twice) will still throw exceptions as normal.

Syntax

public delegate void CalqApiErrorHandler( string errorMessage )
public static event CalqApiErrorHandler OnApiError

Example

protected void Application_Start()
{
    // ...
    
    // Listen to any API errors
    CalqApiDispatcher.OnApiError += CalqApiDispatcher_OnApiError;
}

// Log any Calq errors that occur
void CalqApiDispatcher_OnApiError(string errorMessage)
{
    Log.WarnFormat("[Calq Error] {0}", errorMessage);
}

Special action properties

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