3D Touch in iOS 9, Part 3: Adding Dynamic Shortcut Items

Shortcut-Items

We can define shortcut items that appear when the user presses hard on the app icon from the home screen. If available, the springboard blurs and only leaves our app icon and the shortcut actions visible.

These items can be generated in two ways: via code, and via entries in our app’s Info.plist file. In this article I’ll show you how to create dynamic shortcut items in code. We’ll talk about Static Shortcut Items in my next article.

The difference between this approach and the Info.plist entries is that a user needs to have launched our app at least once for our shortcuts to become available. This is also true for changes to these items after an app upgrade. Another difference is that dynamic items can be updated, while static ones can not (unless we deploy a new version to iTunes Connect).

Shortcut Items without Icons

Shortcut items can be generated without icons with relative ease, as instances of the UIApplicationShortcutItem class. Here’s how to do it in your AppDelegate:

Call this method in applicationDidFinishLaunchingWithOptions. We’ll talk about how to react to these items in a moment.

Shortcut Items with your own Icons

Alternatively we can add swanky icons to these actions, as well as subtitles if we like. The method for this is another init method for the same class as above, taking more parameters. Icons are simple PNG files in 35×35 pixels (or 2x/3x equivalents of those dimensions). Add them to your asset catalogue and instantiate them like this:

[emember_protected]

The procedure is much like the simpler one above, with the added step that we’ll create icons first and add them to the UIApplicationShortcutItem array. Just for demonstration, this class is also available as UIMutableApplicationShortcutItem, which means it can be changed as your app runs.

  • Both classes take five parameters with the initWithType method:
  • a type (an NSString, unique to your app)
  • a localised title (another NSString)
  • a localised subtitle (also an NSString)
  • an icon
  • and a user dictionary (NSDictionary)

The latter can be used if you want to pass parameters with an item.

Shortcut Items with System Images

The documentation also suggests that we can use several system icons that are at our disposal, such as mail or bookmark icons. In theory it’s supposed to work just like the method I’ve shown above, with the exception of how the icons are instantiated:

In practice however, I’ve not been able to make those fancy iOS 9 icons show up. May you have better luck than I have with this venture. My own icons show up without problems – but not the system icons.

[/emember_protected]

Reacting to Shortcut Items

  1. There are two things that can happen when a user selects one of our shiny new shortcut items:
    either the app launches for the first time
  2. or the app is still open in the background

To cover both eventualities, we need to add two things to our AppDelegate.

The first is a check in applicationDidLaucnhingWithOptions to tell us how the app needs to be presented here. Think of the camera app for example: if the user selects the “selfie” option, the front camera needs to be active. Or if he wants to take a normal picture, the back camera needs to be active. We don’t want them to press other options, otherwise they might as well launch our app without a shortcut.

To make it simple here, I’ll print a log message and the title of our shortcut:

[emember_protected]

This method is called when our app was not in the background, and it will tell us if (and which) shortcut has been pressed, or if the app was launched “properly” without a shortcut. At this point we can load the correct view controller and configuration.

If the app was already launched and lurks around in the background, the above method is not called again. Hence we need another way to react to a shortcut item. We can do so by implementing a new method that’s part of the UIApplicationDelegate Protocol. It’s called performActionForShortcutItem. Here it is:

This method is called every time the user selects one of our shortcut items while our app is in the background. Here we are given the actual shortcut item and can evaluate what needs to happen. To react, we can configure the completionHandler block and check if said block was successful or not. Alternatively we can send a notification to the relevant view controllers for the shortcut action to launch.

Demo Project

I’ve added the above methods to my 3D Touch Demo Project, feel free to check it out on GitHub:

[/emember_protected]

Further Reading

About Jay Versluis

Jay is a medical miracle known as Super Survivor. He runs two YouTube channels, five websites and several podcast feeds. To see what else he's up to, and to support him on his mission to make the world a better place, check out his Patreon Campaign.

5 thoughts on “3D Touch in iOS 9, Part 3: Adding Dynamic Shortcut Items

  1. This is great but it doesn’t tell us how to catch if the menu was open in the first place. When the user activates the shortcut menu I then want it to update with some information. How is this done?

    1. Hi Ted, I’m not sure if that’s even possible: as soon as you open the shortcut menu, the system fires performActionForShortcutItem. I guess you could update the shortcutItems array at that point. Try it out and see what happens.

  2. Great article, but would it be possible for you to add how to access a specific view controller from a shortcut? Simply, I would like to be able to call a specific navigation controller in one off my newly segregated storyboards. Thanks.

    1. Hi Deij, very good point – I’ll update the demo project with such an example. In a nutshell, here’s how you’d launch that navigation controller. Set the Storyboard ID in the Identity Inspector accordingly:

      All we need then is a check in performActionForShortcutItem, and in applicationDidFinishLaunching:

      It’s easy to bring up a single view controller. But when it comes to deep linking several levels of view controllers on a navigation stack, make sure you have navigation items to bring the user back to the main view. As an example, you may need to instantiate the nav controller and then push an additional view controllers (without animation) onto the stack so that the back button shows up properly.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.