Client API

Every client SDK exposes the same concepts under names that fit the language. This page is the map between them. For full signatures and platform detail, open that platform's page.

Lifecycle#

Concept	Web / React Native	Flutter	Android	iOS
Create	`AppEngine.create({ appId })`	`AppEngine.create(appId:)`	`AppEngine.create(ctx, appId, handler)`	`AppEngine.create(appId:delegate:)`
Join	`joinChannel(token, wsUrl, opts)`	`joinChannel(token:wsUrl:options:)`	`joinChannel(token, wsUrl, opts)`	`joinChannel(token:wsUrl:options:)`
Leave	`leaveChannel()`	`leaveChannel()`	`leaveChannel()`	`leaveChannel()`
Release	`destroy()`	`dispose()`	`destroy()`	`leaveChannel()`

Leave is not release

leaveChannel ends the call but keeps the engine ready to join again. Release it when the screen is gone, or its listeners live as long as your app does.

Media controls#

Action	Method	Notes
Camera on or off	`enableCamera(on)`	No effect for the audience role, which cannot publish.
Microphone on or off	`enableMicrophone(on)`	On by default for hosts and co-hosts.
Screen share	`enableScreenShare(on)`	Web and Flutter.
Switch camera	`switchCamera()`	Web, Android. Flips between front and back where a second camera exists.
Loudspeaker or earpiece	`setSpeakerphone(on)`	Android. A video call is held at arm’s length; the default routing is the earpiece.
Pick a device	`setDevice(kind, deviceId)`	Web and Electron. Cameras, microphones and speakers by id; see listDevices().
Send data	`sendData(payload, reliable)`	See Data messages.

Events#

The names differ by platform idiom — listeners on web, streams in Flutter, a handler on Android, a delegate on iOS — but the set is the same.

Event	Fires when	Payload
`user-joined`	Someone enters the channel, including everyone already present when you join.	The remote user
`user-left`	Someone leaves, and for everyone when you are disconnected.	The remote user
`track-subscribed`	A remote camera or microphone becomes available to render.	The track and user (web), the user (other platforms)
`track-unsubscribed`	A remote track stops.	The track and user
`connection-state-changed`	Connecting, connected, reconnecting or disconnected.	The new state
`active-speakers-changed`	The set of people currently speaking changes.	Array of identities
`data-received`	Another participant sends data.	Bytes and the sender
`gift-received`	A gift is broadcast to the channel.	The gift event
`error`	A media device or publish operation fails.	The error

Render on track-subscribed, not user-joined

A participant is announced before their camera arrives. A UI that builds tiles only on user-joined shows permanently black boxes. This is the single most common integration mistake.

engine.on('user-joined', (user) => addTile(user.uid));
engine.on('track-subscribed', (track, user) => {
  document.getElementById(`tile-${user.uid}`).append(track.attach());
});
engine.on('user-left', (user) => removeTile(user.uid));

Reading state#

Property	Type	Description
`remoteUsers`	array	Everyone currently in the channel, excluding you.
`connectionState`	string / enum	connecting, connected, reconnecting or disconnected.
`localUid`	string	Your own identity, as issued in the token.
`channelName`	string	The channel you are in.

Remote user

Property	Description
`uid`	The identity your server put in their token.
`displayName`	Their name, if you set one in the token `metadata`.
`metadata`	The JSON your server attached to their token, as a string.
`isSpeaking`	Whether they are speaking right now.
`videoTrack`	Their camera, when one is published.

Join options#

{
  role: 'host' | 'cohost' | 'audience',  // must match the token's role
  camera: boolean,                        // publish camera on join
  microphone: boolean                     // publish microphone on join (default true)
}

The role here only decides what the SDK tries to publish. What you are allowed to publish is fixed by the token, so asking for camera: true with an audience token simply publishes nothing.

Web SDK

Full signatures for the browser.

Flutter SDK

Streams, widgets and disposal.

Roles

What each role can actually do.

Errors

Every code and how to fix it.