Documentation

Web-SDK transport

Address#

Every event is a POST request with a JSON body to

https://<server><pathPrefix>/<urlMark>/t4k.json?dig=<hash>&td_trans=<b|f>

server, pathPrefix (empty by default), and urlMark (band by default) are taken from the configuration. The service name track in the path is replaced with t4k; for other services accessed by request and notify, the path has the form /<urlMark>/<service>.json.

Query string parameters:

Parameter	Description
`dig`	Hash of the request body (cyrb53). Lets the server discard duplicates on retries
`td_trans`	The transport used: `b` — sendBeacon, `f` — fetch

Transport selection#

Events (page, event, automatic ones, notify):

navigator.sendBeacon, if it is supported and allowSendBeacon: true. Beacon does not block the page and is guaranteed to deliver the data on page unload, so page_unload makes it out in time.
If beacon fails (the queue is full or the body is larger than 64 KB) — fetch with keepalive: true and retries after 1 and 5 seconds.

Requests expecting a response (request, the request: true option): always fetch, a response timeout of 10 seconds, the response parsed as JSON. There are no retries, to avoid duplicating side effects on the server.

Library error log: sent to the log service with an image pixel /<urlMark>/log.gif, with the data in the query string. The same pixel is used with the transport_img: true option.

Configuration parameter	Default	Description
`allowSendBeacon`	`true`	Use `sendBeacon` for events
`allowXHR`	`true`	Allow `fetch`
`activateWs`, `wsServer`, `wsPath`	`false`	WebSocket. Reserved, not used

Protocol and HTTPS#

Requests go over https. The only exception is when the page is opened over http and the configuration has allowHTTP: true: then events are also sent over http, which is intended for local development with a server on the same host.

The server must respond to CORS: events are sent with the site's Origin. Beacon and fetch with a text/plain body do not require an OPTIONS preflight request.

Size limits#

The sendBeacon limit is 64 KB per request. Ordinary events fit within a few kilobytes. Session recording batches are cut by trackRecord.maxBatchBytes (40,000 characters by default) so that together with the message envelope they do not exceed the limit.

The easiest way to check delivery is in the Network tab of the developer tools: filter by t4k.json, and each request should have a 200 response. To view message bodies, subscribe to rstat4('onMessage', cb).

The unload and beforeunload events are unreliable in mobile browsers, so page_unload may not arrive. To estimate time on page, use page_visibility and activity.