啟用通話的推播通知

Azure 通訊服務 Web 通話 SDK - Web 推播通知快速入門

Azure 通訊服務 Web 通話 SDK - Web 推播通知處於公開預覽狀態，並可在 1.12.0-beta.2+ 版中取得。

請瀏覽我們的 Web 推播通知快速入門教學課程：https://github.com/Azure-Samples/communication-services-javascript-quickstarts/blob/main/calling-web-push-notifications/README.md

安裝 SDK

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

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();

推播通知的其他必要條件

已設定將 Cloud Messaging 啟用的 Firebase 帳戶 (FCM)，並具有連線至 Azure 通知中樞執行個體的 Firebase Cloud Messaging 服務。 如需詳細資訊，請參閱通訊服務通知。 此外，本教學課程假設您使用 Android Studio 版本 3.6 或更新版本來建置您的應用程式。

Android 應用程式需要一組權限，才能從 Firebase Cloud Messaging 接收通知訊息。 在您的 AndroidManifest.xml 檔案中，於 <manifest ...> 標籤後方或 </application> 下方新增下列這組權限。

<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" />

概觀

行動推播通知是您在行動裝置上看到的快顯通知。 針對通話，我們將著重於 VoIP (透過網際網路通訊協定的語音) 推播通知。 我們註冊推播通知、處理推播通知，然後取消註冊推播通知。

註冊推播通知

若要註冊推播通知，應用程式必須在具有裝置註冊權杖的 CallAgent 執行個體上呼叫 registerPushNotification()。

若要取得裝置註冊權杖，請將 Firebase SDK 新增至應用程式模組的 build.gradle 檔案，方法是在 dependencies 區段中新增下列程式碼行 (如果尚不存在)：

// 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'

在專案層級的 [build.gradle] 檔案中，在 dependencies 區段中新增下列行 (如果尚不存在)：

classpath 'com.google.gms:google-services:4.3.3'

將下列外掛程式新增至檔案的開頭 (如果尚不存在)：

apply plugin: 'com.google.gms.google-services'

在工具列中選取 [立即同步]。 新增下列程式碼片段，以取得 Firebase Cloud Messaging SDK 為用戶端應用程式執行個體產生的註冊權杖。 確保將以下匯入新增至主要活動的標頭中，以擷取權杖。

import com.google.android.gms.tasks.OnCompleteListener;
import com.google.android.gms.tasks.Task;
import com.google.firebase.iid.FirebaseInstanceId;
import com.google.firebase.iid.InstanceIdResult;

新增此程式碼片段以擷取權杖：

FirebaseInstanceId.getInstance().getInstanceId()
    .addOnCompleteListener(new OnCompleteListener<InstanceIdResult>() {
        @Override
        public void onComplete(@NonNull Task<InstanceIdResult> task) {
            if (!task.isSuccessful()) {
                Log.w("PushNotification", "getInstanceId failed", task.getException());
                return;
            }

            // Get new Instance ID token
            String deviceToken = task.getResult().getToken();
            // Log
            Log.d("PushNotification", "Device Registration token retrieved successfully");
        }
    });

向通話服務 SDK 註冊裝置註冊權杖，以取得連入通話的推播通知：

String deviceRegistrationToken = "<Device Token from previous section>";
try {
    callAgent.registerPushNotification(deviceRegistrationToken).get();
}
catch(Exception e) {
    System.out.println("Something went wrong while registering for Incoming Calls Push Notifications.")
}

推播通知處理

若要接收連入通話的推播通知，請在具有裝載的 CallAgent 執行個體上呼叫 handlePushNotification()。

若要從 Firebase Cloud Messaging 取得裝載，請從建立新的服務 ([檔案] > [新增] > [服務] > [服務])，其會延伸 FirebaseMessagingService Firebase SDK 類別並覆寫 onMessageReceived 方法。 此方法是在 Firebase Cloud Messaging 將推播通知傳遞至應用程式時呼叫的事件處理常式。

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.
        if (remoteMessage.getNotification() != null) {
            Log.d("PushNotification", "Message Notification Body: " + remoteMessage.getNotification().getBody());
        }
        else {
            pushNotificationMessageDataFromFCM = remoteMessage.getData();
        }
    }
}

