Início Rápido: Adicionar chamadas de voz à sua aplicação

Comece a utilizar Azure Communication Services através do SDK de Chamadas dos Serviços de Comunicação para adicionar chamadas de voz e vídeo à sua aplicação.

Importante

Azure Communication Services apoia chamadas de emergência para o 112 apenas no Estados Unidos e Porto Rico.

Azure Communication Services' Voice Calling (RTPC) pode ser utilizado para ligar para o 112 a partir de utilizadores no Estados Unidos e Porto Rico. Ligar para o 112 de fora do Estados Unidos & Porto Rico ou ligar para serviços de emergência em países que não o Estados Unidos & Porto Rico não é suportado.

Importante

A funcionalidade descrita neste documento está atualmente em pré-visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Neste início rápido, irá aprender a iniciar uma chamada com o SDK de Chamadas Azure Communication Services para Windows.

Código de exemplo UWP

Pode transferir a aplicação de exemplo do GitHub.

Pré-requisitos

Para concluir este tutorial, precisará dos seguintes pré-requisitos:

Configurar

Criar o projeto

No Visual Studio, crie um novo projeto com o modelo Aplicação Em Branco (Universal Windows) para configurar uma aplicação de Plataforma Universal do Windows de página única (UWP).

Captura de ecrã a mostrar a janela Novo Projeto UWP no Visual Studio.

Instalar o pacote

Clique com o botão direito do rato no projeto e aceda a Manage Nuget Packages instalar Azure.Communication.Callinga versão 1.0.0-beta.33 ou superior. Certifique-se de que a opção Incluir Preleased está selecionada.

Pedir acesso

Aceda a Package.appxmanifest e clique em Capabilities. Verifique Internet (Client & Server) para obter acesso de entrada e saída à Internet. Verifique Microphone para aceder ao feed de áudio do microfone.

Captura de ecrã a mostrar o pedido de acesso à Internet e ao Microfone no Visual Studio.

Configurar a arquitetura de aplicações

Temos de configurar um esquema básico para anexar a nossa lógica. Para efetuar uma chamada de saída, precisamos de um TextBox para fornecer o ID de Utilizador do destinatário. Também precisamos de um Start Call botão e de um Hang Up botão. Abra o MainPage.xaml projeto e adicione o Grid nó ao seu Page:

<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="60*"/>
            <RowDefinition Height="200*"/>
            <RowDefinition Height="60*"/>
        </Grid.RowDefinitions>
        <TextBox x:Name="CalleeTextBox" Text="Who would you like to call?" TextWrapping="Wrap" VerticalAlignment="Center" Grid.Row="0" Height="40" Margin="10,10,10,10" />
        <Grid Grid.Row="1">
        </Grid>
        <StackPanel Grid.Row="2" Orientation="Horizontal">
            <Button x:Name="CallButton" Content="Start Call" Click="CallButton_Click" VerticalAlignment="Center" Margin="10,0,0,0" Height="40" Width="200"/>
            <Button x:Name="HangupButton" Content="Hang Up" Click="HangupButton_Click" VerticalAlignment="Center" Margin="10,0,0,0" Height="40" Width="200"/>
            <TextBlock x:Name="State" Text="Status" TextWrapping="Wrap" VerticalAlignment="Center" Margin="40,0,0,0" Height="40" Width="200"/>
        </StackPanel>
    </Grid>
</Page>

Abra para (clique com App.xaml.cs o botão direito do rato e selecione Ver Código) e adicione esta linha à parte superior:

using CallingQuickstart;

Abra e MainPage.xaml.cs substitua o conteúdo pela seguinte implementação:

using Azure.Communication.Calling;
using Azure.WinRT.Communication;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Windows.Foundation;
using Windows.UI.ViewManagement;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;

namespace CallingQuickstart
{
    public sealed partial class MainPage : Page
    {
        CallAgent callAgent;
        Call call;
        DeviceManager deviceManager;

        public MainPage()
        {
            this.InitializeComponent();
            Task.Run(() => this.InitCallAgentAndDeviceManagerAsync()).Wait();
        }

        private async Task InitCallAgentAndDeviceManagerAsync()
        {
            // Create and cache CallAgent and optionally fetch DeviceManager
        }

        private async void CallButton_Click(object sender, RoutedEventArgs e)
        {
            // Start call
        }

        private async void HangupButton_Click(object sender, RoutedEventArgs e)
        {
            // End the current call
        }

        private async void Call_OnStateChangedAsync(object sender, PropertyChangedEventArgs args)
        {
            // Update call state
        }
    }
}

Modelo de objeto

As seguintes classes e interfaces processam algumas das principais funcionalidades do SDK de Chamadas Azure Communication Services:

Nome Descrição
CallClient O CallClient é o ponto de entrada principal do SDK de Chamadas.
CallAgent O CallAgent é utilizado para iniciar e gerir chamadas.
CommunicationTokenCredential O CommunicationTokenCredential é utilizado como a credencial do token para instanciar o CallAgent.
CommunicationUserIdentifier O CommunicationUserIdentifier é utilizado para representar a identidade do utilizador, que pode ser uma das seguintes: CommunicationUserIdentifier/PhoneNumberIdentifier/CallingApplication.

Autenticar o cliente

Inicialize uma CallAgent instância com um Token de Acesso de Utilizador que nos permitirá fazer e receber chamadas e, opcionalmente, obter uma instância do DeviceManager para consultar as configurações do dispositivo cliente.

No código seguinte, substitua por <AUTHENTICATION_TOKEN> um Token de Acesso de Utilizador. Veja a documentação do token de acesso do utilizador se ainda não tiver um token disponível.

Adicione o seguinte código à InitCallAgentAndDeviceManagerAsync função.

var callClient = new CallClient();
this.deviceManager = await callClient.GetDeviceManager();

var tokenCredential = new CommunicationTokenCredential("<AUTHENTICATION_TOKEN>");
var callAgentOptions = new CallAgentOptions()
{
    DisplayName = "<DISPLAY_NAME>"
};

this.callAgent = await callClient.CreateCallAgent(tokenCredential, callAgentOptions);

Iniciar uma chamada

Adicione a implementação ao CallButton_Click para iniciar uma chamada com o que criámos e ligue o callAgent processador de eventos de estado de chamada.

var startCallOptions = new StartCallOptions();

var callees = new ICommunicationIdentifier[1] { new CommunicationUserIdentifier(CalleeTextBox.Text.Trim()) };

this.call = await this.callAgent.StartCallAsync(callees, startCallOptions);
this.call.OnStateChanged += Call_OnStateChangedAsync;

Terminar uma chamada

Termine a chamada atual quando o Hang Up botão for clicado. Adicione a implementação ao HangupButton_Click para terminar uma chamada com o callAgent que criámos e remova o processador de eventos de estado de chamada.

this.call.OnStateChanged -= Call_OnStateChangedAsync;
await this.call.HangUpAsync(new HangUpOptions());

Controlar o estado da chamada

Mantenha-se notificado sobre o estado da chamada atual.

var state = (sender as Call)?.State;
await this.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => {
    State.Text = state.ToString();
});

Executar o código

Pode criar e executar o código no Visual Studio. Tenha em atenção que para as plataformas de soluções suportamos ARM64e x64x86.

Pode fazer uma chamada de saída ao fornecer um ID de utilizador no campo de texto e ao clicar no Start Call botão. A 8:echo123 chamada liga-o a um bot de eco, isto é ótimo para começar e verificar se os seus dispositivos de áudio estão a funcionar.

Captura de ecrã a mostrar a execução da aplicação de início rápido UWP

Código de exemplo WinUI 3

Pode transferir a aplicação de exemplo do GitHub.

Pré-requisitos

Para concluir este tutorial, precisará dos seguintes pré-requisitos:

Configurar

Criar o projeto

No Visual Studio, crie um novo projeto com o modelo Aplicação Em Branco, Empacotado (WinUI 3 no Ambiente de Trabalho) para configurar uma aplicação WinUI 3 de página única.

