C# Web Client

Installation

Grab a release using your preferred method. You can always download full source code for our clients from GitHub if desired.

Method 1: via NuGet: Run Install-Package Calq.Client.Web.dll from the Package Manager Console.

Method 2: via GitHub: Grab the latest compiled release and add it to your project.

Either way, the client will need your Calq write key to send events. You can find this inside the Calq reporting interface. The easiest way to give Calq your write key is to add it to your web.config inside the appSettings section. Add a new node with your write key called CalqWriteKey.

<configuration>
    <appSettings>
        <add key="CalqWriteKey" value="YOUR_WRITE_KEY_HERE" />
        <!-- ... other entries ... -->
    </appSettings>
</configuration>

The Calq client can also take a write key parameter during creation if you want finer control over how your API keys are specified.

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.

// Get an instance populated from the current request
var client = CalqClient.FromCurrentRequest();

The C# Web client is compatible with the JavaScript client. Any properties set client side using JavaScript will be read by the C# 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 CalqClient.Track. Specify the action and any associated data you wish to record.

// 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);

The dictionary 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 CalqClient.TrackSale. This includes the same parameters as CalqClient.Track but includes 2 extra for a currency code and revenue amount.

// 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 Sale", extras, "USD", 9.99);

Using the CalqClient.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 CalqClient.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
client.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.
$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).

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 CalqClient.Identify.

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

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

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

You must call CalqClient.Identify before you can store profile information.

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.

Applications should add a suitable listener to CalqApiDispatcher.OnApiError.

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);
}