Skip to content

Getting Started Quickstart

Jump to bottom
Mr.P edited this page Aug 25, 2026 · 2 revisions

Quick Start

This guide will help you get started with AIBuds SDK iOS quickly. We'll walk you through the basic setup and show you how to perform common tasks.

Step 1: Import the SDK

Import the main header in any file where you use the SDK:

Swift

import AIBuds
import ABMate
import AIBudsLog
import AIBudsAIFoundation
import AIBudsAI
import AIBudsStarBurst
import AIBudsMagicHelper
import AIBudsVoiceAssistant
import AIBudsXLFacility
import AIBudsLiveStream
import AIBudsCrashReporter
import AIBudsAllInOne

Objective-C

#import <AIBuds/AIBuds.h>
#import <AIBuds/AIBuds-Swift.h>
#import <ABMate/ABMate-Swift.h>
#import <AIBudsLog/AIBudsLog-Swift.h>
#import <AIBudsAIFoundation/AIBudsAIFoundation-Swift.h>
#import <AIBudsAI/AIBudsAI-Swift.h>
#import <AIBudsStarBurst/AIBudsStarBurst-Swift.h>
#import <AIBudsMagicHelper/AIBudsMagicHelper-Swift.h>
#import <AIBudsVoiceAssistant/AIBudsVoiceAssistant-Swift.h>
#import <AIBudsXLFacility/AIBudsXLFacility-Swift.h>
#import <AIBudsLiveStream/AIBudsLiveStream-Swift.h>
#import <AIBudsCrashReporter/AIBudsCrashReporter.h>
#import <AIBudsCrashReporter/AIBudsCrashReporter-Swift.h>
#import <AIBudsAllInOne/AIBudsAllInOne-Swift.h>

Step 2: Initialize the SDK

First, you need to initialize the AIBuds SDK in your application. This is typically done in your AppDelegate or SceneDelegate:

Swift

// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Initialize AIBuds SDK with Full Installation
    initWithFullInstallation()

    // Initialize AIBuds SDK with Custom Installation
    //initWithCustomInstallation()

    return true
}

/// Initialize AIBuds SDK with Full Installation
private func initWithFullInstallation() {
    // Initialize AIBuds SDK
    if !AllInOneSDK.init(withDelegate: self) {
        print("Failed to initialize AIBuds AllInOne SDK.")
    }

    // Install crash reporter
    AllInOneSDK.installCrashReporter { reportFilePath in
        print("Last crash report path: \(reportFilePath ?? "")")
    } reportListUpdateCallback: {
        print("Crash report list updated")
    }
    // Set user info for crash reporter
    CrashReporterSDK.setUserInfo("Tom", forKey: "User Name")
    CrashReporterSDK.setUserInfo("199", forKey: "User ID")

    // Start AI dashboard
    AllInOneSDK.startAIDashboard()
}

/// Initialize AIBuds SDK with Custom Installation
private func initWithCustomInstallation() {
    // Set XLFacility plugin
    AIBudsLogSDK.setXLFacilityPlugin(XLFacilitySDK.shared())

    // Initialize AIBuds SDK with all Ble SDKs you would like to integrate into your app
    let sdkConfiguration = SDKConfiguration.default()
    // Set log level to verbose
    sdkConfiguration.logLevel = .verbose
    let success = AIBudsSDK.initialize([ABMateSDK.shared()],
                                 configuration: sdkConfiguration,
                                 delegate: self)
    if !success {
        print("AIBudsSDK initialize failed.")
    }

    // Install StarBurst AI plugin
    AIBudsSDK.setStarBurstAIPlugin(StarBurstAuthPlugin.shared())
    // Install MltCloud AI plugin
    AIBudsSDK.setMltCloudAIPlugin(MltCloudAuthPlugin.shared())

    // Install OnDeviceVoiceAssistant plugin
    AIBudsSDK.setOnDeviceVoiceAssistantPlugin(OnDeviceVoiceAssistantPlugin.shared())

    // Initialize AI SDK with all AI SDKs you would like to integrate into your app
    let aiSuccess = AIBudsAISDK.initialize([StarBurstSDK.shared(),
                                            MagicHelperSDK.shared()])
    if !aiSuccess {
        print("AIBudsAISDK initialize failed.")
    }

    // Install crash reporter
    CrashReporterSDK.installCrashReporter { reportFilePath in
        print("Last crash report path: \(reportFilePath ?? "")")
    } reportListUpdateCallback: {
        print("Crash report list updated")
    }
    // Set user info for crash reporter
    CrashReporterSDK.setUserInfo("Tom", forKey: "User Name")
    CrashReporterSDK.setUserInfo("199", forKey: "User ID")

    // Start AI dashboard
    AIDashboardSDK.start()
}

