Povratne informacije Uredi

Quickstart: Get started with the UI Library

  • Članak
  • 12 min. za čitanje

Get started with Azure Communication Services by using the UI Library to quickly integrate communication experiences into your applications. In this quickstart, you'll learn how to integrate the composites into your applications.

The UI library will render a full communication experience right into your application. It takes care of connecting to the desired call and setting it up behind the scenes. As a developer you just need to worry about where in your experience you want the communication experience to launch. The composite takes the user through setting up their devices, joining the call and participating in it, and rendering other participants.

Note

For detailed documentation and quickstarts about the Web UI Library visit the Web UI Library Storybook.

Prerequisites

You can access the following quickstarts

Azure Communication UI open source library for Android and the sample application code can be found here

Prerequisites

Setting up

Creating an Android app with an empty activity

In Android Studio, create a new project and select the Empty Activity.

Start a new Android Studio Project

Click the Next button and name the project UILibraryQuickStart, set language to Java/Kotlin and select Minimum SDK API 21: Android 5.0 (Lollipop) or greater.

Screenshot showing the 'Finish' button selected in Android Studio.

Click Finish.

Install the packages

Add Dependency

In your app level (app folder) UILibraryQuickStart/app/build.gradle, add the following dependency.

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-ui-calling:+'
    ...
}

Maven Repositories

Two maven repositories are required to integrate the library. MavenCentral is the first, the second is Azure's package repository.

In your project gradle scripts ensure the following repositories are added.

For Android Studio (2020.*), the repositories are in settings.gradle dependencyResolutionManagement(Gradle version 6.8 or greater).
If you are using old versions of Android Studio (4.*), then the repositories will be in project level build.gradle allprojects{}.

// dependencyResolutionManagement
repositories {
    ...
    mavenCentral()
    maven {
        url "https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1"
    }
    ...
}

Sync project with gradle files. (Android Studio -> File -> Sync Project With Gradle Files)

Add a button to the activity_main

Go to the layout file (app/src/main/res/layout/activity_main.xml). Here we'll drop the following code to create a button to start composite.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/startButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Launch"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Initialize composite

Go to MainActivity. Here we'll drop the following code to initialize our Composite Components for Calling. Replace "GROUP_CALL_ID" with your group ID for your call, "DISPLAY_NAME" with your name, and "<USER_ACCESS_TOKEN>" with your token.

package com.example.uilibraryquickstart

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.Button
import com.azure.android.communication.common.CommunicationTokenCredential
import com.azure.android.communication.common.CommunicationTokenRefreshOptions
import com.azure.android.communication.ui.calling.CallComposite
import com.azure.android.communication.ui.calling.CallCompositeBuilder
import com.azure.android.communication.ui.calling.models.CallCompositeGroupCallLocator
import com.azure.android.communication.ui.calling.models.CallCompositeJoinLocator
import com.azure.android.communication.ui.calling.models.CallCompositeRemoteOptions
import java.util.UUID

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        val startButton: Button = findViewById(R.id.startButton)
        startButton.setOnClickListener { l -> startCallComposite() }
    }

    private fun startCallComposite() {
        val communicationTokenRefreshOptions = CommunicationTokenRefreshOptions({ fetchToken() }, true)
        val communicationTokenCredential = CommunicationTokenCredential(communicationTokenRefreshOptions)

        val locator: CallCompositeJoinLocator = CallCompositeGroupCallLocator(UUID.fromString("GROUP_CALL_ID"))
        val remoteOptions = CallCompositeRemoteOptions(locator, communicationTokenCredential, "DISPLAY_NAME")

        val callComposite: CallComposite = CallCompositeBuilder().build()
        callComposite.launch(this, remoteOptions)
    }

    private fun fetchToken(): String? {
        return "USER_ACCESS_TOKEN"
    }
}

Run the code

Build and start application from Android Studio.

  • Click Launch.
  • Accept permissions and select device, mic, and video settings.
  • Click Join Call.

Launch

Object Model

The following classes and interfaces handle some of the major features of the Azure Communication Services Android UI:

Name Description
CallComposite Composite component that renders a call experience with participant gallery and controls.
CallCompositeBuilder Builder to build CallComposite with options.
CallCompositeJoinMeetingLocator Passed in CallComposite launch to start group call.
CallCompositeTeamsMeetingLinkLocator Passed to CallComposite launch to join Teams meeting.
CallCompositeLocalizationOptions Injected as optional in CallCompositeBuilder to set language of composite.

UI Library functionality

Create Call Composite

Initialize a CallCompositeBuilder instance and a CallComposite instance inside the startCallComposite function.

val callComposite: CallComposite = CallCompositeBuilder().build()

Setup authentication

Initialize a CommunicationTokenCredential instance inside the startCallComposite function. Replace "<USER_ACCESS_TOKEN>" with your token.

val callComposite: CallComposite = CallCompositeBuilder().build()

val communicationTokenRefreshOptions = CommunicationTokenRefreshOptions(this::fetchToken, true)

val communicationTokenCredential = CommunicationTokenCredential(communicationTokenRefreshOptions)

Setup Group Call or Teams Meeting Options

Depending on what type of Call/Meeting you would like to set up, use the appropriate options object.

Group Call

Initialize a CallCompositeGroupCallLocator and supply it to the CallCompositeRemoteOptions object.

val locator = CallCompositeGroupCallLocator(UUID.fromString("GROUP_CALL_ID"))

val remoteOptions = CallCompositeRemoteOptions(
    locator,
    communicationTokenCredential,            
    "DISPLAY_NAME",
)

Teams Meeting

Initialize a CallCompositeTeamsMeetingLinkLocator and supply it to the CallCompositeRemoteOptions object.

val locator = CallCompositeTeamsMeetingLinkLocator("TEAMS_MEETING_LINK")

val remoteOptions = CallCompositeRemoteOptions(
    locator,
    communicationTokenCredential,            
    "DISPLAY_NAME",
)

A Microsoft Teams meeting link can be retrieved using Graph APIs. This process is detailed in Graph documentation.

The Communication Services Call SDK accepts a full Microsoft Teams meeting link. This link is returned as part of the onlineMeeting resource, accessible under the joinWebUrl property You can also get the required meeting information from the Join Meeting URL in the Teams meeting invite itself.

Launch

Call launch on the CallComposite instance inside the startCallComposite function

callComposite.launch(context, remoteOptions)

Subscribe to error events from CallComposite

To receive error events, call setOnErrorHandler with the CallComposite.

The following errorCode values may be sent to the Error Handler

  • CallCompositeErrorCode.CALL_JOIN_FAILED
  • CallCompositeErrorCode.CALL_END_FAILED
  • CallCompositeErrorCode.TOKEN_EXPIRED
callComposite.addOnErrorEventHandler { callCompositeErrorEvent ->
    println(callCompositeErrorEvent.errorCode)
}

Apply theme configuration

To change the primary color of composite, create a new theme style in src/main/res/values/themes.xml and src/main/res/values-night/themes.xml by considering AzureCommunicationUICalling.Theme as parent theme. To apply theme, inject the theme ID in CallCompositeBuilder.

<style name="MyCompany.CallComposite" parent="AzureCommunicationUICalling.Theme">
    <item name="azure_communication_ui_calling_primary_color">#27AC22</item>
    <item name="azure_communication_ui_calling_primary_color_tint10">#5EC65A</item>
    <item name="azure_communication_ui_calling_primary_color_tint20">#A7E3A5</item>
    <item name="azure_communication_ui_calling_primary_color_tint30">#CEF0CD</item>
</style>

val callComposite: CallComposite =
        CallCompositeBuilder()
            .theme(R.style.MyCompany_CallComposite)
            .build()

Apply localization configuration

To change the language of composite, create a CallCompositeLocalizationOptions with Locale from CallCompositeSupportedLocale. To apply language, inject the localization configuration in CallCompositeBuilder. By default, all text labels use English (en) strings. If desired, CallCompositeLocalizationOptions can be used to set a different language. Out of the box, the UI library includes a set of language usable with the UI components. CallCompositeSupportedLocale provides the supported Locales. For example, to access English Locale, CallCompositeSupportedLocale.EN can be used. CallCompositeSupportedLocale.getSupportedLocales() provides list of supported language's Locale objects.

import com.azure.android.communication.ui.calling.models.CallCompositeLocalizationOptions
import com.azure.android.communication.ui.calling.models.CallCompositeSupportedLocale

// CallCompositeSupportedLocale provides list of supported locale
val callComposite: CallComposite =
            CallCompositeBuilder().localization(
                CallCompositeLocalizationOptions(CallCompositeSupportedLocale.EN)
            ).build()

More Features

The list of use cases has detailed information of more features.

Add notifications into your mobile app

The push notifications allow you to send information from your application to users' mobile devices. You can use push notifications to show a dialog, play a sound, or display incoming call UI. Azure Communication Services provides integrations with Azure Event Grid and Azure Notification Hubs that enable you to add push notifications to your apps follow the link.

Azure Communication UI open source library for Android and the sample application code can be found here

Prerequisites

Setting up

Creating the Xcode project

In Xcode, create a new iOS project and select the App template. We'll be using UIKit storyboards. You're not going to create tests during this quickstart. Feel free to uncheck Include Tests.

Screenshot showing the New Project template selection within Xcode.

Name the project UILibraryQuickStart and select Storyboard under the Interface dropdown.

Screenshot showing the New Project details within Xcode.

Install the package and dependencies with CocoaPods

  1. (Optional) For MacBook with M1, install and enable Rosetta in Xcode.
  2. Create a Podfile in your project root directory by running pod init.
    • If encounter error, update CocoaPods to latest version
  3. Add the following to your Podfile:
    • Replace UILibraryQuickStart with your project name
platform :ios, '14.0'

target 'UILibraryQuickStart' do
    use_frameworks!
    pod 'AzureCommunicationUICalling', '1.0.0'
end
  1. Run pod install --repo-update.
  2. Open the generated .xcworkspace with Xcode.

Request access to the microphone, camera, etc.

To access the device's hardware, update your app's Information Property List. Set the associated value to a string that will be included in the dialog the system uses to request access from the user.

Right-click the Info.plist entry of the project tree and select Open As > Source Code. Add the following lines the top level <dict> section, and then save the file.

<key>NSCameraUsageDescription</key>
<string></string>
<key>NSMicrophoneUsageDescription</key>
<string></string>

Screenshot showing the Info plist sourc code in Xcode.

To verify requesting the permission is added correctly, view the Info.plist as Open As > Property List and should expect to see the following:

Screenshot showing the Camera and Microphone privacy in Xcode.

Turn off Bitcode

Set Enable Bitcode option to No in the project Build Settings. To find the setting, you have to change the filter from Basic to All, you can also use the search bar on the right.

Screenshot showing the BitCode option in Xcode.

Initialize composite

Go to 'ViewController'. Here we'll drop the following code to initialize our Composite Components for Call. Replace <GROUP_CALL_ID> with either your call group ID or UUID() to generate one. Also replace <DISPLAY_NAME> with your name, and <USER_ACCESS_TOKEN> with your token. The limit for string length of <DISPLAY_NAME> is 256.

import UIKit
import AzureCommunicationCalling
import AzureCommunicationUICalling

class ViewController: UIViewController {

    private var callComposite: CallComposite?

    override func viewDidLoad() {
        super.viewDidLoad()

        let button = UIButton(frame: CGRect(x: 100, y: 100, width: 200, height: 50))
        button.contentEdgeInsets = UIEdgeInsets(top: 10.0, left: 20.0, bottom: 10.0, right: 20.0)
        button.layer.cornerRadius = 10
        button.backgroundColor = .systemBlue
        button.setTitle("Start Experience", for: .normal)
        button.addTarget(self, action: #selector(startCallComposite), for: .touchUpInside)

        button.translatesAutoresizingMaskIntoConstraints = false
        self.view.addSubview(button)
        button.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
        button.centerYAnchor.constraint(equalTo: view.centerYAnchor).isActive = true
    }

    @objc private func startCallComposite() {
        let callCompositeOptions = CallCompositeOptions()

        callComposite = CallComposite(withOptions: callCompositeOptions)

        let communicationTokenCredential = try! CommunicationTokenCredential(token: "<USER_ACCESS_TOKEN>")

        let remoteOptions = RemoteOptions(for: .groupCall(groupId: UUID(uuidString: "<GROUP_CALL_ID>")!),
                                          credential: communicationTokenCredential,
                                          displayName: "<DISPLAY_NAME>")
        callComposite?.launch(remoteOptions: remoteOptions)
    }
}

Run the code

You can build and run your app on iOS simulator by selecting Product > Run or by using the (⌘-R) keyboard shortcut.

  1. Tap Start Experience.
  2. Accept audio permissions and select device, mic, and video settings.
  3. Tap Start Call.

Final look and feel of the quick start app

Object Model

The following classes and interfaces handle some of the major features of the Azure Communication Services UI client library:

Name Description
CallComposite The composite renders a call experience with participant gallery and controls.
CallCompositeOptions Includes options such as the theme options and the events handler.
RemoteOptions The remote options send to AzureCommunicationService for joining a group call or Team's meeting.
ThemeOptions Allows you to customize the theme.
LocalizationOptions Allows you to set the language for the composite.

UI Library functionality

Create call composite

Initialize a CallCompositeOptions instance and a CallComposite instance inside the startCallComposite function.

@objc private func startCallComposite() {
    let callCompositeOptions = CallCompositeOptions()

    callComposite = CallComposite(withOptions: callCompositeOptions)
}

Setup authentication

Initialize a CommunicationTokenCredential instance inside the startCallComposite function. Replace <USER_ACCESS_TOKEN> with your token.

let communicationTokenCredential = try! CommunicationTokenCredential(token: "<USER_ACCESS_TOKEN>")

Refer to the user access token documentation if you don't already have a token available.

Setup group call or Teams meeting options

Depending on what type of Call/Meeting you would like to set up, use the appropriate options object.

Group call

Initialize a RemoteOptions instance for .groupCall locator inside the startCallComposite function. Replace <GROUP_CALL_ID> with your group ID for your call and <DISPLAY_NAME> with your name.

Learn more about group call here.

// let uuid = UUID() to create a new call
let uuid = UUID(uuidString: "<GROUP_CALL_ID>")!
let remoteOptions = RemoteOptions(for: .groupCall(groupId: uuid),
                                  credential: communicationTokenCredential,
                                  displayName: "<DISPLAY_NAME>")

Teams meeting

Initialize a RemoteOptions instance for .teamsMeeting locator inside the startCallComposite function. Replace <TEAMS_MEETING_LINK> with your Teams meeting link for your call and <DISPLAY_NAME> with your name.

let remoteOptions = RemoteOptions(for: .teamsMeeting(teamsLink: "<TEAMS_MEETING_LINK>"),
                                  credential: communicationTokenCredential,
                                  displayName: "<DISPLAY_NAME>")

A Microsoft Teams meeting link can be retrieved using Graph APIs. This process is detailed in Graph documentation. The Communication Services Calling SDK accepts a full Microsoft Teams meeting link. This link is returned as part of the onlineMeeting resource, accessible under the joinWebUrl property You can also get the required meeting information from the Join Meeting URL in the Teams meeting invite itself.

Launch

Call launch on the CallComposite instance inside the startCallComposite function

callComposite?.launch(remoteOptions: remoteOptions)

Subscribe to events

You can implement the closures to act on the events. An event for when the composite ended with an error is an example.

callComposite?.events.onError = { error in
    print("CallComposite failed with error:\(error)")
}

Apply theme options

You can customize the theme by creating custom theme options that implement the ThemeOptions protocol. You then include an instance of that new class in your CallCompositeOptions.

class CustomThemeOptions: ThemeOptions {
   var primaryColor: UIColor {
       return UIColor.red
   }
}

let callCompositeOptions = CallCompositeOptions(theme: CustomThemeOptions())

For more on how theming works, check out the Theming guide.

Apply localization options

You can change the language by creating custom localization options and include it to your CallCompositeOptions. By default, all text labels use our English (SupportedLocale.en) strings. If desired, LocalizationOptions can be used to set a different locale. Out of the box, the UI library includes a set of locale usable with the UI components. SupportedLocale.values provides a list of all supported languages.

For the example below, the composite will be localized to French (fr).

// Option1: Use intellisense to get supported locales by the UI Library
let localizationOptions = LocalizationOptions(locale: SupportedLocale.frFR)

// Option2: Swift Locale struct, if locale not supported by UI Library, will default to English
let localizationOptions = LocalizationOptions(locale: Locale(identifier: "fr-FR"))

let callCompositeOptions = CallCompositeOptions(localization: localizationOptions)

For more on localization and list of supported languages, check out the Localization guide.

Add notifications into your mobile app

The push notifications allow you to send information from your application to users' mobile devices. You can use push notifications to show a dialog, play a sound, or display incoming call UI. Azure Communication Services provides integrations with Azure Event Grid and Azure Notification Hubs that enable you to add push notifications to your apps follow the link.

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.