Cheatsheet for the JSON payload of an iOS push notification

When configuring the JSON payload of an iOS push notification, there are a lot of configurations options we can choose from. This guide serves as a reference and cheatsheet for those configuration options.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free

Basic JSON payload structure

The payload for a remote notification is a JSON dictionary with the following basic structure:

{
  "aps": {
    "alert": "Title of the push notification",
    "sound": "default",
    // More configuration keys and values
  },
  "customKey1": "Some content",
  "customKey2": "Some other content",
  // More custom keys and values.
}

As we can see above, the JSON is a dictionary which can contain custom keys for example to provide a deep link or additional information our app may need.

To customize the push notification, we can use the aps dictionary as also shown above. Let's explore those keys and their effects on the push notification.

The alert key

The value for the alert key can either be a String or a Dictionary.

{
  "aps": {
    "alert": "Title of the push notification"
  }
}

The configuration above produces the following push notification:

Alternatively, we can specify the notification's title, subtitle and body:

{
  "aps": {
    "alert": {
        "title": "Title of the notification",
        "subtitle": "Subtitle of the notification",
        "body": "The content of the notification."
    }
  }
}

Which results in the following output:

There is also the possibility to use localized keys instead:

{
   "aps" : {
      "alert" : {
         "title-loc-key" : "notification.newMessage.title",
         "title-loc-args" : [ "argument1", "argument2"],
         "subtitle-loc-key" : "notification.newMessage.subtitle",
         "body-loc-key" : "notification.newMessage.body",
      }
   }
}

The keys stored in Localizable.strings will automatically be used.

The badge key

The badge key is used to specify the number that will appear on the app's icon as a badge.

{
  "aps" : {
    ...
    "badge" : 0
  }
}

The value 0 removes the current badge.

The sound key

The sound key is used to specify the sound that will play when the notification is received which can either be a default, a custom or a critical sound.

Default sound

{
   "aps" : {
      ...
      "sound" : "default"
   }
}

The example above plays the system sound.

Custom sound

{
   "aps" : {
      ...
      "sound" : "applause.wav"
   }
}

As shown above, we can specify a sound file in the app's main bundle in .aiff, .wav or .caf file format to be played when the notification is shown.

Critical sound

A critical sound plays even if Do Not Disturb is turned on or the device is muted. Only apps approved for the critical alerts entitlement are allowed to send critical alerts. For example:

{
   "aps" : {
      ...
      "sound": {
        "critical" : 1,
        "name": "default", // or name of a sound file in the app's main bundle
        "volume": 1 // value between 0 (silent) and 1 (full volume)
      }
   }
}

The thread-id key

An identifier for grouping related notifications, for example:

{
   "aps" : {
      ...
      "thread-id": "com.tanaschita.newArticle"
   }
}

The iOS system will automatically sum up notifications with the same thread-id into a group when showing them in the notification center.

The category key

The category key can be used to add custom actions to the notification.

{
   "aps" : {
      ...
      "category" : "drinkingReminderCategory"
   }
}

Checkout this article on how to add custom actions for iOS notifications to learn more.

The content-available key

The content-available key declares the notification as a background notification.

A background notification doesn't display an alert, play a sound or show a badge. It wakes the app in the background and gives it time to initiate downloads and update its content.

{
   "aps" : {
      "content-available" : 1
   }
}

Check out the official documentation on pushing background updates to your app to learn more about background notifications.

The mutable-content key

The mutable-content key can be used if we need to modify the payload of a remote notification before it's shown to the user, for example to decrypt data or to incorporate additional content based on data within the application.

{
   "aps" : {
      "mutable-content" : 1,
      ...
   },
}

Modifying a remote notification requires a notification service app extension, which receives the contents of the notification before is is displayed to the user to be able update the notification payload.

Check out the official documentation on modifying content in newly delivered notifications to learn more.

The interruption-level key

The interruption-level key represents the importance and delivery timing of a notification:

{
   "aps" : {
      "interruption-level" : "active",
      ...
   },
}

The following values are available:

• active - presents the notification immediately, lights up the screen, can play a sound.
• critical - presents the notification immediately, lights up the screen, bypasses the mute switch to play a sound.
• passive - adds the notification to the notification list without lighting up the screen or playing a sound.
• timeSensitive - similar to active notifications, but can break through system controls such as Notification Summary and Focus. The user can turn off the ability for time sensitive notification interruptions.

The relevance-score key

The relevance score value is a number between 0 and 1, that the system uses to sort the notifications from the same iOS application.

{
   "aps" : {
      "relevance-score" : 1,
      ...
   },
}

The highest score gets featured in the notification summary.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free