API Reference

Agent SDK API reference

Class: default

The Cobrowse Agent SDK provides a way to interact with the Cobrowse APIs for a variety of use cases. Primarily this library is designed for building a fully white-labeled version of Cobrowse, including custom user interfaces and styling to match your own platform.

The library can be used either from the browser (most common), or a NodeJS environment. Note: not all APIs are available when used in NodeJS.

Hierarchy

  • EventEmitter

    ↳ default

Constructors

constructor

• new default(token?, options?)

Create a new Agent SDK instance. An instance encapsulates information about your API location (if using the self-hosted Cobrowse Enterprise option), and optionally, the authorization token for the agent using the SDK.

Options

api - The url for an Enterprise Cobrowse instance. You do not need to configure this when using our global hosted service.

const token = await myJWTGeneratingFunction()
const cobrowse = new CobrowseAPI(token, { api: 'https://cobrowse.example.com' })

Parameters

Name
Type
Description

token?

string

options?

Record<string, any>

Options for configuring this instance of CobrowseAPI.

Overrides

EventEmitter.constructor

Accessors

api

• get api(): string

The url for the Cobrowse instance.

Returns

string

devices

• get devices(): DevicesAPI

Namespace API for devices. A device in Cobrowse is how a single instance of an app or website is tracked by Cobrowse.

Returns

DevicesAPI

license

• get license(): string

The license key for the Cobrowse account. This uniquely identifies your account within Cobrowse, you may choose to have different license keys for development, test, and production environments.

Returns

string

• set license(license): void

The license key for the Cobrowse account. This uniquely identifies your account within Cobrowse, you may choose to have different license keys for development, test, and production environments.

Parameters

Name
Type

license

string

Returns

void

recordings

• get recordings(): SessionRecordingAPI

Namespace API for recordings. A recording in Cobrowse represents the video and event metadata for a recorded session.

Returns

SessionRecordingAPI

sessions

• get sessions(): SessionsAPI

Namespace API for sessions. A session in Cobrowse represents a single screensharing activity with an agent.

Returns

SessionsAPI

token

• get token(): string

The JWT for API authorization. This token should be securely generated by your backend to authorize use of the Cobrowse APIs.

Returns

string

• set token(token): void

The JWT for API authorization. This token should be securely generated by your backend to authorize use of the Cobrowse APIs.

Parameters

Name
Type

token

string

Returns

void

users

• get users(): UsersAPI

Namespace API for users.

Returns

UsersAPI

Methods

attachContext

▸ attachContext(target): Promise<RemoteContext>

Attach the agent context to an iframe; no JWT is required to use these APIs. The returned context allows you to control certain elements within the iframe hosting the screenshare. For example, you may switch the active agent tool being used, change the session into a "full device" mode session, or just subscribe to changes in the session parameters.

const cobrowse = new CobrowseAPI()
const frameEl = document.getElementById('myIframe')
const ctx = await cobrowse.attachContext(frameEl)

ctx.on('session.updated', (session) => {
  console.log('session was updated', session)
})

Parameters

Name
Type
Description

target

HTMLIFrameElement

An iframe element.

Returns

Promise<RemoteContext>

  • The context returns contains methods specific to controlling the iframe

Interface: Device

Represents a device in Cobrowse. A device in Cobrowse is how a single instance of an app or website is tracked by Cobrowse. Each website within each different browser on a user's machine will be tracked as a separate device. Devices can be listed and filtered by support agents to find a specific user's device. Read more about Identifying your devices to add metadata for filtering.

const cobrowse = new CobrowseAPI(...)
const device = await cobrowse.device.get('some device id here')
device.subscribe()
device.on('updated', d => console.log('device was updated', d))

Events

fires updated - The updated event will be fired when device data changes.

Hierarchy

  • EventEmitter

    ↳ Device

Properties

connectable

• connectable: boolean

Is the device in a state where it can accept a screenshare connection

