Sending broadcast push notification requests to APNs

Overview

Starting with iOS 18 and iPadOS 18, devices can subscribe on channels to receive updates for Live Activities. You can send a single push notification to APNs on the channel to update a Live Activity event to a large audience. When you have a notification to send on a channel, your provider must construct a POST request and send it to APNs. Upon receiving your server’s POST request, APNs validates the request using either the provided authentication token or your server’s certificate. If authentication succeeds, APNs then validates the channel ID you’re using to send the push notification. After channel validation, APNs tries to send your JSON payload to all the devices subscribed to the channel. For information on sending test notifications without setting up the environment, refer to Testing notifications using the Push Notification Console.

As a best-effort service, APNs may reorder notifications you send on the same channel. If APNs can’t deliver a notification immediately, it may store the notification based on the channel’s message storage policy specified during channel creation. Notifications with Medium and Low apns-priority might get grouped and delivered in bursts to the person’s device. APNs may also throttle your notifications and, in some cases, not deliver them. The exact behavior is determined by the way the person interacts with your application and the power state of the device.

Establish a connection to APNs

Use HTTP/2 and TLS 1.2 or later to establish a connection between your provider server and one of the following servers:

• Development/Sandbox Environment: api.sandbox.push.apple.com:443

• Production Environment: api.push.apple.com:443

For more details on establishing a connection to the APNs server to send requests, refer to Establishing a connection to Apple Push Notification service (APNs).

Send a POST request to APNs

Include header fields in your notifications or the system won’t be able to deliver them. In addition to the preceding data, add the following header fields in to your request. Other headers are optional or may depend on whether you’re using token-based or certificate-based authentication.

Put the JSON payload with the notification’s content into the body of your request. Don’t use a compressed JSON payload, and the payload is limited to a maximum size of 5 KB (5,120 bytes).

The code snippet below shows a sample request constructed with an authentication token to the development enviroment.

HEADERS
  - END_STREAM
  + END_HEADERS
  :method = POST
  :scheme = https
  :path = 4/broadcasts/apps/com.example.MyApp
  host = api-broadcast.sandbox.push.apple.com
  authorization = bearer eyAia2lkIjogIjhZTDNHM1JSWDciIH0.eyAiaXNzIjogIkM4Nk5WOUpYM0QiLCAiaWF0I
         jogIjE0NTkxNDM1ODA2NTAiIH0.MEYCIQDzqyahmH1rz1s-LFNkylXEa2lZ_aOCX4daxxTZkVEGzwIhALvkClnx5m5eAT6
         Lxw7LZtEQcH6JENhJTMArwLf3sXwi
  apns-id = eabeae54-14a8-11e5-b60b-1697f925ec7b
  apns-push-type = liveactivity
  apns-expiration = 0
  apns-priority = 10
  apns-channel-id = dHN0LXNyY2gtY2hubA==
DATA
  + END_STREAM
  {
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "content-state": {
            "currentHealthLevel": 0.0,
            "eventDescription": "Power Panda has been knocked down!"
        },
        "alert": {
            "title": {
                "loc-key": "%@ is knocked down!",
                "loc-args": ["Power Panda"]
            },
            "body": {
                "loc-key": "Use a potion to heal %@!",
                "loc-args": ["Power Panda"]
            },
            "sound": "HeroDown.mp4"
        }
    }
}

The code snippet below shows a sample request constructed for use with a certificate.

HEADERS
  - END_STREAM
  + END_HEADERS
  :method = POST
  :scheme = https
  :path = 4/broadcasts/apps/com.example.MyApp
  host = api-broadcast.sandbox.push.apple.com
  apns-request-id = eabeae54-14a8-11e5-b60b-1697f925ec7b
  apns-push-type = liveactivity
  apns-expiration = 0
  apns-priority = 10
  apns-channel-id = dHN0LXNyY2gtY2hubA==
DATA
  + END_STREAM
  {
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "content-state": {
            "currentHealthLevel": 0.0,
            "eventDescription": "Power Panda has been knocked down!"
        },
        "alert": {
            "title": {
                "loc-key": "%@ is knocked down!",
                "loc-args": ["Power Panda"]
            },
            "body": {
                "loc-key": "Use a potion to heal %@!",
                "loc-args": ["Power Panda"]
            },
            "sound": "HeroDown.mp4"
        }
    }
}

APNs provides a response to each POST request your server transmits. Each response contains a header with fields indicating the status of the response. If the request succeeded, the body of the response is empty. A successful request provides the following fields in the response.

Pay attention to status returned by APNs for each push notification and take appropriate action for your application in case of error. For more information on how to handle error responses, refer to Handling error responses from Apple Push Notification service

See Also

Broadcast push notifications

• Setting up broadcast push notifications
• Sending channel management requests to APNs
• Handling error responses from Apple Push Notification service