Captura de ecrã a mostrar a janela Novo Projeto WinUI no Visual Studio.

Instalar o pacote

Clique com o botão direito do rato no projeto e aceda a Manage Nuget Packages instalar Azure.Communication.Callinga versão 1.0.0-beta.33 ou superior. Certifique-se de que a opção Incluir Preleased está selecionada.

Pedir acesso

Captura de ecrã a mostrar o pedido de acesso à Internet e ao Microfone no Visual Studio.

Configurar a arquitetura de aplicações

Temos de configurar um esquema básico para anexar a nossa lógica. Para efetuar uma chamada de saída, precisamos de um TextBox para fornecer o ID de Utilizador do destinatário. Também precisamos de um Start Call botão e de um Hang Up botão. Abra o MainWindow.xaml projeto e adicione o Grid nó ao seu Window:

<Window
    x:Class="CallingQuickstart.MainWindow"
    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">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="60*"/>
            <RowDefinition Height="200*"/>
            <RowDefinition Height="60*"/>
        </Grid.RowDefinitions>
        <TextBox x:Name="CalleeTextBox" Text="Who would you like to call?" TextWrapping="Wrap" VerticalAlignment="Center" Height="40" Margin="10,10,10,10" />
        <Grid Grid.Row="1">
        </Grid>
        <StackPanel Grid.Row="2" Orientation="Horizontal">
            <Button x:Name="CallButton" Content="Start Call" Click="CallButton_Click" VerticalAlignment="Center" Margin="10,0,0,0" Height="40" Width="200"/>
            <Button x:Name="HangupButton" Content="Hang Up" Click="HangupButton_Click" VerticalAlignment="Center" Margin="10,0,0,0" Height="40" Width="200"/>
            <TextBlock x:Name="State" Text="Status" TextWrapping="Wrap" VerticalAlignment="Center" Margin="40,0,0,0" Height="40" Width="200"/>
        </StackPanel>
    </Grid>
</Window>

Abra e MainWindow.xaml.cs substitua o conteúdo pela seguinte implementação:

using Azure.Communication.Calling;
using Azure.WinRT.Communication;
using Microsoft.UI.Xaml;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Windows.Media.Core;

namespace CallingQuickstart
{
    public sealed partial class MainWindow : Window
    {
        CallAgent callAgent;
        Call call;
        DeviceManager deviceManager;

        public MainWindow()
        {
            this.InitializeComponent();
            Task.Run(() => this.InitCallAgentAndDeviceManagerAsync()).Wait();
        }

        private async Task InitCallAgentAndDeviceManagerAsync()
        {
            // Create and cache CallAgent and optionally fetch DeviceManager
        }

        private async void CallButton_Click(object sender, RoutedEventArgs e)
        {
            // Start call
        }

        private async void HangupButton_Click(object sender, RoutedEventArgs e)
        {
            // End call
        }

        private async void Call_OnStateChangedAsync(object sender, PropertyChangedEventArgs args)
        {
            // Update call state
        }
    }
}

Modelo de objeto

As seguintes classes e interfaces processam algumas das principais funcionalidades do SDK de Chamadas Azure Communication Services:

Nome Descrição
CallClient O CallClient é o ponto de entrada principal do SDK de Chamadas.
CallAgent O CallAgent é utilizado para iniciar e gerir chamadas.
CommunicationTokenCredential O CommunicationTokenCredential é utilizado como a credencial do token para instanciar o CallAgent.
CommunicationUserIdentifier O CommunicationUserIdentifier é utilizado para representar a identidade do utilizador, que pode ser uma das seguintes: CommunicationUserIdentifier/PhoneNumberIdentifier/CallingApplication.

Autenticar o cliente

Inicialize uma CallAgent instância com um Token de Acesso de Utilizador que nos permitirá fazer e receber chamadas e, opcionalmente, obter uma instância do DeviceManager para consultar as configurações do dispositivo cliente.

