Esercizio - Aggiungere il codice per chiamate vocali

  • 3 minuti

In questa unità si aggiunge altro codice all'app Web creata nell'unità precedente. Questa app consente di effettuare chiamate vocali tramite Servizi di comunicazione di Azure.

Aggiungere elementi HTML di input

Per effettuare una chiamata, sono necessarie due informazioni importanti:

  1. Un token di accesso utente di Servizi di comunicazione di Azure per l'utente che effettua la chiamata. Questo token identifica e autorizza l'utente a contattare il servizio e ad avviare una chiamata vocale.
  2. La persona che l'utente vuole chiamare (rappresentata da un ID utente di Servizi di comunicazione di Azure).

Per ottenere queste informazioni dall'utente, si usano alcuni input standard di un modulo HTML. Aggiungere questi input al file index.html:

  1. Aprire il file index.html in un editor di testo.

  2. Aggiungere il codice HTML seguente nel corpo del file HTML, dopo il commento <!-- Calling HTML here -->:

    <input 
    id="token-input"
    type="text"
    placeholder="Your User access token"
/>
<button id="token-submit" type="button">
    Submit
</button>
<br /><br />
<input 
    id="callee-id-input"
    type="text"
    placeholder="Who would you like to call?"
    style="margin-bottom:1em; width: 200px; display: block;"
/>

Il primo elemento di input è per il token dell'utente che effettua la chiamata. Il pulsante di invio viene utilizzato per attivare alcuni oggetti di Azure Communication Services una volta fornito il token. Il secondo elemento di input viene usato per immettere l'ID utente della persona che si vuole chiamare.

Aggiungere pulsanti di azione per chiamate di base

Sono inoltre necessari dei pulsanti per alcune azioni di chiamata di base che consentono all'utente di controllare la chiamata:

  1. Avvia chiamata
  2. Riaggancia

A questo punto, aggiungere anche questi pulsanti sotto gli elementi di input del passaggio precedente:

<button id="call-button" type="button" disabled="true">
    Start Call
</button>
&nbsp;
<button id="hang-up-button" type="button" disabled="true">
    Hang Up
</button>

Testare il codice HTML

Dopo aver immesso il codice HTML, è stata completata la maggior parte del codice per questa app. Se si esegue l'app immettendo lo stesso comando dell'unità precedente (npx parcel index.html) e quindi si apre l'app, si vedrà l'app seguente nel browser.

Screenshot dell'applicazione web vuota visualizzata in un browser.

Questa app non ha un aspetto molto simile, ma contiene tutti gli elementi visivi necessari per creare un'app per chiamate vocali. A questo punto si è terminato di inserire il codice HTML della propria applicazione. Il resto del codice è JavaScript.

Importare alcune dipendenze

Il primo passaggio all'interno del file app.js consiste nell'importare le dipendenze per effettuare chiamate con Servizi di comunicazione di Azure. Queste dipendenze provengono dagli SDK installati in precedenza usando npm. Per importarle, aggiungere le righe seguenti al file app.js:

import { CallClient } from "@azure/communication-calling";
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

La prima importazione è un elemento CallClient, da usare in seguito per effettuare le chiamate. Gestisce microfoni, audio e altro ancora per te. La seconda importazione, AzureCommunicationTokenCredential, viene usata per gestire i requisiti di autenticazione per Servizi di comunicazione di Azure. L'autenticazione consente di sapere chi è l'utente che effettua una chiamata.

Ottenere riferimenti al codice HTML

In precedenza sono stati creati degli elementi HTML che gli utenti possono usare per controllare l'app. Per ascoltare l'utente che interagisce con loro, è necessario ottenere dei riferimenti agli elementi in JavaScript.

Sono inoltre necessarie un paio di variabili che conterranno alcuni elementi, usati nel codice. Aggiungere il codice seguente a app.js dopo le istruzioni di importazione:

const userToken = document.getElementById("token-input"); 
const submitToken = document.getElementById("token-submit");

const calleeInput = document.getElementById("callee-id-input");

const callButton = document.getElementById("call-button");
const hangUpButton = document.getElementById("hang-up-button");

let call;
let callAgent;
let tokenCredential;

Gestire l'autenticazione

Dopo aver completato alcune impostazioni di base, è possibile iniziare a creare alcune funzionalità. La prima funzionalità necessaria è quella per gestire l'autenticazione. L'autenticazione viene gestita dall'utente che immette un token utente nell'elemento di input del token creato e quindi fa clic sul pulsante "Invia Token". Per gestire questo processo all'interno del codice, registrare un gestore clic per il pulsante di invio del token, che elabora il token utente. È possibile aggiungere questo codice dopo le definizioni delle variabili della sezione precedente:

submitToken.addEventListener("click", async () => {
  const callClient = new CallClient();
  const userTokenCredential = userToken.value;

  try {
    tokenCredential = new AzureCommunicationTokenCredential(userTokenCredential);
    callAgent = await callClient.createCallAgent(tokenCredential);
    callAgent.on('incomingCall', incomingCallHandler);

    callButton.disabled = false;
    submitToken.disabled = true;
  } catch(error) {
    window.alert("Please submit a valid token!");
  }
});

Questo codice esegue le azioni seguenti:

  1. Crea un client di chiamata di Servizi di comunicazione di Azure.
  2. Recupera il token utente dall'elemento di input del token e crea da esso un elemento AzureCommunicationTokenCredential. Queste credenziali vengono utilizzate per effettuare e gestire tutte le chiamate.
  3. Crea un elemento CallAgent, che viene usato per effettuare e ricevere chiamate.
  4. Registra un gestore di chiamate in arrivo, che verrà scritto a breve.
  5. Aggiorna alcuni dei pulsanti per consentire all'utente di procedere.

Effettua chiamate

Ora che l'autenticazione è stata risolta, puoi iniziare con delle funzionalità effettive. Per iniziare, consentire all'utente di effettuare una chiamata:

callButton.addEventListener("click", () => {
  // start a call
  const userToCall = calleeInput.value;
  call = callAgent.startCall(
    [{ id: userToCall }],
    {}
  );

  // toggle button states
  hangUpButton.disabled = false;
  callButton.disabled = true;
});

Questo codice consente di registrare un gestore di clic per il pulsante Avvia chiamata. Recupera l'ID chiamante dall'elemento di input corrispondente e quindi usa l'agente di chiamata per effettuare una chiamata.

Riaggancia

Dopo l'avvio di una chiamata, è necessario consentire all'utente di interromperla:

hangUpButton.addEventListener("click", () => {
  // end the current call
  call.hangUp({ forEveryone: true });

  // toggle button states
  hangUpButton.disabled = true;
  callButton.disabled = false;
});

Questo codice consente di registrare un gestore di clic per il pulsante Interrompi e quindi indica semplicemente alla chiamata di interrompersi.

Ricevere una chiamata

Ora che è possibile effettuare una chiamata, è necessario gestire anche la ricezione di una chiamata. Per gestire la ricezione di una chiamata, viene creato il gestore di chiamate in arrivo, come accennato in precedenza:

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

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

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

Testare l'app completata

Il codice JavaScript è stato completato ora. Eseguire l'app usando lo stesso comando dell'unità precedente (npx parcel index.html) e quindi aprire l'app nel browser. A questo punto si ha un'app per le chiamate di base funzionante!

Ottenere le credenziali di prova

Per testare l'esecuzione di una chiamata, sono necessarie alcune credenziali. È possibile ottenere le credenziali dal portale di Azure. Aprire la risorsa di Servizi di comunicazione di Azure nel portale di Azure e quindi selezionare Impostazioni>Identità e token di accesso utente nel menu del servizio di comunicazione:

Screenshot del portale di Azure che mostra l'opzione di menu Identità e token di accesso utente evidenziata.

Nella pagina visualizzata è possibile generare le credenziali di test. Per questa app è sufficiente disporre dell'autorizzazione per Chiamate vocali e videochiamate (VoIP), quindi controllare questa opzione e selezionare Genera:

Screenshot della finestra di generazione del token in cui è selezionata l'opzione VOIP.

Si ottiene una singola identità di Servizi di comunicazione di Azure, che è adatta per il test. Assicurarsi di copiare i valori di Identità e del Token di accesso utente in un punto sicuro per il test, ad esempio un documento di testo.

Screenshot della finestra di generazione del token in cui vengono visualizzate le credenziali di test.

Se si vuole provare a chiamare un altro utente, generare un set aggiuntivo di credenziali selezionando Genera di nuovo. I nuovi valori vengono creati nei campi Identità e Token di accesso utente.

Il primo set di credenziali viene usato per l'utente chiamante e il secondo set viene usato per l'utente ricevente.

In un'app reale è consigliabile usare i sistemi di gestione identità e le librerie client per creare e archiviare queste credenziali. In questo modo un utente reale non deve copiare e immettere manualmente questi elementi. Per altre informazioni su questo concetto, aprire i collegamenti alla fine di questo modulo.

Chiamare Echo Bot

In Servizi di comunicazione di Azure è presente un bot Echo Bot, che è possibile chiamare per testare il microfono. Echo Bot è compatibile con questa app. Per chiamare Echo Bot:

  1. Aprire l'app nel browser.
  2. Incollare un token salvato nell'elemento di input del token utente.
  3. Selezionare il pulsante Invia.
  4. Immettere l'ID utente di Echo Bot (8:echo123).
  5. Selezionare Avvia chiamata.

Il browser potrebbe visualizzare delle richieste in alcune finestre di dialogo di autorizzazione del microfono, quindi assicurarsi di accettarle. Se tutto funziona correttamente, si dovrebbe essere connessi a una chiamata con Echo Bot. Il bot consente di registrare un breve messaggio, che viene quindi riprodotto all'utente.

Chiamare un altro utente

È anche possibile chiamare un altro utente usando questa app. Questa azione richiede un secondo set di credenziali, generato in precedenza. Seguire questa procedura:

  1. Aprire due copie dell'app. Usare più schede o finestre per simulare la chiamata di un altro utente.
  2. Nella prima copia immettere il primo token utente salvato dal generatore di credenziali e quindi selezionare Invia.
  3. Nella seconda copia immettere il secondo token utente salvato dal generatore di credenziali, quindi selezionare Invia.
  4. Tornare alla prima copia e immettere il secondo ID utente nell'elemento di input Chi vuoi chiamare?.
  5. Nella prima copia, selezionare Avvia chiamata.

Se entrambe le schede o finestre si trovano nello stesso dispositivo, si potrebbe avvertire un eco nella chiamata, ma il processo e le chiamate sono funzionanti tra due schede del browser. Se si distribuisce l'app in un server Web accessibile a più computer, è possibile effettuare una vera e propria chiamata vocale senza eco.