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.
An event can represent any web activity or combination of the following; page view, movie start, tweet, download, ajax call, etc.
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 have a name (we'll color it red for reading), and a value (lovely blue).
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:
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.
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.sid is the session id of an event. A session is a series of events.eid is the id of an event. The event id is a UUid string returned by the Opentracker event engine to
represent the event.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.
The property name must be comprised of ascii characters, no spaces allowed.
The value can be any url encoded
string.
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]
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.netmessage is 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.
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.
This is useful if you wish to add several events to the session.
The following example illustrates this:
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).
This is useful if you wish to add multiple events to the session.
The following example illustrates this:
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).
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:
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.
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]
}