Merge pull request #287869 from ShawnJackson/two-communication-services-articles

[AQ] edit pass: Two Communication Services articles

Author: ktoliver

articles/communication-services/how-tos/calling-sdk/includes/install-sdk/install-sdk-android.md

@@ -8,7 +8,7 @@ ms.author: rifox
 
 ## Install the SDK
 
-Locate your project-level *build.gradle* file and add `mavenCentral()` to the list of repositories under `buildscript` and `allprojects`:
+Locate your project-level `build.gradle` file and add `mavenCentral()` to the list of repositories under `buildscript` and `allprojects`:
 
 ```groovy
 buildscript {
@@ -30,7 +30,7 @@ allprojects {
 }
 ```
 
-Then, in your module-level *build.gradle* file, add the following lines to the `dependencies` section:
+Then, in your module-level `build.gradle` file, add the following lines to the `dependencies` section:
 
 ```groovy
 dependencies {
@@ -40,7 +40,7 @@ dependencies {
 }
 ```
 
-### Initialize the required objects
+## Initialize the required objects
 
 To create a `CallAgent` instance, you have to call the `createCallAgent` method on a `CallClient` instance. This call asynchronously returns a `CallAgent` instance object.
 

articles/communication-services/how-tos/calling-sdk/includes/install-sdk/install-sdk-ios.md

@@ -10,9 +10,9 @@ ms.author: rifox
 
 ### Create the Xcode project
 
-In Xcode, create a new iOS project and select the **Single View App** template. This quickstart uses the [SwiftUI framework](https://developer.apple.com/xcode/swiftui/), so you should set **Language** to **Swift** and set **Interface** to **SwiftUI**.
+In Xcode, create a new iOS project and select the **Single View App** template. This article uses the [SwiftUI framework](https://developer.apple.com/xcode/swiftui/), so you should set **Language** to **Swift** and set **Interface** to **SwiftUI**.
 
-You're not going to create tests during this quickstart. Feel free to clear the **Include Tests** checkbox.
+You're not going to create tests in this article. Feel free to clear the **Include Tests** checkbox.
 
 :::image type="content" source="../../../../quickstarts/voice-video-calling/media/ios/xcode-new-ios-project.png" alt-text="Screenshot that shows the window for creating a project within Xcode.":::
 
@@ -27,14 +27,16 @@ You're not going to create tests during this quickstart. Feel free to clear the
         pod 'AzureCommunicationCalling', '~> 1.0.0'
     end
     ```
+
 2. Run `pod install`.
+
 3. Open `.xcworkspace` by using Xcode.
 
 ### Request access to the microphone
 
 To access the device's microphone, you need to update your app's information property list by using `NSMicrophoneUsageDescription`. You set the associated value to a string that will be included in the dialog that the system uses to request access from the user.
 
-Right-click the *Info.plist* entry of the project tree, and then select **Open As** > **Source Code**. Add the following lines in the top-level `<dict>` section, and then save the file.
+Right-click the **Info.plist** entry of the project tree, and then select **Open As** > **Source Code**. Add the following lines in the top-level `<dict>` section, and then save the file.
 
 ```xml
 <key>NSMicrophoneUsageDescription</key>
@@ -43,14 +45,14 @@ Right-click the *Info.plist* entry of the project tree, and then select **Open A
 
 ### Set up the app framework
 
-Open your project's *ContentView.swift* file. Add an `import` declaration to the top of the file to import the `AzureCommunicationCalling` library. In addition, import `AVFoundation`. You'll need it for audio permission requests in the code.
+Open your project's `ContentView.swift` file. Add an `import` declaration to the top of the file to import the `AzureCommunicationCalling` library. In addition, import `AVFoundation`. You'll need it for audio permission requests in the code.
 
 ```swift
 import AzureCommunicationCalling
 import AVFoundation
 ```
 
-## Initialize CallAgent
+### Initialize CallAgent
 
 To create a `CallAgent` instance from `CallClient`, you have to use a `callClient.createCallAgent` method that asynchronously returns a `CallAgent` object after it's initialized.
 

articles/communication-services/how-tos/calling-sdk/includes/install-sdk/install-sdk-windows.md

@@ -9,7 +9,7 @@ ms.author: jowang
 
 ### Create the Visual Studio project
 
-For a UWP app, in Visual Studio 2022, create a new **Blank App (Universal Windows)** project. After you enter the project name, feel free to choose any Windows SDK later than 10.0.17763.0.
+For a Universal Windows Platform (UWP) app, in Visual Studio 2022, create a new **Blank App (Universal Windows)** project. After you enter the project name, feel free to choose any Windows SDK later than 10.0.17763.0.
 
 For a WinUI 3 app, create a new project with the **Blank App, Packaged (WinUI 3 in Desktop)** template to set up a single-page WinUI 3 app. [Windows App SDK version 1.3](/windows/apps/windows-app-sdk/stable-channel#version-13) or later is required.
 

articles/communication-services/how-tos/calling-sdk/includes/push-notifications/push-notifications-android.md

@@ -5,56 +5,56 @@ ms.topic: include
 ms.date: 08/06/2024
 ms.author: sanathr
 ---
-> [!IMPORTANT]
-> On June 20, 2023, Google announced that it [deprecated sending messages using the FCM legacy APIs](https://firebase.google.com/docs/cloud-messaging). Google is removing the legacy FCM from service in June 2024. Google recommends [migrating from legacy FCM APIs to FCM HTTP v1](https://firebase.google.com/docs/cloud-messaging/migrate-v1).
-> Please follow this [migration guide](/azure/communication-services/tutorials/call-chat-migrate-android-push-fcm-v1) if your Communication reosurce is still using the old FCM legacy APIs.
-
-[!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)]
 
-### Additional Prerequisites for Push Notifications
+- A Firebase account with Firebase Cloud Messaging (FCM) enabled and with your FCM service connected to an Azure Notification Hubs instance. For more information, see [Communication Services notifications](../../../../concepts/notifications.md).
+- Android Studio version 3.6 or later to build your application.
+- A set of permissions to enable the Android application to receive notification messages from FCM. In your `AndroidManifest.xml` file, add the following permissions right after `<manifest ...>` or below the `</application>` tag:
 
-A Firebase account set up with Cloud Messaging (FCM) enabled and with your Firebase Cloud Messaging service connected to an Azure Notification Hub instance. See [Communication Services notifications](../../../../concepts/notifications.md) for more information.
-Additionally, the tutorial assumes you're using Android Studio version 3.6 or higher to build your application.
+  ```xml
+  <uses-permission android:name="android.permission.INTERNET"/>
+  <uses-permission android:name="android.permission.GET_ACCOUNTS"/>
+  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
+  ```
 
-A set of permissions is required for the Android application in order to be able to receive notifications messages from Firebase Cloud Messaging. In your `AndroidManifest.xml` file, add the following set of permissions right after the `<manifest ...>` or below the `</application>` tag.
+> [!IMPORTANT]
+> On June 20, 2023, Google announced that it [deprecated sending messages by using the FCM legacy APIs](https://firebase.google.com/docs/cloud-messaging) and would start removing the legacy FCM from service in June 2024. Google recommends [migrating from legacy FCM APIs to FCM HTTP v1](https://firebase.google.com/docs/cloud-messaging/migrate-v1).
+>
+> If your Communication Services resource is still using the FCM legacy APIs, follow [this migration guide](/azure/communication-services/tutorials/call-chat-migrate-android-push-fcm-v1).
 
-```xml
-<uses-permission android:name="android.permission.INTERNET"/>
-<uses-permission android:name="android.permission.GET_ACCOUNTS"/>
-<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
-```
+## Considerations for mobile push notifications
 
-## Overview
-Mobile push notifications are the pop-up notifications you see on mobile devices. For calling, we'll be focusing on VoIP (Voice over Internet Protocol) push notifications. We register for push notifications, handle push notifications, and then unregister push notifications.
+Mobile push notifications are the pop-up notifications that appear on mobile devices. For calling, this article focuses on voice over Internet Protocol (VoIP) push notifications.
 
 > [!NOTE]
-> Registering for Push Notifications and handling of the incoming Push Notifications for a Teams user, the APIs are the same. The APIs described here can also be invoked on the `CommonCallAgent` or `TeamsCallAgent` classes.
+> When the application registers for push notifications and handles the incoming push notifications for a Teams user, the APIs are the same. The APIs that this article describes can also be invoked on the `CommonCallAgent` or `TeamsCallAgent` class.
+
+[!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)]
 
 ## Register for push notifications
 
-To register for push notifications, the application needs to call `registerPushNotification()` on a `CallAgent` instance with a device registration token.
+To register for push notifications, the application needs to call `registerPushNotification()` on a `CallAgent` instance by using a device registration token.
 
-To obtain the device registration token, add the Firebase SDK to your application module's `build.gradle` file by adding the following lines in the `dependencies` section if it's not already there:
+To obtain the device registration token, add the Firebase SDK to your application module's `build.gradle` file by adding the following lines in the `dependencies` section (if the lines aren't already there):
 
 ```groovy
 // Add the SDK for Firebase Cloud Messaging
 implementation 'com.google.firebase:firebase-core:16.0.8'
 implementation 'com.google.firebase:firebase-messaging:20.2.4'
 ```
 
-In your project level's *build.gradle* file, add the following line in the `dependencies` section if it's not already there:
+In your project level's `build.gradle` file, add the following line in the `dependencies` section if it's not already there:
 
 ```groovy
 classpath 'com.google.gms:google-services:4.3.3'
 ```
 
-Add the following plugin to the beginning of the file if it's not already there:
+Add the following plug-in to the beginning of the file if it's not already there:
 
 ```groovy
 apply plugin: 'com.google.gms.google-services'
 ```
 
-Select *Sync Now* in the toolbar. Add the following code snippet to get the device registration token generated by the Firebase Cloud Messaging SDK for the client application instance. Be sure to add the below imports to the header of the main Activity for the instance to retrieve the token.
+On the toolbar, select **Sync Now**. Add the following code snippet to get the device registration token that the Firebase Cloud Messaging SDK generated for the client application instance. Be sure to add the following imports to the header of the main activity for the instance to retrieve the token.
 
 ```java
 import com.google.android.gms.tasks.OnCompleteListener;
@@ -75,13 +75,14 @@ FirebaseInstanceId.getInstance().getInstanceId()
                 return;
             }
 
-            // Get new Instance ID token
+            // Get the new instance ID token
             String deviceToken = task.getResult().getToken();
             // Log
             Log.d("PushNotification", "Device Registration token retrieved successfully");
         }
     });
 ```
+
 Register the device registration token with the Calling Services SDK for incoming call push notifications:
 
 ```java
@@ -94,19 +95,19 @@ catch(Exception e) {
 }
 ```
 
-## Push notification handling
+## Handle push notifications
 
-To receive incoming call push notifications, call *handlePushNotification()* on a *CallAgent* instance with a payload.
+To receive incoming call push notifications, call `handlePushNotification()` on a `CallAgent` instance with a payload.
 
-To obtain the payload from Firebase Cloud Messaging, begin by creating a new Service (File > New > Service > Service) that extends the *FirebaseMessagingService* Firebase SDK class and override the `onMessageReceived` method. This method is the event handler called when Firebase Cloud Messaging delivers the push notification to the application.
+To obtain the payload from Firebase Cloud Messaging, begin by creating a new service (select **File** > **New** > **Service** > **Service**) that extends the `FirebaseMessagingService` Firebase SDK class and overrides the `onMessageReceived` method. This method is the event handler that's called when Firebase Cloud Messaging delivers the push notification to the application.
 
 ```java
 public class MyFirebaseMessagingService extends FirebaseMessagingService {
     private java.util.Map<String, String> pushNotificationMessageDataFromFCM;
 
     @Override
     public void onMessageReceived(RemoteMessage remoteMessage) {
-        // Check if message contains a notification payload.
+        // Check if the message contains a notification payload.
         if (remoteMessage.getNotification() != null) {
             Log.d("PushNotification", "Message Notification Body: " + remoteMessage.getNotification().getBody());
         }
@@ -116,6 +117,7 @@ public class MyFirebaseMessagingService extends FirebaseMessagingService {
     }
 }
 ```
+
 Add the following service definition to the `AndroidManifest.xml` file, inside the `<application>` tag:
 
 ```xml
@@ -128,7 +130,7 @@ Add the following service definition to the `AndroidManifest.xml` file, inside t
 </service>
 ```
 
-Once the payload is retrieved, it can be passed to the *Communication Services* SDK to be parsed out into an internal *IncomingCallInformation* object that will handle calling the *handlePushNotification* method on a *CallAgent* instance. A `CallAgent` instance is created by calling the `createCallAgent(...)` method on the `CallClient` class.
+After you retrieve the payload, you can pass it to the Communication Services SDK to be parsed into an internal `IncomingCallInformation` object. This object handles calling the `handlePushNotification` method on a `CallAgent` instance. You create a `CallAgent` instance by calling the `createCallAgent(...)` method on the `CallClient` class.
 
 ```java
 try {
@@ -140,11 +142,11 @@ catch(Exception e) {
 }
 ```
 
-When the handling of the Push notification message is successful, and the all events handlers are registered properly, the application rings.
+When the handling of the push notification message is successful, and the all event handlers are registered properly, the application rings.
 
 ## Unregister push notifications
 
-Applications can unregister push notification at any time. Call the `unregisterPushNotification()` method on callAgent to unregister.
+Applications can unregister push notification at any time. To unregister, call the `unregisterPushNotification()` method on `callAgent`:
 
 ```java
 try {
@@ -155,13 +157,14 @@ catch(Exception e) {
 }
 ```
 
-## Disable internal push for incoming call
+## Disable internal push notifications for an incoming call
+
+The push payload of an incoming call can be delivered to the callee in two ways:
 
-There are two ways that a push payload of an incoming call can be delivered to the callee.
-   - Using FCM and registering the device token with the API mentioned above, `registerPushNotification` on `CallAgent` or `TeamsCallAgent`.
-   - When a `CallAgent` or `TeamsCallAgent` is created, SDK also registers with an internal service to get the push payload delivered.
+- Using FCM and registering the device token with the API mentioned earlier, `registerPushNotification` on `CallAgent` or `TeamsCallAgent`
+- Registering the SDK with an internal service upon creation of `CallAgent` or `TeamsCallAgent` to get the push payload delivered
 
-Using the property `setDisableInternalPushForIncomingCall` in `CallAgentOptions` or `TeamsCallAgentOptions` it's possible to instruct the SDK to disable the delivery of the push payload using the internal push service.
+By using the property `setDisableInternalPushForIncomingCall` in `CallAgentOptions` or `TeamsCallAgentOptions`, it's possible to instruct the SDK to disable the delivery of the push payload via the internal push service:
 
 ```java
 CallAgentOptions callAgentOptions = new CallAgentOptions();