Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Settings

Preferences and settings are data values that change infrequently and that you use to configure your app’s behavior or appearance. If your Watch app uses preferences for its configuration, you can add a watch–specific settings bundle to your project to present those settings to the user. This settings bundle lives inside your iOS app, and the settings themselves are displayed by Apple’s Watch app on the user’s iPhone.

A watch-specific settings bundle works in the same way that an iOS settings bundle works. The settings bundle defines the controls you want displayed by the system and the name of the preference that each control modifies. Apple’s Watch app on the user’s iPhone displays your settings and writes any changes to the defaults database associated with your app. That database must be stored in a shared app group so that your WatchKit extension can access it.

Your WatchKit extension can read the values of preferences, but you should not write new values. Preferences are forwarded from iOS to Apple Watch, but any modifications you make are not sent back to iOS. If your Watch app needs to change the preferences, use the Watch Connectivity framework to send the values back to your iOS app, and change the values there.

For general information about how settings bundles work, see Preferences and Settings Programming Guide.

Creating Your Settings Bundle

To add a watch-specific settings bundle to your iOS app, do the following in Xcode:

  1. Select File > New > File.

  2. In the iOS section, select Settings Bundle and click Next.

  3. Create the settings bundle with the name Settings-Watch.bundle and add it to your iOS app target.

    Naming the bundle Settings-Watch.bundle is required to distinguish it from your iOS app’s settings bundle (if any).

The initial contents of the watch-specific settings bundle are the same as for an iOS app’s settings bundle and are shown in Listing 16-1. To configure your settings, configure the Root.plist file with the controls you want to display.

Listing 16-1Contents of a watchOS settings bundle
  1. Settings-Watch.bundle/
  2. Root.plist
  3. en.lproj/
  4. Root.strings

For information on how to configure the contents of your settings bundle, see Implementing an iOS Settings Bundle. For detailed information about the keys you can include in a Settings bundle, see Settings Application Schema Reference.

Configuring a Shared App Group to Store Your Settings

You must configure a shared app group to store any watch-specific settings. The shared app group identifies the location where Apple’s Watch app can access the defaults database containing your preferences. Your Watch app also uses the identifier of the shared app group to access your preferences. To configure the shared app group for your settings, do the following:

  • Enable the App Groups capability for your iOS app, WatchKit extension, and Watch app. Select an identifier from the list or create a new one.

  • Add the ApplicationGroupContainerIdentifier key to the Root.plist file of your Settings-Watch bundle.

    Place the key at the top level of your property list. Set its value to the identifier you specified in the App Groups capability.

Accessing Settings at Runtime

To access preferences from your WatchKit extension, use the initWithSuiteName: method to initialize a new NSUserDefaults object. Specify the identifier of your shared app group as the suite name. You can use the resulting user defaults object to get preference values. Your WatchKit extension can only read values from the database. Listing 16-2 shows an example that accesses a custom group.

Listing 16-2Accessing preferences in a shared group container

Objective-C

  1. NSUserDefaults *defaults = [[NSUserDefaults alloc] initWithSuiteName:@"group.com.example.MyWatchKitApp"];
  2. BOOL enabled = [defaults boolForKey:@"enabled_preference"];

Swift

  1. let defaults = NSUserDefaults(suiteName: "group.com.example.MyWatchKitApp")
  2. let enabled = defaults?.boolForKey("enabled_preference")

For more information on how to access preferences values, see NSUserDefaults Class Reference.