The Javascript API provides a set of functions allowing you to start and control the behaviour of your Surfly sessions.
Once a session has been initialized, you'll be able to use several events in order to check the session status and, if necessary, make modifications depending on this status. More information on how to handle events can be found on the session events page.
SurflySession SurflySession.startLeader( [ iframeSelector ], [ userData ] )
SurflySession SurflySession.startFollower( [ iframeSelector ], [ userData ] )
(not available inside a session)
Initialize a cobrowsing session, open a new iframe/browser tab if necessary, and put the session in support queue.
iframeSelector - (optional) CSS selector string to an iframe element on the current page. If specified, Surfly will open a session in this iframe instead of creating a new one. Note that Surfly cannot open a session in an iframe when 3rd-party cookies are disabled. Also, this is not compatible with the open_in_new_window option.
userData - (optional) a plain object with additional data to be attached to the joining user. This will be visible in subsequent user-related events (viewer_joined, for example), and can be used to track users when they join or leave the session. There are some special fields that have additional effects:
name: this will be displayed as a user name in chatbox inside a sessionemail: this will be used for Gravatar lookupagent_id: will pin the (unpinned) session to a specific Agent. Agent must belong to the company owning the widget key that was used for creating the session.
userData from .startLeader() call will be visible on the Queue page in Surfly dashboard, so you can easily distinguish between the users in the queue.
var session = Surfly.session().startLeader();
// now send `session.followerLink` to someone else
// in another browser
Surfly.session({}, followerLink)
.startFollower(null, {name: 'John Doe', foo: 'bar'});(not available inside a session)
Just initialize a new session (retrieve a leader and follower links from Surfly server) without opening a cobrowsing window. In most cases there is no need to call this function explicitly. It will be called automatically from SurflySession.startLeader() and SurflySession.startFollower().
Note that you still must call SurflySession.startLeader() or SurflySession.startFollower() at some point, to open a cobrowsing window.
If the session is already initialized, SurflySession.create() does nothing.
gracefully ends the current session (as long as the current user has permissions to do so).
If specified, redirectUrl should be a valid URL string. The user will be redirected there after session ends. The exception is when end_of_session_popup_url settings is set. In this case, it will have priority over redirectUrl.
Note that by default a user is redirected to the page that was last visited inside the session.
(read only, not available inside a session)
returns the session settings by which the session was created
set an event handler. Inside the callback function, this will be set to the current SurflySession instance. See Events section for more details.
Returns a reference to the current SurflySession, so chained calls are possible:
Surfly.session().on(/*...*/).on(/*...*/).startLeader();log message to the Audit log (available in Surfly Dashboard after session ends). entry must be a plain string.
This function is useful when you need to establish a communication channel between your JS code on the original page, and its proxified version inside the session.
It is available on both sides, and works in symmetric way: it will trigger a message event on the other side of the channel (see Events section).
message argument must be a plain JSON-serializable object.
targetOriginshould be set to the origin of the expected recipient. If set to "*", message will be delivered regardless of the recipient's origin.
Switch control to the user with specified clientIndex. clientIndex is always 0 for the leader and 1 or more for followers.
See also Control options
Request control from the session leader. This call will be silently ignored if the user is already in control, if she is a leader, or if one of agent_can_request_control and allow_control_switching options is disabled.
(not available inside a session)
Navigate current tab to newUrl
drawingSettings SurflySession.setDrawingSettings( [drawingSettings] )
(not available inside a session)
get or set drawing settings. Example:
session.drawingSettings({mode: 'permanent', color: '#ff0000'});(not available inside a session)
boolean, set to true if the session window is opened
(not available inside a session)
contains a leader link. This is a URL that SurflySession.startLeader() opens. It can only be opened in one browser at a time.
(not available inside a session)
contains a URL that can be used for joining the session. This is a URL that SurflySession.startFollower() opens.
contains a 4-digit PIN code that can be used to join the session. This becomes available only after the session is started (either manually by .startLeader() call, or automatically by Surfly Button).
(not available inside a session)
if a session is opened in an iframe, it contains a reference to its DOM node
(not available inside a session)
reference to the session window (either tab window or contentWindow of the iframe container)