Avvio rapido: Aggiungere chiamate vocali all'app

  • Articolo

Introduzione alla Servizi di comunicazione di Azure usando Communication Services Calling SDK per aggiungere voce e videochiamata all'app.

Importante

Servizi di comunicazione di Azure supporta solo le chiamate di emergenza ai numeri di emergenza nei Stati Uniti, Porto Rico, Canada e Regno Unito.

Servizi di comunicazione di Azure chiamata vocale (PSTN) può essere usata per comporre il numero di emergenza 911 nella Stati Uniti, Porto Rico e Canada e per chiamare numeri di emergenza 999 e 112 nel Regno Unito. Servizi di comunicazione di Azure attualmente non supporta la chiamata di tali numeri di emergenza dall'esterno di tali paesi o aree geografiche o la chiamata di servizi di emergenza in altri paesi o aree geografiche.

In questa guida introduttiva si apprenderà come avviare una chiamata usando l'SDK per chiamate Servizi di comunicazione di Azure per Windows.

È possibile scaricare l'app di esempio da GitHub.

Prerequisiti

Per completare questa esercitazione è necessario soddisfare i prerequisiti seguenti:

Configurazione

Creazione del progetto

In Visual Studio creare un nuovo progetto con il modello App vuota (Windows universale) per configurare un'app piattaforma UWP (Universal Windows Platform) a pagina singola (UWP).

Screenshot che mostra la finestra Nuovo progetto UWP in Visual Studio.

Installare il pacchetto

Selezionare il progetto e passare a Manage Nuget Packages installare Azure.Communication.Calling.WindowsClient1.0.0 o superiore. Assicurarsi che Includi Preleased sia selezionata.

Richiedere l'accesso

Passare a Package.appxmanifest e selezionare Capabilities. Controllare Internet (Client) e Internet (Client & Server) ottenere l'accesso in ingresso e in uscita a Internet. Controllare Microphone di accedere al feed audio del microfono e Webcam di accedere al feed video della fotocamera.

Screenshot che mostra la richiesta di accesso a Internet e microfono in Visual Studio.

Configurare il framework dell'app

È necessario configurare un layout di base per collegare la logica. Per inserire una chiamata in uscita, è necessario TextBox specificare l'ID utente del chiamante. È anche necessario un Start/Join call pulsante e un Hang up pulsante. Una Mute casella di controllo e una BackgroundBlur casella di controllo sono incluse anche in questo esempio per illustrare le funzionalità di attivazione degli stati audio e degli effetti video.

Aprire l'oggetto del progetto e aggiungere il nodo all'oggetto MainPage.xamlGridPage:

<Page
    x:Class="CallingQuickstart.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:CallingQuickstart"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}" Width="800" Height="600">

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="16*"/>
            <RowDefinition Height="30*"/>
            <RowDefinition Height="200*"/>
            <RowDefinition Height="60*"/>
            <RowDefinition Height="16*"/>
        </Grid.RowDefinitions>
        <TextBox Grid.Row="1" x:Name="CalleeTextBox" PlaceholderText="Who would you like to call?" TextWrapping="Wrap" VerticalAlignment="Center" Height="30" Margin="10,10,10,10" />

        <Grid x:Name="AppTitleBar" Background="LightSeaGreen">
            <TextBlock x:Name="QuickstartTitle" Text="Calling Quickstart sample title bar" Style="{StaticResource CaptionTextBlockStyle}" Padding="7,7,0,0"/>
        </Grid>

        <Grid Grid.Row="2">
            <Grid.RowDefinitions>
                <RowDefinition/>
            </Grid.RowDefinitions>
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*"/>
                <ColumnDefinition Width="*"/>
            </Grid.ColumnDefinitions>
            <MediaPlayerElement x:Name="LocalVideo" HorizontalAlignment="Center" Stretch="UniformToFill" Grid.Column="0" VerticalAlignment="Center" AutoPlay="True" />
            <MediaPlayerElement x:Name="RemoteVideo" HorizontalAlignment="Center" Stretch="UniformToFill" Grid.Column="1" VerticalAlignment="Center" AutoPlay="True" />
        </Grid>
        <StackPanel Grid.Row="3" Orientation="Vertical" Grid.RowSpan="2">
            <StackPanel Orientation="Horizontal">
                <Button x:Name="CallButton" Content="Start/Join call" Click="CallButton_Click" VerticalAlignment="Center" Margin="10,0,0,0" Height="40" Width="123"/>
                <Button x:Name="HangupButton" Content="Hang up" Click="HangupButton_Click" VerticalAlignment="Center" Margin="10,0,0,0" Height="40" Width="123"/>
                <CheckBox x:Name="MuteLocal" Content="Mute" Margin="10,0,0,0" Click="MuteLocal_Click" Width="74"/>
            </StackPanel>
        </StackPanel>
        <TextBox Grid.Row="5" x:Name="Stats" Text="" TextWrapping="Wrap" VerticalAlignment="Center" Height="30" Margin="0,2,0,0" BorderThickness="2" IsReadOnly="True" Foreground="LightSlateGray" />
    </Grid>
