The 3 Ps to Custom Alert Sounds in iOS Push Notifications
Quick personal intro: This is my first blog on Medium but I’m no stranger to iOS development for apps featuring push notifications. I plan to blog here about my interests in mobile development, connected devices, and cloud architecture. I spend most of my days exploring mobile software solutions and have a special interest in iOS. At times I’ll dive deep into specific mobile topics and other times I’ll stay on the surface of a new idea or implementation to get a feel for the interest level. I hope you enjoy my musings. Whatever your reaction, I welcome you to share it with me.
In mobile app development, one of the most exciting features you can enable in your app is notifications. The ultimate engagement tool, notifications give you the opportunity to provide messaging (e.g., alerts, rewards, promotions, etc.) tailored to each user. But to increase app retention and improve user experience, consider adding custom sound(s) to your push notifications. Like other sensory triggers, these audio clips can ultimately create an emotional connection with your users. And that’s when the magic happens.
Today’s blog focuses on how to enable mobile push notification sounds through the steps of the 3 Ps: prepare audio files and package requirements, play audio files embedded in the app, and publish a reference to the audio files in the app when sending remote notifications to app users. Also, I’ll share with you some insider tidbits based on my experiences.
iOS provides Local and Remote Notifications that are short text messages, images, sounds, and other media that can be pushed to your app users. These notifications are delivered to the device to trigger your app to display text, play a sound, increase badge count, or silently initiate a background task even if the user is not actively using the app.
In this exercise, I’ll focus on Remote Notifications.
Remote notifications look almost identical to local notifications but instead pushed to the user devices from your server (or services) via the Apple Push Notification service (APNs). They can also be sent silently to trigger your app to do something like download new content or check-in with a service.
Now that you are familiar with remote notifications, let’s get back to the custom sounds piece. As I mentioned before, notifications can send text, images, badge updates, and sounds to alert the app user. By default, a notification contains an alert message that is displayed to the user without playing a sound. If you want to play a sound when a notification arrives, Apple provides one “default” sound that you can specify; otherwise, you need to create a custom sound file and add it to your app bundle before publishing to the app store.
[Prepare Audio Files]
In iOS, you can specify a sound that plays when your app presents a notification. As I mentioned earlier, there is one default iOS sound file built into the OS and it does not need to (and doesn’t) exist in your application bundle. To enable the app to play the “default” iOS sound when sending a push notification, you simply provide the following key/value in the “aps” payload like this: “sound” : “default”.
The majority of mobile app developers elect the default iOS sound file for their push notification alerts. My sense is they do so because either they’re unaware a custom option exists or they don’t know how to create and embed a custom audio file in their apps. But with a few easy steps, a custom audio file can give your app personality and uniqueness so users immediately identify a sound with an alert from your app.
For custom audio files, you must first create the file (or use an existing audio file) in the correct file format (.aiff, .caf, or .aiff) and audio format (aLaw, MA4, Linear PCM, or µLaw) for your app bundle.
Once your custom audio file is ready, you must place it in the application bundle (top level directory of your Xcode project) of the client app or in the Library/Sounds folder of your app’s data container. Custom alert sounds are played by your app when it receives a reference to the audio file in the notification payload (more about that in a minute). To place your sound file in the application bundle,….
Now that you understand audiophile basics and have bundled your custom audio files in your app, let’s talk about audio playback app requirements. You’ll need to provide code in the client app to handle the push notification message, parse the payload, and play the specified audio.
[Play Audio Files]
All remote push notifications are received by your app in the app delegate and handled by two methods depending on whether the app is running in the foreground or backgrounded. If the app is running in the foreground (user is actively using the app), the system sends the remote notification payload to application:didReceiveRemoteNotification: method. If the app is not active (not running in foreground), the system passes the notification payload on to the application:didReceiveRemoteNotification:fetchCompletionHandler: method of your app delegate.
It is the developer’s responsibility for handling the remote notification in both methods. In either case, the payload is passed in under a userInfo dictionary. The userInfo dictionary is sent by the OS potentially containing a badge number, app icon, sound file name, and alert message to display to the user. This dictionary should match the payload that you’ll send in the next section. You simply need to parse out the dictionary into key-values for handling of the alert message and audio file reference.
Here’s a snippet of functions used to parse userInfo looking for the “sound” key/value and playing the sound (using AudioToolbox) when a notification arrives.
[Publish a Push Notification with Custom Sound Payload]
Now that your iOS app has a bundled custom audio file and can parse the userInfo dictionary and play audio files, we need to publish/send a specific payload from the server to the devices. For a developer to send a remote push notification, he or she must first know the unique Apple push token associated with a device running your app. All remote push notifications go through the Apple Push Notification service (APNs) by specifying a JSON dictionary containing the notification’s payload; however, developers typically do not publish notifications directly to Apple’s APNs but instead go through a third-party provider such as Amazon Pinpoint or Amazon SNS.
Whatever provider you choose, the payload is the same as Apple requires the following standard format for a simple alert message and sound:
Default and custom sounds can be delivered to iOS devices by passing along the “sound” APS Dictionary Key as part of the Remote Notification Payload sent to APNs (mostly via a third party).
Note: If you send a notification payload that includes a reference to a sound file that does not exist in the app bundle or in the Library/Sounds folder, the app will play the “default” sound. For example, payload key/value “sound” : “bellring.aiff” tells the app to play the bellring.aiff file located in the app bundle. If that exact file is not found, the app will play the “default” sound instead. Also, there’s no way to tell the OS to silence the notification or take other actions at runtime if the specified sound file does not already exist in the app. So be sure the custom sound file exists in your app before publishing.
Once you publish to APNs with the “sound” key/value specifying the custom audio file, the app will receive the message, parse it, and play the specified audio.
Let’s recap what it takes to prepare, play, and publish custom sounds in push notifications for iOS applications:
1. Obtain an .aiff, .caf, or .wav audio file or make your own.
2. Add the audio file to your Application Bundle (placed at the top level directory).
3. Add audioPlayer code to your app delegate methods to parse the notification userInfo dictionary and play the specified sound file stored in the application bundle.
4. Build and deploy app to device.
5. From the server (third-party provider), publish a message to the device using the “aps” payload “sound” key specifying the name of the audio file that you want the app to play when a notification is received. For example, if you bundled the custom audio file “tarzanwut.wav” to your application bundle and you want this audio to play when a push notification arrives, this is what the notification payload would look like:
Here’s a demo of what the user experiences on the device :).
Finally, as promised, here are a few insider tidbits for push notification audio files:
Audio files cannot be longer than 30 seconds. If you uploaded an audio file to the app bundle that is longer than 30 seconds, the iOS “default” audio sound will play on the device instead.
If the mobile phone or tablet is set to silent when a remote notification “Sound” key arrives, the app will show the alert message AND VIBRATE the phone instead of playing the custom or “default” audio. “Silent mode” is determined by the position of the hardware mute button on the side of the phone or tablet.
Be aware of the local time zones of your app users when sending audio alerts or you may alarm them during standard sleeping hours.
Now go add some audio (i.e., personality) to your push notifications. If nothing else, thinking about what sound file is right for your app will encourage you to analyze its uniqueness. Have fun with it!
