Package apns provide a Apple Push Notification service provider.
Apple Push Notification service (APNs) is the centerpiece of the remote
notifications feature. It is a robust and highly efficient service for
propagating information to iOS (and, indirectly, watchOS), tvOS, and macOS
devices. On initial activation, a device establishes an accredited and
encrypted IP connection with APNs and receives notifications over this
persistent connection. If a notification for an app arrives when that app is
not running, the device alerts the user that the app has data waiting for it.
You provide your own server to generate remote notifications for the users of
your app. This server, known as the provider, has three main
For each notification, the provider:
On receiving the HTTP/2 request, APNs delivers the notification payload to
your app on the user's device.
Apple Push Notification service includes a default Quality of Service (QoS)
component that performs a store-and-forward function. If APNs attempts to
deliver a notification but the destination device is offline, APNs stores the
notification for a limited period of time and delivers it to the device when
the device becomes available.
This mechanism stores only one recent notification per device, per app: if
you send multiple notifications while a device is offline, a new notification
causes the previous notification to be discarded.
If a device remains offline for a long time, all notifications that were
being stored for it are discarded; when the device goes back online, none of
the notifications are displayed.
When a device is online, all the notifications you send are delivered and
available to the user. However, you can avoid showing duplicate notifications
by employing a collapse identifier across multiple, identical notifications.
The APNs request header key for the collapse identifier is
For example, a news service that sends the same headline twice in a row could
employ the same collapse identifier for both push notification requests. APNs
would then take care of coalescing these requests into a single notification
for delivery to a device.
To ensure secure communication, APNs servers employ connection certificates,
certification authority (CA) certificates, and cryptographic keys (private
and public) to validate connections to, and identities of, providers and
devices. APNs regulates the entry points between providers and devices using
two levels of trust: connection trust and device token trust.
Connection trust establishes certainty that APNs is connected to an
authorized provider, owned by a company that Apple has agreed to deliver
notifications for. You must take steps to ensure connection trust exists
between your provider servers and APNs. APNs also uses connection trust with
each device to ensure the legitimacy of the device. Connection trust with the
device is handled automatically by APNs.
Device token trust ensures that notifications are routed only between
legitimate start and end points. A device token is an opaque, unique
identifier assigned to a specific app on a specific device. Each app instance
receives its unique token when it registers with APNs. The app must share
this token with its provider, to allow the provider to employ the token when
communicating with APNs. Each notification that your provider sends to APNs
must include the device token, which ensures that the notification is
delivered only to the app-device combination for which it is intended.
Important: To protect user privacy, do not attempt to use a device token to
identify a device.
Device tokens can change after updating the operating system, and always
change when a device's data and settings are erased. Whenever the system
delivers a device token to an instance of your app, the app must forward it
to your provider servers to allow further push notifications to the device.
A provider using the HTTP/2-based APNs Provider API can use JSON web tokens
(JWT) to validate the provider's connection with APNs. In this scheme, the
provider does not require a certificate-plus-private key to establish
connection. Instead, you provision a public key to be retained by Apple, and
a private key which you retain and protect. Your providers then use your
private key to generate and sign JWT authentication tokens. Each of your push
requests must include an authentication token.
Important: To establish TLS sessions with APNs, you must ensure that a
GeoTrust Global CA root certificate is installed on each of your providers.
You can download this certificate from the GeoTrust Root Certificates
The HTTP/2-based provider connection is valid for delivery to one specific
app, identified by the topic (the app bundle ID) specified in the
certificate. Depending on how you configure and provision your APNs Transport
Layer Security (TLS) certificate, the trusted connection can also be valid
for delivery of remote notifications to other items associated with your app,
including Apple Watch complications and voice-over-Internet Protocol (VoIP)
services. APNs delivers these notifications even when those items are running
in the background.
APNs maintains a certificate revocation list; if a provider's certificate is
on the revocation list, APNs can revoke provider trust (that is, APNs can
refuse the TLS initiation connection).