Users, Sessions and Events explained

Before proceeding, be sure to read our  basic introduction page. An event can represent any web activity or combination of the following; page view, movie start, tweet, download, ajax call, etc.

What about session and users?

At Opentracker we group the events we receive into  sessions and  users. A session is made up of a series of events. A single User can generate multiple sessions. The following diagram illustrates this:

Properties used in the examples

Properties have a  name (we'll color it for reading), and a  value (lovely). Properties give meaning to an event. An example of a property is the  title of this webpage and its value  Opentracker Web API - Users, Sessions and Events. Opentracker uses four properties by default, which are defined as follows:

  • The property si is the site for which to insert data. You must open an account at Opentracker to use the API to its full potential. This property is required.
  • The property uid is the user id of an event. In most cases, a user represents a person who is responsible for one or more sessions. Sessions are grouped together per user, and define that user.
  • The property sid is the session id of an event. A session is a series of events.
  • The property eid is the id of an event. The event id is a UUid string returned by the Opentracker event engine to represent the event.

Raw url events:

We have created multiple libraries/SDKs to make it super easy for you to start sending us the events you are interested in. All these libraries have one thing in common: They send their data by submitting an event to our logging servers via secure https request to:  https://log.opentracker.net You can also take advantage of Opentracker without these libraries by sending us events as raw URLs.
If you want to know more on using raw url events, please read:  Inserting events with a url

Formatting:

The property  name must be comprised of ascii characters, no spaces allowed. The  value can be any  url encoded string.

IDs explained

Id's help organize data into events, sessions and users. You can pass your own session id's and user id's to the event tracking engine, if you do not send id's, we will generate these for you. The mechanism of generating id's is designed to help developers easily group events, sessions & users, and is described underneath:

When we receive a request with only the site property, we generate 3 id's: event id, user id and session id. They will all have the same value. For example: log.opentracker.net/?si=test.opentracker.net&message=Please track me too!
Event id:  eid= 4454d621-e056-4afc-bb5b-063a3f98e4a7 [generated randomly]
Session id:  sid= 4454d621-e056-4afc-bb5b-063a3f98e4a7 [copied]
User id:  uid= 4454d621-e056-4afc-bb5b-063a3f98e4a7 [copied]
When we receive a request with the site property and a session id, that event is added to that session. For example: log.opentracker.net/?si=test.opentracker.net&message=Please track me too!&sid=a session id given
Event id:  eid= 4454d621-e056-4afc-bb5b-063a3f98e4a7 [generated randomly]
Session id:  sid= a session id given [given]
User id:  uid= a session id given [copied]
When we receive a request with the site property and a user id, a new session id is generated for that user and the event is added to new session id. For example: log.opentracker.net/?si=test.opentracker.net&message=Please track me too!&uid=a user id given
Event id:  eid= 4454d621-e056-4afc-bb5b-063a3f98e4a7 [generated randomly]
Session id:  sid= 4454d621-e056-4afc-bb5b-063a3f98e4a7 [copied]
User id:  uid= a user id given [given]

Examples

Example 1: first request to the api.

The most simple event to be tracked can be explained with this example url:
https://log.opentracker.net/?message=Please track me&si=test.opentracker.net
messageis an arbitrary property name. This will trigger the opentracker.net engine to store an property called  message with a value  Please track me and return a string event id ( eid). The example above will trigger the opentracker.net engine to store the following event: 
event {
 unixtimestamp: system current time milliseconds
 message: Please track me
 eid: eid [generated]
 sid: eid [copied]
 uid: eid [copied]
}

session {
 unixtimestamp: system current time milliseconds
 message: Please track me
 eid: eid [generated]
 sid: eid [copied]
 uid: eid [copied]
}

user {
 unixtimestamp: system current time milliseconds
 message: Please track me
 eid: eid [generated]
 sid: eid [copied]
 uid: eid [copied]
}

Notice that an  eid has been generated (this is returned), and that this has propagated to the  sid and  uid. The following is an example of what is returned:  4454d621-e056-4afc-bb5b-063a3f98e4a7.

Example 2: an event added to the api, with a known session id.

This will allow you to add events to an existing session id (clickstream). Illustrated by the following example: https://log.opentracker.net/?message=Please track me too!&sid=1234567890&si=test.opentracker.net 
event {
 unixtimestamp: system current time milliseconds
 message: Please track me too!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

session {
 unixtimestamp: system current time milliseconds
 message: Please track me too!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

user {
 unixtimestamp: system current time milliseconds
 message: Please track me too!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

Notice that an  eid has been generated. Notice that the  sid has been given. Notice that the  uid has been copied from the  sid. The  eid is returned.

Example 3: a second event added to the api, with a known session id.

This is useful if you wish to add several events to the session. The following example illustrates this: https://log.opentracker.net/?message=Please track a seconds event!&sid=1234567890&si=test.opentracker.net 
event {
 unixtimestamp: system current time milliseconds
 message: Please track a seconds event!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

session {
 unixtimestamp: system current time milliseconds
 message: Please track a seconds event!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

user {
 unixtimestamp: system current time milliseconds
 message: Please track a seconds event!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

Notice that an  eid has been generated. Notice that the  sid has been given. Notice that the  uid has been copied from the  sid. The  eid is returned. Notice that the session data (and user data) has now been changed (relative to example 2).

Example 4: a third event added to the api, with a known session id.

This is useful if you wish to add multiple events to the session. The following example illustrates this: https://log.opentracker.net/?privateMessage=Please track a third event!&sid=1234567890&si=test.opentracker.net 
event {
 unixtimestamp: system current time milliseconds
 privateMessage: Please track a third event!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

session {
 unixtimestamp: system current time milliseconds
 message: Please track a seconds event!
 privateMessage: Please track a third event!
 eid: last_eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

user {
 unixtimestamp: system current time milliseconds
 message: Please track a seconds event!
 privateMessage: Please track a seconds event!
 eid: last_eid [generated]
 sid: 1234567890 [given]
 uid: 1234567890 [copied]
}

Notice that an  eid has been generated. Notice that the  sid has been given. Notice that the  uid has been copied from the  sid. The  eid is returned. Notice that the session data (and user data) has now been changed (relative to the example 3).

Example 5: events added to the api, with a known sid and uid.

In most cases simply passing a sid to be tracked is not rich enough from a user behavioral perspective. It is more efficient to link sessions through a uid. The following example illustrates this: https://log.opentracker.net/?message=Please track me too!&sid=1234567890&uid=123456&si=test.opentracker.net 
event {
 unixtimestamp: system current time milliseconds
 message: Please track me too!
 eid: eid [generated]
 sid: 1234567890 [given]
 uid: 123456 [given]
}

Notice that an  eid has been generated. Notice that the  sid has been given. Notice that the  uid has been given. The  eid is returned.

Example 6: a user sending a new signal to the api (which triggers a new session):

https://log.opentracker.net/?message=Im a new session starting!&uid=123456&si=test.opentracker.net 
event {
 unixtimestamp: system current time milliseconds
 message: Im a new session starting!
 eid: eid [generated]
 sid: eid [copied]
 uid: 123456 [given]
}
We have implemented a time-to-live of 60 days. All data outside of this timeframe-window will be lost. Please contact us if you need a larger time window.

Opentracker defines an event as any signal sending an http(s) request to our servers for collection. By implementing this API, it is possible to securely track, monitor, and generate real-time reports for any device connected to the internet.