Fall Detection API in Swift for watchOS

I was recently implementing the Fall Detection API in Swift/SwiftUI for watchOS, and I had a lot of trouble getting it working. The documentation was very sparse, and I ended up wasting a lot of hours trying to figure out how to use the API. I was finally able to get it working after about 95% of the way through, but I was still stuck on one error “Fall Detection entitlement is required for this API”. Thanks to Brett Best from the iOS Developer community on Slack, who is an expert in iOS development. Brett was able to help me figure out the last piece of the puzzle, and I was finally able to get the API working. I was so relieved to finally have it working, and I decided to write this article to help others who might be struggling with the same issue.

In this article, I will walk you through the steps on how to use the Fall Detection API in Swift for watchOS. I will also provide some tips that I learned along the way that will hopefully help you avoid some of the same pitfalls that I did.

The Fall Detection API in watchOS allows you to detect when a wearer falls and take appropriate action. This can be used to send an emergency notification, call for help, or simply notify the wearer that they have fallen.

To use the Fall Detection API, you must first apply for the entitlement from Apple using this link. After filling in all the details and submitting the request it normally takes 2–3 days to get a response from Apple. Once you have been granted the entitlement you will receive an email from Apple.

The response email from Apple

Once your request gets approved then comes the fun part. Below are the four steps which will let see the API in action in no time:

Step 1:

Add the following keys to your app’s Info.plist file:

• NSFallDetectionUsageDescription

The NSFallDetectionUsageDescription key is a string that describes why your app needs access to the Fall Detection API.

The fall detection usage key in the info.plist

Step 2:

Enable the Fall Detection Notifications capability in your developer account. To do that go to your developer account then go to identifiers and select your desired app identifier. Then go to additional capabilities and enable the Fall detection Notifications and click save.

Enabling the fall detection notifications in the developer account

Step 3:

Add the entitlements key to your entitlements file in Xcode. Add ‘com.apple.developer.health.fall-detection’ as Key, ‘Boolean’ as Type, and ‘Yes’ as Value.

The fall detection key in the entitlements file

Step 4:

Start using the Fall Detection API. The following code shows how to request authorization from the user and handle a fall event:

import CoreMotion

class FallDetectionManager: NSObject, CMFallDetectionDelegate {

  let fallDetectionManager = CMFallDetectionManager()

  override init() {
    super.init()
    fallDetectionManager.delegate = self
    fallDetectionManager.requestAuthorization { status in
        switch status {
        case .notDetermined:
            print("notDetermined")
        case .restricted:
            print("restricted")
        case .denied:
            print("denied")
        case .authorized:
            print("authorized")
        @unknown default:
            print("unknown")
        }
    }
  }

  func fallDetectionManager(_ fallDetectionManager: CMFallDetectionManager, didDetect event: CMFallDetectionEvent) async {
    print("fall detected!", event.date, event.resolution.rawValue)
  }
}

To use that all you need to do is this

struct DetectionView: View {
    
    let fallDetectionManager = FallDetectionManager()
    
    var body: some View {
        Text("Fall detection in process...")
    }
}

This code will request authorization from the user to use the Fall Detection API. If the user grants permission,

The permission alert for giving access to the app to listen to fall detection events

the delegate will then listen for fall events. When a fall event is detected, the code will print a message to the console. Now the print message contains two values the ‘event.date’ when the fall was detected and the ‘event.resolution.rawValue’ against that fall detection notification.

And that is all it takes to implement Apple’s Fall Detection API for watchOS.

Oh, wait! I am not done yet. 😎

How are you going to test this API? 🤔

Well, luckily Xcode makes that really easy for us. Run the app using any watch simulator but it must be a Series 4 or later. Once the app is launched you will see the permission alerts as shown in the screenshots above, after allowing the permission. Select your simulator and from the menu bar go to Features > Simulate Fall and select any resolution you want. You will see the date and the response you have chosen printed in the console.🤯

Simulating the fall using the Apple Watch simulator

Furthermore, the fall detection resolution is an enum and these are all the cases.

Alright, I am done. This was epic, The Fall Detection API is a powerful tool that can be used to help people who are at risk of falling. I hope you enjoyed it and found this article helpful. If you have any questions, please feel free to leave a comment below. And if you’re interested in learning more about the Fall Detection API, I encourage you to check out the Apple Developer documentation.

If you want to get in touch or are interested in more content like this visit https://swiftshorts.com or https://saifullahsajid.com.