custom_data

• custom_data: Record<string, any>

The metadata you have associated with this device for discoverability and filtering by agents

device

• device: DeviceInfo

The device metadata exposed by the Cobrowse SDKs

id

• id: string

The unique ID of this device, generated internally by the Cobrowse SDKs. You cannot control this value.

last_active

• last_active: Date

The last time the device was seen

online

• online: boolean

Is the device currently connected to the Cobrowse service

Methods

on

▸ on(event, listener): Device

Listen for events on this device.

Parameters

Name
Type

event

string

listener

(device: Device) => void

Returns

Device

Overrides

EventEmitter.on

subscribe

▸ subscribe(): Promise<void>

Subscribe to changes in this device. Note: this is a browser only method and will not work from a NodeJS environment

Returns

Promise<void>

toJSON

▸ toJSON(): Device

Converts this device instance to a plain object.

Returns

Device

unsubscribe

▸ unsubscribe(): void

Unsubscribe from this device. Note: this is a browser only method and will not work from a NodeJS environment

Returns

void

Interface: DeviceInfo

Properties

app_id

• app_id: string

An identifier for the app being used (e.g. the domain name, or iOS app ID).

app_name

• app_name: string

The name of the app being used by the end user.

device

• device: string

The type of the device being used, e.g. iPhone or Chrome Browser.

device_locale

• device_locale: string

The preferred locale of the user's device.

device_timezone

• device_timezone: string

The timezone of the user's device.

full_device_control

• full_device_control: boolean

(Android only) Indicates whether full device remote control is currently available

os_version

• os_version: string

The OS version of the device.

platform

• platform: string

Which platform is being used, e.g. web, ios, android, windows, macos

sdk_version

• sdk_version: string

The version of the Cobrowse SDK that the device is running

Interface: DevicesAPI

Methods

get

▸ get(id, query?): Promise<Device>

Get a device by ID.

const cobrowse = new CobrowseAPI(...)
const device = await cobrowse.devices.get('some device id here')

Parameters

Name
Type

id

string

query?

Record<string, string>

Returns

Promise<Device>

list

▸ list(query?): Promise<Device[]>

List devices, optionally filter by query parameters.

Supported query parameters:

filter_XXX - where XXX is replaced by your customData field names. e.g. filter_user_id=abc would filter devices with customData = { user_id: 'abc' }

seen_before - only include devices that checked-in with the Cobrowse service before this date

seen_after - only include devices that checked-in with the Cobrowse service after this date

const cobrowse = new CobrowseAPI(...)
const devices = await cobrowse.devices.list({ filter_user_id: 'abcdef' } })

Parameters

Name
Type

query?

Record<string, string>

Returns

Promise<Device[]>

Interface: RemoteContext

Control Cobrowse hosted in an iframe from a parent context. Note: these are browser only methods and will not work from a NodeJS environment

Events

fires session.updated - This event is fired when a property of the session is changed, for example full_device mode is switched on of off.

fires screen.updated - This event is triggered when some metadata about the screen changes, for example the size or orientation. Note, this event is only available via the RemoteContext.

fires error - This event is triggered when an error happens in the iframe (e.g. a license limit is hit)

Hierarchy

  • EventEmitter

    ↳ RemoteContext

Methods

androidBack

▸ androidBack(): Promise<boolean>

Triggers the Android Back button

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.androidBack()

Returns

Promise<boolean>

androidHome

▸ androidHome(): Promise<boolean>

Triggers the Android Home button

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.androidHome()

Returns

Promise<boolean>

clearAnnotations

▸ clearAnnotations(): Promise<boolean>

Clear all agent session annotations from the user's view.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.clearAnnotations()

Returns

Promise<boolean>

destroy

▸ destroy(): void

Destroy this remote context; stops listening for events and detaches from the iframe.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.destroy()

Returns

void

endSession

▸ endSession(): Promise<boolean>

