Démarrage rapide : Ajouter la messagerie du canal de données à votre application d’appel

Article
08/06/2024

L’API de fonctionnalité du canal de données active la messagerie en temps réel pendant les appels audio et vidéo. Dans ce guide de démarrage rapide, nous allons montrer le processus d’intégration de la fonctionnalité Chaîne de données, permettant l’échange de SMS entre les participants à un appel de groupe. Notez qu’il existe de nombreuses solutions de messagerie autres que la fonctionnalité Canal de données. Vous devez choisir celle qui convient à votre scénario d’usage spécifique.

Important

N’oubliez pas que notre implémentation actuelle de l’API de la fonctionnalité DataChannel ne prend pas en charge la messagerie directe entre un navigateur web et une application native dans un scénario d’appel d’égal à égal.

Créer un objet DataChannelSender

Vous devez au préalable créer un objet DataChannelSender pour envoyer des messages. Dans cette application de messagerie personnalisée, nous vous suggérons d’attribuer un nombre à channelId, afin de distinguer les différents cas d’usage de l’application. Par exemple, vous pouvez attribuer à channelId le nombre 1 000 pour les messages personnalisés.

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

Il existe plusieurs autres options, comme la fiabilité, la bande passante et la priorité. Pour l’instant, vous pouvez les ignorer et utiliser les valeurs par défaut. Pendant la création de l’objet expéditeur, vous avez toujours besoin d’un objet récepteur pour recevoir des messages.

Inscrire un écouteur afin d’obtenir l’objet DataChannelReceiver

Pour acquérir un objet récepteur, vous devez inscrire un écouteur qui capture l’événement dataChannelReceiverCreated. Lorsqu’un objet récepteur est créé, le kit de développement logiciel (SDK) génère l’événement en même temps que l’objet récepteur.

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

Dans la fonction rappel de l’écouteur, vous pouvez accéder à l’objet récepteur et récupérer des informations telles que channelId et l’ID senderParticipantIdentifier l’expéditeur participant. La gestion de la référence d’objet récepteur est de votre responsabilité, car le kit de développement logiciel (SDK) génère l’événement une fois pour chaque objet récepteur créé.

Gérer messageReady et fermer l’événement pour l’objet DataChannelReceiver

Lorsqu’un message arrive, l’objet DataChannelReceiver le reçoit, le stocke dans sa mémoire tampon interne et génère un événement messageReady. Il n’est pas nécessaire d’inscrire l’écouteur d’événements messageReady pour recevoir des messages, car vous pouvez toujours appeler l’API readMessage à tout moment. Pour une bonne pratique, nous vous recommandons toutefois de lire le message dans le rappel de l’écouteur messageReady. Si le traitement des messages prend beaucoup de temps, vous pouvez décharger le travail vers un rôle de travail pour empêcher le blocage de la réception du message.

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

Définir les participants

Pour renseigner les destinataires de vos messages, vous pouvez utiliser l’API DataChannelSender.setParticipants. L’objet expéditeur gère la liste des participants la plus récente que vous fournissez. Le type de participant est CommunicationIdentifier et vous pouvez l’obtenir à partir de remoteParticipant.identifier. Pour plus d’informations, consultez Accéder aux propriétés des participants distants.

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

Notez que la liste des participants est limitée à 64. Si la liste des participants est un tableau vide, le kit de développement logiciel (SDK) diffuse le message à tous les participants à l’appel.

Envoyer et recevoir des messages

L’API de fonctionnalité DataChannel nécessite que vous transmettiez des données en tant que type Uint8Array. Vous ne pouvez pas directement envoyer une chaîne JavaScript à l’aide de l’API sendMessage. Si vous souhaitez par exemple envoyer une chaîne abc, vous ne pouvez pas utiliser sender.sendMessage('abc'). Vous devez plutôt d’abord sérialiser les données dans une mémoire tampon en octets.

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

Voici un autre exemple de l’envoi d’un objet JSON.

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

Recevoir et décoder le message

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

Vous pouvez trouver un exemple complet au travers du lien suivant : https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Important

Veuillez noter que l’API de la fonctionnalité Data Channel actuelle ne prend pas en charge la messagerie directe entre un navigateur web et une application native dans un scénario d’appel d’homologue à homologue.

Vue d’ensemble

L’API de la fonctionnalité Data Channel active la messagerie de données en temps réel pendant les appels audio et vidéo. Dans ce guide de démarrage rapide, nous vous expliquons comment intégrer la fonctionnalité Data Channel à votre appel et comment utiliser les API Data Channel pour envoyer et recevoir des messages de données via un canal de données.

Prérequis

Reportez-vous au Guide de démarrage rapide des appels vocaux pour configurer un exemple d’application avec les appels vocaux.

Classes

Nom	Description
DataChannelCallFeature	Permet de démarrer, puis de gérer la fonctionnalité de canal de données.
DataChannelSender	Permet de gérer un canal de données en tant qu’expéditeur et d’envoyer des données.
DataChannelReceiver	Permet de gérer un canal de données en tant que récepteur et recevoir des données.
DataChannelSenderOptions	Permet de représenter les options de création d’un expéditeur de canal de données.

Énumérations

Nom	Description
DataChannelPriority	Décrit les options de priorité du canal de données. Valeurs : { `NORMAL`, `HIGH` }.
DataChannelReliability	Décrit les options de fiabilité du canal de données. Valeurs : { `LOSSY`, `DURABLE` }.

Code d’erreur

Nom	Description
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` peut échouer avec ce code d’erreur, indiquant que le canal de données sous-jacent n’est pas prêt à être utilisé.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` peut échouer avec ce code d’erreur, indiquant que tous les ID de canal aléatoires disponibles ont déjà été utilisés.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` peut échouer avec ce code d’erreur, indiquant que l’expéditeur a déjà été fermé.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` peut échouer avec ce code d’erreur, indiquant que la taille des données du message dépasse la limite. Vous pouvez obtenir la limite de taille des messages à l’aide de `getMaxMessageSizeInBytes()` dans `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` peut échouer avec ce code d’erreur, indiquant un échec d’envoi du message en raison d’une bande passante insuffisante.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` peut échouer avec ce code d’erreur, indiquant un échec d’envoi du message en raison de l’utilisation globale du canal de données non conforme aux règles de limite de trafic. Pour plus d’informations sur la limite du trafic, reportez-vous au document sur le concept de canal de données.

Méthodes

Activer la fonctionnalité Data Channel

Récupérez l’objet d’appel en cours établi au cours des étapes prérequises.
Obtenez l’objet Data Channel Feature.

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

Réception d’un message de données

Définissez l’écouteur 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);
    }
};

Enregistrer receiverCreatedListener.

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

Définissez 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
    }
};

Définissez ReceiverClosedListener.

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

Inscrivez les éléments messageReceivedListener et receiverClosedListener.

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

Envoi d’un message de données

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

Obtenir DataChannelSender et envoyer un message de données

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

Vue d’ensemble

Prérequis

Reportez-vous au Guide de démarrage rapide des appels vocaux pour configurer un exemple d’application avec les appels vocaux.

Classes

Nom	Description
DataChannelCallFeature	Permet de démarrer, puis de gérer la fonctionnalité de canal de données.
DataChannelSender	Permet de gérer un canal de données en tant qu’expéditeur et d’envoyer des données.
DataChannelReceiver	Permet de gérer un canal de données en tant que récepteur et recevoir des données.
DataChannelSenderOptions	Permet de représenter les options de création d’un expéditeur de canal de données.

Énumérations

Nom	Description
DataChannelPriority	Décrit les options de priorité du canal de données. Valeurs : { `normal`, `high` }.
DataChannelReliability	Décrit les options de fiabilité du canal de données. Valeurs : { `lossy`, `durable` }.

Code d’erreur

Nom	Description
dataChannelFailedToStart	`getDataChannelSender()` peut échouer avec ce code d’erreur, indiquant que le canal de données sous-jacent n’est pas prêt à être utilisé.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` peut échouer avec ce code d’erreur, indiquant que tous les ID de canal aléatoires disponibles ont déjà été utilisés.
dataChannelSenderClosed	`sendMessage()` peut échouer avec ce code d’erreur, indiquant que l’expéditeur a déjà été fermé.
dataChannelMessageSizeOverLimit	`sendMessage()` peut échouer avec ce code d’erreur, indiquant que la taille des données du message dépasse la limite. Vous pouvez obtenir la limite de taille des messages à l’aide de `maxMessageSizeInBytes` dans `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` peut échouer avec ce code d’erreur, indiquant un échec d’envoi du message en raison d’une bande passante insuffisante.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` peut échouer avec ce code d’erreur, indiquant un échec d’envoi du message en raison de l’utilisation globale du canal de données non conforme aux règles de limite de trafic. Pour plus d’informations sur la limite du trafic, reportez-vous au document sur le concept de canal de données.

Méthodes

Activer la fonctionnalité Data Channel

Récupérez l’objet d’appel en cours établi au cours des étapes prérequises.
Obtenez l’objet Data Channel Feature.

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

Réception d’un message de données

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

Envoi d’un message de données

Configurez 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

Définir l’expéditeur DataChannelSender, puis envoyer un message de données

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

Vue d’ensemble

Prérequis

Reportez-vous au Guide de démarrage rapide des appels vocaux pour configurer un exemple d’application avec les appels vocaux.

Classes

Nom	Description
DataChannelCallFeature	Permet de démarrer, puis de gérer la fonctionnalité de canal de données.
DataChannelSender	Permet de gérer un canal de données en tant qu’expéditeur et d’envoyer des données.
DataChannelReceiver	Permet de gérer un canal de données en tant que récepteur et recevoir des données.
DataChannelSenderOptions	Permet de représenter les options de création d’un expéditeur de canal de données.

Énumérations

Nom	Description
DataChannelPriority	Décrit les options de priorité du canal de données. Valeurs : { `Normal`, `High` }.
DataChannelReliability	Décrit les options de fiabilité du canal de données. Valeurs : { `Lossy`, `Durable` }.

Code d’erreur

Nom	Description
DataChannelFailedToStart	`GetDataChannelSender()` peut échouer avec ce code d’erreur, indiquant que le canal de données sous-jacent n’est pas prêt à être utilisé.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` peut échouer avec ce code d’erreur, indiquant que tous les ID de canal aléatoires disponibles ont déjà été utilisés.
DataChannelSenderClosed	`SendMessage()` peut échouer avec ce code d’erreur, indiquant que l’expéditeur a déjà été fermé.
DataChannelMessageSizeOverLimit	`SendMessage()` peut échouer avec ce code d’erreur, indiquant que la taille des données du message dépasse la limite. Vous pouvez obtenir la limite de taille des messages à l’aide de `MaxMessageSizeInBytes` dans `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` peut échouer avec ce code d’erreur, indiquant un échec d’envoi du message en raison d’une bande passante insuffisante.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` peut échouer avec ce code d’erreur, indiquant un échec d’envoi du message en raison de l’utilisation globale du canal de données non conforme aux règles de limite de trafic. Pour plus d’informations sur la limite du trafic, reportez-vous au document sur le concept de canal de données.

Méthodes

Activer la fonctionnalité Data Channel

Récupérez l’objet d’appel en cours établi au cours des étapes prérequises.
Obtenez l’objet Data Channel Feature.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Réception d’un message de données

Définissez le gestionnaire d’événements 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;
}

Attachez DataChannelReceiverCreatedHandler.

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Définissez le gestionnaire d’événements 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
}

Définissez le gestionnaire d’événements Closed.

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

Attachez les éléments MessageReceivedHandler et ReceiverClosedHandler.

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

Envoi d’un message de données

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

Définir l’expéditeur DataChannelSender, puis envoyer un message de données

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

Étapes suivantes

Pour plus d’informations, consultez les articles suivants :

En savoir plus sur le document concernant les concepts de fonctionnalité de la chaîne de données
En savoir plus sur les fonctionnalités du kit de développement logiciel (SDK) d’appel

Partage via

Démarrage rapide : Ajouter la messagerie du canal de données à votre application d’appel

Créer un objet DataChannelSender

Inscrire un écouteur afin d’obtenir l’objet DataChannelReceiver

Gérer messageReady et fermer l’événement pour l’objet DataChannelReceiver

Définir les participants

Envoyer et recevoir des messages

Vue d’ensemble

Prérequis

Classes

Énumérations

Code d’erreur

Méthodes

Activer la fonctionnalité Data Channel

Réception d’un message de données

Envoi d’un message de données

Vue d’ensemble

Prérequis

Classes

Énumérations

Code d’erreur

Méthodes

Activer la fonctionnalité Data Channel

Réception d’un message de données

Envoi d’un message de données

Vue d’ensemble

Prérequis

Classes

Énumérations

Code d’erreur

Méthodes

Activer la fonctionnalité Data Channel

Réception d’un message de données

Envoi d’un message de données

Étapes suivantes

Commentaires

Ressources supplémentaires