Documentation Index
Fetch the complete documentation index at: https://docs.spatialreal.ai/llms.txt
Use this file to discover all available pages before exploring further.
AvatarKit client SDKs expose event callbacks so your app can react to connection changes, conversation state transitions, and errors in real time.
Event Callbacks
| Callback | Payload | Location | Description |
|---|
onFirstRendering | — | AvatarView | Fires once when the avatar renders its first frame. |
onConnectionState | ConnectionState | AvatarController | Fires when the WebSocket connection state changes. SDK mode only. |
onConversationState | ConversationState | AvatarController | Fires when the avatar’s playback state changes. |
onError | AvatarError | AvatarController | Fires when a runtime error occurs. |
ConnectionState
Indicates the current state of the WebSocket connection to the driving service.
| State | Description |
|---|
disconnected | No active connection. |
connecting | Connection is being established. |
connected | Connection is active and ready. |
failed | Connection failed. On iOS and Android, includes code and message details. |
ConversationState
Tracks the avatar’s current playback state.
| State | Description |
|---|
idle | No active conversation — avatar shows breathing animation. |
playing | Avatar is actively playing audio and animation. |
paused | Playback is paused. |
Usage Examples
const controller = avatarView.controller;
// First frame rendered
avatarView.onFirstRendering = () => {
console.log('First frame rendered');
};
// Connection state (SDK mode only)
controller.onConnectionState = (state) => {
console.log('Connection:', state);
};
// Conversation state
controller.onConversationState = (state) => {
console.log('Conversation:', state);
};
// Error handling
controller.onError = (error) => {
console.error('Error:', error.code, error.message);
};
let controller = avatarView.controller
// First frame rendered
avatarView.onFirstRendering = {
print("First frame rendered")
}
// Connection state (SDK mode only)
controller.onConnectionState = { state in
switch state {
case .connected:
print("Connected")
case .failed(let code, let message):
print("Failed: \(code) \(message)")
default:
break
}
}
// Conversation state
controller.onConversationState = { state in
print("Conversation: \(state)")
}
// Error handling
controller.onError = { error in
print("Error: \(error.localizedDescription)")
}
val controller = avatarView.controller
// First frame rendered
avatarView.onFirstRendering = {
Log.d("Avatar", "First frame rendered")
}
// Connection state (SDK mode only)
controller?.onConnectionState = { state ->
when (state) {
is ConnectionState.Connected ->
Log.d("Avatar", "Connected")
is ConnectionState.Failed ->
Log.e("Avatar", "Failed: ${state.message}")
else -> {}
}
}
// Conversation state
controller?.onConversationState = { state ->
Log.d("Avatar", "Conversation: $state")
}
// Error handling
controller?.onError = { error ->
Log.e("Avatar", "Error: ${error.message}")
}
