The SessionStack Developer Hub

Welcome to the SessionStack developer hub. You'll find comprehensive guides and documentation to help you start working with SessionStack as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Identify Users

 

Create user identity

Each time a new session is started by a user who can be identified (your system has logged the user’s personal data) SessionStack allows you to associate him/her with the current session by assigning the user a unique cookie. If the user is anonymous, he’ll automatically get assigned a unique ID and name. As soon as the ‘identify’ command is called, the user will no longer be anonymous and his browsing data will be reconciled with the automatically assigned identifier.

sessionstack('identify', {
    userId: 'USER-ID' // Your app user id
});

More personal details like email or display name can be easily stored.

sessionstack('identify', {
    userId: 'USER-ID',
    email: 'user@example.com',
    displayName: 'John Smith'
});

Along with email/display name, SessionStack lets you save custom data too.

sessionstack('identify', {
    userId: 'USER-ID', // Required
    email: 'user@example.com', // Not required
    displayName: 'John Smith', // Not required

    // Add your own custom user variables here.
    role: 'user',
    pricingPlan: 'free'
});

Note

All custom fields must be key/value pairs.

Note

You should not be using the ‘identify’ command for anonymous or guest users, since you don’t actually know who they are.

All user data can be used for searching specific sessions.

Update user identity

All user identity data (except user ID) can be modified during the session. You need to call the identify command with the value(s) you want to update.

If you have identified user with userId: ‘USER-ID’ and email: 'user@example.com‘, and you want to change the email to 'john@example.com‘, call the identify command with the same userId and the new email

sessionstack('identify', {
    userId: 'USER-ID',
    email: 'john@example.com'
});

If you need to add user identity data during the session, call the ‘identify’ command passing user ID and the new data as key/value pairs.

sessionstack('identify', {
    userId: 'USER-ID',
    displayName: 'John Smith'
});

You can set user email or display name the same way.

Restrictions

All fields must be of type Sstring*. Main fields (userId, email and displayName) are limited up to 128 characters each. Custom fields keys and values should not be longer than 512 characters.

Note

Values longer than the maximum length will be automatically trimmed to fit.

Suggest Edits

Clear Identification Cookie

 

When a given user logs out, you can clear his/her cookie in order to allow different users to share a browser without mixing up their session data. Calling clearUserCookie will clear the cookie of the identified user. The next started session from this browser will be associated with the guest user that used your app before you called identify.

sessionstack('clearUserCookie'); // Clear identified user cookie

If you need each new session to be associated with a new guest user - pass true as the first argument to clearUserCookie.

sessionstack('clearUserCookie', true); // Clear identified user cookie and guest user cookie
Suggest Edits

Start Recording

 

You can start recording a session using the startRecording command.

sessionstack("startRecording");

This command receives a configuration object as a second optional argument.

sessionstack("startRecording", {
    sensitiveInputFields: true
});

The configuration object has the following properties:

Property Name
Type
Description

sensitiveInputFields

Boolean

Automatically make all input fields sensitive

The command can also receive a callback function as an optional argument:

sessionstack("startRecording", function(sessionId) {
    // sessionId -> the ID of the current session.
});

or in combination with the configuration object:

sessionstack("startRecording", {
    sensitiveInputFields: true
}, function(sessionId) {
    // sessionId -> the ID of the current session.
});
Suggest Edits

Stop Recording

 

You can stop recording the current session using the stopRecording command.

sessionstack("stopRecording");
 

You can log specific moments during a user session with appropriate messages. This will allow you to later search and replay them instead of having to watch a whole session in order to find what you need.

sessionstack('log', 'sample message');

This will simply log ‘sample message’.

The provided argument is not limited to a simple String, but can be any JavaScript object. If the provided object inherits from the JavaScript Error type, SessionStack will capture the corresponding stack trace to provide you with more context when you try to figure out what went wrong.

try {
    // code
} catch (e) {
    sessionstack('log', e); // Will capture the stack trace from the provided error.
}

