Condividi tramite

Gestire le chiamate

Questo articolo descrive come gestire le chiamate usando l'SDK per chiamate di Servizi di comunicazione di Azure. Gli argomenti includono come effettuare chiamate, gestire i partecipanti e gestire le proprietà.

Prerequisiti

Supporto tecnico

Le tabelle seguenti definiscono il supporto nelle stanze di lavoro di gruppo nei Servizi di comunicazione di Azure.

Identità e tipi di chiamata

Nella tabella seguente viene illustrato il supporto delle funzionalità per un tipo di chiamata e un'identità specifici.

Identità Riunione di Teams Stanza Chiamata 1:1 Chiamata di gruppo Chiamata di interoperabilità di Teams 1:1 Chiamata di interoperabilità di Teams di gruppo
Utente di Servizi di comunicazione ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Utente di Microsoft 365 ✔️ ✔️ ✔️

Operazioni

La tabella seguente illustra il supporto per le singole API nell'SDK chiamante correlato ai singoli tipi di identità.

Operazioni Utente di Servizi di comunicazione Utente di Microsoft 365
Avviare una chiamata all'utente di Servizi di comunicazione ✔️
Avviare una chiamata all'utente di Microsoft 365 ✔️ ✔️
Avviare una chiamata al numero di telefono ✔️ ✔️
Accedi a una sala ✔️
Partecipare a una riunione di Teams ✔️ ✔️
Partecipare a una chiamata in base a groupId ✔️
Accettare o rifiutare la chiamata in ingresso ✔️ ✔️
Mettere in attesa e riprendere una chiamata ✔️ ✔️
Ottenere i partecipanti ✔️ ✔️
Aggiungere l'utente di Servizi di comunicazione ✔️
Rimuovere l'utente di Servizi di comunicazione ✔️ ✔️
Aggiungere o rimuovere l'utente di Microsoft 365 ✔️ ✔️
Aggiungere o rimuovere il numero di telefono ✔️ ✔️
Interrompere o ripristinare l'audio del partecipante remoto ✔️ [1] ✔️ [1]
Interrompere una chiamata ✔️ ✔️
Terminare la chiamata per tutti ✔️ [2] ✔️

[1] L'API è supportata solo nelle chiamate di gruppo, nelle sale e nelle riunioni di Teams. [2] L'API non è supportata nelle sale.

SDK

Le tabelle seguenti illustrano il supporto per le funzionalità nei singoli SDK Servizi di comunicazione di Azure.

Stato del supporto Rete Internet Interfaccia utente Web Ios Interfaccia utente iOS Androide Interfaccia utente Android Finestre
È supportato ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Installazione dell'SDK

Usare il comando npm install per installare l'SDK dei Servizi di comunicazione comuni e di chiamata di Azure per la piattaforma JavaScript.

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

Inizializzare gli oggetti necessari

Per la maggior parte delle operazioni di chiamata è necessaria un'istanza di CallClient. Quando si crea una nuova istanza di CallClient, è possibile configurarla con opzioni personalizzate come un'istanza di Logger.

Con l'istanza di CallClient è possibile creare un'istanza di CallAgent chiamando il createCallAgent. Questo metodo restituisce in modo asincrono un oggetto istanza CallAgent.

Il metodo createCallAgent usa CommunicationTokenCredential come argomento. Accetta un token di accesso utente.

È possibile usare il metodo getDeviceManager nell'istanza di CallClient per accedere a deviceManager.

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Gestire la connettività dell'SDK all'infrastruttura Microsoft

L'istanza Call Agent consente di gestire le chiamate (per partecipare o avviare le chiamate). Per lavorare con l'SDK per chiamate, è necessario connettersi all'infrastruttura Microsoft per ricevere notifiche delle chiamate in arrivo e coordinare altri dettagli delle chiamate. Call Agent ha due possibili stati:

Connesso : un valore connectionStatue Call Agent di Connected indica che l'SDK client è connesso e in grado di ricevere notifiche dall'infrastruttura Microsoft.

Disconnesso : un valore connectionStatue Call Agent di Disconnected indica un problema che impedisce all'SDK di connettersi correttamente. Call Agent deve essere ricreato.

  • invalidToken: se un token è scaduto o non è valido l'istanza Call Agent si disconnette con questo errore.
  • connectionIssue: se si verifica un problema con il client che si connette all'infrastruttura Microsoft, dopo molti tentativi Call Agent espone l'errore connectionIssue .

È possibile verificare se l'infrastruttura locale Call Agent è connessa all'infrastruttura Microsoft controllando il valore corrente della proprietà connectionState. Durante una chiamata attiva è possibile restare in ascolto dell'evento connectionStateChanged per determinare se Call Agent cambia dallo stato Connesso a Disconnesso.

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

Effettua una chiamata

Per creare e avviare una chiamata, usare una delle API in callAgent e fornire un utente creato tramite il SDK Identità di Servizi di comunicazione.

La creazione e l'avvio di chiamate sono sincroni. L'istanza call consente di sottoscrivere a eventi di chiamata.

Effettuare una chiamata 1:n a un utente o a un PSTN

Per chiamare un altro utente di Servizi di comunicazione, usare il metodo startCall su callAgent e passare il CommunicationUserIdentifier del destinatario creato con la libreria di amministrazione di Servizi di comunicazione.

Per una chiamata 1:1 a un utente, usare il codice seguente:

const userCallee = { communicationUserId: '<ACS_USER_ID>' }
const oneToOneCall = callAgent.startCall([userCallee]);

Per effettuare una chiamata a una rete Public Switched Telephone Network (PSTN), usare il metodo startCall su callAgent e passare il PhoneNumberIdentifier del destinatario. La risorsa di Servizi di comunicazione deve essere configurata per consentire chiamate PSTN.

Quando si chiama un numero PSTN, specificare il proprio ID chiamante alternativo. Un ID chiamante alternativo è un numero di telefono (basato sullo standard E.164) che identifica il chiamante in una chiamata PSTN. È il numero di telefono che il destinatario della chiamata vedrà per una chiamata in arrivo.

Nota

Vedere i dettagli dell'offerta di chiamate PSTN. Per l'accesso in anteprima al programma, iscriversi al programma early adopter.

Per una chiamata 1:1 a un numero PSTN, usare il codice seguente:

const pstnCallee = { phoneNumber: '<ACS_USER_ID>' }
const alternateCallerId = {phoneNumber: '<ALTERNATE_CALLER_ID>'};
const oneToOneCall = callAgent.startCall([pstnCallee], { alternateCallerId });

Per una chiamata 1:n a un utente e un numero PSTN, usare il codice seguente:

const userCallee = { communicationUserId: '<ACS_USER_ID>' }
const pstnCallee = { phoneNumber: '<PHONE_NUMBER>'};
const alternateCallerId = {phoneNumber: '<ALTERNATE_CALLER_ID>'};
const groupCall = callAgent.startCall([userCallee, pstnCallee], { alternateCallerId });

Partecipare a una videochiamata nella stanza

Per partecipare a una chiamata room, è possibile creare un'istanza di un oggetto contesto con la proprietà roomId come identificatore room. Per partecipare alla chiamata, usare il metodo join e passare l'istanza di contesto.

const context = { roomId: '<RoomId>' }
const call = callAgent.join(context);

room consente agli sviluppatori di applicazioni di avere maggiore controllo su chi possa unirsi a una chiamata, quando si incontrino e come collaborino. Per altre informazioni sulle sale, vedere API Rooms per riunioni strutturate e Partecipare a una chiamata in sala.

Partecipare a una chiamata di gruppo

Nota

Il groupId parametro è metadati di sistema, usato da Microsoft per le operazioni necessarie per eseguire il sistema. Non includere dati personali nel valore groupId. Microsoft non considera questo parametro come dati personali e il relativo contenuto potrebbe essere visibile a dipendenti Microsoft o essere archiviato a lungo termine.

Il parametro groupId richiede che i dati siano in formato GUID. È consigliabile usare GUID generati in modo casuale che non siano considerati dati personali nei sistemi.

Per avviare una nuova chiamata di gruppo o unirsi a una chiamata di gruppo in corso, utilizzare il metodo join e passare un oggetto con una proprietà groupId. Il groupId valore deve essere un GUID.

const context = { groupId: '<GUID>'};
const call = callAgent.join(context);

Ricevere una chiamata in arrivo

L'istanza callAgent genera un evento incomingCall quando l'identità registrata riceve una chiamata in ingresso. Per restare in ascolto di questo evento, sottoscrivere usando una di queste opzioni:

const incomingCallHandler = async (args: { incomingCall: IncomingCall }) => {
    const incomingCall = args.incomingCall;

    // Get incoming call ID
    var incomingCallId = incomingCall.id

    // Get information about this Call. This API is provided as a preview for developers
    // and may change based on feedback that we receive. Do not use this API in a production environment.
    // To use this api please use 'beta' release of Azure Communication Services Calling Web SDK
    var callInfo = incomingCall.info;

    // Get information about caller
    var callerInfo = incomingCall.callerInfo

    // Accept the call
    var call = await incomingCall.accept();

    // Reject the call
    incomingCall.reject();

    // Subscribe to callEnded event and get the call end reason
     incomingCall.on('callEnded', args => {
        console.log(args.callEndReason);
    });

    // callEndReason is also a property of IncomingCall
    var callEndReason = incomingCall.callEndReason;
};
callAgentInstance.on('incomingCall', incomingCallHandler);

L'evento incomingCall include un'istanza incomingCall che può essere accettata o rifiutata.

L'SDK di chiamata comunicazione di Azure genera una diagnostica di chiamata cameraStartFailed: true se la fotocamera non è disponibile quando si avvia, si accetta o si partecipa a una chiamata con video abilitato. In questo caso, la chiamata inizia con video disattivato. La fotocamera potrebbe non essere disponibile perché viene usata da un altro processo o è disabilitata nel sistema operativo.

Mettere in attesa e riprendere una chiamata

Nota

In ogni momento, deve essere presente una sola chiamata attiva, nello stato Connected, con media attivi. Tutte le altre chiamate devono essere sospese da un utente o programmaticamente dall'applicazione. Questo scenario è comune in scenari come i contact center, in cui un utente potrebbe dover gestire più chiamate in uscita e in ingresso. In questo caso, tutte le chiamate inattive devono essere sospese e l'utente deve interagire con altri solo nella chiamata attiva

Per mettere in attesa o riprendere la chiamata, usare le API asincrone hold e resume:

Per contenere la chiamata:

await call.hold();

Quando hold l'operazione viene risolta, lo stato della chiamata viene impostato su LocalHold. In una chiamata 1:1, l'altro partecipante viene messo in attesa e lo stato della chiamata dal punto di vista del partecipante è impostato su RemoteHold. In seguito, l'altro partecipante potrebbe mettere in attesa la chiamata, con conseguente modifica dello stato a LocalHold.

In una chiamata di gruppo o una riunione, hold è un'operazione locale e non mette in attesa la chiamata per altri partecipanti alla chiamata.

Per riprendere la chiamata, tutti gli utenti che hanno avviato il blocco devono riprenderlo.

Per riprendere la chiamata dopo averla messa in attesa:

await call.resume();

Quando l'operazione resume viene risolta, lo stato della chiamata viene nuovamente impostato su Connected.

Disattivare e disattivare l'audio di una chiamata

Per disattivare o riattivare l'audio dell'endpoint locale, usare le API asincrone mute e unmute:

//mute local device (microphone / sent audio)
await call.mute();

//unmute local device (microphone / sent audio)
await call.unmute();

Disattivare e attivare l'audio in ingresso

Disattivare l'audio in ingresso imposta il volume di chiamata su 0. Per disattivare o attivare l'audio in ingresso, usare le operazioni asincrone muteIncomingAudio e unmuteIncomingAudio.

//mute local device (speaker)
await call.muteIncomingAudio();

//unmute local device (speaker)
await call.unmuteIncomingAudio();

Quando l'audio in ingresso viene disattivato, l'SDK del client partecipante riceve comunque l'audio della chiamata (audio del partecipante in remoto). L'audio della chiamata non viene sentito nell'altoparlante e il partecipante non è in grado di ascoltare finché call.unmuteIncomingAudio() non viene chiamato. Tuttavia, è possibile applicare un filtro sull'audio delle chiamate e riprodurre l'audio filtrato.

Gestire partecipanti remoti

Tutti i partecipanti remoti sono inclusi nell'oggetto RemoteParticipant e disponibili tramite la raccolta in un'istanza remoteParticipants di chiamata. L'oggetto remoteParticipants è accessibile da un'istanza Call.

Elencare i partecipanti di una chiamata

La raccolta remoteParticipants restituisce un elenco di partecipanti remoti di una chiamata:

call.remoteParticipants; // [remoteParticipant, remoteParticipant....]

Aggiungere un partecipante a una chiamata

Per aggiungere un partecipante (un utente o un numero di telefono) a una chiamata, usare l'operazione addParticipant . Specificare uno dei tipi Identifier. Restituisce in modo sincrono l'istanza remoteParticipant. Quando un partecipante viene aggiunto con successo alla chiamata, viene generato l'evento remoteParticipantsUpdated da Call.

const userIdentifier = { communicationUserId: '<ACS_USER_ID>' };
const pstnIdentifier = { phoneNumber: '<PHONE_NUMBER>' }
const remoteParticipant = call.addParticipant(userIdentifier);
const alternateCallerId = {  phoneNumber: '<ALTERNATE_CALLER_ID>' };
const remoteParticipant = call.addParticipant(pstnIdentifier, { alternateCallerId });

Rimuovere un partecipante da una chiamata

Per rimuovere un partecipante (un utente o un numero di telefono) da una chiamata, è possibile chiamare removeParticipant. È necessario passare uno dei tipi Identifier. Questo metodo viene risolto in modo asincrono dopo la rimozione del partecipante dalla chiamata. Il partecipante viene rimosso anche dalla raccolta remoteParticipants.

const userIdentifier = { communicationUserId: '<ACS_USER_ID>' };
const pstnIdentifier = { phoneNumber: '<PHONE_NUMBER>' }
await call.removeParticipant(userIdentifier);
await call.removeParticipant(pstnIdentifier);

Accedere alle proprietà dei partecipanti remoti

I partecipanti remoti hanno un set di proprietà e raccolte associate:

  • CommunicationIdentifier: Ottieni l'identificatore per un partecipante remoto. L’identità è uno dei tipi CommunicationIdentifier:

    const identifier = remoteParticipant.identifier;

  • Può essere uno dei tipi CommunicationIdentifier seguenti:

    • { communicationUserId: '<ACS_USER_ID'> }: oggetto che rappresenta l'utente di Servizi di comunicazione di Azure.
    • { phoneNumber: '<E.164>' }: oggetto che rappresenta il numero di telefono in formato E.164.
    • { microsoftTeamsUserId: '<TEAMS_USER_ID>', isAnonymous?: boolean; cloud?: "public" | "dod" | "gcch" }: oggetto che rappresenta l'utente di Teams.
    • { id: string }: oggetto che rappresenta un identificatore che non rientra tra nessun altro tipo di identificatore

  • state: ottenere lo stato di un partecipante in remoto.

    const state = remoteParticipant.state;

  • Lo stato può essere:

    • Idle: stato iniziale.
    • Connecting: stato di transizione mentre un partecipante si connette alla chiamata.
    • Ringing: il partecipante sta squillando.
    • Connected: il partecipante è connesso alla chiamata.
    • Hold: il partecipante è in attesa.
    • EarlyMedia: Un messaggio di annuncio che viene riprodotto prima che un partecipante si connetta alla chiamata.
    • InLobby: indica che il partecipante in remoto si trova nella sala d'attesa.
    • Disconnected: stato finale. Il partecipante viene disconnesso dalla chiamata. Se il partecipante in remoto perde la connettività di rete, il suo stato diventa Disconnected dopo due minuti.

  • callEndReason: per informazioni sul motivo per cui un partecipante ha lasciato la chiamata, controllare la proprietà callEndReason:

    const callEndReason = remoteParticipant.callEndReason;
const callEndReasonCode = callEndReason.code // (number) code associated with the reason
const callEndReasonSubCode = callEndReason.subCode // (number) subCode associated with the reason

    Nota

    Questa proprietà viene impostata solo quando si aggiunge un partecipante remoto tramite l'API Call.addParticipant() e il partecipante remoto, ad esempio, rifiuta la chiamata.

    Nello scenario in cui UserB espelle UserC, dal punto di vista di UserA, UserA non vede questo flag impostato per UserC. In altre parole, UserA non visualizza la proprietà callEndReason di UserC.

  • Stato isMuted: per scoprire se l’audio di un partecipante in remoto è disattivato, controllare la proprietà isMuted. Restituisce Boolean.

    const isMuted = remoteParticipant.isMuted;

  • Stato isSpeaking: per scoprire se un partecipante in remoto sta parlando, controllare la proprietà isSpeaking. Restituisce Boolean.

    const isSpeaking = remoteParticipant.isSpeaking;

  • videoStreams: per controllare tutti i flussi video inviati da un determinato partecipante in questa chiamata, controllare la raccolta videoStreams. Contiene oggetti RemoteVideoStream.

    const videoStreams = remoteParticipant.videoStreams; // [RemoteVideoStream, ...]

  • displayName: Per ottenere il nome visualizzato per questo partecipante remoto, esaminare la proprietà displayName: essa restituisce una stringa.

    const displayName = remoteParticipant.displayName;

  • endpointDetails: ottenere i dettagli di tutti gli endpoint per questo partecipante in remoto

    const endpointDetails: EndpointDetails[] = remoteParticipant.endpointDetails;

    Nota

    Un partecipante remoto può prendere parte alla chiamata da diversi endpoint possibili, e ogni endpoint ha il suo elemento univoco participantId. participantId è diverso dall'identificatore ID non elaborato RemoteParticipant.

Disattivare l'audio per altri partecipanti

Nota

Utilizzare l'SDK Web per le chiamate di Azure Communication Services versione 1.26.1 o superiore.

Per disattivare tutti gli altri partecipanti o disattivare un partecipante specifico connesso a una chiamata, è possibile usare le API muteAllRemoteParticipants asincrone sulla chiamata e mute sul partecipante remoto. L'evento mutedByOthers dalla chiamata viene generato quando l'audio del partecipante locale è stato disattivato da altri.

Importante

Questa funzionalità di Servizi di comunicazione di Azure è attualmente in anteprima. Le funzionalità in anteprima sono disponibili pubblicamente e possono essere usate da tutti i clienti Microsoft nuovi ed esistenti.

Le anteprime di API e SDK vengono fornite senza un contratto di servizio. È consigliabile non usarle per carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero essere vincolate.

Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

La disattivazione di un endpoint PSTN utilizzando il WebJS SDK del chiamante è attualmente in anteprima pubblica ed è disponibile nella build 1.34.1 1.34.1 e versioni successive.

Nota

Disattivare l'audio di altri durante una chiamata 1:1 non è supportato.

//mute all participants except yourself
await call.muteAllRemoteParticipants();

//mute a specific participant
await call.remoteParticipants[0].mute();

Controllare le proprietà di chiamata

Ottenere l'ID univoco (stringa) per una chiamata:

const callId: string = call.id;

Ottenere l'ID partecipante locale:

const participantId: string = call.info.participantId;

Nota

Un'identità di Servizi di comunicazione di Azure può usare l'SDK per chiamate web su molti endpoint e ogni endpoint ha un identificatore univoco proprio participantId. participantId è diverso dall'ID non elaborato dell'identità di Servizi di comunicazione di Azure.

Recuperare l'ID del thread se ci si unisce a una riunione di Teams:

const threadId: string | undefined = call.info.threadId;

Ottenere informazioni sulla chiamata:

const callInfo = call.info;

Per informazioni sugli altri partecipanti alla chiamata, esaminare la raccolta remoteParticipants nell'istanza call:

const remoteParticipants = call.remoteParticipants;

Identificare il chiamante di una chiamata in ingresso:

const callerIdentity = call.callerInfo.identifier;

identifier è uno dei tipi CommunicationIdentifier.

Ottenere lo stato di una chiamata:

const callState = call.state;

Viene restituita una stringa che rappresenta lo stato corrente di una chiamata:

  • None: stato della chiamata iniziale.
  • Connecting: stato di transizione iniziale, quando viene effettuata o accettata una chiamata.
  • Ringing: per una chiamata in uscita, indica che una chiamata sta squillando per i partecipanti remoti. È Incoming sul loro lato.
  • EarlyMedia: indica uno stato in cui viene riprodotto un annuncio prima che la chiamata sia connessa.
  • Connected: indica che la chiamata è connessa.
  • LocalHold: indica che un partecipante locale alla chiamata ha messo in attesa la chiamata. Nessun elemento multimediale è in flusso tra l'endpoint locale e i partecipanti in remoto.
  • RemoteHold: indica che un partecipante remoto ha messo in attesa la chiamata. Nessun elemento multimediale è in flusso tra l'endpoint locale e i partecipanti in remoto.
  • InLobby: indica che l'utente è nella sala di attesa.
  • Disconnecting: stato di transizione prima che la chiamata passi a uno stato Disconnected.
  • Disconnected: stato finale della chiamata. Se la connessione di rete viene persa, lo stato diventa Disconnected dopo due minuti.

Scoprire perché una chiamata è terminata esaminando la proprietà callEndReason:

const callEndReason = call.callEndReason;
const callEndReasonMessage = callEndReason.message // (string) user friendly message
const callEndReasonCode = callEndReason.code // (number) code associated with the reason
const callEndReasonSubCode = callEndReason.subCode // (number) subCode associated with the reason

Scoprire se la chiamata corrente è in ingresso o in uscita esaminando la proprietà direction. Restituisce CallDirection.

const isIncoming = call.direction == 'Incoming';
const isOutgoing = call.direction == 'Outgoing';

Esaminare i flussi video attivi e i flussi di condivisione dello schermo attivi controllando la raccolta localVideoStreams. L'operazione localVideoStreams restituisce LocalVideoStream oggetti di tipo Video, ScreenSharingo RawMedia.

const localVideoStreams = call.localVideoStreams;

Controllare se il microfono corrente è disattivato. Restituisce Boolean.

const muted = call.isMuted;

Controllare se l'audio in ingresso corrente (altoparlante) è disattivato. Restituisce Boolean.

const incomingAudioMuted = call.isIncomingAudioMuted;

Controllare se il video è attivo. Restituisce Boolean.

const isLocalVideoStarted = call.isLocalVideoStarted;

Verificare se la condivisione dello schermo è attivata. Restituisce Boolean.

const isScreenSharingOn = call.isScreenSharingOn;

Interrompere una chiamata

Esistono due modi per appendere la chiamata.

  • Il chiamante iniziale può lasciare la chiamata e gli altri partecipanti rimangono nella chiamata.
  • Quando il chiamante iniziale lascia, la chiamata termina per tutti i partecipanti.

Per lasciare la chiamata, usare:

call.hangUp();

Terminare la chiamata per tutti i partecipanti specificando HangUpOptions.

Nota

Questa operazione non è disponibile nelle stanze.

call.hangUp( forEveryone: true);

Installazione dell'SDK

Individua il file del progetto a livello build.gradle e aggiungi mavenCentral() all'elenco dei repository sotto buildscript e allprojects:

buildscript {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

allprojects {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

Quindi, nel file a livello build.gradle di modulo aggiungere le righe seguenti alla dependencies sezione :

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-calling:1.0.0'
    ...
}

Inizializzare gli oggetti necessari

Per creare un'istanza CallAgent, è necessario chiamare il metodo createCallAgent in un'istanza CallClient. Questa chiamata restituisce in modo asincrono un oggetto istanza CallAgent.

Il metodo createCallAgent accetta CommunicationUserCredential come argomento, che incapsula un token di accesso.

Per accedere a DeviceManager, è prima necessario creare un'istanza callAgent. Quindi è possibile usare il metodo CallClient.getDeviceManager per ottenere DeviceManager.

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

Per impostare nome visualizzato per il chiamante, usare questo metodo alternativo:

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

Effettua una chiamata

Per creare e avviare una chiamata, è necessario chiamare il CallAgent.startCall() metodo e fornire il Identifier destinatario o i destinatari.

Per partecipare a una chiamata di gruppo, è necessario chiamare il CallAgent.join() metodo e specificare .groupId Gli ID gruppo devono essere in formato GUID o UUID.

La creazione e l'avvio di chiamate sono sincroni. L'istanza di chiamata consente di eseguire la sottoscrizione a tutti gli eventi nella chiamata.

Effettuare una chiamata 1:1 a un utente

Per effettuare una chiamata a un altro utente di Servizi di comunicazione, richiamare il metodo call su callAgent e passare un oggetto con chiave communicationUserId.

StartCallOptions startCallOptions = new StartCallOptions();
Context appContext = this.getApplicationContext();
CommunicationUserIdentifier acsUserId = new CommunicationUserIdentifier(<USER_ID>);
CommunicationUserIdentifier participants[] = new CommunicationUserIdentifier[]{ acsUserId };
call oneToOneCall = callAgent.startCall(appContext, participants, startCallOptions);

Effettuare una chiamata 1:n con utenti e PSTN

Nota

Vedere i dettagli dell'offerta di chiamate PSTN. Per l'accesso in anteprima al programma, iscriversi al programma early adopter.

Per effettuare una chiamata 1:n a un utente e un numero PSTN (Public Switched Telephone Network), è necessario specificare il numero di telefono del destinatario o dei destinatari.

La risorsa di Servizi di comunicazione deve essere configurata per abilitare le chiamate PSTN:

CommunicationUserIdentifier acsUser1 = new CommunicationUserIdentifier(<USER_ID>);
PhoneNumberIdentifier acsUser2 = new PhoneNumberIdentifier("<PHONE_NUMBER>");
CommunicationIdentifier participants[] = new CommunicationIdentifier[]{ acsUser1, acsUser2 };
StartCallOptions startCallOptions = new StartCallOptions();
Context appContext = this.getApplicationContext();
Call groupCall = callAgent.startCall(participants, startCallOptions);

Accettare una chiamata

Per accettare una chiamata, chiamare il metodo accept su un oggetto di chiamata.

Context appContext = this.getApplicationContext();
IncomingCall incomingCall = retrieveIncomingCall();
Call call = incomingCall.accept(context).get();

Per accettare una chiamata con videocamera attivata:

Context appContext = this.getApplicationContext();
IncomingCall incomingCall = retrieveIncomingCall();
AcceptCallOptions acceptCallOptions = new AcceptCallOptions();
VideoDeviceInfo desiredCamera = callClient.getDeviceManager().get().getCameraList().get(0);
acceptCallOptions.setVideoOptions(new VideoOptions(new LocalVideoStream(desiredCamera, appContext)));
Call call = incomingCall.accept(context, acceptCallOptions).get();

Ottenere la chiamata in ingresso iscrivendosi all'evento onIncomingCall sull'oggetto callAgent.

// Assuming "callAgent" is an instance property obtained by calling the 'createCallAgent' method on CallClient instance 
public Call retrieveIncomingCall() {
    IncomingCall incomingCall;
    callAgent.addOnIncomingCallListener(new IncomingCallListener() {
        void onIncomingCall(IncomingCall inboundCall) {
            // Look for incoming call
            incomingCall = inboundCall;
        }
    });
    return incomingCall;
}

Partecipare a una videochiamata nella stanza

Utilizzare il CallAgent e RoomCallLocator per partecipare a una chiamata di sala specificando un roomId. Il CallAgent.join metodo restituisce un Call oggetto :

val roomCallLocator = RoomCallLocator(roomId)
call = callAgent.join(applicationContext, roomCallLocator, joinCallOptions)

room consente agli sviluppatori di applicazioni di avere maggiore controllo su chi possa unirsi a una chiamata, quando si incontrino e come collaborino. Per altre informazioni sulle sale, vedere API Rooms per riunioni strutturate e Partecipare a una chiamata in sala.

Partecipare a una chiamata di gruppo

Per avviare una nuova chiamata di gruppo o partecipare a una chiamata di gruppo in corso, è necessario chiamare il join metodo e passare un oggetto con una groupId proprietà . Il valore deve essere un GUID.

Context appContext = this.getApplicationContext();
GroupCallLocator groupCallLocator = new GroupCallLocator("<GUID>");
JoinCallOptions joinCallOptions = new JoinCallOptions();

call = callAgent.join(context, groupCallLocator, joinCallOptions);

Proprietà della chiamata

Ottenere l'ID univoco per questa chiamata:

String callId = call.getId();

Per informazioni su altri partecipanti alla chiamata, ispezionare la raccolta remoteParticipant nell'istanza call:

List<RemoteParticipant> remoteParticipants = call.getRemoteParticipants();

Identità del chiamante se la chiamata è in ingresso:

CommunicationIdentifier callerId = call.getCallerInfo().getIdentifier();

Ottenere lo stato della chiamata:

CallState callState = call.getState();

Restituisce una stringa che rappresenta lo stato corrente di una chiamata:

  • NONE - stato della chiamata iniziale
  • EARLY_MEDIA - indica uno stato in cui viene riprodotto un annuncio prima che la chiamata sia connessa
  • CONNECTING - stato di transizione iniziale dopo che la chiamata viene inserita o accettata
  • RINGING - per una chiamata in uscita - indica che la chiamata sta suonando per i partecipanti remoti
  • CONNECTED - chiamata collegata
  • LOCAL_HOLD - chiamata sospesa dal partecipante locale senza flusso multimediale tra l'endpoint locale e i partecipanti remoti
  • REMOTE_HOLD - chiamata sospesa da un partecipante remoto senza flusso multimediale tra l'endpoint locale e i partecipanti remoti
  • DISCONNECTING - stato di transizione prima che la chiamata passi allo Disconnected stato
  • DISCONNECTED - stato della chiamata finale
  • IN_LOBBY - in sala di attesa per l'interoperabilità di una riunione di Teams

Per capire il motivo per cui una chiamata è terminata, esaminare la proprietà callEndReason. Contiene codice/codice secondario:

CallEndReason callEndReason = call.getCallEndReason();
int code = callEndReason.getCode();
int subCode = callEndReason.getSubCode();

Per verificare se la chiamata corrente è una chiamata in ingresso o in uscita, controllare la proprietà callDirection:

CallDirection callDirection = call.getCallDirection(); 
// callDirection == CallDirection.INCOMING for incoming call
// callDirection == CallDirection.OUTGOING for outgoing call

Per verificare se il microfono corrente è disattivato, controllare la proprietà muted:

boolean muted = call.isMuted();

Per esaminare i flussi video attivi, controllare la raccolta localVideoStreams:

List<LocalVideoStream> localVideoStreams = call.getLocalVideoStreams();

Disattivare e riattivare l'audio

Per disattivare o riattivare l'audio dell'endpoint locale, è possibile usare le API asincrone mute e unmute:

Context appContext = this.getApplicationContext();
call.mute(appContext).get();
call.unmute(appContext).get();

Modificare il volume della chiamata

Mentre i partecipanti sono in una chiamata, le chiavi del volume hardware sul telefono dovrebbero consentire all'utente di modificare il volume di chiamata.

Usare il metodo setVolumeControlStream con il tipo di flusso AudioManager.STREAM_VOICE_CALL nell'attività in cui viene eseguita la chiamata.

Questo metodo consente alle chiavi del volume hardware di modificare il volume della chiamata, indicato da un'icona del telefono o qualcosa di simile nel dispositivo di scorrimento del volume. Impedisce inoltre le modifiche apportate al volume da altri profili audio, ad esempio allarmi, supporti o volumi a livello di sistema. Per altre informazioni, vedere Gestione delle modifiche nell'output audio | Sviluppatori Android.

@Override
protected void onCreate(Bundle savedInstanceState) {
    ...
    setVolumeControlStream(AudioManager.STREAM_VOICE_CALL);
}

Gestione di partecipanti in remoto

Tutti i partecipanti remoti hanno il tipo RemoteParticipant e saranno disponibili tramite la raccolta remoteParticipants in un'istanza di chiamata.

Elencare i partecipanti a una chiamata

La raccolta remoteParticipants restituisce un elenco di partecipanti in remoto di una determinata chiamata:

List<RemoteParticipant> remoteParticipants = call.getRemoteParticipants(); // [remoteParticipant, remoteParticipant....]

Aggiungere un partecipante a una chiamata

Per aggiungere un partecipante a una chiamata (un utente o un numero di telefono), è possibile chiamare l'operazione addParticipant .

Questa operazione restituisce in modo sincrono l'istanza del partecipante remoto.

const acsUser = new CommunicationUserIdentifier("<acs user id>");
const acsPhone = new PhoneNumberIdentifier("<phone number>");
RemoteParticipant remoteParticipant1 = call.addParticipant(acsUser);
AddPhoneNumberOptions addPhoneNumberOptions = new AddPhoneNumberOptions(new PhoneNumberIdentifier("<alternate phone number>"));
RemoteParticipant remoteParticipant2 = call.addParticipant(acsPhone, addPhoneNumberOptions);

Rimuovere un partecipante da una chiamata

Per rimuovere un partecipante da una chiamata (un utente o un numero di telefono), è possibile chiamare l'operazione removeParticipant .

Questa operazione viene risolta in modo asincrono quando il partecipante viene rimosso dalla chiamata.

Il partecipante viene rimosso anche dalla raccolta remoteParticipants.

RemoteParticipant acsUserRemoteParticipant = call.getParticipants().get(0);
RemoteParticipant acsPhoneRemoteParticipant = call.getParticipants().get(1);
call.removeParticipant(acsUserRemoteParticipant).get();
call.removeParticipant(acsPhoneRemoteParticipant).get();

Proprietà del partecipante remoto

Qualsiasi partecipante remoto specificato ha un set di proprietà e raccolte associate:

  • Ottenere l'identificatore per questo partecipante in remoto.

L’identità è uno dei tipi Identifier:

CommunicationIdentifier participantIdentifier = remoteParticipant.getIdentifier();

  • Ottieni lo stato di questo partecipante remoto.

    ParticipantState state = remoteParticipant.getState();

Lo stato può essere uno dei seguenti:

  • IDLE - stato iniziale

  • EARLY_MEDIA - l'annuncio viene riprodotto prima che il partecipante sia connesso alla chiamata

  • RINGING - la chiamata del partecipante sta suonando

  • CONNECTING - stato di transizione mentre il partecipante si connette alla chiamata

  • CONNECTED - il partecipante è connesso alla chiamata

  • HOLD - partecipante è in attesa

  • IN_LOBBY - partecipante è in attesa nella sala di attesa per essere ammesso. Attualmente usato solo nello scenario di interoperabilità di Teams

  • DISCONNECTED - stato finale - Il partecipante viene disconnesso dalla chiamata

  • Per informazioni sul motivo per cui un partecipante ha lasciato la chiamata, esaminare la proprietà callEndReason:

    CallEndReason callEndReason = remoteParticipant.getCallEndReason();

  • Per verificare se l’audio del partecipante in remoto sia disattivato o meno, controllare la proprietà isMuted:

    boolean isParticipantMuted = remoteParticipant.isMuted();

  • Per verificare se il partecipante in remoto stia parlando o meno, controllare la proprietà isSpeaking:

    boolean isParticipantSpeaking = remoteParticipant.isSpeaking();

  • Per controllare tutti i flussi video inviati da un determinato partecipante in questa chiamata, controllare la raccolta videoStreams:

    List<RemoteVideoStream> videoStreams = remoteParticipant.getVideoStreams(); // [RemoteVideoStream, RemoteVideoStream, ...]

Disattivare l'audio per altri partecipanti

Nota

Usare l'SDK Android di chiamata di Servizi di comunicazione di Azure versione 2.11.0 o successive.

Quando l'audio di un partecipante PSTN viene disattivato, il partecipante riceve un annuncio indicante che il suo audio è stato disattivato e che può premere una combinazione di tasti, ad esempio (*6) per riattivarlo. Quando preme *6, non vengono attivati.

Per disattivare tutti gli altri partecipanti in una chiamata, usare l'operazione muteAllRemoteParticipants API.

call.muteAllRemoteParticipants();

Per disattivare un partecipante remoto specifico, usare l'operazione mute API su un determinato partecipante remoto.

remoteParticipant.mute();

Per notificare al partecipante locale che il suo audio è stato disattivato da altri, eseguire la sottoscrizione all'evento onMutedByOthers.

Uso di servizi in primo piano

Se si vuole eseguire un'attività visibile dall'utente anche quando l'applicazione è in background, è possibile usare Servizi in primo piano.

Usare Servizi in primo piano, ad esempio, per fornire agli utenti una notifica visibile quando l'applicazione ha una chiamata attiva. In questo modo, anche se l'utente passa alla schermata iniziale o rimuove l'applicazione dalla schermata recenti, la chiamata continua ad essere attiva.

Se non si usa un servizio in primo piano durante una chiamata, il passaggio alla schermata iniziale può mantenere attiva la chiamata, ma la rimozione dell'applicazione dalla schermata recente può interrompere la chiamata se il sistema operativo Android termina il processo dell'applicazione.

È necessario avviare il servizio in primo piano quando un utente avvia o partecipa a una chiamata, ad esempio:

call = callAgent.startCall(context, participants, options);
startService(yourForegroundServiceIntent);

È anche consigliabile arrestare il servizio in primo piano quando si termina la chiamata o lo stato della chiamata è 'Disconnesso', ad esempio:

call.hangUp(new HangUpOptions()).get();
stopService(yourForegroundServiceIntent);

Dettagli del servizio in primo piano

Tenere presente che scenari come l'arresto di un servizio in primo piano già in esecuzione quando l'app viene rimossa dall'elenco degli elementi recenti rimuovono la notifica visibile dall'utente. In questo caso il sistema operativo Android può mantenere attivo il processo dell'applicazione per un periodo di tempo aggiuntivo, vale a dire che la chiamata può rimanere attiva durante questo periodo.

Se l'applicazione arresta il servizio in primo piano nel metodo del servizio onTaskRemoved, ad esempio, l'applicazione può avviare o interrompere audio e video in base al Ciclo di vita dell'attività. Ad esempio, interrompere audio e video quando l’attività viene eliminata con l'override del metodo onDestroy.

Configurare il sistema

Seguire questa procedura per configurare il sistema.

Creare il progetto Xcode

In Xcode creare un nuovo progetto iOS e selezionare il modello Single View Application. Questo articolo usa il framework SwiftUI, quindi è consigliabile impostare Language su Swift e impostare Interface su SwiftUI.

In questo articolo non verranno creati test. È possibile deselezionare la casella di controllo Includi i test.

Screenshot che mostra la finestra per la creazione di un progetto in Xcode.

Installare il pacchetto e le dipendenze usando CocoaPods

  1. Creare un file Podfile per l'applicazione, come questo esempio:

    platform :ios, '13.0'
use_frameworks!
target 'AzureCommunicationCallingSample' do
    pod 'AzureCommunicationCalling', '~> 1.0.0'
end

  2. Eseguire pod install.

  3. Aprire .xcworkspace con Xcode.

Richiedere l'accesso al microfono

Per accedere al microfono del dispositivo, è necessario aggiornare l'elenco delle proprietà informazioni dell'app usando NSMicrophoneUsageDescription. Impostare il valore associato su una stringa inclusa nella finestra di dialogo usata dal sistema per richiedere l'accesso dall'utente.

Fare clic con il pulsante destro del mouse sulla voce info.plist dell'albero del progetto, quindi selezionare Apri come>codice sorgente. Aggiungere le righe seguenti nella sezione di primo livello <dict> e quindi salvare il file.

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

Configurare il framework dell'app

Apri il file ContentView.swift del progetto. Aggiungere una dichiarazione import all'inizio del file per importare la libreria AzureCommunicationCalling. Inoltre, importare AVFoundation. È necessario per le richieste di autorizzazione audio nel codice.

import AzureCommunicationCalling
import AVFoundation

Inizializzare CallAgent

Per creare un'istanza CallAgent da CallClient, è necessario usare un metodo callClient.createCallAgent che restituisce in modo asincrono un oggetto CallAgent dopo l'inizializzazione.

Per creare un client di chiamata, passare un oggetto CommunicationTokenCredential:

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

Passare l'oggetto CommunicationTokenCredential creato in CallClient e impostare il nome visualizzato:

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

Nota

Quando l'applicazione implementa delegati di eventi, deve mantenere un riferimento forte agli oggetti che richiedono sottoscrizioni di eventi. Ad esempio, quando si chiama il call.addParticipant metodo e restituisce un RemoteParticipant oggetto . L'applicazione imposta quindi il delegato in ascolto su RemoteParticipantDelegate e deve mantenere un riferimento solido all'oggetto RemoteParticipant. In caso contrario, se questo oggetto viene raccolto, il delegato genera un'eccezione irreversibile quando il Calling SDK prova a invocare l'oggetto.

Effettuare una chiamata in uscita

Per creare e avviare una chiamata, è necessario chiamare una delle API su CallAgent e fornire l'identità di Servizi di comunicazione di un utente di cui è stato effettuato il provisioning usando il SDK di Gestione di Servizi di comunicazione.

La creazione e l'avvio di chiamate sono sincroni. Si riceve un'istanza di chiamata che consente di sottoscrivere tutti gli eventi della chiamata.

Effettua una chiamata 1:1 a un utente o una chiamata 1:n con utenti su PSTN.

let callees = [CommunicationUser(identifier: 'UserId')]
self.callAgent?.startCall(participants: callees, options: StartCallOptions()) { (call, error) in
     if error == nil {
         print("Successfully started outgoing call")
         self.call = call
     } else {
         print("Failed to start outgoing call")
     }
}

Effettuare una chiamata 1:n con utenti e PSTN

Nota

Vedere i dettagli dell'offerta di chiamate PSTN. Per l'accesso in anteprima al programma, iscriversi al programma early adopter.

Per effettuare una chiamata 1:n a un utente e a una rete PSTN (Public Switched Telephone Network), è necessario specificare un numero di telefono acquisito con Servizi di comunicazione.

let pstnCallee = PhoneNumberIdentifier(phoneNumber: '+1999999999')
let callee = CommunicationUserIdentifier('UserId')
self.callAgent?.startCall(participants: [pstnCallee, callee], options: StartCallOptions()) { (groupCall, error) in
     if error == nil {
         print("Successfully started outgoing call to multiple participants")
         self.call = groupCall
     } else {
         print("Failed to start outgoing call to multiple participants")
     }
}

Partecipare a una videochiamata nella stanza

Per unire una chiamata room, specificare la proprietà roomId come identificatore room. Per unirsi alla chiamata, utilizzare il metodo join e passare il roomCallLocator.

func joinRoomCall() {
    if self.callAgent == nil {
        print("CallAgent not initialized")
        return
    }
    
    if (self.roomId.isEmpty) {
        print("Room ID not set")
        return
    }
    
    // Join a call with a Room ID
    let options = JoinCallOptions()
    let audioOptions = AudioOptions()
    audioOptions.muted = self.muted
    
    options.audioOptions = audioOptions
    
    let roomCallLocator = RoomCallLocator(roomId: roomId)
    self.callAgent!.join(with: roomCallLocator, joinCallOptions: options) { (call, error) in
        self.setCallAndObserver(call: call, error: error)
    }
}

room consente agli sviluppatori di applicazioni di avere maggiore controllo su chi possa unirsi a una chiamata, quando si incontrino e come collaborino. Per altre informazioni sulle sale, vedere API Rooms per riunioni strutturate e Partecipare a una chiamata in sala.

Partecipare a una chiamata di gruppo

Per partecipare a una chiamata, è necessario chiamare una delle API in CallAgent.

let groupCallLocator = GroupCallLocator(groupId: UUID(uuidString: "uuid_string")!)
self.callAgent?.join(with: groupCallLocator, joinCallOptions: JoinCallOptions()) { (call, error) in
    if error == nil {
        print("Successfully joined group call")
        self.call = call
    } else {
        print("Failed to join group call")
    }
}

Sottoscrivere a una chiamata in ingresso

Eseguire la sottoscrizione a un evento di chiamata in ingresso.

final class IncomingCallHandler: NSObject, CallAgentDelegate, IncomingCallDelegate
{
    // Event raised when there is an incoming call
    public func callAgent(_ callAgent: CallAgent, didReceiveIncomingCall incomingcall: IncomingCall) {
        self.incomingCall = incomingcall
        // Subscribe to get OnCallEnded event
        self.incomingCall?.delegate = self
    }

    // Event raised when incoming call was not answered
    public func incomingCall(_ incomingCall: IncomingCall, didEnd args: PropertyChangedEventArgs) {
        print("Incoming call was not answered")
        self.incomingCall = nil
    }
}

Accettare una chiamata in arrivo.

Per accettare una chiamata, chiamare il metodo accept su un oggetto IncomingCall.

self.incomingCall!.accept(options: AcceptCallOptions()) { (call, error) in
   if (error == nil) {
       print("Successfully accepted incoming call")
       self.call = call
   } else {
       print("Failed to accept incoming call")
   }
}

let firstCamera: VideoDeviceInfo? = self.deviceManager!.cameras.first
localVideoStreams = [LocalVideoStream]()
localVideoStreams!.append(LocalVideoStream(camera: firstCamera!))
let acceptCallOptions = AcceptCallOptions()
acceptCallOptions.videoOptions = VideoOptions(localVideoStreams: localVideoStreams!)
if let incomingCall = self.incomingCall {
    incomingCall.accept(options: acceptCallOptions) { (call, error) in
        if error == nil {
            print("Incoming call accepted")
        } else {
            print("Failed to accept incoming call")
        }
    }
} else {
  print("No incoming call found to accept")
}

Eseguire operazioni durante la chiamata

È possibile eseguire operazioni durante una chiamata per gestire le impostazioni relative a video e audio.

Disattivare e riattivare l'audio

Per disattivare o riattivare l'audio dell'endpoint locale, usare le API asincrone mute e unmute.

call!.mute { (error) in
    if error == nil {
        print("Successfully muted")
    } else {
        print("Failed to mute")
    }
}

Usare il codice seguente per riattivare l'audio dell'endpoint locale in modo asincrono.

call!.unmute { (error) in
    if error == nil {
        print("Successfully un-muted")
    } else {
        print("Failed to unmute")
    }
}

Gestire partecipanti remoti

Il RemoteParticipant tipo rappresenta tutti i partecipanti remoti. Sono disponibili tramite la raccolta remoteParticipants su un'istanza di chiamata.

Elencare i partecipanti a una chiamata

call.remoteParticipants

Aggiungere un partecipante a una chiamata

Per aggiungere un partecipante a una chiamata come utente o un numero di telefono, chiamare l'operazione addParticipant . Questa operazione restituisce in modo sincrono un'istanza del partecipante remoto.

let remoteParticipantAdded: RemoteParticipant = call.add(participant: CommunicationUserIdentifier(identifier: "userId"))

Rimuovere un partecipante da una chiamata

Per rimuovere un partecipante da una chiamata come utente o un numero di telefono, chiamare l'operazione removeParticipant . Questa operazione viene risolta in modo asincrono.

call!.remove(participant: remoteParticipantAdded) { (error) in
    if (error == nil) {
        print("Successfully removed participant")
    } else {
        print("Failed to remove participant")
    }
}

Ottenere le proprietà di partecipanti remoti

// [RemoteParticipantDelegate] delegate - an object you provide to receive events from this RemoteParticipant instance
var remoteParticipantDelegate = remoteParticipant.delegate

// [CommunicationIdentifier] identity - same as the one used to provision a token for another user
var identity = remoteParticipant.identifier

// ParticipantStateIdle = 0, ParticipantStateEarlyMedia = 1, ParticipantStateConnecting = 2, ParticipantStateConnected = 3, ParticipantStateOnHold = 4, ParticipantStateInLobby = 5, ParticipantStateDisconnected = 6
var state = remoteParticipant.state

// [Error] callEndReason - reason why participant left the call, contains code/subcode/message
var callEndReason = remoteParticipant.callEndReason

// [Bool] isMuted - indicating if participant is muted
var isMuted = remoteParticipant.isMuted

// [Bool] isSpeaking - indicating if participant is currently speaking
var isSpeaking = remoteParticipant.isSpeaking

// RemoteVideoStream[] - collection of video streams this participants has
var videoStreams = remoteParticipant.videoStreams // [RemoteVideoStream, RemoteVideoStream, ...]

Disattivare l'audio per altri partecipanti

Nota

Utilizzare l'SDK iOS di Azure Communication Services per le chiamate, versione 2.13.0 o successiva.

Quando l'audio di un partecipante PSTN viene disattivato, il partecipante riceve un annuncio indicante che il suo audio è stato disattivato e che può premere una combinazione di tasti, ad esempio (*6) per riattivarlo. Quando preme *6, l'audio viene riattivato.

Per disattivare tutti gli altri partecipanti in una chiamata, usare l'operazione muteAllRemoteParticipants sulla chiamata.

call!.muteAllRemoteParticipants { (error) in
    if error == nil {
        print("Successfully muted all remote participants.")
    } else {
        print("Failed to mute remote participants.")
    }
}

Per disattivare un partecipante remoto specifico, usare l'operazione mute su un determinato partecipante remoto.

remoteParticipant.mute { (error) in
    if error == nil {
        print("Successfully muted participant.")
    } else {
        print("Failed to mute participant.")
    }
}

Per notificare al partecipante locale che il suo audio è stato disattivato da altri, eseguire la sottoscrizione all'evento onMutedByOthers.

Configurare il sistema

Seguire questa procedura per configurare il sistema.

Creare il progetto di Visual Studio

Per un'app della piattaforma UWP (Universal Windows Platform), in Visual Studio 2022, creare un nuovo progetto App vuota (Universal Windows). Dopo aver immesso il nome del progetto, è possibile scegliere qualsiasi Windows SDK successivo alla versione 10.0.17763.0.

Per un'app WinUI 3, creare un nuovo progetto con il modello App vuota, Incluso nel pacchetto (WinUI 3 in Desktop) per configurare un'app WinUI 3 a pagina singola. È necessario SDK per app di Windows in versione 1.3 o successiva.

Installare il pacchetto e le dipendenze usando Gestione pacchetti NuGet

Le API e le librerie del SDK di Chiamata sono disponibili pubblicamente tramite un pacchetto NuGet.

Per trovare, scaricare e installare il pacchetto NuGet Calling SDK:

  1. Aprire Gestione pacchetti NuGet selezionando Strumenti>Gestione pacchetti NuGet> Gestisci pacchetti NuGet per la soluzione.
  2. Selezionare Sfoglia e quindi immettere Azure.Communication.Calling.WindowsClient nella casella di ricerca.
  3. Assicurarsi che la casella di controllo Includi versione preliminare sia selezionata.
  4. Selezionare il pacchetto Azure.Communication.Calling.WindowsClient e quindi selezionare Azure.Communication.Calling.WindowsClient1.4.0-beta.1 o una versione più recente.
  5. Selezionare la casella di controllo corrispondente al progetto Servizi di comunicazione di Azure nel riquadro destro.
  6. Selezionare Installa.

Implementare l'app di esempio in Visual Studio

Questa sezione descrive come sviluppare l'app per gestire le chiamate che funzionano in Visual Studio.

Richiedere l'accesso al microfono

L'app richiede l'accesso al microfono. Nelle app UWP (Universal Windows Platform) la funzionalità del microfono deve essere dichiarata nel file manifesto dell'app.

Per accedere al microfono:

  1. Nel pannello Solution Explorer, fare doppio clic sul file con estensione .appxmanifest.
  2. Fare clic sulla scheda Capabilities.
  3. Selezionare la casella di controllo Microphone dall'elenco delle funzionalità.

Creare pulsanti dell'interfaccia utente per effettuare e terminare la chiamata

Questa app di esempio contiene due pulsanti. Uno per effettuare la chiamata e un altro per terminare una chiamata effettuata.

Aggiungere due pulsanti all'app.

  1. Nel pannello Solution Explorer, fare doppio clic sul file denominato MainPage.xaml per UWP o MainWindows.xaml per WinUI 3.
  2. Nel pannello centrale, cercare il codice XAML sotto l'anteprima dell'interfaccia utente.
  3. Modificare il codice XAML con il seguente estratto:
<TextBox x:Name="CalleeTextBox" PlaceholderText="Who would you like to call?" />
<StackPanel>
    <Button x:Name="CallButton" Content="Start/Join call" Click="CallButton_Click" />
    <Button x:Name="HangupButton" Content="Hang up" Click="HangupButton_Click" />
</StackPanel>

Configurare l'app con le API dell'SDK per chiamate

Le API di chiamata dell'SDK sono divise in due diversi namespace.

La procedura seguente informa il compilatore C# su questi namespace, abilitando IntelliSense di Visual Studio per assistere nello sviluppo del codice.

  1. Nel pannello Solution Explorer, fare clic sulla freccia sul lato sinistro del file denominato MainPage.xaml per UWP o MainWindows.xaml per WinUI 3.
  2. Fare doppio clic sul file denominato MainPage.xaml.cs o MainWindows.xaml.cs.
  3. Aggiungere i comandi seguenti nella parte inferiore delle istruzioni correnti using.
using Azure.Communication.Calling.WindowsClient;

Mantenere aperto MainPage.xaml.cs o MainWindows.xaml.cs. I passaggi successivi aggiungono altro codice.

Abilitare le interazioni con le app

I pulsanti dell'interfaccia utente aggiunti in precedenza devono operare sopra un CommunicationCall posizionato. Significa che un membro dati CommunicationCall deve essere aggiunto alla classe MainPage o MainWindow. Inoltre, per consentire all'operazione asincrona che crea CallAgent di avere esito positivo, è necessario aggiungere anche un membro dati CallAgent alla stessa classe.

Aggiungere i membri dati seguenti alla classe MainPage pr MainWindow:

CallAgent callAgent;
CommunicationCall call;

Creare gestori di pulsanti

In precedenza, sono stati aggiunti al codice XAML due pulsanti dell'interfaccia utente. Il codice seguente aggiunge i gestori da eseguire quando un utente seleziona il pulsante. Il codice seguente deve essere aggiunto dopo i membri di dati della sezione precedente.

private async void CallButton_Click(object sender, RoutedEventArgs e)
{
    // Start call
}

private async void HangupButton_Click(object sender, RoutedEventArgs e)
{
    // End the current call
}

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità della libreria client Chiamate di Servizi di comunicazione di Azure per UWP.

Nome Descrizione
CallClient CallClient è il principale punto di ingresso alla libreria client Chiamate.
CallAgent Il CallAgent viene usato per avviare e unire chiamate.
CommunicationCall L'oggetto CommunicationCall viene utilizzato per gestire le chiamate inserite o unite in join.
CommunicationTokenCredential CommunicationTokenCredential viene utilizzato come credenziale di token per istanziare CallAgent.
CallAgentOptions CallAgentOptions Contiene informazioni per identificare il chiamante.
HangupOptions HangupOptions Informa tutti i partecipanti se una chiamata deve essere terminata.

Inizializzare CallAgent

Per creare un'istanza di CallAgent da un CallClient, è necessario usare il metodo CallClient.CreateCallAgentAsync che restituisce in modo asincrono un oggetto CallAgent dopo l'inizializzazione.

Per creare CallAgent, è necessario passare un oggetto CallTokenCredential e un oggetto CallAgentOptions. Tenere presente che viene generato CallTokenCredential se viene passato un token non valido.

Per chiamare durante l'inizializzazione dell'app, aggiungere il codice seguente all'interno di una funzione helper.

var callClient = new CallClient();
this.deviceManager = await callClient.GetDeviceManagerAsync();

var tokenCredential = new CallTokenCredential("<AUTHENTICATION_TOKEN>");
var callAgentOptions = new CallAgentOptions()
{
    DisplayName = "<DISPLAY_NAME>"
};

this.callAgent = await callClient.CreateCallAgentAsync(tokenCredential, callAgentOptions);

Modificare <AUTHENTICATION_TOKEN> con un token di credenziali valido per la risorsa. Se è necessario creare un token di credenziali, vedere token di accesso utente.

Creare CallAgent ed effettuare una chiamata

Gli oggetti necessari per creare un CallAgent sono ora pronti. È il momento di creare CallAgent in modo asincrono ed effettuare una chiamata.

Aggiungere il codice seguente dopo aver gestito l'eccezione del passaggio precedente.

var startCallOptions = new StartCallOptions();
var callees = new [] { new UserCallIdentifier(CalleeTextBox.Text.Trim()) };

this.call = await this.callAgent.StartCallAsync(callees, startCallOptions);
this.call.OnStateChanged += Call_OnStateChangedAsync;

Usare 8:echo123 per comunicare con il bot echo di Servizi di comunicazione di Azure.

Disattivare e riattivare l'audio

Per disattivare o riattivare l'audio in uscita, usare le operazioni asincrone MuteOutgoingAudioAsync e UnmuteOutgoingAudioAsync.

// mute outgoing audio
await this.call.MuteOutgoingAudioAsync();

// unmute outgoing audio
await this.call.UnmuteOutgoingAudioAsync();

Disattivare l'audio per altri partecipanti

Nota

Usare l'SDK Android di chiamata di Servizi di comunicazione di Azure versione 1.9.0 o successive.

Quando l'audio di un partecipante PSTN viene disattivato, il partecipante deve ricevere un annuncio indicante che il suo audio è stato disattivato e che può premere una combinazione di tasti, ad esempio (*6) per riattivarlo. Quando preme *6, l'audio deve essere riattivato.

Per disattivare tutti gli altri partecipanti o disattivare un partecipante specifico, usare le operazioni MuteAllRemoteParticipantsAsync asincrone sulla chiamata e MuteAsync sul partecipante remoto:

// mute all participants except yourself
await this.call.MuteAllRemoteParticipantsAsync();

// mute specific participant in the call
await this.call.RemoteParticipants.FirstOrDefault().MuteAsync();

Per notificare al partecipante locale che il suo audio è stato disattivato da altri, eseguire la sottoscrizione all'evento MutedByOthers.

Terminare una chiamata

Utilizzare il metodo HangupAsync dell'oggetto CommunicationCall per terminare la chiamata una volta effettuata.

Utilizzare un'istanza di HangupOptions per informare tutti i partecipanti se la chiamata deve essere terminata.

Aggiungere il seguente codice dentro HangupButton_Click:

this.call.OnStateChanged -= Call_OnStateChangedAsync;
await this.call.HangUpAsync(new HangUpOptions() { ForEveryone = false });

Eseguire il codice

  1. Assicurarsi che Visual Studio compili l'app per x64, x86 o ARM64.
  2. Premere F5 per avviare l'esecuzione dell'app.
  3. Quando l'app è in esecuzione, fare clic sul pulsante Chiama per inserire una chiamata al destinatario definito.

La prima volta che l'app viene eseguita, il sistema chiede all'utente di concedere l'accesso al microfono.

Passaggi successivi