Merge pull request #231934 from Mohtasim/how-to/bypass-setup-screen

Guide to use Skip Setup Screen feature for public preview 1.3.0 GA

Author: AnnaMHuff

articles/communication-services/concepts/ui-library/includes/mobile-ui-use-cases.md

@@ -77,6 +77,10 @@ Use the UI Library for mobile native platforms to give local and remote particip
 
 :::image type="content" source="../../media/mobile-ui/ios-composite.gif" alt-text="GIF animation that shows the pre-meeting experience and joining experience on iOS.":::
 
+### Skip Setup Screen
+
+UI Library provides the capability to join a call skipping the setup screen of the call join experience. By default, user goes through a setup screen to join a call. Here, user sets the call configuration such as camera turn on or off, microphone turn on or off and audio device selection before joining a call. This screen requires user interaction to join a call, which might be unnecessary for some users. So we provide the capability to join a call by skipping the setup screen and providing the call configuration APIs. For more information, see [How to use Skip Setup Screen Feature](../../../how-tos/ui-library-sdk/skip-setup-screen.md)
+
 ## Chat use cases
 
 [!INCLUDE [Public Preview Notice](../../../includes/public-preview-include.md)]

articles/communication-services/how-tos/ui-library-sdk/includes/data-model/android.md

@@ -10,15 +10,15 @@ ms.service: azure-communication-services
 
 Azure Communication UI [open source library](https://github.com/Azure/communication-ui-library-android) for Android and the sample application code can be found [here](https://github.com/Azure-Samples/communication-services-android-quickstarts/tree/main/ui-calling)
 
-### Participant View Customization
+### Local Participant View Customization
 
 The UI Library gives developers the ability to provide a more customized experience regarding Participant information. At launch, developers can optionally inject local participant data. This local data isn't shared with the server and can be used to customize the display name and avatar of the local user.
 
 #### Local Options
 
-`CallCompositeLocalOptions` is the data model that can have `CallCompositeParticipantViewData` and `CallCompositeSetupScreenViewData`. It will represent the local participant.  By default, for remote participants, the UI library will display the `displayName` injected in `RemoteOptions` that is sent to Azure Communication Service backend server. If `CallCompositeParticipantViewData` is injected, the participant `displayName` and `avatar` will be displayed in all avatar components locally and only in user's side. 
+`CallCompositeLocalOptions` is the data model that can have `CallCompositeParticipantViewData` and `CallCompositeSetupScreenViewData`. It represents the local participant.  By default, for remote participants, the UI library displays the `displayName` injected in `RemoteOptions` that is sent to Azure Communication Service backend server. If `CallCompositeParticipantViewData` is injected, the participant `displayName` and `avatar` are displayed in all avatar components locally. 
 
-Similarly, for `CallCompositeSetupScreenViewData`, the `title` and `subtitle` in `CallCompositeSetupScreenViewData` would overwrite the navigation bar's title and subtitle in pre-meeting screen respectively. By default, the UI library will display 'Setup' as the title and subtitle will be set to hidden.
+Similarly, for `CallCompositeSetupScreenViewData`, the `title` and `subtitle` in `CallCompositeSetupScreenViewData` overwrites the navigation bar's title and subtitle in premeeting screen respectively. By default, the UI library displays 'Setup' as the title and nothing as the subtitle.
 
 #### Local Participant View Data
 
@@ -30,7 +30,7 @@ This class is held in the `CallCompositeLocalOptions` object that represents opt
 
 #### Setup Screen View Data
 
-`CallCompositeSetupScreenViewData` is an object that sets the `title` and `subtitle` for the navigationBar on call setup screen. If `subtitle` is not defined, then subtitle would always be set to hidden. Here `title` is a required to set the `subtitle` but `subtitle` is optional when `title` is set. This class is locally stored and its information will not be sent up to the server.
+`CallCompositeSetupScreenViewData` is an object that sets the `title` and `subtitle` for the navigationBar on call setup screen. If `subtitle` isn't defined, then subtitle is hidden. Here `title` is a required to set the `subtitle` but `subtitle` is optional when `title` is set. This class is locally stored and its information aren't sent up to the server.
 
 #### Usage
 
@@ -39,20 +39,20 @@ To use the `CallCompositeLocalOptions`, pass the instance of `CallCompositeParti
 #### [Kotlin](#tab/kotlin)
 
 ```kotlin
-val CallCompositeParticipantViewData participantViewData = CallCompositeParticipantViewData()
+val participantViewData: CallCompositeParticipantViewData = CallCompositeParticipantViewData()
     .setAvatarBitmap((Bitmap) avatarBitmap)
     .setScaleType((ImageView.ScaleType) scaleType)
-    .setDisplayName((String) displayName);
+    .setDisplayName((String) displayName)
 
-val CallCompositeSetupScreenViewData setupScreenViewData = CallCompositeSetupScreenViewData()
+val setupScreenViewData: CallCompositeSetupScreenViewData = CallCompositeSetupScreenViewData()
     .setTitle((String) title)
-    .setSubtitle((String) subTitle);
+    .setSubtitle((String) subTitle)
 
-val CallCompositeLocalOptions localOptions = new CallCompositeLocalOptions()
+val localOptions: CallCompositeLocalOptions = CallCompositeLocalOptions()
     .setParticipantViewData(participantViewData)
-    .setNavigationBarViewData(navigationBarViewData);
+    .setSetupScreenViewData(setupScreenViewData)
 
-callComposite.launch(callLauncherActivity, remoteOptions, localOptions);
+callComposite.launch(callLauncherActivity, remoteOptions, localOptions)
 ```
 
 #### [Java](#tab/java)
@@ -69,7 +69,7 @@ final CallCompositeSetupScreenViewData setupScreenViewData = new CallCompositeSe
 
 final CallCompositeLocalOptions localOptions = new CallCompositeLocalOptions()
     .setParticipantViewData(participantViewData)
-    .setNavigationBarViewData(navigationBarViewData);
+    .setSetupScreenViewData(setupScreenViewData);
 
 callComposite.launch(callLauncherActivity, remoteOptions, localOptions);
 ```
@@ -121,4 +121,4 @@ callComposite.addOnRemoteParticipantJoinedEventHandler { remoteParticipantJoined
 
 |Participants list|
 | ---- |
-| :::image type="content" source="media/android-model-injection-remote.png" alt-text="Screenshot showing the Android data custom model remote injection."::: |
+| :::image type="content" source="media/android-model-injection-remote.png" alt-text="Screenshot of the Android remote participants view data injection."::: |

articles/communication-services/how-tos/ui-library-sdk/includes/data-model/ios.md

@@ -12,22 +12,22 @@ Azure Communication UI [open source library](https://github.com/Azure/communicat
 
 ### Local Participant View Data Injection
 
-The UI Library now gives developers the ability to provide a more customized experience. At launch, developers can now inject an optional Local Data Options. This object can contain a UIimage that represents the avatar to render, and a display name they can optionally display instead. None of this information will be sent to Azure Communication Services and will be only held locally in the UI library.
+The UI Library now gives developers the ability to provide a more customized experience. At launch, developers can now inject an optional Local Data Options. This object can contain a UIimage that represents the avatar to render, and a display name they can optionally display instead. None of this information is sent to Azure Communication Services and is held locally in the UI library.
 
 #### Local Options
 
-`LocalOptions` is data model that consists of `ParticipantViewData` and `SetupScreenViewData`.  By default for `ParticipantViewData`, the UI library displays the `displayName` injected in `RemoteOptions` that is sent to Azure Communication Service backend server. If `ParticipantViewData` is injected, the participant `displayName` and `avatar` will be displayed in all avatar components. 
+`LocalOptions` is data model that consists of `ParticipantViewData` and `SetupScreenViewData`.  By default for `ParticipantViewData`, the UI library displays the `displayName` injected in `RemoteOptions` that is sent to Azure Communication Service backend server. If `ParticipantViewData` is injected, the participant `displayName` and `avatar` are displayed in all avatar components. 
 
-Similarly, for 'SetupScreenViewData', by default the UI library displays 'Setup' as the title and subtitle is set to hidden. The `title` and `subtitle` in 'SetupScreenViewData' would overwrite the navigation bar's title and subtitle in pre-meeting screen respectively. 
+Similarly, for 'SetupScreenViewData', by default, the UI library displays 'Setup' as the title and nothing as subtitle. The `title` and `subtitle` in 'SetupScreenViewData' overwrites the navigation bar's title and subtitle in premeeting screen respectively. 
 
-#### Participant View Data
+#### Local Participant View Data
 
-`ParticipantViewData` is an object that sets the `displayName` and `avatar` UIImage for avatar components. This class is injected into the UI Library to set avatar information, and it will always be locally stored and never sent up to the server.
+`ParticipantViewData` is an object that sets the `displayName` and `avatar` UIImage for avatar components. This class is injected into the UI Library to set avatar information. It's stored locally and never sent up to the server.
 
 #### Setup Screen View Data
 
-`SetupScreenViewData` is an object that sets the `title` and `subtitle` for the navigationBar on pre-meeting screen (also known as Setup View). If `SetupScreenViewData` is defined, then 'title' must be provided as it's a required field. 'subtitle', however, isn't required. 
-If `subtitle` isn't defined, then the subtitle would always be set to hidden. This class is locally stored and its information won't be sent up to the server.
+`SetupScreenViewData` is an object that sets the `title` and `subtitle` for the navigationBar on premeeting screen (also known as Setup View). If `SetupScreenViewData` is defined, then 'title' must be provided as it's a required field. 'subtitle', however, isn't required. 
+If `subtitle` isn't defined, then it's hidden. This class is locally stored and its information isn't sent up to the server.
 
 #### Usage
 
@@ -53,7 +53,7 @@ callComposite.launch(remoteOptions: remoteOptions, localOptions: localOptions)
 
 ### Remote Participant View Data Injection
 
-On remote participant join, developers can inject the participant view data for remote participant. This participant view data can contain a UIImage that represents the avatar to render, and a display name they can optionally display instead. None of this information will be sent to Azure Communication Services and will be only held locally in the UI library.
+On remote participant join, developers can inject the participant view data for remote participant. This participant view data can contain a UIImage that represents the avatar to render, and a display name they can optionally display instead. None of this information is sent to Azure Communication Services and is held locally in the UI library.
 
 #### Usage
 

articles/communication-services/how-tos/ui-library-sdk/includes/skip-setup-screen/android.md

@@ -0,0 +1,119 @@
+---
+description: In this tutorial, you learn how to use the Calling composite on Android
+author: mbellah
+
+ms.author: mbellah
+ms.date: 03/21/2023
+ms.topic: include
+ms.service: azure-communication-services
+---
+
+Azure Communication UI [open source library](https://github.com/Azure/communication-ui-library-android) for Android and the sample application code can be found [here](https://github.com/Azure-Samples/communication-services-android-quickstarts/tree/main/ui-calling)
+
+
+### Skip setup screen option
+
+`CallCompositeLocalOptions` is an options wrapper that sets the capability of the UI Library to skip the setup screen using a boolean. By default, the skip setup screen capability is set to false. You have to set `skipSetupScreen` with true boolean value to get the skip setup screen experience.
+
+We recommend you to build your application such a way that when user tries to join a call, microphone permission has already been granted to get a smooth call join experience.
+
+:::image type="content" source="media/android-bypass-setup-screen.png" alt-text="Diagram of joining call skipping the setup screen for Android.":::
+
+
+To use the feature, pass the boolean value with `skipSetupScreen` to `CallCompositeLocalOptions` and inject it to `callComposite.launch`.
+
+### [Kotlin](#tab/kotlin)
+
+```kotlin
+import com.azure.android.communication.ui.calling.models.CallCompositeLocalOptions
+
+val localOptions: CallCompositeLocalOptions = CallCompositeLocalOptions()
+    .setSkipSetupScreen(true)
+
+callComposite.launch(callLauncherActivity, remoteOptions, localOptions)
+```
+
+### [Java](#tab/java)
+```java
+import com.azure.android.communication.ui.calling.models.CallCompositeLocalOptions;
+
+final CallCompositeLocalOptions localOptions = new CallCompositeLocalOptions()
+    .setSkipSetupScreen(true);
+
+callComposite.launch(callLauncherActivity, remoteOptions, localOptions);
+```
+-----
+
+### Default camera and microphone configuration options
+
+By default, setup screen gives the user an option to configure the camera and microphone settings before joining a call. When you try to skip the setup screen to join a call, user doesn't have that option unless they join the call already. We're providing more options to set default behavior of the camera and microphone so that developers get more control over default state of camera and microphone. You can pass a boolean value with `cameraOn` and `microphoneOn` to turn camera and microphone ON or OFF. These attributes empower developers to have control over camera and microphone controls prior to join a call. Default camera and microphone state control functionality isn't affected if user grants the permission for each of them respectively.
+
+By default, both `cameraOn` and `microphoneOn` are set to false. You can use this functionality even with UI Libraries default call join experience. In that case, setup screen camera and microphone are turned ON or OFF according to the configuration that you set.
+
+To use camera and microphone default state feature, pass the boolean value with
+`cameraOn` and `microphoneOn` to `CallCompositeLocalOptions` and inject it to `callComposite.launch`.
+
+### [Kotlin](#tab/kotlin)
+
+```kotlin
+import com.azure.android.communication.ui.calling.models.CallCompositeLocalOptions
+
+val localOptions: CallCompositeLocalOptions = CallCompositeLocalOptions()
+    .setMicrophoneOn(true)
+    .setCameraOn(true)
+
+callComposite.launch(callLauncherActivity, remoteOptions, localOptions)
+```
+
+### [Java](#tab/java)
+
+```java
+import com.azure.android.communication.ui.calling.models.CallCompositeLocalOptions;
+
+final CallCompositeLocalOptions localOptions = new CallCompositeLocalOptions()
+    .setMicrophoneOn(true)
+    .setCameraOn(true);
+
+callComposite.launch(callLauncherActivity, remoteOptions, localOptions);
+```
+-----
+
+### Permission handling
+
+It's recommended to let the users join a call with microphone and camera permission being granted to use the skip setup screen feature with camera and microphone default configuration APIs. However, if developers don't handle the permissions of the user, UI Library tries to handle them for you.
+
+Microphone permission is a must have to join a call. If users try to join a call with denied microphone permission, UI Library drops the call in connecting stage and may throw an error with code `CallCompositeErrorCode.MICROPHONE_PERMISSION_NOT_GRANTED`.
+On the other hand, users are able to join a call even if they deny the camera permission. UI Library disables the camera functionality when camera permission is set as denied. Thus the camera default configuration API doesn't affect the calling experience. User may enjoy default camera configuration API effect once the camera permission is set as granted.
+
+We recommend, developers handle the microphone permission. If user joins the call with camera turned on default, we recommend developers to handle the camera permission as well.
+
+### Network error
+
+If network disruption happens or call drops during a call, UI Library exits and may throw an error with code `CallCompositeErrorCode.CALL_END_FAILED`. If user doesn't have network connection prior to join a call and tries to join the call with skip setup screen feature, UI Library exits at call connecting stage and may throw an error with code `CallCompositeErrorCode.NETWORK_CONNECTION_NOT_AVAILABLE`.
+
+It's recommended to join the call by checking network availability to avoid such error.
+
+To receive error events, call `setOnErrorHandler` with `CallComposite`.
+
+The following `error` values might be sent to the error handler:
+- `microphonePermissionNotGranted`
+- `networkConnectionNotAvailable`
+
+### [Kotlin](#tab/kotlin)
+
+```kotlin
+callComposite.addOnErrorEventHandler { callCompositeErrorEvent ->
+    println(callCompositeErrorEvent.errorCode)
+}
+```
+
+### [Java](#tab/java)
+
+```java
+callComposite.addOnErrorEventHandler(callCompositeErrorEvent -> {
+    System.out.println(callCompositeErrorEvent.getErrorCode());
+});
+```
+-----
+
+