You can pass an optional configuration object:

Property Name
Type
Description

level

String

One of the following:

  • “info” (default if none is specified)
  • “warn”
  • “debug”
  • “error”

as follows:

sessionstack('log', 'sample error message', {
    level: 'error'
});
Suggest Edits

Current Session Id

 

Retrieves the ID of the currently recorded session.

sessionstack("getSessionId", function(sessionId) {
    if (sessionId === null) {
        // No session is being recorded.
    } else {
        // sessionId -> the ID of the currently recorded session.
    }
});

This command receives a callback function as a second argument. The callback function will be invoked with the first parameter being the Id of the currently recorded session. If no session is being recorded, null will be passed instead.

Suggest Edits

Introduction

 

You can manage the tokens related to your account from the API tokens menu.

Suggest Edits

Authentication

 

The SessionStack REST API uses Basic authentication.

The Basic authentication requires you to provide an “Authorization” header with each request beginning with the word “Basic” followed by an interval then your email and the api token in the form:

email:token (base64 encoded)

Note

Because of the basic authentication method, it is advisable to use the API over https to make sure that nobody will steal your credentials.

The sample code below uses the email and API token from the Introduction section. Please replace them with your own credentials.

var email = "user@example.com";
var apiToken = "d4ee759a2c1d4fa5ab789018f1d4b802";
var headers = {
    "Authorization": "Basic " + btoa(email + ":" + apiToken)
};
Suggest Edits

Versioning

 

The versioning of the REST API is specified as part of the URI. For instance, in order to use v1 of the API the request, URI should begin with /v1 followed by a specific endpoint.

https://api.sessionstack.com/v1

With the provided REST APIs, you can perform the following operations:

  • Retrieving all of your sites
  • Retrieve an individual site
Suggest Edits

/websites

List all the sites in your account.

 
get/websites
// List all the sites associated with your account
$.ajax({
    "url": 'https://api.sessionstack.com/v1/websites',
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": 12345,
            "name": "Website 1"
        },
        {
            "id": 12346,
            "name": "Website 2"
        }
    ]
}
 
Suggest Edits

/websites/:website_id

Retrieve information about an individual site.

 
get/websites/website_id
// Retrieve an individual site associated with your account
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "id": 12345,
    "name": "Website 1"
}

Path Params

website_id
string
required

Id of a website, associated with your account.

 
 

With the provided REST APIs, you can perform the following operations:

  • Retrieve and search for sessions associated with your websites
  • Retrieve information about an individual session
  • Deleting information about an individual session
  • Export a session
  • Import a session
  • Add log to a session
Suggest Edits

/websites/:website_id/sessions

Retrieve and search for sessions associated with your websites sorted by their start time.

 
get/websites/website_id/sessions
// Search for sessions which have automatically logged errors.
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions?search=AutoLoggedError&skip=10&limit=1",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "56e6a481abf649ea7e47ee84",
            "start": 1457956056.163,
            "device": {
                "browser_name": "Chrome Mobile",
                "browser_version": "49.0.2623.73",
                "os": "iOS 9.2.1",
                "manufacturer": "Apple"
            },
            "location": {
                "country": "United Kingdom",
                "city": "London",
                "ip": "52.29.121.148"
            },
            "initial_state": {
                "window_width": 1920.0,
                "window_height": 973.0,
                "page_url": "http://www.example.com/"
            },
            "logs": [
                {
                    "timestamp": 1457956476.163,
                    "message": "Uncaught ReferenceError: functionName3 is not defined"
                }
            ]
        }
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

Query Params

limit
string

The maximum number of sessions to return in one response. If not present, all sessions are returned.

skip
string

The number of sessions to be skipped before retrieving the result. If not present, all sessions from the beginning will be returned.

search
string

If present the resulting sessions will match this search query. Read the Sessions Search section for more details.

sort
string

Name of a filed, which will be used for sorting. The allowed values are: start, last_active, length, browser_name, os.

order
string

The sorting order. The allowed values are: asc, desc.

 

When you are searching for sessions, results are being matched by the following properties:

  • Log messages associated with the session
  • Location
    • Country
    • City
    • IP
  • Device
    • Browser name
    • Browser version
    • Layout engine
    • Operating system
    • Manufacturer
Suggest Edits

/websites/:website_id/sessions/:session_id

Retrieve information about an individual session.

 
get/websites/website_id/sessions/session_id
// Search an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "id": "56e6a481abf649ea7e47ee84",
    "start": 1457956056.163,
    "device": {
        "browser_name": "Chrome Mobile",
        "browser_version": "49.0.2623.73",
        "os": "iOS 9.2.1",
        "manufacturer": "Apple"
    },
    "location": {
        "country": "United Kingdom",
        "city": "London",
        "ip": "52.29.121.148"
    },
    "initial_state": {
        "window_width": 1920.0,
        "window_height": 973.0,
        "page_url": "http://www.example.com/"
    },
    "logs": [
        {
            "timestamp": 1457956476.163,
            "message": "Uncaught ReferenceError: functionName3 is not defined"
        }
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, which will be retrieved.

 
Suggest Edits

/websites/:website_id/sessions/:session_id

Deleting an Individual Session.

 
delete/websites/website_id/sessions/session_id
// Delete an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84",
    "type": "DELETE",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, which will be deleted.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/export

Export all data for a session either as JSON (default) or HTML file. The exported session in JSON format will contain only the data for the given session. The exported session in HTML format will also contain an embedded player which will allow replaying the session offline.

 
get/websites/website_id/sessions/session_id/export
curl --request GET \
  --url http://example.com/websites/website_id/sessions/session_id/export
var request = require("request");

var options = { method: 'GET',
  url: 'http://example.com/websites/website_id/sessions/session_id/export' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://example.com/websites/website_id/sessions/session_id/export")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://example.com/websites/website_id/sessions/session_id/export");

xhr.send(data);
import requests

url = "http://example.com/websites/website_id/sessions/session_id/export"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, which will be retrieved.

Query Params

format
string

Optional query parameter for specifying the format of the exported session. The allowed values are: json html.

 
Suggest Edits

/websites/:website_id/sessions/import

Import a session from previously exported session as JSON.

 
post/websites/website_id/sessions/import
// Import a session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/import",
    "type": "POST",
    "data": sessionContents,
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "session_id": "56e6a481abf649ea7e47ee84"
}

Path Params

website_id
string
required

Id of a website, associated with your account, in which the session will be imported.

Body Params

data
json

The contents of the JSON file with the previously exported session.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/logs

Add log to a session at a specified time. Optionally set a log level of the log.

 
get/websites/website_id/sessions/session_id/logs
// Add log to a session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/logs",
    "type": "POST",
    "data": {
        "message": "Some error occurred",
        "timestamp": 1479881245380,
        "level": "error"
    },
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, to which the log will be added.

Body Params

message
string
required

String representing the log message.

client_timestamp
int32

The client-side time in milliseconds at which the log will be added

level
string

Optional parameter for the level of the log. The allowed values are: debug, info, warn, error.

 

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

$.get('http://yoursite.com/test/' + id, function(data) {
    console.log(data);
});

With the provided REST APIs, you can retrieve information about events in your sessions.

Suggest Edits

/websites/:website_id/sessions/:session_id/events/mouse_click

Retrieve information about mouse clicks during the session.

 
get/websites/website_id/sessions/session_id/events/mouse_click
// Search an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/events/mouse_click",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "timestamp": 1457721477.072,
            "left": 702.0,
            "top": 279.0
        },
        {
            "timestamp": 1457721476.715,
            "left": 205.0,
            "top": 179.0
        },

        ...
        // More data
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, the events of which will be retrieved.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/events/mouse_move

Retrieve information about mouse moves during the session.

 
get/websites/website_id/sessions/session_id/events/mouse_move
// Search an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/events/mouse_move",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "timestamp": 1457721468.269,
            "left": 277,
            "top": 407
        },
        {
            "timestamp": 1457721468.370,
            "left": 279,
            "top": 407
        },

        ...
        // More data
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, the events of which will be retrieved.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/events/scroll

Retrieve information about scrolling during the session.

 
get/websites/website_id/sessions/session_id/events/scroll
// Search an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/events/scroll",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "timestamp": 1457966179.832,
            "left": 959,
            "top": 8
        },
        {
            "timestamp": 1457966179.850,
            "left": 971,
            "top": 9
        },

        ...
        // More data
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, the events of which will be retrieved.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/events/window_resize

Retrieve information about browser window resizes during the session.

 
get/websites/website_id/sessions/session_id/events/window_resize
// Search an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/events/window_resize",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "timestamp": 1457966185.622,
            "height": 534,
            "width": 965
        },
        {
             "timestamp": 1457966185.603,
             "height": 530,
             "width": 987
         },

         ...
         // More data
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, the events of which will be retrieved.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/events/location_path_change

 
get/websites/website_id/sessions/session_id/events/location_path_change
// Search an individual session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/events/location_path_change",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "timestamp": 1457966191.549,
            "page_url": "http://example.com/page2"
        },
        {
            "timestamp": 1457966194.296,
            "page_url": "http://example.com/page3"
        },

        ...
        // More data
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, the events of which will be retrieved.

 
Suggest Edits

Access Tokens

 

Creating an access token for a session and putting it as a query parameter named access_token in the URL of the session will give access to the session to anyone who has the URL.

http://app.sessionstack.com/player/#/sessions/5832ce33c93f8e1d665f15e6?access_token=779aef3287e54966b4f15e214761e12f

This would load a session with Id equal to 5832ce33c93f8e1d665f15e6 even if you don't have access to iy.

Suggest Edits

/sessions/:session_id/access_tokens

Creating an access token for a session and putting it as a query parameter named access_token in the URL of the session will give access to the session to anyone who has the URL.

 
post/sessions/session_id/access_tokens
// Create access token for a session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/access_tokens",
    "type": "POST",
    "data": {
        "name": "public"
    },
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "id": "5832ce33c93f8e1d665f15e6",
    "name": "public",
    "access_token": "779aef3287e54966b4f15e214761e12f"
}

Path Params

website_id
string
required

d of a website, associated with your account.

session_id
string
required

Id of a session, for which the access token will be created.

Body Params

name
string

A name describing the access token being created. The name should be unique for the specified session.

 
Suggest Edits

/sessions/:session_id/access_tokens

 
get/sessions/session_id/access_tokens
// Retrieve access tokens for a session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/access_tokens",
    "type": "GET",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "5832ce33c93f8e1d665f15e6",
            "name": "public",
            "access_token": "779aef3287e54966b4f15e214761e12f"
        },
        {
            "id": "5831641bc93f8e731ff5565b",
            "name": "other token",
            "access_token": "819770cf05df434cba31b7dbc9267112"
        },

        ...
        // More data
    ]
}

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, for which the access tokens will be retrieved.

 
Suggest Edits

/websites/:website_id/sessions/:session_id/access_tokens/:access_token_id

Delete an access token for a session to make the session inaccessible through the URL with the given token.

 
delete/websites/website_id/sessions/session_id/access_tokens/access_token_id
// Delete access token for a session
$.ajax({
    "url": "https://api.sessionstack.com/v1/websites/12345/sessions/56e6a481abf649ea7e47ee84/access_tokens/5832ce33c93f8e1d665f15e6",
    "type": "DELETE",
    "headers": {
        "Authorization": "Basic " + btoa("user@example.com:d4ee759a2c1d4fa5ab789018f1d4b802")
    },
    success: function(response) {
        // Code which handles the response...
    }
});
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

website_id
string
required

Id of a website, associated with your account.

session_id
string
required

Id of a session, for which the access token will be deleted.

access_token_id
string
required

Id of the access token to be deleted.