觀察使用者的功能

我是否有權開啟視訊、我是否有權開啟麥克風、我是否有權共用畫面？ 這些權限是您可以從功能 API 中認識到的一些參與者功能範例。 了解這些功能可協助建置使用者介面，該介面只會顯示與本機使用者具有權限之動作相關的按鈕。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• 已部署通訊服務資源。 建立通訊服務資源。
• 用來啟用呼叫用戶端的使用者存取權杖。 如需詳細資訊，請參閱建立和管理存取權杖。
• 選擇性：完成快速入門以將語音通話新增至您的應用程式

安裝 SDK

使用 npm install 命令，安裝適用於 JavaScript 的 Azure 通訊服務通用和通話 SDK：

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

初始化必要的物件

大部分通話作業都需要 CallClient 執行個體。 當您建立新的 CallClient 執行個體時，您可以使用自訂選項加以設定，如同 Logger 執行個體一樣。

使用 CallClient 執行個體，您可以藉由呼叫 createCallAgent 來建立 CallAgent 執行個體。 此方法會以非同步的方式傳回 CallAgent 執行個體物件。

createCallAgent 方法會使用 CommunicationTokenCredential 作為引數。 其接受使用者存取權杖。

您可以使用 CallClient 執行個體上的 getDeviceManager 方法來存取 deviceManager。

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

如何最好地管理與 Microsoft 基礎結構的 SDK 連線

Call Agent 執行個體可協助您管理通話 (加入或啟動通話)。 若要運作，您的通話 SDK 必須連線到 Microsoft 基礎結構以取得來電通知，並協調其他通話詳細資料。 您的 Call Agent 有兩種可能的狀態：

已連線 - Connected 的 Call Agent connectionStatue 值表示用戶端 SDK 已連線且能夠接收來自 Microsoft 基礎結構的通知。

已中斷連線 - Disconnected 狀態的 Call Agent connectionStatue 值指出有問題導致 SDK 無法正確連線。 Call Agent 應該重新建立。

• invalidToken：如果權杖已過期或無效，Call Agent 執行個體會中斷連線，並出現此錯誤。
• connectionIssue：如果用戶端連線到 Microsoft 基礎結構時發生問題，在多次重試之後，Call Agent 會公開 connectionIssue 錯誤。

您可以藉由檢查 connectionState 屬性的目前值，檢查本機 Call Agent 是否已連線到 Microsoft 基礎結構。 在作用中通話期間，您可以接聽 connectionStateChanged 事件，以判斷 Call Agent 是否從已連線變更為已中斷連線狀態。

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

功能特徵是核心 Call API 的擴充功能，可讓您取得目前通話中本機參與者的功能。

此功能可讓您註冊事件接聽程式，以接聽功能變更。

註冊功能特徵：

const capabilitiesFeature = this.call.feature(Features.Capabilities);

取得本機參與者的功能： 功能物件具有本機參與者的功能，且類型為 ParticipantCapabilities。 功能的屬性包括：

• isPresent 指出功能是否存在。
• reason 表示功能解決原因。

const capabilities =  capabilitiesFeature.capabilities;

訂閱capabilitiesChanged事件：

capabilitiesFeature.on('capabilitiesChanged', (capabilitiesChangeInfo) => {
    for (const [key, value] of Object.entries(capabilitiesChangeInfo.newValue)) {
        if(key === 'turnVideoOn' && value.reason != 'FeatureNotSupported') {
             (value.isPresent) ? this.setState({ canOnVideo: true }) : this.setState({ canOnVideo: false });
             continue;
        }
        if(key === 'unmuteMic' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canUnMuteMic: true }) : this.setState({ canUnMuteMic: false });
            continue;
        }
        if(key === 'shareScreen' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canShareScreen: true }) : this.setState({ canShareScreen: false });
            continue;
        }
        if(key === 'spotlightParticipant' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canSpotlight: true }) : this.setState({ canSpotlight: false });
            continue;
        }
        if(key === 'raiseHand' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canRaiseHands: true }) : this.setState({ canRaiseHands: false });
            continue;
        }
        if(key === 'muteOthers' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canMuteOthers: true }) : this.setState({ canMuteOthers: false });
            continue;
        }
        if(key === 'reaction' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canReact: true }) : this.setState({ canReact: false });
            continue;
        }
    }
});

公開的功能

