Sample Code

Add Home Screen Quick Actions

Expose commonly used functionality with static or dynamic 3D Touch Home screen quick actions.

Overview

On devices that support 3D Touch, you can use Home screen quick actions to provide access to frequently used functionality in your app. To reveal Home screen quick actions, the user presses your app icon, using a bit more pressure than is required for touch and hold.

Quick actions can be defined statically at build time or dynamically at runtime. For information about the types of functionality you should expose using quick actions, see the Human Interface Guidelines.

The app in this sample project is a basic contact manager that allows a small set of contacts to be viewed and edited. The initial view controller shows a list of contacts in a table view. Tapping any contact shows a detail screen where you can edit the name and email address, or tap to turn on the Favorite switch.

When you press the sample app’s Home screen icon, several Home screen quick actions are displayed. The first two give access to search and sharing functionality, and the rest provide shortcuts to favorite contacts.

Define Static Quick Actions

If the quick actions that are appropriate for your app never change, define them as static quick actions using your project’s Info.plist file. In this sample project, two static quick actions have been defined, one for searching and one for sharing.

The UIApplicationShortcutItems key in the Info.plist file contains an array of two dictionaries representing the two static quick actions.

<key>UIApplicationShortcutItems</key>
<array>
    <dict>
        <key>UIApplicationShortcutItemType</key>
        <string>SearchAction</string>
        <key>UIApplicationShortcutItemIconType</key>
        <string>UIApplicationShortcutIconTypeSearch</string>
        <key>UIApplicationShortcutItemTitle</key>
        <string>Search</string>
        <key>UIApplicationShortcutItemSubtitle</key>
        <string>Search for an item</string>
    </dict>
    <dict>
        <key>UIApplicationShortcutItemType</key>
        <string>ShareAction</string>
        <key>UIApplicationShortcutItemIconType</key>
        <string>UIApplicationShortcutIconTypeShare</string>
        <key>UIApplicationShortcutItemTitle</key>
        <string>Share</string>
        <key>UIApplicationShortcutItemSubtitle</key>
        <string>Share an item</string>
    </dict>
</array>

The value for UIApplicationShortcutItemType should be a unique string passed to your app when a user invokes the quick action.

For information about other Info.plist keys you can use to configure Home screen quick actions, see the Information Property List Key Reference.

Define Dynamic Quick Actions

You configure dynamic Home screen quick actions by setting the shortcutItems property of the shared UIApplication instance to an array of UIApplicationShortcutItem objects.

You can set dynamic Home screen quick actions at any point, but in this sample code they’re set in the applicationWillResignActive(_:) method of the application delegate. During the transition to a background state is a good time to update any dynamic quick actions because this code is always executed before the user returns to the Home screen.

func applicationWillResignActive(_ application: UIApplication) {
    // Transform each favorite contact into a UIApplicationShortcutItem.
    application.shortcutItems = ContactsData.shared.favoriteContacts.map { contact -> UIApplicationShortcutItem in
        return UIApplicationShortcutItem(type: "FavoriteAction",
                                         localizedTitle: contact.name,
                                         localizedSubtitle: contact.email,
                                         icon: UIApplicationShortcutIcon(type: .contact),
                                         userInfo: contact.quickActionUserInfo)
    }
}

You don’t need to limit the number of quick actions provided to the shortcutItems property because the system displays only the number of items that fit the screen. For this reason, the implementation of favoriteContacts on the ContactsData class returns all contacts that have the favorite property set to true.

Pass Data with a Quick Action

The dynamic quick actions in this sample project all have the same type because they all perform the same action. However, the contact information associated with each is different and is passed to the app through the userInfo dictionary.

var quickActionUserInfo: [String: NSSecureCoding] {
    // Encode the name of the contact into the userInfo dictionary so it can be passed
    // back when a quick action is triggered. Note: In the real world, it's more appropriate
    // to encode a unique identifier for the contact than for the name.
    return [ "Name": self.name as NSSecureCoding ]
}

Static Home screen quick actions can also pass userInfo data by including it in the UIApplicationShortcutItemUserInfo key in the app’s Info.plist file.

All values passed as userInfo must conform to NSSecureCoding.

Respond to Triggered Quick Actions

When the user triggers a Home screen quick action, your app is notified in one of these ways:

If your app isn’t already loaded, it’s launched and the details of the shortcut item are passed in through the launchOptions parameter of the application(_:didFinishLaunchingWithOptions:) method.
If your app is already loaded, the system calls the application(_:performActionFor:completionHandler:) method of your application delegate.

In this sample code, an instance variable in the AppDelegate class is assigned a value in one of two ways.

This code shows the value assigned in the application(_:didFinishLaunchingWithOptions:) method:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
    // If launchOptions contains the appropriate launch options key, a Home screen quick action
    // is responsible for launching the app. Store the action for processing once the app has
    // completed initialization.
    if let shortcutItem = launchOptions?[UIApplication.LaunchOptionsKey.shortcutItem] as? UIApplicationShortcutItem {
        shortcutItemToProcess = shortcutItem
    }

    return true
}

This code shows the value assigned in the application(_:performActionFor:completionHandler:) method:

func application(_ application: UIApplication, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
    // Alternatively, a shortcut item may be passed in through this delegate method if the app was
    // still in memory when the Home screen quick action was used. Again, store it for processing.
    shortcutItemToProcess = shortcutItem
}

If a value is assigned to the shortcutItemToProcess instance variable when the app becomes active, the functionality for that quick action is triggered. In this sample an alert is shown, but in a real-world app the actual functionality would be executed:

func applicationDidBecomeActive(_ application: UIApplication) {
    // Is there a shortcut item that has not yet been processed?
    if let shortcutItem = shortcutItemToProcess {
        // In this sample an alert is being shown to indicate that the action has been triggered,
        // but in real code the functionality for the quick action would be triggered.
        var message = "\(shortcutItem.type) triggered"
        if let name = shortcutItem.userInfo?["Name"] {
            message += " for \(name)"
        }
        let alertController = UIAlertController(title: "Quick Action", message: message, preferredStyle: .alert)
        alertController.addAction(UIAlertAction(title: "Close", style: .default, handler: nil))
        window?.rootViewController?.present(alertController, animated: true, completion: nil)

        // Reset the shortcut item so it's never processed twice.
        shortcutItemToProcess = nil
    }
}