Complete reference documentation for all public types, properties, and methods in WatchConnectivitySwift.

• WatchConnection
• WatchRequest Protocol
• FireAndForgetRequest Protocol
• SharedState
• FileTransfer
• ReceivedFile
• DeliveryStrategy
• DeliveryMode
• RetryPolicy
• WatchConnectionError
• SessionHealth
• DiagnosticEvent
• WCSessionProviding Protocol

The main entry point for watch connectivity communication.

@MainActor
public final class WatchConnection: NSObject, ObservableObject

public init(
    session: any WCSessionProviding = WCSession.default,
    encoder: JSONEncoder = JSONEncoder(),
    decoder: JSONDecoder = JSONDecoder()
)

Parameters:

• session: The WCSession to use. Defaults to WCSession.default.
• encoder: JSON encoder for serializing requests.
• decoder: JSON decoder for deserializing responses.

Sends a request and returns the typed response.

public func send<R: WatchRequest>(
    _ request: R,
    strategy: DeliveryStrategy = .messageWithUserInfoFallback,
    delivery: DeliveryMode = .queued,
    retryPolicy: RetryPolicy = .default
) async throws -> R.Response

Parameters:

• request: The request to send.
• strategy: Delivery strategy with fallback options.
• delivery: When to deliver if not immediately reachable.
• retryPolicy: Retry and timeout configuration.

Returns: The typed response from the remote device.

Throws: WatchConnectionError if the request fails.

Sends a fire-and-forget request.

public func send<R: FireAndForgetRequest>(
    _ request: R,
    strategy: DeliveryStrategy = .messageWithUserInfoFallback
) async

Parameters:

• request: The fire-and-forget request to send.
• strategy: Delivery strategy.

Registers a handler for a specific request type.

public func register<R: WatchRequest>(
    _ requestType: R.Type,
    handler: @escaping @Sendable (R) async throws -> R.Response
)

Parameters:

• requestType: The type of request to handle.
• handler: An async closure that processes the request.

Activates the connection and attempts to establish connectivity.

public func connect() async

In active mode:

• Queued requests are processed as soon as connectivity is available
• Diagnostic events are emitted for connection attempts

Disconnects and cancels all pending requests.

public func disconnect()

Waits for the session to be activated.

public func waitForActivation(timeout: Duration = .seconds(10)) async throws

Parameters:

• timeout: Maximum time to wait. Defaults to 10 seconds.

Throws: WatchConnectionError.notActivated if activation fails or times out.

Waits for the connection to become ready for messaging.

public func waitForConnection(timeout: Duration? = nil) async throws

Parameters:

• timeout: Maximum time to wait. Pass nil to wait indefinitely.

Throws: WatchConnectionError.notActivated if activation fails, or WatchConnectionError.timeout if the timeout expires.

Sends a request, waiting for connection and retrying on failure.

public func sendWhenReady<R: WatchRequest>(
    _ request: R,
    strategy: DeliveryStrategy = .messageWithUserInfoFallback,
    maxAttempts: Int = 3,
    connectionTimeout: Duration = .seconds(30)
) async throws -> R.Response

Parameters:

• request: The request to send.
• strategy: Delivery strategy with fallback options.
• maxAttempts: Maximum number of connection attempts. Defaults to 3.
• connectionTimeout: Maximum time to wait for each connection attempt.

Returns: The typed response from the remote device.

Throws: WatchConnectionError if all attempts fail.

Cancels all queued requests.

public func cancelAllQueuedRequests()

Cancels a specific queued request.

public func cancelQueuedRequest(id: UUID)

Attempts to recover from a degraded or unhealthy session.

public func attemptRecovery() async

Transfers a file to the counterpart device.

@discardableResult
public func transferFile(
    _ fileURL: URL,
    metadata: [String: Any]? = nil
) async throws -> FileTransfer

Parameters:

• fileURL: The URL of the file to transfer. Must be a local file URL.
• metadata: Optional metadata dictionary (property list types only).

Returns: A FileTransfer object for tracking progress or cancellation.

Throws: WatchConnectionError.fileNotFound if the file doesn't exist.

Cancels all pending file transfers.

public func cancelAllFileTransfers()

