< Back to Package Overview
Third Party iOS Application Requirements
- Handling Incoming Telephony Push Notifications
- Handling Incoming Messaging Notifications
- Handling Push Notification Token Retrieval Delays
This section documents requirements that an Avaya Breeze® Client SDK based third party iOS application needs to follow in order to successfully implement the push notification handling. The section is organized into two main sections, describing how incoming telephony events and multimedia messaging events need to be handled by your iOS application. The sections assume that the Avaya Breeze® Client SDK is already initialized by your iOS application using the Avaya Breeze® Client SDK APIs.
1. Handling Incoming Telephony Push Notifications
The telephony push notification events are marked in such a way that they are delivered with highest priority by Apple as VoIP push notification events through iOS PushKit APIs. Your iOS application must register with the PushKit APIs in order to receive telephony push notification events.
When a telephony push notification event is received, assuming your application is not the active, iOS will either:
- resume your application, if your application was suspended while in the background, or
- start your application, if your application was terminated by iOS while in the background.
The following steps are implemented by your iOS application and Avaya Breeze® Client SDK in order to process the incoming telephony push notification event:
Avaya Aura® Web Gateway receives incoming call event from Avaya Aura® and sends a push notification message towards your APN Provider.
Your APN Provider sends the notification message to Apple's push notification network. Apple maintains a persistent connection to iOS client and routes the notification towards the iOS client.
iOS PushKit informs your iOS application about the incoming VoIP push notification message.
Your iOS application informs Avaya Breeze® Client SDK about the incoming call notification. Avaya Breeze® Client SDK decrypts the message based on the decryption key obtained from Avaya Aura® Web Gateway during push notification service activation (done as a result of user logging into Avaya Aura® with your iOS application). Avaya Breeze® Client SDK initializes its connection to Avaya Aura® and receives incoming call notification.
Avaya Breeze® Client SDK informs your iOS application about the incoming call. Your application can use CallKit to display the call to the end user. If the user answers the alerting call, your IOS client informs Avaya Breeze® about call being answered, and Avaya Breeze® Client SDK informs Avaya Aura® that the call is answered. The media path is established.
These interactions are shown in Figure 1.
![Incoming telephony event handling.]()
2. Handling Incoming Messaging Notifications
The messaging push notification events are delivered with normal priority by Apple push notification network and are delivered to iOS notification center.
Unlike the telephony notification events, you will need to implement an iOS notification service extension (NSE) to preprocess the incoming messaging notification before it is presented to the end user through iOS notification center.
This pre-processing step includes decryption of the incoming message before it is presented to the end user by iOS notification center. Unlike the telephony events, messaging events do not immediately activate your iOS application.
Your iOS application may remain suspended or terminated while the incoming message is presented to the end user through iOS notification center.
When the user decides to view the details of the incoming message or reply to the message your iOS application is woken up, and Avaya Breeze® Client SDK connects back to Avaya Aura® Presence Services.
The following steps need to be implemented by your iOS application in order to process the incoming messaging push notification event:
Avaya Aura® Presence Services receives a message for an iOS user, and sends a push notification message towards your APN Provider. The push notification message may include the message's text content and sender if this is allowed as per the configuration of Avaya Aura® Presence Services, as explained in the solution configuration section. All of this information is encrypted before it is sent by Avaya Aura® Presence Services towards your APN Provider.
Your APN Provider sends the notification message to Apple's push notification network.
-
Apple push notification network maintains a persistent connection to iOS client and routes the notification towards the iOS client.
- The message is delivered to the iOS notification center.
The iOS notification center delivers the notification message to your application's notification service extension.
The notification encryption key needs to be shared between your iOS application and its notification service extension. The notification service extension decrypts the message and calls back the iOS notification center.
The iOS notification center displays the message to the user.
User clicks on "View" to view the message in your iOS application.
The iOS brings your application to foreground. The application may need to be started if it were previously killed by iOS while in the background. The message id URL that the user wanted to view is passed by your application into Avaya Breeze® Client SDK.
Avaya Breeze® Client SDK connects to Avaya Aura® Presence Services server and requests display of the message that was received in the push notification message.
These interactions are shown in Figure 2.
![Incoming messaging event handling.]()
3. Handling Push Notification Token Retrieval Delays
The push notification related token retrieval from Apple is asynchronous and may be slow. It is recommended that your iOS application implement the following behavior in order to compensate for this issue:
- The very first time your iOS application is started:
- The application should start token retrieval from Apple while simultaneously starting Avaya Breeze® Client SDK by calling CSUser.start() without passing in any push notification token in.
- When either the messaging or the VoIP push notification token is received, the application should call CSUser.stop(), create a new CSUser object with the token passed in, and call CSUser.start() on the newly created CSUser object. It is recommended, though not required, that the application not tie the retrieval of the messaging and the VoIP tokens together, to avoid additional complexity. In this case, the application will likely go through the cycle of calling CSUser.stop() on the existing object, creating a new CSUser object, and calling CSUser.start() twice.
- The messaging and VoIP push notification tokens should be stored persistently.
- When the application is re-started, the Client SDK may be started (i.e., call to CSUser.start()) with a potentially stale token
- If the messaging and VoIP tokens are not stale, then no further action needs to be taken by the application.
- If a new token is received from Apple, the application should call CSUser.stop(), create a new CSUser object with the new token, and call CSUser.start() on the newly created CSUser object.
- During the period where push notifications are not available, the application should provide a message such as "Push service not available", informing the user of the push notification service.
