Cobrowse.io Docs
HomeProductDemoPricing
Search
⌃K
Links
Comment on page

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
The JWT for API authorization.
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?