An application shortcut item, also called a Home screen dynamic quick action, that specifies a user-initiated action for your app.
- iOS 9.0+
- Mac Catalyst 13.0+
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
UIApplication instances during initialization, before you register them with your app object. The quick actions you’ve registered with your app object are immutable.
Registering an Array of Dynamic Quick Actions With Your App
To register an array of Home screen dynamic quick actions, set the value of your shared app object’s
shortcut property with an
NSArray instance containing your defined dynamic Home screen quick actions.
Changing Your App’s Dynamic Quick Actions
To change your app’s Home screen dynamic quick actions, replace your app object’s
shortcut array by setting a new value for the property. As a convenience for working with registered quick actions, this class has a mutable subclass,
UIMutable. The following code snippet illustrates one way to use the
mutable method, along with mutable quick actions, to change the title of a dynamic Home screen quick action:
Dynamic vs. Static Quick Actions
Although immutable, a
UIApplication 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
Infofile, 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.
App Launch and App Update Considerations for Quick Actions
When a user chooses one of your Home screen quick actions, the system launches or resumes your app and UIKit calls the
application: method in your app delegate. Be sure to read the description of that method in
UIApplication 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
user dictionary of a quick action.