Contents

Establishing a connection to Apple Push Notification service (APNs)

Secure your communications with APNs to send API requests.

Overview

Use HTTP/2 and TLS 1.2 or later to establish a connection between your provider server and APNs server to send API requests. Based on the type of request you’re using, there’s a different development and production endpoint. If you’re shipping apps, use the production end points. If you’re testing, use the development endpoints. If you’re sending many remote notifications, you can establish multiple connections to these servers to improve performance.

APNs allows for 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, if you’re 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 you experience a revoked provider certificate, 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, refer to the response error strings in Handling notification responses from APNs.

Create a request to APNs

To send a notification to a person’s device, construct and send a POST notification to APNs. Send this request over the connection you created using HTTP/2 and TLS. To create your POST notification, you must already have the following pieces of information:

Send a request to APNs

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:

  • The first time you send an APNs documented header name, encode them with incremental indexing and add the header fields to the dynamic table. Reuse the indexed header name for subsequent requests.

  • Index and reuse an APNs documented header value that doesn’t change frequently for your use-case.

If you are using token-based authentication, the authorization header value shouldn’t change frequently and can be indexed. If you are using separate connections for different push types, apns-push-type header value can also be indexed and reused. If you are using broadcast push notifications, the channel ID used for push notifications might not change often and can be indexed.

Troubleshoot problems with connecting to APNs

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. Refer to Establishing a certificate-based connection to APNs.

  • Check how often your provider server connects to APNs. If your provider server 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_client command from your server, as shown below. This command can also show if your TLS/SSL certificates are expired or revoked.

The code listing below verifies the TLS handshake with device push notifications sandbox endpoint

$ openssl s_client -connect api.development.push.apple.com:443 -cert YourSSLCertAndPrivateKey.pem -debug 
-showcerts -CAfile server-ca-cert.pem

See Also

Server tasks