Gestire le chiamate

  • Articolo

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

Prerequisiti

Installazione dell'SDK

Usare il npm install comando per installare gli SDK comuni e chiamante 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 CallClient di . In questo caso si crea una nuova CallClient istanza. È possibile configurarlo con opzioni personalizzate come un'istanza Logger di .

Quando si dispone di un'istanza CallClient di , è possibile creare un'istanza CallAgent chiamando il metodo nell'istanza createCallAgentCallClient di . Questo metodo restituisce in modo asincrono un CallAgent oggetto istanza.

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

È possibile usare il metodo nell'istanza getDeviceManagerCallClient di per accedere deviceManagera .

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

Effettua una chiamata

Per creare e avviare una chiamata, usare una delle API in callAgent e fornire un utente creato tramite Communication Services Identity SDK.

La creazione e l'avvio delle chiamate sono sincrone. L'istanza call consente di sottoscrivere gli 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 startCall metodo su callAgent e passare il destinatario creato con la libreria di amministrazione di CommunicationUserIdentifierServizi 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 PSTN (Public Switched Telephone Network), usare il startCall metodo su callAgent e passare il destinatario.PhoneNumberIdentifier La risorsa di Servizi di comunicazione deve essere configurata per consentire le chiamate PSTN.

Quando si chiama un numero PSTN, specificare l'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 vede per una chiamata in arrivo.

Nota

Controllare i dettagli dell'offerta di chiamate PSTN. Per l'accesso al programma di anteprima, applicare 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 unire una room chiamata, è possibile creare un'istanza di un oggetto contesto con la roomId proprietà come room identificatore. Per unire la chiamata, usare il join metodo e passare l'istanza del contesto.

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

Un'applicazione room consente agli sviluppatori di applicazioni di controllare meglio chi può partecipare a una chiamata, quando si incontrano e come collaborano. Per altre informazioni su rooms, è possibile leggere la documentazione concettuale o seguire la guida introduttiva.

Partecipare a una chiamata di gruppo

Nota

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

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

Per avviare una nuova chiamata di gruppo o partecipare a una chiamata di gruppo in corso, utilizzare il join metodo e passare un oggetto con una groupId proprietà . 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 incomingCall evento 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 include un'istanza incomingCallincomingCall che è possibile accettare o rifiutare.

All'avvio, all'aggiunta o all'accettazione di una chiamata con video attivato, se la fotocamera viene usata da un altro processo o se è disabilitata nel sistema operativo, la chiamata inizia con video disattivato e viene generata una videocameraStartFailed: viene generata una vera diagnostica delle chiamate.

Blocco e ripresa chiamata

Nota

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

Per mantenere o riprendere la chiamata, è possibile usare le hold API asincrone e resume :

Per contenere la chiamata

await call.hold();

Quando hold l'API viene risolta, lo stato della chiamata verrà impostato su LocalHold, se si tratta di una chiamata 1:1, l'altro partecipante verrà messo in attesa e lo stato della chiamata dal punto di vista del partecipante verrà impostato su 'RemoteHold'. L'altro partecipante può ulteriormente mettere in attesa la chiamata, con conseguente modifica dello stato in LocalHold. Se si tratta di una chiamata di gruppo, è hold solo un'operazione locale, non conterrà la chiamata ad altri partecipanti di tale chiamata. Per riprendere completamente la chiamata a tutti gli utenti che hanno avviato il blocco devono riprenderlo.

Per riprendere la chiamata dal blocco:

await call.resume();

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

Disattivare e disattivare l'audio di una chiamata

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

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

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

Disattivare e disattivare l'audio in ingresso

Disattivare l'audio in ingresso imposta il volume di chiamata su 0. Per disattivare o disattivare l'audio in ingresso, è possibile usare le muteIncomingAudio API asincrone 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 riceverà comunque l'audio della chiamata (audio del partecipante remoto). L'audio della chiamata non verrà sentito nell'altoparlante e il partecipante non sarà in grado di ascoltare finché non viene chiamato 'call.unmuteIncomingAudio()'. Tuttavia, è possibile applicare un filtro all'audio delle chiamate e riprodurre l'audio filtrato.

Disattivare l'audio di altri partecipanti

Nota

Questa API viene fornita come anteprima per gli sviluppatori e potrebbe essere modificata in base ai commenti ricevuti. Per usare questa API, usare la versione 'beta' di Servizi di comunicazione di Azure Calling Web SDK versione 1.18.1 o successiva.

Per disattivare tutti gli altri partecipanti o disattivare un partecipante specifico, è possibile usare le API muteAllRemoteParticipants asincrone sulla chiamata e mute sul partecipante remoto:

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

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

Gestire i partecipanti remoti

Tutti i partecipanti remoti sono descritti in dettaglio nell'API RemoteParticipant e disponibili tramite la raccolta in un'istanza remoteParticipants di chiamata.

Elencare i partecipanti in una chiamata

La remoteParticipants raccolta restituisce un elenco di partecipanti remoti in 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, è possibile usare l'API addParticipant . Specificare uno dei Identifier tipi. Restituisce in modo sincrono l'istanza remoteParticipant di . L'evento remoteParticipantsUpdated da Call 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 remoteParticipant = call.addParticipant(pstnIdentifier, {alternateCallerId: '<ALTERNATE_CALLER_ID>'});

Rimuovere un partecipante da una chiamata

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

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 remoto. Identity è uno dei CommunicationIdentifier tipi seguenti:
const identifier = remoteParticipant.identifier;

  • Può essere uno dei tipi seguenti CommunicationIdentifier :

    • { communicationUserId: '<ACS_USER_ID'> }: oggetto che rappresenta l'utente 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 l'identificatore che non rientra negli altri tipi di identificatore

  • state: ottiene lo stato di un partecipante 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 suonando.
    • 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 remoto si trova nella sala di attesa.
    • Disconnected: stato finale. Il partecipante viene disconnesso dalla chiamata. Se il partecipante remoto perde la connettività di rete, lo stato diventa Disconnected dopo due minuti.

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

    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 rifiuta ad esempio.
    • Nello scenario in cui, ad esempio, UserB avvia UserC, dal punto di vista di UserA, UserA non visualizzerà questo flag impostato per UserC. In altre parole, UserA non visualizzerà la proprietà callEndReason di UserC impostata.

  • isMuted status: per scoprire se un partecipante remoto è disattivato, controllare la isMuted proprietà . Restituisce Boolean.

    const isMuted = remoteParticipant.isMuted;

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

    const isSpeaking = remoteParticipant.isSpeaking;

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

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

  • displayName: per ottenere il nome visualizzato per questo partecipante remoto, controllare la displayName proprietà restituita stringa.

    const displayName = remoteParticipant.displayName;

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

        const endpointDetails: EndpointDetails[] = remoteParticipant.endpointDetails;

    Nota: un partecipante remoto potrebbe trovarsi nella chiamata da molti endpoint e ogni endpoint avrà un proprio univoco participantId. participantId è diverso dall'ID non elaborato di RemoteParticipant.identifier.

Controllare le proprietà delle chiamate

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à Servizi di comunicazione di Azure può usare l'SDK per chiamate Web in molti endpoint e ogni endpoint avrà un proprio univoco participantId. participantIdè diverso dall'ID non elaborato dell'identità Servizi di comunicazione di Azure.

Recuperare l'ID del thread se si partecipa 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 nell'istanza remoteParticipants 'call':

const remoteParticipants = call.remoteParticipants;

Identificare il chiamante di una chiamata in ingresso:

const callerIdentity = call.callerInfo.identifier;

identifier è uno dei CommunicationIdentifier tipi .

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 inserita o accettata una chiamata.
  • Ringing: per una chiamata in uscita, indica che una chiamata sta suonando per i partecipanti remoti. Incoming È dalla loro parte.
  • 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 la chiamata viene sospesa da un partecipante locale. Nessun supporto viene propagato tra l'endpoint locale e i partecipanti remoti.
  • RemoteHold: indica che la chiamata è stata sospesa dal partecipante remoto. Nessun supporto viene propagato tra l'endpoint locale e i partecipanti remoti.
  • InLobby: indica che l'utente è nella sala di attesa.
  • Disconnecting: stato di transizione prima che la chiamata passi a uno Disconnected stato.
  • Disconnected: stato della chiamata finale. Se la connessione di rete viene persa, lo stato diventa Disconnected dopo due minuti.

Scopri perché una chiamata è terminata controllando la callEndReason proprietà :

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

Informazioni su se la chiamata corrente è in ingresso o in uscita esaminando la direction proprietà . 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 localVideoStreams raccolta. L'API localVideoStreams restituisce LocalVideoStream oggetti o tipo Videoo ScreenSharingRawMedia.

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;

Controlla se il video è attivo. Restituisce Boolean.

const isLocalVideoStarted = call.isLocalVideoStarted;

Verifica che la condivisione dello schermo sia attivata. Restituisce Boolean.

const isScreenSharingOn = call.isScreenSharingOn;

Installazione dell'SDK

Individuare il file build.gradle a livello di progetto e aggiungere mavenCentral() all'elenco dei repository in buildscript e allprojects:

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

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

Quindi, nel file build.gradle a livello 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 di , è necessario chiamare il metodo in un'istanza createCallAgentCallClient di . Questa chiamata restituisce in modo asincrono un CallAgent oggetto istanza.

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

Per accedere a DeviceManager, è prima necessario creare un'istanza callAgent di . È quindi possibile usare il CallClient.getDeviceManager metodo 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 un 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 e fornire il del chiamato.to create and start a call you need to call the CallAgent.startCall() method and provide the Identifier of the callee/s. Per partecipare a una chiamata di gruppo, è necessario chiamare il CallAgent.join() metodo e specificare il groupId. Gli ID gruppo devono essere in formato GUID o UUID.

La creazione e l'avvio delle chiamate sono sincrone. L'istanza di chiamata consente di sottoscrivere 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 call metodo su callAgent e passare un oggetto con communicationUserId chiave.

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 al programma di anteprima, applicare 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 su:

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 sull'oggetto onIncomingCallcallAgent :

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

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

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

Un'applicazione room consente agli sviluppatori di applicazioni di controllare meglio chi può partecipare a una chiamata, quando si incontrano e come collaborano. Per altre informazioni su rooms, è possibile leggere la documentazione concettuale o seguire la guida introduttiva.

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

Chiamare le proprietà

Ottenere l'ID univoco per questa chiamata:

String callId = call.getId();

Per informazioni su altri partecipanti nella raccolta di ispezione remoteParticipant delle chiamate nell'istanza call di :

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' - La chiamata è connessa
  • 'LOCAL_HOLD': la chiamata viene messa in attesa da parte del partecipante locale, nessun supporto sta fluendo tra l'endpoint locale e i partecipanti remoti
  • 'REMOTE_HOLD': la chiamata viene messa in attesa da un partecipante remoto, non viene eseguito alcun flusso multimediale tra l'endpoint locale e i partecipanti remoti
  • '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à delle riunioni di Teams

Per informazioni sul motivo per cui una chiamata è terminata, esaminare la callEndReason proprietà . 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 callDirection la proprietà :

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 muted proprietà :

boolean muted = call.isMuted();

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

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

Disattivare e attivare l'audio

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

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

Disattivare l'audio di altri partecipanti

Nota

Questa API viene fornita come anteprima pubblica per gli sviluppatori e può cambiare in base al feedback ricevuto. Per usare questa API, usare la versione 'beta' di Servizi di comunicazione di Azure Chiamata di Android SDK versione 2.6.0-beta.5 o successiva.

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

call.muteAllRemoteParticipants();

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

remoteParticipant.mute();

Modificare il volume della chiamata

Mentre si è in una chiamata, le chiavi del volume hardware sul telefono dovrebbero consentire all'utente di modificare il volume delle chiamate. A tale scopo, usare il metodo setVolumeControlStream con il tipo di AudioManager.STREAM_VOICE_CALL flusso nell'attività in cui viene inserita la chiamata. Ciò consente ai tasti del volume hardware di modificare il volume della chiamata (indicata da un'icona del telefono o qualcosa di simile nel dispositivo di scorrimento del volume), impedendo di modificare il volume per altri profili audio, ad esempio allarmi, supporti o volume a livello di sistema. Per altre informazioni, è possibile controllare Gestione delle modifiche nell'output audio | Sviluppatori Android.

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

Gestione dei partecipanti remoti

Tutti i partecipanti remoti sono rappresentati dal RemoteParticipant tipo e sono disponibili tramite la raccolta in un'istanza remoteParticipants di chiamata.

Elencare i partecipanti a una chiamata

La remoteParticipants raccolta restituisce un elenco di partecipanti remoti nella chiamata specificata:

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 richiamare addParticipant. Verrà restituita 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 richiamare removeParticipant. Questa operazione verrà risolta in modo asincrono dopo che il partecipante viene rimosso dalla chiamata. Il partecipante verrà rimosso anche dalla remoteParticipants raccolta.

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

Proprietà del partecipante remoto

A un partecipante remoto specificato è associato un set di proprietà e raccolte:

  • Ottenere l'identificatore per questo partecipante remoto. Identity è uno dei tipi 'Identifier'

    CommunicationIdentifier participantIdentifier = remoteParticipant.getIdentifier();

  • Ottenere lo stato di questo partecipante remoto.

    ParticipantState state = remoteParticipant.getState();

Lo stato può essere uno dei

  • 'IDLE' - stato iniziale

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

  • 'RINGING' - Chiamata partecipante squillante

  • '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 è 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 callEndReason la proprietà :

    CallEndReason callEndReason = remoteParticipant.getCallEndReason();

  • Per verificare se il partecipante remoto è disattivato o meno, controllare la isMuted proprietà :

    boolean isParticipantMuted = remoteParticipant.isMuted();

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

    boolean isParticipantSpeaking = remoteParticipant.isSpeaking();

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

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

Uso dei servizi in primo piano

Nei casi in cui si vuole eseguire un'attività visibile all'utente anche quando l'applicazione è in background, è possibile usare i servizi in primo piano.

Usando i servizi in primo piano, ad esempio, è possibile mantenere visibile una notifica dell'utente quando l'applicazione ha una chiamata attiva. In questo modo, anche se l'utente passa alla schermata iniziale o rimuove l'applicazione dalla schermata recente, la chiamata continuerà ad essere attiva.

Se non si usa un servizio in primo piano 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 primo piano all'avvio/aggiunta di una chiamata, ad esempio:

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

Arrestare il servizio in primo piano quando si blocca la chiamata o lo stato della chiamata è Disconnesso, ad esempio:

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

Note sull'uso di Servizi in primo piano

Tenere presente che gli scenari come l'arresto di un servizio in primo piano già in esecuzione quando l'app viene rimossa dall'elenco dei recenti, rimuoveranno la notifica visibile dell'utente e 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 primo piano nel metodo del servizio onTaskRemoved , ad esempio, l'applicazione può avviare/arrestare audio e video in base al ciclo di vita dell'attività , ad esempio l'arresto dell'audio e del video quando l'attività viene eliminata definitivamente con l'override del onDestroy metodo.

Configurare il sistema

Creare il progetto Xcode

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

Durante questa guida introduttiva non verranno creati test. Deselezionare la casella di controllo Includi 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 podfile per l'applicazione, come nell'esempio seguente:

    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à delle informazioni dell'app usando NSMicrophoneUsageDescription. Impostare il valore associato su una stringa che verrà 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 e quindi scegliere 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 ContentView.swift del progetto. Aggiungere una import dichiarazione all'inizio del file per importare la AzureCommunicationCalling libreria. Inoltre, importare AVFoundation. Sarà 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 callClient.createCallAgent metodo che restituisce in modo asincrono un CallAgent oggetto dopo l'inizializzazione.

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

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 a CallCliente 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 viene restituito un RemoteParticipant oggetto per richiamare il call.addParticipant metodo e l'applicazione imposta il delegato da ascoltare 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 in CallAgent e fornire l'identità di Servizi di comunicazione di un utente di cui è stato effettuato il provisioning usando Communication Services Management SDK.

La creazione e l'avvio delle chiamate sono sincrone. Si riceverà un'istanza di chiamata che consente di sottoscrivere 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 al programma di anteprima, applicare 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 room chiamata, specificare la roomId proprietà come room identificatore. Per unire la chiamata, usare il join metodo e passare .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)
    }
}

Un'applicazione room consente agli sviluppatori di applicazioni di controllare meglio chi può partecipare a una chiamata, quando si incontrano e come collaborano. Per altre informazioni su rooms, è possibile leggere la documentazione concettuale o seguire la guida introduttiva.

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 una chiamata in ingresso

Sottoscrivere 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 ingresso

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

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 mid-call

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

Disattivare e attivare l'audio

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

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

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

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

Disattivare l'audio di altri partecipanti

Nota

Questa API viene fornita come anteprima pubblica per gli sviluppatori e può cambiare in base al feedback ricevuto. Per usare questa API, usare la versione 'beta' di Servizi di comunicazione di Azure Calling iOS SDK versione 2.7.0-beta.3 o successiva.

Per disattivare tutti gli altri partecipanti in una chiamata, usare l'API muteAllRemoteParticipants nella 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'API mute in un determinato partecipante remoto.

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

Gestire i partecipanti remoti

Tutti i partecipanti remoti sono rappresentati dal RemoteParticipant tipo e sono disponibili tramite la raccolta in un'istanza remoteParticipants 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), è possibile richiamare addParticipant. Questo comando restituirà 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 (un utente o un numero di telefono), è possibile richiamare l'API removeParticipant . 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à dei 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, ...]

Configurare il sistema

Creare il progetto di Visual Studio

Per un'app UWP, 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, In pacchetto (WinUI 3 in Desktop) per configurare un'app WinUI 3 a pagina singola. SDK per app di Windows versione 1.3 o successiva è necessario.

Installare il pacchetto e le dipendenze usando NuGet Gestione pacchetti

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

I passaggi seguenti illustrano come trovare, scaricare e installare il pacchetto NuGet di Calling SDK:

  1. Aprire Gestione pacchetti NuGet selezionando Strumenti>NuGet Gestione pacchetti> 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 Azure.Communication.Calling.WindowsClient pacchetto 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 nella scheda a destra.
  6. Selezionare il pulsante Installa.

Richiedere l'accesso al microfono

L'app richiede l'accesso al microfono per l'esecuzione corretta. Nelle app UWP la funzionalità del microfono deve essere dichiarata nel file manifesto dell'app.

I passaggi seguenti esemplificano come ottenere questo risultato.

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

Creare pulsanti dell'interfaccia utente per posizionare e appendere la chiamata

Questa semplice app di esempio contiene due pulsanti. Uno per inserire la chiamata e un altro per appendere una chiamata inserita. La procedura seguente illustra come aggiungere questi pulsanti all'app.

  1. Solution Explorer Nel pannello 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 seguendo l'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 di Calling SDK si trovano in due spazi dei nomi diversi. La procedura seguente informa il compilatore C# su questi spazi dei nomi che consentono a IntelliSense di Visual Studio di supportare lo sviluppo di codice.

  1. Solution Explorer Nel pannello 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 aprire. I passaggi successivi aggiungeranno altro codice.

Consenti interazioni con le app

I pulsanti dell'interfaccia utente aggiunti in precedenza devono operare sopra un elemento posizionato CommunicationCall. Significa che un CommunicationCall membro dati deve essere aggiunto alla MainPage classe o MainWindow . Inoltre, per consentire la creazione CallAgent dell'operazione asincrona, è necessario aggiungere un CallAgent membro dati alla stessa classe.

Aggiungere i membri dati seguenti alla MainPage classe pr MainWindow :

CallAgent callAgent;
CommunicationCall call;

Creare gestori di pulsanti

In precedenza, al codice XAML sono stati aggiunti 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 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 di chiamata Servizi di comunicazione di Azure per la piattaforma UWP.

Nome Descrizione
CallClient CallClient è il punto di ingresso principale della libreria client chiamante.
CallAgent Viene CallAgent utilizzato per avviare e partecipare alle chiamate.
CommunicationCall L'oggetto CommunicationCall viene utilizzato per gestire le chiamate inserite o unite in join.
CommunicationTokenCredential Viene CommunicationTokenCredential usato come credenziale del token per creare un'istanza di CallAgent.
CallAgentOptions CallAgentOptions Contiene informazioni per identificare il chiamante.
HangupOptions HangupOptions Informa se una chiamata deve essere terminata a tutti i partecipanti.

Inizializzare CallAgent

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

Per creare CallAgent, è necessario passare un CallTokenCredential oggetto e un CallAgentOptions oggetto . 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);

<AUTHENTICATION_TOKEN> Modificare con un token di credenziali valido per la risorsa. Fare riferimento alla documentazione del token di accesso utente se è necessario creare un token di credenziali.

Creare CallAgent e inserire una chiamata

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

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 parlare con il bot echo Servizi di comunicazione di Azure.

Disattivare e attivare l'audio

Per disattivare o disattivare l'audio in uscita, è possibile usare le MuteOutgoingAudioAsync API asincrone e UnmuteOutgoingAudioAsync :

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

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

Disattivare l'audio di altri partecipanti

Nota

Questa API viene fornita come anteprima pubblica per gli sviluppatori e può cambiare in base al feedback ricevuto. Per usare questa API, usare la versione 'beta' di Servizi di comunicazione di Azure Chiamata a Windows SDK versione 1.4.0-beta.1 o successiva.

Per disattivare tutti gli altri partecipanti o disattivare un partecipante specifico, è possibile usare le API 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();

Terminare una chiamata

Una volta inserita una chiamata, è necessario utilizzare il HangupAsync metodo dell'oggetto CommunicationCall per appendere la chiamata.

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

Il codice seguente deve essere aggiunto all'interno HangupButton_Clickdi .

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

Eseguire il codice

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

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

Passaggi successivi