Condividi tramite

Gestire le chiamate

  • Articolo

Informazioni su come gestire chiamate con SDK di Servizi di comunicazione di Azure. Si apprenderà come effettuare chiamate e gestirne i partecipanti e le proprietà.

Prerequisiti

Installazione dell'SDK

Usare il comando npm install per installare SDK comuni e di chiamata di Servizi di comunicazione di Azure per 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()

Come gestire al meglio 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 a Microsoft infrascture, 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

Controllare 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 chiamata alla sala

Per unirsi a una room chiamata, creare un'istanza di contesto di ambiente con la proprietà roomId come identificatore room. Per unire la chiamata, usare il metodo join e passare l'istanza del 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 su rooms, leggere la documentazione concettuale o seguire la guida di avvio rapido.

Partecipare a una chiamata di gruppo

Nota

Il parametro groupId è considerato come metadati di sistema e può essere 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 valore groupId 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.

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

Mettere in attesa e riprendere una chiamata

Nota

Dovrebbe essere presente sempre soltanto una chiamata attiva (in stato Connected, con supporti attivi). Tutte le altre chiamate devono essere messe in attesa da un utente o a livello di codice per applicazione. Questo è comune in scenari come contact center, in cui un utente potrebbe dover gestire più chiamate in uscita e in ingresso; tutte le chiamate inattive devono essere messe in attesa e l'utente deve interagire con altri utenti solo nella chiamata attiva

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

Per mettere in attesa la chiamata

await call.hold();

Quando l'API hold viene risolta, lo stato della chiamata viene impostato su LocalHold. In una chiamata 1:1, A anche 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. Per riprendere la chiamata, tutti gli utenti che hanno messo in attesa la chiamata devono riprenderla.

Per riprendere la chiamata dopo averla messa in attesa:

await call.resume();

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

Disattivare e disattivare l'audio di una chiamata

Per disattivare o attivare 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

Disattiva audio in ingresso imposta il volume di chiamata su 0. Per disattivare o attivare l'audio in ingresso, usare le API 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 trasmesso nell'altoparlante e il partecipante non è in grado di ascoltare finché 'call.unmuteIncomingAudio()' non viene chiamato. Tuttavia, è possibile applicare un filtro all'audio delle chiamate e riprodurre l'audio filtrato.

Gestire partecipanti remoti

Tutti i partecipanti remoti sono descritti in dettaglio nell'oggetto RemoteParticipant e disponibili tramite la raccolta remoteParticipants in un'istanza di chiamata. remoteParticipants è accessibile da un'istanza di 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'API addParticipant. Specificare uno dei tipi Identifier. Restituisce in modo sincrono l'istanza remoteParticipant. L'evento remoteParticipantsUpdated da chiamata viene generato quando un partecipante viene aggiunto correttamente alla chiamata.

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, richiamare 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: ottiene l'identificatore per un partecipante in 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: la chiamata al partecipante sta squillando.
    • Connected: il partecipante è connesso alla chiamata.
    • Hold: il partecipante è in attesa.
    • EarlyMedia: annuncio riprodotto prima che un partecipante si connetta alla chiamata.
    • InLobby: indica che il partecipante in remoto si trova nella sala di 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 avvia UserC, dal punto di vista di UserA, UserA non visualizza 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, controllare la proprietà displayName stringa restituita.

    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 in remoto potrebbe trovarsi nella chiamata da molti endpoint, ciascuno con il proprio participantId univoco. participantId è diverso dall'ID non elaborato RemoteParticipant.identifier.

Disattivare l'audio per altri partecipanti

Nota

Per usare questa API, usare il SDK Web di Servizi di comunicazione di Azure versione 1.26.1 o successive.

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

Nota: scenari in cui si disattiva l’audio di partecipanti PSTN (numero di telefono) o partecipanti a chiamate 1:1 non sono supportati.

//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 in locale:

const participantId: string = call.info.participantId;

Nota: un'identità di Servizi di comunicazione di Azure può usare l'SDK per chiamate Web in molti endpoint, ciascuno con un proprio participantId univoco. 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 la chiamata sta squillando per i partecipanti in remoto. È 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 in 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 in 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 della chiamata finale. Se la connessione di rete va 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 e di condivisione dello schermo attivi controllando la raccolta localVideoStreams. L'API localVideoStreams restituisce oggetti LocalVideoStream di tipo Video, ScreenSharing o 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;

Installazione dell'SDK

Individuare il file a livello build.gradle di progetto e aggiungere mavenCentral() all'elenco dei repository in 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 metodo CallAgent.startCall() e fornire il Identifier del/i chiamato/i. Per partecipare a una chiamata di gruppo, è necessario chiamare il metodo CallAgent.join() e specificare il 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 sottoscrivere 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

Controllare 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 è necessario specificare il numero di telefono del chiamato. La risorsa di Servizi di comunicazione deve essere configurata per consentire 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 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();

La chiamata in ingresso può essere ottenuta sottoscrivendo l'evento onIncomingCall nell'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 chiamata alla sala

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

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 su rooms, leggere la documentazione concettuale o seguire la guida di avvio rapido.

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 metodo 'join' e passare un oggetto con una proprietà groupId. 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);

Chiamare proprietà

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 effettuata o accettata
  • “RINGING”: per una chiamata in uscita, indica che la chiamata sta squillando per i partecipanti in remoto
  • “CONNECTED”: la chiamata è connessa
  • “LOCAL_HOLD”: la chiamata è stata messa in attesa da parte del partecipante in locale, nessun elemento multimediale è in flusso tra l'endpoint locale e il/i partecipante/i in remoto
  • “REMOTE_HOLD”: la chiamata è stata messa in attesa da parte del partecipante in remoto, nessun elemento multimediale è in flusso tra l'endpoint locale e il/i partecipante/i in remoto
  • “DISCONNECTING”: stato di transizione prima che la chiamata passi allo stato "Disconnesso"
  • “DISCONNECTED”: stato della chiamata finale
  • “IN_LOBBY”: nella sala di attesa per l'interoperabilità di una riunione di Teams

Per informazioni sul 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 attivare l'audio

Per disattivare o attivare l'audio dell'endpoint locale, 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 si è in chiamata, i tasti per il volume hardware presenti sul telefono dovrebbero consentire all'utente di modificare il volume delle chiamate. A tale scopo, usare il metodo setVolumeControlStream con il tipo di flusso AudioManager.STREAM_VOICE_CALL nell'attività in cui viene effettuata la chiamata. Ciò consente ai tasti del volume hardware di modificare il volume della chiamata (indicata da un'icona telefono o simili nel dispositivo di scorrimento del volume), impedendo di modificare il volume per altri profili audio, ad esempio sveglie, file multimediali o volume a livello di sistema. Per altre informazioni, consultare 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 in remoto sono rappresentati dal tipo RemoteParticipant e sono 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), richiamare addParticipant. Questo restituirà in modo sincrono l'istanza del partecipante in 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) richiamare removeParticipant. Questa operazione verrà risolta in modo asincrono dopo che il partecipante viene rimosso dalla chiamata. Il partecipante verrà 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 in remoto

Ogni partecipante in remoto ha un set di proprietà e raccolte associato:

  • Ottenere l'identificatore per questo partecipante in remoto. L’identità è uno dei tipi 'Identifier'

    CommunicationIdentifier participantIdentifier = remoteParticipant.getIdentifier();

  • Ottenere lo stato di questo partecipante remoto.

    ParticipantState state = remoteParticipant.getState();

Lo stato può essere uno tra

  • “IDLE”: stato iniziale

  • “EARLY_MEDIA”: un annuncio viene riprodotto prima che il partecipante sia connesso alla chiamata

  • “RINGING”: la chiamata sta squillando per il partecipante

  • “CONNECTING”: stato di transizione mentre il partecipante si connette alla chiamata

  • “CONNECTED”: il partecipante è connesso alla chiamata

  • “HOLD”: il partecipante è in attesa

  • “IN_LOBBY”: il partecipante è nella sala d'attesa, in attesa di 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

Per usare questa API, usare l'Android SDK di Servizi di comunicazione di Azure versione 2.11.0 o successive.

Per disattivare l’audio per tutti gli altri partecipanti in una chiamata, usare l'API sulla chiamata muteAllRemoteParticipants.

call.muteAllRemoteParticipants();

Per disattivare l'audio per un determinato partecipante in remoto, usare l'API mute sul partecipante remoto.

remoteParticipant.mute();

Per notificare al partecipante in locale che il suo audio è stato disattivato da altri utenti, sottoscrivere all'evento onMutedByOthers.

Uso di Servizi in foreground

Nei casi in cui si voglia eseguire un'attività visibile all'utente anche quando l'applicazione è in background, usare Servizi in foreground.

Usando Servizi in foreground è ad esempio possibile mantenere visibile una notifica all'utente quando l'applicazione ha una chiamata attiva. In questo modo, anche se l'utente passa alla schermata home o rimuove l'applicazione dalla schermata recenti, la chiamata continuerà ad essere attiva.

Se non si usa un Servizio in foreground durante una chiamata, passare alla schermata iniziale può mantenere attiva la chiamata, ma la rimozione dell'applicazione dalla schermata recente può arrestare la chiamata se il sistema operativo Android termina il processo dell'applicazione.

È necessario avviare il Servizio in foreground all'avvio/aggiunta di una chiamata, ad esempio:

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

Arrestare il Servizio in foreground quando si termina la chiamata o lo stato della chiamata è Disconnesso, ad esempio:

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

Note sull'uso di Servizi in foreground

Tenere presente che scenari come l'arresto di un Servizio in foreground già in esecuzione quando l'app viene rimossa dall'elenco recenti rimuoveranno la notifica visibile all'utente; il sistema operativo Android può mantenere attivo il processo dell'applicazione per un periodo di tempo aggiuntivo, ovvero che la chiamata può ancora essere attiva durante questo periodo.

Se l'applicazione arresta il Servizio in foreground nel metodo onTaskRemoved del servizio — ad esempio, l'applicazione può avviare/arrestare audio e video in base al Ciclo di vita dell'attività, come l'arresto dell'audio e del video quando l'attività viene eliminata definitivamente 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

Aprire il file del ContentView.swift 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 contenere un riferimento sicuro agli oggetti che richiedono sottoscrizioni di eventi. Ad esempio, quando un oggetto RemoteParticipant viene restituito richiamando il metodo call.addParticipant e l'applicazione imposta il delegato in ascolto su RemoteParticipantDelegate, l'applicazione deve contenere un riferimento sicuro all'oggetto RemoteParticipant. In caso contrario, se questo oggetto viene raccolto, il delegato genererà un'eccezione irreversibile quando l'SDK Chiamante tenta di richiamare 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 riceverà un'istanza di chiamata che consente di sottoscrivere a tutti gli eventi nella chiamata.

Effettuare una chiamata 1:1 a un utente o a una chiamata 1:n con utenti e 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

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

Per effettuare la chiamata a PSTN, è 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 chiamata alla sala

Per unire una chiamata room, specificare la proprietà roomId come identificatore room. Per unire la chiamata, usare 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 su rooms, leggere la documentazione concettuale o seguire la guida di avvio rapido.

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

Sottoscrivere 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 varie operazioni durante una chiamata per gestire le impostazioni relative a video e audio.

Disattivare e attivare l'audio

Per disattivare o attivare 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 attivare 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

Tutti i partecipanti remoti sono rappresentati con il tipo RemoteParticipant e sono disponibili tramite la raccolta remoteParticipants in 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 (un utente o un numero di telefono), richiamare addParticipant. Questo comando restituirà in modo sincrono un'istanza del partecipante in remoto.

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

Rimuovere un partecipante da una chiamata

Per rimuovere un partecipante da una chiamata, (un utente o un numero di telefono) richiamare l’API removeParticipant. Ciò verrà risolto 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 in remoto

// [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

Per usare questa API, usare l'SDK iOS di Servizi di comunicazione di Azure versione 2.13.0 o successive.

Per disattivare l’audio per tutti gli altri partecipanti in una chiamata, usare l'API sulla chiamata muteAllRemoteParticipants.

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

Per disattivare l'audio per un determinato partecipante in remoto, usare l'API mute sul partecipante remoto.

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

Per notificare al partecipante in locale che il suo audio è stato disattivato da altri utenti, sottoscrivere all'evento onMutedByOthers.

Configurare il sistema

Seguire questa procedura per configurare il sistema.

Creare il progetto di Visual Studio

Per un'app piattaforma UWP (Universal Windows Platform), in Visual Studio 2022 creare un nuovo progetto App vuota (Windows universale). 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 di SDK 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.WindowsClient 1.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.

Richiedere l'accesso al microfono

L'app richiede l'accesso al microfono perché possa essere eseguita correttamente. Nelle app UWP, la funzionalità microfono deve essere dichiarata nel file manifesto dell'app.

I passaggi seguenti esemplificano come ottenere questo risultato.

  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 semplice app di esempio contiene due pulsanti. Uno per effettuare la chiamata e un altro per terminarla. La procedura seguente illustra come aggiungere questi 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 come dall'estratto seguente:
<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>

Configurazione dell'app con le API dell'SDK per chiamate

Le API dell’SDK per chiamate si trovano in due spazi dei nomi diversi. La procedura seguente informa il compilatore C# in proposito a questi spazi dei nomi, consentendo a IntelliSense di Visual Studio di supportare lo sviluppo di 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 MainPage.xaml.cs o MainWindows.xaml.cs aperti. I passaggi successivi aggiungeranno ulteriore codice.

Consenti interazioni con le app

I pulsanti dell'interfaccia utente aggiunti in precedenza devono operare sopra una CommunicationCall effettuata. 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 usato come credenziale del token per creare un'istanza di 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 CallTokenCredential genera un'eccezione se viene passato un token in formato non valido.

Il codice seguente deve essere aggiunto all'interno e alla funzione helper da chiamare nell'inizializzazione dell'app.

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. Fare riferimento alla documentazione del token di accesso utente se si necessita di creare un token di credenziali.

Creare CallAgent ed effettuare una chiamata

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

Dopo aver gestito l'eccezione del passaggio precedente, è necessario aggiungere il codice seguente.

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;

È possibile usare 8:echo123 per comunicare con il bot echo di Servizi di comunicazione di Azure.

Disattivare e attivare l'audio

Per disattivare o attivare l'audio in uscita, usare le API 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

Per usare questa API, usare l'SDK Windows di Servizi di comunicazione di Azure versione 1.9.0 o successive.

Per disattivare l’audio per tutti gli altri partecipanti o per un partecipante specifico, usare le API asincrone MuteAllRemoteParticipantsAsync sulla chiamata e MuteAsync sul partecipante in 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 in locale che il suo audio è stato disattivato da altri utenti, sottoscrivere all'evento MutedByOthers.

Terminare una chiamata

Una volta effettuata una chiamata, utilizzare il metodo HangupAsync dell'oggetto CommunicationCall per terminarla.

È inoltre necessario utilizzare un'istanza di HangupOptions per informare tutti i partecipanti se la chiamata deve essere terminata.

Il codice seguente deve essere aggiunto all'interno di HangupButton_Click.

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

Eseguire il codice

Assicurarsi che Visual Studio compili l'app per x64, x86 o ARM64, quindi premere F5 per avviare l'esecuzione dell'app. Successivamente, fare clic sul pulsante Call per inserire una chiamata al chiamato definito.

Tenere presente che alla prima esecuzione dell’app, il sistema chiede all'utente di concedere l'accesso al microfono.

Passaggi successivi