Sessions in Web-SDK

Events are grouped into sessions (visits) right in the browser: the server receives a ready-made session number, its type, and marks in the sess block of every message.

A session starts with the first event and ends when more than sessionTimeout seconds have passed since the last event (1800 by default, i.e. 30 minutes). The end time is taken to be the time of the last event. A session is initiated by any event, not just a page view: an activity from mouse movement is enough, so the number of interactions is counted more accurately.

The session event#

A session start is also an event. It is sent instead of the event that triggered it, and that event is sent right after. Its data is empty, with the full description in the sess block. It can be sent forcibly with a rstat4('sessionEvent') call.

sess field	Description
num	Visitor's session number
start	Session start time
pageNum, eventNum	Counters of pages and events within the session
type	Source type, see below
engine	Search engine or social network, if recognized
refhost	Referrer host without www
keyword	Search query, if the engine passes it in the referrer
marks, hasMarks	Ad marks from the query string and a flag indicating their presence
marksHash	Hash of the set of marks, used to detect a new campaign

When a session restarts#

1. On timeout: more than sessionTimeout has passed since the last event.
2. On a new significant source. On every page, the SDK determines the source, and the session restarts early if:
   • the source is campaign and the set of ad marks differs from the previous session, or the referrer changed;
   • the source is partner and the set of partner marks differs;
   • the source is organic and the referrer differs from the previous session.
3. Forcibly with a rstat4('sessionEvent') call.

Direct entries, referral, social, and internal transitions do not restart the session: refreshing the page or returning to the site within the timeout continues the current session.

The session state (last event time, source description, counters) is stored in localStorage, so closing the browser or the app does not end the session: returning within sessionTimeout continues it.

Cookie rst4-sstart#

The start time of the current session is duplicated in the <cookiePrefix>sstart cookie (rst4-sstart by default), so that the site's backend can stitch its own requests together with the Rockstat session. The cookie lives sessionTimeout seconds and is extended by each event, i.e. it exists exactly as long as the session is alive in the SDK, and it survives closing the app or the browser.

Session types#

Type	Condition
campaign	There are UTM marks, gclid or yclid, or the referrer is an ad network (googlesyndication.com, googleadservices.com, doubleclick.net)
partner	There are partner marks pid, cid, sub1…sub5
organic	The referrer is a search engine with no ad marks
social	The referrer is a social network or messenger with no ad marks
referral	The referrer is any other site
internal	The referrer is the site itself, and the session ended on timeout
direct	There is no referrer
webview	The query string contains inWebView=1 — opened inside an app

The checks run in this order of priority: campaign marks override referrer-based classification, partner marks override campaign, and webview overrides everything.

Recognized engines: search — google, yandex, mailru, rambler, bing, yahoo, nigma, duckduckgo; social networks and messengers — fb, instagram, tiktok, vk, ok, telegram, twitter, linkedin, youtube. For Yandex, Mail.ru, Rambler, Bing, and Yahoo, the search query is extracted from the referrer into keyword.

Ad marks#

marks contains utm_source, utm_campaign, utm_medium, utm_content, utm_term, as well as gclid, yclid, fbclid together with the has_gclid, has_yclid, has_fbclid flags. fbclid is marked, but it does not force the campaign type: Facebook adds it to all outbound links. Mark values are decoded from URL encoding, and if several are identical the first one is taken.

The last ad campaign is stored for lastCampaignExpires seconds (90 days by default).

Examples#

Ad campaign#

{
  "name": "session",
  "sess": {
    "pageNum": 0, "eventNum": 0, "num": 2,
    "type": "campaign",
    "engine": "google",
    "refhost": "google.com",
    "marks": { "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "feb", "gclid": "Cj0K...", "has_gclid": 1 },
    "hasMarks": true,
    "marksHash": 184467440,
    "start": 1757960000000
  }
}

Organic#

{
  "name": "session",
  "sess": {
    "pageNum": 0, "eventNum": 0, "num": 2,
    "type": "organic",
    "engine": "yandex",
    "refhost": "yandex.ru",
    "keyword": "купить шторку для ванны",
    "marks": {}, "hasMarks": false,
    "start": 1757960000000
  }
}

Social networks#

{
  "name": "session",
  "sess": {
    "pageNum": 0, "eventNum": 0, "num": 2,
    "type": "social",
    "engine": "vk",
    "refhost": "away.vk.com",
    "marks": {}, "hasMarks": false,
    "start": 1757960000000
  }
}

Partner transition#

{
  "name": "session",
  "sess": {
    "pageNum": 0, "eventNum": 0, "num": 2,
    "type": "partner",
    "refhost": "partner-site.ru",
    "marks": { "pid": "778", "sub1": "banner_top" },
    "hasMarks": true,
    "marksHash": 99124587,
    "start": 1757960000000
  }
}

Referral, internal, direct#

{ "name": "session", "sess": { "type": "referral", "refhost": "2gis.ru", "marks": {}, "hasMarks": false, "num": 2 } }

{ "name": "session", "sess": { "type": "internal", "refhost": "example.com", "marks": {}, "hasMarks": false, "num": 3 } }

{ "name": "session", "sess": { "type": "direct", "refhost": "", "marks": {}, "hasMarks": false, "num": 2 } }

Direct entries and apps#

direct usually implies typing the address manually or navigating from bookmarks, but in reality it is almost always transitions from apps: messengers, email clients, QR scanners. The referrer is absent in such transitions. On Android, the source app's package is sometimes visible, in which case a referrer like android-app://org.telegram.messenger is recognized as social with the telegram engine, and android-app://com.google.android.googlequicksearchbox as organic with the google engine.

Differences from Google Analytics and Yandex Metrica#

Rockstat has internal sessions. A visitor came to the site, got distracted, the session ended on timeout, then they came back and continued from the same place. GA would count another visit with the same channel as the previous one. Rockstat will mark it as internal, and the previous session's source will not be counted twice. Metrica has internal visits too, but its initialization algorithm differs.