Haptics

Haptics

Haptic feedback provides tactile confirmation of user actions and system events. When designed thoughtfully, haptics transform interfaces from functional to delightful.

Overview

Haptics should enhance interactions, not dominate them. The core principle: haptic feedback is like sound design—every haptic should have purpose (confirmation, error, warning), timing (immediate or delayed), and restraint (less is more).

Reference Loading Guide

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

Core Workflow

1. Choose complexity level: Simple (UIFeedbackGenerator) vs Custom (Core Haptics) 2. For simple haptics: Use UIImpactFeedbackGenerator, UISelectionFeedbackGenerator, or UINotificationFeedbackGenerator 3. For custom patterns: Create CHHapticEngine, define CHHapticEvents, build CHHapticPattern 4. Prepare before triggering: Call prepare() to reduce latency 5. Apply design principles: Ensure Causality (timing), Harmony (multimodal), Utility (meaningful)

System Requirements

• iOS 10+ for UIFeedbackGenerator
• iOS 13+ for Core Haptics (CHHapticEngine)
• iPhone 8+ for Core Haptics hardware support
• Physical device required - haptics cannot be tested in Simulator

Common Mistakes

1. Haptic feedback on every action — Every button doesn't need haptics. Reserve haptics for critical confirmations (purchase, delete, settings change). Over-haptics are annoying and drain battery.

2. Triggering haptics on main thread blocks — Long haptic patterns can freeze UI briefly. Use background threads or async for Core Haptics prepare() calls to prevent jank.

3. Haptic without audio/visual feedback — Relying ONLY on haptics means deaf or deaf-blind users miss feedback. Always pair haptics with sound or visual response.

4. Ignoring haptic settings — Some users disable haptics system-wide. Check UIFeedbackGenerator.isHapticFeedbackEnabled before triggering. Graceful degradation is required.

5. AHAP file errors silently — Invalid AHAP files fail silently without errors. Test with Xcode's haptic designer and validate file syntax before shipping.

6. Forgetting battery impact — Continuous haptic patterns (progress bars, loading states) drain battery fast. Use haptics for state changes only, not ongoing feedback.

AHAP Patterns

AHAP (Apple Haptic Audio Pattern) files are JSON files combining haptic events and audio.

Basic AHAP Structure

{
  "Version": 1.0,
  "Metadata": { "Project": "My App", "Created": "2024-01-15" },
  "Pattern": [
    {
      "Event": {
        "Time": 0.0,
        "EventType": "HapticTransient",
        "EventParameters": [
          { "ParameterID": "HapticIntensity", "ParameterValue": 1.0 },
          { "ParameterID": "HapticSharpness", "ParameterValue": 0.5 }
        ]
      }
    }
  ]
}

Event Types

HapticTransient (short tap)

{ "Event": { "Time": 0.0, "EventType": "HapticTransient",
    "EventParameters": [
      { "ParameterID": "HapticIntensity", "ParameterValue": 0.8 },
      { "ParameterID": "HapticSharpness", "ParameterValue": 0.6 }
    ] } }

HapticContinuous (sustained vibration)

{ "Event": { "Time": 0.0, "EventType": "HapticContinuous", "EventDuration": 0.5,
    "EventParameters": [
      { "ParameterID": "HapticIntensity", "ParameterValue": 0.6 },
      { "ParameterID": "HapticSharpness", "ParameterValue": 0.3 }
    ] } }

AudioCustom (synchronized audio)

{ "Event": { "Time": 0.0, "EventType": "AudioCustom",
    "EventWaveformPath": "impact_sound.wav",
    "EventParameters": [{ "ParameterID": "AudioVolume", "ParameterValue": 0.8 }]
  } }

Loading AHAP Files

func loadAHAPPattern(named name: String) -> CHHapticPattern? {
    guard let url = Bundle.main.url(forResource: name, withExtension: "ahap") else {
        return nil
    }
    return try? CHHapticPattern(contentsOf: url)
}

// Usage
func playPattern() {
    guard let pattern = loadAHAPPattern(named: "ShieldTransient") else { return }
    let player = try? engine?.makePlayer(with: pattern)
    try? player?.start(atTime: CHHapticTimeImmediate)
}

Multi-Event Crescendo Pattern

{
  "Version": 1.0,
  "Pattern": [
    { "Event": { "Time": 0.0, "EventType": "HapticTransient",
        "EventParameters": [
          { "ParameterID": "HapticIntensity", "ParameterValue": 0.3 },
          { "ParameterID": "HapticSharpness", "ParameterValue": 0.3 }] } },
    { "Event": { "Time": 0.15, "EventType": "HapticTransient",
        "EventParameters": [
          { "ParameterID": "HapticIntensity", "ParameterValue": 0.6 },
          { "ParameterID": "HapticSharpness", "ParameterValue": 0.5 }] } },
    { "Event": { "Time": 0.3, "EventType": "HapticTransient",
        "EventParameters": [
          { "ParameterID": "HapticIntensity", "ParameterValue": 1.0 },
          { "ParameterID": "HapticSharpness", "ParameterValue": 0.8 }] } }
  ]
}

Parameter Curves

Smooth intensity transitions:

{
  "Version": 1.0,
  "Pattern": [
    { "Event": { "Time": 0.0, "EventType": "HapticContinuous", "EventDuration": 1.0,
        "EventParameters": [
          { "ParameterID": "HapticIntensity", "ParameterValue": 0.5 },
          { "ParameterID": "HapticSharpness", "ParameterValue": 0.5 }] } },
    { "ParameterCurve": { "ParameterID": "HapticIntensityControl", "Time": 0.0,
        "ParameterCurveControlPoints": [
          { "Time": 0.0, "ParameterValue": 0.0 },
          { "Time": 0.5, "ParameterValue": 1.0 },
          { "Time": 1.0, "ParameterValue": 0.0 }] } }
  ]
}

Audio File Requirements

• Maximum size: 4.2 MB
• Maximum duration: 23 seconds
• Formats: WAV, CAF, AIFF, AAC
• Recommended: Use AAC for smaller file sizes

Troubleshooting

• AHAP fails to load: Verify JSON syntax, check audio file paths, ensure files in bundle
• Audio out of sync: Audio file too large/long, test on physical device

Core Haptics

Advanced haptic API for custom patterns. Available iOS 13+, requires iPhone 8+.

Four Fundamental Elements

1. Engine (CHHapticEngine) - Link to the phone's actuator 2. Player (CHHapticPatternPlayer) - Playback control 3. Pattern (CHHapticPattern) - Collection of events over time 4. Events (CHHapticEvent) - Building blocks specifying the experience

CHHapticEngine Lifecycle

import CoreHaptics

class HapticManager {
    private var engine: CHHapticEngine?

    func initializeHaptics() {
        guard CHHapticEngine.capabilitiesForHardware().supportsHaptics else { return }

        do {
            engine = try CHHapticEngine()
            engine?.stoppedHandler = { [weak self] _ in self?.restartEngine() }
            engine?.resetHandler = { [weak self] in self?.restartEngine() }
            try engine?.start()
        } catch {
            print("Failed to create haptic engine: \(error)")
        }
    }

    private func restartEngine() {
        try? engine?.start()
    }
}

Critical: Always set stoppedHandler and resetHandler to handle system interruptions.

CHHapticEvent Types

Transient Events (short tap)

let event = CHHapticEvent(
    eventType: .hapticTransient,
    parameters: [
        CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
        CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.5)
    ],
    relativeTime: 0.0
)

Parameters:

• hapticIntensity: 0.0 (barely felt) to 1.0 (maximum)
• hapticSharpness: 0.0 (dull thud) to 1.0 (crisp snap)

Continuous Events (sustained vibration)

let event = CHHapticEvent(
    eventType: .hapticContinuous,
    parameters: [
        CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.8),
        CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.3)
    ],
    relativeTime: 0.0,
    duration: 2.0
)

Creating and Playing Patterns

func playCustomPattern() {
    let events = [
        CHHapticEvent(eventType: .hapticTransient,
            parameters: [
                CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.5),
                CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.5)
            ], relativeTime: 0.0),
        CHHapticEvent(eventType: .hapticTransient,
            parameters: [
                CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
                CHHapticEventParameter(parameterID: .hapticSharpness, value: 1.0)
            ], relativeTime: 0.3)
    ]

    do {
        let pattern = try CHHapticPattern(events: events, parameters: [])
        let player = try engine?.makePlayer(with: pattern)
        try player?.start(atTime: CHHapticTimeImmediate)
    } catch {
        print("Failed to play pattern: \(error)")
    }
}

Advanced Player: Looping and Dynamic Updates

func startRollingTexture() {
    let event = CHHapticEvent(
        eventType: .hapticContinuous,
        parameters: [
            CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.4),
            CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.2)
        ],
        relativeTime: 0.0, duration: 0.5)

    do {
        let pattern = try CHHapticPattern(events: [event], parameters: [])
        let player = try engine?.makeAdvancedPlayer(with: pattern)
        player?.loopEnabled = true
        try player?.start(atTime: CHHapticTimeImmediate)
    } catch {
        print("Failed: \(error)")
    }
}

func updateIntensity(player: CHHapticAdvancedPatternPlayer?, value: Float) {
    let param = CHHapticDynamicParameter(
        parameterID: .hapticIntensityControl, value: value, relativeTime: 0)
    try? player?.sendParameters([param], atTime: CHHapticTimeImmediate)
}

Troubleshooting

Engine fails to start:

• Device < iPhone 8 doesn't support Core Haptics
• Haptics disabled in Settings or Low Power Mode enabled

func safelyStartEngine() {
    guard CHHapticEngine.capabilitiesForHardware().supportsHaptics else {
        useFallbackHaptics() // Use UIFeedbackGenerator
        return
    }
    try? engine?.start()
}

Haptics not felt:

• Check Settings > Sounds & Haptics > System Haptics is ON
• Check Low Power Mode is OFF
• Verify intensity > 0.3 (values below may be too subtle)

Haptic Design Principles

Apple's Causality-Harmony-Utility framework from WWDC 2021 for multimodal feedback design.

Causality: Make it Obvious What Caused the Feedback

Problem: User can't tell what triggered the haptic. Solution: Haptic timing must match the visual/interaction moment.

Good vs Bad Timing

// Good: Immediate feedback on touch
@objc func buttonTapped() {
    let generator = UIImpactFeedbackGenerator(style: .medium)
    generator.impactOccurred()  // Fire immediately
    performAction()
}

// Bad: Delayed feedback loses causality
@objc func buttonTapped() {
    performAction()
    DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
        let generator = UIImpactFeedbackGenerator(style: .medium)
        generator.impactOccurred()  // Too late - user confused
    }
}

WWDC Example

• Ball hits wall -> haptic fires at collision moment (correct)
• Ball hits wall -> haptic fires 100ms later (confusing)

Key Insight

Fire haptic at the exact moment the visual change occurs. Even 100ms delay breaks the illusion of physical feedback.

Harmony: Senses Work Best When Coherent

Problem: Visual, audio, and haptic don't match. Solution: All three senses should feel like a unified experience.

Matching Intensity Across Senses

Code Pattern

func playImpact(for objectMass: CGFloat) {
    // Match haptic intensity to visual/audio characteristics
    let normalizedMass = min(max(objectMass / 100.0, 0.0), 1.0)

    let generator = UIImpactFeedbackGenerator(style: .medium)
    generator.impactOccurred(intensity: normalizedMass)

    // Audio pitch should also scale with mass
    playSound(pitch: 1.0 - (normalizedMass * 0.5))
}

WWDC Example: Shield Transformation

Initial attempt: 3 transient pulses (haptic) + progressive continuous sound (audio) - no harmony. Solution: Continuous haptic + continuous audio - unified experience.

Utility: Provide Clear Value

Problem: Haptics used everywhere "just because we can." Solution: Reserve haptics for significant moments that benefit the user.

When to Use Haptics

When NOT to Use Haptics

Decision Framework

func shouldPlayHaptic(for event: UserEvent) -> Bool {
    switch event {
    case .buttonTap(let importance):
        return importance == .high  // Only important buttons
    case .selectionChange:
        return true  // Picker-style selection feedback
    case .scroll:
        return false  // Never haptic on scroll
    case .success, .error:
        return true  // Always confirm outcomes
    }
}

Audio-Haptic Synchronization

Matching Animation Timing

func performShieldTransformation() {
    // Start haptic simultaneously with animation
    playShieldPattern()

    UIView.animate(withDuration: 0.5) {
        self.shieldView.transform = CGAffineTransform(scaleX: 1.2, y: 1.2)
    }
}

Coordinated Start

func playCoordinatedExperience() {
    impactGenerator.prepare()  // Reduce latency

    // Start both simultaneously
    audioPlayer.play()
    impactGenerator.impactOccurred()
}

Testing Checklist

• [ ] Does the haptic fire at the exact moment of visual change? (Causality)
• [ ] Do visual, audio, and haptic feel unified? (Harmony)
• [ ] Does this haptic provide clear value to the user? (Utility)
• [ ] Is the intensity appropriate for the action?
• [ ] Test with haptics disabled - does the UI still work?

Related WWDC Sessions

• Practice audio haptic design (WWDC 2021/10278)
• Introducing Core Haptics (WWDC 2019/520)
• Expanding the Sensory Experience (WWDC 2019/223)

UIFeedbackGenerator

Simple haptic feedback API for most common use cases. Available iOS 10+.

Three Generator Types

UIImpactFeedbackGenerator

Physical collision or impact sensation.

Styles: .light, .medium (most common), .heavy, .rigid, .soft

class MyViewController: UIViewController {
    private let impactGenerator = UIImpactFeedbackGenerator(style: .medium)

    override func viewDidLoad() {
        super.viewDidLoad()
        impactGenerator.prepare() // Reduces latency
    }

    @objc func buttonTapped() {
        impactGenerator.impactOccurred()
    }
}

// Intensity variation (iOS 13+): 0.0 to 1.0
impactGenerator.impactOccurred(intensity: 0.5)

UISelectionFeedbackGenerator

Discrete selection changes. Feels like clicking a physical wheel.

private let selectionGenerator = UISelectionFeedbackGenerator()

func pickerView(_ picker: UIPickerView, didSelectRow row: Int, inComponent component: Int) {
    selectionGenerator.selectionChanged()
}

Use cases: Picker wheels, segmented controls, page indicators

UINotificationFeedbackGenerator

System-level success/warning/error feedback.

let notificationGenerator = UINotificationFeedbackGenerator()

func submitForm() {
    if isValid {
        notificationGenerator.notificationOccurred(.success)
    } else {
        notificationGenerator.notificationOccurred(.error)
    }
}

Types: .success, .warning, .error

Performance: prepare()

Call prepare() before the haptic to reduce latency (~1 second window).

// Good: Prepare on touch down, fire on touch up
@IBAction func buttonTouchDown(_ sender: UIButton) {
    impactGenerator.prepare()
}

@IBAction func buttonTouchUpInside(_ sender: UIButton) {
    impactGenerator.impactOccurred() // Immediate
}

Common Patterns

HapticButton

class HapticButton: UIButton {
    private let impactGenerator = UIImpactFeedbackGenerator(style: .medium)

    override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
        super.touchesBegan(touches, with: event)
        impactGenerator.prepare()
    }

    override func touchesEnded(_ touches: Set<UITouch>, with event: UIEvent?) {
        super.touchesEnded(touches, with: event)
        impactGenerator.impactOccurred()
    }
}

Slider Scrubbing

class HapticSlider: UISlider {
    private let selectionGenerator = UISelectionFeedbackGenerator()
    private var lastValue: Float = 0

    @objc func valueChanged() {
        if abs(value - lastValue) >= 0.1 {
            selectionGenerator.selectionChanged()
            lastValue = value
        }
    }
}

Pull-to-Refresh

func scrollViewDidScroll(_ scrollView: UIScrollView) {
    if scrollView.contentOffset.y <= -100 && !isRefreshing {
        impactGenerator.impactOccurred()
        isRefreshing = true
        beginRefresh()
    }
}

Success/Error Feedback

func handleServerResponse(_ result: Result<Data, Error>) {
    let generator = UINotificationFeedbackGenerator()
    switch result {
    case .success: generator.notificationOccurred(.success)
    case .failure: generator.notificationOccurred(.error)
    }
}