End the current agent session.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.endSession()

Returns

Promise<boolean>

on

▸ on(event, listener): RemoteContext

Listen for events in this context.

Parameters

Name
Type

event

string

listener

(param: any) => void

Returns

RemoteContext

Overrides

EventEmitter.on

setFullDevice

▸ setFullDevice(state): Promise<boolean>

Set the current state of the session full-device mode. A full device session enables the agent to capture all screens of the user's device, not just those inside your app or website. Initiates request or ends full-device mode. The user must approve when switching to full device mode.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setFullDevice('requested')

Parameters

Name
Type

state

"off" | "requested"

Returns

Promise<boolean>

setRemoteControl

▸ setRemoteControl(state): Promise<boolean>

Set the current state of remote control, allowing the agent to request remote control of the user's device. Initiate or end remote control. Note: The agent may not set the remote control state to on directly, they can only set it to requested and the user must approve if required.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setRemoteControl('requested')

Parameters

Name
Type

state

"off" | "requested" | "on" | "rejected"

Returns

Promise<boolean>

setTool

▸ setTool(tool): Promise<boolean>

Set the tool to use in the Agent session.

const cobrowse = new CobrowseAPI()
const ctx = cobrowse.attachContext(document.querySelector('#my-iframe-id'))
ctx.setTool('drawing')

Parameters

Name
Type

tool

"laser" | "drawing" | "control"

Returns

Promise<boolean>

Interface: Session

Represents a session in Cobrowse.

Events

fires updated - fired when a session property changes

fires ended - fired when a session transitions to the ended state

Hierarchy

  • EventEmitter

    ↳ Session

Properties

activated

• activated: Date

The activation timestamp of the session. This is the time the user accepted the session.

agent

• agent: Object

Metadata about the agent that started the session

Type declaration

Name
Type

colour

string

id

string

name

string

code

• code: string

A 6 digit, human friendly code that can be used to initiate a session

created

• created: Date

The date the session was first created (this will usually be before the activated timestamp).

custom_data

• custom_data: Record<string, any>

The metadata you have associated with this session for discoverability and filtering by agents.

device

• device: DeviceInfo

Metadata about the user's device

ended

• ended: Date

The timestamp the session was ended

full_device

• full_device: "off" | "requested" | "on" | "rejected"

The state of the full device mode

id

• id: string

The unique ID for this screenshare session

recorded

• recorded: boolean

Was the session recorded

remote_control

• remote_control: "off" | "requested" | "on" | "rejected"

The state of the remote control authorization for the session

state

• state: "pending" | "authorizing" | "active" | "ended"

The current state of the session. A session will progress through its lifecycle in this order: pending → (authorizing →) active → ended. Only session that require user consent will enter the authorizing state.

updated

• updated: Date

The timestamp of the last update to the session

Methods

end

▸ end(): Promise<void>

Ends this session.

Returns

Promise<void>

isActive

▸ isActive(): boolean

True if the session is active. An active session is one where the user has accepted the screen share if required and frame are streaming to the agent

Returns

boolean

isAuthorizing

▸ isAuthorizing(): boolean

True if the session is authorizing. An authorizing session is one where the user has been presented with a consent dialog but has not yet agreed.

Returns

boolean

isEnded

▸ isEnded(): boolean

True if the session is ended.

Returns

boolean

isPending

▸ isPending(): boolean

True if the session is pending. A pending session is the inital state, waiting for either a device or agent to join

Returns

boolean

on

▸ on(event, listener): Session

Listen for events on this session.

Parameters

Name
Type

event

"ended"

listener

(session: Session) => void

Returns

Session

Overrides

EventEmitter.on

▸ on(event, listener): Session

Parameters

Name
Type

event

"updated"

listener

(session: Session) => void

Returns

Session

Overrides

EventEmitter.on

setFullDevice

▸ setFullDevice(state): Promise<boolean>

Set the current state of the session full-device mode. A full device session enables the agent to capture all screens of the user's device, not just those inside your app or website. Initiates request or ends full-device mode. The user must approve when switching to full device mode.

Parameters

Name
Type

state

"off" | "requested"

Returns

Promise<boolean>

setRemoteControl

▸ setRemoteControl(state): Promise<void>

Set the current state of remote control, allowing the agent to request remote control of the user's device. Initiate or end remote control. Note: The agent may not set the remote control state to on directly, they can only set it to requested and the user must approve if required.

Parameters

Name
Type

state

"off" | "requested" | "on" | "rejected"

Returns

Promise<void>

subscribe

▸ subscribe(): Promise<void>

Subscribe to changes in this session. Note: this is a browser only method and will not work from a NodeJS environment

Returns

Promise<void>

toJSON

▸ toJSON(): Session

Converts this session instance to a plain object.

Returns

Session

unsubscribe

▸ unsubscribe(): void

Unsubscribe from this session. Note: this is a browser only method and will not work from a NodeJS environment

Returns

void

Interface: SessionRecording

Represents a session recording in Cobrowse.

Hierarchy

  • EventEmitter

    ↳ SessionRecording

Properties

id

• id: string

The unique ID for this recording

video

• video: Object

Provides access to the video for this recording

Type declaration

Name
Type

fetch

() => Promise<any>

url

() => Promise<string>

Methods

destroy

▸ destroy(): Promise<any>

Deletes this recording from the server

Returns

Promise<any>

events

▸ events(): Promise<any[]>

Gets the list of events for this recording

Returns

Promise<any[]>

toJSON

▸ toJSON(): SessionRecording

Converts this session instance to a plain object.

Returns

SessionRecording

Interface: SessionRecordingAPI

Methods

destroy

▸ destroy(): Promise<SessionRecording>

Deletes a recording by its ID

Returns

Promise<SessionRecording>

get

▸ get(id, query?): Promise<SessionRecording>

Get a recording by (Session) ID

Parameters

Name
Type

id

string

query?

Record<string, string>

Returns

Promise<SessionRecording>

Interface: SessionsAPI

Methods

create

▸ create(resource?, query?): Promise<Session>

Create a session, optionally passing additional query parameters.

Parameters

Name
Type

resource?

any

query?

Record<string, string>

Returns

Promise<Session>

get

▸ get(id, query?): Promise<Session>

Get a session by ID

Parameters

Name
Type

id

string

query?

Record<string, string>

Returns

Promise<Session>

list

▸ list(query?): Promise<Session[]>

List sessions, optionally filter by query parameters.

Supported query parameters:

filter_XXX - where XXX is replaced by your customData field names. e.g. filter_user_id=abc would filter devices with customData = { user_id: 'abc' }

activated_before - only include sessions that were activated before this date. Useful for paging.

activated_after - only include devices that were activated after this date. Useful for paging.

agent - Administrator may set this to all to list sessions for all agents. Agent roles may only list their own sessions.

state - Filter by session that are in one of the supported states: pending, authorizing, active, ended.

Parameters

Name
Type

query?

Record<string, string>

Returns

Promise<Session[]>

Interface: User

Represents a user in Cobrowse.

Hierarchy

  • EventEmitter

    ↳ User

Properties

id

• id: string

Methods

on

▸ on(event, listener): User

Listen for events on this user.

Parameters

Name
Type

event

"updated"

listener

(user: User) => void

Returns

User

Overrides

EventEmitter.on

toJSON

▸ toJSON(): User

Converts this device instance to a plain object.

Returns

User

Interface: UsersAPI

Methods

get

▸ get(id, query?): Promise<User>

Get a user by ID and optionally filter by query parameters.

Parameters

Name
Type

id

string

query?

Record<string, string>

Returns

Promise<User>

PreviousAgent SDKNextSample code snippets

Last updated