Início rápido: adicionar mensagens do Canal de Dados ao seu aplicativo de chamada

Artigo
08/06/2024

A API do recurso Canal de Dados permite o envio de mensagens em tempo real durante chamadas de áudio e vídeo. Neste guia de início rápido, ilustraremos como integrar o recurso Canal de Dados, permitindo a troca de mensagens de texto entre os participantes em uma chamada de grupo. Observe que há muitas soluções de mensagens diferentes do recurso do Canal de dados, e você deve escolher a solução adequada para seu cenário de uso específico.

Importante

Lembre-se de que nossa implementação atual da API do recurso DataChannel não dá suporte a mensagens diretas entre um navegador da Web e um aplicativo nativo em um cenário de chamada ponto a ponto.

Criar um objeto DataChannelSender

Primeiro, você precisa criar um objeto DataChannelSender para enviar mensagens. Neste aplicativo de mensagens personalizadas, sugerimos atribuir um número a channelId, que serve para distinguir diferentes casos de uso do aplicativo. Por exemplo, você pode atribuir channelId 1000 para mensagens personalizadas.

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

Há várias outras opções, como confiabilidade, largura de banda e prioridade. Você pode ignorá-las por enquanto e usar os valores padrão. Enquanto o objeto remetente é criado, você ainda precisa de um objeto receptor para receber mensagens.

Registrar um ouvinte para obter o objeto DataChannelReceiver

Para adquirir um objeto receptor, você precisa registrar um ouvinte que capture o evento dataChannelReceiverCreated. Quando um objeto receptor é criado, o SDK emite o evento junto com o objeto receptor.

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

Dentro da função de retorno de chamada do ouvinte, você pode acessar o objeto receptor e recuperar informações como channelId e a ID do participante do remetente senderParticipantIdentifier. É sua responsabilidade manter a referência de objeto do receptor, pois o SDK emite o evento uma vez para cada objeto receptor criado.

Manipular messageReady e fechar evento do objeto DataChannelReceiver

Quando uma mensagem chega, o objeto DataChannelReceiver recebe a mensagem, armazena-a em seu buffer interno e emite um evento messageReady. Não é necessário registrar o ouvinte de eventos messageReady para receber mensagens, pois você sempre pode chamar a API readMessage a qualquer momento. No entanto, como melhor prática, recomendamos ler a mensagem dentro do retorno de chamada do ouvinte messageReady; se o processamento de mensagens levar muito tempo, você poderá descarregar o trabalho para uma função de trabalho para evitar o bloqueio da recepção da mensagem.

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

Definir participantes

Para especificar os destinatários para suas mensagens, você pode usar a API DataChannelSender.setParticipants. O objeto remetente mantém a lista de participantes mais recente que você fornece. O tipo de participante é CommunicationIdentifier, que você pode obter de remoteParticipant.identifier. Para obter mais informações, confira Acessar propriedades de participante remoto.

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

Observe que a lista de participantes é limitada a 64 participantes. Se a lista de participantes for uma matriz vazia, o SDK transmitirá a mensagem para todos os participantes na chamada.

Enviar e receber mensagens

A API do recurso DataChannel exige que você passe dados como tipo Uint8Array. Você não pode enviar diretamente uma cadeia de caracteres JavaScript usando a API sendMessage. Por exemplo, se você quiser enviar uma cadeia de caracteres abc, não poderá usar sender.sendMessage('abc'). Em vez disso, você precisa serializar os dados em um buffer de bytes primeiro.

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

Aqui está outro exemplo para enviar um objeto JSON.

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

Receber e decodificar a mensagem

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}`);
        });
    }
});

Você pode encontrar um exemplo completo no seguinte link: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Importante

Lembre-se de que a API atual do recurso Canal de Dados não dá suporte a mensagens diretas entre um navegador da Web e um aplicativo nativo em um cenário de chamada ponto a ponto.

Visão geral

A API do recurso Canal de Dados permite o envio de mensagens de dados em tempo real durante chamadas de áudio e vídeo. Neste guia de início rápido, ilustramos como integrar o recurso Canal de Dados à sua chamada e usar as APIs do Canal de Dados para enviar e receber mensagens de dados por meio de um canal de dados.

Pré-requisitos

Consulte o guia de Início Rápido de Chamada de Voz para configurar um aplicativo de exemplo com chamada de voz.

Classes

Nome	Descrição
DataChannelCallFeature	Usado para iniciar e gerenciar o recurso de canal de dados.
DataChannelSender	Usado para gerenciar um canal de dados como remetente e enviar dados.
DataChannelReceiver	Usado para gerenciar um canal de dados como receptor e receber dados.
DataChannelSenderOptions	Usado para representar opções para criar um remetente de canal de dados.

Enumerações

Nome	Descrição
DataChannelPriority	Descreve as opções de prioridade do canal de dados. Valores: { `NORMAL`, `HIGH` }.
DataChannelReliability	Descreve as opções de confiabilidade do canal de dados. Valores: { `LOSSY`, `DURABLE` }.

Código de erro

Nome	Descrição
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` pode falhar com este código de erro, indicando que o Canal de Dados subjacente não está pronto para ser usado.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` pode falhar com este código de erro, indicando que todas as IDs de canal aleatório disponíveis já foram usadas.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` pode falhar com este código de erro, indicando que o remetente já foi fechado anteriormente.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` pode falhar com este código de erro, indicando que o tamanho dos dados da mensagem excede o limite. Você pode obter o limite de tamanho da mensagem usando `getMaxMessageSizeInBytes()` em `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` pode falhar com este código de erro, indicando uma falha no envio da mensagem devido à largura de banda ser insuficiente.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` pode falhar com este código de erro, indicando uma falha no envio da mensagem devido ao uso geral do Canal de Dados não estar em conformidade com as regras de limite de tráfego. Confira o Documento de conceito do canal de dados para obter detalhes do limite de tráfego.

Métodos

Habilitar o recurso Canal de Dados

Obtenha o objeto de chamada em andamento estabelecido durante as etapas de pré-requisito.
Obter o objeto Recurso do Canal de Dados.

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

Mensagem de recebimento de dados

Defina o 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);
    }
};

Registrar o receiverCreatedListener.

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

Defina o 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
    }
};

Defina o ReceiverClosedListener.

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

Registre o messageReceivedListener e o receiverClosedListener .

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

Enviando mensagem de dados

Configure o 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);

Obter o DataChannelSender e enviar mensagem de dados

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

Importante

Lembre-se de que a API atual do recurso Canal de Dados não dá suporte a mensagens diretas entre um navegador da Web e um aplicativo nativo em um cenário de chamada ponto a ponto.

Visão geral

Pré-requisitos

Consulte o guia de Início Rápido de Chamada de Voz para configurar um aplicativo de exemplo com chamada de voz.

Classes

Nome	Descrição
DataChannelCallFeature	Usado para iniciar e gerenciar o recurso de canal de dados.
DataChannelSender	Usado para gerenciar um canal de dados como remetente e enviar dados.
DataChannelReceiver	Usado para gerenciar um canal de dados como receptor e receber dados.
DataChannelSenderOptions	Usado para representar opções para criar um remetente de canal de dados.

Enumerações

Nome	Descrição
DataChannelPriority	Descreve as opções de prioridade do canal de dados. Valores: { `normal`, `high` }.
DataChannelReliability	Descreve as opções de confiabilidade do canal de dados. Valores: { `lossy`, `durable` }.

Código de erro

Nome	Descrição
dataChannelFailedToStart	`getDataChannelSender()` pode falhar com este código de erro, indicando que o Canal de Dados subjacente não está pronto para ser usado.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` pode falhar com este código de erro, indicando que todas as IDs de canal aleatório disponíveis já foram usadas.
dataChannelSenderClosed	`sendMessage()` pode falhar com este código de erro, indicando que o remetente já foi fechado anteriormente.
dataChannelMessageSizeOverLimit	`sendMessage()` pode falhar com este código de erro, indicando que o tamanho dos dados da mensagem excede o limite. Você pode obter o limite de tamanho da mensagem usando `maxMessageSizeInBytes` em `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` pode falhar com este código de erro, indicando uma falha no envio da mensagem devido à largura de banda insuficiente.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` pode falhar com este código de erro, indicando uma falha no envio da mensagem devido ao uso geral do Canal de Dados não estar em conformidade com as regras de limite de tráfego. Confira o Documento de conceito do canal de dados para obter detalhes do limite de tráfego.

Métodos

Habilitar o recurso Canal de Dados

Obtenha o objeto de chamada em andamento estabelecido durante as etapas de pré-requisito.
Obter o objeto Recurso do Canal de Dados.

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

Mensagem de recebimento de dados

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
    }
}

Enviando mensagem de dados

Configure o 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

Defina o DataChannelSender e envie mensagem de dados

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)

Importante

Lembre-se de que a API atual do recurso Canal de Dados não dá suporte a mensagens diretas entre um navegador da Web e um aplicativo nativo em um cenário de chamada ponto a ponto.

Visão geral

Pré-requisitos

Consulte o guia de Início Rápido de Chamada de Voz para configurar um aplicativo de exemplo com chamada de voz.

Classes

Nome	Descrição
DataChannelCallFeature	Usado para iniciar e gerenciar o recurso de canal de dados.
DataChannelSender	Usado para gerenciar um canal de dados como remetente e enviar dados.
DataChannelReceiver	Usado para gerenciar um canal de dados como receptor e receber dados.
DataChannelSenderOptions	Usado para representar opções para criar um remetente de canal de dados.

Enumerações

Nome	Descrição
DataChannelPriority	Descreve as opções de prioridade do canal de dados. Valores: { `Normal`, `High` }.
DataChannelReliability	Descreve as opções de confiabilidade do canal de dados. Valores: { `Lossy`, `Durable` }.

Código de erro

Nome	Descrição
DataChannelFailedToStart	`GetDataChannelSender()` pode falhar com este código de erro, indicando que o Canal de Dados subjacente não está pronto para ser usado.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` pode falhar com este código de erro, indicando que todas as IDs de canal aleatório disponíveis já foram usadas.
DataChannelSenderClosed	`SendMessage()` pode falhar com este código de erro, indicando que o remetente já foi fechado anteriormente.
DataChannelMessageSizeOverLimit	`SendMessage()` pode falhar com este código de erro, indicando que o tamanho dos dados da mensagem excede o limite. Você pode obter o limite de tamanho da mensagem usando `MaxMessageSizeInBytes` em `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` pode falhar com este código de erro, indicando uma falha no envio da mensagem devido à largura de banda insuficiente.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` pode falhar com este código de erro, indicando uma falha no envio da mensagem devido ao uso geral do Canal de Dados não estar em conformidade com as regras de limite de tráfego. Confira o Documento de conceito do canal de dados para obter detalhes do limite de tráfego.

Métodos

Habilitar o recurso Canal de Dados

Obtenha o objeto de chamada em andamento estabelecido durante as etapas de pré-requisito.
Obter o objeto Recurso do Canal de Dados.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Mensagem de recebimento de dados

Definir o manipulador de eventos 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;
}

Anexe o DataChannelReceiverCreatedHandler.

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Defina o manipulador de eventos 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
}

Defina o manipulador de eventos Fechado.

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

Anexe o MessageReceivedHandler e o ReceiverClosedHandler.

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

Enviando mensagem de dados

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

Defina o DataChannelSender e envie mensagem de dados

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

Próximas etapas

Para obter mais informações, consulte os seguintes artigos:

Saiba mais sobre o documento de conceito de recurso do Canal de Dados
Saiba mais sobre os recursos do SDK de Chamada

Compartilhar via

Início rápido: adicionar mensagens do Canal de Dados ao seu aplicativo de chamada

Criar um objeto DataChannelSender

Registrar um ouvinte para obter o objeto DataChannelReceiver

Manipular messageReady e fechar evento do objeto DataChannelReceiver

Definir participantes

Enviar e receber mensagens

Visão geral

Pré-requisitos

Classes

Enumerações

Código de erro

Métodos

Habilitar o recurso Canal de Dados

Mensagem de recebimento de dados

Enviando mensagem de dados

Visão geral

Pré-requisitos

Classes

Enumerações

Código de erro

Métodos

Habilitar o recurso Canal de Dados

Mensagem de recebimento de dados

Enviando mensagem de dados

Visão geral

Pré-requisitos

Classes

Enumerações

Código de erro

Métodos

Habilitar o recurso Canal de Dados

Mensagem de recebimento de dados

Enviando mensagem de dados

Próximas etapas

Comentários

Recursos adicionais