|
| 1 | +--- |
| 2 | +title: Enable push notifications in your chat app |
| 3 | +titleSuffix: An Azure Communication Services tutorial |
| 4 | +description: Learn how to enable push notification in IOS App by using Azure Communication Chat SDK |
| 5 | +author: angellan |
| 6 | +services: azure-communication-services |
| 7 | + |
| 8 | +ms.author: angellan |
| 9 | +ms.date: 08/09/2022 |
| 10 | +ms.topic: tutorial |
| 11 | +ms.service: azure-communication-services |
| 12 | +--- |
| 13 | + |
| 14 | +# Enable Push Notifications in your chat app |
| 15 | + |
| 16 | +>[!IMPORTANT] |
| 17 | +>This Push Notification feature is currently in public preview. Preview APIs and SDKs are provided without a service-level agreement, and aren't recommended for production workloads. Certain features might not be supported or might have constrained capabilities. |
| 18 | +
|
| 19 | +This tutorial will guide you to enable Push Notification in your IOS App by using Azure Communication Chat SDK. |
| 20 | +Push notifications alert clients of incoming messages in a chat thread in situations where the mobile app isn't running in the foreground. Azure Communication Services supports two versions of push notifications. |
| 21 | + |
| 22 | +- `Basic Version` : The user will be able to see a badge number of 1 on the app’s icon, receive a notification sound and see a pop-up alert banner. |
| 23 | +- `Advanced Version`: Except for the features supported in basic version, the Contoso will be able to customize the title & message preview section in alert banner. |
| 24 | + |
| 25 | + <img src="./media/add-chat-push-notification/basic-version.png" width="340" height="270" alt="Screenshot of basic version of push notification."> |
| 26 | + |
| 27 | + [Basic Version] |
| 28 | + |
| 29 | + <img src="./media/add-chat-push-notification/advanced-version.png" width="340" height="270" alt="Screenshot of advanced version of push notification."> |
| 30 | + |
| 31 | + [Advanced Version] |
| 32 | + |
| 33 | + |
| 34 | +## Download code |
| 35 | + |
| 36 | +Access the sample code for this tutorial on [GitHub](https://github.com/Azure-Samples/communication-services-ios-quickstarts/tree/main/add-chat-push-notifications). |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +1. Finish all the prerequisite steps in [Chat Quickstart](https://docs.microsoft.com/azure/communication-services/quickstarts/chat/get-started?pivots=programming-language-swift) |
| 41 | + |
| 42 | +2. ANH Setup |
| 43 | +Create an Azure Notification Hub within the same subscription as your Communication Services resource and link the Notification Hub to your Communication Services resource. See [Notification Hub provisioning](../concepts/notifications.md#notification-hub-provisioning). |
| 44 | + |
| 45 | +3. APNS Cert Configuration |
| 46 | +Here we recommend creating a .p12 APNS cert and set it in Notification Hub. |
| 47 | + |
| 48 | + `If you are not a Microsoft internal client`, please follow step 1 to step 9. |
| 49 | + `If you are a Microsoft internal client`, please submit a ticket [here](https://aka.ms/mapsupport) and provide the bundle ID of your app to get a .p12 cert. Once you get a valid certificate issued, please execute the step 9. |
| 50 | + |
| 51 | +* Step 1: Log in to the Apple Developer Portal. Navigate to `Certificates, IDs & Profiles > Identifiers > App IDs` and click the App ID associated with your app. |
| 52 | + |
| 53 | + <img src="./media/add-chat-push-notification/cert-1.png" width="700" height="230" alt="Screenshot of APNS Cert Configuration step 1."> |
| 54 | + |
| 55 | +* Step 2: On the screen for your App ID, check `Capabilities > Push Notifications`. Click Save and respond “Confirm” to the Modify App Capabilities dialog box that appears. |
| 56 | + |
| 57 | + <img src="./media/add-chat-push-notification/cert-2.png" width="700" height="350" alt="Screenshot of APNS Cert Configuration step 2-1."> |
| 58 | + |
| 59 | + <img src="./media/add-chat-push-notification/cert-3.png" width="700" height="210" alt="Screenshot of APNS Cert Configuration step 2-2."> |
| 60 | + |
| 61 | +* Step 3: In the same page, click `Capabilities > Push Notifications > Configure`. Click one of the following buttons: |
| 62 | + * Development SSL Certificate > Create Certificate (for testing push notifications while developing an iOS app) |
| 63 | + * Production SSL Certificate > Create Certificate (for sending push notifications in production) |
| 64 | + |
| 65 | + <img src="./media/add-chat-push-notification/cert-4.png" width="700" height="320" alt="Screenshot of APNS Cert Configuration step 3."> |
| 66 | + |
| 67 | +* Step 4: Then you're navigated to the below page. Here, you'll upload a Certificate Signing Request (CSR). Follow the next step to create a CSR. |
| 68 | + |
| 69 | + <img src="./media/add-chat-push-notification/cert-5.png" width="700" height="400" alt="Screenshot of APNS Cert Configuration step 4."> |
| 70 | + |
| 71 | +* Step 5: In a new browser tab, follow this [help page](https://help.apple.com/developer-account/#/devbfa00fef7) to create a CSR and save the file as “App name.cer”. |
| 72 | + |
| 73 | + <img src="./media/add-chat-push-notification/cert-6.png" width="700" height="360" alt="Screenshot of APNS Cert Configuration step 5 - 1."> |
| 74 | + <img src="./media/add-chat-push-notification/cert-7.png" width="700" height="500" alt="Screenshot of APNS Cert Configuration step 5 - 2."> |
| 75 | + |
| 76 | +* Step 6: Drag the .cer file to “Choose File” area. Then hit “continue” on the right top corner. |
| 77 | + |
| 78 | + <img src="./media/add-chat-push-notification/cert-8.png" width="880" height="400" alt="Screenshot of APNS Cert Configuration step 6."> |
| 79 | + |
| 80 | +* Step 7: Click “Download” and save the file to local disk. |
| 81 | + |
| 82 | + <img src="./media/add-chat-push-notification/cert-9.png" width="700" height="220" alt="Screenshot of APNS Cert Configuration step 7."> |
| 83 | + |
| 84 | +* Step 8: Open the .cer file you downloaded; it will open Keychain Access. Select your certificate, right-click, and export your certificate in .p12 format. |
| 85 | + |
| 86 | + <img src="./media/add-chat-push-notification/cert-11.png" width="700" height="400" alt="Screenshot of APNS Cert Configuration step 8."> |
| 87 | + |
| 88 | +* Step 9: Go to your notification hub, click “Apple (APNS)” under Settings and select “Certificate” under Authentication Mode. Also select the Application Mode based on your need. Then upload the .p12 file you just created. |
| 89 | + |
| 90 | + <img src="./media/add-chat-push-notification/cert-12.png" width="700" height="360" alt="Screenshot of APNS Cert Configuration step 9."> |
| 91 | + |
| 92 | +4. XCode Configuration |
| 93 | +* In XCode, go to `Signing & Capabilities`. Add a capability by selecting "+ Capability", and then select “Push Notifications”. |
| 94 | + |
| 95 | +* Add another capability by selecting “+ Capability”, and then select “Background Modes”. Also select “Remote Notifications” under Background Modes. |
| 96 | + |
| 97 | +<img src="./media/add-chat-push-notification/xcode-config.png" width="730" height="500" alt="Screenshot of Enable Push Notifications and Background modes in Xcode."> |
| 98 | + |
| 99 | +## Implementation |
| 100 | + |
| 101 | + |
| 102 | +### 1 - Basic Version |
| 103 | +If you want to implement a basic version of Push Notification, you need to register for remote notifications with APNS (Apple Push Notification Service). Refer to [sample code](https://github.com/Azure-Samples/communication-services-ios-quickstarts/blob/main/add-chat-push-notifications/SwiftPushTest/AppDelegate.swift) to see the related implementation in `AppDelegate.swift`. |
| 104 | + |
| 105 | +### 2 - Advanced Version |
| 106 | +If you want to implement an advanced version of Push Notification, you need to include the following items in your app. The reason is that we encrypt customer content (e.g. chat message content, sender display name, etc.) in push notification payload and it requires some workaround on your side. |
| 107 | + |
| 108 | +* Item 1: Data Storage for encryption keys |
| 109 | + |
| 110 | +First, you should create a persistent data storage in IOS device. This data storage should be able to share data between Main App and App Extensions (Refer to Item 2 for more information about App Extension – Notification Service Extension). |
| 111 | + |
| 112 | +In our sample code, we'll choose “App Group” as the data storage. Below are the suggested steps to create and use “App Group”: |
| 113 | + |
| 114 | +Follow the steps in [Add a capability](https://developer.apple.com/documentation/xcode/adding-capabilities-to-your-app?changes=latest_minor#Add-a-capability) to add the Apps Groups capability to your app’s targets – both Main App and Notification Service Extension (Refer to Item 2 on how to create a Notification Service Extension). |
| 115 | + |
| 116 | +Also follow the steps in this [Apple official doc](https://developer.apple.com/documentation/xcode/configuring-app-groups?changes=latest_minor) to configure App Group. Make sure your Main App and App Extension have the same container name. |
| 117 | + |
| 118 | +* Item 2: Notification Service Extension |
| 119 | + |
| 120 | +Second, you should implement a “Notification Service Extension” bundled with main app. This is used for decrypting the push notification payload when receiving it. |
| 121 | + |
| 122 | +Go to this [Apple official doc](https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications). Follow the step “Add a Service App Extension to your project” and “Implement Your Extension’s Handler Methods”. |
| 123 | + |
| 124 | +Notice that in the step “Implement Your Extension’s Handler Methods,” Apple provides the sample code to decrypt data and we'll follow the overall structure. However, since we use chat SDK for decryption, we need to replace the part starting from `“// Try to decode the encrypted message data.”` with our customized logic. Refer to the [sample code](https://github.com/Azure-Samples/communication-services-ios-quickstarts/blob/main/add-chat-push-notifications/SwiftPushTestNotificationExtension/NotificationService.swift) to see the related implementation in `NotificationService.swift`. |
| 125 | + |
| 126 | +* Item 3: Implementation of PushNotificationKeyHandler Protocol |
| 127 | + |
| 128 | +Third, `PushNotificationKeyHandler` is required for advanced version. As the SDK user, you could use the default `AppGroupPushNotificationKeyHandler` class provided by chat SDK to generate a key handler. If you don’t use `App Group` as the key storage or would like to customize key handling methods, create your own class which conforms to PushNotificationKeyHandler protocol. |
| 129 | + |
| 130 | +For PushNotificationKeyHandler, it defines two methods: `onPersistKey(encryptionKey:expiryTime)` and `onRetrieveKeys() -> [String]`. |
| 131 | + |
| 132 | +The first method is used to persist the encryption key in the storage of user’s IOS device. Chat SDK will set 45 minutes as the expiry time of the encryption key. If you want Push Notification to be effect for more than 45 minutes, you need to schedule to call `chatClient.startPushNotifications(deviceToken:)` on a comparatively frequent basis (eg. every 15 minutes) so a new encryption key could be registered before the old key expires. |
| 133 | + |
| 134 | +The second method is used to retrieve the valid keys previously stored. You have the flexibility to provide the customization based on the data storage (item 1) you choose. |
| 135 | + |
| 136 | +In protocol extension, chat SDK provides the implementation of `decryptPayload(notification:) -> PushNotificationEvent` method which you can take advantage of. Refer to the [sample code](https://github.com/Azure-Samples/communication-services-ios-quickstarts/blob/main/add-chat-push-notifications/SwiftPushTestNotificationExtension/NotificationService.swift) to see the related implementation in `NotificationService.swift`. |
| 137 | + |
| 138 | +## Testing |
| 139 | +1. Create a Chat Thread with User A and User B. |
| 140 | + |
| 141 | +2. Download the Sample App Repo and follow the above steps in the prerequisites and implementation section. |
| 142 | + |
| 143 | +3. Put User A’s <ACESS_TOEKN> and <ACS_RESOURCE_ENDPOINT> into `AppSettings.plist`. |
| 144 | + |
| 145 | +4. Set “Enable Bitcode” to “No” for two Pods targets – AzureCommunicationChat and Trouter. |
| 146 | + |
| 147 | +5. Plug the IOS device into your mac, run the program and click “allow” when asked to authorize push notification on device. |
| 148 | + |
| 149 | +6. As User B, send a chat message. You (User A) should be able to receive a push notification in your IOS device. |
| 150 | + |
| 151 | + |
0 commit comments