上报已找到 iPhone

响应由设备发起的查找 iPhone 请求，在应用中管理 iPhone 端提示，并在用户找到 iPhone 后通知请求设备。

该流程与查找设备方向相反：由已连接设备发起，宿主 App 负责播放声音、触发振动或显示 UI，帮助用户找到 iPhone。

前提条件

上报已找到 iPhone 前，请确保：

• 发起请求的设备仍处于连接和就绪状态。
• 应用监听 deviceDidRequestStartFindingPhone 和 deviceDidRequestStopFindingPhone，或对应的 SDKDelegate 回调。
• 设备支持 FindPhoneStateReportingAPI。
• 用户确认找到 iPhone 后，应用已经停止 iPhone 端提示。

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

notifyPhoneFound 方法定义在 FindPhoneStateReportingAPI 中。

Swift

Swift

/// Reports to a connected device that its find-phone request has been resolved.
///
/// Find-phone is initiated by the device rather than by this API. Observe
/// `DeviceDelegate.deviceDidRequestStartFindingPhone(_:)` and
/// `DeviceDelegate.deviceDidRequestStopFindingPhone(_:)`, or the corresponding
/// `SDKDelegate` callbacks, to start and stop the app's phone-side alert.
///
/// After the user locates the phone, call `notifyPhoneFound(_:)` to notify the
/// requesting device. To make the connected device itself emit a locate
/// indication, use `DeviceFindAPI` instead.
public protocol FindPhoneStateReportingAPI: DeviceAPI {
    /// Notifies the connected device that the user has found the phone.
    ///
    /// Call this after handling a device-originated find-phone request and
    /// stopping the phone-side alert. The completion reports delivery and
    /// command processing; it does not represent a new find-phone request.
    /// - Parameters:
    ///   - completion: Called when command processing completes.
    ///     - success: `true` when the device accepted the report; otherwise,
    ///       `false`.
    ///     - error: The command or communication error, or `nil` on success.
    func notifyPhoneFound(_ completion: AIBudsCompletionHandler?)
}

Objective-C

Objective-C

/// Reports to a connected device that its find-phone request has been resolved.
///
/// Find-phone is initiated by the device. Observe the device or SDK delegate
/// callbacks to start and stop the app's phone-side alert.
@protocol AIBudsFindPhoneStateReportingAPI <AIBudsDeviceAPI>
/// Notifies the connected device that the user has found the phone.
///
/// Call this after stopping the phone-side alert. The completion reports
/// delivery and command processing; it does not start a new request.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the report; otherwise,
///       `false`.
///     - error: The command or communication error, or `nil` on success.
- (void)notifyPhoneFoundWithCompletion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

通知已连接设备用户已经找到 iPhone。

Swift

Swift

/// Notifies the connected device that the user has found the phone.
///
/// Call this after handling a device-originated find-phone request and
/// stopping the phone-side alert. The completion reports delivery and
/// command processing; it does not represent a new find-phone request.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the report; otherwise,
///       `false`.
///     - error: The command or communication error, or `nil` on success.
func notifyPhoneFound(_ completion: AIBudsCompletionHandler?)

Objective-C

Objective-C

/// Notifies the connected device that the user has found the phone.
///
/// Call this after stopping the phone-side alert. The completion reports
/// delivery and command processing; it does not start a new request.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the report; otherwise,
///       `false`.
///     - error: The command or communication error, or `nil` on success.
- (void)notifyPhoneFoundWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

请在 API Reference 中查看 notifyPhoneFound。

参数

参数	类型	说明
completion	AIBudsCompletionHandler?	上报传输和指令处理完成时调用的可选 Handler。

回调参数：

名称	类型	说明
success	Bool / BOOL	设备接受已找到 iPhone 上报时为 true，否则为 false。
error	NSError?	指令或通信错误；成功时为 nil。

返回值

该方法没有直接返回值。完成回调用于报告解决结果是否传递给请求设备，不会发起新的查找 iPhone 请求。

使用示例

监听设备发起的开始和停止请求。用户确认已经找到 iPhone 时，应先停止 iPhone 端提示，再上报解决结果。

Swift

Swift

import AIBuds

final class FindPhoneCoordinator: NSObject, DeviceDelegate {
    private weak var requestingDevice: DeviceConvertible?

    func deviceDidRequestStartFindingPhone(_ device: DeviceConvertible) {
        requestingDevice = device
        DispatchQueue.main.async {
            self.startPhoneAlert()
        }
    }

    func deviceDidRequestStopFindingPhone(_ device: DeviceConvertible) {
        DispatchQueue.main.async {
            self.stopPhoneAlert()
        }
    }

    func userConfirmedPhoneFound() {
        stopPhoneAlert()

        guard let reporter = requestingDevice as? FindPhoneStateReportingAPI else {
            print("Device cannot receive a phone-found report")
            return
        }

        reporter.notifyPhoneFound { success, error in
            guard success else {
                print(
                    "Failed to report phone found: \(error?.localizedDescription ?? "Unknown error")"
                )
                return
            }
            print("Phone-found report accepted")
        }
    }
}

Objective-C

Objective-C

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

@property(nonatomic, weak) id<AIBudsDeviceConvertible> requestingDevice;

- (void)deviceDidRequestStartFindingPhone:(id<AIBudsDeviceConvertible>)device {
    self.requestingDevice = device;
    dispatch_async(dispatch_get_main_queue(), ^{
        [self startPhoneAlert];
    });
}

- (void)deviceDidRequestStopFindingPhone:(id<AIBudsDeviceConvertible>)device {
    dispatch_async(dispatch_get_main_queue(), ^{
        [self stopPhoneAlert];
    });
}

- (void)userConfirmedPhoneFound {
    [self stopPhoneAlert];

    id<AIBudsFindPhoneStateReportingAPI> reporter =
        (id<AIBudsFindPhoneStateReportingAPI>)self.requestingDevice;
    if (![reporter conformsToProtocol:@protocol(AIBudsFindPhoneStateReportingAPI)]) {
        NSLog(@"Device cannot receive a phone-found report");
        return;
    }

    [reporter notifyPhoneFoundWithCompletion:^(BOOL success, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Failed to report phone found: %@",
                  error.localizedDescription ?: @"Unknown error");
            return;
        }
        NSLog(@"Phone-found report accepted");
    }];
}

错误处理

保持 iPhone 端提示状态与上报传输相互独立。当设备请求停止或用户确认找到 iPhone 时立即停止提示；如果 notifyPhoneFound 发生通信错误，应显示错误，但不要自动重新启动提示。

最佳实践

1. 响应设备请求：仅在收到对应 Delegate 回调后启动 iPhone 端提示。
2. 实现 iPhone 端提示：由宿主 App 负责声音、振动、权限、后台行为和 UI。
3. 先停止再上报：调用 notifyPhoneFound(_:) 前停止本地提示资源。
4. 保留请求设备：将上报发送给发起请求的同一已连接设备。
5. 在主队列更新 UI：将 Delegate 和完成回调中的 UIKit 操作派发到主队列。

注意事项

• notifyPhoneFound(_:) 用于确认请求已经解决，不会启动查找 iPhone 操作。
• 设备发起的停止请求表示应用应停止 iPhone 端提示；它与用户确认找到 iPhone 的上报相互独立。
• 当应用需要已连接设备自身发出定位提示时，请使用 DeviceFindAPI。