Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Configuring Your Xcode Project

You distribute your Watch app inside your corresponding iOS app. You can add a Watch app to an existing iOS project, or create a new iOS project that includes a Watch app. In both cases, Xcode automatically configures targets for the Watch app and WatchKit extension bundles and their initial resources. (Both bundles are required.) Those bundles are then delivered as part of your iOS app on the App Store.

The Watch app and WatchKit extension targets provided by Xcode contain everything you need to get started creating your Watch app, complications, and custom notification interfaces. Additionally, the iOS Simulator provides you with a runtime environment for testing the appearance and behavior of all of your interfaces. For testing, the Simulator supports running your Watch app side-by-side with your iOS app and debugging both processes at the same time. This is particularly useful for testing communication between the Watch app and iOS app.

To add a Watch app to your existing iOS app project
  1. In Xcode, open the project for your iOS app.

  2. Choose File > New > Target, and navigate to the watchOS section.

  3. Select WatchKit App, then click Next.

  4. In the next sheet, enter a product name for the target.

  5. If you plan to implement a custom notification or complication, select the appropriate checkboxes.

    The Include Notification Scene checkbox is selected by default. It is recommended that you leave this checkbox selected, even if you do not plan on implementing notifications right away. Selecting the checkbox adds an additional file to your project for debugging your notification interfaces. If you do not select that option, later you must create the file manually.

  6. Click Finish.

To create a new Watch app project
  1. In Xcode, select File > New > Project.

  2. Navigate to the watchOS section.

  3. Select iOS App with WatchKit App, and then click Next.

  4. Enter a product name for the project.

  5. If you plan to implement a custom notification or complication, select the appropriate checkboxes.

    The Include Notification Scene checkbox is selected by default. It is recommended that you leave this checkbox selected, even if you do not plan on implementing notifications right away. Selecting the checkbox adds an additional file to your project for debugging your notification interfaces. If you do not select that option, later you must create the file manually.

  6. Click Finish.

Xcode configures the targets for your Watch app and WatchKit extension and adds the needed files to your iOS project. The bundle IDs for both new targets are configured automatically, based on the iOS app’s bundle ID. The root of the Watch app and WatchKit extension’s bundle IDs must match the iOS app’s bundle ID.

App Target Structure

Adding a Watch app to your Xcode project configures two new executables and updates your project’s build dependencies. Building your iOS app builds all three executables (the iOS app, Watch app, and WatchKit extension) and packages them together inside the iOS app’s bundle.

Figure 2-1 illustrates the structure of your iOS app and watchOS executables. The iOS app contains the Watch app, which then contains the WatchKit extension. When the user installs your iOS app on their iPhone, the system installs the Watch app (including the WatchKit extension) on the user’s Apple Watch, if present. iOS handles the installation process automatically and requires no further work on your part.

Figure 2-1Target structure in watchOS image: ../Art/target_structure.png

Building, Running, and Debugging Your Watch App

Xcode provides a build scheme to run and debug your Watch app. Use that scheme to launch and run your app in iOS Simulator or on a device. If you asked Xcode to configure a custom notification interface or complication when adding the Watch app to your project, there are also build schemes for running those interfaces as well. If you did not initially ask Xcode to configure those interfaces, you must configure additional build schemes manually to facilitate running and testing them.

To configure custom build schemes for notifications or complications
  1. Select your existing Watch app scheme.

  2. From the Scheme menu, select Edit Scheme. image: ../Art/edit_scheme_menu_2x.png

  3. Duplicate your existing Watch app scheme, and give the new scheme an appropriate name.

    For example, give it a name like “Notification - My Watch app” to indicate that the scheme is specifically for running and debugging your notification.

  4. Select Run in the left column of the scheme editor.

  5. In the Info tab, select the appropriate Watch Interface for the new scheme. image: ../Art/duplicate_scheme_2x.png

  6. If you are creating a build scheme for your notification interfaces, specify a JSON file to use as the notification payload during testing. For more information about notification payloads, see To configure custom build schemes for notifications or complications.

  7. Close the scheme editor to save your changes.

Specifying a Payload for Remote Notification Testing and Debugging

When debugging remote notification interfaces in iOS Simulator, you specify the JSON payload data that you want the system to deliver to your interface during testing. You specify the payload data in a text file with a .apns filename extension. Add that file to your project and select it in the Scheme editor when configuring the build scheme for your notification interface. You can include multiple payload files in your project and either change the payload file of your build scheme or create multiple build schemes to facilitate your testing.

The PushNotificationPayload.apns file contains most of the keys you need to simulate a remote notification, and you can add more keys as needed. Note shows the default JSON file that comes with your project.

Figure 2-2A simulated remote notification payload image: ../Art/PushNotificationPayload.apns_2x.png

Most of the JSON data is packaged into a dictionary and delivered to your code at runtime. Because iOS Simulator does not have access to your iOS app’s registered actions, use the payload file to specify the action buttons to display in your interface. The WatchKit Simulator Actions key contains an array of dictionaries, each of which represents an action button to add to your interface. Each dictionary can contain the following keys:

  • title—(Required.) The value of this key is the title of the action button.

  • identifier—(Required.) The value of this key is a string that identifies the action selected by the user. When the user taps the button, the system calls your notification center delegate’s userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: method. The system assigns the value of this key to the actionIdentifier property of the UNNotificationResponse object passed to this method.

  • behavior—(Optional.) The only valid value for this key is the string textInput. If this key is present, the resulting button triggers text input.

  • destructive—(Optional.) The value of this key is the value 1 or 0, where 1 causes the resulting button to be rendered in a way that indicates it performs a destructive action. The value 0 causes the button to be rendered normally.

  • background—(Optional.) The value of this key is the value 1 or 0, where 1 causes the button to launch the app in the background. The value 0 launches the app in the foreground, as usual.

To test your notification interface with the JSON payload, configure the build scheme with the appropriate payload file. When you select a notification interface executable, Xcode adds a menu for choosing one of your payload files. You can create different build schemes for different notification payloads, or you can update the payload file for an existing build scheme before testing.

For information about the keys and values to include in your remote notification payloads, see Local and Remote Notification Programming Guide.