Users, Sessions and Events explained

<div class="alert alert-success version">Before proceeding, be sure to read our <a href="/node/264">basic introduction page.</a></div>

<p>An event can represent any web activity or combination of the following; page view, movie start, tweet, download, ajax call, etc.</p>

<h3>What about session and users?</h3>

<p>At Opentracker we group the events we receive into <strong>sessions</strong> and <strong>users</strong>.</p>

<p>A session is made up of a series of events. A single User can generate multiple sessions.</p>

<p>The following diagram illustrates this:</p>

<p><img src="http://api.opentracker.net/api/inserts/data/events.png" /><br />
<!-- <p>Details on how to read session and user id from opentracker cookies can be found on this page: <a href="reading_cookie.jsp">Reading Opentracker Cookies</a></p> --></p>

<p>&nbsp;</p>

<h3>Properties used in the examples</h3>

<p>&nbsp;</p>

<p>Properties have a <code>name</code> (we&#39;ll color it red for reading), and a <code style="color: blue">value</code> (lovely blue). Properties give meaning to an event. An example of a property is the <code>title</code> of this webpage and its value <code style="color: blue">Opentracker Web API - Users, Sessions and Events</code>.<br />
<br />
Opentracker uses four properties by default, which are defined as follows:</p>

<p>&nbsp;</p>

<ul>
<li>The property <code>si</code> is the site for which to insert data. You must open an <a href="http://www.opentracker.net/signup" target="_blank">account</a> at Opentracker to use the API to its full potential. This property is required. <!-- If the site given is not registered at Opentracker.net, then all data will be deleted after one day. This makes testing the system easy before deciding to register an account. --></li>
<li>The property <code>uid</code> 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.</li>
<li>The property <code>sid</code> is the session id of an event. A <a href="http://en.wikipedia.org/wiki/Session_(computer_science)" target="_blank">session</a> is a series of events.</li>
<li>The property <code>eid</code> is the id of an event. The event id is a UUid string returned by the Opentracker event engine to represent the event.<br />
&nbsp;</li>
</ul>

<p>&nbsp;</p>

<h4>Raw url events:</h4>

<p>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: <code>https://log.opentracker.net</code></p>

<p>You can also take advantage of Opentracker without these libraries by sending us events as raw URLs.</p>

<div class="alert alert-success">If you want to know more on using raw url events, please read: <a href="/node/260">Inserting events with a url</a></div>

<h4>Formatting:</h4>

<p>The property <code>name</code> must be comprised of ascii characters, no spaces allowed.<br />
The <code style="color: blue">value</code> can be any <a href="http://en.wikipedia.org/wiki/Percent-encoding">url encoded</a> string.</p>

<p>&nbsp;</p>

<h3>IDs explained</h3>

<p>&nbsp;</p>

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

<hr />
<p>When we receive a request with only the site property, we generate 3 id&#39;s: event id, user id and session id. They will all have the same value. For example:</p>

<p><code><a href="https://log.opentracker.net/?si=test.opentracker.net&amp;message=Please%... target="_blank">log.opentracker.net/?si=test.opentracker.net&amp;message=Please track me too!</a></code></p>

<p>Event id: <code>eid</code>=<code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code> [generated randomly]<br />
<br />
Session id: <code>sid</code>=<code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code> [copied]<br />
<br />
User id: <code>uid</code>=<code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code> [copied]<br />
&nbsp;</p>

<hr />
<p>When we receive a request with the site property and a session id, that event is added to that session. For example:</p>

<p><code><a href="https://log.opentracker.net/?si=test.opentracker.net&amp;message=Please%... target="_blank">log.opentracker.net/?si=test.opentracker.net&amp;message=Please track me too!&amp;sid=a session id given</a></code></p>

<p>Event id: <code>eid</code>=<code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code> [generated randomly]<br />
<br />
Session id: <code>sid</code>=<code style="color: blue">a session id given</code> [given]<br />
<br />
User id: <code>uid</code>=<code style="color: blue">a session id given</code> [copied]<br />
&nbsp;</p>

<hr />
<p>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:</p>

<p><code><a href="https://log.opentracker.net/?si=test.opentracker.net&amp;message=Please%... target="_blank">log.opentracker.net/?si=test.opentracker.net&amp;message=Please track me too!&amp;uid=a user id given</a></code></p>

<p>Event id: <code>eid</code>=<code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code> [generated randomly]<br />
<br />
Session id: <code>sid</code>=<code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code> [copied]<br />
<br />
User id: <code>uid</code>=<code style="color: blue">a user id given</code> [given]<br />
&nbsp;</p>

<h2>Examples</h2>

<h3>Example 1: first request to the api.</h3>

<p>The most simple event to be tracked can be explained with this example url:</p>

<p><code><a href="https://log.opentracker.net/?message=Please%20track%20me&amp;si=test.ope... target="_blank">https://log.opentracker.net/?message=Please track me&amp;si=test.opentracker.net</a></code></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><code>message</code> is an arbitrary property name.</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>This will trigger the opentracker.net engine to store an property called <code>message</code> with a value <code style="color: blue">Please track me</code> and return a string event id (<code>eid</code>).</p>

<p>The example above will trigger the opentracker.net engine to store the following event:</p>

<pre>
event {
unixtimestamp: system current time milliseconds
message: Please track me
eid: eid [generated]
sid: eid [copied]
uid: eid [copied]
}
</pre>

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

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

<p>Notice that an <code>eid</code> has been generated (this is returned), and that this has propagated to the <code>sid</code> and <code>uid</code>.</p>

<p>The following is an example of what is returned: <code style="color: blue">4454d621-e056-4afc-bb5b-063a3f98e4a7</code>.</p>

<p>&nbsp;</p>

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

<p>This will allow you to add events to an existing session id (clickstream).</p>

<p>Illustrated by the following example:</p>

<p><code><a href="https://log.opentracker.net/?message=Please%20track%20me%20too!&amp;sid=... target="_blank">https://log.opentracker.net/?message=Please track me too!&amp;sid=1234567890&amp;si=test.opentracker.net</a></code></p>

<pre>
event {
unixtimestamp: system current time milliseconds
message: Please track me too!
eid: eid [generated]
sid: 1234567890 [given]
uid: 1234567890 [copied]
}
</pre>

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

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

<p>Notice that an <code>eid</code> has been generated. Notice that the <code>sid</code> has been given. Notice that the <code>uid</code> has been copied from the <code>sid</code>.</p>

<p>The <code>eid</code> is returned.</p>

<p>&nbsp;</p>

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

<p>This is useful if you wish to add several events to the session.</p>

<p>The following example illustrates this:</p>

<p><code><a href="https://log.opentracker.net/?message=Please%20track%20a%20seconds%20even... target="_blank">https://log.opentracker.net/?message=Please track a seconds event!&amp;sid=1234567890&amp;si=test.opentracker.net</a></code></p>

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

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

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

<p>Notice that an <code>eid</code> has been generated. Notice that the <code>sid</code> has been given. Notice that the <code>uid</code> has been copied from the <code>sid</code>.</p>

<p>The <code>eid</code> is returned.</p>

<p>Notice that the session data (and user data) has now been changed (relative to example 2).</p>

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

<p>This is useful if you wish to add multiple events to the session.</p>

<p>The following example illustrates this:</p>

<p><code><a href="https://log.opentracker.net/?privateMessage=Please%20track%20a%20third%2... target="_blank">https://log.opentracker.net/?privateMessage=Please track a third event!&amp;sid=1234567890&amp;si=test.opentracker.net</a></code></p>

<pre>
event {
unixtimestamp: system current time milliseconds
privateMessage: Please track a third event!
eid: eid [generated]
sid: 1234567890 [given]
uid: 1234567890 [copied]
}
</pre>

<pre>
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]
}
</pre>

<pre>
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]
}
</pre>

<p>Notice that an <code>eid</code> has been generated. Notice that the <code>sid</code> has been given. Notice that the <code>uid</code> has been copied from the <code>sid</code>.</p>

<p>The <code>eid</code> is returned.</p>

<p>Notice that the session data (and user data) has now been changed (relative to the example 3).</p>

<p>&nbsp;</p>

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

<p>In most cases simply passing a sid to be tracked is not rich enough from a user behavioral perspective.</p>

<p>It is more efficient to link sessions through a uid.</p>

<p>The following example illustrates this:</p>

<p><code><a href="https://log.opentracker.net/?message=Please%20track%20me%20too!&amp;sid=... target="_blank">https://log.opentracker.net/?message=Please track me too!&amp;sid=1234567890&amp;uid=123456&amp;si=test.opentracker.net</a></code></p>

<pre>
event {
unixtimestamp: system current time milliseconds
message: Please track me too!
eid: eid [generated]
sid: 1234567890 [given]
uid: 123456 [given]
}
</pre>

<p>Notice that an <code>eid</code> has been generated. Notice that the <code>sid</code> has been given. Notice that the <code>uid</code> has been given.</p>

<p>The <code>eid</code> is returned.</p>

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

<p><code><a href="https://log.opentracker.net/?message=Im%20a%20new%20session%20starting!&... target="_blank">https://log.opentracker.net/?message=Im a new session starting!&amp;uid=123456&amp;si=test.opentracker.net</a></code></p>

<pre>
event {
unixtimestamp: system current time milliseconds
message: Im a new session starting!
eid: eid [generated]
sid: eid [copied]
uid: 123456 [given]
}
</pre>

<div class="alert alert-info">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.</div>

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.