Guida introduttiva: Aggiungere la messaggistica del canale dati all'app chiamante

Articolo
08/14/2024

L'API della funzionalità Canale dati consente la messaggistica in tempo reale durante le chiamate audio e video. In questa guida introduttiva verrà illustrato come integrare la funzionalità Canale dati, abilitando lo scambio di messaggi di testo tra i partecipanti all'interno di una chiamata di gruppo. Si noti che esistono molte soluzioni di messaggistica diverse rispetto alla funzionalità Canale dati ed è consigliabile scegliere la soluzione adatta per lo scenario di utilizzo specifico.

Importante

Tenere presente che l'implementazione corrente dell'API della funzionalità Canale dati corrente non supporta la messaggistica diretta tra un Web browser e un'app nativa in uno scenario di chiamata peer-to-peer.

Creare un oggetto DataChannelSender

Prima di tutto è necessario creare un oggetto DataChannelSender per inviare messaggi. In questa applicazione di messaggistica personalizzata è consigliabile assegnare un numero a channelId, che serve a distinguere diversi casi d'uso dell'applicazione. Ad esempio, è possibile assegnare channelId 1000 per i messaggi personalizzati.

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

Sono disponibili diverse altre opzioni, ad esempio affidabilità, larghezza di banda e priorità. È possibile ignorarli per il momento e usare i valori predefiniti. Durante la creazione dell'oggetto mittente, è comunque necessario un oggetto ricevitore per ricevere messaggi.

Registrare un listener per ottenere l'oggetto DataChannelReceiver

Per acquisire un oggetto ricevitore, è necessario registrare un listener che acquisisca l'evento dataChannelReceiverCreated. Quando viene creato un oggetto ricevitore, l'SDK genera l'evento insieme all'oggetto ricevitore.

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

All'interno della funzione di callback del listener è possibile accedere all'oggetto ricevitore e recuperare informazioni quali channelId e l'ID partecipante del mittente senderParticipantIdentifier. È responsabilità dell'utente mantenere il riferimento all'oggetto ricevitore, perché l'SDK genera l'evento una volta per ogni oggetto ricevitore creato.

Gestire messageReady e chiudere l'evento dell'oggetto DataChannelReceiver

Quando arriva un messaggio, l'oggetto DataChannelReceiver riceve il messaggio, lo archivia nel buffer interno e genera un evento messageReady. Non è necessario registrare il listener di eventi messageReady per ricevere messaggi, perché è sempre possibile chiamare l'API readMessage in qualsiasi momento. Tuttavia, per la procedura consigliata, è consigliabile leggere il messaggio all'interno del callback del listener messageReady. Se l'elaborazione dei messaggi richiede molto tempo, è possibile eseguire l'offload del lavoro a un ruolo di lavoro per impedire il blocco della ricezione dei messaggi.

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

Impostare i partecipanti

Per specificare i destinatari per i messaggi, è possibile usare l'API DataChannelSender.setParticipants. L'oggetto mittente mantiene l'elenco dei partecipanti più recente specificato. Il tipo di partecipante è CommunicationIdentifier, che è possibile ottenere da remoteParticipant.identifier. Per altre informazioni, vedere le proprietà del partecipante remoto di Access.

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

Si noti che l'elenco dei partecipanti è limitato a 64 partecipanti. Se l'elenco dei partecipanti è una matrice vuota, l'SDK trasmette il messaggio a tutti i partecipanti nella chiamata.

Inviare e ricevere messaggi

L'API della funzionalità DataChannel richiede di passare i dati come tipo Uint8Array. Non è possibile inviare direttamente una stringa JavaScript usando l'API sendMessage. Ad esempio, se si vuole inviare una stringa abc, non è possibile usare sender.sendMessage('abc'). È invece necessario serializzare prima i dati in un buffer di byte.

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

Ecco un altro esempio per l'invio di un oggetto JSON.

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

Ricevere e decodificare il messaggio

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

Per un esempio completo, vedere il collegamento seguente: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Importante

Tenere presente che l'API della funzionalità Canale dati corrente non supporta la messaggistica diretta tra un Web browser e un'app nativa in uno scenario di chiamata peer-to-peer.

Panoramica

L'API della funzionalità Canale dati consente la messaggistica dei dati in tempo reale durante le chiamate audio e video. In questa guida introduttiva viene illustrato come integrare la funzionalità Canale dati alla chiamata e usare le API Canale dati per inviare e ricevere messaggi di dati tramite un canale dati.

Prerequisiti

Per configurare un'app di esempio con chiamate vocali, vedere la Guida introduttiva alle chiamate vocali.

Classi

Nome	Descrizione
DataChannelCallFeature	Usata per avviare e gestire la funzionalità del canale dati.
DataChannelSender	Usata per gestire un canale dati come mittente e inviare dati.
DataChannelReceiver	Usata per gestire un canale dati come ricevitore e ricevere dati.
DataChannelSenderOptions	Usata per rappresentare le opzioni per creare un mittente del canale dati.

Enumerazioni

Nome	Descrizione
DataChannelPriority	Descrive le opzioni di priorità del canale dati. Valori: { `NORMAL`, `HIGH` }.
DataChannelReliability	Descrive le opzioni di affidabilità del canale dati. Valori: { `LOSSY`, `DURABLE` }.

Codice di errore

Nome	Descrizione
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` può non riuscire con questo codice di errore, a indicare che il canale dati sottostante non è pronto per l'uso.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` può non riuscire con questo codice di errore, a indicare che sono già stati usati tutti gli ID canale casuali disponibili.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` può non riuscire con questo codice di errore, a indicare che il mittente è già stato chiuso in precedenza.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` può non riuscire con questo codice di errore, a indicare che le dimensioni dei dati del messaggio superano il limite. È possibile ottenere il limite di dimensioni dei messaggi usando `getMaxMessageSizeInBytes()` in `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` può non riuscire con questo codice di errore, a indicare un errore durante l'invio del messaggio a causa di una larghezza di banda insufficiente.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` può non riuscire con questo codice di errore, a indicare un errore durante l'invio del messaggio a causa dell'utilizzo complessivo del canale dati non conforme alle regole del limite di traffico. Per informazioni dettagliate sul limite di traffico, vedere il Documento di concetto su Canale dati.

Metodi

Abilitare la funzionalità Canale dati

Stabilire l'oggetto di chiamata in corso durante i passaggi dei prerequisiti.
Ottenere l'oggetto Funzionalità Canale dati.

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

Ricezione del messaggio di dati

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

Registrare receiverCreatedListener.

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

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

Definire ReceiverClosedListener.

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

Registrare messageReceivedListener e receiverClosedListener.

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

Invio del messaggio di dati

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

Ottenere DataChannelSender e inviare un messaggio di dati

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

Tenere presente che l'API della funzionalità Canale dati corrente non supporta la messaggistica diretta tra un Web browser e un'app nativa in uno scenario di chiamata peer-to-peer.

Panoramica

Prerequisiti

Per configurare un'app di esempio con chiamate vocali, vedere la Guida introduttiva alle chiamate vocali.

Classi

Nome	Descrizione
DataChannelCallFeature	Usata per avviare e gestire la funzionalità del canale dati.
DataChannelSender	Usata per gestire un canale dati come mittente e inviare dati.
DataChannelReceiver	Usata per gestire un canale dati come ricevitore e ricevere dati.
DataChannelSenderOptions	Usata per rappresentare le opzioni per creare un mittente del canale dati.

Enumerazioni

Nome	Descrizione
DataChannelPriority	Descrive le opzioni di priorità del canale dati. Valori: { `normal`, `high` }.
DataChannelReliability	Descrive le opzioni di affidabilità del canale dati. Valori: { `lossy`, `durable` }.

Codice di errore

Nome	Descrizione
dataChannelFailedToStart	`getDataChannelSender()` può non riuscire con questo codice di errore, a indicare che il canale dati sottostante non è pronto per l'uso.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` può non riuscire con questo codice di errore, a indicare che sono già stati usati tutti gli ID canale casuali disponibili.
dataChannelSenderClosed	`sendMessage()` può non riuscire con questo codice di errore, a indicare che il mittente è già stato chiuso in precedenza.
dataChannelMessageSizeOverLimit	`sendMessage()` può non riuscire con questo codice di errore, a indicare che le dimensioni dei dati del messaggio superano il limite. È possibile ottenere il limite di dimensioni dei messaggi usando `maxMessageSizeInBytes` in `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` può non riuscire con questo codice di errore, a indicare un errore durante l'invio del messaggio a causa di una larghezza di banda insufficiente.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` può non riuscire con questo codice di errore, a indicare un errore durante l'invio del messaggio a causa dell'utilizzo complessivo del canale dati non conforme alle regole del limite di traffico. Per informazioni dettagliate sul limite di traffico, vedere il Documento di concetto su Canale dati.