</Page>

Aprire e MainPage.xaml.cs sostituire il contenuto con l'implementazione seguente:

using Azure.Communication.Calling.WindowsClient;
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Linq;
using System.Threading.Tasks;
using Windows.ApplicationModel;
using Windows.ApplicationModel.Core;
using Windows.Media.Core;
using Windows.Networking.PushNotifications;
using Windows.UI;
using Windows.UI.ViewManagement;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Media;
using Windows.UI.Xaml.Navigation;

namespace CallingQuickstart
{
    public sealed partial class MainPage : Page
    {
        private const string authToken = "<AUTHENTICATION_TOKEN>";

        private CallClient callClient;
        private CallTokenRefreshOptions callTokenRefreshOptions = new CallTokenRefreshOptions(false);
        private CallAgent callAgent;
        private CommunicationCall call;

        private LocalOutgoingAudioStream micStream;
        private LocalOutgoingVideoStream cameraStream;

        #region Page initialization
        public MainPage()
        {
            this.InitializeComponent();
            // Additional UI customization code goes here
        }

        protected override async void OnNavigatedTo(NavigationEventArgs e)
        {
            base.OnNavigatedTo(e);
        }
        #endregion

        #region UI event handlers
        private async void CallButton_Click(object sender, RoutedEventArgs e)
        {
            // Start a call
        }

        private async void HangupButton_Click(object sender, RoutedEventArgs e)
        {
            // Hang up a call
        }

        private async void MuteLocal_Click(object sender, RoutedEventArgs e)
        {
            // Toggle mute/unmute audio state of a call
        }
        #endregion

        #region API event handlers
        private async void OnIncomingCallAsync(object sender, IncomingCallReceivedEventArgs args)
        {
            // Handle incoming call event
        }

        private async void OnStateChangedAsync(object sender, PropertyChangedEventArgs args)
        {
            // Handle connected and disconnected state change of a call
        }
        #endregion
    }
}

Modello a oggetti

Nella tabella successiva sono elencate le classi e le interfacce che gestiscono alcune delle principali funzionalità dell'SDK per chiamate Servizi di comunicazione di Azure:

Nome Descrizione
CallClient Il CallClient punto di ingresso principale è l'SDK chiamante.
CallAgent Viene CallAgent usato per avviare e gestire le chiamate.
CommunicationCall Viene CommunicationCall usato per gestire una chiamata in corso.
CallTokenCredential Viene CallTokenCredential usato come credenziale del token per creare un'istanza di CallAgent.
CallIdentifier Viene CallIdentifier usato per rappresentare l'identità dell'utente, che può essere una delle opzioni seguenti: UserCallIdentifiere PhoneNumberCallIdentifier così via.

Autenticare il client

Inizializzare un'istanza con un token di accesso utente che consente di effettuare e ricevere chiamate e, facoltativamente, ottenere un'istanza CallAgent di DeviceManager per eseguire query per le configurazioni del dispositivo client.

Nel codice sostituire <AUTHENTICATION_TOKEN> con un token di accesso utente. Se non è disponibile un token, vedere la documentazione dei token di accesso utente.

Aggiungere InitCallAgentAndDeviceManagerAsync la funzione, che avvia l'SDK. Questo helper può essere personalizzato per soddisfare i requisiti dell'applicazione.

        private async Task InitCallAgentAndDeviceManagerAsync()
        {
            this.callClient = new CallClient(new CallClientOptions() {
                Diagnostics = new CallDiagnosticsOptions() { 
                    AppName = "CallingQuickstart",
                    AppVersion="1.0",
                    Tags = new[] { "Calling", "ACS", "Windows" }
                    }
                });

            // Set up local video stream using the first camera enumerated
            var deviceManager = await this.callClient.GetDeviceManagerAsync();
            var camera = deviceManager?.Cameras?.FirstOrDefault();
            var mic = deviceManager?.Microphones?.FirstOrDefault();
            micStream = new LocalOutgoingAudioStream();

            var tokenCredential = new CallTokenCredential(authToken, callTokenRefreshOptions);

            var callAgentOptions = new CallAgentOptions()
            {
                DisplayName = $"{Environment.MachineName}/{Environment.UserName}",
            };

            this.callAgent = await this.callClient.CreateCallAgentAsync(tokenCredential, callAgentOptions);
            this.callAgent.IncomingCallReceived += OnIncomingCallAsync;
        }

Avviare la chiamata

Dopo aver ottenuto un StartCallOptions oggetto, CallAgent è possibile usare per avviare la chiamata ACS:

        private async Task<CommunicationCall> StartAcsCallAsync(string acsCallee)
        {
            var options = new StartCallOptions();
            var call = await this.callAgent.StartCallAsync( new [] { new UserCallIdentifier(acsCallee) }, options);
            return call;
        }

Terminare una chiamata

Terminare la chiamata corrente quando viene fatto clic sul Hang up pulsante. Aggiungere l'implementazione al HangupButton_Click per terminare una chiamata e arrestare i flussi di anteprima e video.

        private async void HangupButton_Click(object sender, RoutedEventArgs e)
        {
            var call = this.callAgent?.Calls?.FirstOrDefault();
            if (call != null)
            {
                await call.HangUpAsync(new HangUpOptions() { ForEveryone = false });
            }
        }

Attiva disattivazione/annullamento modifica dell'audio

Disattivare l'audio in uscita quando viene fatto clic sul Mute pulsante. Aggiungere l'implementazione al MuteLocal_Click per disattivare la chiamata.

        private async void MuteLocal_Click(object sender, RoutedEventArgs e)
        {
            var muteCheckbox = sender as CheckBox;

            if (muteCheckbox != null)
            {
                var call = this.callAgent?.Calls?.FirstOrDefault();
                if (call != null)
                {
                    if ((bool)muteCheckbox.IsChecked)
                    {
                        await call.MuteOutgoingAudioAsync();
                    }
                    else
                    {
                        await call.UnmuteOutgoingAudioAsync();
                    }
                }

                // Update the UI to reflect the state
            }
        }

Accettare una chiamata in ingresso

IncomingCallReceived il sink di eventi viene configurato nell'helper InitCallAgentAndDeviceManagerAsyncbootstrap sdk .

    this.callAgent.IncomingCallReceived += OnIncomingCallAsync;

L'applicazione ha l'opportunità di configurare la modalità di accettazione della chiamata in ingresso, ad esempio i tipi di flusso video e audio.

        private async void OnIncomingCallAsync(object sender, IncomingCallReceivedEventArgs args)
        {
            var incomingCall = args.IncomingCall;

            var acceptCallOptions = new AcceptCallOptions() { };

            call = await incomingCall.AcceptAsync(acceptCallOptions);
            call.StateChanged += OnStateChangedAsync;
        }

Monitorare e rispondere all'evento di modifica dello stato della chiamata

StateChanged evento sull'oggetto CommunicationCall viene generato quando una chiamata in corso chiama transazioni da uno stato a un altro. L'applicazione offre le opportunità di riflettere le modifiche dello stato sull'interfaccia utente o inserire logica di business.

        private async void OnStateChangedAsync(object sender, PropertyChangedEventArgs args)
        {
            var call = sender as CommunicationCall;

            if (call != null)
            {
                var state = call.State;

                // Update the UI

                switch (state)
                {
                    case CallState.Connected:
                        {
                            await call.StartAudioAsync(micStream);

                            break;
                        }
                    case CallState.Disconnected:
                        {
                            call.StateChanged -= OnStateChangedAsync;

                            call.Dispose();

                            break;
                        }
                    default: break;
                }
            }
        }

Eseguire il codice

