Inicio rápido: Agregar mensajería de canal de datos a la aplicación que realiza la llamada

Artículo
08/06/2024

La API de características del canal de datos permite la mensajería en tiempo real durante las llamadas de audio y vídeo. En esta guía de inicio rápido, se muestra cómo integrar la característica Canal de datos, lo que permite el intercambio de mensajes de texto entre los participantes dentro de una llamada grupal. Tenga en cuenta que hay muchas soluciones de mensajería distintas a la característica Canal de datos y debe elegir la solución adecuada para su escenario de uso específico.

Importante

Tenga en cuenta que nuestra implementación actual de la API de características de DataChannel no admite mensajería directa entre un explorador web y una aplicación nativa en un escenario de llamada punto a punto.

Creación de un objeto DataChannelSender

En primer lugar, debe crear un objeto DataChannelSender para enviar mensajes. En esta aplicación de mensajería personalizada, se recomienda asignar un número a channelId, que sirve para distinguir diferentes casos de uso de aplicaciones. Por ejemplo, puede asignar channelId 1000 para mensajes personalizados.

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

Hay otras opciones, como la confiabilidad, el ancho de banda y la prioridad. Puede omitirlos por ahora y usar los valores predeterminados. Mientras se crea el objeto emisor, todavía necesita un objeto receptor para recibir mensajes.

Registrar un agente de escucha para obtener el objeto DataChannelReceiver

Para adquirir un objeto receptor, debe registrar un agente de escucha que capture el evento dataChannelReceiverCreated. Cuando se crea un objeto receptor, el SDK emite el evento junto con el objeto receptor.

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

Dentro de la función de devolución de llamada del agente de escucha, puede acceder al objeto receptor y recuperar información como channelId y el identificador de participante del remitente senderParticipantIdentifier. Es su responsabilidad mantener la referencia del objeto receptor, ya que el SDK emite el evento una vez para cada objeto receptor creado.

Control del evento messageReady y cierre del objeto DataChannelReceiver

Cuando llega un mensaje, el objeto DataChannelReceiver recibe el mensaje, lo almacena en su búfer interno y emite un evento messageReady. No es necesario registrar el agente de escucha de eventos messageReady para recibir mensajes, ya que siempre puede llamar a la API readMessage en cualquier momento. Sin embargo, para el procedimiento recomendado, se recomienda leer el mensaje dentro de la devolución de llamada del agente de escucha messageReady, si el procesamiento de mensajes tarda mucho tiempo, puede descargar el trabajo en un trabajo web para evitar el bloqueo de la recepción de mensajes.

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

Configurar participantes

Para especificar los destinatarios de los mensajes, puede usar la API DataChannelSender.setParticipants. El objeto del remitente mantiene la lista de participantes más reciente que proporcione. El tipo de participante es CommunicationIdentifier, que puede obtener de remoteParticipant.identifier. Para obtener más información, consulte Acceso a las propiedades de los participantes remotos.

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

Tenga en cuenta que la lista de participantes está limitada a 64 participantes. Si la lista de participantes es una matriz vacía, el SDK difunde el mensaje a todos los participantes de la llamada.

Envío y recepción de mensajes

La API de características de DataChannel requiere que pase datos como tipo Uint8Array. No se puede enviar directamente una cadena de JavaScript mediante la API sendMessage. Por ejemplo, si desea enviar una cadena abc, no puede usar sender.sendMessage('abc'). En su lugar, primero debe serializar los datos en un búfer de bytes.

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

Este es otro ejemplo para enviar un objeto JSON.

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

Recibir y descodificar el mensaje

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

Puede encontrar un ejemplo completo en el siguiente vínculo: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Importante

Tenga en cuenta que la actual API de características de Data Channel no admite mensajería directa entre un explorador web y una aplicación nativa en un escenario de llamada punto a punto.

Información general

La API de características de Data Channel permite la mensajería de datos en tiempo real durante las llamadas de audio y vídeo. En esta guía de inicio rápido, se muestra cómo integrar la característica Data Channel en la llamada y usar las API de Data Channel para enviar y recibir mensajes de datos a través de un canal de datos.

Requisitos previos

Consulte el inicio rápido de llamadas de voz para configurar una aplicación de ejemplo con llamadas de voz.

Clases

NOMBRE	Descripción
DataChannelCallFeature	Se usa para iniciar y administrar la característica de canal de datos.
DataChannelSender	Se usa para administrar un canal de datos como remitente y enviar datos.
DataChannelReceiver	Se usa para administrar un canal de datos como receptor y recibir datos.
DataChannelSenderOptions	Se usa para representar opciones para crear un remitente del canal de datos.

Enumeraciones

Nombre	Descripción
DataChannelPriority	Describe las opciones de prioridad del canal de datos. Valores: { `NORMAL`, `HIGH` }.
DataChannelReliability	Describe las opciones de confiabilidad del canal de datos. Valores: { `LOSSY`, `DURABLE` }.

Código de error

Nombre	Descripción
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` puede producir un error con este código de error, lo que indica que el canal de datos subyacente no está listo para usarse.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` puede producir un error con este código de error, lo que indica que ya se han usado todos los id. de canal aleatorios disponibles.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` puede producir un error con este código de error, lo que indica que el remitente ya se ha cerrado anteriormente.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` puede producir un error con este código de error, lo que indica que el tamaño de los datos del mensaje supera el límite. Puede obtener el límite de tamaño del mensaje usando `getMaxMessageSizeInBytes()` en `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` puede producir un error con este código de error, lo que indica un error al enviar el mensaje debido a que no hay suficiente ancho de banda.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` puede producir un error con este código de error, lo que indica un error al enviar el mensaje debido al uso general del canal de datos que no cumple las reglas de límite de tráfico. Consulte el documento sobre el concepto del canal de datos para obtener más información sobre el límite de tráfico.

Métodos

Habilitación de la característica Data Channel

Obtenga el objeto de llamada en curso establecido durante los pasos de requisitos previos.
Obtenga el objeto de la característica Data Channel.

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

Recepción de un mensaje de datos

Defina 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 el receiverCreatedListener.

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

Defina 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 ReceiverClosedListener.

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

Registre messageReceivedListener y receiverClosedListener.

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

Envío de un mensaje de datos

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

Obtenga DataChannelSender y envíe el mensaje de datos

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

Tenga en cuenta que la actual API de características de Data Channel no admite mensajería directa entre un explorador web y una aplicación nativa en un escenario de llamada punto a punto.

Información general

Requisitos previos

Consulte el inicio rápido de llamadas de voz para configurar una aplicación de ejemplo con llamadas de voz.

Clases

NOMBRE	Descripción
DataChannelCallFeature	Se usa para iniciar y administrar la característica de canal de datos.
DataChannelSender	Se usa para administrar un canal de datos como remitente y enviar datos.
DataChannelReceiver	Se usa para administrar un canal de datos como receptor y recibir datos.
DataChannelSenderOptions	Se usa para representar opciones para crear un remitente del canal de datos.

Enumeraciones

Nombre	Descripción
DataChannelPriority	Describe las opciones de prioridad del canal de datos. Valores: { `normal`, `high` }.
DataChannelReliability	Describe las opciones de confiabilidad del canal de datos. Valores: { `lossy`, `durable` }.

Código de error

Nombre	Descripción
dataChannelFailedToStart	`getDataChannelSender()` puede producir un error con este código de error, lo que indica que el canal de datos subyacente no está listo para usarse.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` puede producir un error con este código de error, lo que indica que ya se han usado todos los id. de canal aleatorios disponibles.
dataChannelSenderClosed	`sendMessage()` puede producir un error con este código de error, lo que indica que el remitente ya se ha cerrado anteriormente.
dataChannelMessageSizeOverLimit	`sendMessage()` puede producir un error con este código de error, lo que indica que el tamaño de los datos del mensaje supera el límite. Puede obtener el límite de tamaño del mensaje usando `maxMessageSizeInBytes` en `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` puede producir un error con este código de error, lo que indica un error al enviar el mensaje debido a que no hay suficiente ancho de banda.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` puede producir un error con este código de error, lo que indica un error al enviar el mensaje debido al uso general del canal de datos que no cumple las reglas de límite de tráfico. Consulte el documento sobre el concepto del canal de datos para obtener más información sobre el límite de tráfico.

Métodos

Habilitación de la característica Data Channel

Obtenga el objeto de llamada en curso establecido durante los pasos de requisitos previos.
Obtenga el objeto de la característica Data Channel.

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

Recepción de un mensaje de datos

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

Envío de un mensaje de datos

Configure 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 DataChannelSender y envíe el mensaje de datos.

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

Tenga en cuenta que la actual API de características de Data Channel no admite mensajería directa entre un explorador web y una aplicación nativa en un escenario de llamada punto a punto.

Información general

Requisitos previos

Consulte el inicio rápido de llamadas de voz para configurar una aplicación de ejemplo con llamadas de voz.

Clases

NOMBRE	Descripción
DataChannelCallFeature	Se usa para iniciar y administrar la característica de canal de datos.
DataChannelSender	Se usa para administrar un canal de datos como remitente y enviar datos.
DataChannelReceiver	Se usa para administrar un canal de datos como receptor y recibir datos.
DataChannelSenderOptions	Se usa para representar opciones para crear un remitente del canal de datos.

Enumeraciones

Nombre	Descripción
DataChannelPriority	Describe las opciones de prioridad del canal de datos. Valores: { `Normal`, `High` }.
DataChannelReliability	Describe las opciones de confiabilidad del canal de datos. Valores: { `Lossy`, `Durable` }.

Código de error

Nombre	Descripción
DataChannelFailedToStart	`GetDataChannelSender()` puede producir un error con este código de error, lo que indica que el canal de datos subyacente no está listo para usarse.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` puede producir un error con este código de error, lo que indica que ya se han usado todos los id. de canal aleatorios disponibles.
DataChannelSenderClosed	`SendMessage()` puede producir un error con este código de error, lo que indica que el remitente ya se ha cerrado anteriormente.
DataChannelMessageSizeOverLimit	`SendMessage()` puede producir un error con este código de error, lo que indica que el tamaño de los datos del mensaje supera el límite. Puede obtener el límite de tamaño del mensaje usando `MaxMessageSizeInBytes` en `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` puede producir un error con este código de error, lo que indica un error al enviar el mensaje debido a que no hay suficiente ancho de banda.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` puede producir un error con este código de error, lo que indica un error al enviar el mensaje debido al uso general del canal de datos que no cumple las reglas de límite de tráfico. Consulte el documento sobre el concepto del canal de datos para obtener más información sobre el límite de tráfico.

Métodos

Habilitación de la característica Data Channel

Obtenga el objeto de llamada en curso establecido durante los pasos de requisitos previos.
Obtenga el objeto de la característica Data Channel.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Recepción de un mensaje de datos

Defina el controlador 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;
}

Adjunte DataChannelReceiverCreatedHandler.

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Defina el controlador 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 el controlador de eventos Closed.

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

Adjunte MessageReceivedHandler y ReceiverClosedHandler.

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

Envío de un mensaje de datos

Configure 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 DataChannelSender y envíe el mensaje de datos.

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

Pasos siguientes

Para más información, consulte los siguientes artículos.

Más información sobre el documento de concepto de características del canal de datos
Más información sobre las Funcionalidades del SDK de llamadas

Compartir a través de

Inicio rápido: Agregar mensajería de canal de datos a la aplicación que realiza la llamada

Creación de un objeto DataChannelSender

Registrar un agente de escucha para obtener el objeto DataChannelReceiver

Control del evento messageReady y cierre del objeto DataChannelReceiver

Configurar participantes

Envío y recepción de mensajes

Información general

Requisitos previos

Clases

Enumeraciones

Código de error

Métodos

Habilitación de la característica Data Channel

Recepción de un mensaje de datos

Envío de un mensaje de datos

Información general

Requisitos previos

Clases

Enumeraciones

Código de error

Métodos

Habilitación de la característica Data Channel

Recepción de un mensaje de datos

Envío de un mensaje de datos

Información general

Requisitos previos

Clases

Enumeraciones

Código de error

Métodos

Habilitación de la característica Data Channel

Recepción de un mensaje de datos

Envío de un mensaje de datos

Pasos siguientes

Comentarios

Recursos adicionales