CREATING APPLE WATCH APPS: THE MISSING STEPS
3/12/23
I recently uploaded an iOS app update, one that included an all-new Apple Watch app. I had a suspicion that the watch app wasn’t included in the archive uploaded to App Store Connect. I was right: when the app was released, the watch app was missing. Fixing this involved three steps, ones that took more sleuthing than I would have expected.
Step one: embed the watch app
First, the watch app must be embedded in the iOS target. In the Navigator area of Xcode, select your project (1).
Next, in the editor area, select your iOS app target along the left side of the editor area (2). Make sure you are on the General tab (3). Scroll down in the editor area to near the bottom, and click the plus sign under Frameworks, Libraries, and Embedded Content (4). In the file chooser that appears, select the .app file for your watch app, and press Add. When you are done, your watch app should be listed under Frameworks, Libraries, and Embedded Content (5).
Step two: set the watch app’s bundle identifier
In the second step, you need to give the watch app the correct bundle identifier. For this, you’ll need the bundle identifier for your iOS app. To get it, select your iOS app target (1), click on the Signing & Capabilities tab (2), and copy the name that is displayed to the right of the Bundle Identifier (3).
Now, let’s use that to set the bundle identifier for the wach app. Select the watch app target (1), and click on the General tab (2). Look at the value to the right of the bundle identifier (3); it will likely say ”.watchkitapp“. Paste the iOS bundle identifier you just copied in front of this .watchkitapp suffix. The bundle identifier for the watch app should be identical to the bundle identifier for the iOS app, with .watchkitapp tacked onto the end.
Step three: associate the watch app with the iOS app
Finally, associate the watch app with its parent bundle, that is, the iOS app bundle. Select the watch app target (1), and click the Info tab (2). Next to WKCompanionAppBundleIdentifier (3), enter the iOS app’s bundle name, the same one you copied in the first part of Step Two.
Verifying that this works
You have two checks that this actually works. The first is that you get no errors during validation or uploading to App Store Connect. I show some of these errors below.
Second, when you upload the app to App Store Connect, you can be sure that the watch app has been included because under Included Assets, you will see two icons, one for the iOS app and one for the Apple Watch app.
Error messages
If one of these steps goes wrong, or if you forget to do them, you will likely get an error message when validating or uploading the app. Note that if you neglect all three steps, there will be no errors or warnings, and your uploaded iOS app will simply be missing its watch app.
Here are the various error messages I encountered.
If you see this, follow the instructions under Step Two to give the watch app the correct bundle identifier.
This error message also relates to Step Two. Specifically, the watch app bundle name should be identical to the iOS bundle name, with .watchkitapp appended to it. For example, if your iOS bundle name is com.myCompany.myApp, the Apple Watch bundle name should be com.myCompany.myApp.watchkitapp. To get this error, you may have forgotten the .watchkitapp suffix, or you may have misspelled it.
This message relates to Step Three. Follow the steps to associate the watch app with its parent bundle.
This error message appears when uploading to the App Store, and it also relates to Step Three. To address it, follow the steps for associating the watch app with its parent bundle. I can’t recall how I managed to get past the validation phase and not get this error until uploading to the App Store, but somehow I snuck past the guards!
Some thoughts
Two things surprise me. First, it is odd that XCode doesn’t automatically do these steps when you add a watch target. Xcode has the information it needs. Why doesn’t it automatically make these three settings?
Second, I was surprised at how hard it was to find this information. Perhaps Apple has a tutorial on this, but searching did not reveal it. Apple has great tutorials on creating a watch app, but instructions on bundling it with an app aren’t obvious. I did find a posting on the Developer Forums for Step One, for embedding the watch bundle in the iOS bundle. I also found a posting on Stack Overflow that helped with Steps Two and Three. It seems like Apple would have a short tutorial that puts all of this in one place, and that it would be easily found.