Push notification delivery

At various points in an Atomic Card's lifecycle the Atomic platform may attempt to deliver a push notification to an customer's device. There are multiple systems that work together when sending a notification. It is helpful to understand the responsibility of each of the systems.

Queuing, Processing and Analytics (Atomic Platform)

The Atomic Platform is responsible for queuing and processing incoming data events, some of which will require a notification to be sent. Atomic sends a notification request to the distributor (SNS), and creates analytic data reflecting the response to that request.

Security of certificates

The Atomic Platform uploads certificates to AWS SNS Applications, and does not store them its own database or file systems. There is no way to retrieve the certificate from the Atomic Platform once it is uploaded to an AWS SNS Application. The Atomic Platform grants access to the AWS SNS Application on a least-privilege basis within our private network.

Distribution (Amazon SNS)

Amazon SNS is responsible for distributing the notification payload to a platform notification service. In the case of Android devices, this is Google’s Firebase. In the case of iOS devices it is Apple’s APNS. The Amazon SNS service is a service used as an adjunct to the Atomic platform. SNS responds to requests for distribution from the Atomic platform, and indicates whether the notification request has been accepted by the platform notification service.

Platform Notification Services (APNS and Firebase)

APNS and Google Firebase are provided by Apple and Google respectively as the sole mechanisms for push notification delivery, and are responsible for delivery of notifications to devices. These services are “best effort” services that will attempt to deliver notifications, but do not guarantee delivery.

Deliverability

The following must be in place to enable a push notification to be successfully delivered.

Configuration

The Atomic Platform must be correctly configured with the correct App IDs and keys or certificates to operate with the platform notification services.

Android options

There are a number of special configurations available for Android notifications:

• Send data-only notifications: whether or not to populate the notification option as documented by Firebase - when disabled (default) the notification will be sent with the title and body as configured in the card notification settings and the optional Channel Id value as configured in the Android settings. In most cases this setting should be left disabled.
• Channel Id: maps to the android_channel_id option as documented by Firebase.
• Restricted package name: maps to the restricted_package_name option as documented by Firebase.

Key rotation

In the Firebase console, you can create new FCM server keys and revoke existing ones for Android. The keys are generated by Google and you cannot specify an expiry on them.

System availability

The Atomic platform, AWS SNS, Google Firebase and APNS are all designed for high-availability, and are integrated in a way that minimizes the risk of messages not being delivered. In the event that a platform notification service becomes temporarily unavailable Atomic will retry sending the notification, though the notification will not be considered as delivered for service level purposes during this time.

Customer context

Customer's may configure their devices in a way that prevents notifications from being delivered, or seen. Push notifications can also only be received where customer devices are operating and connected to the relevant platform notification service.

Delivery times

Typically, notifications are received by customers less than 5 seconds after an action card requiring a notification is ready for an customer to view. There are a number of factors influencing delivery time for any given notification. The diagram below illustrates the delivery interval and how it can be broken down.

The timeline starts with you sending an event to the Atomic API and ends with a device receiving a notification. This entire period is called the delivery interval. The delivery interval can be broken down into three smaller intervals:

1. Queue interval:
   When a request is made to the Atomic API, it may be queued for processing. When not under high load the request will pass through the queue nearly immediately. The throughput of the queue under high load is subject to the service tier that you have selected, and the load you are placing on Atomic at the time the request is made. The queue interval is defined as the time between the request and the dequeuing of the request for processing
   

2. Processing interval:
   When the Atomic platform processes an event and creates an action card ready for delivery, it also initiates a push notification if necessary. The processing interval is defined as the time between the start of processing and the creation of an analytics event recording the outcome of the distribution service (SNS) offloading the notification to a platform delivery service (APNS, FIrebase). This interval is typically less than a second.
   

3. Offload interval:
   This interval begins when the notification has left Atomic’s services and is being handled by the platform notification service. It will usually end within a few seconds, once the notification has been delivered to the device. However, as the platform notification services do not provide guaranteed delivery, it is possible that it will not end.

Analytics

Atomic provides analytics events for notifications. An analytic event is recorded when a notification has been sent to a platform notification service. This event records the processing interval.

It is also possible to configure your client applications to inform the Atomic SDKs that a notification has been received by the device. The SDK will then forward an analytic event to the Atomic platform for recording. The SDKs do not do this automatically, due to technical limitations within iOS, and Atomic’s principle of separating the concerns of the SDK from that of the host platform and host application.

Service Levels

The service levels Atomic provides for notification delivery timeframes is constrained to the processing interval described in this document.

Atomic will ensure the processing interval will be less than 2 seconds, in 99.9% of cases, for notifications that meet the criteria for deliverability.

The queue interval is an upstream concern and is not within the scope of notification delivery service levels. The queue interval is instead covered by subscription tier service levels.

Atomic cannot provide service levels for the offload interval, and does not guarantee the downstream platform delivery services will deliver the notification. This constraint is inherited from the platform delivery services.