Methods

Get Started

Methods

`init`

This method is an entry point for LiveSession tracking script used to initialize tracking script on your website. You can find your trackingID in LiveSession -> Settings -> Websites.

Type signture:

function ("init", trackingID: string, options?: InitOptions)

Examples:

import ls from "@livesession/browser";

ls.init("accountID.websiteID");

with options:

Init and track every input

import ls from "@livesession/browser";

ls.init("accountID.websiteID", { keystrokes: true });

options signature:

interface InitOptions {
    // 	Your accountID. Automatically extracted from trackingID
    accountID?: string

    // Your websiteID. Automatically extracted from trackingID
    websiteID?: string

    // Enable global keystroke tracking
    keystrokes?: boolean

    // Set this to the highest-level hostname to record session across different subdomains on your site
    // (e.g. `.your-domain.com`)
    rootHostname?: string
}

More info about keystrokes you can find here.

`identify`

Identify user and custom data to session.

Type signture:

function("identify", data: IdentifyData)

Examples:

import ls from "@livesession/browser";

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

with params:

Identify with parameters

import ls from "@livesession/browser";

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

data signature:

interface IdentifyData {
    // Displays usernames in app
    // Maximum length: 128 characters
    name?: string

    // Displays user email
    // Maximum length: 128 characters
    email?: string

    // Displays user context data
    // Maximum length: 50 items
    params?: {[key: string]: string | number | boolean}
}

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

`track`

This method allows you to send custom event that your users perform along with custom properties.

Type signture:

function("track", event: string, properties?: EventProperties)

Examples:

import ls from "@livesession/browser";

ls.track("User Subscribed");

with properties:

Track with properties

import ls from "@livesession/browser";

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

without properties type suffix (not recommended):

Track with properties without suffix

import ls from "@livesession/browser";

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

properties signature:

// Maximum length: 50 items
type EventProperties = TypedEventProperty | {[key: string]: string | number | boolean}

type TypedEventProperty =
    EventPropertyString |
    EventPropertyInt |
    EventPropertyFloat |
    EventPropertyBool

// String property value, eg. {plan_str: "premium"}
// Maximum length: 256 characters
type EventPropertyString = {[key: `${string}_str`]: string }

// Int property value, eg. {seats_int: 2}
// Maximum length: int max. value
type EventPropertyInt = {[key: `${string}_int`]: number }

// Float property value, eg. {total_float: 255.50}
// Maximum length: float max. value
type EventPropertyFloat = {[key: `${string}_float`]: number }

// Bool property value, eg. {isPatron_bool: true}
type EventPropertyBool = {[key: `${string}_bool`]: boolean }

Example usage

import ls from "@livesession/browser";

ls.track("User Subscribed", {
  plan_str: "premium",
  price: 1,
  total_float: 255.50,
  pro: true
});

`newPageView`

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

Type signture:

function("newPageView", options?: NewPageViewOptions)

Examples:

import ls from "@livesession/browser";

ls.newPageView();

with options:

import ls from "@livesession/browser";

ls.newPageView({ title: "Anonimized page title" });

with conditions:

New page view with conditions

import ls from "@livesession/browser";

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

with base URL:

New page view with base URL

import ls from "@livesession/browser";

ls.newPageView({
  baseURL: "https://example.com",
});

// or

ls.newPageView({
  baseURL: function(base) {
    return base
  },
});

options signature:

interface NewPageViewOptions {
    // Overwrite page title
    title?: string
    // Conditions for starting new pageView
    conditions?: NewPageViewCondition[]
    // Overwrite base URL on player
    baseURL?: string | ((base: string) => string)
}

interface NewPageViewCondition {
  // Use to specify condition based on user interaction (event).
  type: "event";
  // Event type
  name: EventType;
  // Operator for condition
  operator: Operator;
  // Event key
  key: EventKey;
  // Event value
  value: string;
}

type EventType =
  | "MouseClick" // Click on element
  | "RageClick" // Click on element multiple times
  | "ErrorClick" // Click on element with error
  | "Scroll" // Scroll on page
  | "WindowScroll" // Scroll on window
  | "MouseMove" // Move mouse on page
  | "TouchMove"; // Move touch on page

type Operator =
    "start" | // base.indexOf(value) == 0
    "contain" | // base.indexOf(value) > -1
    "end" | // base.indexOf(value) == base.length - value.length
    "eq" | // base == value
    "neq" | // base !== value
    "gt" | // base > value
    "gte" | // base >= value
    "lt" | // base < value
    "lte"; // base <= value

type EventKey =
    // Full DOM path to element
    // e.g `body > #header > .link.add-cart[href="/cart"]`
    "path" |
    // Element identificator
    // `.link.add-cart[href="/cart"]`
    "el" |
    // 	Text content of element
    // e.g `Add to cart`
    "txt";

`setCustomParams`

Set custom properties to session.

Type signture:

function("setCustomParams", options: CustomParamsOptions)

Examples:

import ls from "@livesession/browser";

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

options signature:

type CustomParamsOptions = {
    // Maximum length: 50 items
    params: {[key: string]: string | number | boolean}
}

`getSessionURL`

Get URL to current session.

Type signture:

function("getSessionURL", callback: GetSessionURLCallback)

Examples:

import ls from "@livesession/browser";

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 });
});

callback signature:

type GetSessionURLCallback = (
    // https://app.livesession.io/app/session/{visitor_id}/{session_id}
    url: string,
    isNewSession: boolean
) => void

`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.

Type signture:

function ("setOptions", options: InitOptions)

Exmaples:

import ls from "@livesession/browser";

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

with keystrokes:

Set options with keystrokes

import ls from "@livesession/browser";

ls.setOptions({ keystrokes: true });

`invalidateSession`

Close curent session.

Type signture:

function ("invalidateSession")

Examples:

import ls from "@livesession/browser";

ls.invalidateSession();

`debug`

Set debug logging mode.

Type signture:

function ("debug")

Examples:

import ls from "@livesession/browser";

ls.debug();

`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.

Type signture:

function ("log", logLevel?: LogLevel, data?: object)

Examples:

import ls from "@livesession/browser";

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

logLevel signature:

type LogLevel = "info" | "warn" | "error"

`off`

Turn LiveSession script off.

Type signture:

function ("off")

Examples:

import ls from "@livesession/browser";

ls.off();

Edit page

Recording conditions

Built with

Show your support! Star us on GitHub ⭐️

Star