API Reference

SPAvatarSDK

The main entry point class for the SDK, responsible for initialization and global configuration.

public protocol SPAvatarSDKDelegate: AnyObject {
    /// SDK verification succeeded
    func avatarSDKDidStarted() -> Void
    /// SDK verification failed
    func avatarSDKFailedToStart() -> Void
}

/// SDK entry point
public final class SPAvatarSDK {
    weak var delegate: SPAvatarSDKDelegate?

    /// Start the SDK
    /// - Parameter sessionToken: Authentication token
    /// - Parameter configuration: SDK configuration
    /// - Parameter delegate: Delegate
    public func setup(sessionToken: String, configuration: Configuration, delegate: SPAvatarSDKDelegate?) { }
    
    /// Update configuration
    /// - Parameter configuration: New configuration
    public func update(configuration: Configuration) { }
    
    /// Get SDK version
    public func sdkVersion() ->  String { }
    
    /// Setup environment
    public func setupEnvironment(_ environment: SPAvatarSDK.Environment) { }
}

public struct Configuration : Sendable {
    /// Downgrade plan option
    public var downgradePlan: DowngradePlan = .none
    /// Request timeout duration in seconds
    public var requestTimeout: TimeInterval?
}

public enum DowngradePlan: Sendable {
    /// No downgrade plan
    case none
    /// Play audio with idle animation
    case playAudioWithIdleAnimation
}

public enum Environment: String {
    /// Release
    case release
    /// Development
    case develop
}

SPCharacterManager

Character manager responsible for rendering and control.

public protocol SPCharacterManagerDelegate: AnyObject {
    /// Service connection state has been updated
    /// - Parameter newConnectionState: New connection state
    func characterManager(_ characterManager: SPCharacterManager, didUpdatedConnectionState newConnectionState: SPAvatar.ConnectionState) -> Void
    /// Conversation state has been updated
    /// - Parameter newConversationState: New conversation state
    func characterManager(_ characterManager: SPCharacterManager, didUpdatedConversationState newConversationState: SPAvatar.ConversationState) -> Void
    /// Player state has been updated
    /// - Parameter newPlayerState: New player state
    func characterManager(_ characterManager: SPCharacterManager, didUpdatedPlayerState newPlayerState: SPAvatar.PlayerState) -> Void
    /// Encountered an error
    /// - Parameter error: Error
    func characterManager(_ characterManager: SPCharacterManager, didEncounteredError error: SPAvatar.Error) -> Void
}

public final class SPCharacterManager {
    /// Service connection state
    public var connectionState: SPAvatar.ConnectionState
    /// Conversation state
    public var conversationState: SPAvatar.ConversationState
    /// Player state
    public var playerState: SPAvatar.PlayerState
    
    /// Delegate
    public weak var delegate: SPCharacterManagerDelegate?

    /// Initializer
    /// - Parameter character: Character to render
    public init(character: SPAvatar.Character) { }
    
    /// Connect to service
    public func start() { }

    /// Close service and reset conversation state
    /// - Parameter shouldCleanup: Whether to clean up resources, recommended when leaving character page
    public func close(shouldCleanup: Bool) { }

    /// Interrupt conversation
    public func interrupt() { }

    /// Toggle player mute/unmute
    public func togglePlayerMute() { }

    /// Send audio data to server
    /// - Parameter audioData: PCM audio data
    /// - Parameter end: Whether audio data has been fully sent
    public func sendAudioData(_ audioData: Data, end: Bool) { }
}

SPCharacterLoader

Character loader responsible for downloading and caching character resources

public final class SPCharacterLoader: Sendable {
    /// State handler
    public typealias StateHandler = @Sendable (LoadState) -> Void

    /// Load state
    public enum LoadState: Sendable {
        /// About to start loading
        case preparing
        /// Downloading
        case downloading(progress: DownloadProgress)
        /// Loading completed
        case completed
        /// Loading failed
        case failed(Error)
        /// Information
        case info(String)
    }

    /// Load character
    /// - Parameter characterId: Character ID
    /// - Parameter stateHandler: State handler callback
    /// - Returns: Successfully loaded character data structure, returns nil if loading fails
    public func loadCharacter(_ characterId: String, stateHandler: @escaping StateHandler) async -> SPAvatar.Character? { }
}

Connection State

SPAvatar.ConnectionState

SDK connection state definition

public enum ConnectionState {
    /// Disconnected
    case disconnected
    /// Connecting
    case connecting
    /// Connected
    case connected
    /// Connection failed
    case failed
}

Conversation State

SPAvatar.ConversationState

SDK conversation state definition

public enum ConversationState {
    /// Idle
    case idle
    /// Starting
    case starting
    /// Active
    case active
    /// Closing
    case closing
}

Player State

SPAvatar.PlayerState

SDK player state definition

public enum PlayerState {
    /// Idle
    case idle
    /// Playing
    case playing
}

Error Handling

SPAvatar.Error.ErrorType

SDK error type definition

public enum SPAvatar.Error.ErrorType: Int {
    /// SDK not verified
    case sdkNotVerified = 1001
    /// Character ID is invalid
    case characterIdWrong = 1002
    /// Character assets are missing
    case characterAssetsMissing = 1003
    /// Character camera settings are invalid
    case characterCameraSettingsWrong =  1004
    /// Server error
    case serviceError = 1005
    /// Failed to activate AudioSession
    case activeAudioSessionFailed = 1006
    /// Failed to start AudioEngine
    case startAudioEngineFailed = 1007
    /// Sent data is invalid
    case sendDataWrong = 1008
    /// Request timeout
    case requestTimeout = 1009
}

