Home screen dynamic quick actions on iOS

iOS apps can add quick actions which are displayed when force touching on the app’s icon. We’ll add quick actions to my open source WaterMyPlants example app. Quick actions can be static and dynamic: static actions are defined in the Info.plist and dynamic actions are configured in the code by updating UIApplication’s shortcutItems property. In the WaterMyPlants app, we’ll add one static action for adding a new plant and dynamic actions for opening added plants.

Static quick actions

Static quick actions are defined in the Info.plist. We need to add the UIApplicationShortcutItems key with array of dictionaries. Every dictionary in the array defines a quick action. Quick actions are required to have type and title and optionally we can add a subtitle and an icon. In the example below, we used one of the predefined icons. Predefined icons can be used by adding a key UIApplicationShortcutItemIconType with a string matching a format UIApplicationShortcutIconType<name>. Custom images are defined by the UIApplicationShortcutItemIconFile key where the string value is the name of an image in the asset catalog.

	<key>UIApplicationShortcutItems</key>
	<array>
	<dict>
	<key>UIApplicationShortcutItemType</key>
	<string>com.augmentedcode.watermyplants.addplants</string>
	<key>UIApplicationShortcutItemTitle</key>
	<string>Add Plant</string>
	<key>UIApplicationShortcutItemIconType</key>
	<string>UIApplicationShortcutIconTypeAdd</string>
	</dict>
	</array>

view raw Infoplist hosted with ❤ by GitHub

Dynamic quick actions

Actions which depend on the data or state of the app can be added by setting the UIApplications’s shortcutItems property. Note that when adding items then we can use UIApplicationShortcutIcon‘s systemImageName initializer which enables us using any of the SF Symbols. Otherwise it is pretty much the same as defining a static quick action: setting type and title. It is useful to add an enum containing all the action types which becomes handy when we are handling actions. WaterMyPlants app uses scene delegates and therefore a good time to set dynamic quick actions is when the scene is resigning active status (see sceneWillResignActive(_:)).

	func reloadShortcuts() {
	let context = dependencyContainer.persistentContainer.viewContext
	let plants = Plant.all(in: context).sorted(by: { $0.name < $1.name })
	let items = plants.map({ (plant) -> UIApplicationShortcutItem in
	return UIApplicationShortcutItem(type: UIApplicationShortcutItem.Action.showPlant.rawValue,
	localizedTitle: plant.name,
	localizedSubtitle: nil,
	icon: UIApplicationShortcutIcon(systemImageName: "leaf.arrow.circlepath"),
	userInfo: ["id": plant.id] as [String: NSSecureCoding])
	})
	UIApplication.shared.shortcutItems = items
	}

view raw UIApplicationShortcutIcon.swift hosted with ❤ by GitHub

Performing quick actions

Quick actions are handled either in the UIApplicationDelegate or in the UISceneDelegate. WaterMyPlants uses scene delegates, therefore we’ll look into how to perform actions using scene delegates. We need to keep in mind that when selecting a shortcut launches the app, then we would need to check the shortcut property in the UIScene.ConnectionOptions and use it for configuring the UI to perform the action (windowScene(_:performActionFor:completionHandler:) is not called in that case). But if the app is already running in the background, then we can handle the action in the performActionFor delegate callback.

	extension UIApplicationShortcutItem {
	enum Action: String {
	case addPlant
	case showPlant
	}
	}
	final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
	func windowScene(_ windowScene: UIWindowScene, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
	guard let identifier = UIApplicationShortcutItem.Action(rawValue: shortcutItem.type) else { fatalError("Unknown shortcut") }
	switch identifier {
	case .addPlant:
	flowCoordinator?.plantListViewModel.isPresentingAddPlant = true
	case .showPlant:
	print("show plant: \(String(describing: shortcutItem.userInfo))")
	}
	completionHandler(true)
	}
	func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
	// …
	// Triggering the add plant shortcut when launching the app
	if connectionOptions.shortcutItem?.type == UIApplicationShortcutItem.Action.addPlant.rawValue {
	viewModel.isPresentingAddPlant = true
	}
	// Setting up a view with the view model configured to show add plant view
	}
	}

view raw PerformingActions.swift hosted with ❤ by GitHub

Summary

We added home screen quick actions to the WaterMyPlants app. We looked into how to add static and dynamic quick actions and how to perform the selected action.

If this was helpful, please let me know on Mastodon@toomasvahter or Twitter @toomasvahter. Feel free to subscribe to RSS feed. Thank you for reading.

Project

WaterMyPlants (GitHub) Xcode 11.5

Pull request #3