장치 연결 해제

장치 연결 해제 작업은 장치와 연결된 장치 간의 페어링 관계를 제거합니다. 이 작업은 장치를 영구적으로 연결 해제하거나 다른 장치와 페어링할 준비를 할 때 유용합니다.

전제 조건

연결 해제를 수행하기 전에 다음을 확인하십시오:

• 장치가 연결되어 있고 안정적인 상태인지
• 필요한 모든 데이터 동기화가 완료되었는지
• 사용자가 연결 해제 후 장치가 연결 해제될 것임을 이해하고 있는지

AI를 활용해 구현

AI로 구현

AI로 이 워크플로 구현

공식 “AIBuds 기기 페어링 해제” 스킬을 사용해 앱에 맞게 구현하세요.

https://docs-aibuds.github.io/ko/skills/implement-aibuds-unpair-device을 읽고 지침을 따르세요. 이 스킬로 “AIBuds 기기 페어링 해제”을 이 iOS 프로젝트에 구현하고 검증하세요.

공식 스킬 보기↗

API 참조

프레임워크

AIBuds.xcframework

가져오기

SDK를 사용할 파일에서 주 헤더를 가져옵니다:

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds.h>
#import <AIBuds/AIBuds-Swift.h>

프로토콜

unpair 메서드는 다음 프로토콜에서 정의됩니다. 이 프로토콜은 기본 장치 API 프로토콜을 상속합니다.

Swift

Swift

/// Defines common device operations including unpairing
protocol DeviceCommonAPI: DeviceAPI {
    /// Unpairs the device
    /// - Parameters:
    ///   - completion: A completion callback that returns the operation result
    ///     - success: `true` if the operation succeeds, `false` otherwise
    ///     - error: An `NSError` object describing the error that occurred, or `nil` if the operation succeeds
    func unpair(_ completion: AIBudsCompletionHandler?)
}

Objective-C

Objective-C

/// Defines common device operations including unpairing
@protocol AIBudsDeviceCommonAPI <AIBudsDeviceAPI>
/// Unpairs the device
/// - Parameters:
///   - completion: A completion callback that returns the operation result
///     - success: `true` if the operation succeeds, `false` otherwise
///     - error: An `NSError` object describing the error that occurred, or `nil` if the operation
///     succeeds
- (void)unpairWithCompletion:(AIBudsCompletionHandler)completion;
@end

인스턴스 메서드

연결된 장치와의 페어링을 해제합니다.

iOS 13.0+

Swift

Swift

/// Unpairs the device
/// - Parameters:
///   - completion: A completion callback that returns the operation result
///     - success: `true` if the operation succeeds, `false` otherwise
///     - error: An `NSError` object describing the error that occurred, or `nil` if the operation succeeds
func unpair(_ completion: AIBudsCompletionHandler?)

Objective-C

Objective-C

/// Unpairs the device
/// - Parameters:
///   - completion: A completion callback that returns the operation result
///     - success: `true` if the operation succeeds, `false` otherwise
///     - error: An `NSError` object describing the error that occurred, or `nil` if the operation
///     succeeds
- (void)unpairWithCompletion:(AIBudsCompletionHandler)completion;

매개변수

매개변수	유형	설명
completion	AIBudsCompletionHandler?	작업이 완료될 때 호출되는 선택적 완료 콜백

콜백 매개변수:

이름	유형	설명
success	Bool	작업이 성공하면 true, 그렇지 않으면 false
error	NSError?	작업이 실패하면 오류 정보를 포함하고, 그렇지 않으면 nil

반환 값

이 메서드는 직접 값을 반환하지 않습니다. 결과는 완료 콜백을 통해 제공됩니다.

사용 예제

Swift

Swift

import AIBuds

class DeviceManager {

    /// Connected device
    weak var device: DeviceConvertible?

    /// Unpairs the connected device
    func unpairDevice() {
        // Check if the device supports the unpair protocol
        guard let device = device as? DeviceCommonAPI else {
            print("Device does not support unpairing")
            return
        }

        // Execute unpair with completion handler
        device.unpair { [weak self] success, error in
            // Handle failure case
            if !success {
                let errorMessage = {
                    if let error = error {
                        return "\(error)"
                    }
                    return "Unknown error"
                }()
                print("Unpair failed: \(errorMessage)")
                return
            }
            // Handle success case
            print("Unpair completed successfully")
        }
    }
}

Objective-C

Objective-C

#import <AIBuds/AIBuds.h>

@interface DeviceManager ()

/// Connected device
@property(weak, nonatomic) id<AIBudsDeviceConvertible> device;

@end

@implementation DeviceManager

- (void)unpairDevice {
    __weak typeof(self) weakSelf = self;

    id<AIBudsDeviceCommonAPI> device = (id<AIBudsDeviceCommonAPI>)self.device;
    // Check if the device supports the unpair protocol
    if ([device conformsToProtocol:@protocol(AIBudsDeviceCommonAPI)]) {
        // Execute unpair with completion handler
        [device unpairWithCompletion:^(BOOL success, NSError *_Nullable error) {
            // Handle failure case
            if (!success) {
                NSLog(@"Unpair failed: %@", error);
                return;
            }
            // Handle success case
            NSLog(@"Unpair completed successfully");
        }];
    }
}

@end

오류 처리

완료 핸들러는 다음 오류 유형을 반환할 수 있습니다:

오류 도메인: AIBudsSDK.ErrorDomain

Swift

오류 코드	설명	복구 제안
.deviceNotConnected	장치가 연결되지 않았습니다	장치가 페어링되고 연결되었는지 확인
.bleCommandExecFailedDueToTimeout	작업이 시간 초과되었습니다	작업을 재시도
.deviceBusy	장치가 다른 작업으로 바쁩니다	진행 중인 작업이 완료될 때까지 기다림
.deviceNotSupport	이 장치에서는 연결 해제가 지원되지 않습니다	호출하기 전에 장치 기능을 확인

Objective-C

오류 코드	설명	복구 제안
AIBudsSdkErrorCodeDeviceNotConnected	장치가 연결되지 않았습니다	장치가 페어링되고 연결되었는지 확인
AIBudsSdkErrorCodeBleCommandExecFailedDueToTimeout	작업이 시간 초과되었습니다	작업을 재시도
AIBudsSdkErrorCodeDeviceBusy	장치가 다른 작업으로 바쁩니다	진행 중인 작업이 완료될 때까지 기다림
AIBudsSdkErrorCodeDeviceNotSupport	이 장치에서는 연결 해제가 지원되지 않습니다	호출하기 전에 장치 기능을 확인

권장 사항

1. 사용자 확인: 연결 해제를 시작하기 전에 항상 확인 대화 상자를 표시하십시오. 이 작업은 장치를 연결 해제하고 재페어링이 필요합니다.

2. 백그라운드 실행 처리: UI를 업데이트할 때 완료 핸들러를 DispatchQueue.main.async 블록으로 감싸십시오.

3. 약한 Self 참조: 완료 핸들러에서 [weak self]를 사용하여 보유 주기를 방지하십시오.

4. 프로토콜 준수 확인: 메서드를 호출하기 전에 장치가 DeviceCommonAPI 프로토콜을 준수하는지 확인하십시오.

5. 연결 해제 처리: 연결 해제에 성공한 후 장치 연결 해제를 원활하게 처리하고 재페어링을 위한 안내를 제공하십시오.

플랫폼 제한 사항

iOS 시스템 블루투스 제한

iOS에서는 시스템 블루투스 설정에서 애플리케이션이 블루투스 장치를 프로그래밍 방식으로 연결 해제할 수 없습니다. 이는 Apple이 보안 및 사용자 제어를 위해 설정한 시스템 수준 제한입니다.

이의 의미:

• unpair를 호출한 후에도 iOS는 장치의 BLE 페어링 정보를 계속 유지합니다
• 장치가 앱 재시작 또는 블루투스 활성화 시 자동으로 재연결될 수 있습니다
• 장치가 iOS 설정 > 블루투스에 계속 표시됩니다

권장 사용자 안내:

iOS 앱에서 연결 해제 기능을 구현할 때 사용자에게 iOS 설정에서 수동으로 연결 해제하도록 안내해야 합니다:

1. 완전한 연결 해제: 사용자에게 "설정 > 블루투스"로 이동하여 장치를 찾고 "i" 아이콘을 탭한 다음 "이 장치 무시"를 선택하도록 안내합니다
2. 명확한 UI 피드백 제공: 사용자가 연결 해제를 요청할 때 설명 또는 블루투스 설정으로의 딥 링크를 표시합니다
3. 앱 수준 연결 해제: unpair 메서드는 여전히 장치와의 연결을 해제하지만 시스템 페어링은 유지됩니다

Swift

Swift

/// Prompt user to unpair from iOS Settings
func promptUserToUnpairFromSettings() {
    // Show alert with instructions
    let alert = UIAlertController(
        title: "Unpair Device",
        message:
            "To completely unpair the device, go to Settings > Bluetooth, find your device, tap the 'i' icon next to it, then select 'Forget This Device'.",
        preferredStyle: .alert
    )
    alert.addAction(
        UIAlertAction(title: "Open Settings", style: .default) { _ in
            // Deep link to Bluetooth settings
            if let url = URL(string: "App-prefs:Bluetooth") {
                UIApplication.shared.open(url)
            }
        })
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))

    // Present alert
    if let viewController = UIApplication.shared.windows.first?.rootViewController {
        viewController.present(alert, animated: true)
    }
}

Objective-C

Objective-C

/// Prompt user to unpair from iOS Settings
- (void)promptUserToUnpairFromSettings {
    UIAlertController *alert = [UIAlertController
        alertControllerWithTitle:@"Unpair Device"
                         message:@"To completely unpair the device, go to Settings > Bluetooth, "
                                 @"find your device, tap the 'i' icon next to it, then select "
                                 @"'Forget This Device'."
                  preferredStyle:UIAlertControllerStyleAlert];

    [alert addAction:[UIAlertAction actionWithTitle:@"Open Settings"
                                              style:UIAlertActionStyleDefault
                                            handler:^(UIAlertAction *_Nonnull action) {
                                                NSURL *url =
                                                    [NSURL URLWithString:@"App-prefs:Bluetooth"];
                                                if (url && [[UIApplication sharedApplication]
                                                               canOpenURL:url]) {
                                                    [[UIApplication sharedApplication] openURL:url
                                                                                       options:@{}
                                                                             completionHandler:nil];
                                                }
                                            }]];

    [alert addAction:[UIAlertAction actionWithTitle:@"Cancel"
                                              style:UIAlertActionStyleCancel
                                            handler:nil]];

    UIViewController *viewController =
        [UIApplication sharedApplication].windows.firstObject.rootViewController;
    [viewController presentViewController:alert animated:YES completion:nil];
}

참고 사항

• 연결 해제 명령이 실행된 후 장치가 연결 해제됩니다
• 장치를 다시 연결하려면 재페어링이 필요합니다
• 모든 페어링 정보가 두 장치에서 제거됩니다
• 진행 중인 모든 작업이 중단됩니다
• 연결 해제는 몇 초가 걸릴 수 있습니다