Metodi

Abilitare la funzionalità Canale dati

Stabilire l'oggetto di chiamata in corso durante i passaggi dei prerequisiti.
Ottenere l'oggetto Funzionalità Canale dati.

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

Ricezione del messaggio di dati

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

Invio del messaggio di dati

Configurare 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

Definire DataChannelSender e inviare un messaggio di dati

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

Tenere presente che l'API della funzionalità Canale dati corrente non supporta la messaggistica diretta tra un Web browser e un'app nativa in uno scenario di chiamata peer-to-peer.

Panoramica

Prerequisiti

Per configurare un'app di esempio con chiamate vocali, vedere la Guida introduttiva alle chiamate vocali.

Classi

Nome	Descrizione
DataChannelCallFeature	Usata per avviare e gestire la funzionalità del canale dati.
DataChannelSender	Usata per gestire un canale dati come mittente e inviare dati.
DataChannelReceiver	Usata per gestire un canale dati come ricevitore e ricevere dati.
DataChannelSenderOptions	Usata per rappresentare le opzioni per creare un mittente del canale dati.

Enumerazioni

Nome	Descrizione
DataChannelPriority	Descrive le opzioni di priorità del canale dati. Valori: { `Normal`, `High` }.
DataChannelReliability	Descrive le opzioni di affidabilità del canale dati. Valori: { `Lossy`, `Durable` }.

Codice di errore

Nome	Descrizione
DataChannelFailedToStart	`GetDataChannelSender()` può non riuscire con questo codice di errore, a indicare che il canale dati sottostante non è pronto per l'uso.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` può non riuscire con questo codice di errore, a indicare che sono già stati usati tutti gli ID canale casuali disponibili.
DataChannelSenderClosed	`SendMessage()` può non riuscire con questo codice di errore, a indicare che il mittente è già stato chiuso in precedenza.
DataChannelMessageSizeOverLimit	`SendMessage()` può non riuscire con questo codice di errore, a indicare che le dimensioni dei dati del messaggio superano il limite. È possibile ottenere il limite di dimensioni dei messaggi usando `MaxMessageSizeInBytes` in `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` può non riuscire con questo codice di errore, a indicare un errore durante l'invio del messaggio a causa di una larghezza di banda insufficiente.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` può non riuscire con questo codice di errore, a indicare un errore durante l'invio del messaggio a causa dell'utilizzo complessivo del canale dati non conforme alle regole del limite di traffico. Per informazioni dettagliate sul limite di traffico, vedere il Documento di concetto su Canale dati.

Metodi

Abilitare la funzionalità Canale dati

Stabilire l'oggetto di chiamata in corso durante i passaggi dei prerequisiti.
Ottenere l'oggetto Funzionalità Canale dati.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Ricezione del messaggio di dati

Definire il gestore eventi 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;
}

Allegare DataChannelReceiverCreatedHandler.

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Definire il gestore eventi 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
}

Definire il gestore eventi Chiuso.

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

Allegare MessageReceivedHandler e ReceiverClosedHandler.

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

Invio del messaggio di dati

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

Definire DataChannelSender e inviare un messaggio di dati

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

Passaggi successivi

Per altre informazioni, vedere gli articoli seguenti:

Informazioni sulla Documentazione del concetto di funzionalità del canale dati
Altre informazioni sulle funzionalità di Calling SDK

Condividi tramite

Guida introduttiva: Aggiungere la messaggistica del canale dati all'app chiamante

Creare un oggetto DataChannelSender

Registrare un listener per ottenere l'oggetto DataChannelReceiver

Gestire messageReady e chiudere l'evento dell'oggetto DataChannelReceiver

Impostare i partecipanti

Inviare e ricevere messaggi

Panoramica

Prerequisiti

Classi

Enumerazioni

Codice di errore

Metodi

Abilitare la funzionalità Canale dati

Ricezione del messaggio di dati

Invio del messaggio di dati

Panoramica

Prerequisiti

Classi

Enumerazioni

Codice di errore

Metodi

Abilitare la funzionalità Canale dati

Ricezione del messaggio di dati

Invio del messaggio di dati

Panoramica

Prerequisiti

Classi

Enumerazioni

Codice di errore

Metodi

Abilitare la funzionalità Canale dati

Ricezione del messaggio di dati

Invio del messaggio di dati

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive