Edit

Get started with the calling hero sample

  • Article
  • 12 minutes to read

The Azure Communication Services Group Calling Hero Sample demonstrates how the Communication Services Calling Web SDK can be used to build a group calling experience.

In this Sample quickstart, we'll learn how the sample works before we run the sample on your local machine. We'll then deploy the sample to Azure using your own Azure Communication Services resources.

Download code

Find the project for this sample on GitHub. A version of the sample which includes features currently in public preview such as Teams Interop and Call Recording can be found on a separate branch.

Deploy to Azure

Overview

The sample has both a client-side application and a server-side application. The client-side application is a React/Redux web application that uses Microsoft's Fluent UI framework. This application sends requests to an ASP.NET Core server-side application that helps the client-side application connect to Azure.

Here's what the sample looks like:

Screenshot showing the landing page of the sample application.

When you press the "Start a call" button, the web application fetches a user access token from the server-side application. This token is then used to connect the client app to Azure Communication Services. Once the token is retrieved, you'll be prompted to specify the camera and microphone that you want to use. You'll be able to disable/enable your devices with toggle controls:

Screenshot showing the pre-call screen of the sample application.

Once you configure your display name and devices, you can join the call session. You'll then see the main call canvas where the core calling experience lives.

Screenshot showing the main screen of the sample application.

Components of the main calling screen:

  • Media Gallery: The main stage where participants are shown. If a participant has their camera enabled, their video feed is shown here. Each participant has an individual tile which shows their display name and video stream (when there is one)
  • Header: This is where the primary call controls are located to toggle settings and participant side bar, turn video and mix on/off, share screen and leave the call.
  • Side Bar: This is where participants and settings information are shown when toggled using the controls on the header. The component can be dismissed using the 'X' on the top right corner. Participants side bar will show a list of participants and a link to invite more users to chat. Settings side bar allows you to configure microphone and camera settings.

Note

Based on limitations on the Web Calling SDK, only 4 video streams and 1 screen sharing stream is rendered. For more information see, Calling SDK Stream Support.

Below you'll find more information on prerequisites and steps to set up the sample.

Prerequisites

Before running the sample for the first time

  1. Open an instance of PowerShell, Windows Terminal, Command Prompt or equivalent and navigate to the directory that you'd like to clone the sample to.

    git clone https://github.com/Azure-Samples/communication-services-web-calling-hero.git

  2. Get the Connection String from the Azure portal or by using the Azure CLI.

    az communication list-key --name "<acsResourceName>" --resource-group "<resourceGroup>"

    For more information on connection strings, see Create an Azure Communication Resources

  3. Once you get the Connection String, add the connection string to the samples/Server/appsetting.json file. Input your connection string in the variable: ResourceConnectionString.

  4. Get the Endpoint string from the Azure portal or by using the Azure CLI.

    az communication list-key --name "<acsResourceName>" --resource-group "<resourceGroup>"

    For more information on Endpoint strings, see Create an Azure Communication Resources

  5. Once you get the Endpoint String, add the endpoint string to the samples/Server/appsetting.json file. Input your endpoint string in the variable EndpointUrl

Local run

  1. Install dependencies

    npm run setup

  2. Start the calling app

    npm run start

    This will open a client server on port 3000 that serves the website files, and an api server on port 8080 that performs functionality like minting tokens for call participants.

Troubleshooting

  • The app shows an "Unsupported browser" screen but I am on a supported browser.

    If your app is being served over a hostname other than localhost, you must serve traffic over https and not http.

Publish to Azure

  1. npm run setup
  2. npm run build
  3. npm run package
  4. Use the Azure extension and deploy the Calling/dist directory to your app service

Clean up resources

If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.

Next steps

Download the sample from GitHub

For more information, see the following articles:

Additional reading

  • Samples - Find more samples and examples on our samples overview page.
  • Redux - Client-side state management
  • FluentUI - Microsoft powered UI library
  • React - Library for building user interfaces
  • ASP.NET Core - Framework for building web applications

The Azure Communication Services Group Calling Hero Sample for iOS demonstrates how the Communication Services Calling iOS SDK can be used to build a group calling experience that includes voice and video. In this sample quickstart, you will learn how to set up and run the sample. An overview of the sample is provided for context.

Download code

Find the project for this sample on GitHub.

Overview

The sample is a native iOS application that uses the Azure Communication Services iOS SDKs to build a calling experience that features both voice and video calling. The application uses a server-side component to provision access tokens that are then used to initialize the Azure Communication Services SDK. To configure this server-side component, feel free to follow the Trusted Service with Azure Functions tutorial.

Here's what the sample looks like:

Screenshot showing the landing page of the sample application.

When you press the "Start new call" button, the iOS application prompts you to enter your display name to use for the call.

Screenshot showing the pre-call screen of the sample application.

After tapping "Next" on the "Start Call" screen, you have the opportunity to share the group ID of the call via the iOS share sheet.

Screenshot showing the share group ID screen of the sample application.

The application also allows you to join an existing Azure Communication Services call by specifying the existing call's ID or teams ID link.

Screenshot showing the join call screen of the sample application.

After joining a call, you'll be prompted to give the application permission to access your camera and microphone, if not already authorized. Keep in mind that, like all AVFoundation-based apps, true audio and video functionality is only available on real hardware.

Once you configure your display name and join the call, you'll see the main call canvas where the core calling experience lives.

Screenshot showing the main screen of the sample application.

Components of the main calling screen:

  • Media Gallery: The main stage where participants are shown. If a participant has their camera enabled, their video feed is shown here. Each participant has an individual tile which shows their display name and video stream (when there is one). The gallery supports multiple participants and is updated when participants are added or removed to the call.
  • Action Bar: This is where the primary call controls are located. These controls let you turn your video and microphone on/off, share your screen, and leave the call.

Below you'll find more information on prerequisites and steps to set up the sample.

Prerequisites

Running sample locally

The group calling sample can be run locally using XCode. Developers can either use their physical device or an emulator to test the application.

Before running the sample for the first time

  1. Install dependencies by running pod install.
  2. Open AzureCalling.xcworkspace in XCode.
  3. Create a text file at the root, called AppSettings.xcconfig and set the value: 
    communicationTokenFetchUrl = <your authentication endpoint, without the https:// component>

Run sample

Build and run the sample in XCode, using the AzureCalling target on the simulator or device of your choice.

(Optional) Securing an authentication endpoint

For demonstration purposes, this sample uses a publicly accessible endpoint by default to fetch an Azure Communication Services access token. For production scenarios, we recommend using your own secured endpoint to provision your own tokens.

With additional configuration, this sample supports connecting to an Azure Active Directory (Azure AD) protected endpoint so that user login is required for the app to fetch an Azure Communication Services access token. See steps below:

  1. Enable Azure Active Directory authentication in your app.
  2. Go to your registered app overview page under Azure Active Directory App Registrations. Take note of the Application (client) ID, Directory (tenant) ID, Application ID URI

Azure Active Directory configuration on Azure portal.

  1. Create a AppSettings.xcconfig file at the root if not already present and add the values: 
    communicationTokenFetchUrl = <Application ID URI, without the https:// component>
aadClientId = <Application (client) ID>
aadTenantId = <Directory (tenant) ID>

Clean up resources

If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.

Next steps

Download the sample from GitHub

For more information, see the following articles:

Additional reading

The Azure Communication Services Group Calling Hero Sample for Android demonstrates how the Communication Services Calling Android SDK can be used to build a group calling experience that includes voice and video. In this sample quickstart, you will learn how to set up and run the sample. An overview of the sample is provided for context.

Download code

Find the project for this sample on GitHub.

Overview

The sample is a native Android application that uses the Azure Communication Services Android UI client library to build a calling experience that features both voice and video calling. The application uses a server-side component to provision access tokens that are then used to initialize the Azure Communication Services SDK. To configure this server-side component, feel free to follow the Trusted Service with Azure Functions tutorial.

Here's what the sample looks like:

Screenshot showing the landing page of the sample application.

When you press the "Start new call" button, the Android application prompts you to enter your display name to use for the call.

Screenshot showing the pre-call screen of the sample application.

After tapping "Next" on the "Start A call" page, you have the opportunity to share the "Group Call ID".

Screenshot showing the share Group Call ID screen of the sample application.

The application allows you to join an existing Azure Communication Services call by specifying the existing call's ID or teams meeting ID link and display name.

Screenshot showing the join call screen of the sample application.

After joining a call, you'll be prompted to give the application permission to access your camera and microphone, if not already authorized. You'll see the main call canvas where the core calling experience lives.

Screenshot showing the main screen of the sample application.

Components of the main calling screen:

  • Media Gallery: The main stage where participants are shown. If a participant has their camera enabled, their video feed is shown here. Each participant has an individual tile which shows their display name and video stream (when there is one). The gallery supports multiple participants and is updated when participants are added or removed to the call.
  • Action Bar: This is where the primary call controls are located. These controls let you turn your video and microphone on/off, share your screen, and leave the call.

Below you'll find more information on prerequisites and steps to set up the sample.

Prerequisites

Running sample locally

The group calling sample can be run locally using Android Studio. Developers can either use their physical device or an emulator to test the application.

Before running the sample for the first time

  1. Open Android Studio and select Open an Existing Project
  2. Open the AzureCalling folder inside downloaded release for the sample.
  3. Expand app/assets to update appSettings.properties. Set the value for the key communicationTokenFetchUrl to be the URL for your Authentication Endpoint set up as a prerequisite.

Run sample

Build and run the sample in Android Studio.

(Optional) Securing an authentication endpoint

For demonstration purposes, this sample uses a publicly accessible endpoint by default to fetch an Azure Communication Services token. For production scenarios, we recommend using your own secured endpoint to provision your own tokens.

With additional configuration, this sample supports connecting to an Azure Active Directory (Azure AD) protected endpoint so that user login is required for the app to fetch an Azure Communication Services token. See steps below:

  1. Enable Azure Active Directory authentication in your app.

  2. Go to your registered app overview page under Azure Active Directory App Registrations. Take note of the Package name, Signature hash, MSAL Configutaion

Azure Active Directory configuration on Azure portal.

  1. Edit AzureCalling/app/src/main/res/raw/auth_config_single_account.json and set isAADAuthEnabled to enable Azure Active Directory

  2. Edit AndroidManifest.xml and set android:path to keystore signature hash. (Optional. The current value uses hash from bundled debug.keystore. If different keystore is used, this must be updated.)

    <activity android:name="com.microsoft.identity.client.BrowserTabActivity">
         <intent-filter>
             <action android:name="android.intent.action.VIEW" />
             <category android:name="android.intent.category.DEFAULT" />
             <category android:name="android.intent.category.BROWSABLE" />
             <data
                 android:host="com.azure.samples.communication.calling"
                 android:path="/Signature hash" <!-- do not remove /. The current hash in AndroidManifest.xml is for debug.keystore. -->
                 android:scheme="msauth" />
         </intent-filter>
     </activity>

  3. Copy MSAL Android configuration from Azure portal and paste to AzureCalling/app/src/main/res/raw/auth_config_single_account.json. Include "account_mode": "SINGLE"

       {
      "client_id": "",
      "authorization_user_agent": "DEFAULT",
      "redirect_uri": "",
      "account_mode" : "SINGLE",
      "authorities": [
         {
            "type": "AAD",
            "audience": {
            "type": "AzureADMyOrg",
            "tenant_id": ""
            }
         }
      ]
   }

  4. Edit AzureCalling/app/src/main/res/raw/auth_config_single_account.json and set the value for the key communicationTokenFetchUrl to be the URL for your secure Authentication Endpoint.

  5. Edit AzureCalling/app/src/main/res/raw/auth_config_single_account.json and set the value for the key aadScopes from Azure Active Directory Expose an API scopes

  6. Set value for graphURL in AzureCalling/app/assets/appSettings.properties as the Graph API endpoint to fetch user information.

  7. Edit AzureCalling/app/src/main/assets/appSettings.properties and set the value for the key tenant to enable silent login so that the user does not have to be authenticated again and again while restarting the application.

Clean up resources

If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.

Next steps

Download the sample from GitHub

For more information, see the following articles:

Additional reading