No código seguinte, substitua por <AUTHENTICATION_TOKEN> um Token de Acesso de Utilizador. Veja a documentação do token de acesso do utilizador se ainda não tiver um token disponível.

Adicione o seguinte código à InitCallAgentAndDeviceManagerAsync função.

var callClient = new CallClient();
this.deviceManager = await callClient.GetDeviceManager();

var tokenCredential = new CommunicationTokenCredential("<AUTHENTICATION_TOKEN>");
var callAgentOptions = new CallAgentOptions()
{
    DisplayName = "<DISPLAY_NAME>"
};

this.callAgent = await callClient.CreateCallAgent(tokenCredential, callAgentOptions);
this.callAgent.OnCallsUpdated += Agent_OnCallsUpdatedAsync;
this.callAgent.OnIncomingCall += Agent_OnIncomingCallAsync;

Iniciar uma chamada

Adicione a implementação ao CallButton_Click para iniciar uma chamada com o que criámos e ligue o callAgent processador de eventos de estado de chamada.

var startCallOptions = new StartCallOptions();

var callees = new ICommunicationIdentifier[1]
{
    new CommunicationUserIdentifier(CalleeTextBox.Text.Trim())
};

this.call = await this.callAgent.StartCallAsync(callees, startCallOptions);
this.call.OnStateChanged += Call_OnStateChangedAsync;

Terminar uma chamada

Termine a chamada atual quando o Hang Up botão for clicado. Adicione a implementação ao HangupButton_Click para terminar uma chamada com o callAgent que criámos e remova o processador de eventos de estado de chamada.

this.call.OnStateChanged -= Call_OnStateChangedAsync;
await this.call.HangUpAsync(new HangUpOptions());

Controlar o estado da chamada

Mantenha-se notificado sobre o estado da chamada atual.

var state = (sender as Call)?.State;
this.DispatcherQueue.TryEnqueue(() => {
    State.Text = state.ToString();
});

Executar o código

Pode criar e executar o código no Visual Studio. Tenha em atenção que para as plataformas de soluções suportamos ARM64e x64x86.

Pode fazer uma chamada de saída ao fornecer um ID de utilizador no campo de texto e ao clicar no Start Call botão. A 8:echo123 chamada liga-o a um bot de eco, isto é ótimo para começar e verificar se os seus dispositivos de áudio estão a funcionar.

Captura de ecrã a mostrar a execução da aplicação de início rápido WinUI

Neste início rápido, irá aprender a iniciar uma chamada com o SDK de Chamadas Azure Communication Services para JavaScript.

Código de exemplo

Pode transferir a aplicação de exemplo do GitHub.

Nota

As chamadas de saída para um utilizador Azure Communication Services podem ser acedidas através da Biblioteca de IU do Azure Communication Services. A Biblioteca de IU permite que os programadores adicionem um cliente de chamada ativado para a sua aplicação com apenas algumas linhas de código.

Pré-requisitos

Configurar

Criar uma nova aplicação Node.js

Abra o terminal ou a janela de comandos para criar um novo diretório para a sua aplicação e navegue até ao mesmo.

mkdir calling-quickstart && cd calling-quickstart

Execute npm init -y para criar um ficheiro package.json com as predefinições.

npm init -y

Instalar o pacote

Utilize o npm install comando para instalar o SDK de Chamadas Azure Communication Services para JavaScript.

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

A --save opção lista a biblioteca como uma dependência no ficheiro package.json .

Configurar a arquitetura de aplicações

Este início rápido utiliza o pacote para agrupar os recursos da aplicação. Execute o seguinte comando para instalá-lo e listá-lo como uma dependência de desenvolvimento no seu package.json:

npm install parcel --save-dev

Crie um ficheiro index.html no diretório de raiz do seu projeto. Vamos utilizar este ficheiro para configurar um esquema básico que permitirá ao utilizador efetuar uma chamada.

Eis o html que temos de adicionar ao index.html ficheiro que criámos:

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

