Casi d'uso della libreria dell'interfaccia utente
Usare componenti e compositi nella libreria dell'interfaccia utente di Servizi di comunicazione di Azure per creare esperienze di chiamata e chat nelle applicazioni.
In un composito, le funzionalità di chiamata e chat sono integrate direttamente ed esposte quando si integra il composito in un'applicazione. In un componente dell'interfaccia utente, le funzionalità di chiamata e chat vengono esposte tramite una combinazione di funzionalità dell'interfaccia utente e librerie con stato sottostanti. Per sfruttare al meglio queste funzionalità, è consigliabile usare i componenti dell'interfaccia utente con librerie client di chat e chiamate con stato.
Ottenere altre documentazione concettuale, guide introduttive ed esempi nel storybook della libreria dell'interfaccia utente.
Casi d'uso delle chiamate
| Area | Utilizzare casi |
|---|---|
| Tipi di chiamata | Partecipare a una riunione di Microsoft Teams |
| Partecipare a una chiamata Servizi di comunicazione di Azure usando un ID gruppo | |
| Partecipa a una sala Servizi di comunicazione di Azure | |
| Avviare una chiamata in uscita a un altro utente Servizi di comunicazione di Azure | |
| Avviare una chiamata in uscita a un numero di telefono | |
| Interoperabilità di Teams | Partecipare alla sala di attesa delle chiamate |
| Visualizzare un banner di avviso di trascrizione e registrazione | |
| Controlli di chiamata | Disattivare e disattivare l'audio di una chiamata |
| Attivare e disattivare video durante una chiamata | |
| Attivare la condivisione dello schermo | |
| Terminare una chiamata | |
| Raccolta partecipanti | Mostra partecipanti remoti in una griglia |
| Rendere disponibile l'anteprima video durante una chiamata per un utente locale | |
| Rendere disponibili avatar predefiniti quando il video è disattivato | |
| Visualizzare il contenuto della schermata condivisa nella raccolta partecipanti | |
| Configurazione delle chiamate | Gestire il dispositivo microfono |
| Gestire il dispositivo fotocamera | |
| Gestire il dispositivo altoparlante | |
| Rendere disponibile l'anteprima locale per consentire all'utente di controllare il video | |
| Partecipanti | Mostra un elenco partecipanti |
Casi d'uso della chat
| Area | Chat di Servizi di comunicazione di Azure | Chat di interoperabilità di Teams |
|---|---|---|
| Tipi di chat | Aggiungere un thread di chat Servizi di comunicazione di Azure | Partecipare a una chat riunione di Microsoft Teams |
| Azioni di chat | Inviare e ricevere messaggi di testo | Inviare e ricevere messaggi di testo |
| Ricevere messaggi RTF | Ricevere messaggi RTF | |
| - | Ricevere immagini inline* | |
| Inviare e ricevere allegati di file | Ricevere allegati di file* | |
| Eventi di chat | Inviare e ricevere indicatori di digitazione | Inviare e ricevere indicatori di digitazione** |
| Inviare e ricevere ricevute di lettura | Inviare e ricevere ricevute di lettura | |
| Mostra quando un partecipante viene aggiunto o rimosso | Mostra quando un partecipante viene aggiunto o rimosso | |
| Partecipanti | Mostra un elenco partecipanti | Mostra un elenco partecipanti |
*Il supporto per immagini e file allegati inline è attualmente disponibile in anteprima pubblica. Le API di anteprima e gli SDK vengono forniti senza un contratto di servizio. È consigliabile non usarli per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per altre informazioni, vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.
**Il nome visualizzato dell'evento di digitazione dell'utente di Teams potrebbe non essere visualizzato correttamente.
Identità supportate
Per inizializzare un composito ed eseguire l'autenticazione al servizio, un utente deve avere un'identità Servizi di comunicazione di Azure. Per altre informazioni, vedere Eseguire l'autenticazione a Servizi di comunicazione di Azure e Avvio rapido: Creare e gestire i token di accesso.
Interoperabilità di Teams
Per gli scenari di interoperabilità di Teams, è possibile usare i compositi della libreria dell'interfaccia utente per aggiungere un utente a una riunione di Teams tramite Servizi di comunicazione. Per abilitare l'interoperabilità di Teams, usare le funzionalità predefinite della chiamata composita o composita della chat oppure usare i componenti dell'interfaccia utente per creare un'esperienza personalizzata.
Quando si aggiungono chiamate e chat a un'applicazione, è importante ricordare che il client di chat non può essere inizializzato fino a quando il partecipante non viene ammesso alla chiamata. Dopo che il partecipante è stato ammesso, il client di chat può essere inizializzato per partecipare al thread di chat della riunione. Il modello è illustrato nella figura seguente:
Se si usano i componenti dell'interfaccia utente per offrire esperienze di interoperabilità di Teams, iniziare usando esempi di libreria dell'interfaccia utente per creare componenti chiave dell'esperienza:
- Esempio di lobby. Sala di attesa di esempio in cui un partecipante può attendere di essere ammesso a una chiamata.
- Banner di conformità. Banner di esempio che mostra l'utente se la chiamata viene registrata.
- Tema di Teams. Un tema di esempio che rende gli elementi della libreria dell'interfaccia utente simili a Microsoft Teams.
- Condivisione di immagini*. Un esempio di utente finale del servizio di comunicazione di Azure può ricevere immagini inviate dall'utente di Teams.
- Condivisione file*. Un esempio di utente finale del servizio di comunicazione di Azure può ricevere allegati di file inviati dall'utente di Teams.
Personalizzazione
Usare i modelli di libreria dell'interfaccia utente per modificare i componenti in modo che corrispondano all'aspetto dell'applicazione. La personalizzazione è una differenza fondamentale tra i componenti compositi e dell'interfaccia utente in Servizi di comunicazione. I compositi hanno meno opzioni di personalizzazione per un'esperienza di integrazione più semplice.
La tabella seguente confronta i componenti compositi e dell'interfaccia utente per i casi d'uso di personalizzazione:
| Caso d'uso | Compositi | Componenti dell'interfaccia utente |
|---|---|---|
| Usare il tema basato su Fluent | X | X |
| Comporre il layout dell'esperienza | X | |
| Usare gli stili CSS per modificare le proprietà di stile | X | |
| Sostituisci icone | X | |
| Modificare il layout della raccolta partecipanti | X | |
| Modificare il layout del controllo delle chiamate | X | X |
| Inserire modelli di dati per modificare i metadati utente | X | X |
Osservabilità
L'architettura di gestione dello stato della libreria dell'interfaccia utente è disaccoppiata, quindi è possibile accedere direttamente ai client di chiamata e chat con stato. È possibile eseguire l'hook nel client con stato per leggere lo stato, gestire gli eventi ed eseguire l'override del comportamento da passare ai componenti dell'interfaccia utente.
La tabella seguente confronta i componenti compositi e dell'interfaccia utente per i casi d'uso di osservabilità:
| Caso d'uso | Compositi | Componenti dell'interfaccia utente |
|---|---|---|
| Accesso alla chiamata e allo stato del client di chat | X | X |
| Accedere e gestire gli eventi client | X | X |
| Accedere e gestire gli eventi dell'interfaccia utente | X | X |
Architettura consigliata
Inizializzare un componente composito e di base usando un token di accesso Servizi di comunicazione di Azure. È importante ottenere i token di accesso da Servizi di comunicazione tramite un servizio attendibile gestito. Per altre informazioni, vedere Avvio rapido: Creare e gestire i token di accesso e l'esercitazione sul servizio attendibile.
Le librerie client di chiamata e chat devono avere il contesto per la chiamata o la chat a cui partecipano. Analogamente ai token di accesso utente, distribuire il contesto ai client usando il proprio servizio attendibile.
La tabella seguente riepiloga le funzioni di inizializzazione e gestione delle risorse necessarie per aggiungere contesto a una libreria client:
| Responsabilità di Contoso | Responsabilità della libreria dell'interfaccia utente |
|---|---|
| Fornire un token di accesso da Azure | Passare il token di accesso fornito per inizializzare i componenti |
| Fornire una funzione di aggiornamento | Aggiornare il token di accesso usando una funzione fornita dallo sviluppatore |
| Recuperare e passare le informazioni di join per la chiamata o la chat | Passare le informazioni sulle chiamate e sulle chat per inizializzare i componenti |
| Recuperare e passare informazioni utente per qualsiasi modello di dati personalizzato | Passare un modello di dati personalizzato ai componenti di cui eseguire il rendering |
Piattaforme supportate
| SDK | Windows | macOS | Ubuntu | Linux | Android | iOS |
|---|---|---|---|---|---|---|
| SDK dell'interfaccia utente | Chrome*, Microsoft Edge | Chrome*, Safari** | Chrome* | Chrome* | Chrome* | Safari** |
* Sono supportate la versione corrente di Chrome e le due versioni precedenti.
** Sono supportati Safari versione 13.1 e versioni successive. Il video in uscita per Safari macOS non è ancora supportato, ma è supportato per iOS. La condivisione dello schermo in uscita è supportata solo in iOS desktop.
Accessibilità
L'accessibilità per impostazione predefinita è un principio tra i prodotti Microsoft. La libreria dell'interfaccia utente segue questo principio e tutti i componenti dell'interfaccia utente sono completamente accessibili.
Localizzazione
La localizzazione è fondamentale per creare prodotti per gli utenti di tutto il mondo e che parlano lingue diverse. La libreria dell'interfaccia utente offre il supporto predefinito per alcune lingue e funzionalità, incluse le lingue da destra a sinistra. È possibile fornire i propri file di localizzazione da usare con la libreria dell'interfaccia utente.
CallComposite Usare e ChatComposite nella libreria dell'interfaccia utente di Servizi di comunicazione di Azure per creare esperienze di chiamata nelle applicazioni iOS e Android. Usando un paio di righe di codice, è possibile integrare facilmente un'intera esperienza di chiamata e chat nell'applicazione. I compositi in Servizi di comunicazione gestiscono l'intero ciclo di vita della chiamata e della chat, dalla configurazione fino alla fine della chiamata e della chat.
Casi d'uso per chiamate
È possibile usare la chiamata composita in Servizi di comunicazione per creare questi casi d'uso:
| Area | Utilizzare casi |
|---|---|
| Tipi di chiamata | Partecipare a una riunione di Microsoft Teams |
| Partecipare a una chiamata usando un ID gruppo | |
| Interoperabilità di Teams | Partecipare alla sala di attesa delle chiamate |
| Visualizzare un banner di avviso di trascrizione e registrazione | |
| Raccolta partecipanti | Mostra partecipanti remoti in una griglia |
| Rendere disponibile l'anteprima video durante una chiamata per un utente locale | |
| Rendere disponibili avatar predefiniti quando il video è disattivato | |
| Visualizzare il contenuto della schermata condivisa nella raccolta partecipanti | |
| Abilitare la personalizzazione dell'avatar dei partecipanti | |
| Mostra un elenco partecipanti | |
| Configurazione delle chiamate | Gestire il dispositivo microfono |
| Gestire il dispositivo fotocamera | |
| Gestire il dispositivo altoparlante (cablato o Bluetooth) | |
| Rendere disponibile l'anteprima locale per consentire a un utente di controllare il video | |
| Controlli di chiamata | Disattivare e disattivare l'audio di una chiamata |
| Attivare o disattivare video durante una chiamata | |
| Terminare una chiamata | |
| Tenere e riprendere una chiamata dopo l'interruzione dell'audio |
Interoperabilità di Teams
Per gli scenari di interoperabilità di Teams, è possibile usare i compositi della libreria dell'interfaccia utente per aggiungere un utente a una riunione di Teams tramite Servizi di comunicazione. Per abilitare l'interoperabilità di Teams, usare la chiamata composita. Il composito gestisce l'intero ciclo di vita dell'aggiunta a una chiamata di interoperabilità di Teams.
La figura seguente mostra un esempio dell'esperienza utente prima che un chiamante venga aggiunto a una riunione di Teams:
Visualizzare il contenuto condiviso
Tramite la libreria dell'interfaccia utente per le piattaforme native per dispositivi mobili, i partecipanti possono visualizzare il contenuto condiviso quando altri partecipanti condividono le schermate durante una chiamata di Teams. Un partecipante remoto può usare movimenti di avvicinamento e avvicinamento delle dita per ingrandire o ridurre il contenuto condiviso nella chiamata.
Temi
Puoi usare la chiamata della libreria dell'interfaccia utente composita per iOS e Android per creare un tema personalizzato dell'esperienza di un chiamante. Per creare l'esperienza della piattaforma, passare un set di colori di tema, come illustrato nella tabella seguente. Per altre informazioni, vedere Come creare il tema.
| Android | iOS |
|---|---|
|
|
Dimensioni schermo
È possibile adattare la Servizi di comunicazione di Azure chiamata composita per adattarsi alle dimensioni dello schermo da 5 pollici a tablet. Usare la modalità di divisione e la modalità tablet nella composizione delle chiamate per ottenere il layout del roster dei partecipanti dinamici, fornire chiarezza sulla visualizzazione e concentrarsi sulla conversazione.
| Modalità di divisione | Modalità tablet |
|---|---|
|
|
Localizzazione
La localizzazione è fondamentale per creare prodotti per gli utenti di tutto il mondo e che parlano lingue diverse. La libreria dell'interfaccia utente supporta 12 lingue: inglese, spagnolo, francese, tedesco, italiano, giapponese, coreano, olandese, portoghese, russo, turco e cinese. Supporta anche lingue da destra a sinistra. Per altre informazioni, vedere Come aggiungere la localizzazione all'app.
Accessibilità
L'accessibilità è un elemento chiave delle librerie di chiamate. È possibile usare un'utilità per la lettura dello schermo per fare annunci importanti sullo stato delle chiamate e per garantire che gli utenti con problemi di vista possano partecipare efficacemente quando usano l'applicazione.
Visualizzare l'inserimento dei dati
Usa la libreria dell'interfaccia utente per le piattaforme native per dispositivi mobili per offrire ai partecipanti locali e remoti la possibilità di personalizzare la modalità di visualizzazione come utenti in una chiamata. Un partecipante locale può scegliere un avatar locale, un nome visualizzato personalizzato, il titolo e il sottotitolo della navigazione nella schermata di installazione all'inizio di una chiamata. Un utente remoto può creare un avatar personalizzato quando partecipa alla riunione. Per altre informazioni, vedere Come personalizzare la visualizzazione pre-riunione.
Ignora schermata di installazione
La libreria dell'interfaccia utente offre la possibilità di partecipare a una chiamata ignorando la schermata di configurazione dell'esperienza di aggiunta alle chiamate. Per impostazione predefinita, l'utente passa attraverso una schermata di configurazione per partecipare a una chiamata. In questo caso, l'utente imposta la configurazione delle chiamate, ad esempio l'attivazione o la disattivazione del microfono, la selezione del microfono e del dispositivo audio prima di partecipare a una chiamata. Questa schermata richiede l'interazione dell'utente per partecipare a una chiamata, che potrebbe non essere necessaria per alcuni utenti. È quindi possibile partecipare a una chiamata ignorando la schermata di installazione e fornendo le API di configurazione delle chiamate. Per altre informazioni, vedere How to use Skip Setup Screen Feature
Modalità solo audio
La modalità solo audio nella libreria dell'interfaccia utente consente ai partecipanti di partecipare alle chiamate usando solo l'audio, senza condividere o ricevere video. Questa funzionalità viene usata per risparmiare larghezza di banda e ottimizzare la privacy. Se attivata, la modalità solo audio disabilita automaticamente le funzionalità video per l'invio e la ricezione di flussi e regola l'interfaccia utente in modo da riflettere questa modifica rimuovendo i controlli correlati al video. Questa modalità può essere abilitata tramite la configurazione CallComposite, altre informazioni disponibili tramite la guida introduttiva Solo audio
Orientamento
La libreria dell'interfaccia utente supporta la configurazione dell'orientamento dello schermo per ogni schermata separatamente prima di avviare l'esperienza della libreria. Ciò consente agli sviluppatori di applicazioni di configurare un orientamento fisso per l'esperienza chiamante che allinea l'orientamento dell'applicazione. Per altre informazioni sull'elenco dell'orientamento supportato per la piattaforma Android e iOS e l'uso dell'API, vedere Come usare la funzionalità di orientamento
Multitasking e immagine in-picture
La libreria dell'interfaccia utente supporta l'immagine in modalità immagine per la schermata di chiamata. Durante la chiamata, l'utente può fare clic sul pulsante Indietro nella schermata di chiamata per abilitare il multitasking che porterà l'utente alla schermata precedente. Se l'immagine in immagine è abilitata, verrà visualizzato un'immagine in-immagine di sistema per la chiamata. Per altre informazioni sul multitasking e sull'immagine in-picture per la piattaforma Android e iOS e l'uso dell'API, vedere Come usare l'immagine nell'immagine
Supporto di CallKit
La libreria dell'interfaccia utente supporta l'integrazione di CallKit per gestire l'interazione con CallKit per le chiamate. Per altre informazioni sull'integrazione per la piattaforma iOS e l'uso dell'API, vedere Come usare CallKit
Supporto per chiamate uno-a-uno e notifiche PUSH
La libreria dell'interfaccia utente supporta una chiamata VoIP uno-a-uno per comporre gli utenti tramite identificatore di comunicazione. Per ricevere la libreria dell'interfaccia utente delle chiamate in ingresso supporta anche la registrazione per le notifiche PUSH. Per altre informazioni sull'integrazione per la piattaforma Android e iOS e l'uso dell'API, vedere Come effettuare una chiamata uno-a-uno e ricevere notifiche PUSH
Casi d'uso della chat
Importante
Questa funzionalità di Servizi di comunicazione di Azure è attualmente in anteprima.
Le API di anteprima e gli SDK vengono forniti senza un contratto di servizio. È consigliabile non usarli per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate.
Per altre informazioni, vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.
| Area | Utilizzare casi |
|---|---|
| Tipi di chat | Aggiungere un thread di chat Servizi di comunicazione di Azure |
| Azioni di chat | Inviare un messaggio di chat |
| Ricevere un messaggio di chat | |
| Eventi di chat | Mostra indicatori di digitazione |
| Visualizzare una ricevuta di lettura | |
| Mostra quando un partecipante viene aggiunto o rimosso | |
| Mostra le modifiche apportate al titolo della chat |
Flessibilità
È ChatComposite stato progettato per adattarsi a layout e visualizzazioni diversi nell'applicazione. Ad esempio, è possibile scegliere di posizionare Chat in una visualizzazione di spostamento, una visualizzazione modale o un'altra visualizzazione. L'oggetto ChatComposite si adatta e garantisce che l'utente abbia un'esperienza senza problemi.
| Nella visualizzazione di spostamento | In visualizzazione modale |
|---|---|
|
|
Identità supportate
Per inizializzare un composito ed eseguire l'autenticazione al servizio, un utente deve avere un'identità Servizi di comunicazione di Azure. Per altre informazioni, vedere Eseguire l'autenticazione a Servizi di comunicazione di Azure e Avvio rapido: Creare e gestire i token di accesso.
Architettura consigliata
Inizializzare un composito usando un token di accesso Servizi di comunicazione di Azure. È importante ottenere token di accesso da Servizi di comunicazione di Azure tramite un servizio attendibile gestito. Per altre informazioni, vedere Avvio rapido: Creare e gestire i token di accesso e l'esercitazione sul servizio attendibile.
Le librerie client di chiamata e chat devono avere il contesto per la chiamata a cui partecipano. Analogamente ai token di accesso utente, distribuire il contesto ai client usando il proprio servizio attendibile. La tabella seguente riepiloga le funzioni di inizializzazione e gestione delle risorse necessarie per aggiungere contesto a una libreria client:
| Responsabilità di Contoso | Responsabilità della libreria dell'interfaccia utente |
|---|---|
| Fornire un token di accesso da Azure | Passare il token di accesso fornito per inizializzare i componenti |
| Fornire una funzione di aggiornamento | Aggiornare il token di accesso usando una funzione fornita dallo sviluppatore |
| Recuperare e passare le informazioni di join per la chiamata o la chat | Passare le informazioni sulle chiamate e sulle chat per inizializzare i componenti |
| Recuperare e passare informazioni utente per qualsiasi modello di dati personalizzato | Passare un modello di dati personalizzato ai componenti di cui eseguire il rendering |
Piattaforme supportate
| Piattaforma | Versioni |
|---|---|
| iOS | iOS 14 e versioni successive |
| Android | API 21 e versioni successive |
Guida alla risoluzione dei problemi
Quando si verifica una risoluzione dei problemi per le chiamate vocali o video, potrebbe essere richiesto di fornire un CALLID. Questo ID viene usato per identificare le chiamate di Servizi di comunicazione.
Questo CallID può essere recuperato tramite la barra delle azioni nella parte inferiore della schermata di chiamata; vedete un pulsante con i puntini di sospensione; una volta che l'utente esegue l'azione di tocco, un'opzione "Condividi informazioni di diagnostica"; l'utente può condividere le informazioni di diagnostica necessarie per tenere traccia di eventuali problemi dal team di supporto.
Per l'accesso a livello di codice a CallID, vedere "Come ottenere informazioni di debug a livello di codice".
Per altre informazioni sulle linee guida per la risoluzione dei problemi, vedere la pagina "Risoluzione dei problemi in Servizi di comunicazione di Azure".
| Schermata di chiamata | Menu Informazioni di diagnostica | Share CallID |
|---|---|---|
|
|
|