To get realtime updates about changes to presence data, use the Presence API. This article includes instructions on how to implement Ditto’s Presence APIs to enable 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.

Accessing Presence APIs

To access API methods for mesh presence functionality, call the presence namespace on the root Ditto object:


ditto.presence

ditto.presence

ditto.presence;

import { Ditto, Presence } from "@dittolive/ditto";

const presence: Presence = ditto.presence;

ditto.getPresence();

Ditto.Presence

ditto.get_presence()

ditto.presence()

ditto.presence

dit.Presence()

Presence Graph

Once discovered in the mesh, peers automatically establish a presence graph by advertising their device presence within the mesh and forming network connections with other connected peers. The presence graph is a data structure representing the current state of the mesh from a specific peer’s point of view. You can integrate the presence graph into your app to enable end-user functionality like network monitoring, management, and transport optimization. For example, once implemented, end users can input personal information, such as their name, and inspect remote peers connected within the mesh. For more information, see DittoSwiftTools on GitHub.

Accessing Presence Graphs

To view your current presence graph:


let presenceGraph = ditto.presence.graph

val presenceGraph = ditto.presence.graph

const presenceGraph = ditto.presence.graph;

import { Ditto, PresenceGraph } from "@dittolive/ditto";

const presenceGraph: PresenceGraph = ditto.presence.graph;

DittoPresenceGraph graph = ditto.getPresence().getGraph();

var PresenceGraph = Ditto.Presence.Graph

auto presenceGraph = ditto.get_presence().graph()

let presenceGraph = ditto.presence().graph()

final presenceGraph = ditto.presence.graph;

presenceGraph := dit.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:

{
  localPeer: Peer;
  remotePeers: Peer[];
}

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 for more information.)

Observing Presence Graph Modifications

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.

Android: Always close presence observers explicitly. On Android, if a PresenceObserver is garbage collected without being closed first, its finalizer runs on Android’s FinalizerDaemon thread. If the teardown performs any I/O (for example, due to a custom log callback registered via setCustomLogCallback), the finalizer can exceed Android’s hard 10-second timeout, resulting in a java.util.concurrent.TimeoutException crash.To avoid this, always call close() on the observer when it is no longer needed. If you are wrapping the observer in a Kotlin callbackFlow, ensure the awaitClose block calls observer.close() and that the Flow’s coroutine scope is properly cancelled — for example, by collecting within lifecycleScope.

let presenceObserver = ditto.presence.observe { presenceGraph in
// observe changes to the presence graph
}

// presence.observe() returns Flow<DittoPresenceGraph>. Collect it in a
// CoroutineScope (e.g. lifecycleScope) — the upstream observer is cancelled
// with the scope.
lifecycleScope.launch {
    ditto.presence.observe().collect { graph ->
        // observe changes to the presence graph
    }
}

const presenceObserver = ditto.presence.observe((presenceGraph) => {
  // observe changes to the presence graph
});

import { Ditto, PresenceGraph, Observer } from "@dittolive/ditto";

const presenceObserver: Observer = ditto.presence.observe(
  (presenceGraph: PresenceGraph) => {
    // observe changes to the presence graph
  },
);

DittoPresenceObserver presenceObserver = ditto.getPresence().observe(graph -> {
    // observe changes to the presence graph
});

var presenceObserver = Ditto.Presence.Observe((DittoPresenceGraph graph) =>
{
    // Observe changes to the presence graph
});

auto presenceObserver = ditto.get_presence().observe([&](PresenceGraph graph) {
    // observe changes to the presence graph
});

let presence_observer = ditto.presence().register_observer(move |_graph| {
    // observe changes to the presence graph
})?;

final presenceObserver = ditto.presence.observe((graph) {
  // observe changes to the presence graph
});

presenceObserver := dit.Presence().Observe(func(graph *ditto.PresenceGraph) {
    // observe changes to the presence graph
})

Closing Presence Observers

When you no longer need presence updates, close the observer to release resources:

presenceObserver.close()

presenceObserver.close()

presenceObserver.stop();

presenceObserver.stop();

presenceObserver.close();

presenceObserver.Dispose();

presenceObserver.reset();

drop(presence_observer);

presenceObserver.close();

presenceObserver.Close()

In Kotlin v5, presence.observe() returns a Flow<DittoPresenceGraph> instead of a DittoPresenceObserver. When you collect the Flow within a lifecycle-aware scope like lifecycleScope, cancellation and cleanup are automatic — no manual close() is needed.

Peer Key Identifier

Once discovered in the mesh, each peer device running Ditto is automatically assigned a peer key.

Reading Peer Keys

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:


ditto.presence.graph.localPeer.peerKeyString

ditto.presence.graph.localPeer.peerKey

ditto.presence.graph.localPeer.peerKey;

