Requirements
Before getting started, ensure your development environment meets the following requirements:
- Xcode Version: Xcode 16.0+
- iOS Version: 16.0+
- Physical Device: iOS device with Metal GPU Family 7 support
Step 1: Integrate SPAvatarKit
Swift Package Manager
CocoaPods
Swift Package Manager
- Open your project in Xcode
- Select
File → Add Packages...
- Enter the package URL:
https://github.com/your-org/SPAvatarKit.git
- Select version rule: Up to Next Major Version
- Select target project and click
Add Package
Step 2: Initialize SDK
Initialize the SDK in AppDelegate.swift:
import UIKit
import SPAvatarKit
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
let configuration = SPAvatarSDK.Configuration()
SPAvatarSDK.shared.setup(sessionToken: "", configuration: configuration, delegate: self)
return true
}
}
extension AppDelegate: SPAvatarSDKDelegate {
func avatarSDKDidStarted() -> Void {
}
func avatarSDKFailedToStart() -> Void {
}
}
Step 3: Create Avatar View
Add the avatar renderer in your ViewController:
import UIKit
import SPAvatarKit
class ViewController: UIViewController {
private var characterManager: SPCharacterManager!
override func viewDidLoad() {
super.viewDidLoad()
setupCharacterManager()
setupCharacterView()
}
/* Create SPCharacterManager:
1. Load the avatar
2. Create SPCharacterManager with the avatar
*/
private func setupCharacterManager() {
Task { [weak self] in
guard let self = self else { return }
guard let character = await SPCharacterLoader.shared.loadCharacter("Avatar ID", 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
}
}
/// Create avatar view
private func setupCharacterView() {
guard self.characterManager != nil else { return }
let characterView = SPCharacterView(characterManager: self.characterManager)
view.addSubview(characterView)
characterView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
// Custom layout...
])
}
}
// MARK: - SPCharacterManagerDelegate
extension ViewController: SPCharacterManagerDelegate {
/// Service connection state updated
func characterManager(_ characterManager: SPCharacterManager, didUpdatedConnectionState newConnectionState: SPAvatar.ConnectionState) -> Void { }
/// Conversation state updated
func characterManager(_ characterManager: SPCharacterManager, didUpdatedConversationState newConversationState: SPAvatar.ConversationState) -> Void { }
/// Player state updated
func characterManager(_ characterManager: SPCharacterManager, didUpdatedPlayerState newPlayerState: SPAvatar.PlayerState) -> Void { }
/// Error encountered
func characterManager(_ characterManager: SPCharacterManager, didEncounteredError error: SPAvatar.Error) -> Void { }
}
Step 4: Using Features
// Connect to service
characterManager.start()
// Send data to server
characterManager.sendAudioData("pcmAudioData")
// Interrupt conversation
characterManager.interrupt()
// Close service, resources will be cleaned up when shouldCleanup is true
characterManager.close(shouldCleanup: true)
Step 5: Debug & Run
- Select a physical device
- Click the run button
- Check console output to confirm SDK initialization succeeded
- Observe whether the avatar displays correctly
Running on a physical device is required.
Next Steps
Congratulations! You have successfully integrated the SPAvatarKit. Next you can:
Having Issues?
If you encounter problems during integration, please check:
- FAQ - Common integration questions and answers
