Web-SDK JavaScript API

The entire API is a single global function, rstat4. The first argument is the method name, the rest are its parameters. Before the library loads, calls are queued and return 0; after it loads, they are executed immediately and return the method's result.

rstat4('<method>', ...args)

Sending data#

page — page view#

rstat4('page', [data], [options])

Sends a page event with performance data in the perf block and resets the tracker counters (maximum scroll depth, etc.). The library does not send it on its own: call it after configure, and in an SPA — on every route change.

Parameter	Type	Default	Description
data	Object	{}	Any page data: type, category, product identifier
options	Object	{}	Delivery options

rstat4('page', { type: 'content', name: 'Контакты' });
rstat4('page', { type: 'category', id: '2342344', name: 'Товары для дома' });

event — custom event#

rstat4('event', name, [data], [options])

Parameter	Type	Default	Description
name	String		Event name, describes what happened
data	Object	{}	Arbitrary event data
options	Object	{}	Delivery options

rstat4('event', 'add_to_cart', {
  sku: 'A-100',
  name: 'Шторка для ванны',
  category: 'Товары для дома',
  qty: 2
});

rstat4('event', 'popup_displayed', { type: 'discount', offer: 'personal_24h' });

identify — user identification#

rstat4('identify', userId, [traits])
rstat4('identify', traits)

Parameter	Type	Description
userId	String, Number	User identifier from your database
traits	Object	User characteristics: plan, segment, email hash, etc.

userId and the traits are saved in browser storage and added to the user block of every subsequent message: user.id plus the trait keys. No separate event is sent to the server, so it makes sense to call identify before page or right after login.

rstat4('identify', 42, { plan: 'pro', email_hash: 'c8d1...' });
rstat4('identify', { segment: 'vip' }); // traits only

request — request to a service with a response#

rstat4('request', service, name, [data]) → Promise<response>

Parameter	Type	Description
service	String	Name of the platform service
name	String	Service method
data	Object	Parameters passed to the service

Always goes through fetch, and the response is parsed as JSON. The promise is rejected on a network error or a 10-second timeout. There are no retries, so as not to duplicate side effects on the server.

const offer = await rstat4('request', 'offers', 'get', { slot: 'hero' });

notify — notify a service without a response#

rstat4('notify', service, name, [data])

Same as request, but without waiting for a response: it is sent via sendBeacon.

sessionEvent — forced session event#

rstat4('sessionEvent')

Sends a session event with the current session data.

Delivery options#

The third argument of event and page is a delivery options object:

Option	Description
request: true	Send via fetch and return a promise with the server response
transport_img: true	Send via a pixel image
outbound: true	Mark of a click on an external link, set automatically in link_click

Session recording#

record#

rstat4('record', [options])

Starts session recording. The rrweb-record.js bundle is loaded from the tracker server only at this moment. options override trackRecord from the configuration. A repeated call during an active recording is ignored, and a call made before initialization is deferred until it completes.

stopRecord#

rstat4('stopRecord')
rstat4('record', false)

Stops the recording and sends the rest of the buffer. After stopping, recording can be started again.

rstat4('record');                         // start
rstat4('record', { recordCanvas: true }); // start with options
rstat4('stopRecord');                     // stop

Masking settings are described in the trackRecord configuration.

Callbacks#

onReady — library initialized#

rstat4('onReady', function () {
  const uid = rstat4('getUid');
  dataLayer.push({ rstatUid: uid });
});

If the library is already initialized, the callback runs immediately.

onEvent — every event before it is sent#

rstat4('onEvent', function (name, data, options) { /* ... */ })

Argument	Description
name	Event name
data	Event data passed at creation time
options	Delivery options

Example: an incorrectly filled delivery form opens a chat with support.

rstat4('onEvent', function (name, data) {
  if (name === 'field_invalid' && data.fname === 'delivery') {
    setTimeout(function () {
      SomeChat.open({ info: 'Проблемы с заполнением формы доставки' });
      rstat4('event', 'chat_opened', { reason: 'invalid_delivery_form' });
    }, 5000);
  }
});

onMessage — the full message exactly as it is sent to the server#

rstat4('onMessage', function (msg) {
  console.log(msg.name, msg.sess, msg.page);
})

msg contains all the blocks from the event structure. Suitable for debugging and your own integrations.

onInternalEvent — internal library events#

rstat4('onInternalEvent', function (name, data) { /* ... */ })

Names: dom_loaded, before_unload, visibility_change.

onServerMessage — messages from the server#

rstat4('onServerMessage', function (name, data) { /* ... */ })

Utilities#

Method	Description
rstat4('getUid')	The visitor's current uid. Before initialization — a warning and undefined, use it inside onReady
rstat4('getSessNum')	Number of the visitor's current session
rstat4('getLibInfo')	{ id: 'web-sdk', v, sv, st } — library version as a number (5.2.1 → 5002001), snippet version, start time
rstat4('isInitialized')	true after initialization
rstat4('buildProjectId', domain)	[domain, projectId] — the normalized domain and its hash, used as the default projectId
rstat4('setCustomConfig', config)	Save personal configuration overrides to browser storage. Applied on subsequent loads
rstat4('enableLogger')	Verbose log in the console. Before the library loads, it can be enabled via window._rst4_logger = true
rstat4('set', name, obj)	Put an object into the library registry

rstat4('buildProjectId', 'www.shop.example.com')
// → ['example.com', 1617632140]

rstat4('getLibInfo')
// → { id: 'web-sdk', v: 5002001, sv: 5002001, st: 1757960000000 }