import { Ditto } from "@dittolive/ditto";

const peerKey: string = ditto.presence.graph.localPeer.peerKey;

ditto.getPresence().getGraph().getLocalPeer().getPeerKey()

Ditto.Presence.Graph.LocalPeer.PeerKeyString

ditto.get_presence().graph().local_peer.peer_key_string

ditto.presence().graph().local_peer.peer_key

ditto.presence.graph.localPeer.peerKey

dit.Presence().Graph().LocalPeer.PeerKeyString

To retrieve the peer key for a remote peer:

let remotePeers = presenceGraph.remotePeers
let firstPeer = remotePeers.first!

let peerkeyString = firstPeer.peerKeyString

val remotePeers = ditto.presence.graph.remotePeers
val firstPeer = remotePeers.first()

val peerKey = firstPeer.peerKey

const remotePeers = ditto.presence.graph.remotePeers;
const firstPeer = remotePeers[0];

const peerKey = firstPeer.peerKey;

import { Ditto, Peer } from "@dittolive/ditto";

const remotePeers: Peer[] = ditto.presence.graph.remotePeers;
const firstPeer: Peer = remotePeers[0];

const peerKey: string = firstPeer.peerKey;

List<DittoPeer> remotePeers = ditto.getPresence().getGraph().getRemotePeers();
DittoPeer firstPeer = remotePeers.get(0);

String peerKey = firstPeer.getPeerKey();

DittoPeer remotePeers = ditto.presence.graph.remotePeers
const firstPeer = remotePeers[0]

const peerkeyString = firstPeer.peerKeyString

auto remotePeers = ditto.get_presence().graph().remote_peers;
auto firstPeer = remotePeers[0];

auto peerkeyString = firstPeer.peer_key_string;

let remote_peers = ditto.presence().graph().remote_peers;
let first_peer = &remote_peers[0];

let peer_key = &first_peer.peer_key;

final remotePeers = ditto.presence.graph.remotePeers;
final firstPeer = remotePeers.first;
final peerKey = firstPeer.peerKey;

remotePeers := dit.Presence().Graph().RemotePeers
firstPeer := remotePeers[0]
peerKeyString := firstPeer.PeerKeyString

End-User Defined Peer Metadata

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.

Data added to the peer metadata object is shared during the connection handshake. Large data payloads may impact performance on low-bandwidth connections, such as BLE.

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.

Setting Local Peer Metadata

To implement functionality providing end users the ability to define metadata, call the setPeerMetadata API method as follows:

// Setting via Object
try ditto.presence.setPeerMetadata(["location": "inside"])

// Setting via JSON String
let jsonData = "{location:\"inside\"}".data(using: .utf8)!
try ditto.presence.setPeerMetadataJSONData(jsonData)

// Setting via Object — peerMetadata expects DittoJsonSerializable.ObjectValue,
// so wrap the plain map with .toDittoJson().
ditto.presence.peerMetadata = mapOf("number" to 1).toDittoJson()

// Setting via JSON String
ditto.presence.peerMetadataJsonString =
    """
    {"location":"inside"}
    """.trimIndent()

// Setting via Object
await ditto.presence.setPeerMetadata({ location: "inside" });

// Setting via JSON String
await ditto.presence.setPeerMetadataJSONString('{location:"inside"}');

import { Ditto } from "@dittolive/ditto";

interface PeerMetadata {
  location: string;
}

// Setting via Object
const metadata: PeerMetadata = { location: "inside" };
await ditto.presence.setPeerMetadata(metadata);

// Setting via JSON String
await ditto.presence.setPeerMetadataJSONString('{"location":"inside"}');

import static com.ditto.java.serialization.DittoCborSerializable.buildDictionary;

// Setting via DittoCborSerializable.Dictionary
ditto.getPresence().setPeerMetadata(
    buildDictionary().put("number", 1).build()
);

// Setting via JSON String
ditto.getPresence().setPeerMetadataJsonString("{\"location\":\"inside\"}");

Ditto.Presence.SetPeerMetadata(new Dictionary<string, object>()  { { "location", "inside" } });

nlohmann::json metadata = {
    {"location", "inside"}
};

ditto.get_presence().set_peer_metadata(metadata);

let metadata = json!({
    "location": "inside",
});
ditto.presence().set_peer_metadata(&metadata)?;

// Setting via Object
ditto.presence.peerMetadata = {"location": "inside"};

// Setting via JSON String
ditto.presence.peerMetadataJsonString = '{"location": "inside"}';

// Setting via object
var metadata map[string]any
metadata["location"] = "inside"
dit.Presence().SetPeerMetadata(metadata)

// Setting via JSON string
dit.Presence().SetPeerMetadataJSONData([]byte("{\"location\": \"inside\"}"))

