管理设备应用

启动或停止应用前，应以设备返回的应用列表为准。

前提条件

• 设备已连接，并遵循 DeviceAppsAPI。
• 仅将 deviceApps 返回的原始值转换为 DeviceApp。

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“管理 AIBuds 设备应用”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/manage-aibuds-device-apps，使用该技能在当前 iOS 项目中完成“管理 AIBuds 设备应用”，并验证结果。

查看官方技能↗

API 参考

框架

AIBuds.xcframework

协议

Swift

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

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

符号

符号	用途
deviceApps	可用设备应用的原始值。
startApp	启动一个应用。
stopApp	停止一个应用。
stopAllAppsAndReturnToHomeScreen	返回设备主屏幕。
getCurrentForegroundApp	查询前台应用。

应用取值

Swift	Objective-C	原始值	含义
.homeScreen	AIBudsDeviceAppHomeScreen	0x00	设备主屏幕，不可传给 startApp 或 stopApp。
.teleprompter	AIBudsDeviceAppTeleprompter	0x01	提词器应用。
.aiChat	AIBudsDeviceAppAiChat	0x02	AI 对话应用。
.navigation	AIBudsDeviceAppNavigation	0x03	导航应用。
.clock	AIBudsDeviceAppClock	0x04	时钟应用。
.translation	AIBudsDeviceAppTranslation	0x05	翻译应用。

使用示例

Swift

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

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);
}];

错误处理

不要假定每台设备都支持全部 DeviceApp case。使用 deviceApps 判断可用性，通过 getCurrentForegroundApp 读取设备当前的前台应用，并保留设备状态码供产品按需处理。