UIApplicationShortcutItem

On a device that supports 3D Touch, a user invokes the quick action by pressing your app's icon on the Home screen and then selecting the quick action’s title. Your app delegate receives and handles the quick action.

You must specify the characteristics of your UIApplicationShortcutItem instances during initialization, before you register them with your app object. The quick actions you’ve registered with your app object are immutable.

To register an array of Home screen dynamic quick actions, set the value of your shared app object’s shortcutItems property with an NSArray instance containing your defined dynamic Home screen quick actions.

To change your app’s Home screen dynamic quick actions, replace your app object’s shortcutItems array by setting a new value for the property. As a convenience for working with registered quick actions, this class has a mutable subclass, UIMutableApplicationShortcutItem. The following code snippet illustrates one way to use the mutableCopy() method, along with mutable quick actions, to change the title of a dynamic Home screen quick action:

var shortcutItems = UIApplication.shared.shortcutItems ?? []
if let existingShortcutItem = shortcutItems.first {
    guard let mutableShortcutItem = existingShortcutItem.mutableCopy() as? UIMutableApplicationShortcutItem
        else { preconditionFailure("Expected a UIMutableApplicationShortcutItem") }
    guard let index = shortcutItems.index(of: existingShortcutItem)
        else { preconditionFailure("Expected a valid index") }

    mutableShortcutItem.localizedTitle = "New Title"
    shortcutItems[index] = mutableShortcutItem
    UIApplication.shared.shortcutItems = shortcutItems
}

Although immutable, a UIApplicationShortcutItem instance is considered dynamic to distinguish it from a static quick action you specify at build time.

• Define Home screen dynamic quick actions using this class. Your code creates dynamic quick actions, and registers them with your app object, at runtime.

• Define Home screen static quick actions in the UIApplicationShortcutItems array in your Xcode project’s Info.plist file, as described in the iOS Keys chapter in Information Property List Key Reference. The system registers your static quick actions when your app is installed.

The system limits the number of quick actions displayed when a user presses a Home screen app icon. Within the limited set of displayed quick action titles, your static quick actions are shown first, starting at the topmost position in the list. If your static items do not consume the permissible number for display and you have also defined dynamic quick actions using this class, then one or more of your dynamic quick actions is displayed.

When a user chooses one of your Home screen quick actions, the system launches or resumes your app and UIKit calls the application(_:performActionFor:completionHandler:) method in your app delegate. Be sure to read the description of that method in UIApplicationDelegate for information on how to ensure the method is called only when it should be.

After a user first installs your app and before they first launch it, pressing your Home screen icon displays only the app’s static quick actions. After first launch, your dynamic quick actions (if you’ve defined any and there is room in the list to accommodate them) are displayed as well.

If a user installs an update for your app but has not yet launched the update, pressing your Home screen icon shows the dynamic quick actions for the previously-installed version. One way to gracefully handle this scenario is to provide app version information in the userInfo dictionary of a quick action.