Report iPhone Found

Respond to a device-originated find-iPhone request, manage the iPhone-side alert in your app, and notify the requesting device after the user locates the iPhone.

This is the opposite direction from Find Device: the connected device initiates this flow, while the host app owns the sound, vibration, or UI used to locate the iPhone.

Prerequisites

Before reporting that the iPhone was found, ensure:

• The requesting device remains connected and ready.
• Your app observes deviceDidRequestStartFindingPhone and deviceDidRequestStopFindingPhone, or the corresponding SDKDelegate callbacks.
• The device supports FindPhoneStateReportingAPI.
• The app has stopped its iPhone-side indication after the user confirms that the iPhone was found.

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

Protocol

The notifyPhoneFound method is defined in 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

Instance Method

Notifies the connected device that the user has found the 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;

See notifyPhoneFound in the API Reference.

Parameters

Parameter	Type	Description
completion	AIBudsCompletionHandler?	Optional handler called when report delivery and command processing complete.

Callback Parameters:

Name	Type	Description
success	Bool / BOOL	true when the device accepted the iPhone-found report; otherwise false.
error	NSError?	The command or communication error, or nil on success.

Return Value

This method does not return a value directly. Its completion reports delivery of the resolution to the requesting device; it does not initiate a new find-iPhone request.

Usage Examples

Observe the device-originated start and stop requests. When the user confirms that the iPhone has been located, stop the iPhone-side alert before reporting resolution.

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");
    }];
}

Error Handling

Keep the iPhone-side alert state independent from report delivery. Stop the alert immediately when the device requests it or the user confirms that the iPhone was found, then surface any notifyPhoneFound communication error without restarting the alert automatically.

Best Practices

1. React to Device Requests: Start the iPhone-side indication only after the corresponding delegate callback.
2. Own the iPhone Experience: Implement sound, vibration, permissions, background behavior, and UI in the host app.
3. Stop Before Reporting: Stop local alert resources before calling notifyPhoneFound(_:).
4. Retain the Requesting Device: Send the report to the same connected device that initiated the request.
5. Update UI on the Main Queue: Dispatch UIKit work from delegate and completion callbacks to the main queue.

Notes

• notifyPhoneFound(_:) acknowledges resolution; it does not start a find-iPhone operation.
• A device-originated stop request means the app should stop its iPhone-side indication. It is separate from a user-confirmed iPhone-found report.
• Use DeviceFindAPI when the app needs the connected device itself to present a locate indication.