Reading Local Peer Metadata

Once set, inspect the metadata:

// Reading from the presence namespace
ditto.presence.peerMetadata

// Reading from the presence graph
ditto.presence.graph.localPeer.peerMetadata

// Reading from the presence namespace
ditto.presence.peerMetadata

// Reading from the presence graph
ditto.presence.graph.localPeer.peerMetadata

// Reading from the presence namespace
ditto.presence.peerMetadata;

// Reading from the presence graph
ditto.presence.graph.localPeer.peerMetadata;

import { Ditto } from "@dittolive/ditto";

// Reading from the presence namespace
const metadata: Record<string, unknown> = ditto.presence.peerMetadata;

// Reading from the presence graph
const localPeerMetadata: Record<string, unknown> = ditto.presence.graph.localPeer.peerMetadata;

import com.ditto.java.serialization.DittoCborSerializable;

// Reading from the presence namespace
DittoCborSerializable.Dictionary metadata = ditto.getPresence().getPeerMetadata();

// Reading from the presence graph
DittoCborSerializable.Dictionary metadata2 = ditto.getPresence().getGraph().getLocalPeer().getPeerMetadata();

// Reading from the presence namespace
Ditto.Presence.PeerMetadata;

// Reading from the presence graph
Ditto.Presence.Graph.LocalPeer.PeerMetadata;

// Reading from the presence namespace
ditto.get_presence().peer_metadata()

// Reading from the presence graph
ditto.get_presence().graph().local_peer.peer_metadata

// Reading from the presence namespace
ditto.presence().peer_metadata()

// Reading from the presence graph
ditto.presence().graph().local_peer.peer_metadata

// Reading from the presence namespace
ditto.presence.peerMetadata

// Reading from the presence graph
ditto.presence.graph.localPeer.peerMetadata

// Reading from the presence namespace
dit.Presence().GetPeerMetadata()

// Reading from the presence graph
dit.Presence().Graph().LocalPeer.PeerMetadata

Reading Remote Peer Metadata

To inspect the metadata set by all other peers in the mesh:

let remotePeers = ditto.presence.graph.remotePeers
let firstPeer = remotePeers.first!

let peerMetadata = firstPeer.peerMetadata

val remotePeers = ditto.presence.graph.remotePeers
val firstPeer = remotePeers.first()

val peerMetadata = firstPeer.peerMetadata

const remotePeers = ditto.presence.graph.remotePeers;
const firstPeer = remotePeers[0];

const peerMetadata = firstPeer.peerMetadata;

import { Ditto, Peer } from "@dittolive/ditto";

const remotePeers: Peer[] = ditto.presence.graph.remotePeers;
const firstPeer: Peer = remotePeers[0];

const peerMetadata: Record<string, unknown> = firstPeer.peerMetadata;

import com.ditto.java.serialization.DittoCborSerializable;

List<DittoPeer> remotePeers = ditto.getPresence().getGraph().getRemotePeers();
DittoPeer firstPeer = remotePeers.get(0);

DittoCborSerializable.Dictionary metadata = firstPeer.getPeerMetadata();

var RemotePeers = Ditto.Presence.Graph.RemotePeers.PeerMetadata;
var FirstPeer = RemotePeers[0];

var PeerMetadata = FirstPeer.PeerMetadata;

auto remotePeers = ditto.get_presence().graph().remote_peers;
auto firstPeer = remotePeers[0];

auto peerMetadata = firstPeer.peer_metadata();

let remote_peers = ditto.presence().graph().remote_peers;
let first_peer = &remote_peers[0];

let peer_metadata = &first_peer.peer_metadata;

final remotePeers = ditto.presence.graph.remotePeers;
final firstPeer = remotePeers.first;
final metadata = firstPeer.peerMetadata;

remotePeers := dit.Presence().Graph().RemotePeers
firstPeer := remotePeers[0]
metadata := firstPeer.PeerMetadata

Identity Server Metadata

Identity server metadata is application information that is set when the user is authenticating. As part of the authentication process the application developer can provide information about the peer that is added to the user’s peer object and shared with other peers in the mesh. The identity server metadata is signed by the identity server and validated by all peers reading to prevent spoofing of the information.

Setting Identity Server Metadata

The identity server metadata is set during the See End-User Access>Setting Identity Server User Metadata for specifics.

Reading Local Peer Identity Server Metadata

To inspect the identity server metadata of the local peer doing the following:

// Reading from the presence namespace
ditto.presence.identityServiceMetadata

// Reading from the presence graph
ditto.presence.graph.localPeer.identityServiceMetadata

// Reading from the presence graph
ditto.presence.graph.localPeer.identityServiceMetadata

// Reading from the presence graph
ditto.presence.graph.localPeer.identityServiceMetadata;

import { Ditto } from "@dittolive/ditto";

