快速入門：將資料通道傳訊功能新增至您的通話應用程式

發行項
08/08/2024

資料通道功能 API 可在語音和視訊通話期間支援即時傳訊。在本快速入門指南中，我們將說明如何整合資料通道功能，以便在群組通話時讓參與者可以交換文字簡訊。請注意，除了資料通道功能以外，還有許多不同的訊息解決方案，您應該選擇適合的解決方案來滿足特定使用案例的需求。

重要

請注意，我們目前實作的資料通道功能 API 不支援點對點通話案例中網頁瀏覽器與原生應用程式之間的直接傳訊。

建立 DataChannelSender 物件

首先，您必須先建立一個 DataChannelSender 物件來傳送訊息。在此自訂傳訊應用程式中，我們建議指派一個數字給 channelId，用來區分不同的應用程式使用案例。例如，若是自訂訊息，您可以 1000 給 channelId。

const dataChannel = call.feature(Features.DataChannel);
const messageSender = dataChannel.createDataChannelSender({
    channelId: 1000
});

還有幾個其他選項，例如可靠性、頻寬和優先順序。您現在可以忽略這些選項，並使用預設值。建立傳送者物件時，您仍然需要接收者物件來接收訊息。

註冊接聽程式以取得 DataChannelReceiver 物件

若要取得接收者物件，您必須註冊接聽程式以擷取 dataChannelReceiverCreated 事件。建立接收者物件時，SDK 會連同接收者物件一起發出事件。

dataChannel.on('dataChannelReceiverCreated', receiver => {
    // receiver.channelId
    // receiver.senderParticipantIdentifier, which shows the sender id
});

在接聽程式回撥函式中，您可以存取接收者物件，並擷取 channelId 和傳送者參與者的參與者識別碼 senderParticipantIdentifier 等資訊。您必須負責維護接收者物件參考，因為 SDK 會針對每個建立的接收者物件發出一次事件。

處理 DataChannelReceiver 的 messageReady 和 close 事件

當訊息送達時，DataChannelReceiver 物件會收到訊息、將其儲存在內部緩衝區中並發出 messageReady 事件。不需要註冊 messageReady 事件接聽程式來接收訊息，因為您一直都可以隨時呼叫 readMessage API。不過，為了獲得最佳做法，建議您在 messageReady 接聽程式回撥中讀取訊息，如果訊息處理需要很長的時間，您可以將工作卸載給 Web 背景工作角色，以防止封鎖訊息接收。

dataChannel.on('dataChannelReceiverCreated', receiver => {
    if (receiver.channelId === 1000) {
        receiver.on('close', () => {
            console.log(`data channel id = ${receiver.channelId} from ${JSON.stringify(receiver.senderParticipantIdentifier)} is closed`);
        });
        receiver.on('messageReady', () => {
            const message = receiver.readMessage();
            // process the message
        });
    }
});

設定參與者

若要指定訊息的收件者，您可以使用 DataChannelSender.setParticipants API。傳送者物件會維護您所提供的最新參與者清單。參與者類型是 CommunicationIdentifier，您可以從 remoteParticipant.identifier 中取得。如需詳細資訊，請參閱存取遠端參與者屬性。

const user = call.remoteParticipants[0]; // assume the user wants to send a message to the first participant in the remoteParticipants list
messageSender.setParticipants([user.identifier]);

請注意，參與者清單的參與者數目上限為 64 名。如果參與者清單是空陣列，SDK 會將訊息廣播給通話中的所有參與者。

傳送和接收訊息

資料通道功能 API 會要求您以 Uint8Array 類型傳遞資料。您無法使用 sendMessage API 直接傳送 JavaScript 字串。例如，如果您要傳送字串 abc，則無法使用 sender.sendMessage('abc')。而必須改為先在位元組緩衝區中序列化資料。

const data = (new TextEncoder()).encode('abc');
sender.sendMessage(data);

以下是另一個傳送 JSON 物件的範例。

const obj = {...}; // some object
const data = (new TextEncoder()).encode(JSON.stringify(obj));
sender.sendMessage(data);

接收和解碼訊息

dataChannel.on('dataChannelReceiverCreated', receiver => {
    if (receiver.channelId === 1000) {
        const textDecoder = new TextDecoder();
        receiver.on('close', () => {
            console.log(`data channel id = ${receiver.channelId} from ${JSON.stringify(receiver.senderParticipantIdentifier)} is closed`);
        });
        receiver.on('messageReady', () => {
            const message = receiver.readMessage();
            const text = textDecoder.decode(message.data);
            console.log(`from ${JSON.stringify(receiver.senderParticipantIdentifier)}:${text}`);
        });
    }
});

您可以使用下列連結取得完整的範例：https://github.com/Azure-Samples/communication-services-web-calling-tutorial

重要

請注意，目前的資料通道功能 API 不支援點對點通話案例中網頁瀏覽器與原生應用程式之間的直接傳訊。

概觀

資料通道功能 API 可在語音和視訊通話期間支援即時資料傳訊。在本快速入門指南中，我們將說明如何將資料通道功能整合到您的通話，並使用資料通道 API 透過資料通道傳送和接收資料訊息。

必要條件

請參閱語音通話快速入門，設定具有語音通話功能的範例應用程式。

類別

名稱	描述
DataChannelCallFeature	用來啟動和管理資料通道功能。
DataChannelSender	用來以傳送者身分管理資料通道和傳送資料。
DataChannelReceiver	用來以接收者身分管理資料通道和接收資料。
DataChannelSenderOptions	用於代表建立資料通道傳送者的選項。

列舉

名稱	描述
DataChannelPriority	描述資料通道的優先順序選項。值：{ `NORMAL`, `HIGH` }。
DataChannelReliability	描述資料通道的可靠性選項。值：{ `LOSSY`, `DURABLE` }。

錯誤碼

名稱	描述
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` 可能失敗並出現此錯誤碼，表示基礎資料通道尚未就緒，無法使用。
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` 可能失敗並出現此錯誤碼，表示所有可用的隨機通道識別碼都已在使用中。
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` 可能失敗並出現此錯誤碼，表示先前已關閉傳送者。
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` 可能失敗並出現此錯誤碼，表示訊息資料大小超過限制。您可以使用 `DataChannelSender` 中的 `getMaxMessageSizeInBytes()` 取得訊息大小限制。
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` 可能失敗並出現此錯誤碼，表示由於頻寬不足而導致傳送訊息失敗。
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` 可能失敗並出現此錯誤碼，表示由於資料通道的整體使用量不符合流量限制規則而導致傳送訊息失敗。如需流量限制的詳細資料，請參閱資料通道概念文件 (部分機器翻譯)。

方法

啟用資料通道功能

取得在執行必要條件步驟期間建立的持續呼叫物件。
取得資料通道功能物件。

DataChannelCallFeature dataChannelCallFeature = call.feature(Features.DATA_CHANNEL);

接收資料訊息

定義 DataChannelReceiverCreatedListener。

DataChannelReceiverCreatedListener receiverCreatedListener = new DataChannelReceiverCreatedListener() {
    @Override
    public void onReceiverCreated(DataChannelReceiverCreatedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the new data channel receiver
        int channelId = receiver.getChannelId(); // get the channel id
        CommunicationIdentifier senderId = receiver.getSenderIdentifier(); // get the message sender id
        // listen to the message received event and closed event from this receiver
        // receiver.addOnMessageReceivedListener(messageReceivedlistener);
        // receiver.addOnClosedListener(receiverClosedListener);
    }
};

註冊 receiverCreatedListener。

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

定義 MessageReceivedListener。

MessageReceivedListener messageReceivedListener = new MessageReceivedListener() {
    @Override
    public void onMessageReceived(PropertyChangedEvent e) {
        DataChannelMessage message = e.getReceiver().receiveMessage(); // read the data message from the receiver
        int sequence = message.getSequenceNumber(); // get the message sequence number
        byte[] data = message.getData(); // get the data content
    }
};

定義 ReceiverClosedListener。

ReceiverClosedListener receiverClosedListener = new ReceiverClosedListener() {
    @Override
    public void onReceiverClosed(PropertyChangedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the data channel receiver to be closed
    }
};

註冊 messageReceivedListener 和 receiverClosedListener。

receiver.addOnMessageReceivedListener(messageReceivedlistener);
receiver.addOnClosedListener(receiverClosedListener);

傳送資料訊息

設定 DataChannelSenderOptions。

DataChannelSenderOptions options = new DataChannelSenderOptions();
options.setChannelId(1000);
options.setBitrateInKbps(32);
options.setPriority(DataChannelPriority.NORMAL);
options.setReliability(DataChannelReliability.LOSSY);

List<CommunicationIdentifier> participants = Arrays.asList( /* identifier1, identifier2, ... */ );
options.setParticipants(participants);

取得 DataChannelSender 並傳送資料訊息

DataChannelSender dataChannelSender = dataChannelCallFeature.getDataChannelSender(options);

// msgData contains the byte[] data to be sent
dataChannelSender.sendMessage(msgData);

// change participants in the channel if needed
dataChannelSender.setParticipants(new ArrayList<CommunicationIdentifier>());

重要

請注意，目前的資料通道功能 API 不支援點對點通話案例中網頁瀏覽器與原生應用程式之間的直接傳訊。

概觀

必要條件

請參閱語音通話快速入門，設定具有語音通話功能的範例應用程式。

類別

名稱	描述
DataChannelCallFeature	用來啟動和管理資料通道功能。
DataChannelSender	用來以傳送者身分管理資料通道和傳送資料。
DataChannelReceiver	用來以接收者身分管理資料通道和接收資料。
DataChannelSenderOptions	用於代表建立資料通道傳送者的選項。

列舉

名稱	描述
DataChannelPriority	描述資料通道的優先順序選項。值：{ `normal`, `high` }。
DataChannelReliability	描述資料通道的可靠性選項。值：{ `lossy`, `durable` }。

錯誤碼

名稱	描述
dataChannelFailedToStart	`getDataChannelSender()` 可能失敗並出現此錯誤碼，表示基礎資料通道尚未就緒，無法使用。
dataChannelRandomIdNotAvailable	`getDataChannelSender()` 可能失敗並出現此錯誤碼，表示所有可用的隨機通道識別碼都已在使用中。
dataChannelSenderClosed	`sendMessage()` 可能失敗並出現此錯誤碼，表示先前已關閉傳送者。
dataChannelMessageSizeOverLimit	`sendMessage()` 可能失敗並出現此錯誤碼，表示訊息資料大小超過限制。您可以使用 `DataChannelSender` 中的 `maxMessageSizeInBytes` 取得訊息大小限制。
dataChannelMessageFailureForBandwidth	`sendMessage()` 可能失敗並出現此錯誤碼，表示由於頻寬不足而導致傳送訊息失敗。
dataChannelMessageFailureForTrafficLimit	`sendMessage()` 可能失敗並出現此錯誤碼，表示由於資料通道的整體使用量不符合流量限制規則而導致傳送訊息失敗。如需流量限制的詳細資料，請參閱資料通道概念文件 (部分機器翻譯)。

方法

啟用資料通道功能

取得在執行必要條件步驟期間建立的持續呼叫物件。
取得資料通道功能物件。

var dataChannelCallFeature = self.call!.feature(Features.dataChannel)

接收資料訊息

let featureDelegate = new FeatureDelegate()
let receiverDelegate = new ReceiverDelegate()
dataChannelCallFeature!.delegate = featureDelegate

class FeatureDelegate: NSObject, DataChannelCallFeatureDelegate {
    public func dataChannelCallFeature(_ dataChannelCallFeature: DataChannelCallFeature, didCreateReceiver args: DataChannelReceiverCreatedEventArgs) {
        let receiver = args.receiver // get the new data channel receiver
        let channelId = receiver.channelId // get the channel id
        let senderId = receiver.senderIdentifier // get the message sender id

        receiver.delegate = receiverDelegate
    }
}

class ReceiverDelegate: NSObject, DataChannelReceiverDelegate {
    public func dataChannelReceiver(_ dataChannelReceiver: DataChannelReceiver, didReceiveMessage args: PropertyChangedEventArgs) {
        let message = dataChannelReceiver.receiveMessage() // read the data message from the receiver
        let sequence = message?.sequenceNumber // get the message sequence number
        let data = message?.data // get the data content
    }
    
    public func dataChannelReceiver(_ dataChannelReceiver: DataChannelReceiver, didClose args: PropertyChangedEventArgs) {
       let channelId = dataChannelReceiver.channelId // get the data channel id to be closed
    }
}

傳送資料訊息

設定 DataChannelSenderOptions。

let options = new DataChannelSenderOptions()
options.channelId = 1000
options.bitrateInKbps = 32
options.priority = DataChannelPriority.normal
options.reliability = DataChannelReliability.lossy

let communicationIdentifiers: [CommunicationIdentifier] = [ /* identifier1, identifier2, ... */ ]
options.participants = communicationIdentifiers

定義 DataChannelSender 和傳送資料訊息

DataChannelSender sender = dataChannelCallFeature.getDataChannelSender(options)

// msgData contains the data to be sent
sender.sendMessage(msgData)

// change participants in the channel if needed
let participants: [CommunicationIdentifier] = []
dataChannelSender.setParticipants(participants: participants)

重要

請注意，目前的資料通道功能 API 不支援點對點通話案例中網頁瀏覽器與原生應用程式之間的直接傳訊。

概觀

必要條件

請參閱語音通話快速入門，設定具有語音通話功能的範例應用程式。

類別

名稱	描述
DataChannelCallFeature	用來啟動和管理資料通道功能。
DataChannelSender	用來以傳送者身分管理資料通道和傳送資料。
DataChannelReceiver	用來以接收者身分管理資料通道和接收資料。
DataChannelSenderOptions	用於代表建立資料通道傳送者的選項。

列舉

名稱	描述
DataChannelPriority	描述資料通道的優先順序選項。值：{ `Normal`, `High` }。
DataChannelReliability	描述資料通道的可靠性選項。值：{ `Lossy`, `Durable` }。

錯誤碼

名稱	描述
DataChannelFailedToStart	`GetDataChannelSender()` 可能失敗並出現此錯誤碼，表示基礎資料通道尚未就緒，無法使用。
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` 可能失敗並出現此錯誤碼，表示所有可用的隨機通道識別碼都已在使用中。
DataChannelSenderClosed	`SendMessage()` 可能失敗並出現此錯誤碼，表示先前已關閉傳送者。
DataChannelMessageSizeOverLimit	`SendMessage()` 可能失敗並出現此錯誤碼，表示訊息資料大小超過限制。您可以使用 `DataChannelSender` 中的 `MaxMessageSizeInBytes` 取得訊息大小限制。
DataChannelMessageFailureForBandwidth	`SendMessage()` 可能失敗並出現此錯誤碼，表示由於頻寬不足而導致傳送訊息失敗。
DataChannelMessageFailureForTrafficLimit	`SendMessage()` 可能失敗並出現此錯誤碼，表示由於資料通道的整體使用量不符合流量限制規則而導致傳送訊息失敗。如需流量限制的詳細資料，請參閱資料通道概念文件 (部分機器翻譯)。

方法

啟用資料通道功能

取得在執行必要條件步驟期間建立的持續呼叫物件。
取得資料通道功能物件。

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

接收資料訊息

定義 DataChannelReceiverCreated 事件處理常式。

void DataChannelReceiverCreatedHandler(object sender, DataChannelReceiverCreatedEventArgs args) 
{
    DataChannelReceiver receiver = args.Receiver; // get the new data channel receiver
    int channelId = receiver.ChannelId; // get the channel id
    CallIdentifier senderId = receiver.SenderIdentifier; // get the message sender id
    
    // add event handlers for the message received event and closed event from this receiver
    // receiver.MessageReceived += MessageReceivedHandler;
    // receiver.Closed += ReceiverClosedHandler;
}

附加 DataChannelReceiverCreatedHandler。

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

定義 MessageReceived 事件處理常式。

void MessageReceivedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelMessage message = (sender as DataChannelReceiver).ReceiveMessage(); // read the data message from the receiver
    long sequence = message.SequenceNumber; // get the message sequence number
    byte[] data = message.Data; // get the data content
}

定義 Closed 事件處理常式。

void ReceiverClosedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelReceiver receiver = sender as DataChannelReceiver; // get the data channel receiver to be closed
};

附加 MessageReceivedHandler 和 ReceiverClosedHandler。

receiver.MessageReceived += MessageReceivedHandler;
receiver.Closed += ReceiverClosedHandler;

傳送資料訊息

設定 DataChannelSenderOptions。

DataChannelSenderOptions options = new DataChannelSenderOptions();
options.ChannelId = 1000;
options.BitrateInKbps = 32;
options.Priority = DataChannelPriority.Normal;
options.Reliability = DataChannelReliability.Lossy;
var participants = new List<CallIdentifier> { /* identifier1, identifier2, ... */ };
options.Participants = participants.AsReadOnly();

定義 DataChannelSender 和傳送資料訊息

DataChannelSender sender = dataChannelCallFeature.GetDataChannelSender(options);
// msgData contains the byte[] data to be sent
sender.SendMessage(msgData);
// change participants in the channel if needed
sender.SetParticipants(new List<CallIdentifier>().AsReadOnly());

下一步

如需詳細資訊，請參閱下列文章：

了解資料通道功能概念文件
深入了解通話 SDK 功能

共用方式為

快速入門：將資料通道傳訊功能新增至您的通話應用程式

建立 DataChannelSender 物件

註冊接聽程式以取得 DataChannelReceiver 物件

處理 DataChannelReceiver 的 messageReady 和 close 事件

設定參與者

傳送和接收訊息

概觀

必要條件

類別

列舉

錯誤碼

方法

啟用資料通道功能

接收資料訊息

傳送資料訊息

概觀

必要條件

類別

列舉

錯誤碼

方法

啟用資料通道功能

接收資料訊息

傳送資料訊息

概觀

必要條件

類別

列舉

錯誤碼

方法

啟用資料通道功能

接收資料訊息

傳送資料訊息

下一步

意見反應

其他資源