Skip to main content

Client attachment

Track when community members are actively viewing a community.

What is client attachment?​

A client represents a community member who has the community open on one of their devices. When a member opens a community, they become attached; when they navigate away or disconnect, they become detached.

Attachment is a community-level concept, not per-app. When a member attaches to a community, all apps installed in that community receive the same attachment events. This means you're tracking who is currently viewing the community, not specifically who is using your app.

Attachment is also tracked per-device. A member can have multiple devices attached simultaneously, and the member remains attached to the community as long as at least one device has it open.

Desktop behavior​

On desktop, a member is attached to every community they have open in a tab. Switching between community tabs doesn't affect attachment; only closing a tab detaches from that community.

User tray panes (Friends, Direct Messages, Notifications, Profile) are side panels that overlay the current view without affecting which communities are open. Opening these panes or navigating through settings doesn't detach from any community; attachment state only changes when you open or close community tabs.

Mobile behavior​

On mobile, a member remains attached to the community loaded in their home tab, even when navigating to other tabs like Friends, Messages, Notifications, or Profile. Switching between these tabs doesn't affect attachment.

A member detaches from a community when they navigate to a different community (which replaces the current one) or explicitly leave the community. The exception is community voice channels: if a member is in an active voice channel call and navigates to a different community, they remain attached to both until the call ends. This exception does not apply to direct message calls, which have no community context.

Example​

In the example below, the member has two devices. The desktop has two community tabs open (attached to both). The mobile device has Community A loaded in the home tab.

Events​

The SDK emits four events to distinguish between user-level and device-level changes:

EventWhen fired
ClientEvent.UserAttachedMember's first device attaches (member was not present before)
ClientEvent.UserDetachedMember's last device detaches (member is no longer present)
ClientEvent.UserDeviceAttachedMember already attached, another device joins
ClientEvent.UserDeviceDetachedMember has multiple devices, one leaves (member still attached)

Use ClientEvent.UserAttached and ClientEvent.UserDetached when you care about member presence. Use the device events when you need to track individual connections.

How client attachment works​

Understanding the event model helps you choose the right events to subscribe to and predict what your code will receive.

Attachment lifecycle​

When a member opens the community on their first device:

  1. The server sends an attach notification
  2. The SDK emits ClientEvent.UserAttached with a Client object
  3. The member appears in attachedClients.getClients()

When the same member opens the community on a second device:

  1. The server sends another attach notification
  2. The SDK emits ClientEvent.UserDeviceAttached with a ClientContext object
  3. The member's device count increases (same Client, new device)

When one device disconnects but others remain:

  1. The server sends a detach notification
  2. The SDK emits ClientEvent.UserDeviceDetached
  3. The member remains in attachedClients.getClients()

When the last device disconnects:

  1. The server sends a detach notification
  2. The SDK emits ClientEvent.UserDetached
  3. The member is removed from attachedClients.getClients()

When to use client attachment​

Use attachment events when your code needs to respond to member presence:

  • Welcome active members: Show a greeting or trigger an action when a member arrives by subscribing to ClientEvent.UserAttached.
  • Track active participants: Maintain a count of members currently in the community by querying attachedClients.getClients().
  • Clean up on departure: Release resources or save state when a member leaves by subscribing to ClientEvent.UserDetached.
  • Per-device features: Track individual connections for features like collaborative cursors by using the device events.

If you only need to know who can access the community (regardless of whether they're currently viewing it), use CommunityMemberClient instead.