Sessions keep track of a Profile's Events within a logical period of time - usually when browsing a website or accomplishing some tasks in an application.

Firstparty.js automatically creates and maintains sessions, which should cover most web Analytics use cases. If you're using a JavaScript Source and Firstparty.js to collect Events on your website, you don't need to do anything else to collect and maintain Sessions.

A Session is a simple Data Object that has a known ID as well as a created_at and updated_at timestamps. Sessions make it easier to analyze and group Events sent within a fixed period of time by an individual user.

Creating a Session

Session tracking in Firstparty starts automatically whenever the Event is collected by a JavaScript Source. Firstparty will automatically create a new Session if there is no session_id present on the Event object AND if there is no fsid cookie present in the request sent from firstparty.js, a browser, or any HTTP client.

Sessions are not automatically expired by Firstparty. Firstparty.js will maintain a fsid Session cookie, which will expire after the browser session ends. This behavior may vary from browser to browser, but typically involves ending the session when the browser window is closed.

Attaching Events to a Session

Events will automatically be associated with a Session if, when the Event is collected by Firstparty, one of the following situations are true:

  • The Event payload has a valid Session ID set on the session_id key
  • The HTTP request sending the Event to Firstparty has a valid Session ID set on the fsid cookie

Tracking Sessions Across Sources

You may wish to associate Events sent from different Sources with the same Session. This is useful when you want to associate an Event that is generated from a web server via an HTTP Source with an in-progress Session where a user is generating Events in a browser via Firstparty.js.

Send an existing Session ID as the session_id parameter on the Event, and Firstparty will automatically associate the newly collected Event with the existing Session, even if the Session and Event were created from different sources.