Article

Testing Custom Notification Interfaces

Test your notification interfaces on watchOS using a notification scheme and payload file.

Overview

When you are ready to test your dynamic interface in the simulator, create a custom build scheme for running your notification interface. To configure the scheme, specify the JSON data file containing the test data you want delivered to your interface.

When you create a new WatchKit App project or add a WatchKit App template to an existing project, Xcode adds notification scenes by default. This includes setting up the scheme and providing PushNotificationPayload.apns, a file with test JSON data. This file contains most of the keys you need to simulate a remote notification; however, you can add more keys.

If Xcode added the notification scenes for you, just modify the PushNotificationPayload.apns file so that it contains test data appropriate for your app. If you added the notification scenes yourself, you need to set up the scheme and payload file as well.

Add a Scheme

If you add notifications to your app, you also need to add a scheme to test the notifications. To test multiple notification categories, add a scheme for each category.

To add a scheme, click the current scheme in Xcode’s toolbar, and select New Scheme.

A screenshot showing the New Scheme menu item.

In the new scheme sheet, set the Target to your WatchKit app, and give the scheme a meaningful name.

A screenshot showing the New Scheme sheet, with the WatchKit App target set.

Click OK. Xcode adds and selects the scheme. To configure the new scheme, click the current scheme again, and select Edit Scheme.

In the edit scheme sheet, set the Watch Interface to Static Notification or Dynamic Notification, depending on which interface you want to test. Also set the Notification Payload to the desired payload file. Then click Close.

A screenshot showing the Edit Scheme sheet, with the notification interface and test data selected.

The scheme is now ready to run.

Create a Payload File

To test notification interfaces, you can specify a payload file that contains the test data for your notification. Payload files are text files with an .apns extension. They contain the JSON payload data for your notification. The default PushNotificationPayload.apns contents are shown below:

{
    "aps": {
        "alert": {
            "body": "Test message",
            "title": "Optional title",
            "subtitle": "Optional subtitle"
        },
        "category": "myCategory",
        "thread-id":"5280"
    },
    
    "WatchKit Simulator Actions": [
        {
            "title": "First Button",
            "identifier": "firstButtonAction"
        }
    ],
    
    "customKey": "Use this file to define a testing payload for your notifications. The aps dictionary specifies the category, alert text and title. The WatchKit Simulator Actions array can provide info for one or more action buttons in addition to the standard Dismiss button. Any other top level keys are custom payload. If you have multiple such JSON files in your project, you'll be able to select them when choosing to debug the notification interface of your Watch App."
}

To add a new payload file:

  1. Select File > New > File.

  2. In the file template sheet, make sure the iOS tab is selected, then scroll down to the Apple Watch group. Select the Notification Simulation File template and click Next.

  3. Name the payload file and click Create.

A screenshot showing the Notification Simulation File in the file template sheet.

The template creates a new file with the default JSON payload data. To use this file, select it in the Scheme editor when configuring the build scheme for a notification interface. You can include multiple payload files in your project and either change the build scheme or create multiple build schemes to simplify your testing.

Edit the JSON Payload

Most of the JSON data is packaged into a dictionary and delivered to your app at runtime. You can modify the contents of the payload file to match the actual content of typical notifications sent to your app. At a minimum, you should change the value of the category key to match the name of your notification category. For more information on creating a notification payload, see Payload Key Reference.

Note that the payload file includes a WatchKit Simulator Actions key. This key is not part of a normal notification’s payload. The Apple Watch simulator doesn’t have access to your iOS app’s registered actions, so you must define the actions in the payload file. The WatchKit Simulator Actions key contains an array of dictionaries, each of which represents an action button.

Each dictionary can contain the following keys:

title (Required)

The title of the action button.

identifier (Required)

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 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 1 or 0, where 1 causes the button to launch the app in the background.

Send Test Notifications to the Watch

Because the system automatically determines whether to deliver notifications to Apple Watch, when testing on the device, you may need to set the devices' states to make sure the notification is routed to Apple Watch as expected. To test your notification interfaces while the device is not on your wrist:

  • Disable Wrist Detection on Apple Watch. You can set this in the Watch app on the companion iPhone or in the Settings app on the watch. The option is under Passcode > Wrist Detection.

  • Make sure your Apple Watch is not on a charger.

  • Make sure your iPhone is locked.