Managing the Watch App Life Cycle

The extension delegate manages the life cycle events of your app. When the user launches your app, WatchKit notifies the extension delegate at various points as the app transitions to and from different states. Figure 5-1 shows the state transitions that occur and the methods of the WKExtensionDelegate protocol that are called for each transition. Use these methods to prepare your app’s data structures, check for data from the counterpart iOS app, and initiate requests for any new data.

Figure 5-1The life cycle of a Watch app

At launch time, a Watch app normally transitions from the inactive state directly to the active state. It transitions back to the inactive state when the user exits the app, and at some point later may transition quietly to the not-running state. The delivery of life cycle events may be intermixed with the delivery of activation and deactivation events to the app’s interface controllers, and the order of delivery is not guaranteed. In other words, the willActivate method of an interface controller may be called before or after the applicationDidBecomeActive method of the extension delegate.

Updating Your Notification Action Handler Code

When implementing support for actionable notifications, you now implement a response to button taps in the extension delegate and not in your app’s main interface controller. Actionable notifications provide quick responses for notifications. For example, a meeting invitation might include buttons to accept or decline the invitation. When the user taps one of those buttons, the action information is sent to the extension delegate. Specifically, WatchKit calls one of the following methods:

• For remote notifications, WatchKit calls the handleActionWithIdentifier:forRemoteNotification: or handleActionWithIdentifier:forRemoteNotification:withResponseInfo: method.

• For local notifications, WatchKit calls the handleActionWithIdentifier:forLocalNotification: or handleActionWithIdentifier:forLocalNotification:withResponseInfo: method.

The specific method called by WatchKit depends on whether the action included a text response from the user. Support for text responses is new in watchOS 2 and iOS 9. To add that support, add the UIUserNotificationActionBehaviorTextInput value to the behavior property of the UIUserNotificationAction that you create on iOS. When enabled, the user can dictate a text response or select from a set of predefined messages. The string representing the selected response is provided to your handler block along with the other notification information. You can then incorporate that string into any actions that handle the notification. For example, if the user declined a meeting invite, you can add the text response to the invite so that the originator knows why the user declined.

If a notification arrives while the user is interacting with your Watch app, WatchKit delivers the notification to the didReceiveRemoteNotification: or didReceiveLocalNotification: method of your extension delegate. You can use these methods to refresh your interface or take other actions based on the data in the notification.

Activating the Session Object

Early in the life of your iOS app and WatchKit extension, you must configure and activate the default WCSession object. The session object is the focal point for sending and receiving data. It is a singleton object that you typically configure at launch time. To configure the object, assign a delegate object to it. The delegate is a custom object that conforms to the WCSessionDelegate protocol. You use the methods of this protocol to receive data and to handle errors.

After assigning your delegate to the default session object, activate the session by calling its activateSession method. Activating the session registers it with the Watch Connectivity framework and lets you start using the other methods and properties of the WCSession class.

Listing 5-1 shows a standard example of how to configure and activate your session object. In the example, self is an object that conforms to the WCSessionDelegate protocol and receives any incoming messages. You can use this code in both your iOS app and your WatchKit extension.

After your iOS app activates the session object, check to see if an Apple Watch is paired and ready for communication before taking further actions. If the user does not have a paired Apple Watch or did not install your app, the paired and watchAppInstalled properties of the WCSession object reflect those facts. If a watch is paired and installed, your iOS app can send background messages to your Watch app. When the reachable property is YEStrue, you can also send foreground messages.

Use your delegate object to detect changes to the paired and reachable state of the other process. When the paired or watchAppInstalled property changes, the Watch Connectivity framework calls your delegate’s sessionWatchStateDidChange: method. When the reachable property changes, the framework similarly calls the sessionReachabilityDidChange: method. Use these methods to update your app’s behavior to accommodate for the changes. For example, update your app so that when an Apple Watch becomes reachable, you can send it a foreground message with fresh data.

For more information about the delegate methods and how you implement them, see WCSessionDelegate Protocol Reference.

Choosing the Right Communication Option

The Watch Connectivity framework offers several options for sending data between your iOS app and WatchKit extension. Each option is intended for a different usage. Most options perform a one-way transfer of data in the background and are a convenient way to deliver updates. Foreground transfers let your app send a message immediately and wait for a reply. Table 5-1 lists the methods you use for communication and usage guidelines for each.

For most types of transfers, you provide an NSDictionary object with the data you want to send. The keys and values of your dictionary must all be property list types, because the data must be serialized and sent wirelessly. (If you need to include types that are not property list types, package them in an NSData object or write them to a file before sending them.) In addition, the dictionaries you send should be compact and contain only the data you really need. Keeping your dictionaries small ensures that they are transmitted quickly and do not consume too much power on both devices.

For more information about how to transfer data using the Watch Connectivity framework, see Watch Connectivity Framework Reference.

Guidelines for Communicating Between Apps

Here are some guidelines to consider when adding support for Watch Connectivity to your app:

• Use Background App Refresh to push new data to your Watch app. If your iOS app wakes up periodically to handle tasks, use some of that time to prepare data and send it to your Watch app using the updateApplicationContext:error: method. This is especially useful for keeping your app’s glance up to date.

• Move files synchronously in your delegate method. The system deletes a file transferred to a device after calling the session:didReceiveFile: method of the appropriate delegate object. Deleting files prevents them from taking up space unnecessarily, but it also means that you must explicitly move files to a new location if you want to keep them.

• Transfer only the data that you need. All transfers involve sending data wirelessly to the counterpart app. Do not waste power by sending data that you do not need.

• Use the application context mode for transient data that changes. The updateApplicationContext:error: method is intended as a way to communicate a snapshot of state information between your Watch app and iOS app. Calling the method a second time replaces data from any previous calls. If you want to ensure the delivery of data, use the transferUserInfo: method to queue the data instead.

• Provide a graceful fallback in the case of errors. Errors can occur if there is insufficient space for the data, if the data is malformed, or if there is a communications error. Check for errors in your handler code and take appropriate actions.

• Remember that background transfers may not be delivered immediately. Files and contextual data are delivered as quickly as possible, but transfers are not instantaneous. Data files involving large files or large amounts of data also take a commensurately long time to complete.