Client Lifecycle

SDK initialization, avatar loading, connection management, and resource cleanup.

AvatarKit follows a four-stage lifecycle: Initialize → Load → Connect → Cleanup. Each stage maps to a core component.

Overview

Stage	Component	What happens
Initialize	AvatarSDK	Configures app ID, environment, audio format, and driving mode. Must be called once before any other API.
Load	AvatarManager	Downloads and caches avatar assets. Returns an Avatar instance.
Render	AvatarView	Creates the rendering surface and its associated AvatarController.
Connect	AvatarController	Opens a WebSocket to the driving service. The avatar begins responding to audio.

Stage 1: Initialize

Call AvatarSDK.initialize() once at app startup. This sets global configuration that all subsequent operations depend on.

Web

await AvatarSDK.initialize({
  appId: 'YOUR_APP_ID',
  audioFormat: { channelCount: 1, sampleRate: 16000 },
  drivingServiceMode: 'sdk',
});

iOS

AvatarSDK.initialize(
    appID: "YOUR_APP_ID",
    configuration: Configuration(
        environment: .intl,
        audioFormat: AudioFormat(sampleRate: 16000),
        drivingServiceMode: .sdk,
        logLevel: .warning
    )
)

Android

AvatarSDK.initialize(
    context = applicationContext,
    appId = "YOUR_APP_ID",
    configuration = Configuration(
        environment = Environment.Intl,
        audioFormat = AudioFormat(16000),
        drivingServiceMode = DrivingServiceMode.SDK,
        logLevel = LogLevel.INFO
    )
)

Set AvatarSDK.sessionToken before connecting. The token authenticates your session with the driving service.

Stage 2: Load Avatar

Use AvatarManager to download and cache avatar assets. Loading is asynchronous and supports progress tracking.

Web

const avatar = await AvatarManager.load('AVATAR_ID', (progress) => {
  console.log('Loading:', progress);
});

iOS

let avatar = try await AvatarManager.shared.load(id: "AVATAR_ID") { progress in
    print("Loading: \(progress)")
}

Android

val avatar = AvatarManager.load("AVATAR_ID") { progress ->
    Log.d("Avatar", "Loading: $progress")
}

Loaded assets are cached locally. Subsequent loads for the same avatar ID skip the download. Use AvatarManager.clear(id:) or clearAll() to manage cache.

Stage 3: Render

Create an AvatarView with the loaded avatar. The view automatically creates an AvatarController you can access to manage the connection and send audio.

Web

const avatarView = new AvatarView(avatar, containerElement);
const controller = avatarView.controller;

iOS

let avatarView = AvatarView(avatar: avatar)
let controller = avatarView.controller

Android

val avatarView = AvatarView(context)
avatarView.init(avatar, lifecycleScope)
val controller = avatarView.controller

Stage 4: Connect and Interact

Call controller.start() to open the WebSocket connection. Once connected, send audio with controller.send() (SDK Mode) or controller.yield() (Host Mode).

Call controller.interrupt() to stop the current playback immediately. Call controller.close() when done.

Cleanup

Clean up resources when the avatar is no longer needed.

Web

avatarView.dispose();

iOS

// AvatarView automatically releases resources when removed from the view hierarchy.
// No explicit cleanup call needed.

Android

avatarView.dispose()

On Web and Android, always call avatarView.dispose() when the view is no longer needed. On iOS, resources are released automatically when the view is deallocated.