Article

Preparing Your App to Play Haptics

Set up your app to play haptics.

Overview

This article describes the process of setting up your app to play haptics. You'll check for device compatibility, create a haptic engine, and then configure the engine's handler properties.

Check for Device Compatibility

Not all devices support Core Haptics. For example, iPad and iPod touch don’t support haptic feedback, so calls to Core Haptics won’t result in haptics.

Check for haptics compatibility at the app’s launch, in your app delegate:

var supportsHaptics: Bool = false
...
// Check if the device supports haptics.
let hapticCapability = CHHapticEngine.capabilitiesForHardware()
supportsHaptics = hapticCapability.supportsHaptics

By checking for haptic support early using supportsHaptics, you can set a global Boolean that your view controllers can quickly consult before deciding to play a haptic. If this variable is set to false, then the app can proceed without even attempting a call to Core Haptics. For an example of conditioning haptic playback on this global Boolean, see Playing a Custom Haptic Pattern from a File.

Based on whether or not the user’s device supports haptics, your app can decide to use a different codepath, with stronger audio or other multimedia alternatives for feedback.

Create a Haptic Engine

The CHHapticEngine is your app’s interface to the haptic device. Use an instance of a haptic engine to perform these key tasks:

• Create players to play those haptic and audio patterns.

• Play haptic patterns directly from a file URL.

• Modulate haptic patterns during playback.

Create this engine early in your app’s life cycle—for example, in your main view controller’s viewDidLoad()—and store it in an instance variable or property so it doesn’t go out of scope during playback.

var engine: CHHapticEngine!
...
// Create and configure a haptic engine.
do {
    engine = try CHHapticEngine()
} catch let error {
    fatalError("Engine Creation Error: \(error)")
}

Set the Reset Handler to Recover from Failure

Core Haptics calls the reset handler after the media server has recovered from failure. When this occurs, inside the reset handler, your app should do the following:

// The reset handler provides an opportunity to restart the engine.
engine.resetHandler = {
    
    print("Reset Handler: Restarting the engine.")
    
    do {
        // Try restarting the engine.
        try self.engine.start()
                
        // Register any custom resources you had registered, using registerAudioResource.
        // Recreate all haptic pattern players you had created, using createPlayer.

    } catch {
        fatalError("Failed to restart the engine: \(error)")
    }
}

Your app could attempt to restart the engine inside the handler, allowing it to recover on its own. However, as shown in the code listing above, a restart may still fail if the external reason for the reset hasn't subsided.

Receive Notification of Haptic Engine Stoppage Due to Outside Causes

When external factors cause the haptic engine to stop, like audio interruptions from a phone call or because the user has put your app in the background, Core Haptics calls the stoppedHandler. The reason for the stoppage is passed into the handler. Because stopping is a normal part of the life cycle, you need to restart the engine before it can play the next haptic.

As you're testing your app, set the stoppedHandler to debug the precise cause of the engine stoppage, as shown below.

// The stopped handler alerts engine stoppage.
engine.stoppedHandler = { reason in
    print("Stop Handler: The engine stopped for reason: \(reason.rawValue)")
    switch reason {
    case .audioSessionInterrupt: print("Audio session interrupt")
    case .applicationSuspended: print("Application suspended")
    case .idleTimeout: print("Idle timeout")
    case .systemError: print("System error")
    @unknown default:
        print("Unknown error")
    }
}

In production, your app can handle each cause in a different way. For example, you could handle the case CHHapticEngine.StoppedReason.systemError by continuing the app without haptics, or by throwing a fatal error to terminate the app.

Define and Play Haptics

Once you've set up your app to play haptics, you can incorporate haptic patterns. See:

See Also

Essentials

Playing a Single-Tap Haptic Pattern

Create and play a transient haptic pattern from a dictionary literal inline.

class CHHapticEngine

An object that manages your app's requests to play haptic patterns.

class CHHapticPattern

An object representing a haptic waveform.