Отключение устройства

Операция отключения устройства удаляет связь между устройствами. Эта операция полезна, когда вам нужно разорвать подключение к устройству навсегда или подготовить его для подключения к другому устройству.

Предварительные требования

Перед выполнением отключения убедитесь:

• Устройство подключено и находится в стабильном состоянии
• Завершена все необходимая синхронизация данных
• Пользователь понимает, что после отключения устройство отключится

Реализация с помощью AI

Разработка с AI

Реализуйте этот сценарий с AI

Используйте официальный навык «Отмена сопряжения AIBuds» и адаптируйте сценарий к приложению.

Прочитайте и выполните инструкции https://docs-aibuds.github.io/ru/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?	Необязательный callback, вызываемый при завершении операции

Параметры callback:

Имя	Тип	Описание
success	Bool	true, если операция прошла успешно, иначе false
error	NSError?	Содержит информацию об ошибке, если операция не удалась, иначе nil

Возвращаемое значение

Этот метод не возвращает значение напрямую. Результат предоставляется через callback.

Примеры использования

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

Обработка ошибок

Callback может вернуть следующие типы ошибок:

Домен ошибок: AIBudsSDK.ErrorDomain

Swift

Код ошибки	Описание	Рекомендация по восстановлению
.deviceNotConnected	Устройство не подключено	Убедитесь, что устройство спарено и подключено
.bleCommandExecFailedDueToTimeout	Истекло время ожидания операции	Повторить операцию
.deviceBusy	Устройство занято другой операцией	Дождитесь завершения выполняющихся операций
.deviceNotSupport	Отключение не поддерживается этим устройством	Проверить возможности устройства перед вызовом

Objective-C

Код ошибки	Описание	Рекомендация по восстановлению
AIBudsSdkErrorCodeDeviceNotConnected	Устройство не подключено	Убедитесь, что устройство спарено и подключено
AIBudsSdkErrorCodeBleCommandExecFailedDueToTimeout	Истекло время ожидания операции	Повторить операцию
AIBudsSdkErrorCodeDeviceBusy	Устройство занято другой операцией	Дождитесь завершения выполняющихся операций
AIBudsSdkErrorCodeDeviceNotSupport	Отключение не поддерживается этим устройством	Проверить возможности устройства перед вызовом

Лучшие практики

1. Подтверждение у пользователя: Всегда отображайте диалог подтверждения перед началом отключения, так как эта операция отключит устройство и потребует повторного подключения.

2. Обработка фонового выполнения: При обновлении UI заверните callback в блок DispatchQueue.main.async.

3. Слабая ссылка на self: Используйте [weak self] в callback, чтобы избежать утечек памяти.

4. Проверка соответствия протоколу: Перед вызовом метода убедитесь, что устройство соответствует протоколу DeviceCommonAPI.

5. Обработка отключения: После успешного отключения устройства корректно обработайте его отключение и предоставьте рекомендации по повторному подключению.

Ограничения платформы

Ограничение системного Bluetooth в iOS

В iOS системные настройки Bluetooth не позволяют приложениям программно отключать Bluetooth-устройства. Это ограничение на уровне системы, установленное Apple по соображениям безопасности и контроля пользователей.

Что это означает:

• После вызова unpair iOS по-прежнему будет хранить информацию о BLE-связывании устройства
• Устройство может автоматически переподключиться при перезапуске приложения или включении Bluetooth
• Устройство останется видимым в iOS Настройки > Bluetooth

Рекомендуемые инструкции для пользователя:

При реализации функции отключения в приложении iOS вы должны направлять пользователей к ручному отключению через настройки iOS:

1. Для полного отключения: Направьте пользователя в Настройки > Bluetooth, найдите устройство, нажмите значок "i", затем выберите "Забыть это устройство"
2. Обеспечьте четкую обратную связь в UI: Покажите пользователям инструкции или глубокую ссылку на настройки Bluetooth при запросе на отключение
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];
}

Примечания

• После выполнения команды отключения устройство отключится
• Для повторного подключения устройства потребуется повторная синхронизация
• Все данные о подключении будут удалены с обоих устройств
• Любые выполняющиеся операции будут прерваны
• Отключение может занять несколько секунд