Core Device Apps Applications

Manage Device Applications

Use the device-provided application list as the source of truth before starting or stopping an application.

Prerequisites

• The device is connected and conforms to DeviceAppsAPI.
• Convert only raw values returned by deviceApps into DeviceApp values.

API Reference

Framework

AIBuds.xcframework

Protocol

Swift

/// The protocol for device apps API. (Device Side Applications)
protocol DeviceAppsAPI: DeviceAPI {
    /// List of apps installed on the device, each element is an `NSNumber` wrapping the raw value of `DeviceApp`.
    var deviceApps: [NSNumber]? { get }

    /// Start the device side application.
    /// - Parameters:
    ///   - app: The app to start.
    ///   - completion: Reports success, the device status code, and an optional error.
    func startApp(_ app: DeviceApp, completion: AIBudsStatusCodeCompletionHandler?)

    /// Stop the device side application.
    /// - Parameters:
    ///   - app: The app to stop.
    ///   - completion: Reports success, the device status code, and an optional error.
    func stopApp(_ app: DeviceApp, completion: AIBudsStatusCodeCompletionHandler?)

    /// Stop all running applications and return to the home screen.
    /// - Parameter completion: Reports success and an optional error.
    func stopAllAppsAndReturnToHomeScreen(_ completion: AIBudsCompletionHandler?)

    /// Get the current foreground application.
    /// - Parameter completion: Reports success, the foreground app raw value, and an optional error.
    func getCurrentForegroundApp(
        _ completion: (
            (
                _ success: Bool,
                _ app: NSNumber?,
                _ error: NSError?
            ) -> Void
        )?
    )
}

Objective-C

/// The protocol for device apps API. (Device Side Applications)
@protocol AIBudsDeviceAppsAPI <AIBudsDeviceAPI>
@property(nonatomic, readonly, copy) NSArray<NSNumber *> *_Nullable deviceApps;

/// Start the device side application.
- (void)startApp:(enum AIBudsDeviceApp)app
      completion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;

/// Stop the device side application.
- (void)stopApp:(enum AIBudsDeviceApp)app
     completion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;

/// Stop all running applications and return to the home screen.
- (void)stopAllAppsAndReturnToHomeScreenWithCompletion:
    (AIBudsCompletionHandler _Nullable)completion;

/// Get the current foreground application.
- (void)getCurrentForegroundAppWithCompletion:
    (void (^_Nullable)(BOOL, NSNumber *_Nullable, NSError *_Nullable))completion;
@end

Symbols

Symbol	Purpose
deviceApps	Raw values for available device applications.
startApp	Start one application.
stopApp	Stop one application.
stopAllAppsAndReturnToHomeScreen	Return to the home screen.
getCurrentForegroundApp	Query the foreground app.

Application Values

Swift	Objective-C	Raw value	Meaning
.homeScreen	AIBudsDeviceAppHomeScreen	0x00	Device home screen. Do not pass it to startApp or stopApp.
.teleprompter	AIBudsDeviceAppTeleprompter	0x01	Teleprompter application.
.aiChat	AIBudsDeviceAppAiChat	0x02	AI conversation application.
.navigation	AIBudsDeviceAppNavigation	0x03	Navigation application.
.clock	AIBudsDeviceAppClock	0x04	Clock application.
.translation	AIBudsDeviceAppTranslation	0x05	Translation application.

Usage Examples

Swift

guard let device = device as? DeviceAppsAPI else { return }

let apps = (device.deviceApps ?? []).compactMap {
    DeviceApp(rawValue: $0.intValue)
}

guard let app = apps.first else {
    print("No device application is available")
    return
}

device.startApp(app) { success, statusCode, error in
    guard success else {
        print(error?.localizedDescription ?? "Application failed to start")
        return
    }
    print("Application started: \(statusCode?.stringValue ?? "Unavailable")")
}

device.getCurrentForegroundApp { success, rawApp, error in
    let foreground = rawApp.flatMap { DeviceApp(rawValue: $0.intValue) }
    print(
        success
            ? "Foreground: \(String(describing: foreground))"
            : (error?.localizedDescription ?? "Query failed"))
}

Objective-C

id<AIBudsDeviceAppsAPI> device = (id<AIBudsDeviceAppsAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceAppsAPI)])
    return;

NSNumber *rawApp = device.deviceApps.firstObject;
if (rawApp != nil) {
    AIBudsDeviceApp app = (AIBudsDeviceApp)rawApp.integerValue;
    [device startApp:app
          completion:^(BOOL success, NSNumber *_Nullable statusCode, NSError *_Nullable error) {
              if (!success)
                  NSLog(@"Application failed to start: %@", error.localizedDescription);
          }];
}

[device getCurrentForegroundAppWithCompletion:^(
            BOOL success, NSNumber *_Nullable app, NSError *_Nullable error) {
    NSLog(success ? @"Foreground app: %@" : @"Query failed: %@",
          success ? app : error.localizedDescription);
}];

Error Handling

Do not assume every DeviceApp case exists on every device. Use deviceApps for availability, getCurrentForegroundApp for authoritative foreground state, and preserve device status codes for product-specific handling.