2. Project Structure

Written by Scott Grosch

You’ll use Xcode when creating an app to run on the Apple Watch, just like when you develop for iOS. The structure is a little different, though. In iOS, you usually have a single target for the app, but you’ll always have three when creating a watchOS app.

Start Xcode and create a new project. You’ll notice some tabs at the top of the template chooser dialog. The Multiplatform tab is the default selection.

While you could start from the App template, you shouldn’t. Instead, select the watchOS tab. You’ll see two templates you can choose from:

If you’re reading this book, you probably need a watch app. However, what type of app are you going to create?

1. Does the watch app stand alone, with no corresponding iOS app?
2. Does the watch app require a companion iOS app to function properly?
3. Does the watch app function on its own, but there’s also an iOS app?

Standalone app

Most of this book’s chapters pretend that you’ve chosen the first option. The watch app will be fully functional and won’t need a companion iOS app. As the Apple Watch is the focus of this book, I don’t want to confuse the examples with a ton of code for an iOS app that doesn’t add value. One of the later chapters will provide instructions for tying your Watch App to an iOS app if required.

Select the Watch App template and pick a name for your project. I chose Standalone.

Take a look at the targets, and you’ll see the template created three for you:

1. Standalone is the general target for your project. It acts as a wrapper for your project so that you can submit it to the App Store.
2. Standalone WatchKit App is the target for building the watchOS app. An app bundle contains your watchOS app’s storyboard and any assets used by the storyboard.
3. Standalone WatchKit Extension is the target for building the watchOS extension. An extension contains your watchOS app’s code.

You’ll seldom interact with the first two targets. When you think of an Apple Watch app you’re talking about the extension.

Standalone schemes

Look at the scheme selector. You’ll see three default schemes:

The schemes don’t directly map to the three default targets. Instead, they control what type of execution you wish to perform when running in the simulator or on a physical device.

Standalone WatchKit App

The first scheme is the one you’ll use most often. You can think of this scheme as the standard “run my app”. When you build and run using the Standalone WatchKit App scheme, the simulator or physical device will execute what the end-user would see when starting your app.

Standalone WatchKit App (Notification)

You created the second scheme when you left the Include Notification Scene checkbox selected while creating the project. More recent versions of watchOS let you send notifications directly to the device.

If you select the Standalone WatchKit App (Notification) scheme, then build and run the app, you won’t see the standard user interface you’d expect. Instead, the app will jump directly to the notification view which you’ve defined. You’ll only use this scheme when you’re testing your local or remote push notifications.

Notifications are a complex topic that you’ll address in Chapter 6, “Notifications.”

Standalone WatchKit App (Complication)

Due to the complexity of writing a watchOS app, Apple created a final scheme specifically to address that difficulty. Kidding!

Complications, which will be the topic of multiple later chapters, are the small pieces of information you see on the watch’s face. Timers, small gauges and the activity ring are all examples of complications.

When debugging your watch app’s optional complication, you’ll use the Standalone WatchKit App (Complication) scheme.

Note: Make sure you select the proper scheme when debugging different parts of your app.

Including an iOS app

If you’re going to have both an iOS and a watchOS app, select the iOS App with Watch App template when creating a project. You can choose any name you like — I chose Example — and leave the defaults for everything else. Click Next and choose a location. You’ll get Xcode’s main window.

Take a look at the targets. You’ll see three:

1. Example is the target for building the iOS app.
2. Example WatchKit App is the target for building the watchOS app.
3. Example WatchKit Extension is the target for building the watchOS extension.

Requiring a companion app

While many watchOS apps require a companion iOS project, it’s also possible for a watch app to fully function without a companion iOS app. By default, Xcode assumes your watch app can run without an installed companion iOS app.

If your watch app can’t run without a corresponding iOS app, then you’ll need to make a small configuration change:

1. Click the project in the Project Navigator, or press Command‑1.
2. Select the extension target.
3. Select the General tab.
4. In the Deployment Info section, uncheck the Supports Running Without iOS App Installation checkbox.

Naming your app

Run the standalone project in the simulator using the Standalone WatchKit App scheme. Once the simulator appears, open the Settings app. There are four ways to get there:

1. Click the digital crown on the simulator.
2. Click the picture of the home icon above the watch image.
3. Choose Device ▸ Home from the menubar.
4. Press the Shift‑Command‑H keyboard shortcut.

After tapping the Settings app, scroll down to App View. Then select List View:

Now go back to the home screen and scroll down to the bottom of the list of apps. You’ll see your app displayed with a horrible name:

By default, Xcode will append WatchKit App to the name you entered when creating the app. The fix is pretty simple if you know where to look.

Bring up the Project Navigator by pressing Command‑1 and select the Standalone WatchKit App target. Then switch to the General tab, if not already there:

Once there, it’s a simple matter of entering the text you want to display by editing the Display Name.

Build and rerun the app. Go to the home screen and scroll to your app name in the list. You’ll see the shorter name that you likely expected to see in the first place:

App vs. extension folders

Look at the list of files and directories that Xcode created. You’ll see three primary directories below the project:

• Standalone WatchKit App
• Standalone WatchKit Extension
• Products

Like any normal Xcode project, you won’t do anything with the Products folder.

When assigning the images for your app icon, you’ll want to open the directory ending with App, for example, Standalone WatchKit App/Assets.xcassets. Don’t do anything else inside of that folder structure.

For all other assets, as well as all the coding you’ll perform, you’ll work in the Extensions directory, for example, Standalone WatchKit Extension.

Note: Previous versions of watchOS worked differently. Don’t put your non-app icon images in the app directory’s Assets.xcassets area any longer!

Adding Apple Watch support later

It’s OK if you forget to include support for a watch app. Maybe you weren’t ready to work on the watch app yet, or perhaps you’re adding watch support to a legacy app. Maybe you just plain forgot.

With your existing iOS project open, simply add a new target via File ▸ New ▸ Target… and then choose the Watch App template.

Note: You won’t be able to name the watchOS target the same as the iOS target because Xcode would try to create conflicting names.

Having to pick a different name might be a hard stop for your team. If that’s the case, be sure to start with the watch template instead of the iOS template.

Key points

• Watch apps can be standalone, without an accompanying iOS app, require a companion iOS app or work independently of the iOS app. There’s also an iOS app you may use but don’t have to.
• You can add watch support to an iOS app at a later date.
• All your work, except the app icon, should be in the extension folder.
• Remember to change the Display Name of the app target.