Crie um ficheiro no diretório de raiz do projeto denominado app.js para conter a lógica da aplicação para este início rápido. Adicione o seguinte código para importar o cliente de chamadas e obter referências aos elementos DOM para que possamos anexar a nossa lógica de negócio.

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

Modelo de objeto

As seguintes classes e interfaces processam algumas das principais funcionalidades do SDK de Chamadas Azure Communication Services:

Nome Descrição
CallClient O CallClient é o ponto de entrada principal do SDK de Chamadas.
CallAgent O CallAgent é utilizado para iniciar e gerir chamadas.
AzureCommunicationTokenCredential A classe AzureCommunicationTokenCredential implementa a interface CommunicationTokenCredential, que é utilizada para instanciar o CallAgent.

Autenticar o cliente

Tem de introduzir um token de acesso de utilizador válido para o recurso no campo de texto e clicar em "Submeter". Veja a documentação do token de acesso do utilizador se ainda não tiver um token disponível. Com o CallClient, inicialize uma CallAgent instância com uma CommunicationTokenCredential que nos permita efetuar e receber chamadas.

Adicione o seguinte código 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!");
    }
})

Iniciar uma chamada

Adicione um processador de eventos para iniciar uma chamada quando clicar callButton em:

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

Terminar uma chamada

Adicione um serviço de escuta de eventos para terminar a chamada atual quando clicar hangUpButton em:

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

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

A forEveryone propriedade termina a chamada para todos os participantes da chamada.

Executar o código

Utilize o comando npx parcel index.html para executar a sua aplicação.

Abra o browser e navegue para http://localhost:1234/. Deverá ver o seguinte:

Captura de ecrã da Aplicação JavaScript concluída.

Pode fazer uma chamada VOIP de saída ao fornecer um token de acesso de utilizador e ID de utilizador válidos nos campos de texto correspondentes e ao clicar no botão Iniciar Chamada .

A 8:echo123 chamada liga-o a um bot de eco, o que é ótimo para começar e verificar se os seus dispositivos de áudio estão a funcionar. Passe {id: '8:echo123'} para a API CallAgent.startCall() para chamar echobot. Para chamar um utilizador de comunicação Azure Communication Services, passe {communicationUserId: 'ACS_USER_ID'} para a CallAgent.startCall() API.

Neste início rápido, irá aprender a iniciar uma chamada com o SDK de Chamadas Azure Communication Services para Android.

Código de Exemplo

Pode transferir a aplicação de exemplo do GitHub.

Pré-requisitos

Configurar

Criar uma aplicação Android com uma atividade vazia

No Android Studio, selecione Iniciar um novo projeto do Android Studio.

Captura de ecrã a mostrar o botão

Selecione o modelo de projeto "Atividade Vazia" em "Telemóvel e Tablet".

Captura de ecrã a mostrar a opção

Selecione SDK Mínimo de "API 26: Android 8.0 (Oreo)" ou superior.

Captura de ecrã a mostrar a opção

Instalar o pacote

Localize o build.gradle ao nível do projeto e certifique-se de que adiciona mavenCentral() à lista de repositórios em buildscript e allprojects

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

Em seguida, no nível do módulo build.gradle, adicione as seguintes linhas às dependências e secções 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'
    ...
}

Adicionar permissões ao manifesto da aplicação

Para pedir permissões necessárias para efetuar uma chamada, primeiro têm de ser declaradas no Manifesto da Aplicação (app/src/main/AndroidManifest.xml). Substitua o conteúdo do ficheiro pelo seguinte:

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

Configurar o esquema da aplicação

São necessárias duas entradas: uma entrada de texto para o ID do destinatário e um botão para efetuar a chamada. Estes podem ser adicionados através do estruturador ou ao editar o esquema xml. Crie um botão com um ID de call_button e uma entrada de texto de callee_id. Navegue para (app/src/main/res/layout/activity_main.xml) e substitua o conteúdo do ficheiro pelo seguinte:

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

Criar os principais enlaces e estruturamentos de atividade

Com o esquema criado, os enlaces podem ser adicionados, bem como o estruturamento básico da atividade. A atividade processará o pedido de permissões de tempo de execução, a criação do agente de chamada e a colocação da chamada quando o botão for premido. Cada um deles será abrangido na sua própria secção. O onCreate método será substituído para invocar getAllPermissions e createAgent adicionar os enlaces do botão de chamada. Isto ocorrerá apenas uma vez quando a atividade for criada. Para obter mais informações, no onCreate, consulte o guia Compreender o Ciclo de Vida da Atividade.

Navegue para MainActivity.java e substitua o conteúdo pelo seguinte código:

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

Pedir permissões no runtime

Para Android 6.0 e superior (nível de API 23) e targetSdkVersion 23 ou superior, as permissões são concedidas no runtime em vez de quando a aplicação é instalada. Para o suportar, getAllPermissions pode ser implementado para chamar ActivityCompat.checkSelfPermission e ActivityCompat.requestPermissions para cada permissão necessária.

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

Ao conceber a sua aplicação, considere quando estas permissões devem ser pedidas. As permissões devem ser pedidas conforme forem necessárias, não com antecedência. Para obter mais informações, consulte o Guia de Permissões do Android.

Modelo de objeto

As seguintes classes e interfaces processam algumas das principais funcionalidades do SDK de Chamadas Azure Communication Services:

Nome Descrição
CallClient O CallClient é o ponto de entrada principal do SDK de Chamadas.
CallAgent O CallAgent é utilizado para iniciar e gerir chamadas.
CommunicationTokenCredential O CommunicationTokenCredential é utilizado como a credencial do token para instanciar o CallAgent.
CommunicationIdentifier O CommunicationIdentifier é utilizado como um tipo diferente de participante que poderia fazer parte de uma chamada.

Criar um agente a partir do token de acesso do utilizador

Com um token de utilizador, um agente de chamada autenticado pode ser instanciado. Geralmente, este token será gerado a partir de um serviço com autenticação específica da aplicação. Para obter mais informações sobre tokens de acesso de utilizador, consulte o guia Tokens de Acesso de Utilizador .

Para o início rápido, substitua <User_Access_Token> por um token de acesso de utilizador gerado para o recurso do Azure Communication Service.


/**
 * 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();
    }
}

Iniciar uma chamada com o agente de chamadas

A colocação da chamada pode ser efetuada através do agente de chamada e apenas requer a disponibilização de uma lista de IDs de destinatários e as opções de chamada. Para o início rápido, serão utilizadas as opções de chamada predefinidas sem vídeo e um único ID de callee da entrada de texto.

/**
 * 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);
}

Inicie a aplicação e chame o bot echo

A aplicação pode agora ser iniciada com o botão "Executar Aplicação" na barra de ferramentas (Shift+F10). Verifique se consegue efetuar chamadas ao chamar 8:echo123. Será reproduzida uma mensagem pré-gravada e, em seguida, repetirá a sua mensagem para si.

Captura de ecrã a mostrar a aplicação concluída.

Neste início rápido, irá aprender a iniciar uma chamada com o SDK de Chamadas Azure Communication Services para iOS.

Código de Exemplo

Pode transferir a aplicação de exemplo do GitHub.

Pré-requisitos

Para concluir este tutorial, precisará dos seguintes pré-requisitos:

Configurar

Criar o projeto Xcode

No Xcode, crie um novo projeto iOS e selecione o Modelo de aplicação . Este tutorial utiliza a arquitetura SwiftUI, pelo que deve definir a Linguagem como Swift e a Interface de Utilizador como SwiftUI. Não vai criar testes durante este guia de introdução. Não hesite em desmarcar Incluir Testes.

Captura de ecrã a mostrar a janela Novo Projeto no Xcode.

Instalar o pacote e as dependências com o CocoaPods

  1. Para criar um Podfile para a sua aplicação, abra o terminal e navegue para a pasta do projeto e execute:

    pod init

  2. Adicione o seguinte código ao Podfile e guarde (certifique-se de que "target" corresponde ao nome do projeto):

    platform :ios, '13.0'
    use_frameworks!
    
    target 'AzureCommunicationCallingSample' do
      pod 'AzureCommunicationCalling', '~> 1.0.0'
    end
    
  3. Execute pod install.

  4. Abra o .xcworkspace com xcode.

Pedir acesso ao microfone

Para aceder ao microfone do dispositivo, tem de atualizar a Lista de Propriedades de Informação da sua aplicação com um NSMicrophoneUsageDescription. Defina o valor associado para um string que será incluído na caixa de diálogo que o sistema utiliza para pedir acesso ao utilizador.

Clique com o botão direito do rato na Info.plist entrada da árvore do projeto e selecione Abrir Como>Código Fonte. Adicione as seguintes linhas à secção de nível <dict> superior e, em seguida, guarde o ficheiro.

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

Configurar a arquitetura de aplicações

Abra o ficheiro ContentView.swift do projeto e adicione uma import declaração à parte superior do ficheiro para importar o AzureCommunicationCalling library. Além disso, importe AVFoundation, vamos precisar disto para o pedido de permissão de áudio no código.

import AzureCommunicationCalling
import AVFoundation

Substitua a implementação da ContentView estrutura por alguns controlos de IU simples que permitem a um utilizador iniciar e terminar uma chamada. Iremos anexar lógica de negócio a estes controlos neste início rápido.

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

Modelo de objeto

As seguintes classes e interfaces processam algumas das principais funcionalidades do SDK Azure Communication Services Calling:

Nome Descrição
CallClient O CallClient é o ponto de entrada principal para o SDK de Chamadas.
CallAgent O CallAgent é utilizado para iniciar e gerir chamadas.
CommunicationTokenCredential O CommunicationTokenCredential é utilizado como a credencial do token para instanciar o CallAgent.
CommunicationUserIdentifier O CommunicationUserIdentifier é utilizado para representar a identidade do utilizador, que pode ser uma das seguintes: CommunicationUserIdentifier/PhoneNumberIdentifier/CallingApplication.

Autenticar o cliente

Inicialize uma CallAgent instância com um Token de Acesso de Utilizador que nos permitirá fazer e receber chamadas.

No código seguinte, terá de substituir <USER ACCESS TOKEN> por um token de acesso de utilizador válido para o recurso. Veja a documentação do token de acesso de utilizador se ainda não tiver um token disponível.

Adicione o seguinte código à onAppear chamada de retorno em 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.")
    }
}

Iniciar uma chamada

O startCall método é definido como a ação que será executada quando o botão Iniciar Chamada for tocado. Atualize a implementação para iniciar uma chamada com :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")
                }
            }
        }
    }
}

Também pode utilizar as propriedades no StartCallOptions para definir as opções iniciais da chamada (ou seja, permite iniciar a chamada com o microfone desativado).

Terminar uma chamada

Implemente o endCall método para terminar a chamada atual quando o botão Terminar Chamada for tocado.

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

Executar o código

Pode criar e executar a sua aplicação no simulador iOS ao selecionarExecução de Produto> ou utilizando o atalho de teclado (⌘-R).

Aspeto e funcionalidade finais da aplicação de início rápido

Pode fazer uma chamada VOIP de saída ao fornecer um ID de utilizador no campo de texto e tocar no botão Iniciar Chamada . A chamada 8:echo123 liga-o a um bot de eco, o que é ótimo para começar e verificar se os seus dispositivos de áudio estão a funcionar.

Nota

Quando efetuar uma chamada pela primeira vez, o sistema irá pedir-lhe acesso ao microfone. Numa aplicação de produção, deve utilizar a AVAudioSession API para verificar o estado da permissão e atualizar corretamente o comportamento da aplicação quando a permissão não for concedida.

Limpar os recursos

Se quiser limpar e remover uma subscrição do Communication Services, pode eliminar o recurso ou grupo de recursos. Eliminar o grupo de recursos também elimina quaisquer outros recursos associados ao mesmo. Saiba mais sobre a limpeza de recursos.

Próximos passos

Para obter mais informações, veja os seguintes artigos: