Technical Note TN2424

Project Configuration Reference for watchOS 2 Applications

This document discusses the proper configuration of a WatchKit Extension and Watch App when added to an existing Xcode project. Refer to this document if you have made a change to your project which is causing your Watch App to no longer run, or if you are encountering validation errors related to the Watch App when submitting your app.

If you are just getting started with WatchKit, refer to Adding a Watch App to Your iOS Project in the Apple Watch Programming Guide for the steps to add a WatchKit App to your existing project.

The Watch App
The WatchKit Extension
The iOS App
Appendix A: Retrieving Device Logs
Document Revision History

The Watch App

The Watch app is the actual app that the user launches from the Apple Watch home screen. It contains only the resource files associated with your app’s user interface and it works in tandem with your WatchKit extension. The Watch app does not contain any code; instead an Xcode provided binary is inserted into the Watch app bundle at build time. Being an app bundle, the Watch app must have a unique bundle identifier and it must be code signed. During installation the Watch app bundle is copied to the paired watch. The watch validates the bundle's code signature, information property list, and executable. If your Watch app fails to install on the watch, the problem is most likely caused by the incorrect configuration of your Watch app or WatchKit extension target. Additional information about the error which triggered the installation failure is logged to the paired iPhone's console. See Retrieving Device Logs.

Information Property List

The Watch App must have an associated information property list. One is created for you by default when adding a Watch App to your project. By default it can be found under the folder named <Target Name> in the project navigator where <Target Name> is the name of your Watch app. Certain information property list keys are invalid for Watch apps and will produce a verification failure upon install. The offending key will be logged to the paired iPhone's device console.

Figure 1  Information property list for a properly configured WatchKit app target.
  • Bundle Identifier (CFBundleIdentifier): Should be set to $(PRODUCT_BUNDLE_IDENTIFIER).

  • Bundle versions string, short (CFBundleShortVersionString): The value for this key must match the corresponding value in the containing iOS app's information property list.

  • Bundle version (CFBundleVersion): The value for this key must match the corresponding value in the containing iOS app's information property list.

  • WKCompanionAppBundleIdentifier: The value for this key must match the bundle identifier of the containing iOS app.

  • WKWatchKitApp: The value for this key must be YES.

Build Settings

Because the Watch app does not contain any code, most build settings are ignored.

Figure 2  Build settings for a properly configured WatchKit app target.
  • Product Bundle Identifier: Must be a unique reverse DNS string that is prefixed with the containing iOS app's bundle identifier. For example, if your iOS app has the bundle identifier com.example.apple-samplecode.WatchKit-Catalog, then the WatchKit app's bundle identifier should be com.example.apple-samplecode.WatchKit-Catalog.watchkitapp.

  • Architectures: Must be set to Standard architectures (armv7k).

  • Base SDK: Must be set to watchOS 2.0 or Latest watchOS (preferred).

  • Supported Platforms: Must be set to watchOS.

  • Valid Architectures: Must contain armv7k.

  • Enable Bitcode: Must be set to Yes.

  • Info.plist File: Must be the project relative path to the information property list for the Watch app.

  • watchOS Deployment Target: Must be set to 2.0 or later.

  • Asset Catalog App Icon Set Name: Must be set to the name of the app icon set in the asset catalog. The default name is AppIcon.

  • TARGETED_DEVICE_FAMILY: Must be set to 4. This is a User-Defined build setting that is automatically created by the Xcode templates.

  • IBSC_MODULE: Interface Builder uses this setting when compiling storyboards that reference Swift class names. The value must match the Product Module Name of the WatchKit extension. This is a User-Defined build setting that is automatically created by the Xcode templates.

Resources

A storyboard and asset catalog must be associated with your Watch app target. The asset catalog associated with your Watch app target must contain the icons for the Watch app and should not be associated with any other target in your project, to avoid duplicating resources. Additional resources that you want included in the Watch app bundle must either be included in the asset catalog or be associated with the Watch app target.

Figure 3  You can modify the target associations for a resource under the Target Membership pane of the File Inspector.

The WatchKit Extension

The WatchKit extension contains the code for managing content, responding to user interactions, and updating your user interface. It is packaged inside the WatchApp bundle. Like all extensions, the WatchKit extension must have a unique bundle identifier and it must be code signed. Validation errors related to the WatchKit extension will cause the Watch app to fail to install. Additional information about the error which triggered the installation failure is logged to the paired iPhone's console. See Retrieving Device Logs.

Information Property List

The WatchKit extension must have an associated information property list. One is created for you by default when adding a WatchKit App to your project. By default it can be found under the folder named <Target Name> in the project navigator where <Target Name> is the name of your WatchKit extension.

Figure 4  Information property list for a properly configured WatchKit extension target.
  • Bundle Identifier (CFBundleIdentifier): Should be set to $(PRODUCT_BUNDLE_IDENTIFIER).

  • Bundle versions string, short (CFBundleShortVersionString): The value for this key must match the corresponding value in the containing iOS app's information property list.

  • Bundle version (CFBundleVersion): The value for this key must match the corresponding value in the containing iOS app's information property list.

  • WKAppBundleIdentifier: The value for this key must match the bundle identifier of the Watch app.

  • NSExtensionPointIdentifier: The value for this key must be com.apple.watchkit.

Build Settings

Figure 5  Build settings for a properly configured WatchKit extension target.
  • Product Bundle Identifier: Must be a unique reverse DNS string that is prefixed with the iOS app's bundle identifier or the WatchKit app's bundle identifier. For example, if your WatchKit app has the bundle identifier com.example.apple-samplecode.WatchKit-Catalog.watchkitapp, then the WatchKit extension's bundle identifier should be com.example.apple-samplecode.WatchKit-Catalog.watchkitapp.watchkitextension.

  • Architectures: Must be set to Standard architectures (armv7k).

  • Base SDK: Must be set to watchOS 2.0 or Latest watchOS (preferred).

  • Supported Platforms: Must be set to watchOS.

  • Valid Architectures: Must contain armv7k.

  • Enable Bitcode: Must be set to Yes.

  • Info.plist File: Must be the project relative path to the information property list for the WatchKit extension.

  • watchOS Deployment Target: Must be set to 2.0.

  • TARGETED_DEVICE_FAMILY: Must be set to 4. This is a User-Defined build setting that is automatically created by the Xcode templates.

The iOS App

The iOS application must include the Watch app target as a dependency. The Watch app product must also be copied into the iOS application's bundle at build time.

Dependencies

Figure 6  Build phases for an iOS app that includes a Watch app.

Appendix A: Retrieving Device Logs

Error messages relating to installation failures on the Watch are sent over to the paired iPhone, where they are logged to the iPhone's device console. To view the device console:

  1. Connect the iPhone and open Xcode.

  2. Choose Window > Devices from the menu.

  3. Under the DEVICES section in the left column, select the iPhone.

  4. To see the device console, click the up-triangle at the bottom left of the right hand panel to show the device console.



Document Revision History


DateNotes
2016-05-23

New document that describes the proper configuration for a project with a watchOS 2 app.