Customize Push Notification Functionality for iOS Apps

Extend push notification support in your mobile app beyond the built-in functionality of basic configuration with the following customization options.

Custom Sound

Play a custom sound when a push notification arrives.

Interactive Notifications

Display buttons on your push notifications.

Rich Notifications

Include photos and videos.

Custom Keys

Send extra data along with a push notification. For example, add tracking to your mobile app.

URL Handling

Handle URLs from push notifications

This feature uses a sound included in your mobile app as a custom audio signal when a push message arrives on the mobile device.

  1. Add a file named custom.caf to your project. The cloud push payload looks for a file named custom.caf.
  2. Add the custom.caf audio file to the Copy Bundle Resources folder in Xcode for your app.
  3. To prevent Xcode from using cached files, perform a clean build folder in Xcode. In the Product menu, hold the Option key and select Clean Build Folder.
  4. Ask your Marketing Cloud Engagement admin to enable custom sound on the MobilePush Administration page on the Engagement UI.

Use interactive notifications to add buttons to push notifications from your mobile app. Engagement sends the category name for these interactive notifications in the message payload.

  1. To set up interactive notifications for your app, use the sample code in the Example Implementation section as a reference and adapt it to your specific requirements.

    The sample code applies to the AppDelegate.m didFinishLaunchingWithOptions application delegate method. The sample code shows how to create a category named Example. When you send this category with the payload from Engagement, the notification displays in the notification center with buttons for user interaction.

  2. To check if your action triggered and your app performed the necessary response, examine the push notification’s payload in your push handler. Use the sample code in the Example: Handle Actions section as a reference and adapt it to your specific requirements.

  3. After setup, ask your marketing admin to enable interactive notifications on the MobilePush Administration page in the Engagement UI.

In your push handler, examine the push notification’s payload to see if your action is triggered and if your application performed the action.

Rich notifications include images, videos, titles, and subtitles from the MobilePush app and mutable content. Mutable content can include personalization in the title, subtitle, or body of your message.

  • Make sure that your app is built for iOS version 10 and above.
  • Include a service extension for your app that can handle mutable content. For information on adding a service app extension, see Modifying and Presenting Notifications.
  • Make sure that your app is registered for push notifications via the MobilePush SDK.
  1. Click File.
  2. Click New.
  3. Click Target.
  4. Select Notification Service Extension.
  5. Name and save the new extension.
  6. Verify in your project target’s general settings that the new extension was added to the Frameworks, Libraries, and Embedded Content section. If not present, add it.

The same Xcode Managed Profile that signs the main project must sign the Notification Target.

This service extension checks for a _mediaUrl element in request.content.userInfo. If found, the extension attempts to download the media from the URL, creates a thumbnail-size version, and then adds the attachment. The service extension also checks for a _mediaAlt element in request.content.userInfo. If found, the service extension uses the element for the body text if there are any problems downloading or creating the media attachment.

A service extension can time out when it’s unable to download. In the following code sample, the service extension delivers the original content with the body text changed to the value in _mediaAlt.

Use custom keys to send extra data along with a push notification. You can use custom keys to add tracking or additional functionality to your app. For example, you can define a custom key that allows a third-party application to provide custom tracking information regarding customer usage on your mobile app. This data can include an ID value used by the app to retrieve additional data or other function.

You must enable this feature in the Administration page on the Engagement UI.

To implement custom key support in your application, extend your push notification handler to extract the push’s userInfo dictionary and the values contained in it.

OpenDirect customized push messages contain a URL in the payload. MobilePush SDK can pass this URL to your application to handle according to your situation. For information on how to handle URLs from OpenDirect customized push notifications, see Handle URLs.

Your marketing admin can enable OpenDirect via the Administration page on the Engagement UI.

The SDK doesn’t automatically present URLs from the following sources.

  • CloudPages URLs from push notifications
  • OpenDirect URLs from push notifications
  • CloudPages URLs from inbox messages using the built-in UITableView delegate

To handle URLs from these sources, follow these steps.

  1. Implement the URLHandlingDelegate (v8.x) or MarketingCloudSDKURLHandlingDelegate (v7.x) protocol in your app.
  2. Use setURLHandlingDelegate (v8.x) or sfmc_setURLHandlingDelegate: method to set a delegate for the protocol.
  3. Next, you’re prompted to implement the protocol method sfmc_handleURL:type:

When an OpenDirect or CloudPages push notification is received, the SDK passes a NSURL value to sfmc_handleURL:type:. This value contains the push notification or inbox message, and includes the URL. A type value also reflects the source of the URL, which is either SFMCURLTypeCloudPages or SFMCURLTypeOpenDirect.

If the development language is Swift, the class that implements the URLHandlingDelegate (v8.x) or MarketingCloudSDKURLHandlingDelegate (v7.x) delegate must be Objective-C compatible. This means that you must prefix the class with @objc and extend NSObject, as shown in the following example.