Base protocol for all watch connectivity requests.

public protocol WatchRequest: Codable, Sendable {
    associatedtype Response: Codable & Sendable
}

struct FetchUserRequest: WatchRequest {
    typealias Response = User
    let userID: String
}

Marker protocol for requests that don't need a response.

public protocol FireAndForgetRequest: WatchRequest where Response == VoidResponse

struct LogEventRequest: FireAndForgetRequest {
    let eventName: String
    let parameters: [String: String]
}

A synchronized state container for sharing data between devices via applicationContext.

@Observable
@MainActor
public final class SharedState<State: Codable & Sendable & Equatable>

Uses Swift's @Observable macro for seamless nested observation in SwiftUI.

public init(
    initialValue: State,
    connection: WatchConnection,
    encoder: JSONEncoder = JSONEncoder(),
    decoder: JSONDecoder = JSONDecoder()
)

Parameters:

• initialValue: The initial state value.
• connection: The WatchConnection instance to use for synchronization.
• encoder: JSON encoder for serializing state.
• decoder: JSON decoder for deserializing state.

Updates the state and synchronizes to the counterpart device.

public func update(_ newValue: State) throws

Throws: WatchConnectionError.encodingFailed if serialization fails.

Represents an in-progress file transfer to the counterpart device.

@MainActor
public final class FileTransfer: ObservableObject, Sendable, Identifiable

Cancels the file transfer.

public func cancel()

Waits for the transfer to complete.

public func waitForCompletion() async throws

Throws: WatchConnectionError if the transfer fails.

let transfer = try await connection.transferFile(fileURL, metadata: ["type": "backup"])

// Track progress
for await progress in transfer.progressUpdates {
    print("Progress: \(Int(progress * 100))%")
}

// Or wait for completion
try await transfer.waitForCompletion()

// Or cancel
transfer.cancel()

A file received from the counterpart device.

public struct ReceivedFile: @unchecked Sendable

The file at fileURL will be deleted by the system after the receive handler returns. You must synchronously move or copy the file to a permanent location if you want to keep it.

connection.onFileReceived = { file in
    let documents = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
    let destination = documents.appendingPathComponent(file.fileURL.lastPathComponent)
    try? FileManager.default.moveItem(at: file.fileURL, to: destination)

    if let id = file.metadata?["id"] as? String {
        print("Received file with ID: \(id)")
    }
}

Strategy for delivering messages with fallback options.

public enum DeliveryStrategy: String, Sendable, Hashable, Codable

Controls when a request should be delivered.

public enum DeliveryMode: Sendable, Hashable

Configuration for retry behavior.

public struct RetryPolicy: Sendable

public init(maxAttempts: Int, timeout: Duration = .seconds(10))

Parameters:

• maxAttempts: Maximum number of attempts (including the initial attempt).
• timeout: Maximum total time before timeout.

Retries use a fixed 200ms delay between attempts. The library automatically retries on transient errors (.notReachable, .deliveryFailed, .replyFailed).

Errors that can occur during watch connectivity operations.

public enum WatchConnectionError: Error, Codable, Sendable, Hashable

public init(wcError: WCError)
public init(error: Error)

Health state of the WCSession connection.

public enum SessionHealth: Sendable, Hashable, Equatable

Events emitted for debugging and monitoring.

public enum DiagnosticEvent: Sendable

Protocol for WCSession abstraction (for testing).

public protocol WCSessionProviding: AnyObject, Sendable

• WCSession (via extension)
• MockWCSession (for testing)
• FlakyWCSession (for reliability testing)

Response type for fire-and-forget requests.

public struct VoidResponse: Codable, Sendable, Hashable {
    public init()
}

Underlying WCSession delivery method.

public enum DeliveryMethod: String, Sendable, Hashable, Codable {
    case message   // sendMessageData
    case userInfo  // transferUserInfo
    case context   // applicationContext
}

User-facing suggestions for recovering from connectivity issues.

public enum RecoverySuggestion: String, Sendable, Hashable, CaseIterable {
    case openCompanionApp
    case restartWatch

    public var localizedDescription: String
}

Note: Recovery suggestions use Swift String Catalogs for localization.