Using Mesh Presence
This article provides a high-level overview of mesh presence data, commonly referred to as presence, including instructions on how to use Ditto's Presence APIs to implement the following end-user functionality for network monitoring and management within your app:
- Setting and updating peer-specific information, such as name, role, and location.
- Viewing information about other peers currently connected in the mesh.
The API methods for mesh presence functionality are accessible through the presence namespace on the root Ditto object:
The presence graph is a data structure representing the current state of the mesh from a specific peer's point of view. Once discovered, peers automatically establish a presence graph within the network by advertising their device presence within the mesh and forming connections with other connected peers.
Integrate the presence graph into your app to enable end-user functionality like network monitoring, management, and transport optimization. For example, once implemented, your end users can input personal information, such as their name, and inspect remote peers connected within the mesh. For more information, see Implementing Presence .
To view your current presence graph:
Once invoked, Ditto returns the following object, allowing you to perform actions like displaying the status of connected peers and managing network resources:
The localPeer is the metadata set by the end user within your app. The remotePeers property provides an array of the other client devices connected to the mesh. (See End-User Defined Metadata)
To monitor and handle changes observed to the presence graph, call the change handler with the updated graph object as follows:
Make sure the observer response object remains in memory during runtime; otherwise, Ditto removes it during the periodic garbage collection process running in the background, resulting in the change handler no longer being triggered.
Once discovered in the mesh, each peer device running Ditto is automatically assigned a peer key.
View your local device's peer key or the peer key identifying a specific remote device:
- To retrieve the peer key for the current peer:
- To retrieve the peer key for a remote peer:
Using the peer-metadata property, you can provide each peer connected within the mesh the ability to set and view information about themselves or read information defined by other peers within the mesh.
The following table provides an overview of key considerations to know before setting peer metadata, as well as Ditto's recommended best practices to ensure optimal mesh performance and avoid potential issues:
Consideration | Best Practice |
Peer metadata syncs across the mesh with each new connection. Therefore, sharing large data over low-bandwidth transports, such as Bluetooth Low Energy (LE), and low-quality connections may slow or disrupt the connection process. | Keep the size of peer metadata to a minimum, especially when syncing over Bluetooth LE or similar low-bandwidth transports. This is because peer metadata exceeding 128 KB, the maximum limit, results in the operation failing and Ditto throwing an error. |
Peer metadata is visible to all peers connected in the mesh. | Include only non-sensitive information in peer metadata. |
To implement functionality providing end users the ability to define metadata, call the setPeerMetadata API method as follows:
Once set, inspect the metadata:
To inspect the metadata set by all other peers in the mesh: