--- title: Generating a remote notification framework: usernotifications role: article role_heading: Article path: usernotifications/generating-a-remote-notification --- # Generating a remote notification Send notifications to the user’s device with a JSON payload. ## Overview Overview Remote notifications convey important information to the user in the form of a JSON payload. The payload specifies the types of user interactions (alert, sound, or badge) that you want performed, and includes any custom data your app needs to respond to the notification. A basic remote notification payload includes Apple-defined keys and their custom values. You may also add custom keys and values specific to your notifications. Apple Push Notification service (APNs) refuses a notification if the total size of its payload exceeds the following limits: For Voice over Internet Protocol (VoIP) notifications, the maximum payload size is 5 KB (5120 bytes). For all other remote notifications, the maximum payload size is 4 KB (4096 bytes). Create the JSON payload Specify the payload for a remote notification using a JSON dictionary. Inside this dictionary, include an aps key whose value is a dictionary containing one or more additional Apple-defined keys, listed in Table 1. You can include keys instructing the system to display an alert, play a sound, or badge your app’s icon. You can also instruct the system to handle the notification silently in the background. For more information, see Pushing background updates to your App. In addition to the Apple-defined keys, you may add custom keys to your payload to deliver small amounts of data to your app, notification service app extension, or notification content app extension. Your custom keys must have values with primitive types, such as dictionary, array, string, number, or Boolean. Custom keys are available in the userInfo dictionary of the UNNotificationContent object delivered to your app. Typically, you use custom keys to help your code process the notification. For example, you might include an identifier string that your code can use to look up app-specific data. Add app-specific keys as peers of the aps dictionary. Listing 1 shows a notification payload that displays an alert message inviting the user to play a game. If the category key identifies a previously registered UNNotificationCategory object, the system adds action buttons to the alert. For example, the category here includes a play action to start the game immediately. The custom gameID key contains an identifier that the app can use to retrieve the game invitation. Listing 1. A remote notification payload for showing an alert { "aps" : { "alert" : { "title" : "Game Request", "subtitle" : "Five Card Draw", "body" : "Bob wants to play poker" }, "category" : "GAME_INVITATION" }, "gameID" : "12345678" } Listing 2 shows a notification payload that badges the app’s icon and plays a sound. The specified sound file must be on the user’s device already, either in the app’s bundle or in the Library/Sounds folder of the app’s container. The messageID key contains app-specific information for identifying the message that caused the notification. Listing 2. A remote notification payload for playing a sound { "aps" : { "badge" : 9, "sound" : "bingbong.aiff" }, "messageID" : "ABCDEFGHIJ" } For more information about creating sounds for your notifications, see UNNotificationSound. important: Don’t include customer information or any sensitive data, like a credit card number, in a notification’s payload. If you must include customer information or sensitive data, encrypt it before adding it to the payload. You can use a notification service app extension to decrypt the data on the user’s device. For more information, see Modifying content in newly delivered notifications. Localize your alert messages There are two ways to localize the content of remote notifications: Include localized strings directly in the payload. Add localized message strings in your app bundle, and let the system choose which strings to display. Placing localized strings directly into the payload gives you more flexibility, but requires you to track the user’s preferred language on your provider server. Because your provider server supplies the strings, it must know which language to use. On the user’s device, you can retrieve the user’s preferred languages by examining the preferredLanguages property of NSLocale. Your app can then forward that information to your server. If the text of your notification messages is predetermined, you can store your message strings in the Localizable.strings file of your app bundle and use the title-loc-key, subtitle-loc-key, and loc-key payload keys to specify which strings you want to display. Your localized strings may contain placeholders so that you can insert content dynamically into the final string. Listing 3 shows an example of a payload with a message derived from an app-provided string. The loc-args key contains an array of replacement variables to substitute into the string. Listing 3. A remote notification payload with localized content { "aps" : { "alert" : { "loc-key" : "GAME_PLAY_REQUEST_FORMAT", "loc-args" : [ "Shelly", "Rick"] } } } For more information about the keys you use for localized content, see Table 2. Payload key reference Table 1 lists the keys that you may include in the aps dictionary. To interact with the user, include the alert, badge, or sound keys. Don’t add your own custom keys to the aps dictionary; APNs ignores custom keys. Instead, add your custom keys as peers of the aps dictionary, as shown in Listing 1. Table 1. Keys to include in the aps dictionary | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Table 2 lists the keys that you may include in the alert dictionary. Use these strings to specify the title and message to include in the alert banner. Table 2. Keys to include in the alert dictionary | | | | | | | | | | | | | | | | | | | | | | Table 3 lists the keys that you may include in the sound dictionary. Use these keys to configure the sound for a critical alert. Table 3. Keys to include in the sound dictionary | | | | | | | | The figure below shows the default placement of the title, subtitle, and body content in a banner notification. To customize the appearance of alerts, use a notification content app extension as described in Customizing the Appearance of Notifications. ## See Also ### Server tasks - [Registering your app with APNs](usernotifications/registering-your-app-with-apns.md) - [Pushing background updates to your App](usernotifications/pushing-background-updates-to-your-app.md) - [Establishing a connection to Apple Push Notification service (APNs)](usernotifications/establishing-a-connection-to-apns.md)