// Reading from the presence graph
const localIdentityMetadata: Record<string, unknown> =
  ditto.presence.graph.localPeer.identityServiceMetadata;

import com.ditto.java.serialization.DittoCborSerializable;

// Reading from the presence namespace
DittoCborSerializable.Dictionary metadata = ditto.getPresence().getIdentityServiceMetadata();

// Reading from the presence graph
DittoCborSerializable.Dictionary metadata2 = ditto.getPresence().getGraph().getLocalPeer().getIdentityServiceMetadata();

// Reading from the presence namespace
Ditto.Presence.IdentityServiceMetadata;

// Reading from the presence graph
Ditto.Presence.Graph.LocalPeer.IdentityServiceMetadata;

// Reading from the presence namespace
ditto.get_presence().identity_service_metadata()

// Reading from the presence graph
ditto.get_presence().graph().local_peer.identity_service_metadata

// Reading from the presence namespace
ditto.presence().identity_service_metadata()

// Reading from the presence graph
ditto.presence().graph().local_peer.identity_service_metadata

ditto.presence.graph.localPeer.identityServiceMetadata
// Coming Soon

dit.Presence().Graph().LocalPeer.IdentityServiceMetadata

Reading Remote Peer Identity Server Metadata

To inspect the identity server metadata set by other peers connected within the mesh:

let remotePeers = ditto.presence.graph.remotePeers
let firstPeer = remotePeers.first!

let peerMetadata = firstPeer.identityServiceMetadata

val remotePeers = ditto.presence.graph.remotePeers
val firstPeer = remotePeers.first()

val peerMetadata = firstPeer.identityServiceMetadata

const remotePeers = ditto.presence.graph.remotePeers;
const firstPeer = remotePeers[0];

const peerMetadata = firstPeer.identityServiceMetadata;

import { Ditto, Peer } from "@dittolive/ditto";

const remotePeers: Peer[] = ditto.presence.graph.remotePeers;
const firstPeer: Peer = remotePeers[0];

const identityServiceMetadata: Record<string, unknown> = firstPeer.identityServiceMetadata;

import com.ditto.java.serialization.DittoCborSerializable;

List<DittoPeer> remotePeers = ditto.getPresence().getGraph().getRemotePeers();
DittoPeer firstPeer = remotePeers.get(0);

DittoCborSerializable.Dictionary metadata = firstPeer.getIdentityServiceMetadata();

var RemotePeers = Ditto.Presence.Graph.RemotePeers.PeerMetadata;
var FirstPeer = RemotePeers[0];

var PeerMetadata = FirstPeer.IdentityServiceMetadata;

auto remotePeers = ditto.get_presence().graph().remote_peers;
auto firstPeer = remotePeers[0];

auto peerMetadata = firstPeer.identity_service_metadata();

let remote_peers = ditto.presence().graph().remote_peers;
let first_peer = &remote_peers[0];

let peer_metadata = &first_peer.identity_service_metadata;

final remotePeers = ditto.presence.graph.remotePeers;
final firstPeer = remotePeers.first;

final peerMetadata = firstPeer.identityServiceMetadata;

remotePeers := dit.Presence().Graph().RemotePeers
firstPeer := remotePeers[0]
peerMetadata := firstPeer.IdentityServiceMetadata

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Using Mesh Presence

Accessing Presence APIs

Presence Graph

Accessing Presence Graphs

Observing Presence Graph Modifications

Closing Presence Observers

Peer Key Identifier

Reading Peer Keys

End-User Defined Peer Metadata

Setting Local Peer Metadata

Reading Local Peer Metadata

Reading Remote Peer Metadata

Identity Server Metadata

Setting Identity Server Metadata

Reading Local Peer Identity Server Metadata

Reading Remote Peer Identity Server Metadata

​Accessing Presence APIs

​Presence Graph

​Accessing Presence Graphs

​Observing Presence Graph Modifications

​Closing Presence Observers

​Peer Key Identifier

​Reading Peer Keys

​End-User Defined Peer Metadata

​Setting Local Peer Metadata

​Reading Local Peer Metadata

​Reading Remote Peer Metadata

​Identity Server Metadata

​Setting Identity Server Metadata

​Reading Local Peer Identity Server Metadata

​Reading Remote Peer Identity Server Metadata

Accessing Presence APIs

Presence Graph

Accessing Presence Graphs

Observing Presence Graph Modifications

Closing Presence Observers

Peer Key Identifier

Reading Peer Keys

End-User Defined Peer Metadata

Setting Local Peer Metadata

Reading Local Peer Metadata

Reading Remote Peer Metadata

Identity Server Metadata

Setting Identity Server Metadata

Reading Local Peer Identity Server Metadata

Reading Remote Peer Identity Server Metadata