기기 앱 제어

앱을 실행하거나 종료하기 전에 기기가 제공한 앱 목록을 기준으로 사용하세요.

사전 요구 사항

• 기기가 연결되어 있고 DeviceAppsAPI를 준수합니다.
• deviceApps가 반환한 raw value만 DeviceApp 값으로 변환합니다.

AI를 활용해 구현

AI로 구현

AI로 이 워크플로 구현

공식 “AIBuds 기기 앱 관리” 스킬을 사용해 앱에 맞게 구현하세요.

https://docs-aibuds.github.io/ko/skills/manage-aibuds-device-apps을 읽고 지침을 따르세요. 이 스킬로 “AIBuds 기기 앱 관리”을 이 iOS 프로젝트에 구현하고 검증하세요.

공식 스킬 보기↗

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	사용할 수 있는 기기 앱의 raw value입니다.
startApp	앱 하나를 실행합니다.
stopApp	앱 하나를 종료합니다.
stopAllAppsAndReturnToHomeScreen	홈 화면으로 돌아갑니다.
getCurrentForegroundApp	현재 포그라운드 앱을 조회합니다.

앱 값

Swift	Objective-C	Raw value	의미
.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으로 조회하며, 제품별 처리를 위해 기기 상태 코드를 보관하세요.