Presence

1. Properties
   1. remotePresences – Object
   2. localPresences – Object
2. Methods
   1. subscribe()
   2. unsubscribe()
   3. create()
   4. destroy()
3. Events
   1. 'receive'
   2. 'error'

Representation of the presence data associated with a given channel.

A Presence instance can be obtained with connection.getPresence() or connection.getDocPresence().

If created with connection.getDocPresence(), this will represent the presence data associated with a given Doc.

Properties

remotePresences – Object

Map of remote presence IDs to their values

localPresences – Object

Map of local presence IDs to their LocalPresence instances

Methods

subscribe()

Subscribe to presence updates from other clients.

presence.subscribe([callback])

Presence can be submitted without subscribing, but remote clients will not be able to re-request presence from an unsubscribed client.

callback – Function

Optional

function(error) { ... }

A callback that will be called once the presence has been subscribed

unsubscribe()

Unsubscribe from presence updates from remote clients.

presence.unsubscribe([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called once the presence has been unsubscribed

create()

Create an instance of LocalPresence, which can be used to represent the client’s presence. Many – or none – such local presences may exist on a Presence instance.

presence.create([presenceId])

presenceId – string

Optional

A unique ID representing the local presence. If omitted, a random ID will be assigned

Depending on use-case, the same client may have multiple presences, so a user or client ID may not be appropriate to use as a presence ID.

Return value

A new LocalPresence instance

destroy()

Clear all LocalPresence instances associated with this Presence, setting them all to have a value of null, and sending the update to remote subscribers.

Also deletes this Presence instance for garbage-collection.

presence.destroy([callback])

callback – Function

Optional

function(error) { ... }

A callback that will be called once the presence has been destroyed

Events

This class extends EventEmitter, and can be used with the normal methods such as on() and off().

'receive'

An update from a remote presence client has been received.

presence.on('receive', function(id, value) { ... });

id – string

The ID of the remote presence

The same client may have multiple presence IDs

value – Object

The presence value. The structure of this object will depend on the type

A null value means the remote client is no longer present in the document (e.g. they disconnected)

'error'

An error has occurred.

presence.on('error', function(error) { ... })

error – ShareDBError

The error that occurred