Guides and Sample Code

Developer

Adopting 3D Touch on iPhone

On This Page

3D Touch APIs

iOS 9 provides the following 3D Touch APIs:

  • The Home screen quick action API is for adding shortcuts to your app icon that anticipate and accelerate a user’s interaction with your app.

  • The UIKit peek and pop API lets you provide easy access, within your app, to additional content while maintaining the user’s context. Use the peek quick actions API to provide a press-enabled replacement to your app’s touch-and-hold actions.

  • The Web view peek and pop API lets you enable system-mediated previews of HTML link destinations.

  • The UITouch force properties let you add customized force-based user interaction to your app.

No matter which of these APIs you adopt, your app must check the availability of 3D Touch at runtime.

Checking for 3D Touch Availability

To check at runtime whether a device supports 3D Touch, read the value of the forceTouchCapability property on the trait collection for any object that has a trait environment (seeUITraitEnvironment Protocol Reference). A user can turn off 3D Touch while your app is running, so read this property as part of your implementation of the traitCollectionDidChange: delegate method.

To ensure that all your users can access your app’s features, branch your code depending on whether 3D Touch is available. When it is available, take advantage of 3D Touch capabilities. When it is not available, provide alternatives such as by employing touch and hold, implemented with the UILongPressGestureRecognizer class.

Refer to iOS Human Interface Guidelines for ideas on how to enhance your app’s interactions for users with 3D Touch-capable devices while not leaving your other users behind.

Home Screen Quick Actions

iOS 9 supports Home screen static and dynamic quick actions.

iOS 9 displays up to four Home screen quick actions for your app. Within this limit, the system shows your static quick actions first, starting at the topmost position in the menu. If your static items do not exhaust the limit and you have also defined dynamic quick actions, then one or more of your dynamic quick actions is displayed.

Home screen static and dynamic quick action can each display up to two lines of text along with an icon. The system formats the text, wrapping it, aligning it, and adding ellipses as appropriate. For the icon of a quick action, use one of the system template icons available via the iconWithType: class method of the UIApplicationShortcutIcon class. If you want to instead use a custom icon, it must be a template (that is, stencil-like) image, which you can create using that class’s iconWithTemplateImageName: class method.

The Home screen Quick Actions feature supports Voice Over.

For details on implementing Home screen quick actions, read the following material:

UIKit Peek and Pop

iOS 9 lets you configure view controllers for the user features of peek, which provides a preview of additional content when a user presses on a specified view, and pop, which commits to viewing that content and navigates to it.

To support peek and pop on 3D Touch-capable devices, the iOS 9 SDK includes:

  • New methods in the UIViewController class for registering and unregistering a view controller for participation in 3D Touch

  • New view controller protocols to support 3D Touch

You can optionally configure a preview view controller to include a set of peek quick actions, or deep links into your app. A user can obtain peek quick actions by swiping a peek upward.

To support peek quick actions, the iOS 9 SDK includes:

For details on implementing peek and pop and for implementing peek quick actions, read the following material:

Web View Peek and Pop

In web views, you can enable peek and pop for links and for detected data using the new allowsLinkPreview property. In iOS 9, this property is available in the recommended WKWebView class (in the WebKit framework) and in the older UIWebView class (in the UIKit framework).

Peek and pop for links and detected data work automatically with the SFSafariViewController (Safari view controller) class in the Safari Services framework.

Force Properties in UITouch Objects

The UITouch class has two new properties to support custom implementation of 3D Touch in your app: force and maximumPossibleForce. For the first time on iOS devices, these properties let you detect and respond to touch pressure in the UIEvent objects your app receives.

On iPhone, the force of a touch has a high dynamic range, available as a floating point value to your app.

For details on providing a custom implementation of 3D Touch using force values, read the following material: