iPhone 発見の通知

デバイスから開始された iPhone 探索要求を処理し、アプリで iPhone 側の通知を管理します。ユーザーが iPhone を見つけたら、要求元のデバイスへ完了を通知します。

これはデバイスを探すとは逆方向の処理です。接続中のデバイスがフローを開始し、iPhone を見つけるための音、振動、UI はホストアプリが管理します。

前提条件

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 リファレンスの notifyPhoneFound を参照してください。

パラメータ

パラメータ	型	説明
completion	AIBudsCompletionHandler?	通知の送信とコマンド処理の完了時に呼び出される任意のハンドラー。

コールバックのパラメータ:

名前	型	説明
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. デバイス要求に応答する: 対応するデリゲートコールバックを受け取った後にのみ、iPhone 側の通知を開始します。
2. iPhone 側の体験を実装する: 音、振動、権限、バックグラウンド動作、UI はホストアプリで実装します。
3. 通知前に停止する: notifyPhoneFound(_:) を呼び出す前に、ローカルのアラートリソースを停止します。
4. 要求元デバイスを保持する: 要求を開始した同じ接続デバイスへ通知を送ります。
5. メインキューで UI を更新する: デリゲートや完了コールバックからの UIKit 処理はメインキューへ切り替えます。

注意事項

• notifyPhoneFound(_:) は完了を通知するためのもので、iPhone 探索を開始しません。
• デバイスから停止要求を受けた場合、アプリは iPhone 側の通知を停止します。これは、ユーザーが確認した iPhone 発見通知とは別の処理です。
• 接続中のデバイス自体に探索通知を出させる場合は、DeviceFindAPI を使用します。