¬ę Back to help center

Sending events via HTTPS

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

Contents

Sending events via HTTPS

1. Introduction

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

Event tracker integration

2. HTTPS endpoint

Property Value
URL https://track.contiamo.com/v3/[ user | session | event ]
Protocol HTTPS
Method POST
Payload JSON
Content-Type application/json

Authentication

There are two options to authenticate a request:

Option Description
HTTP Header Authorization: Contiamo YOURTOKEN
or Token in JSON body { "_token": "YOURTOKEN", ... }

Gzip encoding

All requests can optionally use gzip encoding.

If there is a Content-Encoding: gzip header in the request, Contiamo decodes the data received as gzipped data.

NOTE: Gzip encoding is only supported for POST requests.

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

POST https://track.contiamo.com/v3/user

A user is a known or unidentified visitor, user or customer who performed actions (created events). Any properties can be attached to a user. The existing user record will be updated if an existing _uid is used.

Property Type Comments
_uid string Unique user identifier. This is a distinct identifier allowing us to identify a user and store events and sessions connected to this user. You will have to choose the type of this unique identifier yourself. Most people use their internal user / customer id, email address or hashes based on one of these properties.
other properties (optional) any type Properties, describing the user. The properties might contain information like gender, email or age.

Example

$ curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Contiamo YOURTOKEN' \
  -d @user.json \
  https://track.contiamo.com/v3/user

Where user.json could contain the following information:

{
  "_uid": "sarah@contiamo.com",
  "first_name": "Sarah",
  "city": "New York"
}

5. Sessions

POST https://track.contiamo.com/v3/session

A session is a period of continous user activity. Any properties can be attached to a session. The existing session record will be updated if an existing _sid is used.

Property Type Comments
_uid (optional) string Unique user identifier. Without a user identifier, the session will be an anonymous session.
_sid string Unique session identifier. This is a distinct identifier allowing us to identify a session. In our javascript tracker the unique session id is generated automatically. When using our HTTP endpoint directly, you'll have to provide a unique value yourself (for example a random uuid). All events with the same session id will be grouped into one session.
other properties (optional) any type Properties, describing the session. The properties might contain information like traffic source, device used or origin country.

Example

$ curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Contiamo YOURTOKEN' \
  -d @session.json \
  https://track.contiamo.com/v3/session

Where session.json could contain the following information:

{
  "_uid": "sarah@contiamo.com",
  "_sid": "550e8400-e29b-11d4-a716-446655440000",
  "device": "tablet"
}

6. Events

POST https://track.contiamo.com/v3/event

Every kind of action performed by a user can be modelled and tracked as an event. Events cannot be updated after they have been created. An event consists of:

Property Type Comments
_uid (optional) string Unique user identifier. Without a user identifier, the event will be an anonymous event.
_sid (optional) string Unique session identifier.
_event_at (optional) string The date at which the event was created (e.g. "2016-07-01T14:58:31"). If not provided, Contiamo will assume the date at which the event was received.
_event string e.g. visit, signup, order - uniquely identifying the type of action the user performed.
other properties (optional) any type Additional properties, describing the event. These properties can be numeric (such as order value and price) or text (such as payment method and product color).

Example

$ curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Contiamo YOURTOKEN' \
  -d @event.json \
  https://track.contiamo.com/v3/event

Where event.json could contain the following information:

{
  "_uid": "sarah@contiamo.com",
  "_sid": "550e8400-e29b-11d4-a716-446655440000",
  "_event": "order",
  "value": 39.99,
  "payment_method": "Credit Card"
}

7. Alternative methods to send data

We strongly recommend to use POST requests with a JSON body to send events. If for some reason this is not possible, there are multiple other options. These work for all three endpoints - Users, Sessions and Events.

GET requests

Option Description
URL parameters .../event?_event=EVENTNAME&property=VALUE...
or base64 endcoded JSON in data param .../event?data=eyJfZXZlbnQiOiJvcmRlciIsInZhbH...

Webhooks: If you would like to use the GET endpoint for Webhooks, you'll find more details in our documentation on using Webhooks.

GET requests with image response

The event tracker will respond with a 1x1 empty gif if ctm.gif is appended to the url:

Example

https://track.contiamo.com/v3/event/ctm.gif

GET requests with script response

The event tracker will respond with an empty javascript file if ctm.js is appended to the url:

Example

https://track.contiamo.com/v3/event/ctm.js