Push Notifications and the Mobile SDKs

​

Use Cases

In ASAPP Chat, users can receive Push Notifications (a.k.a. ASAPP background messages) for the following reasons:

• New live messages: if a customer is talking to a live agent and leaves the chat interface, new messages can be delivered via Push Notifications.
• Proactive messages: used to notify customers about promotions, reminders, or other relevant information, depending on the requirements of the implementation.

If you are looking for a way to get the most recent Conversation Status, please see the Android or iOS documentation.

​

Overall Architecture

​

Overview 1 - Device Token Registration

Figure 1: Push Notification Overview 1 - Device Token Registration.

​

Overview 2 - Sending Push Notifications

Figure 2: Push Notification Overview 2 - Sending Push Notifications

​

Device Token

After the Customer App (Figure 1) acquires the Device Token, it is then responsible to register it to the ASAPP SDK. ASAPP’s servers use this token to send push notification requests to a Customer-provided API endpoint (Customer Backend), which in turn sends requests to Firebase and/or APNs.

The ASAPP SDK and servers act as the middle-man with regards to the Device Token. In general, the Device Token must be a string that uniquely identifies the device that is defined and generated by the customer.

The Device Token format and content can be customized to include the necessary information for the Customer’s Backend service to send the push notifications. As an example, the Device Token can be a base64-encoded JSON Web Token (JWT) that contains the end user information required by the Customer’s Backend service.

ASAPP does not need to understand the content of the Device Token; however, the Device Token is persisted within the ASAPP Push Notification system.

​

Customer Implementation

This section details the customer work necessary to integrate Push Notifications in two parts: the App and the Backend.

​

Customer App

The Customer App manages the Device Token. In order for ASAPP’s servers to route notifications properly, the Customer App must register and deregister the token with the ASAPP SDK.

The Customer App also detects when push notifications are received and handles them accordingly.

​

Register for Push Notifications

Please refer to Figure 1 for a high level overview. There are usually two situations where the Customer App will need to register the Device Token:

• App start After you initialize the ASAPP SDK and set up the ASAPP User properly, register the Device Token.
• Token update In case the Device Token changes, register the token again. Please refer to the specific Android and iOS docs for more detailed information.

​

Deregister for Disable Push Notifications

If the user signs out of the Customer App, it is important to call the SDK API to de-register for push notifications.

Please refer to the specific Android and iOS docs for more detailed information.

​

Receive Messages in the Foreground

See Scenario 2 in Figure 2.

On Android: you usually receive foreground Push Notifications via a Firebase callback. To check if this is an ASAPP-generated Push Notification, call ASAPP.instance.getConversationStatusFromNotification, which will return a non-null status object. The Customer App can now display user feedback as desired using the status object.

On iOS, if you have set a UNUserNotificationCenterDelegate, it calls userNotificationCenter(_:willPresent:withCompletionHandler:) when a push notification is received while the app is in the foreground. In your implementation of that delegate method, call ASAPP.canHandleNotification(with: notification.request.userInfo) to determine if ASAPP generated the notification. An alternative method is to implement application(_:didReceiveRemoteNotification:fetchCompletionHandler:), which is called when a push notification is received regardless of whether the app is in the foreground or the background. In both cases, you can access userInfo["UnreadMessages"] to determine the number of unread messages.

​

Receive Push Notifications in the Background

See Scenario 1 in Figure 2.

When the App is in the background (or the device is locked), a system push notification displays as usual.

When the user opens the push notification:

• On Android: the App opens with an Android Intent. The Customer App can verify if the Intent is from an ASAPP generated Push Notification by calling the utility method ASAPP.instance.shouldOpenChat . This should open chat. See more details and code examples in the Android SDK Handle Push Notifications section.
• On iOS: if the app is running in the background, it calls application(_:didReceiveRemoteNotification:fetchCompletionHandler:) as above. If the app is not running, the app will start and call application(_:didFinishLaunchingWithOptions:), with the notification’s payload accessible at launchOptions[.remoteNotification]. Once again, call ASAPP.canHandleNotification(with:) to determine if ASAPP generated the notification.

​

Customer Backend

It is common that the Customer solution already includes middleware that handles Push Notifications. This middleware usually provides the Customer App with the Device Tokens and sends Push Notification requests to Firebase and/or APNs. If the middleware provides an endpoint that can be called to trigger push notifications, ASAPP can integrate with it (given that the authentication strategy is in place). Otherwise, ASAPP requires that the Customer provides or implements an endpoint for this to take place.

ASAPP’s Push Notification adapters call the provided endpoint with a previously agreed-upon payload format. The following is a payload example:

{
  authToken: "auth-token",
  deviceToken: "the-device-token",
  payload: {
    aps: {
      alert: {
        title: "New Message",
        body: "Hello, how can we help?"
      }
    },
    ...  
  },
  ...
}

​

ASAPP Implementation

​

ASAPP Backend

For any new Push Notification Integration, ASAPP creates an “adapter” for ASAPP’s Notification Hub service. This adapter translates messages sent by Agents to a request that is compatible with the Customer Backend. This usually means that the Notification Hub adapter makes HTTP calls to the Customer’s specified endpoint, with a previously agreed-upon payload format.

​

ASAPP SDK

The ASAPP Android and iOS SDKs as well as the ASAPP Xamarin SDK already supply the interfaces and utilities needed for Customer Apps to register and de-register for Push Notifications.

​

Testing Environments and QA

From a Quality Assurance standpoint, ASAPP requires access to lower-level environments with credentials so that we can properly develop and test new adapters.