빠른 시작: 통화 앱에 데이터 채널 메시징 추가

아티클
08/08/2024

데이터 채널 기능 API를 사용하면 오디오 및 영상 통화 중에 실시간 메시지를 사용할 수 있습니다. 이 빠른 시작 가이드에서는 데이터 채널 기능을 통합하여 그룹 통화 내의 참가자 간에 문자 메시지 교환을 사용하도록 설정하는 방법을 설명합니다. 데이터 채널 기능 외에도 다양한 메시징 솔루션이 있으므로 특정 사용 시나리오에 적합한 솔루션을 선택해야 합니다.

Important

DataChannel 기능 API의 현재 구현은 피어 투 피어 호출 시나리오에서 웹 브라우저와 네이티브 앱 간의 직접 메시징을 지원하지 않습니다.

DataChannelSender 개체 만들기

먼저 메시지를 보낼 DataChannelSender 개체를 만들어야 합니다. 이 사용자 지정 메시징 애플리케이션에서는 다양한 애플리케이션 사용 사례를 구분하는 역할을 하는 channelId에 번호를 할당하는 것이 좋습니다. 예를 들어 사용자 지정 메시지에 channelId 1000을 할당할 수 있습니다.

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

안정성, 대역폭 및 우선 순위와 같은 몇 가지 다른 옵션이 있습니다. 지금은 이를 무시하고 기본값을 사용할 수 있습니다. 발신자 개체를 만드는 동안 메시지를 수신하려면 수신자 개체가 필요합니다.

수신기를 등록하여 DataChannelReceiver 개체 가져오기

수신자 개체를 획득하려면 dataChannelReceiverCreated 이벤트를 캡처하는 수신기를 등록해야 합니다. 수신자 개체를 만들 때 SDK는 수신자 개체와 함께 이벤트를 내보냅니다.

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

수신기 콜백 함수 내에서 수신자 개체에 액세스하고 channelId 및 발신자 참가자 ID senderParticipantIdentifier와 같은 정보를 검색할 수 있습니다. SDK가 만든 각 수신자 개체에 대해 이벤트를 한 번 내보내기 때문에 수신자 개체 참조를 유지 관리하는 것은 사용자의 책임입니다.

DataChannelReceiver 개체의 messageReady 및 close 이벤트 처리

메시지가 도착하면 DataChannelReceiver 개체가 메시지를 수신하고, 내부 버퍼에 저장하고, messageReady 이벤트를 내보냅니다. 언제든지 readMessage API를 호출할 수 있으므로 messageReady 이벤트 수신기를 등록하여 메시지를 받을 필요는 없습니다. 그러나 모범 사례의 경우 messageReady 수신기 콜백 내에서 메시지를 읽는 것이 좋습니다. 메시지 처리에 시간이 오래 걸리는 경우 웹 작업자에 작업을 오프로드하여 메시지 수신이 차단되는 것을 방지할 수 있습니다.

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는 통화의 모든 참가자에게 메시지를 브로드캐스트합니다.

메시지 보내기 및 받기

DataChannel 기능 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 링크에서 전체 샘플을 찾을 수 있습니다.

Important

현재 데이터 채널 기능 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()`는 이 오류 코드로 인해 실패할 수 있으며, 이는 사용 가능한 모든 임의 채널 ID가 이미 사용되었음을 나타냅니다.
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>());

Important

현재 데이터 채널 기능 API는 피어 투 피어 호출 시나리오에서 웹 브라우저와 네이티브 앱 간의 직접 메시징을 지원하지 않습니다.

개요

필수 조건

음성 통화 빠른 시작을 참조하여 음성 통화가 포함된 샘플 앱을 설정합니다.

클래스

이름	설명
DataChannelCallFeature	데이터 채널 기능을 시작하고 관리하는 데 사용됩니다.
DataChannelSender	송신자로 데이터 채널을 관리하고 데이터를 보내는 데 사용됩니다.
DataChannelReceiver	데이터 채널을 수신자로 관리하고 데이터를 수신하는 데 사용됩니다.
DataChannelSenderOptions	데이터 채널 발신자를 만드는 옵션을 나타내는 데 사용됩니다.

열거형

이름	설명
DataChannelPriority	데이터 채널의 우선 순위 옵션을 설명합니다. 값: { `normal`, `high` }.
DataChannelReliability	데이터 채널의 안정성 옵션을 설명합니다. 값: { `lossy`, `durable` }.

오류 코드

속성	설명
dataChannelFailedToStart	`getDataChannelSender()`는 이 오류 코드로 인해 실패할 수 있으며, 이는 기본 데이터 채널을 사용할 준비가 되지 않았음을 나타냅니다.
dataChannelRandomIdNotAvailable	`getDataChannelSender()`는 이 오류 코드로 인해 실패할 수 있으며, 이는 사용 가능한 모든 임의 채널 ID가 이미 사용되었음을 나타냅니다.
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)

Important

현재 데이터 채널 기능 API는 피어 투 피어 호출 시나리오에서 웹 브라우저와 네이티브 앱 간의 직접 메시징을 지원하지 않습니다.

개요

필수 조건

음성 통화 빠른 시작을 참조하여 음성 통화가 포함된 샘플 앱을 설정합니다.

클래스

이름	설명
DataChannelCallFeature	데이터 채널 기능을 시작하고 관리하는 데 사용됩니다.
DataChannelSender	송신자로 데이터 채널을 관리하고 데이터를 보내는 데 사용됩니다.
DataChannelReceiver	데이터 채널을 수신자로 관리하고 데이터를 수신하는 데 사용됩니다.
DataChannelSenderOptions	데이터 채널 발신자를 만드는 옵션을 나타내는 데 사용됩니다.

열거형

이름	설명
DataChannelPriority	데이터 채널의 우선 순위 옵션을 설명합니다. 값: { `Normal`, `High` }.
DataChannelReliability	데이터 채널의 안정성 옵션을 설명합니다. 값: { `Lossy`, `Durable` }.

오류 코드

속성	설명
DataChannelFailedToStart	`GetDataChannelSender()`는 이 오류 코드로 인해 실패할 수 있으며, 이는 기본 데이터 채널을 사용할 준비가 되지 않았음을 나타냅니다.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()`는 이 오류 코드로 인해 실패할 수 있으며, 이는 사용 가능한 모든 임의 채널 ID가 이미 사용되었음을 나타냅니다.
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 이벤트 처리

참가자 설정

메시지 보내기 및 받기

개요

필수 조건

클래스

열거형

오류 코드

메서드

데이터 채널 기능 사용

데이터 메시지 받기

데이터 메시지 보내기

개요

필수 조건

클래스

열거형

오류 코드

메서드

데이터 채널 기능 사용

데이터 메시지 받기

데이터 메시지 보내기

개요

필수 조건

클래스

열거형

오류 코드

메서드

데이터 채널 기능 사용

데이터 메시지 받기

데이터 메시지 보내기

다음 단계

피드백

추가 리소스