¬ę Back to help center

Sending events using Javascript

This guide explains how to send events from your app or website in Javascript.

Contents

Sending events using Javascript

1. Introduction

After installing an event tracker, you can start sending events to Contiamo immediately. You will find customized code snippets in the Integration tab of your even tracker.

2. Javascript snippet

If you want to track events from your website or web-app, our Javascript tracker gets you started within minutes. Simply add the Javascript snippet to your page, ideally inside the <head> section.

Note: In order to get code customized for your tracker, please visit the Integration tab of your event tracker in the Contiamo Manage section.

Event tracker integration

3. Recap: Understanding Events, Users and Sessions

The Contiamo tracker allows you to store information on three different levels. Events belong to Sessions which in turn belong to Users:

Event tracker entities

4. The Tracker JS API

4.1. Identifying a user

contiamo.identify(uid)

To identify a user, simply tell us their distinct identifier (uid.) Once you have identified the user, we will keep the uid around in a cookie and automatically link future activities to the user. It is however good practice to put an identify call into every page you track before sending an event (if you can identify the user at that point).

contiamo.identify("sarah@contiamo.com");

4.2. Storing user information

contiamo.user([uid], properties)

You can add and modify information stored on a user's profile:

contiamo.user({ "first_name": "Sarah", "city": "New York" });

If you haven't identified the user before, you will need to also send their distinct identifier (uid):

contiamo.user("sarah@contiamo.com", { "first_name": "Sarah", "city": "New York" });

4.3. Storing session information

contiamo.session(properties)

You can manually add and modify information stored on the current session of a user. Information that provides context for all events recorded during the session should be stored here. Our tracker will automatically handle initialization and persistance of new sessions. We start a new session after 30 minutes of inactivity (no new events).

contiamo.session({ "device": "tablet" });

Special session properties

Contiamo will try to auto-populate the following properties on a session. You can provide your own values by sending them in the session properties.

Any utm tags in the URL at the beginning of the session are automatically stored on the session:

Additional information about the user agent is stored:

4.4. Tracking events

contiamo.event(event, properties)

Tracking an event is as simple as calling:

contiamo.event("order", { "value": 39.99, "payment_method": "Credit Card" });

Special event properties

Contiamo will try to auto-populate the following properties on an event. You can provide your own values by sending them in the session properties.

The current page path is automatically added to every event:

5. Putting it all together (example)

Let's assume you have a standard website on which you want to track events. Tracking is performed in three steps:

<head>
  <!-- 1) Contiamo snippet -->
  <!-- Start Contiamo -->
  <script type="text/javascript">(...)</script>
  <!-- End Contiamo -->
</head>
<body>
  <!-- 2) Identify the user -->
  <script type="text/javascript">
    contiamo.user("sarah@contiamo.com", { "first_name": "Sarah", "city": "New York" });
  </script>

  <!-- Optionally store additional information on the session -->
  <script type="text/javascript">
    contiamo.session({ "device": "tablet" });
  </script>

  <!-- 3) Track an event -->
  <script type="text/javascript">
    contiamo.event("order", { "value": 39.99, "payment_method": "Credit Card" });
  </script>
</body>

6. Advanced functionality

6.1. Setting a custom session IDs

Instead of an auto-generated session ID, a custom session ID can be provided (for example to cross-reference this session with a session in another system):

  contiamo.setSid('custom_identifier_for_this_session');

6.2. Callback after initialization and additional functionality

The tracker offers a whenReady method that executes a callback when the tracker is ready. All contiamo.xyz methods mentioned above can however be called before the tracker has been initialized and will simply be queued in order until the tracker is ready.

contiamo.whenReady(function() {
  // contiamo tracker is now initialized
});

After the tracker has been initialized, the following additional methods are available:

6.2.1. getSid

Returns the session identifier for the current session.

contiamo.whenReady(function() {
  contiamo.getSid();
});

6.2.2. getUid

Returns the uid for the current user.

contiamo.whenReady(function() {
  contiamo.getUid();
});

6.2.3. reset

Resets the tracker, removes current session id and uid

contiamo.whenReady(function() {
  contiamo.reset();
});