Usage Examples

Basic Initialization

Create Configuration

let configuration = SPAvatarSDK.Configuration()

Initialize SDK

SPAvatarSDK.shared.setup(sessionToken: "", configuration: configuration, delegate: self)

Authentication will start when connecting to the service. If authentication fails, SPAvatarSDKDelegate will call the failure callback

Create Character View

Create Character Manager Instance

class ViewController: UIViewController {
    private var characterManager: SPCharacterManager!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupCharacterManager()
    }
    
    private func setupCharacterManager() {
      Task { [weak self] in
          guard let self = self else { return }
          guard let character = await SPCharacterLoader.shared.loadCharacter("characterId", stateHandler: { state in
              // Handle download state
              switch state {
              case .preparing:
                  // Preparing to load
                  break
              case .downloading(let progress):
                  // Downloading
                  break
              case .failed(let error):
                  // Loading failed
                  break
              case .completed:
                  // Loading completed
                  break
              case .info(let msg):
                  // Information
                  break
              }
          }) else {
              // Handle loading failure
              return
          }
          self.characterManager = SPCharacterManager(character: character)
          self.characterManager.delegate = self
      }
  }
}

Ensure the model URL is valid and the network connection is stable. It’s recommended to check network status before loading.

Create Character View

class ViewController: UIViewController {
  ... 

  private func setupCharacterView() {
      guard self.characterManager != nil else { return }
      let characterView = SPCharacterView(characterManager: self.characterManager)
      view.addSubview(characterView)
      characterView.translatesAutoresizingMaskIntoConstraints = false
      let aspectRatio = self.characterManager.character.aspectRatio
      NSLayoutConstraint.activate([
         // Customize layout based on aspectRatio
      ])
  }

  ...
}

Audio Processing

Audio Usage Example

characterManager.sendAudioData("pcmAudioData")

Implement Delegate Methods

SPCharacterManagerDelegate Implementation

extension ViewController: SPCharacterManagerDelegate {
    /// Service connection state has been updated
    func characterManager(_ characterManager: SPCharacterManager, didUpdatedConnectionState newConnectionState: SPAvatar.ConnectionState) -> Void { }
    /// Conversation state has been updated
    func characterManager(_ characterManager: SPCharacterManager, didUpdatedConversationState newConversationState: SPAvatar.ConversationState) -> Void { }
    /// Player state has been updated
    func characterManager(_ characterManager: SPCharacterManager, didUpdatedPlayerState newPlayerState: SPAvatar.PlayerState) -> Void { }
    /// Encountered an error
    func characterManager(_ characterManager: SPCharacterManager, didEncounteredError error: SPAvatar.Error) -> Void { }
}

Error Code Reference

Error Type	Error Code	Description	Solution
`sdkNotVerified`	1001	SDK not verified	Check if SDK started successfully
`characterIdWrong`	1002	Character ID is invalid	Check character status
`characterAssetsMissing`	1003	Character assets are missing	Check if character resources are complete
`characterCameraSettingsWrong`	1004	Character camera settings are invalid	Check camera parameters
`serviceError`	1005	Server error	Network service may be temporarily down, downgrade plan will be activated
`activeAudioSessionFailed`	1006	Unsupported operation	Check for AudioEngine configuration conflicts
`startAudioEngineFailed`	1007	Failed to start AudioEngine	Check SDK version and feature support
`sendDataWrong`	1008	Sent data is invalid	Check if the audio data sent is valid
`requestTimeout`	1009	Request timeout	Check network status

Thread Safety

Main Thread: UI-related operations must be executed on the main thread
Background Thread: Network requests and file operations are executed on background threads
Callbacks: All delegate callbacks are executed on the main thread

Memory Management

SPAvatarKit automatically manages internal resources
Avoid retain cycles by using weak references for delegate objects
When exiting the character page, call close(shouldCleanup: Bool = true) through SPCharacterManager to clean up resources

Getting started

Integration

Development

Support

SPAvatarSDK

SPCharacterManager

SPCharacterLoader

Connection State

SPAvatar.ConnectionState

Conversation State

SPAvatar.ConversationState

Player State

SPAvatar.PlayerState

Error Handling

SPAvatar.Error.ErrorType

Usage Examples

Basic Initialization

Create Character View

Audio Processing

Implement Delegate Methods

Error Code Reference

Thread Safety

Memory Management

Getting started

Integration

Development

Support

​SPAvatarSDK

​SPCharacterManager

​SPCharacterLoader

​Connection State

​SPAvatar.ConnectionState

​Conversation State

​SPAvatar.ConversationState

​Player State

​SPAvatar.PlayerState

​Error Handling

​SPAvatar.Error.ErrorType

​Usage Examples

​Basic Initialization

​Create Character View

​Audio Processing

​Implement Delegate Methods

​Error Code Reference

​Thread Safety

​Memory Management

SPAvatarSDK

SPCharacterManager

SPCharacterLoader

Connection State

SPAvatar.ConnectionState

Conversation State

SPAvatar.ConversationState

Player State

SPAvatar.PlayerState

Error Handling

SPAvatar.Error.ErrorType

Usage Examples

Basic Initialization

Create Character View

Audio Processing

Implement Delegate Methods

Error Code Reference

Thread Safety

Memory Management