Sending channel management requests to APNs

Overview

Broadcast push notifications use channels to reach a large number of people with Live Activities. To send updates with a Live Activity for an event such a sports game using broadcast push notifications, associate your event with a channel, identified by creating a unique channel ID. Store the association for each Live Activity event with a unique channel ID, and then share the channel ID with the devices. Devices use this channel identifier to subscribe to push notifications for each Live Activity event. Devices on iOS 18 and iPadOS 18 can subscribe to receive updates on channels using ActivityKit. For more information on using ActivityKit to subscribe for updates on a channel, refer to Starting and updating Live Activities with ActivityKit push notifications.

The figure below describes how your server communicates with Apple Push Notification service (APNs) when you create a channel. APNs returns a channel ID which your server shares with the people interested in receiving Live Activity updates. The device uses the channel ID to subscribe for broadcast push notifications on the channel.

[Image]

The lifecycles of the channel ID and Live Activity on device are independent. Specifically, a channel ID exists even if there are no active subscribers, or all subscribers remove the Live Activity. In order to support several simultaneous events, you can maintain up to 10,000 channels for your app in the development and production environment, respectively. Once the Live Activity event is complete, and you no longer plan to use the channel for any subsequent updates, delete the channel to avoid going over the allocated channel limit.

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-manage-broadcast.sandbox.push.apple.com:2195

• Production Environment: api-manage-broadcast.push.apple.com:2196

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).

Create a channel

To create a new channel, create and send a POST request to APNs with the appropriate configuration. Channel IDs generate randomly when you create them, and you can’t request a channel with a specific ID.

Message storage policy configured as part of the request can’t be modified later. The message storage policy of the channel determines if the channel stores deferred messages for offline devices. There are two available options: No Message Storage and Most Recent Message Stored. For activities with frequent updates like sports scores, use No Message Storage, which allows a higher publishing budget. For activities with infrequent updates, such as event tracking and flight updates, use Most Recent Message Stored. Messages in Most Recent Message store for a maximum duration of 8 hours. You can specify an earlier expiration of messages by setting an apns-expiration header when you send push notification on the channel.

The table below describes the HTTP/2 request fields:

The table below describes the JSON dictionary request body fields:

The code snippet below shows a sample to request a channel using a JWT.

curl -v -X POST \
-H "authorization: bearer <token>" \
-H "apns-request-id: 2288cf3f-70d8-46a6-97d7-dd5d00867127" \
-d '{"message-storage-policy": 1, "push-type": "LiveActivity"}' \
--http2 \
https://api-manage-broadcast.sandbox.push.apple.com:2195/1/apps/com.example.MyApp/channels 

HEADERS
  - END_STREAM
  + END_HEADERS
  :method = POST
  :scheme = https
  :path = /1/apps/com.example.MyApp/channels
  host = api-manage-broadcast.sandbox.push.apple.com
  authorization = bearer <token>
  apns-request-id = 2288cf3f-70d8-46a6-97d7-dd5d00867127
DATA
  + END_STREAM
  { "message-storage-policy": 1, "push-type": "LiveActivity" }

The response to a successful request contains the header fields described below, with the body of the response empty. On failure, the response body contains a JSON dictionary describing the error. For more information on how to handle error responses, refer to Handling error responses from Apple Push Notification service.

The table below describes the HTTP/2 response fields:

Read a channel

To read the configuration for a channel, construct and send a request over the connection you created using HTTP/2 and TLS. The table below describes the HTTP/2 request header fields:

The code snippet below shows a sample request constructed for reading the configuration for a channel using a JWT.

curl -v -X GET \
-H "authorization: bearer <token>" \
-H "apns-request-id: 2288cf3f-70d8-46a6-97d7-dd5d00867127" \
-H "apns-channel-id: dHN0LXNyY2gtY2hubA==" \ 
--http2 \
https://api-manage-broadcast.sandbox.push.apple.com:2195/1/apps/com.example.MyApp/channels 

HEADERS
  - END_STREAM
  + END_HEADERS
  :method = GET
  :scheme = https
  :path = /1/apps/com.example.MyApp/channels
  host = api-manage-broadcast.sandbox.push.apple.com
  authorization = bearer <token>
  apns-request-id = 2288cf3f-70d8-46a6-97d7-dd5d00867127
  apns-channel-id = dHN0LXNyY2gtY2hubA==
DATA
  + END_STREAM

The response to a successful request contains the header fields, and the body of the response is a JSON dictionary, as described below. On failure, the response body contains a JSON dictionary describing the error. For more information on how to handle error responses, refer to Handling error responses from Apple Push Notification service.

The table below describes the HTTP/2 response fields:

The table below describes the HTTP/2 response body:

Delete a channel

To delete an existing channel, construct and send a request that includes the channel ID over the connection with APNs. Deleting a channel doesn’t discard pending messages immediately. APNs may still deliver stored messages after you delete the channel. Deleting a channel is an irreversible action. Once you delete the channel, it’s no longer valid; don’t send any pushes to the channel. As channel IDs are randomly generated for channel creation requests, the same channel ID can’t be created again. The table below describes the HTTP/2 request header fields:

The code snippet below shows a sample request constructed for deleting a channel JWT.

curl -v -X DELETE \
-H "authorization: bearer <token>" \
-H "apns-request-id: 2288cf3f-70d8-46a6-97d7-dd5d00867127" \
-H "apns-channel-id: dHN0LXNyY2gtY2hubA==" \ 
--http2 \
https://api-manage-broadcast.sandbox.push.apple.com:2195/1/apps/com.example.MyApp/channels

HEADERS
  - END_STREAM
  + END_HEADERS
  :method = DELETE
  :scheme = https
  :path = /1/apps/com.example.MyApp/channels
  host = api-manage-broadcast.sandbox.push.apple.com
  authorization = bearer <token>
  apns-request-id = 2288cf3f-70d8-46a6-97d7-dd5d00867127
  apns-channel-id = dHN0LXNyY2gtY2hubA==
DATA
  + END_STREAM

The response to a successful request contains the header fields described below, with the body of the response empty. On failure, the response body contains a JSON dictionary describing the error. For more information on how to handle error responses, refer to Handling error responses from Apple Push Notification service.

The table below describes the HTTP/2 response fields:

Read all channel IDs for a bundle ID

To get the list all the current active channels for your app, you can send a GET request over the connection with APNs. The table below describes the HTTP/2 request fields:

The code snippet below shows a sample request constructed for listing all the channels belonging to a bundle ID.

curl -v -X GET \
-H "authorization: bearer <token>" \
-H "apns-request-id: 2288cf3f-70d8-46a6-97d7-dd5d00867127" \
--http2 \
https://api-manage-broadcast.sandbox.push.apple.com:2195/1/apps/com.example.MyApp/all-channels 

HEADERS
  - END_STREAM
  + END_HEADERS
  :method = GET
  :scheme = https
  :path = /1/apps/com.example.MyApp/all-channels
  host = api-manage-broadcast.sandbox.push.apple.com
  authorization = bearer <token>
  apns-request-id = 2288cf3f-70d8-46a6-97d7-dd5d00867127
DATA
  + END_STREAM

The response of a successful request contains the header fields described below, with the body of the response empty. On failure, the response body contains a JSON dictionary describing the error. For more information on how to handle error responses, refer to Handling error responses from Apple Push Notification service.

The table below describes the HTTP/2 response fields:

The key below describes the HTTP/2 response body for a successful request:

See Also

Broadcast push notifications

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