Developers
API status BlogLog inBack to LiveSession
Getting started
WelcomeAPI Changelog
JavaScript API
IntroductionConfigurationMethodsgetSessionURLinitidentifytrackinvalidateSessionnewPageViewsetOptionssetCustomParamsoffoptOutdebuglogRecording conditionsRate limitsTutorialsPlatforms
REST API (BETA)
IntroductionReference
Webhooks (BETA)
IntroductionEvent Types

Methods

getSessionURL

Get URL to current session.

__ls("getSessionURL", callback)

This method works asynchronusly. callback fires after session is inited.

Return

NameTypeValue
urlstringhttps://app.livesession.io/app/session/{visitor_id}/{session_id}
isNewSessionbool-

Example

__ls("getSessionURL", function(url, isNewSession) {
  // do only if it's a new session
  if (isNewSession) {
    YOUR_API.addSessionURL(url);
  }
});

Integration with other software:

__ls("getSessionURL", function(url, isNewSession) {
  if (isNewSession) drift.track("LiveSession recording URL", { sessionURL: url });
});




init

Init LiveSession tracking stript. You can find your website tracking ID in LiveSession -> Settings -> Websites.

__ls("init", trackingID, options)

Options

See configuration section

Example

__ls("init", "abc.cdef");

With options:

__ls("init", "abc.cdef", { keystrokes: true });




identify

Identify user and custom data to session.

__ls("identify", data)

Validation

NameTypeMaximum lengthDetails
namestring128Displays user names in app
emailstring128Displays user email
paramsobject50 items{key:value} JSON object

Example

__ls("identify", { name: "John Doe", email: "john.doe@example.com" });

With params:

__ls("identify", {
  name: "John Doe",
  email: "john.doe@example.com",
  params: {
    order_id: "123-abc-def",
    plan: "premium",
  },
});

Users' name and email will be the same across all of their sessions.





track

Track method allows you to track custom actions that your users perform along with custom properties.

__ls("track", event, properties)

Important: Currently event properties are only visible in timeline. Next version will allow you to find properties through search filter terms.

Validation

NameTypeMaximum lengthDetails
eventstring256Displays event name in your system
propertiesobject50 items{key:value} JSON object
properties[key]string256Properties key

Properties value validation

NameTypeMaximum lengthDetails
{name}_strstring256String property value, eg. {plan_str: "premium"}
{name}_intintint max. valueInt property value, eg. {seats_int: 2}
{name}_floatfloatfloat max. valueFloat property value, eg. {total_float: 255.50}
{name}_boolbool-Bool property value, eg. {isPatron_bool: true}

Nested properties are not allowed.

Example

__ls("track", "User Subscribed");

With properties:

__ls("track", "User Subscribed", {
  plan_str: "premium",
  seats_int: 1,
  total_float: 255.50,
  isPatron_bool: true
});

You can use properties without type suffix in the property key (this variant is not recommended).

__ls("track", "User Subscribed", {
  plan: "premium",
  seats: 1,
  total: 255.50,
  isPatron: true
});




invalidateSession

Close curent session.

__ls("invalidateSession")

Example

__ls("invalidateSession");




newPageView

Start recording user's visit and add it to session when conditions fulfilled. If session doesn't exists it also create new session.

__ls("newPageView", options)

Options

NameTypeDescription
titlestringOverwrite page title
conditionsarray of objectsConditions for starting new pageView (learn more).
baseURLstring or functionOverwrite base URL on player

Example

__ls("newPageView");

with options:

__ls("newPageView", { title: "Anonimized page title" });

with conditions (learn more):

__ls("newPageView", {
  conditions: [{ type: "event", name: "MouseClick", operator: "contain", key: "path", value: ".add-cart" }],
});

with base URL

__ls("newPageView", {
  baseURL: "https://example.com",
});
// or
__ls("newPageView", {
  baseURL: function(base) {
    return base
  },
});




setOptions

Set options and init LiveSession tracking stript (if it's not inited). You can find your website ID and account ID in LiveSession -> Settings -> Websites.

__ls("setOptions", options)

Options

See configuration section

Example

__ls("setOptions", { accountID: "abc", websiteID: "cdef" });

Set keystrokes:

__ls("setOptions", { keystrokes: true });




setCustomParams

Set custom properties to session.

__ls("setCustomParams", data)

Validation

NameTypeMaximum lengthDetails
dataobject50 items{key:value} JSON object

Example

__ls("setCustomParams", {
  params: {
    order_id: "123-abc-def",
    plan: "premium",
  },
});




off

Turn LiveSession script off.

__ls("off")

Example

__ls("off");




optOut

Set optOut flag. This method sets a __ls_optout cookie on current domain to inform LiveSession script to turn off.

__ls("optOut", value)

Example

__ls("optOut", true);




debug

Set debug logging mode.

__ls("debug", value)

Example

__ls("debug", true);




log

Standard console.log() statements will be recorded by LiveSession, but you have the option to log messages without adding additional noise to your users browser consoles.

__ls("log", logLevel?, data)

Parameters

NameTypeRequiredDescription
logLevelstringfalseThese values are identical to the four methods available to the browser console API. If this parameter is not provided, the 'log' value is used by default
dataobjecttrueA object that will be logged to the LiveSession console

logLevel supported

LevelDescription
"log"Object will be logged as log
"info"Object will be logged as info
"warn"Object will be logged as warn
"error"Object will be logged as error

Example

__ls("log","info","demo info message");
__ls("log","warn","demo warn message");
__ls("log","error",{ id:2, message:"demo error message" });