Objective-C

// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Initialize AIBuds SDK with Full Installation
    [self initWithFullInstallation];

    // Initialize AIBuds SDK with Custom Installation
    //[self initWithCustomInstallation];

    return YES;
}

/// Initialize AIBuds SDK with Full Installation
- (void)initWithFullInstallation {
    // Initialize AIBuds SDK
    if(![AIBudsAllInOneSDK initWithDelegate:self]) {
        NSLog(@"%@", @"Failed to initialize AIBuds AllInOne SDK.");
    }

    // Install crash reporter
    [AIBudsAllInOneSDK installCrashReporterWithLastCrashReportCallback:^(NSString * _Nullable reportFilePath) {
        NSLog(@"Last crash report path: %@", reportFilePath);
    } reportListUpdateCallback:^{
        NSLog(@"Crash report list updated");
    }];
    // Set user info for crash reporter
    [AIBudsCrashReporterSDK setUserInfo:@"Tom" forKey:@"User Name"];
    [AIBudsCrashReporterSDK setUserInfo:@"199" forKey:@"User ID"];

    // Start AI dashboard
    [AIBudsAllInOneSDK startAIDashboard];
}

/// Initialize AIBuds SDK with Custom Installation
- (void)initWithCustomInstallation {
    // Set XLFacility plugin
    [AIBudsLogSDK setXLFacilityPlugin:[AIBudsXLFacilitySDK shared]];

    // Initialize AIBuds SDK with all Ble SDKs you would like to integrate into your app
    AIBudsSDKConfiguration* sdkConfiguration = [AIBudsSDKConfiguration defaultConfiguration];
    // Set log level to verbose
    sdkConfiguration.logLevel = AIBudsLogLevelVerbose;
    BOOL success = [AIBudsSDK initWithBleSDKs:@[[ABMateSDK shared]]
                                               configuration:sdkConfiguration
                                                    delegate:self];
    if(!success) {
        NSLog(@"%@", @"AIBudsSDK initialize failed.");
    }

    // Install StarBurst AI plugin
    [AIBudsSDK setStarBurstAIPlugin:[AIBudsStarBurstAuthPlugin shared]];
    // Install MltCloud AI plugin
    [AIBudsSDK setMltCloudAIPlugin:[AIBudsMltCloudAuthPlugin shared]];

    // Install OnDeviceVoiceAssistant plugin
    [AIBudsSDK setOnDeviceVoiceAssistantPlugin:[AIBudsOnDeviceVoiceAssistantPlugin shared]];

    // Initialize AI SDK with all AI SDKs you would like to integrate into your app
    success = [AIBudsAISDK initWithAISDKs:@[[AIBudsStarBurstSDK shared],
                                            [AIBudsMagicHelperSDK shared]]];
    if(!success) {
        NSLog(@"%@", @"AIBudsAISDK initialize failed.");
    }

    // Install crash reporter
    [AIBudsCrashReporterSDK installCrashReporterWithLastCrashReportCallback:^(NSString * _Nullable reportFilePath) {
        NSLog(@"Last crash report path: %@", reportFilePath);
    } reportListUpdateCallback:^{
        NSLog(@"Crash report list updated");
    }];
    // Set user info for crash reporter
    [AIBudsCrashReporterSDK setUserInfo:@"Tom" forKey:@"User Name"];
    [AIBudsCrashReporterSDK setUserInfo:@"199" forKey:@"User ID"];

    // Start AI dashboard
    [AIDashboardSDK start];
}

Step 3: Scan for Devices

To connect to an AIBuds device, you first need to scan for available devices:

Swift

// Start scanning for devices
AIBudsSDK.startScanning(
    deviceFoundHandler: { device, isExistingDevice in
        print("Found device: \(device.name), RSSI: \(device.rssi)")
        print(isExistingDevice ? "Already stored" : "New device")
    },
    completion: {
        print("Scanning stopped")
    }
)

Objective-C

// Start scanning for devices
[AIBudsSDK startScanningWithTimeout:nil deviceFoundHandler:^(id<AIBudsFoundDeviceConvertible>  _Nonnull device, BOOL isExistingDevice) {
    NSLog(@"Found device: %@, RSSI: %@", device.name, device.rssi);
} completion:^{

}];

Step 4: Add a Device

After scanning, you can add a discovered device to "My Devices" so it persists across app launches. Convert the FoundDeviceConvertible returned by the scan through makeStorableDeviceFromDiscovered(_:), then save it through StoredDevicesMgr:

Swift

func store(_ discoveredDevice: FoundDeviceConvertible) {
    // Convert the SDK scan result into a persistent device.
    guard let device = AIBudsSDK.makeStorableDeviceFromDiscovered(discoveredDevice) else {
        return
    }

    // Optional app-owned display information.
    device.screenName = device.name
    device.thumbnail = UIImage(named: "icon.glasses")
    device.customContent = "Smart Glasses"

    if StoredDevicesMgr.addDevice(device) {
        AIBudsSDK.stopScanning()
        navigationController?.popViewController(animated: true)
    }
}

Objective-C

- (void)storeDiscoveredDevice:(id<AIBudsFoundDeviceConvertible>)discoveredDevice {
    // Convert the SDK scan result into a persistent device.
    id<AIBudsDeviceConvertible> device =
        [AIBudsSDK makeStorableDeviceFromDiscovered:discoveredDevice];
    if (device == nil) { return; }

    // Optional app-owned display information.
    device.screenName = device.name;
    device.thumbnail = [UIImage imageNamed:@"icon.glasses"];
    device.customContent = @"Smart Glasses";

    if ([AIBudsStoredDevicesMgr addDevice:device]) {
        [AIBudsSDK stopScanning];
        [self.navigationController popViewControllerAnimated:YES];
    }
}

Step 5: Connect to a Device

With a stored device ready, connect to it using ConnectParams. You can pass AI auth parameters so the SDK authenticates with your AI providers during connection:

Swift

let device = devices[indexPath.item]

let param = ConnectParams()
let aiAuthParams = AIAuthParams()

// StarBurst AI auth
let starBurstAuthParams = StarBurstAIAuthParams()
starBurstAuthParams.productId = configs["STARBURST_PRODUCTID"]
if let ppeEnv = configs["STARBURST_PPEENV"] as? String, !ppeEnv.isEmpty {
    starBurstAuthParams.ppeEnv = ppeEnv
}
aiAuthParams.starburst = starBurstAuthParams

// MltCloud AI auth
let mltCloudAuthParams = MltCloudAIAuthParams()
mltCloudAuthParams.channelId = configs["MLTCLOUD_CHANNELID"]
aiAuthParams.mltcloud = mltCloudAuthParams

param.aiAuthParams = aiAuthParams
param.userId = "199"

// Connect to the device
device.connect(param)

Objective-C

id<AIBudsDeviceConvertible> device = self.devices[indexPath.item];

AIBudsConnectParams *param = [AIBudsConnectParams new];
AIBudsAIAuthParams *aiAuthParams = [AIBudsAIAuthParams new];

// StarBurst AI auth
AIBudsStarBurstAIAuthParams *starBurstAuthParams = [AIBudsStarBurstAIAuthParams new];
starBurstAuthParams.productId = configs[@"STARBURST_PRODUCTID"];
NSString *ppeEnv = configs[@"STARBURST_PPEENV"];
if ([ppeEnv isKindOfClass:[NSString class]] && [ppeEnv length] > 0) {
    starBurstAuthParams.ppeEnv = ppeEnv;
}
aiAuthParams.starburst = starBurstAuthParams;

// MltCloud AI auth
AIBudsMltCloudAIAuthParams *mltCloudAuthParams = [AIBudsMltCloudAIAuthParams new];
mltCloudAuthParams.channelId = configs[@"MLTCLOUD_CHANNELID"];
aiAuthParams.mltcloud = mltCloudAuthParams;

param.aiAuthParams = aiAuthParams;
param.userId = @"199";

// Connect to the device
[device connectWithParams:param];

Step 6: Send Commands

Once connected, you can send commands to the device:

Swift

// Example: Set device time
guard let device = device as? DeviceInfoAPI else { return }
let date = Date()
device.setDeviceTime(date) { success, statusCode, error in
    if success {
        print("Device time set successfully")
    } else {
        print("Failed to set device time: \(error?.localizedDescription ?? "Unknown error")")
    }
}

Objective-C

// Example: Set device time
id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;
if ([device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
    NSDate *date = [NSDate date];
    [device setDeviceTime:date completion:^(BOOL success, NSNumber * _Nullable statusCode, NSError * _Nullable error) {
        if (success) {
            NSLog(@"Device time set successfully");
        } else {
            NSLog(@"Failed to set device time: %@", error.localizedDescription);
        }
    }];
}

Step 7: Handle Device Delegate

Adopt the DeviceDelegate protocol to receive connection lifecycle device delegate events. All methods are @objc optional — implement only the callbacks you need:

Swift

// Mark your class as the device's delegate
device.delegate = self

// Implement the optional delegate methods
extension YourViewController: DeviceDelegate {
    func didStartConnectingDevice(_ device: DeviceConvertible) {
        print("Connecting to \(device.name)…")
    }

    func didConnectedToDevice(_ device: DeviceConvertible) {
        print("Connected to \(device.name)")
    }

    func didFailToConnectDevice(_ device: DeviceConvertible?, error: NSError?) {
        print("Failed to connect: \(error?.localizedDescription ?? "Unknown error")")
    }

    func device(_ device: DeviceConvertible?, didDisconnectWithError error: NSError?) {
        if let error {
            print("Disconnected with error: \(error.localizedDescription)")
        } else {
            print("Disconnected")
        }
    }

    func deviceDidReady(_ device: DeviceConvertible) {
        print("Device ready: \(device.name)")
    }

    /// ... other delegate methods...
}

Objective-C

// YourViewController.h — declare conformance to AIBudsDeviceDelegate
@interface YourViewController : UIViewController <AIBudsDeviceDelegate>
@end

// YourViewController.m
@implementation YourViewController

// Mark your class as the device's delegate
self.device.delegate = self;

// Implement the optional delegate methods
- (void)didStartConnectingDevice:(id<AIBudsDeviceConvertible>)device {
    NSLog(@"Connecting to %@…", device.name);
}

- (void)didConnectedToDevice:(id<AIBudsDeviceConvertible>)device {
    NSLog(@"Connected to %@", device.name);
}

- (void)didFailToConnectDevice:(id<AIBudsDeviceConvertible>)device error:(NSError *)error {
    NSLog(@"Failed to connect: %@", error.localizedDescription);
}

- (void)device:(id<AIBudsDeviceConvertible>)device didDisconnectWithError:(NSError *)error {
    if (error) {
        NSLog(@"Disconnected with error: %@", error.localizedDescription);
    } else {
        NSLog(@"Disconnected");
    }
}

- (void)deviceDidReady:(id<AIBudsDeviceConvertible>)device {
    NSLog(@"Device ready: %@", device.name);
}

/// ... other delegate methods...

@end

Step 8: Disconnect from a Device

When you're done with a device, you should disconnect from it:

Swift

// Disconnect from a device
device.disconnect()

Objective-C

// Disconnect from a device
id<AIBudsDeviceConvertible> device = self.device;
[device disconnect];

Example App

For a complete example, check out the AIBudsSDK-Demo project, which demonstrates how to use the SDK in a real-world application.

Next Steps

Now that you've learned the basics, you can explore the SDK's more advanced features:

AIBuds SDK documentation · Full documentation · API Reference

AIBuds SDK iOS Wiki

Clone this wiki locally