在 UI 程式庫中設定一對一通話和推播通知

發行項
06/28/2024

UI 程式庫提供現成支援，讓您可使用 Azure 通訊服務參與者識別碼進行一對一通話。為了支援一對一通話，UI 程式庫提供了來電通知。您也可以使用 Azure 通訊服務作為通話的 Azure 事件方格事件來源。

在本文中，您將了解如何在應用程式中使用 UI 程式庫正確進行一對一通話。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
用來啟用通話用戶端的使用者存取權杖。取得使用者存取權杖。
選擇性：完成開始使用 UI 程式庫複合的快速入門。

設定功能

如需詳細資訊，請參閱開放原始碼 Android UI 程式庫和範例應用程式程式碼。

設定推播通知的權限

若要設定推播通知，您必須要有已啟用 Firebase Cloud Messaging (FCM) 的 Firebase 帳戶。您的 FCM 服務必須連線至 Azure 通知中樞執行個體。如需詳細資訊，請參閱通訊服務通知。您也需使用 Android Studio 3.6 版或更新版本來建置應用程式。

Android 應用程式必須要有一組權限，才能接收來自 FCM 的通知訊息。在您的 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" />

將來電通知新增至行動應用程式

Azure 通訊服務與 Azure 事件方格和 Azure 通知中樞整合，因此您可以將推播通知新增至 Azure 中的應用程式。

註冊/取消註冊通知中樞推推播通知

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

若要取得裝置註冊權杖，請將 Firebase SDK 新增至應用程式模組的 build.gradle 執行個體。若要從 Firebase 接收通知，請依照通訊服務通知中的指示整合 Azure 通知中樞。

Kotlin
Java

    val deviceRegistrationToken = "" // From Firebase
    callComposite.registerPushNotification(deviceRegistrationToken).whenComplete { _, throwable ->
        if (throwable != null) {
            // Handle error
        }
    }

    String deviceRegistrationToken = ""; // From Firebase
    callComposite.registerPushNotification(deviceRegistrationToken)
    .whenComplete((aVoid, throwable) -> {
            if (throwable != null) {
                // Handle error
            }
    });

處理從事件方格或通知中樞接收的推播通知

若要接收來電的推播通知，請在具有裝載的 CallComposite 執行個體上呼叫 handlePushNotification。

若要從 FCM 取得承載，請先建立可擴充 FirebaseMessagingService Firebase SDK 類別及覆寫 onMessageReceived 方法的新服務 ([檔案]>[新增]>[服務]>[服務])。此方法是在 FCM 將推播通知傳遞至應用程式時呼叫的事件處理常式。

Kotlin
Java

    // On Firebase onMessageReceived
    val pushNotification = CallCompositePushNotification(remoteMessage.data)
    callComposite.handlePushNotification(pushNotification).whenComplete { _, throwable ->
        if (throwable != null) {
            // Handle error
        }
    }

    // On Firebase onMessageReceived
    // push notification contains from/to communication identifiers and event type
    CallCompositePushNotification pushNotification = 
            new CallCompositePushNotification(remoteMessage.data)

    callComposite.handlePushNotification(pushNotification)
    .whenComplete((aVoid, throwable) -> {
            if (throwable != null) {
                // Handle error
            }
    });

註冊來電通知

若要在 handlePushNotification 之後接收來電通知，請訂閱 CallCompositeIncomingCallEvent 和 CallCompositeIncomingCallCancelledEvent。 CallCompositeIncomingCallEvent 包含來電 callId 和來電者資訊。 CallCompositeIncomingCallCancelledEvent 包含 callId 和通話取消碼，Azure 通訊服務中的疑難排解。

Kotlin
Java

    private var incomingCallEvent: IncomingCallEvent? = null
    private var incomingCallCancelledEvent: IncomingCallCancelledEvent? = null

    class IncomingCallEvent : CallCompositeEventHandler<CallCompositeIncomingCallEvent> {
        override fun handle(eventArgs: CallCompositeIncomingCallEvent?) {
            // Display incoming call UI to accept/decline a call
            // CallCompositeIncomingCallEvent contains call id and caller information
        }
    }

    class IncomingCallCancelledEvent : CallCompositeEventHandler<CallCompositeIncomingCallCancelledEvent> {
        override fun handle(eventArgs: CallCompositeIncomingCallCancelledEvent?) {
            // Call-ended event when a call is declined or not accepted
        }
    }

    // Event subscription
    incomingCallEvent = IncomingCallEvent()
    callComposite.addOnIncomingCallEventHandler(incomingCallEvent)

    incomingCallCancelledEvent = IncomingCallCancelledEvent()
    callComposite.addOnIncomingCallCancelledEventHandler(incomingCallEndEvent)

    // Event unsubscribe
    callComposite.removeOnIncomingCallEventHandler(incomingCallEvent)
    callComposite.removeOnIncomingCallCancelledEventHandler(incomingCallEndEvent)

    callComposite.addOnIncomingCallEventHandler((call) -> {
        // Display incoming call UI to accept/decline a call
        // incomingCallEvent.getCallId()
        // incomingCallEvent.getCallerIdentifier()
        // incomingCallEvent.getCallerDisplayName()
    });

    callComposite.addOnIncomingCallCancelledEventHandler((call) -> {
        // Call-ended event when a call is declined or not accepted
        // incomingCallCancelledEvent.getCallId()
        // incomingCallCancelledEvent.getCode()
        // incomingCallCancelledEvent.getSubCode()
    });

處理通話

若要接受通話，請呼叫 accept。若要拒絕通話，請呼叫 reject。

Kotlin
Java

// Accept call
callComposite.accept(applicationContext, incomingCallId, localOptions)

// Decline call
callComposite.reject(incomingCallId)

// Accept call
callComposite.accept(applicationContext, incomingCallId, localOptions);

// Decline call
callComposite.reject(incomingCallId);

向其他參與者撥號

若要開始與其他參與者通話，請從 CommunicationIdentity 和 launch 使用參與者的原始識別碼建立 CallCompositeStartCallOptions。

Kotlin
Java

    val participants: List<CommunicationIdentifier> // participants to dial
    callComposite.launch(context, participants, localOptions)

    Collection<CommunicationIdentifier> participants; // participants to dial
    callComposite.launch(applicationContext, participants, localOptions);

如需詳細資訊，請參閱開放原始碼 iOS UI 程式庫和範例應用程式程式碼。

設定推播通知

行動推播通知是您在行動裝置中取得的快顯通知。本文重點是透過電腦音訊 (VoIP) 推播通知。

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

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

將來電通知新增至行動應用程式

Azure 通訊服務與 Azure 事件方格和 Azure 通知中樞整合，因此您可以將推播通知新增至 Azure 中的應用程式。

註冊/取消註冊通知中樞推播通知

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

    // to register
    let deviceToken: Data = pushRegistry?.pushToken(for: PKPushType.voIP)
    callComposite.registerPushNotifications(
        deviceRegistrationToken: deviceToken) { result in
        switch result {
            case .success:
                // success
            case .failure(let error):
                // failure
        }
    }

    // to unregister
    callComposite.unregisterPushNotification()

處理從事件方格或通知中樞接收的推播通知

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

當您使用 handlePushNotification() 和 CallKit 選項時，您會收到 CallKit 通知以接受或拒絕通話。

    // App is in the background
    // push notification contains from/to communication identifiers and event type
    let pushNotification = PushNotification(data: payload.dictionaryPayload)
    let callKitOptions = CallKitOptions(...//CallKit options)
    CallComposite.reportIncomingCall(pushNotification: pushNotification,
                                    callKitOptions: callKitOptions) { result in
        if case .success() = result {
            DispatchQueue.global().async {
                // You don't need to wait for a Communication Services token to handle the push because 
                // Communication Services common receives a callback function to get the token with refresh options
                // create call composite and handle push notification
                callComposite.handlePushNotification(pushNotification: pushNotification)
            }
        }
    }

    // App is in the foreground
    let pushNotification = PushNotification(data: dictionaryPayload)
    callComposite.handlePushNotification(pushNotification: pushNotification) { result in
        switch result {
            case .success:
                // success
            case .failure(let error):
                // failure
        }
    }

註冊處理推播的來電通知

若要在 handlePushNotification 之後接收來電通知，請訂閱 onIncomingCall 和 onIncomingCallCancelled。 IncomingCall 包含來電 callId 和來電者資訊。 IncomingCallCancelled 包含 callId 和通話取消碼，Azure 通訊服務中的疑難排解。

    let onIncomingCall: (IncomingCall) -> Void = { [] incomingCall in
        // Incoming call id and caller info
    }
    let onIncomingCallEnded: (IncomingCallCancelled) -> Void = { [] incomingCallCancelled in
        // Incoming call cancelled code with callId
    }
    callComposite.events.onIncomingCall = onIncomingCall
    callComposite.events.onIncomingCallEnded = onIncomingCallEnded

停用來電的內部推送

若要只從 EventGrid 和 APNS 接收推播通知，在 CallCompositeOptions 中將 disableInternalPushForIncomingCall 設定為 true。如果 disableInternalPushForIncomingCall 為 true，則只有在呼叫 handlePushNotification 時，才會收到來自 ui 程式庫的推播通知事件。選項 disableInternalPushForIncomingCall 有助於停止在前景模式中接收來自 CallComposite 的通知。此設定不會控制 EventGrid 和 NotificationHub 設定。

    let options = CallCompositeOptions(disableInternalPushForIncomingCall: true)

在從呼叫 SDK CallKit 接受的來電上啟動複合式呼叫

Azure 通訊服務通話 iOS SDK 支援 CallKit 整合。您可以藉由設定 CallCompositeCallKitOption 的執行個體，在 UI 程式庫中啟用此整合。如需詳細資訊，請參閱與 CallKit 整合。

如果已啟用來自呼叫 SDK 的 CallKit，請訂閱 onIncomingCallAcceptedFromCallKit。接受通話時，請使用通話識別碼啟動 callComposite。

    let onIncomingCallAcceptedFromCallKit: (callId) -> Void = { [] callId in
        // Incoming call accepted call id
    }
    
    callComposite.events.onIncomingCallAcceptedFromCallKit = onIncomingCallAcceptedFromCallKit

    // launch composite with/without local options
    // Note: as call is already accepted, setup screen will not be displayed
    callComposite.launch(callIdAcceptedFromCallKit: callId)

使用 CallComposite 處理呼叫

若要接受通話，請呼叫 accept。若要拒絕通話，請呼叫 reject。

// Accept call
callComposite.accept(incomingCallId, 
                     ... // CallKit and local options
                     )

// Decline call
callComposite.reject(incomingCallId)

向其他參與者撥號

若要與其他參與者開始通話，請啟動具有參與者 CommunicationIdentifier 清單的 callComposite。

    // [CommunicationIdentifier]
    // use createCommunicationIdentifier(fromRawId: "raw id")
    callComposite.launch(participants: <list of CommunicationIdentifier>,
                         localOptions: localOptions)

下一步

深入了解 UI 程式庫

共用方式為

在 UI 程式庫中設定一對一通話和推播通知

必要條件

設定功能

設定推播通知的權限

將來電通知新增至行動應用程式

註冊/取消註冊通知中樞推推播通知

處理從事件方格或通知中樞接收的推播通知

註冊來電通知

處理通話

向其他參與者撥號

設定推播通知

將來電通知新增至行動應用程式

註冊/取消註冊通知中樞推播通知

處理從事件方格或通知中樞接收的推播通知

註冊處理推播的來電通知

停用來電的內部推送

在從呼叫 SDK CallKit 接受的來電上啟動複合式呼叫

使用 CallComposite 處理呼叫

向其他參與者撥號

下一步

意見反應

其他資源