Communicator

• Introduction
• Quick start
• Usage
  • Communicator
  • ImmediateMessage
  • InteractiveImmediateMessage
  • GuaranteedMessage
  • Blob
  • Context
  • WatchState
  • PhoneState
  • ComplicationInfo
• Example
• Requirements
• Installation
  • SPM
  • Cocoapods
• Author
• License

Introduction

Sending messages and data between watchOS and iOS apps is possible thanks to Apple's work on WatchConnectivity, however there are a lot of delegate callbacks to work with, some of the API calls are quite similar and it's not really clear which is needed and for what purpose.

Communicator tries to clear all this up, handles a lot of stuff for you, and it's extremely easy to use.

Communicator supports watch switching out-the-box, uses closures rather than delegate functions, and allows multiple places in your app to react to messages and events.

Quick start

Each app gets its own shared Communicator object to use which handles all the underlying session stuff:

Communicator.shared

Usage between the two platforms is essentially identical.

Here's how you send a simple message with Communicator:

let message = ImmediateMessage(identifier: "1234", content: ["messageKey" : "This is some message content!"])
Communicator.shared.send(message)

This will try to send a message to the counterpart immediately. If the receiving app is not appropriately reachable, the message sending will fail, but you can query this any time:

switch Communicator.shared.currentReachability {
  case .immediateMessaging: Communicator.shared.send(message)
  default: break
}

On the other device you register as an observer for new messages as early on as possible in your app's launch cycle:

ImmediateMessage.observe { message in
  guard message.identifier == "1234" else { return }
  print("Message received!", message)
}

You can observe these messages from anywhere in your app and filter out the ones you don't care about. Anything that can change or be received in Communicator, including Reachability and WatchState, is observable using the same syntax, just calling observe on the type you want to observe:

Reachability.observe { reachability in
  print("Reachability changed!", reachability)
}

Additionally, you can unobserve at any time:

let observation = Reachability.observe { _ in }
/// ...
Reachability.unobserve(observation)

Communicator can also transfer GuaranteedMessages, data Blobs and also sync Contexts.

GuaranteedMessages are similar to ImmediateMessages and InteractiveImmediateMessages, in that they have an identifier, but they don't support reply handlers and can be sent when the reachability state is at least .backgroundOnly, and will continue to transfer even if your app is terminated during transfer.

Blobs are perfect for sending larger amounts of data (WatchConnectivity will reject large data in any other message type), can be sent when the reachability state is at least .backgroundOnly, and will continue to transfer even if your app is terminated during transfer.

You can use a Context to keep things in sync between devices, which makes it perfect for preferences. Contexts are not suitable for messaging or sending large data. Sending or receiving a Context overwrites any previously sent Context, which you can query any time with Communicator.shared.mostRecentlySentContext and Communicator.shared.mostRecentlyReceivedContext

Lastly, you can update your watchOS complication from your iOS app by transferring a ComplicationInfo. You get a limited number of ComplicationInfo transfers a day, and you can easily query the remaining number of transfers available by getting the currentWatchState object.

If you have transfers available, your watch app is woken up in the background to process the ComplicationInfo.

NOTE: You app must have a complication added to the user's active watch face to be able to wake your watch up in the background, and the number of transfers available must not be 0.

Usage

Communicator

Each app has its own shared Communicator object which it should use to communicate with the counterpart app.

Communicator.shared

The APIs between iOS and watchOS are almost identical.

The first time you access the .shared instance, Communicator will do what it needs to in order to activate the underlying session and report any received messages/data etc.

This means you should access the shared instance as early on as possible in your app's lifecycle, but also observe any changes as soon as possible to avoid losing data:

Reachability.observe { reachability in
  // Handle reachability change
}
ImmediateMessage.observe { message in
  // Handle immediate message
}
GuaranteedMessage.observe { message in
  // Handle guaranteed message
}

NOTE: Observing any type will impliclty access the .shared instance, so you only need to observe things for Communicator to activate the underlying session.

Querying the current reachability

Before sending any messages or data you should check the current reachability of the counterpart app. This can change as the user switches watches, installs your app or backgrounds your app.

Additionally, since watchOS 6, it's possible to install a watch app without installing the iOS app, which Communicator takes into account.

You can query the current reachability at any time:

let reachability = Communicator.shared.currentReachability

You can also observe and react to reachability changes:

Reachability.observe { reachability in
  // Handle reachability change
}

Different types of communication require a different minimum level of reachability. I.e. ImmediateMessage and InteractiveImmediateMessage require .immediatelyReachable, but GuaranteedMessage, Blob, Context, and ComplicationInfo require at least .backgroundOnly (although can still be sent when .immediatelyReachable).

Querying the current activation state

You can query the current activation state of Communicator at any time:

let state = Communicator.shared.currentState

You can also observe state changes:

Communicator.State.observe { state in
 // Handle new state
}

The state can change as the user switches watches. Generally, you won't need to use this state and instead should query the reachability, which takes into account whether the counterpart app is currently installed.

Querying the current state of the counterpart device

You can query the state of the user's paired watch at any time:

let watchState = Communicator.shared.currentWatchState

You can also observe state changes:

WatchState.observe { state in
 // Handle new state
}

The watch state provides information like whether the watch is paired, your app is installed, a complication is added to the active watch face, and more.

Additionally, you can query the state of the iPhone from the watchOS app, since iOS 6 users can install your watch app without installing the iOS app:

let phoneState = Communicator.shared.currentPhoneState

And like all other states you can observe changes:

PhoneState.observe { state in
  // Handle new state
}

ImmediateMessage

An ImmediateMessage is a simple object comprising of an identifier string of your choosing, and a JSON dictionary as content.

The keys of the JSON dictionary must be strings, and the values must be plist-types. That means anything you can save to UserDefaults; String, Int, Data etc. You cannot send large amounts of data between devices using a ImmediateMessage because the system will reject it. Instead, use a Blob for sending large amounts of data.

This is how you create a simple ImmediateMessage:

let content: Content = ["TotalDistanceTravelled" : 10000.00]
let message = ImmediateMessage(identifier: "JourneyComplete", content: json)

And this is how you send it:

Communicator.shared.send(message) { error in
  // Handle error
}

This works well for rapid, interactive communication between two devices, but is limited to small amounts of data and will fail if either of the devices becomes unreachable during communication.

If you send this from watchOS it will also wake up your iOS app in the background if it needs to so long as the current Reachability is .immediatelyReachable.

On the receiving device you listen for new messages:

ImmediateMessage.observe { message in
  if message.identifier == "JourneyComplete" {
    // Handle message
  }
}

NOTE: The value of Communicator.currentReachability must be .immediatelyReachable otherwise an error will occur which you can catch by assigning an error handler when sending the message.

InteractiveImmediateMessage

An InteractiveImmediateMessage is similar to a regular ImmediateMessage but it additionally takes a reply handler that you must execute yourself on the receiving device. Once you execute the handler on the receiving device, it is called by the system on the sending device.

This provides a means for extremely fast communication between devices, but like an ImmediateMessage, the reachability must be .immediatelyReachable during both the send and the reply.

On the sending device, send the message:

let message = InteractiveImmediateMessage(identifier: "message", content: ["hello": "world"])
Communicator.shared.send(message) { error in

}

And on the receiving device, listen for the message and execute the reply handler:

InteractiveImmediateMessage.observe { message in
  guard message.identifier == "message" else { return }
  let replyMessage = ImmediateMessage("identifier", content: ["reply": "message"])
  message.reply(replyMessage)
}

Like an ImmediateMessage, if you send this from your watch app the system will wake your iOS app up in the background if needed, so long as the current reachability is .immediatelyReachable.

GuaranteedMessage

You can also choose to send a message using the "guaranteed" method. GuaranteedMessages don't have a reply handler because messages can be queued while the receiving device is not currently receiving messages, meaning they're queued until the session is next created:

let content: Content = ["CaloriesBurnt" : 400.00]
let message = GuaranteedMessage(identifier: "WorkoutComplete", content: content)
Communicator.shared.send(message) { result in
  // Handle success or failure
}

Because the messages are queued, they could be received in a stream on the receiving device when it's able to process them. You should make sure your observers are set up as soon as possible to avoid missing any messages, i.e. in your AppDelegate or ExtensionDelegate:

GuaranteedMessage.observe { message in
  if message.identifier == "CaloriesBurnt" {
    let content = message.content
    // Handle message
  }
}

NOTE: On watchOS, receiving a GuaranteedMessage while in the background can cause the system to generate a WKWatchConnectivityRefreshBackgroundTask. If you assign this to the Communicator's task property, Communicator will automatically handle ending the task for you at the right time.

The value of Communicator.currentReachability must not be .notReachable otherwise an error will occur.

Blob

A Blob is very similar to a GuaranteedMessage but is better suited to sending larger bits of data. A Blob is created with an identifier but instead of assigning a JSON dictionary as the content, you assign pure Data instead.

This is how you create a Blob:

let largeData: Data = getJourneyHistoryData()
let blob = Blob(identifier: "JourneyHistory", content: largeData)

And this is how you transfer it to the other device:

Communicator.shared.transfer(blob: blob) { result in
  // Handle success or failure
}

Because a Blob can be much larger than a Message, it might take significantly longer to send. The system handles this, and continues to send it even if the sending device becomes unreachable before it has completed.

On the receiving device you listen for new Blobs. Because these Blobs can often be queued waiting for the session to start again, Communicator will often notify observers very early on. This makes it a good idea to start observing for Blobs as soon as possible, i.e. in the AppDelegate or ExtensionDelegate:

Blob.observe { blob in
  if blob.identifier == "JourneyHistory" {
    let JourneyHistoryData: Data = blob.content
    // ... do something with the data ... //
  }
}

Additionally, you can also attach some metadata to a Blob, by passing in a dictionary of plist values when creating the Blob:

let metadata = ["DateGenerated": Date()]
let blobWithMetadata = Blob(identifier: "JourneyHistory", content: data, metadata: metadata)

And then on the receiving device you can query the metadata on the received Blob:

Blob.observe { blob in
    print(blob.metadata)
}

NOTE: On watchOS, receiving a Blob while in the background can cause the system to generate a WKWatchConnectivityRefreshBackgroundTask. If you assign this to the Communicator's task property, Communicator will automatically handle ending the task for you at the right time.

The value of Communicator.currentReachability must not be .notReachable otherwise an error will occur.

Context

A Context is a very lightweight object. A Context can be sent and received by either device, and the system stores the last sent/received Context that you can query at any time. This makes it ideal for syncing lightweight things like preferences between devices.

A Context has no identifier, and simply takes a JSON dictionary as content. Like an ImmediateMessage, this content must be primitive types like String, Int, Data etc, and must not be too large or the system will reject it:

let content: Content = ["ShowTotalDistance" : true]
let context = Context(content: content)
do {
  try Communicator.shared.sync(context)
} catch {
  // Handle error
}

You can also query the last sent context from either device:

let context = Communicator.shared.mostRecentlySentContext

On the receiving device you listen for new Contexts:

Content.observe { context in
  if let shouldShowTotalDistance = context.content["ShowTotalDistance"] as? Bool {
    print("Show total distance setting changed: \(shouldShowTotalDistance)")
  }
}

You can also query the last received context from either device:

let context = Communicator.shared.mostRecentlyReceivedContext

NOTE: On watchOS, receiving a Context while in the background can cause the system to generate a WKWatchConnectivityRefreshBackgroundTask. If you assign this to the Communicator's task property, Communicator will automatically handle ending the task for you at the right time.

The value of Communicator.currentReachability must not be .notReachable otherwise an error will be thrown.

WatchState

WatchState is one of the only iOS-only elements of Communicator. It provides some information about the current state of the user's paired watch or watches, like whether a complication has been enabled or whether the watch app has been installed.

You can observe any changes in the WatchState on iOS:

WatchState.observe { state in
  // Handle watch state
}

You can also query the current WatchState at any time from the iOS Communicator:

let watchState = Communicator.shared.currentWatchState

You can use WatchState retrieve a URL which points to a directory on the iOS device specific to the currently paired watch.

You can use this directory to store things specific to that watch, which you don't want associated with the user's other watches. This directory (and anything in it) is automatically deleted by the system if the user uninstalls your watchOS app or unpairs their watch.

PhoneState

PhoneState is similar to the WatchState but is queried from the watch's side instead.

Since watchOS 6, users can install watch apps without installing the iOS app, and you can use PhoneState to determine this.

ComplicationInfo

A ComplicationInfo can only be sent from an iOS device, and can only be received on a watchOS device. Its purpose is to wake the watchOS app in the background to process the data and update its complication. At the time of writing your iOS app can do this 50 times a day, and you can query the currentWatchState of the shared Communicator object on iOS to find out how many remaining updates you have left.

Just like a Context, a ComplicationInfo has no identifier and its content is a JSON dictionary:

let content: Content = ["NumberOfStepsWalked" : 1000]
let complicationInfo = ComplicationInfo(content: content)

And you send it from the iOS app like this:

Communicator.shared.transfer(complicationInfo) { result in
  // Handle success or failure
}

Upon successful transfer, the success case in the result provides the remaining complication updates available that day.

On the watchOS side you observe new ComplicationInfos being received. Just like other transfers that may happen in the background, it's a good idea to observe these early on, like in the ExtensionDelegate:

ComplicationInfo.observe { complicationInfo in
  // Handle update
}

The value of Communicator.currentReachability must not be .notReachable otherwise an error will be thrown.

NOTE: On watchOS, receiving a ComplicationInfo while in the background can cause the system to generate a WKWatchConnectivityRefreshBackgroundTask. If you assign this to the Communicator's task property, Communicator will automatically handle ending the task for you at the right time.

Example

To run the example project, clone the repo, and run pod install from the Example directory first.

The watchOS and iOS example apps set up observers for new Messages, Blobs, reachability changes etc and prints out any changes to the console. They set up these observers early on in the app, which is recommended for state changes and observers of things that may have transferred while the app was terminated, like Blobs.

Try running each target and seeing the output when you interact with the buttons.

Requirements

Communicator relies on WatchConnectivity, Apple's framework for communicating between iOS and watchOS apps, but has no external dependencies.

Communicator requires iOS 10.0 and newer and watchOS 3.0 and newer.

Installation

Swift Package Manager

Communicator supports SPM, simply add Communicator as a package dependency in Xcode 11 or newer.

Cocoapods

Add the following line to your Podfile and then run pod install in Terminal:

pod "Communicator"

Author

Kane Cheshire, @kanecheshire

License

Communicator is available under the MIT license. See the LICENSE file for more info.