È possibile compilare ed eseguire il codice in Visual Studio. Per le piattaforme di soluzioni, è supportato ARM64e x64x86.

È possibile effettuare una chiamata in uscita specificando un ID utente nel campo di testo e facendo clic sul Start Call/Join pulsante. La chiamata 8:echo123 si connette con un bot echo, questa funzionalità è ideale per iniziare e verificare che i dispositivi audio funzionino.

Screenshot che mostra l'esecuzione dell'app di avvio rapido UWP

In questa guida introduttiva si apprenderà come avviare una chiamata usando l'SDK chiamante Servizi di comunicazione di Azure per JavaScript.

Codice di esempio

È possibile scaricare l'app di esempio da GitHub.

Nota

È possibile accedere a una chiamata in uscita a un utente Servizi di comunicazione di Azure usando la libreria dell'interfaccia utente Servizi di comunicazione di Azure. La libreria dell'interfaccia utente consente agli sviluppatori di aggiungere un client di chiamata abilitato all'applicazione con solo due righe di codice.

Prerequisiti

Configurazione

Creare una nuova applicazione Node.js

Aprire la finestra del terminale o di comando, creare una nuova directory per l'app e passare a tale directory.

mkdir calling-quickstart && cd calling-quickstart

Eseguire npm init -y per creare un file package.json con le impostazioni predefinite.

npm init -y

Installare il pacchetto

Usare il comando per installare l'SDK npm install chiamante Servizi di comunicazione di Azure per JavaScript.

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

L'opzione --save elenca la libreria come dipendenza nel file package.json.

Configurare il framework dell'app

Questa guida introduttiva usa il pacchetto per raggruppare gli asset dell'applicazione. Eseguire il comando seguente per installarlo e elencarlo come dipendenza di sviluppo nel pacchetto.json:

npm install parcel --save-dev

Creare un file index.html nella directory radice del progetto. Questo file verrà usato per configurare un layout di base che consentirà all'utente di effettuare una chiamata.

Ecco il codice html, che è necessario aggiungere al index.html file creato:

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Calling Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Calling Quickstart</h1>
    <input 
      id="token-input"
      type="text"
      placeholder="User access token"
      style="margin-bottom:1em; width: 200px;"
    />
    </div>
    <button id="token-submit" type="button">
        Submit
    </button>
    <input 
      id="callee-id-input"
      type="text"
      placeholder="Who would you like to call?"
      style="margin-bottom:1em; width: 200px; display: block;"
    />
    <div>
      <button id="call-button" type="button" disabled="true">
        Start Call
      </button>
      &nbsp;
      <button id="hang-up-button" type="button" disabled="true">
        Hang Up
      </button>
    </div>
    <script src="./app.js" type="module"></script>
  </body>
</html>

Creare un file nella directory radice del progetto denominato app.js per contenere la logica dell'applicazione per questa guida introduttiva. Aggiungere il codice seguente per importare il client delle chiamate e ottenere riferimenti agli elementi DOM in modo da collegare la logica di business.

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

let call;
let callAgent;
let tokenCredential = "";
const userToken = document.getElementById("token-input");
const calleeInput = document.getElementById("callee-id-input");
const submitToken = document.getElementById("token-submit");
const callButton = document.getElementById("call-button");
const hangUpButton = document.getElementById("hang-up-button");

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità dell'SDK per chiamate Servizi di comunicazione di Azure:

Nome Descrizione
CallClient Il CallClient punto di ingresso principale è l'SDK chiamante.
CallAgent Viene CallAgent usato per avviare e gestire le chiamate.
AzureCommunicationTokenCredential La AzureCommunicationTokenCredential classe implementa l'interfaccia, usata per creare un'istanza CommunicationTokenCredential di CallAgent.

Autenticare il client

È necessario immettere un token di accesso utente valido per la risorsa nel campo di testo e fare clic su "Invia". Se non è disponibile un token, vedere la documentazione dei token di accesso utente. Usando , inizializzare un'istanza CallClientCallAgent con un CommunicationTokenCredential che consente di effettuare e ricevere chiamate.

Aggiungere il codice seguente a app.js:

submitToken.addEventListener("click", async () => {
  const callClient = new CallClient(); 
  const userTokenCredential = userToken.value;
    try {
      tokenCredential = new AzureCommunicationTokenCredential(userTokenCredential);
      callAgent = await callClient.createCallAgent(tokenCredential);
      callButton.disabled = false;
      submitToken.disabled = true;
    } catch(error) {
      window.alert("Please submit a valid token!");
    }
})

Avviare una chiamata

Aggiungere un gestore eventi per avviare una chiamata quando si fa clic su callButton:

callButton.addEventListener("click", () => {
    // start a call
    const userToCall = calleeInput.value;

    // To call an Azure Communication Services communication user, use {communicationUserId: 'ACS_USER_ID'}.
    // To call echo bot, use {id: '8:echo123'}.
    call = callAgent.startCall(
        [{ id: userToCall }],
        {}
    );
    // toggle button states
    hangUpButton.disabled = false;
    callButton.disabled = true;
});

Terminare una chiamata

Aggiungere un listener di eventi per terminare la chiamata corrente quando si fa clic su hangUpButton:

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

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

La proprietà forEveryone termina la chiamata per tutti i partecipanti.

Eseguire il codice

Usare il comando npx parcel index.html per eseguire l'applicazione.

Aprire il browser e passare a http://localhost:1234/. Verrà visualizzata la schermata seguente:

Screenshot dell'applicazione JavaScript completata.

È possibile effettuare una chiamata VOIP in uscita fornendo un token di accesso utente valido e un ID utente nei campi di testo corrispondenti e facendo clic sul pulsante Avvia chiamata .

La chiamata 8:echo123 consente di connettersi con un echo bot, ideale per iniziare e verificare che i dispositivi audio funzionino. Passare {id: '8:echo123'} all'API CallAgent.startCall() per chiamare echo bot. Per chiamare un utente di comunicazione Servizi di comunicazione di Azure, passare {communicationUserId: 'ACS_USER_ID'} all'APICallAgent.startCall().

In questa guida introduttiva si apprenderà come avviare una chiamata usando il Servizi di comunicazione di Azure Calling SDK per Android.

Codice di esempio

È possibile scaricare l'app di esempio da GitHub.

Prerequisiti

Configurazione

Creare un'app Android con un'attività vuota

In Android Studio avviare un nuovo progetto.

Screenshot che mostra il pulsante per l'avvio di un nuovo progetto di Android Studio selezionato in Android Studio.

Selezionare il modello di progetto "Empty Activity" (Attività vuota) in "Phone and Tablet" (Telefono e tablet).

Screenshot che mostra l'opzione 'Empty Activity' selezionata nella schermata del modello di progetto.

Selezionare Minimum SDK (SDK minimo) di "API 26: Android 8.0 (Oreo)" o versione successiva.

Screenshot che mostra l'opzione 'Empty Activity' selezionata nella schermata 2 del modello di progetto.

Installare il pacchetto

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

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

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

In build.gradle a livello di modulo aggiungere quindi le righe seguenti alle sezioni dependencies e android

android {
    ...
    packagingOptions {
        pickFirst  'META-INF/*'
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

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

Aggiungere autorizzazioni al manifesto dell'applicazione

Per richiedere le autorizzazioni necessarie per effettuare una chiamata, devono essere dichiarate nel manifesto dell'applicazione (app/src/main/AndroidManifest.xml). Sostituire il contenuto del file con il codice seguente:

    <?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.contoso.acsquickstart">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <!--Our Calling SDK depends on the Apache HTTP SDK.
When targeting Android SDK 28+, this library needs to be explicitly referenced.
See https://developer.android.com/about/versions/pie/android-9.0-changes-28#apache-p-->
        <uses-library android:name="org.apache.http.legacy" android:required="false"/>
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

Configurare il layout per l'app

Sono necessari due input: un input di testo per l'ID del destinatario e un pulsante per effettuare la chiamata. Questi input possono essere aggiunti tramite la finestra di progettazione o modificando il codice XML di layout. Creare un pulsante con un ID call_button e un input di testo callee_id. Passare a (app/src/main/res/layout/activity_main.xml) e sostituire il contenuto del file con il codice seguente:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/call_button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginBottom="16dp"
        android:text="Call"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent" />

    <EditText
        android:id="@+id/callee_id"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:ems="10"
        android:hint="Callee Id"
        android:inputType="textPersonName"
        app:layout_constraintBottom_toTopOf="@+id/call_button"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

Creare lo scaffolding e i binding per l'attività principale

Con il layout creato è possibile aggiungere i binding e lo scaffolding di base dell'attività. L'attività gestisce la richiesta di autorizzazioni di runtime, la creazione dell'agente di chiamata e l'inserimento della chiamata quando il pulsante viene premuto ed. Ognuno di essi è trattato nella propria sezione. Il onCreate metodo viene sottoposto a override per richiamare getAllPermissions e createAgent per aggiungere le associazioni per il pulsante di chiamata. Questo evento si verifica una sola volta quando viene creata l'attività. Per altre informazioni, vedere onCreatela guida Informazioni sul ciclo di vita delle attività.

Passare a MainActivity.java e sostituire il contenuto con il codice seguente:

package com.contoso.acsquickstart;

import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import android.media.AudioManager;
import android.Manifest;
import android.content.pm.PackageManager;

import android.os.Bundle;
import android.widget.Button;
import android.widget.EditText;
import android.widget.Toast;

import com.azure.android.communication.common.CommunicationUserIdentifier;
import com.azure.android.communication.common.CommunicationTokenCredential;
import com.azure.android.communication.calling.CallAgent;
import com.azure.android.communication.calling.CallClient;
import com.azure.android.communication.calling.StartCallOptions;


import java.util.ArrayList;

public class MainActivity extends AppCompatActivity {
    
    private CallAgent callAgent;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        getAllPermissions();
        createAgent();
        
        // Bind call button to call `startCall`
        Button callButton = findViewById(R.id.call_button);
        callButton.setOnClickListener(l -> startCall());
        
        setVolumeControlStream(AudioManager.STREAM_VOICE_CALL);
    }

    /**
     * Request each required permission if the app doesn't already have it.
     */
    private void getAllPermissions() {
        // See section on requesting permissions
    }

    /**
      * Create the call agent for placing calls
      */
    private void createAgent() {
        // See section on creating the call agent
    }

    /**
     * Place a call to the callee id provided in `callee_id` text input.
     */
    private void startCall() {
        // See section on starting the call
    }
}

Richiedere autorizzazioni in fase di esecuzione

Per Android 6.0 e versioni successive (livello API 23) e targetSdkVersion 23 o versione successiva, le autorizzazioni vengono concesse in fase di esecuzione invece che durante l'installazione dell'app. Per supportarlo, getAllPermissions può essere implementato per chiamare ActivityCompat.checkSelfPermission e ActivityCompat.requestPermissions per ogni autorizzazione necessaria.

/**
 * Request each required permission if the app doesn't already have it.
 */
private void getAllPermissions() {
    String[] requiredPermissions = new String[]{Manifest.permission.RECORD_AUDIO, Manifest.permission.CAMERA, Manifest.permission.WRITE_EXTERNAL_STORAGE, Manifest.permission.READ_PHONE_STATE};
    ArrayList<String> permissionsToAskFor = new ArrayList<>();
    for (String permission : requiredPermissions) {
        if (ActivityCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) {
            permissionsToAskFor.add(permission);
        }
    }
    if (!permissionsToAskFor.isEmpty()) {
        ActivityCompat.requestPermissions(this, permissionsToAskFor.toArray(new String[0]), 1);
    }
}

Nota

Quando si progetta l'app, valutare quando dovranno essere richieste queste autorizzazioni. È consigliabile che vengano richieste quando è necessario, non prima. Per altre informazioni, vedere la Guida alle autorizzazioni di Android.

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Calling SDK:

Nome Descrizione
allClient CallClient è il punto di ingresso principale di Calling SDK.
CallAgent viene CallAgent utilizzato per avviare e gestire le chiamate.
CommunicationTokenCredential L'oggetto CommunicationTokenCredential viene usato come credenziale del token per creare un'istanza di CallAgent.
CommunicationIdentifier Viene CommunicationIdentifier utilizzato come tipo diverso di partecipante che può far parte di una chiamata.

Creare un agente dal token di accesso utente

Con un token utente, è possibile creare un'istanza di un agente di chiamata autenticato. In genere questo token viene generato da un servizio con autenticazione specifica per l'applicazione. Per altre informazioni sui token di accesso utente, vedere la Guida ai token di accesso utente .

Per la guida di avvio rapido, sostituire <User_Access_Token> con un token di accesso utente generato per la risorsa del servizio di comunicazione di Azure.


/**
 * Create the call agent for placing calls
 */
private void createAgent() {
    String userToken = "<User_Access_Token>";

    try {
        CommunicationTokenCredential credential = new CommunicationTokenCredential(userToken);
        callAgent = new CallClient().createCallAgent(getApplicationContext(), credential).get();
    } catch (Exception ex) {
        Toast.makeText(getApplicationContext(), "Failed to create call agent.", Toast.LENGTH_SHORT).show();
    }
}

Avviare una chiamata con l'agente di chiamata

La chiamata può essere effettuata tramite l'agente di chiamata: è sufficiente fornire un elenco di ID dei destinatari e le opzioni di chiamata. Per la guida introduttiva vengono usate le opzioni di chiamata predefinite senza video e un singolo ID chiamato dall'input di testo.

/**
 * Place a call to the callee id provided in `callee_id` text input.
 */
private void startCall() {
    EditText calleeIdView = findViewById(R.id.callee_id);
    String calleeId = calleeIdView.getText().toString();
    
    StartCallOptions options = new StartCallOptions();

    callAgent.startCall(
        getApplicationContext(),
        new CommunicationUserIdentifier[] {new CommunicationUserIdentifier(calleeId)},
        options);
}

Avviare l'app e chiamare l'Echo Bot

È ora possibile avviare l'app usando il pulsante "Run App" (Esegui app) sulla barra degli strumenti (MAIUSC+F10). Verificare che sia possibile effettuare chiamate chiamando 8:echo123. Un messaggio preregistrato viene riprodotto e quindi ripete il messaggio.

Screenshot che mostra l'applicazione completata.

Questo argomento di avvio rapido illustra come avviare una chiamata usando l'SDK per chiamate Servizi di comunicazione di Azure per iOS.

Codice di esempio

È possibile scaricare l'app di esempio da GitHub.

Prerequisiti

Per completare questa esercitazione è necessario soddisfare i prerequisiti seguenti:

Configurazione

Creazione del progetto Xcode

In Xcode creare un nuovo progetto iOS e selezionare il modello App . Questa esercitazione usa il framework SwiftUI, quindi è necessario impostare Linguaggio su Swift e Interfaccia utente su SwiftUI. In questo argomento di avvio rapido non verranno creati test. È possibile deselezionare Includi test.

Screenshot che mostra la finestra relativa al nuovo progetto in Xcode.

Installare il pacchetto e le dipendenze con CocoaPods

  1. Per creare un podfile per l'applicazione, aprire il terminale e passare alla cartella del progetto ed eseguire:

    pod init

  2. Aggiungere il codice seguente al Podfile e salvare (assicurarsi che "target" corrisponda al nome del progetto):

    platform :ios, '13.0'
use_frameworks!

target 'AzureCommunicationCallingSample' do
  pod 'AzureCommunicationCalling', '~> 1.0.0'
end

  3. Eseguire pod install.

  4. Aprire .xcworkspace con Xcode.

Richiedere l'accesso al microfono

Per accedere al microfono del dispositivo, è necessario aggiornare il file Information Property List dell'app con NSMicrophoneUsageDescription. Il valore associato viene impostato su un string oggetto incluso nella finestra di dialogo utilizzata 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 scegliere Open As>Source Code (Apri come > Codice sorgente). Aggiungere le righe seguenti nella sezione <dict> di primo livello 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 e aggiungere una dichiarazione import all'inizio del file per importare AzureCommunicationCalling library. Inoltre, importare AVFoundation, è necessario questo codice per la richiesta di autorizzazione audio nel codice.

import AzureCommunicationCalling
import AVFoundation

Sostituire l'implementazione dello struct ContentView con alcuni semplici controlli dell'interfaccia utente che consentano a un utente di avviare e terminare una chiamata. La logica di business viene collegata a questi controlli in questa guida introduttiva.

struct ContentView: View {
    @State var callee: String = ""
    @State var callClient: CallClient?
    @State var callAgent: CallAgent?
    @State var call: Call?

    var body: some View {
        NavigationView {
            Form {
                Section {
                    TextField("Who would you like to call?", text: $callee)
                    Button(action: startCall) {
                        Text("Start Call")
                    }.disabled(callAgent == nil)
                    Button(action: endCall) {
                        Text("End Call")
                    }.disabled(call == nil)
                }
            }
            .navigationBarTitle("Calling Quickstart")
        }.onAppear {
            // Initialize call agent
        }
    }

    func startCall() {
        // Ask permissions
        AVAudioSession.sharedInstance().requestRecordPermission { (granted) in
            if granted {
                // Add start call logic
            }
        }
    }

    func endCall() {
        // Add end call logic
    }
}

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Calling SDK:

Nome Descrizione
CallClient CallClient è il punto di ingresso principale di Calling SDK.
CallAgent viene CallAgent utilizzato per avviare e gestire le chiamate.
CommunicationTokenCredential L'oggetto CommunicationTokenCredential viene usato come credenziale del token per creare un'istanza di CallAgent.
CommunicationUserIdentifier Viene CommunicationUserIdentifier usato per rappresentare l'identità dell'utente, che può essere una delle opzioni seguenti: CommunicationUserIdentifier,PhoneNumberIdentifier o CallingApplication.

Autenticare il client

Inizializzare un'istanza CallAgent con un token di accesso utente, che consente di effettuare e ricevere chiamate.

Nel codice seguente è necessario sostituire <USER ACCESS TOKEN> con un token di accesso utente valido per la risorsa. Se non è disponibile un token, vedere la documentazione dei token di accesso utente.

Aggiungere il codice seguente al callback onAppear in ContentView.swift:

var userCredential: CommunicationTokenCredential?
do {
    userCredential = try CommunicationTokenCredential(token: "<USER ACCESS TOKEN>")
} catch {
    print("ERROR: It was not possible to create user credential.")
    return
}

self.callClient = CallClient()

// Creates the call agent
self.callClient?.createCallAgent(userCredential: userCredential!) { (agent, error) in
    if error != nil {
        print("ERROR: It was not possible to create a call agent.")
        return
    }
    else {
        self.callAgent = agent
        print("Call agent successfully created.")
    }
}

Avviare una chiamata

Il startCall metodo viene impostato come azione eseguita quando viene toccato il pulsante Avvia chiamata . Aggiornare l'implementazione per avviare una chiamata con ASACallAgent:

func startCall()
{
    // Ask permissions
    AVAudioSession.sharedInstance().requestRecordPermission { (granted) in
        if granted {
            // start call logic
            let callees:[CommunicationIdentifier] = [CommunicationUserIdentifier(self.callee)]
            self.callAgent?.startCall(participants: callees, options: StartCallOptions()) { (call, error) in
                if (error == nil) {
                    self.call = call
                } else {
                    print("Failed to get call object")
                }
            }
        }
    }
}

È anche possibile usare le proprietà in StartCallOptions per impostare le opzioni iniziali per la chiamata, ovvero consente di avviare la chiamata con il microfono disattivato.

Terminare una chiamata

Implementare il metodo endCall per terminare la chiamata corrente quando viene toccato il pulsante End Call (Termina chiamata).

func endCall()
{    
    self.call!.hangUp(options: HangUpOptions()) { (error) in
        if (error != nil) {
            print("ERROR: It was not possible to hangup the call.")
        }
    }
}

Eseguire il codice

È possibile compilare ed eseguire l'app nel simulatore iOS selezionando Product>Run o usando il tasto di scelta rapida (⌘-R).

Aspetto finale dell'app di avvio rapido

È possibile effettuare una chiamata VoIP in uscita fornendo un ID utente nel campo di testo e toccando il pulsante Start Call (Avvia chiamata). La chiamata 8:echo123 consente di connettersi con un bot echo, questa funzionalità è ideale per iniziare e verificare che i dispositivi audio funzionino.

Nota

La prima volta che si effettua una chiamata, il sistema chiederà l'accesso al microfono. In un'applicazione di produzione è consigliabile usare l'API AVAudioSession per controllare lo stato delle autorizzazioni e aggiornare normalmente il comportamento dell'applicazione quando l'autorizzazione non viene concessa.

Pulire le risorse

Per pulire e rimuovere una sottoscrizione di Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. Eliminando il gruppo di risorse vengono eliminate anche tutte le altre risorse associate. Vedere altre informazioni sulla pulizia delle risorse.

Passaggi successivi

Per altre informazioni, vedere gli articoli seguenti: