Identify Users
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.
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.
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.
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:
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.
});Stop Recording
You can stop recording the current session using the stopRecording command.
sessionstack("stopRecording");Logging
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:
level
String
One of the following:
- “info” (default if none is specified)
- “warn”
- “debug”
- “error”
as follows:
sessionstack('log', 'sample error message', {
level: 'error'
});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.
Introduction
You can manage the tokens related to your account from the API tokens menu.
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)
};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
Sites
With the provided REST APIs, you can perform the following operations:
- Retrieving all of your sites
- Retrieve an individual site
Sessions
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
/websites/:website_id/sessions
Retrieve and search for sessions associated with your websites sorted by their start time.
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
/websites/:website_id/sessions/:session_id
Retrieve information about an individual session.
/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.
/websites/:website_id/sessions/import
Import a session from previously exported session as JSON.
/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('http://yoursite.com/test/' + id, function(data) {
console.log(data);
});Events
With the provided REST APIs, you can retrieve information about events in your sessions.
/websites/:website_id/sessions/:session_id/events/mouse_click
Retrieve information about mouse clicks during the session.
/websites/:website_id/sessions/:session_id/events/mouse_move
Retrieve information about mouse moves during the session.
/websites/:website_id/sessions/:session_id/events/scroll
Retrieve information about scrolling during the session.
/websites/:website_id/sessions/:session_id/events/window_resize
Retrieve information about browser window resizes during the session.
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.
/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.
/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.