Session

A session represents a period of continuous user activity, capturing a chronological view of events as a user navigates through your applications over time.

These are the properties common to all sessions:

sessionId

string

A unique identifier for the session in UUID format.

This ID is assigned to the session based on the session expiration policy defined in the application.

userId

string

A unique identifier for the user in UUID format.

This ID is consistent across sessions based on the anonymity scope defined in the application. It is not the same ID as the one you specify when identifying a user.

parentId(optional)

string

The ID of the session that superseded this session.

Usually set when a user is identified, causing the current anonymous session to end and a new identified session to begin.

externalUserId(optional)

string

The external user ID used to identify the user on the application side.

Always null for anonymous users.

window

object

The time window covering the first and last event of the session.

start

integer

The session start timestamp in milliseconds since epoch.

end

integer

The session end timestamp in milliseconds since epoch.

closeTime

integer

The time from which the session is closed for new events.

May be extended if new events arrive before the session is fully closed.

referrer(optional)

string

The URL of the content that linked to the page that started the session.

landingPageUrl(optional)

string

The URL of the page that started the session.

campaign(optional)

Campaign

The marketing campaign that drove the user to the application, based on UTM parameters.

location(optional)

Location

The geographic location detected for the user, such as country, region, and city.

client(optional)

Client

The device and software used to access the application, including device, operating system, and browser.

attributes

object

The attributes associated with the session.

statistics(optional)

object

The aggregated statistics of the session.

pageViews

integer

The total number of page views.

tabViews

integer

The total number of tab views.

orders

integer

The total number of orders placed.

Attributes

In addition to the standard properties, sessions support custom attributes. Use them to track information specific to a single visit, such as the selected plan, referral code, or experiment group.

Restrictions

The following restrictions apply to session attributes:

• Sessions can have up to 10 custom attributes.
• Attribute names must be strings up to 20 characters, starting with a letter or underscore, followed by letters, digits, or underscores.
• Attributes can be primitives (strings, numbers, booleans, null) or collections (lists, maps).
• Strings can be up to 100 characters long.
• Lists can contain up to 10 elements, including primitives, lists of primitives, or maps of primitives.
• Maps can contain up to 10 elements, including primitives, lists of primitives, or maps of primitives.
• Map keys must be strings up to 50 characters long.

Attribute names are case-insensitive, so referralCode and referralcode are treated as the same attribute and will override each other.

Examples

Below are examples of event contexts:

{  "sessionId": "12345678-1234-1234-1234-123456789012",  "userId": "87654321-4321-4321-4321-210987654321",  "parentId": null,  "externalUserId": "user-123",  "window": {    "start": 1440990000000,    "end": 1441000000000  },  "closeTime": 1441001000000,  "referrer": "https://www.google.com/",  "landingPageUrl": "https://www.example.com/winter-sale",  "campaign": {    "name": "winter-sale",    "source": "google",    "medium": "search",    "content": "shoes",    "term": "black shoes"  },  "location": {    "continent": "NA",    "country": "US",    "region": {      "name": "California",      "code": "CA"    },    "city": "Los Angeles",    "source": "IP"  },  "client": {    "device": {      "name": "MacBook Pro",      "vendor": "Apple",      "category": "desktop",      "operatingSystem": {        "name": "iOS",        "version": "10.0.18363"      }    },    "browser": {      "name": "Chrome",      "version": "78.0.3904.108",      "type": "web"    }  },  "attributes": {    "plan": "starter"  },  "statistics": {    "pageViews": 12,    "tabViews": 3,    "orders": 1  }}