• turnVideoOn：可開啟影片
• unmuteMic：可開啟麥克風
• shareScreen：可分享畫面
• removeParticipant：可移除參與者
• hangUpForEveryOne：可為每個人掛電話
• addCommunicationUser：可新增通訊使用者
• addTeamsUser：可新增 Teams 使用者
• addPhoneNumber：可新增電話號碼
• manageLobby：可管理大廳 (僅限 beta)
• spotlightParticipant：可聚焦參與者 (僅限 beta)
• removeParticipantsSpotlight：可移除參與者聚焦 (僅限 beta)
• startLiveCaptions：可啟動即時輔助字幕 (僅限 beta)
• stopLiveCaptions：可停止即時輔助字幕 (僅限 beta)
• raiseHand：可舉手能力 (僅限 beta)
• muteOthers：可將會議中的遠端參與者軟靜音
• reaction：可在會議中做出反應的能力 (僅限 beta)
• viewAttendeeNames：可檢視會議中的出席者名稱

安裝 SDK

找出您的項目層級build.gradle檔案，並將 新增mavenCentral()至 和allprojects下的buildscript存放庫清單：

buildscript {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

allprojects {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

然後，在您的模組層級 build.gradle 檔案中，將下列幾行新增至 dependencies 區段：

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

初始化必要的物件

若要建立 CallAgent 執行個體，您必須在 CallClient 執行個體上呼叫 createCallAgent 方法。 此呼叫會以非同步方式傳回 CallAgent 執行個體物件。

createCallAgent 方法會採用 CommunicationUserCredential 作為引數，用來封裝存取權杖。

若要存取 DeviceManager，您必須先建立 callAgent 執行個體。 然後，您可以使用 CallClient.getDeviceManager 方法取得 DeviceManager。

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

若要設定來電者的顯示名稱，請使用下列替代方法：

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

功能特徵是核心 Call API 的擴充功能，可讓您取得目前通話中本機參與者的功能。

此功能可讓您註冊事件接聽程式，以接聽功能變更。

若要使用適用於 Windows 的「功能」通話功能，第一個步驟是取得「功能」功能 API 物件：

取得「功能」功能

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.feature(Features.CAPABILITIES);

取得本機參與者的功能

Capabilities 物件具有本機參與者的功能，而且類型為 ParticipantCapability。 功能的屬性包括：

• isAllowed 指出是否可以使用功能。
• reason 表示功能解決原因。

List<ParticipantCapability> capabilities = capabilitiesCallFeature.getCapabilities();

訂閱 capabilitiesChanged 事件

capabilitiesCallFeature.addOnCapabilitiesChangedListener(this::OnCapabilitiesChanged);

private void OnCapabilitiesChanged(CapabilitiesChangedEvent args)
{
    String event = String.format("Capabilities Event: %s", args.getReason().toString());
    Log.i("CapabilitiesInfo", event);
    for (ParticipantCapability capability : args.getChangedCapabilities())
    {
        Log.i("CapabilitiesInfo", capability.getType().toString() + " is " capability.getReason().toString());
    }
}

公開的功能

• TurnVideoOn：可開啟影片
• UnmuteMicrophone：可取消麥克風靜音
• ShareScreen：可共用畫面
• RemoveParticipant：可移除參與者
• HangUpForEveryone：可為每個人掛斷電話
• AddCommunicationUser：可新增通訊使用者
• AddTeamsUser：可新增 Teams 使用者
• AddPhoneNumber：可新增電話號碼
• ManageLobby：可管理大廳
• SpotlightParticipant：可聚焦參與者
• RemoveParticipantSpotlight：可移除參與者聚焦
• BlurBackground：可模糊背景
• CustomBackground：可套用自訂背景
• StartLiveCaptions：可啟動即時輔助字幕
• RaiseHand：可舉手
• MuteOthers：可將會議中的遠端參與者軟靜音

設定系統

請遵循下列步驟來設定系統。

建立 Visual Studio 專案

針對 通用 Windows 平台 應用程式，請在 Visual Studio 2022 中建立新的空白應用程式 （通用 Windows） 專案。 在輸入專案名稱之後，隨意選擇高於 10.0.17763.0 的任何 Windows SDK。

針對 WinUI 3 應用程式，使用空白應用程式、封裝 (桌面中的 WinUI 3) 範本建立新專案，以設定單頁 WinUI 3 應用程式。 需要 Windows App SDK 1.3 版或更新版本。

使用 NuGet 套件管理員來安裝套件和相依性

通話 SDK API 和程式庫可透過 NuGet 套件公開取得。

若要尋找、下載並安裝呼叫 SDK NuGet 套件：

1. 藉由選取 [工具]>[NuGet 套件管理員]>[管理解決方案的 NuGet 套件]，開啟 NuGet 套件管理員。
2. 選取 [ 瀏覽]，然後在搜尋方塊中輸入 Azure.Communication.Calling.WindowsClient 。
3. 請確定 已選取 [包含發行前版本 ] 複選框。
4. 選取 Azure.Communication.Calling.WindowsClient 套件，然後選取 [Azure.Communication.Calling.WindowsClient 1.4.0-beta.1] 或更新版本。
5. 選取對應至右窗格中 Azure 通訊服務 項目的複選框。
6. 選取安裝。

功能特徵是核心 Call API 的擴充功能，可讓您取得目前通話中本機參與者的功能。

此功能可讓您註冊事件接聽程式，以接聽功能變更。

若要使用適用於 Windows 的「功能」通話功能，第一個步驟是取得「功能」功能 API 物件：

取得「功能」功能

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.Features.Capabilities;

取得本機參與者的功能

Capabilities 物件具有本機參與者的功能，而且類型為 ParticipantCapability。 功能的屬性包括：

• isAllowed 指出是否可以使用功能。
• reason 表示功能解決原因。

var capabilities = capabilitiesCallFeature.Capabilities;

訂閱 capabilitiesChanged 事件

capabilitiesCallFeature.CapabilitiesChanged += Call__OnCapabilitiesChangedAsync;

private async void Call__OnCapabilitiesChangedAsync(object sender, CapabilitiesChangedEventArgs args)
{
    Trace.WriteLine(args.Reason.ToString());
    foreach (var capability in args.ChangedCapabilities)
    {
        //Prints out capability kind and resolution reason in console
        Trace.WriteLine(capability.Kind.ToString() + " is " + capability.Reason.ToString());
    }
}

公開的功能

• TurnVideoOn：可開啟影片
• UnmuteMicrophone：可取消麥克風靜音
• ShareScreen：可共用畫面
• RemoveParticipant：可移除參與者
• HangUpForEveryone：可為每個人掛斷電話
• AddCommunicationUser：可新增通訊使用者
• AddTeamsUser：可新增 Teams 使用者
• AddPhoneNumber：可新增電話號碼
• ManageLobby：可管理大廳
• SpotlightParticipant：可聚焦參與者
• RemoveParticipantSpotlight：可移除參與者聚焦
• BlurBackground：可模糊背景
• CustomBackground：可套用自訂背景
• StartLiveCaptions：可啟動即時輔助字幕
• RaiseHand：可舉手
• MuteOthers：可將會議中的遠端參與者軟靜音

設定系統

請遵循下列步驟來設定系統。

建立 Xcode 專案

在 Xcode 中建立新的 iOS 專案，並選取 [單一檢視應用程式] 範本。 本文使用 SwiftUI 架構，因此您應該將 Language 設定為 Swift，並將 Interface 設定為 SwiftUI。

您不會在本文中建立測試。 您可以隨意清除 [包含測試] 核取方塊。

使用 CocoaPods 安裝套件和相依性

1. 為您的應用程式建立 Podfile，如以下範例所示：

   platform :ios, '13.0'
   use_frameworks!
   target 'AzureCommunicationCallingSample' do
       pod 'AzureCommunicationCalling', '~> 1.0.0'
   end
   

2. 執行 pod install。

3. 使用 Xcode 開啟 .xcworkspace。

要求存取麥克風

若要存取裝置的麥克風，您必須使用 NSMicrophoneUsageDescription 更新應用程式的資訊屬性清單。 將相關聯的值設定為對話框中所包含的字串，系統用來要求使用者存取權。

以滑鼠右鍵按一下專案樹狀結構的 Info.plist 項目，接著選取 [開啟為]>[原始程式碼]。 將以下幾行新增至最上層 <dict> 區段中，然後儲存檔案。

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

設定應用程式架構

開啟項目的 ContentView.swift 檔案。 將 import 宣告新增至檔案頂端，以匯入 AzureCommunicationCalling 程式庫。 此外，匯入 AVFoundation。 您需要它才能在程式代碼中要求音訊許可權。

import AzureCommunicationCalling
import AVFoundation

初始化 CallAgent

若要從 CallClient 建立 CallAgent 執行個體，您必須使用 callClient.createCallAgent 方法，在 CallAgent 物件初始化後以非同步方式傳回該物件。

若要建立通話用戶端，請傳遞 CommunicationTokenCredential 物件：

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

將您建立的 CommunicationTokenCredential 物件傳遞至 CallClient，並設定顯示名稱：

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

功能特徵是核心 Call API 的擴充功能，可讓您取得目前通話中本機參與者的功能。

此功能可讓您註冊事件接聽程式，以接聽功能變更。

若要使用適用於 Windows 的「功能」通話功能，第一個步驟是取得「功能」功能 API 物件：

取得「功能」功能

let capabilitiesCallFeature =call.feature(Features.capabilities)

取得本機參與者的功能

Capabilities 物件具有本機參與者的功能，而且類型為 ParticipantCapability。 功能的屬性包括：

• isAllowed 指出是否可以使用功能。
• reason 表示功能解決原因。

var capabilities = capabilitiesCallFeature.capabilities

訂閱 capabilitiesChanged 事件

capabilitiesCallFeature.delegate = CapabilitiesCallDelegate()

public class CapabilitiesCallDelegate : CapabilitiesCallFeatureDelegate
{
    public func capabilitiesCallFeature(_ capabilitiesCallFeature: CapabilitiesCallFeature, didChangeCapabilities args: CapabilitiesChangedEventArgs) {
        let changedReason = args.reason
        let changedCapabilities = args.changedCapabilities
    }
}

公開的功能

• TurnVideoOn：可開啟影片
• UnmuteMicrophone：可取消麥克風靜音
• ShareScreen：可共用畫面
• RemoveParticipant：可移除參與者
• HangUpForEveryone：可為每個人掛斷電話
• AddCommunicationUser：可新增通訊使用者
• AddTeamsUser：可新增 Teams 使用者
• AddPhoneNumber：可新增電話號碼
• ManageLobby：可管理大廳
• SpotlightParticipant：可聚焦參與者
• RemoveParticipantSpotlight：可移除參與者聚焦
• BlurBackground：可模糊背景
• CustomBackground：可套用自訂背景
• StartLiveCaptions：可啟動即時輔助字幕
• RaiseHand：可舉手
• MuteOthers：可將會議中的遠端參與者軟靜音

支援的通話類型

此功能目前僅支援 Azure 通訊服務會議室通話類型和小組會議通話類型

原因

下表提供與無法使用動作的原因相關的其他資訊，並提供如何讓動作可供使用的祕訣。

原因	描述	解決方案
Capable	動作受到允許。
CapabilityNotApplicableForTheCallType	通話類型會封鎖動作。	如果您需要此動作，請考慮其他通話類型。 通話類型包括：1 對 1 通話、群組通話、1 對 1 Teams Interop 通話、1 對 1 Teams Interop 群組通話、分組討論區和會議。
ClientRestricted	執行階段環境正封鎖此動作	變更作業系統、瀏覽器、平台或硬體，以解除封鎖裝置上的動作。 您可以在我們的文件中找到支援的環境。
UserPolicyRestricted	Microsoft 365 使用者的原則會封鎖動作。	使用 ACS SDK 變更指派給會議召集人、通話啟動者或 Microsoft 365 使用者的原則，以啟用此動作。 目標使用者取決於動作的類型。 請在 Teams 中深入了解 Teams 原則。 Teams 系統管理員可以變更原則。
RoleRestricted	指派的角色會封鎖動作。	將使用者升階為不同的角色，讓動作可供使用。
FeatureNotSupported	此通話類型不支援本功能。	請在 Azure 意見反應管道中，讓我們知道您希望讓這項功能可供此通話類型使用。
MeetingRestricted	Teams 會議選項會封鎖動作。	Teams 會議召集人或共同召集人必須變更會議選項，以啟用此動作。
NotInitialized	本功能尚未初始化。	在 this.call.feature(Features.Capabilities) 上訂閱事件 capabilitiesChanged，以得知功能何時初始化。
NotCapable	使用者類型會封鎖動作。	只允許特定類型的身分識別執行此動作。 使用 Microsoft 365 身分識別來啟用此動作。
TeamsPremiumLicenseRestricted	Microsoft 365 使用者必須已指派 Teams 進階版授權。	使用 SDK 將 Teams 進階版授權指派給 Teams 會議召集人或 Microsoft 365 使用者，以啟用此動作。 目標使用者取決於動作的類型。 Microsoft 365 系統管理員可以指派必要的授權。
ExplicitConsentRequired	需要同意才能允許動作。	在或 this.call.feature(Features.Transcription) 下this.call.feature(Features.Recording)呼叫 方法來grantTeamsConsent()提供錄製或轉譯的同意。

下一步

• 了解如何管理視訊
• 了解如何管理通話
• 了解如何錄製通話