Send your remote notification payload and device token information to APNs.
When you have a notification to send to a user, your provider must construct a POST request and send it to APNs. Your request must include the following information:
The JSON payload that you want to send
The device token for the user's device
Request-header fields specifying options for how to deliver the notification
For token-based authentication, your provider server's current authentication token
Upon receiving your server's POST request, APNs validates the request using either the provided authentication token or your server's certificate. If validation succeeds, APNs uses the provided device token to identify the user's device. It then tries to send your JSON payload to that 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:
Use the production server for your shipping apps and the development server for testing. When sending many remote notifications, you can establish multiple connections to these servers to improve performance. For example, if you have multiple provider servers, each one can establish its own connection.
APNs allows multiple concurrent streams for each connection, but don't assume a specific number of streams. The exact number varies based on server load and whether you use a provider certificate or an authentication token. For example, when using an authentication token, APNs allows only one stream until you post a request with a valid authentication token. APNs ignores
HTTP/2 PRIORITY frames, so don't send them on your streams.
If your provider certificate is revoked, or if you revoke your authentication token, close all connections to APNs, fix the problem, and then open new connections. APNs may also terminate a connection by sending a
GOAWAY frame. The payload of the
GOAWAY frame includes JSON data with a
reason key, indicating the reason for the connection termination. For a list of values for the
reason key, see Table 5.
Create and Send a POST Request to APNs
To send a notification to a user’s device, construct and send a POST notification to APNs. Send this request over the connection you created using HTTP/2 and TLS. To construct your POST notification, you must already have the following pieces of information:
The device token that identifies the user device to receive the notification; see Registering Your App with APNs.
Your current authentication token (only if you are using token-based authentication); see Establishing a Token-Based Connection to APNs.
The notification’s payload, specified as JSON data; see Generating a Remote Notification.
In addition to the preceding data, add the header fields in Table 1 to your request. Some header fields are required for delivering the notification. Other headers are optional or may be dependent on whether you are using token-based or certificate-based authentication.
(Required) The value
(Required) The path to the device token. The value of this header is
(Required for token-based authentication) The path to the authentication token. The value of this header is
(Required when delivering notifications to devices running iOS 13 and later, or watchOS 6 and later. Ignored on earlier system versions.) The type of the notification. The value of this header is
The value of this header must accurately reflect the contents of your notification's payload. If there is a mismatch, or if the header is missing on required systems, APNs may delay the delivery of the notification or drop it altogether.
A canonical UUID that is the unique ID for the notification. If an error occurs when sending the notification, APNs includes this value when reporting the error to your server. Canonical UUIDs are 32 lowercase hexadecimal digits, displayed in five groups separated by hyphens in the form 8-4-4-4-12. For example:
The date at which the notification is no longer valid. This value is a UNIX epoch expressed in seconds (UTC). If the value is nonzero, APNs stores the notification and tries to deliver it at least once, repeating the attempt as needed until the specified date. If the value is
The priority of the notification. If you omit this header, APNs sets the notification priority to
The topic of the notification. When using token-based authentication, specify the bundle ID of the app. When using certificate-based authentication, the topic is usually your app's bundle ID. However, the topic may also correspond to the bundle ID of an Apple Watch complication or a background VoIP service. Look in the (
If you omit the header and your certificate does not contain multiple topics, APNs uses your certificate’s Subject as the default topic.
An identifier you use to coalesce multiple notifications into a single notification for the user. Typically, each notification request causes a new notification to be displayed on the user’s device. When sending the same notification more than once, use the same value in this header to coalesce the requests. The value of this key must not exceed 64 bytes.
APNs requires the use of HPACK (header compression for HTTP/2), which prevents repeatedly storing header keys and values. APNs maintains a small dynamic table for HPACK. To avoid filling up that table, encode your headers in the following way—especially when using many streams:
authorizationvalues as literal header fields without indexing.
apns-collapse-idvalues differently based on whether this is an initial or subsequent request.
The first time you send these headers, encode them with incremental indexing to add the header fields to the dynamic table.
For subsequent requests, encode these headers as literal header fields without indexing.
Encode all other fields as literal header fields with incremental indexing.
Put the JSON payload with the notification’s content into the body of your request. The JSON payload must not be compressed and is limited to a maximum size of 4 KB (4096 bytes). For a Voice over Internet Protocol (VoIP) notification, the maximum size is 5 KB (5120 bytes).
Listing 1 shows a sample request constructed with an authentication token
Listing 2 shows a sample request constructed for use with a certificate. APNs uses the app's bundle ID as the default topic.
Handle the Response from APNs
APNs provides a response for each request that you make. Each response contains a header with fields indicating the status of the response. If the request was successful, the body of the response is empty. If an error occurred, the body contains a JSON dictionary with additional information about what happened.
Table 2 describes the meaning of the keys in the header response.
The same value found in the
The HTTP status code. For a list of possible values, see Table 3.
Table 3 lists the possible values in the
: header of the response.
There was an error with the certificate or with the provider’s authentication token.
The request used an invalid
The device token is no longer active for the topic.
The notification payload was too large.
The server received too many requests for the same device token.
Internal server error.
The server is shutting down and unavailable.
Table 4 lists the keys found in the JSON dictionary for unsuccessful requests. The JSON data might also be included in a
GOAWAY frame when a connection is terminated.
The error code (specified as a string) indicating the reason for the failure. For a list of possible values, see Table 5.
The time at which APNs confirmed the token was no longer valid for the topic. This key is included only when the error in the
Table 5 lists the possible error codes included in the reason key of a response’s JSON payload.
The collapse identifier exceeds the maximum allowed size.
The specified device token is invalid. Verify that the request contains a valid token and that the token matches the environment.
The device token doesn't match the specified topic.
One or more headers are repeated.
The device token isn't specified in the request
The message payload is empty.
Pushing to this topic is not allowed.
The certificate is invalid.
The client certificate is for the wrong environment.
The provider token is stale and a new token should be generated.
The specified action is not allowed.
The provider token is not valid, or the token signature cannot be verified.
No provider certificate was used to connect to APNs, and the
The request contained an invalid
The device token is inactive for the specified topic.
The message payload is too large. For information about the allowed payload size, see Create and Send a POST Request to APNs.
The provider’s authentication token is being updated too often. Update the authentication token no more than once every 20 minutes.
Too many requests were made consecutively to the same device token.
An internal server error occurred.
The service is unavailable.
The APNs server is shutting down.
Listing 3 shows a sample response for a successful push request.
Listing 4 shows a sample response when an error occurs.
Troubleshoot Problems with Receiving Notifications
During testing, if you find that your test devices are not receiving push notifications sent by your provider server, examine the following possible causes:
Make sure that your provider server has an up-to-date device token for your test device. Each time your app launches, it should request its current token and forward that token to your provider server. You should also implement the appropriate failure handler methods to determine if APNs reported an error. See Registering Your App with APNs.
Check for errors returned by APNs. When failures occur, APNs reports an appropriate error back to your provider server. See Handle the Response from APNs.
Make sure you included the apns-push-type key in your request headers. This key is required starting in iOS 13 and watchOS 6. The absence of this key may delay the delivery of notifications, or prevent their delivery altogether. See Table 1.
Check to see if you are sending requests to the same device too quickly. APNs queues only one notification at a time for each device, and the device must acknowledge receipt of the notification before APNs dequeues it. If you send multiple notification requests in a very short period of time, each new request might overwrite the previous request.
Check to see if silent notifications are being throttled. APNs sends a limited number of silent notifications—notifications with the
content-availablekey—per day. In addition, if the device has already exceeded its power budget for the day, silent notifications are not sent again until the power budget resets, which happens once a day. These limits are disabled when testing your app from Xcode. See Pushing Background Updates to Your App.
Check the firewall settings of your server and devices. To send notifications, your provider server must allow inbound and outbound TCP packets over port 443 for HTTP/2 connections, or port 2195 when using the binary interface. Devices connecting to APNs over Wi-Fi need to allow inbound and outbound TCP packets over port 5223, falling back to port 443 if port 5223 is unavailable. Computers running macOS must also allow inbound and outbound TCP traffic on port 80.
Verify that you aren't spamming the device. If you send too many notifications to the same device within a short timespan, APNs may treat it as a denial-of-service attack and temporarily block your server from sending notifications.
If your provider server is unable to connect to APNs, examine the following possible causes:
Make sure you have the needed certificates installed on your provider server. If your provider server doesn't have the proper certificates for TLS/SSL validation, it cannot connect to APNs. For certificate-based connections, your provider server must also have the certificate you obtained from Apple. See Establishing a Certificate-Based Connection to APNs.
Check how often your provider server connects to APNs. If your provider server uses the legacy binary interface and opens and closes its connection to APNs repeatedly, APNs may treat it as a denial-of-service attack and temporarily block your server from connecting.
You can verify the TLS handshake between your provider server and APNs by running the OpenSSL
s command from your server, as shown in Listing 5. This command can also show if your TLS/SSL certificates are expired or revoked.