Note: This documentation is for Opentracker's events engine, please contact us if you think you need an upgrade.
Info Getting started. Please see these three important guides: Basic introduction page and Users, sessions & events explained and Adding properties.

Inserting events with a url

Opentracker enables you to log and store any activity that can send a signal via the internet. These signals are events. By implementing this API, it is possible to securely track, monitor, and generate real-time reports for any device connected to the internet.

There are multiple libraries to make it easy for you to start sending us the events. The libraries send their data by submitting an event to our logging servers with a secure https request to:

Our data collection service has been designed for ease of use, real-time reports, speed, redundancy and fault tolerance. Scaling automatically when high event volume is detected. Real-time reports are generated on the fly. You can send event data with either GET or POST requests.

This chapter describes the basics of sending us events as raw URLs over the https protocol.

Why would I want to insert events using raw URLs?

Sending raw urls is the preferred method if you do not want to pass the data automatically with our libraries/ SDKs. Examples for doing this include testing/ development purposes, the need for flexibility, using/ designing your own libraries, or if you are developing in an environment that does not give access to Opentracker's libraries/ SDK's.


A simple example is to send an event that only contains a title, we'll use the abbreviation ti (which happens to be the reserved property for displaying titles in Opentracker's user interface).
We'll need to pass the site (si) property. This is a mandatory property that needs to be passed with all requests sent. The tells the engine which site/ account the data is being inserted for. You'll need to register an account to use all features.

Just click on the following link, to send an event with the ti property set: track me&si=your-registered-app-name

That's a really simple request! This will add a single event to your dataset with the title ti set to Please track me, and the site credentials si set to your-registered-app-name

Opentracker creates an event id (the hex returned from the request), a session id and an user id both have their title ti property set to Please track me. This helps the developer display particular information related to the id's.

And theres more! you get two counters (a unique id counter and normal counter) with segmentation built in. These features are the building blocks of real-time analytic reporting.

For more details on user id's, session id's, events and how Opentracker helps with this, be sure to read our Users, sessions & events explanation.

Valid naming

The property name has to be ascii characters.
The value can be any url encoded string.

Incremental counts

By sending us events with properties, we keep a running tally of anything that interests you or your business model. Examples might be - games played, dollars spent, points earned, miles traveled, leads closed; This is a very popular feature and can best be explained by an example. You can develop your own raw url's to count all types of properties.

Lets say you are interested in finding the gender distribution of all users to a site. The following link generates the property gender with a value of male for a particular session id sid (randomly picked 0eb12a:

And for the female counterpart:

Use the following api call with the correct credentials to see the result of your click:

In the gender property males or females will be increased by one, each time the event is generated, notice the session column is not increased (its the same sid with every event). With this simple call you can count both events and sessions.

Increasing event counts by more then 1

To increase the count for an event property value by 10, use the following raw url event call (notice the [+10] appended to the value):[+10]

You can view the results in following api call:

Decreasing event counts

To decrease the male event count use following url :[-5]


Think of segments as a way to subdivide your data. You don't always need a segment, it is an extra feature that can give more insights. Three segments are auto-generated: platform, browser, and country.

Use the following links to view them:

Custom Segments

It is possible to include custom segments. Please note the exclamation mark (!) appended to the segment age-group:!=40s&sid=1eb12a!=20s&sid=0eb12a

To view for the result of custom age-group segment:

Notice that the example events with no segment given are not displayed. The developer will need to decide how to deal with data that has no segment defined:

Adding properties to an existing user or session

You can add properties to existing sessions or users, by providing both the uid and sid.

Info To understand users and sessions read Users, sessions & events explained

Using a proxy

By inserting events with a raw url, some properties are automatically filled. This includes the computer or browser (from the requests user agent) and are the country/ region/ city etc., are automatically detected and will overwrite the current values of the user.

Sometimes you don't need this, so to prevent this from happening the proxy property can be set to a value of true.


Return formats & callback

The default return value is always the event id, usually generated by the engine

You override this feature, by passing the format needed of the returned value:
&pix will return a 1x1 pixel
&json will return the event id as json

If a callback parameter is received (which is what jquery will call with its jsonp algorithm, then the returned json is formatted as jsonp, otherwise it is formatted as json see for details , eg callback=jQueryCallback)

We would love to hear your feedback. Please use the facebook comment box below