將下列服務定義新增至 AndroidManifest.xml 檔案的 <application> 標籤內：

<service
    android:name=".MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

擷取承載之後，就可以將其傳遞至 [通訊服務] SDK，以剖析成內部 [IncomingCallInformation] 物件，其將處理在 [CallAgent] 執行個體上呼叫 [handlePushNotification] 方法。 CallAgent 執行個體是藉由呼叫 CallClient 類別上的 createCallAgent(...) 方法建立。

try {
    IncomingCallInformation notification = IncomingCallInformation.fromMap(pushNotificationMessageDataFromFCM);
    Future handlePushNotificationFuture = callAgent.handlePushNotification(notification).get();
}
catch(Exception e) {
    System.out.println("Something went wrong while handling the Incoming Calls Push Notifications.");
}

當推播通知訊息的處理成功，且所有事件處理常式都已正確註冊，應用程式會通知。

取消註冊推播通知

應用程式可以隨時取消註冊推播通知。 呼叫 callAgent 上的 unregisterPushNotification() 方法以取消註冊。

try {
    callAgent.unregisterPushNotification().get();
}
catch(Exception e) {
    System.out.println("Something went wrong while un-registering for all Incoming Calls Push Notifications.")
}

停用來電的內部推送

有兩種方法可以將來電的推播承載傳遞給被呼叫者。

• 使用 FCM 並向上述 API 註冊裝置權杖，registerPushNotification 在 CallAgent 或 TeamsCallAgent 上。
• 當建立 CallAgent 或 TeamsCallAgent 時，SDK 還會註冊，具有内部服務，以讓推播承載得以傳遞。

使用 CallAgentOptions 或 TeamsCallAgentOptions 中的屬性 setDisableInternalPushForIncomingCall，可以指示 SDK 停用使用內部推播服務傳遞推播承載。

CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisableInternalPushForIncomingCall(true);

設定系統

建立 Xcode 專案

在 Xcode 中建立新的 iOS 專案，並選取 [單一檢視應用程式] 範本。 本快速入門使用 SwiftUI 架構，因此您應將 [語言] 設定為 [Swift]，並將 [使用者介面] 設定為 [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")
        }
})

概觀

行動推播通知是您在行動裝置上看到的快顯通知。 針對通話，我們將著重於 VoIP (透過網際網路通訊協定的語音) 推播通知。 我們將註冊推播通知、處理推播通知，然後取消註冊推播通知。 如需 iOS 應用程式中 CallKit 整合的指南，請參閱此處，[CallKit 與 iOS ACS SDK 的整合]。

設定推播通知

行動推播通知是您在行動裝置中取得的快顯通知。 針對通話，我們將著重於 VoIP (透過網際網路通訊協定的語音) 推播通知。

下列小節描述如何註冊、處理和取消註冊推播通知。 開始這些工作之前，請先完成下列必要條件：

1. 在 Xcode 中，移至 [簽署與功能]。 選取 [+ 功能]，然後選取 [推播通知]，以新增功能。
2. 選取 [+ 功能]，然後選取 [背景模式]，以新增另一個功能。
3. 在 [背景模式] 底下，選取 [透過 IP 的語音] 和 [遠端通知] 核取方塊。

註冊推播通知

若要註冊推播通知，請使用裝置註冊權杖在 CallAgent 執行個體上呼叫 registerPushNotification()。

成功初始化之後，必須註冊推播通知。 當 callAgent 物件終結時，將會呼叫 logout，這會自動取消註冊推播通知。

let deviceToken: Data = pushRegistry?.pushToken(for: PKPushType.voIP)
callAgent.registerPushNotifications(deviceToken: deviceToken!) { (error) in
    if(error == nil) {
        print("Successfully registered to push notification.")
    } else {
        print("Failed to register push notification.")
    }
}

處理推播通知

若要接收連入通話的推播通知，請在具有字典裝載的 CallAgent 執行個體上呼叫 handlePushNotification()。

let callNotification = PushNotificationInfo.fromDictionary(pushPayload.dictionaryPayload)

callAgent.handlePush(notification: callNotification) { (error) in
    if (error == nil) {
        print("Handling of push notification was successful")
    } else {
        print("Handling of push notification failed")
    }
}

取消註冊推播通知

應用程式可以隨時取消註冊推播通知。 只要呼叫 CallAgent 上的 unregisterPushNotification 方法。

callAgent.unregisterPushNotification { (error) in
    if (error == nil) {
        print("Unregister of push notification was successful")
    } else {
       print("Unregister of push notification failed, please try again")
    }
}

停用來電的內部推送

有 2 種方法可以將來電的推播承載傳遞給被呼叫者。

• 在 registerPushNotification CallAgent 或 TeamsCallAgent 上使用 APNS 並向上述 API 註冊裝置權杖。
• 當建立 CallAgent 或 TeamsCallAgent 時，SDK 還會註冊，具有内部服務，以讓推播承載得以傳遞。

使用 CallAgentOptions 或 TeamsCallAgentOptions 中的屬性 disableInternalPushForIncomingCall，可以指示 SDK 停用使用內部推播服務傳遞推播承載。

let options = CallAgentOptions()
options.disableInternalPushForIncomingCall = true

設定系統

建立 Visual Studio 專案

針對 UWP 應用程式，在 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. 選取與右側索引標籤上的「通訊服務」專案相對應的核取方塊。
6. 選取 [安裝] 按鈕。

概觀

Windows 平台上的推播通知使用 Windows Push Notification Service (WNS), 傳遞。

設定推播通知

推播通知是您在裝置中取得的快顯通知。 針對通話，我們將著重於 VoIP (透過網際網路通訊協定的語音) 推播通知。

以下區段描述了如何註冊、處理和顯示 Windows 通知以接聽/拒絕來電。 開始這些工作之前，請先完成下列必要條件：

1. 遵循 [教學課程：使用 Azure 通知中樞向通用 Windows 平台應用程式傳送通知]。 完成本教學課程後，您將：

   • 具有 WindowsAzure.Messaging.Managed 和 Microsoft.Toolkit.Uwp.Notifications 套件的應用程式。
   • 此快速入門中參考為 <AZURE_PNH_HUB_NAME> 的 Azure PNH (推播通知中樞) 中樞名稱和參考為 <AZURE_PNH_HUB_CONNECTION_STRING> 的 Azure PNH 連接字串。

2. 若要在每個應用程式初始化時註冊 WNS (Windows 通知服務) 通道，請確保在 App.xaml.cs 檔案中新增初始化程式碼：

// App.xaml.cs

protected override async void OnLaunched(LaunchActivatedEventArgs e)
{
    await InitNotificationsAsync();
    
    ...
}

private async Task InitNotificationsAsync()
{
    if (AZURE_PNH_HUB_NAME != "<AZURE_PNH_HUB_NAME>" && AZURE_PNH_HUB_CONNECTION_STRING != "<AZURE_PNH_HUB_CONNECTION_STRING>")
    {
        var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
        channel.PushNotificationReceived += Channel_PushNotificationReceived;
    
        var hub = new NotificationHub(AZURE_PNH_HUB_NAME, AZURE_PNH_HUB_CONNECTION_STRING);
        var result = await hub.RegisterNativeAsync(channel.Uri);
    
        if (result.ChannelUri != null)
        {
            PNHChannelUri = new Uri(result.ChannelUri);
        }
        else
        {
            Debug.WriteLine("Cannot register WNS channel");
        }
    }
}

3. 註冊在 App.xaml.cs 上收到新推播通知訊息時啟動的事件處理常式：

// App.xaml.cs

private void Channel_PushNotificationReceived(PushNotificationChannel sender, PushNotificationReceivedEventArgs args)
{
    switch (args.NotificationType)
    {
      case PushNotificationType.Toast:
      case PushNotificationType.Tile:
      case PushNotificationType.TileFlyout:
      case PushNotificationType.Badge:
          break;
      case PushNotificationType.Raw:
          var frame = (Frame)Window.Current.Content;
          if (frame.Content is MainPage)
          {
              var mainPage = frame.Content as MainPage;
              await mainPage.HandlePushNotificationIncomingCallAsync(args.RawNotification.Content);
          }
          break;
    }
}

註冊推播通知

若要註冊推播通知，請使用在應用程式初始化時取得的 WNS 註冊通道在 CallAgent 執行個體上呼叫 RegisterForPushNotificationAsync()。

成功初始化之後，必須註冊推播通知。

// MainPage.xaml.cs

this.callAgent = await this.callClient.CreateCallAgentAsync(tokenCredential, callAgentOptions);
                
if ((Application.Current as App).PNHChannelUri != null)
{
    await this.callAgent.RegisterForPushNotificationAsync((Application.Current as App).PNHChannelUri.ToString());
}

this.callAgent.CallsUpdated += OnCallsUpdatedAsync;
this.callAgent.IncomingCallReceived += OnIncomingCallAsync;

處理推播通知

若要接收連入通話的推播通知，請在具有字典裝載的 CallAgent 執行個體上呼叫 handlePushNotification()。

// MainPage.xaml.cs

public async Task HandlePushNotificationIncomingCallAsync(string notificationContent)
{
    if (this.callAgent != null)
    {
        PushNotificationDetails pnDetails = PushNotificationDetails.Parse(notificationContent);
        await callAgent.HandlePushNotificationAsync(pnDetails);
    }
}

這會在 CallAgent 上觸發來電事件，顯示來電通知。

// MainPage.xaml.cs

private async void OnIncomingCallAsync(object sender, IncomingCallReceivedEventArgs args)
{
    incomingCall = args.IncomingCall;
    (Application.Current as App).ShowIncomingCallNotification(incomingCall);
}

// App.xaml.cs

public void ShowIncomingCallNotification(IncomingCall incomingCall)
{
    string incomingCallType = incomingCall.IsVideoEnabled ? "Video" : "Audio";
    string caller = incomingCall.CallerDetails.DisplayName != "" ? incomingCall.CallerDetails.DisplayName : incomingCall.CallerDetails.Identifier.RawId;
    new ToastContentBuilder()
    .SetToastScenario(ToastScenario.IncomingCall)
    .AddText(caller + " is calling you.")
    .AddText("New Incoming " + incomingCallType + " Call")
      .AddButton(new ToastButton()
          .SetContent("Decline")
          .AddArgument("action", "decline"))
      .AddButton(new ToastButton()
          .SetContent("Accept")
          .AddArgument("action", "accept"))
      .Show();
}

在 OnActivated 方法中新增處理通知按鈕按下的程式碼：

// App.xaml.cs

protected override async void OnActivated(IActivatedEventArgs e)
{   
    // Handle notification activation
    if (e is ToastNotificationActivatedEventArgs toastActivationArgs)
    {
      ToastArguments args = ToastArguments.Parse(toastActivationArgs.Argument);
      string action = args?.Get("action");
    
      if (!string.IsNullOrEmpty(action))
      {
          var frame = Window.Current.Content as Frame;
          if (frame.Content is MainPage)
          {
              var mainPage = frame.Content as MainPage;
              await mainPage.AnswerIncomingCall(action);
          }
      }
    }
}

// MainPage.xaml.cs

public async Task AnswerIncomingCall(string action)
{
    if (action == "accept")
    {
      var acceptCallOptions = new AcceptCallOptions()
      {
          IncomingVideoOptions = new IncomingVideoOptions()
          {
              StreamKind = VideoStreamKind.RemoteIncoming
          }
      };
    
      call = await incomingCall?.AcceptAsync(acceptCallOptions);
      call.StateChanged += OnStateChangedAsync;
      call.RemoteParticipantsUpdated += OnRemoteParticipantsUpdatedAsync;
    }
    else if (action == "decline")
    {
      await incomingCall?.RejectAsync();
    }
}