恢复出厂设置

恢复出厂设置操作可将设备恢复到原始出厂状态，擦除所有用户数据和自定义配置。此操作在准备转售设备或排查持续性问题时非常有用。

前置条件

执行恢复出厂设置前，请确保：

• 设备已连接且处于稳定状态
• 所有重要数据已备份
• 用户已了解所有个人数据将被擦除

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“实现 AIBuds 恢复出厂设置”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/implement-aibuds-factory-reset，使用该技能在当前 iOS 项目中完成“实现 AIBuds 恢复出厂设置”，并验证结果。

查看官方技能↗

API 参考

框架

AIBuds.xcframework

导入

在使用 SDK 的文件中，导入主头文件：

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

factoryReset 方法定义在以下协议中。该协议继承自基础设备 API 协议。

Swift

Swift

/// Defines common device operations including factory reset
protocol DeviceCommonAPI: DeviceAPI {
    /// Factory reset
    /// - Parameters:
    ///   - completion: Completion callback that returns the operation result
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func factoryReset(_ completion: AIBudsCompletionHandler?)
}

Objective-C

Objective-C

/// Defines common device operations including factory reset
@protocol AIBudsDeviceCommonAPI <AIBudsDeviceAPI>
/// Factory reset
/// - Parameters:
///   - completion: Completion callback that returns the operation result
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)factoryResetWithCompletion:(AIBudsCompletionHandler)completion;
@end

实例方法

将设备恢复到原始出厂设置，擦除所有用户数据和自定义配置。

iOS 13.0+

Swift

Swift

/// Factory reset
/// - Parameters:
///   - completion: Completion callback that returns the operation result
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func factoryReset(_ completion: AIBudsCompletionHandler?)

Objective-C

Objective-C

/// Factory reset
/// - Parameters:
///   - completion: Completion callback that returns the operation result
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)factoryResetWithCompletion:(AIBudsCompletionHandler)completion;

参数

参数	类型	描述
completion	AIBudsCompletionHandler?	操作完成时调用的可选完成回调。

回调参数：

名称	类型	描述
success	Bool	操作成功则为 true，否则为 false。
error	NSError?	操作失败时包含错误信息，操作成功则为 nil。

返回值

此方法不直接返回值，结果通过完成回调提供。

使用示例

Swift

Swift

import AIBuds

class DeviceManager {

    /// The connected device
    weak var device: DeviceConvertible?

    /// Performs factory reset on the connected device
    func performFactoryReset() {
        // Ensure the device supports factory reset protocol
        guard let device = device as? DeviceCommonAPI else {
            print("Device does not support factory reset")
            return
        }

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

Objective-C

Objective-C

#import <AIBuds/AIBuds.h>

@interface DeviceManager ()

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

@end

@implementation DeviceManager

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

    id<AIBudsDeviceCommonAPI> device = (id<AIBudsDeviceCommonAPI>)self.device;
    // Ensure the device supports factory reset protocol
    if ([device conformsToProtocol:@protocol(AIBudsDeviceCommonAPI)]) {
        // Execute factory reset with completion handler
        [device factoryResetWithCompletion:^(BOOL success, NSError *_Nullable error) {
            // Handle failure case
            if (!success) {
                NSLog(@"Factory reset failed: %@", error);
                return;
            }
            // Handle success case
            NSLog(@"Factory reset 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. 清理引用：成功恢复出厂设置后，可能需要重新配对设备。

注意事项

• 恢复出厂设置可能需要几秒钟才能完成
• 设备在此操作期间将断开连接并重置
• 所有用户数据（包括已配对设备、设置和存储的媒体）将被擦除
• 复位完成后设备将自动重启