Zarządzanie wywołaniami

Dowiedz się, jak zarządzać wywołaniami za pomocą zestawu SDK usług Azure Communication Services. Dowiesz się, jak umieszczać wywołania, zarządzać ich uczestnikami i właściwościami.

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Wdrożony zasób usług komunikacyjnych. Utwórz zasób usług komunikacyjnych.
• Element umożliwiający User Access Token włączenie klienta wywołania. Aby uzyskać więcej informacji na temat sposobu uzyskiwania User Access Token
• Opcjonalnie: ukończ przewodnik Szybki start, aby rozpocząć dodawanie wywołań do aplikacji

Instalacja zestawu SDK

Użyj polecenia , npm install aby zainstalować wspólny zestaw SDK usług Azure Communication Services i wywołujący dla języka JavaScript:

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

Inicjowanie wymaganych obiektów

Wystąpienie CallClient jest wymagane w przypadku większości operacji wywołania. Podczas tworzenia nowego CallClient wystąpienia można skonfigurować je za pomocą opcji niestandardowych, takich jak Logger wystąpienie.

CallClient Za pomocą wystąpienia można utworzyć CallAgent wystąpienie, wywołując element createCallAgent. Ta metoda asynchronicznie zwraca CallAgent obiekt wystąpienia.

Metoda createCallAgent używa CommunicationTokenCredential jako argumentu. Akceptuje token dostępu użytkownika.

Aby uzyskać dostęp deviceManagerdo obiektu , możesz użyć getDeviceManager metody w wystąpieniu CallClient .

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Jak najlepiej zarządzać łącznością zestawu SDK z infrastrukturą firmy Microsoft

Wystąpienie Call Agent pomaga zarządzać wywołaniami (aby dołączyć lub uruchomić wywołania). Aby można było pracować z zestawem SDK wywołującym, należy połączyć się z infrastrukturą firmy Microsoft, aby otrzymywać powiadomienia o połączeniach przychodzących i koordynować inne szczegóły połączeń. Istnieją Call Agent dwa możliwe stany:

Połączono — Call Agent wartość Connected connectionStatue oznacza, że zestaw SDK klienta jest połączony i może odbierać powiadomienia z infrastruktury firmy Microsoft.

Rozłączone — Call Agent wartość Disconnected connectionStatue stanów występuje problem uniemożliwiający prawidłowe nawiązywanie połączenia z zestawem SDK. Call Agent należy utworzyć ponownie.

• invalidToken: Jeśli token wygasł lub jest nieprawidłowe Call Agent wystąpienie rozłącza się z tym błędem.
• connectionIssue: Jeśli występuje problem z połączeniem klienta z infrastrukturą firmy Microsoft, po wielu ponownych próbach Call Agent connectionIssue wystąpi błąd.

Możesz sprawdzić, czy środowisko lokalne Call Agent jest połączone z infrastrukturą firmy Microsoft, sprawdzając bieżącą connectionState wartość właściwości. Podczas aktywnego wywołania można nasłuchiwać zdarzenia, connectionStateChanged aby określić, czy Call Agent zmiany ze stanu Połączono z Odłączone .

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

Umieszczanie połączenia

Aby utworzyć i uruchomić wywołanie, użyj jednego z interfejsów API w systemie callAgent i podaj użytkownika utworzonego za pomocą zestawu SDK tożsamości usług komunikacyjnych.

Tworzenie wywołań i uruchamianie są synchroniczne. Wystąpienie call umożliwia subskrybowanie zdarzeń wywoływania.

Umieść wywołanie 1:n do użytkownika lub pstn

Aby wywołać innego użytkownika usług Komunikacyjnych, użyj startCall metody włączonej callAgent i przekaż adresata CommunicationUserIdentifier utworzone za pomocą biblioteki administracyjnej usług komunikacyjnych.

W przypadku wywołania "1:1" dla użytkownika użyj następującego kodu:

const userCallee = { communicationUserId: '<ACS_USER_ID>' }
const oneToOneCall = callAgent.startCall([userCallee]);

Aby umieścić połączenie z publiczną przełączonym siecią telefoniczną (PSTN), użyj startCall metody włączonej callAgent i przekaż odbiorcę PhoneNumberIdentifier. Zasób usług komunikacyjnych musi być skonfigurowany tak, aby zezwalał na wywoływanie pstn.

Po wywołaniu numeru PSTN określ identyfikator alternatywnego obiektu wywołującego. Alternatywny identyfikator rozmówcy to numer telefonu (oparty na standardzie E.164), który identyfikuje rozmówcę w wywołaniu PSTN. Jest to numer telefonu, który odbiorca połączenia widzi w przypadku połączenia przychodzącego.

Uwaga

Sprawdź szczegóły oferty połączeń z siecią PSTN. Aby uzyskać dostęp do programu w wersji zapoznawczej, zastosuj się do programu wczesnego wdrażania.

W przypadku wywołania 1:1 do numeru PSTN użyj następującego kodu:

const pstnCallee = { phoneNumber: '<ACS_USER_ID>' }
const alternateCallerId = {phoneNumber: '<ALTERNATE_CALLER_ID>'};
const oneToOneCall = callAgent.startCall([pstnCallee], { alternateCallerId });

W przypadku wywołania 1:n dla użytkownika i numeru PSTN użyj następującego kodu:

const userCallee = { communicationUserId: '<ACS_USER_ID>' }
const pstnCallee = { phoneNumber: '<PHONE_NUMBER>'};
const alternateCallerId = {phoneNumber: '<ALTERNATE_CALLER_ID>'};
const groupCall = callAgent.startCall([userCallee, pstnCallee], { alternateCallerId });

Dołącz do połączenia z pokojem

Aby dołączyć wywołanieroom, możesz utworzyć wystąpienie obiektu kontekstu z właściwością roomId jako identyfikator.room Aby dołączyć wywołanie, użyj join metody i przekaż wystąpienie kontekstu.

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

Usługa room oferuje deweloperom aplikacji lepszą kontrolę nad tym, kto może dołączyć do połączenia, gdy się spotka i jak współpracują. Aby dowiedzieć się więcej na temat roomsusługi , możesz przeczytać dokumentację koncepcyjną lub skorzystać z przewodnika Szybki start.

Dołączanie do połączenia grupowego

Uwaga

Parametr groupId jest uważany za metadane systemowe i może być używany przez firmę Microsoft na potrzeby operacji wymaganych do uruchomienia systemu. Nie dołączaj danych osobowych do groupId wartości. Firma Microsoft nie traktuje tego parametru jako danych osobowych, a jego zawartość może być widoczna dla pracowników firmy Microsoft ani przechowywana długoterminowo.

Parametr groupId wymaga, aby dane w formacie GUID. Zalecamy używanie losowo generowanych identyfikatorów GUID, które nie są uznawane za dane osobowe w Twoich systemach.

Aby uruchomić nowe wywołanie grupy lub dołączyć do trwającego wywołania grupy, użyj join metody i przekaż obiekt z właściwością groupId . Wartość groupId musi być identyfikatorem GUID.

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

Odbieranie połączenia przychodzącego

Wystąpienie callAgent emituje incomingCall zdarzenie, gdy tożsamość zalogowana odbiera połączenie przychodzące. Aby nasłuchiwać tego zdarzenia, subskrybuj przy użyciu jednej z następujących opcji:

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

    // Get incoming call ID
    var incomingCallId = incomingCall.id

    // Get information about this Call. This API is provided as a preview for developers
    // and may change based on feedback that we receive. Do not use this API in a production environment.
    // To use this api please use 'beta' release of Azure Communication Services Calling Web SDK
    var callInfo = incomingCall.info;

    // Get information about caller
    var callerInfo = incomingCall.callerInfo

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

    // Reject the call
    incomingCall.reject();

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

    // callEndReason is also a property of IncomingCall
    var callEndReason = incomingCall.callEndReason;
};
callAgentInstance.on('incomingCall', incomingCallHandler);

Zdarzenie incomingCall zawiera incomingCall wystąpienie, które można zaakceptować lub odrzucić.

Zestaw SDK wywołania komunikacji platformy Azure zgłasza aparatStartFailed: diagnostyka prawdziwego wywołania, jeśli aparat nie jest dostępny podczas uruchamiania, akceptowania lub dołączania do połączenia z włączonym wideo. W takim przypadku wywołanie rozpoczyna się od wyłączenia wideo. Aparat może być niedostępny, ponieważ jest używany przez inny proces lub jest wyłączony w systemie operacyjnym.

Wstrzymaj i wznów połączenie

Uwaga

W dowolnym momencie powinno istnieć tylko 1 aktywne wywołanie (w Connected stanie z aktywnym nośnikiem). Wszystkie inne wywołania powinny być wstrzymane przez użytkownika lub programowo przez aplikację. Jest to typowe w scenariuszach, takich jak centra kontaktów, w których użytkownik może wymagać obsługi wielu połączeń wychodzących i przychodzących, wszystkie nieaktywne połączenia powinny być wstrzymane, a użytkownik powinien korzystać z innych osób tylko w aktywnym wywołaniu

Aby wstrzymać lub wznowić wywołanie, możesz użyć hold interfejsów API asynchronicznych i resume :

Aby trzymać połączenie

await call.hold();

Gdy hold interfejs API rozwiąże problem, stan wywołania jest ustawiony na LocalHoldwartość . W wywołaniu 1:1 drugi uczestnik jest również wstrzymany, a stan połączenia z perspektywy tego uczestnika jest ustawiony na "RemoteHold". Później inny uczestnik może wstrzymać połączenie, co spowodowałoby zmianę stanu na LocalHold. W wywołaniu grupy lub spotkaniu — hold jest to operacja lokalna, nie przechowuje wywołania dla innych uczestników połączenia. Aby wznowić wywołanie wszystkich użytkowników, którzy zainicjowali blokadę, musi ją wznowić.

Aby wznowić połączenie z blokady:

await call.resume();

resume Gdy interfejs API rozwiąże problem, stan wywołania zostanie ponownie ustawiony na Connectedwartość .

Wycisz i anuluj wyciszenie wywołania

Aby wyciszyć lub cofnąć wyciszenie lokalnego punktu końcowego, możesz użyć mute interfejsów API asynchronicznych i unmute :

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

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

Wycisz i anuluj wyciszanie przychodzącego dźwięku

Wycisz przychodzący dźwięk ustawia głośność wywołań na 0. Aby wyciszyć lub cofnąć wyciszenie przychodzącego dźwięku, możesz użyć muteIncomingAudio interfejsów API asynchronicznych i unmuteIncomingAudio :

//mute local device (speaker)
await call.muteIncomingAudio();

//unmute local device (speaker)
await call.unmuteIncomingAudio();

Gdy przychodzący dźwięk jest wyciszony, zestaw SDK klienta uczestnika nadal odbiera dźwięk połączenia (dźwięk uczestnika zdalnego). Dźwięk połączenia nie jest słyszany w głośniku, a uczestnik nie jest w stanie nasłuchiwać, dopóki nie zostanie wywołana funkcja "call.unmuteIncomingAudio()". Można jednak zastosować filtr dźwięku wywołania i odtworzyć przefiltrowany dźwięk.

Zarządzanie uczestnikami zdalnymi

Wszyscy uczestnicy zdalni RemoteParticipant są szczegółowo opisane w obiekcie i dostępne za pośrednictwem kolekcji w wystąpieniu remoteParticipants wywołania. Element remoteParticipants jest dostępny z Call wystąpienia.

Wyświetlanie listy uczestników połączenia

Kolekcja remoteParticipants zwraca listę uczestników zdalnych w wywołaniu:

call.remoteParticipants; // [remoteParticipant, remoteParticipant....]

Dodawanie uczestnika do połączenia

Aby dodać uczestnika (użytkownika lub numer telefonu) do połączenia, możesz użyć interfejsu addParticipant API. Podaj jeden z Identifier typów. Synchronicznie zwraca remoteParticipant wystąpienie. Zdarzenie remoteParticipantsUpdated z wywołania jest zgłaszane, gdy uczestnik zostanie pomyślnie dodany do połączenia.

const userIdentifier = { communicationUserId: '<ACS_USER_ID>' };
const pstnIdentifier = { phoneNumber: '<PHONE_NUMBER>' }
const remoteParticipant = call.addParticipant(userIdentifier);
const alternateCallerId = {  phoneNumber: '<ALTERNATE_CALLER_ID>' };
const remoteParticipant = call.addParticipant(pstnIdentifier, { alternateCallerId });

Usuwanie uczestnika z połączenia

Aby usunąć uczestnika (użytkownika lub numer telefonu) z połączenia, możesz wywołać metodę removeParticipant. Musisz przekazać jeden z Identifier typów. Ta metoda jest rozpoznawana asynchronicznie po usunięciu uczestnika z wywołania. Uczestnik zostanie również usunięty z kolekcji remoteParticipants .

const userIdentifier = { communicationUserId: '<ACS_USER_ID>' };
const pstnIdentifier = { phoneNumber: '<PHONE_NUMBER>' }
await call.removeParticipant(userIdentifier);
await call.removeParticipant(pstnIdentifier);

Uzyskiwanie dostępu do właściwości uczestnika zdalnego

Uczestnicy zdalni mają zestaw skojarzonych właściwości i kolekcji:

• CommunicationIdentifier: Pobierz identyfikator uczestnika zdalnego. Tożsamość jest jednym z CommunicationIdentifier typów:

const identifier = remoteParticipant.identifier;

• Może to być jeden z następujących CommunicationIdentifier typów:

  • { communicationUserId: '<ACS_USER_ID'> }: obiekt reprezentujący użytkownika usług Azure Communication Services.
  • { phoneNumber: '<E.164>' }: Obiekt reprezentujący numer telefonu w formacie E.164.
  • { microsoftTeamsUserId: '<TEAMS_USER_ID>', isAnonymous?: boolean; cloud?: "public" | "dod" | "gcch" }: obiekt reprezentujący użytkownika usługi Teams.
  • { id: string }: obiekt reprezentujący identyfikator, który nie pasuje do żadnego z innych typów identyfikatorów

• state: Uzyskaj stan uczestnika zdalnego.

const state = remoteParticipant.state;

• Stan może być:

  • Idle: stan początkowy.
  • Connecting: stan przejścia, gdy uczestnik nawiązuje połączenie z połączeniem.
  • Ringing: Uczestnik dzwoni.
  • Connected: Uczestnik jest połączony z połączeniem.
  • Hold: Uczestnik jest wstrzymany.
  • EarlyMedia: Ogłoszenie, które jest odtwarzane przed nawiązaniem połączenia przez uczestnika.
  • InLobby: wskazuje, że uczestnik zdalny znajduje się w holu.
  • Disconnected: stan końcowy. Uczestnik jest odłączony od połączenia. Jeśli uczestnik zdalny utraci łączność sieciową, jego stan zmieni się na Disconnected po dwóch minutach.

• callEndReason: Aby dowiedzieć się, dlaczego uczestnik opuścił połączenie, sprawdź callEndReason właściwość:

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

  Uwaga:

  • Ta właściwość jest ustawiana tylko podczas dodawania uczestnika zdalnego za pośrednictwem interfejsu API Call.addParticipant(), a na przykład uczestnik zdalny odrzuca.
  • W scenariuszu, w którym użytkownikB uruchamia element UserC z punktu widzenia użytkownika, użytkownikA nie widzi tej flagi, aby ustawić wartość UserC. Innymi słowy, właściwość UserA nie widzi właściwości UserC callEndReason zostanie ustawiona w ogóle.

• isMuted status: Aby dowiedzieć się, czy uczestnik zdalny jest wyciszony, sprawdź isMuted właściwość. Zwraca wartość Boolean.

  const isMuted = remoteParticipant.isMuted;
  

• isSpeaking status: Aby dowiedzieć się, czy uczestnik zdalny mówi, sprawdź isSpeaking właściwość. Zwraca wartość Boolean.

  const isSpeaking = remoteParticipant.isSpeaking;
  

• videoStreams: Aby sprawdzić wszystkie strumienie wideo wysyłane przez danego uczestnika w tym wywołaniu, sprawdź videoStreams kolekcję. Zawiera RemoteVideoStream on obiekty.

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

• displayName: Aby uzyskać nazwę wyświetlaną dla tego uczestnika zdalnego, sprawdź displayName właściwość zwracaną przez niego ciąg.

  const displayName = remoteParticipant.displayName;
  

• endpointDetails: Pobierz szczegóły wszystkich punktów końcowych dla tego uczestnika zdalnego

      const endpointDetails: EndpointDetails[] = remoteParticipant.endpointDetails;
  

  Uwaga: uczestnik zdalny może być w wywołaniu z wielu punktów końcowych, a każdy punkt końcowy ma swój własny unikatowy participantIdelement . participantId różni się od nieprzetworzonego identyfikatora RemoteParticipant.identifier.

Wycisz innych uczestników

Uwaga

Aby użyć tego interfejsu API, użyj usługi Azure Communication Services Wywołujący internetowy zestaw SDK w wersji 1.26.1 lub nowszej.

Aby wyciszyć wszystkich innych uczestników lub wyciszyć określonego uczestnika, który jest połączony z połączeniem, możesz użyć asynchronicznych interfejsów muteAllRemoteParticipants API podczas połączenia i mute uczestnika zdalnego. Zdarzenie mutedByOthers z połączenia jest zgłaszane, gdy uczestnik lokalny został wyciszony przez innych.

Uwaga: Scenariusze wyciszenia uczestników połączenia PSTN (numer telefonu) lub 1:1 uczestników połączeń nie są obsługiwane.

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

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

Sprawdzanie właściwości wywołania

Pobierz unikatowy identyfikator (ciąg) dla wywołania:

const callId: string = call.id;

Pobierz identyfikator lokalnego uczestnika:

const participantId: string = call.info.participantId;

Uwaga: tożsamość usług Azure Communication Services może używać zestawu SDK wywołującego sieć Web w wielu punktach końcowych, a każdy punkt końcowy ma swój własny unikatowy element participantId. participantId różni się od identyfikatora pierwotnego tożsamości usług Azure Communication Services.

Pobierz identyfikator wątku, jeśli dołączysz do spotkania usługi Teams:

const threadId: string | undefined = call.info.threadId;

Uzyskaj informacje o wywołaniu:

const callInfo = call.info;

Dowiedz się więcej na temat innych uczestników wywołania, sprawdzając remoteParticipants kolekcję w wystąpieniu "call":

const remoteParticipants = call.remoteParticipants;

Zidentyfikuj obiekt wywołujący połączenie przychodzące:

const callerIdentity = call.callerInfo.identifier;

identifier jest jednym z CommunicationIdentifier typów.

Pobierz stan wywołania:

const callState = call.state;

Spowoduje to zwrócenie ciągu reprezentującego bieżący stan wywołania:

• None: początkowy stan wywołania.
• Connecting: początkowy stan przejścia po umieszczeniu lub zaakceptowaniu wywołania.
• Ringing: W przypadku połączenia wychodzącego wskazuje, że wywołanie jest dzwoniące dla uczestników zdalnych. To po Incoming ich stronie.
• EarlyMedia: wskazuje stan, w którym anons jest odtwarzany przed połączeniem.
• Connected: wskazuje, że połączenie jest połączone.
• LocalHold: wskazuje, że lokalny uczestnik wywołania wstrzymał połączenie. Żaden nośnik nie przepływa między lokalnym punktem końcowym a uczestnikami zdalnymi.
• RemoteHold: wskazuje, że zdalny uczestnik wywołania wstrzymał wywołanie. Żaden nośnik nie przepływa między lokalnym punktem końcowym a uczestnikami zdalnymi.
• InLobby: wskazuje, że użytkownik znajduje się w holu.
• Disconnecting: stan przejścia przed przejściem wywołania Disconnected do stanu.
• Disconnected: Stan ostatniego wywołania. Jeśli połączenie sieciowe zostanie utracone, stan zmieni się na Disconnected po dwóch minutach.

Dowiedz się, dlaczego wywołanie zakończyło się, sprawdzając callEndReason właściwość:

const callEndReason = call.callEndReason;
const callEndReasonMessage = callEndReason.message // (string) user friendly message
const callEndReasonCode = callEndReason.code // (number) code associated with the reason
const callEndReasonSubCode = callEndReason.subCode // (number) subCode associated with the reason

Dowiedz się, czy bieżące wywołanie jest przychodzące lub wychodzące, sprawdzając direction właściwość. Zwraca wartość CallDirection.

const isIncoming = call.direction == 'Incoming';
const isOutgoing = call.direction == 'Outgoing';

Sprawdź aktywne strumienie wideo i strumienie udostępniania aktywnego ekranu, sprawdzając localVideoStreams kolekcję. Interfejs localVideoStreams API zwraca LocalVideoStream obiekty typu Video, ScreenSharinglub RawMedia.

const localVideoStreams = call.localVideoStreams;

Sprawdź, czy bieżący mikrofon jest wyciszony. Zwraca wartość Boolean.

const muted = call.isMuted;

Sprawdź, czy bieżący przychodzący dźwięk (głośnik) jest wyciszony. Zwraca wartość Boolean.

const incomingAudioMuted = call.isIncomingAudioMuted;

Sprawdź, czy wideo jest włączone. Zwraca wartość Boolean.

const isLocalVideoStarted = call.isLocalVideoStarted;

Sprawdź, czy udostępnianie ekranu jest włączone. Zwraca wartość Boolean.

const isScreenSharingOn = call.isScreenSharingOn;

Instalacja zestawu SDK

Znajdź plik na poziomie build.gradle projektu i dodaj mavenCentral() go do listy repozytoriów w obszarze buildscript i allprojects:

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

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

Następnie w pliku na poziomie build.gradle modułu dependencies dodaj następujące wiersze do sekcji:

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

Inicjowanie wymaganych obiektów

Aby utworzyć CallAgent wystąpienie, należy wywołać createCallAgent metodę w wystąpieniu CallClient . To wywołanie asynchroniczne zwraca CallAgent obiekt wystąpienia.

Metoda createCallAgent przyjmuje CommunicationUserCredential jako argument, który hermetyzuje token dostępu.

Aby uzyskać dostęp, DeviceManagernależy najpierw utworzyć callAgent wystąpienie. Następnie możesz użyć metody , aby pobrać metodę CallClient.getDeviceManager DeviceManager.

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

Aby ustawić nazwę wyświetlaną elementu wywołującego, użyj tej alternatywnej metody:

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

Umieszczanie połączenia

Aby utworzyć i uruchomić wywołanie, należy wywołać metodę CallAgent.startCall() i podać Identifier wywołania wywoływane. Aby dołączyć do wywołania grupy, należy wywołać metodę CallAgent.join() i podać identyfikator groupId. Identyfikatory grup muszą być w formacie GUID lub UUID.

Tworzenie wywołań i uruchamianie są synchroniczne. Wystąpienie wywołania umożliwia subskrybowanie wszystkich zdarzeń podczas wywołania.

Umieść wywołanie 1:1 do użytkownika

Aby umieścić wywołanie innego użytkownika usług Komunikacyjnych, wywołaj call metodę on callAgent i przekaż obiekt z kluczem communicationUserId .

StartCallOptions startCallOptions = new StartCallOptions();
Context appContext = this.getApplicationContext();
CommunicationUserIdentifier acsUserId = new CommunicationUserIdentifier(<USER_ID>);
CommunicationUserIdentifier participants[] = new CommunicationUserIdentifier[]{ acsUserId };
call oneToOneCall = callAgent.startCall(appContext, participants, startCallOptions);

Umieść połączenie 1:n z użytkownikami i siecią PSTN

Uwaga

Sprawdź szczegóły oferty połączeń z siecią PSTN. Aby uzyskać dostęp do programu w wersji zapoznawczej, zastosuj się do programu wczesnego wdrażania.

Aby umieścić połączenie 1:n dla użytkownika i numer PSTN, należy określić numer telefonu wywoływanego. Zasób usług komunikacyjnych musi być skonfigurowany tak, aby zezwalał na wywoływanie pstn:

CommunicationUserIdentifier acsUser1 = new CommunicationUserIdentifier(<USER_ID>);
PhoneNumberIdentifier acsUser2 = new PhoneNumberIdentifier("<PHONE_NUMBER>");
CommunicationIdentifier participants[] = new CommunicationIdentifier[]{ acsUser1, acsUser2 };
StartCallOptions startCallOptions = new StartCallOptions();
Context appContext = this.getApplicationContext();
Call groupCall = callAgent.startCall(participants, startCallOptions);

Akceptowanie połączenia

Aby zaakceptować wywołanie, wywołaj metodę "accept" dla obiektu wywołania.

Context appContext = this.getApplicationContext();
IncomingCall incomingCall = retrieveIncomingCall();
Call call = incomingCall.accept(context).get();

Aby zaakceptować połączenie z kamerą wideo w:

Context appContext = this.getApplicationContext();
IncomingCall incomingCall = retrieveIncomingCall();
AcceptCallOptions acceptCallOptions = new AcceptCallOptions();
VideoDeviceInfo desiredCamera = callClient.getDeviceManager().get().getCameraList().get(0);
acceptCallOptions.setVideoOptions(new VideoOptions(new LocalVideoStream(desiredCamera, appContext)));
Call call = incomingCall.accept(context, acceptCallOptions).get();

Połączenie przychodzące można uzyskać, subskrybując onIncomingCall zdarzenie w callAgent obiekcie:

// Assuming "callAgent" is an instance property obtained by calling the 'createCallAgent' method on CallClient instance 
public Call retrieveIncomingCall() {
    IncomingCall incomingCall;
    callAgent.addOnIncomingCallListener(new IncomingCallListener() {
        void onIncomingCall(IncomingCall inboundCall) {
            // Look for incoming call
            incomingCall = inboundCall;
        }
    });
    return incomingCall;
}

Dołącz do połączenia z pokojem

Użyj elementu CallAgent i RoomCallLocator , aby dołączyć do połączenia w pokoju, określając roomId. Metoda CallAgent.join zwróci Call obiekt:

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

Usługa room oferuje deweloperom aplikacji lepszą kontrolę nad tym, kto może dołączyć do połączenia, gdy się spotka i jak współpracują. Aby dowiedzieć się więcej na temat roomsusługi , możesz przeczytać dokumentację koncepcyjną lub skorzystać z przewodnika Szybki start.

Dołączanie do połączenia grupowego

Aby uruchomić nowe wywołanie grupy lub dołączyć do trwającego wywołania grupy, musisz wywołać metodę "join" i przekazać obiekt z właściwością groupId . Wartość musi być identyfikatorem GUID.

Context appContext = this.getApplicationContext();
GroupCallLocator groupCallLocator = new GroupCallLocator("<GUID>");
JoinCallOptions joinCallOptions = new JoinCallOptions();

call = callAgent.join(context, groupCallLocator, joinCallOptions);

Właściwości wywołania

Pobierz unikatowy identyfikator dla tego wywołania:

String callId = call.getId();

Aby dowiedzieć się więcej o innych uczestników kolekcji inspekcji remoteParticipant wywołań w wystąpieniu call :

List<RemoteParticipant> remoteParticipants = call.getRemoteParticipants();

Tożsamość obiektu wywołującego, jeśli połączenie jest przychodzące:

CommunicationIdentifier callerId = call.getCallerInfo().getIdentifier();

Pobierz stan wywołania:

CallState callState = call.getState();

Zwraca on ciąg reprezentujący bieżący stan wywołania:

• "NONE" — początkowy stan wywołania
• "EARLY_MEDIA" — wskazuje stan, w którym jest odtwarzane ogłoszenie przed połączeniem
• "ŁĄCZENIE" — początkowy stan przejścia po umieszczeniu lub zaakceptowaniu wywołania
• "DZWONIENIE" — w przypadku połączenia wychodzącego — wskazuje, że połączenie dzwoni dla uczestników zdalnych
• "CONNECTED" — połączenie jest połączone
• "LOCAL_HOLD" — połączenie jest wstrzymane przez uczestnika lokalnego, żaden nośnik nie przepływa między lokalnym punktem końcowym a uczestnikami zdalnymi
• "REMOTE_HOLD" — połączenie jest wstrzymane przez uczestnika zdalnego, żaden nośnik nie przepływa między lokalnym punktem końcowym a uczestnikami zdalnymi
• "ROZŁĄCZANIE" — stan przejścia przed przejściem do stanu "Rozłączone"
• "ROZŁĄCZONE" — stan ostatniego wywołania
• "IN_LOBBY" — w holu na potrzeby współdziałania spotkania usługi Teams

Aby dowiedzieć się, dlaczego połączenie zakończyło się, sprawdź callEndReason właściwość . Zawiera kod/podkodowanie:

CallEndReason callEndReason = call.getCallEndReason();
int code = callEndReason.getCode();
int subCode = callEndReason.getSubCode();

Aby sprawdzić, czy bieżące wywołanie jest przychodzące lub wychodzące, sprawdź callDirection właściwość:

CallDirection callDirection = call.getCallDirection(); 
// callDirection == CallDirection.INCOMING for incoming call
// callDirection == CallDirection.OUTGOING for outgoing call

Aby sprawdzić, czy bieżący mikrofon jest wyciszony, sprawdź muted właściwość:

boolean muted = call.isMuted();

Aby sprawdzić aktywne strumienie wideo, sprawdź localVideoStreams kolekcję:

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

Wycisz i Wyłącz wyciszenie

Aby wyciszyć lub cofnąć wyciszenie lokalnego punktu końcowego, możesz użyć mute interfejsów API asynchronicznych i unmute :

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

Zmienianie woluminu wywołania

Podczas rozmowy klucze woluminu sprzętowego na telefonie powinny zezwalać użytkownikowi na zmianę woluminu połączeń. Odbywa się to przy użyciu metody setVolumeControlStream z typem AudioManager.STREAM_VOICE_CALL strumienia w działaniu, w którym jest umieszczane wywołanie. Dzięki temu głośności sprzętu mogą zmieniać głośność połączenia (oznaczone ikoną telefonu lub podobne na suwaku głośności), uniemożliwiając zmianę głośności dla innych profilów dźwięku, takich jak alarmy, nośniki lub głośność systemu. Aby uzyskać więcej informacji, zobacz Obsługa zmian w danych wyjściowych dźwięku | Deweloperzy systemu Android.

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

Zarządzanie uczestnikami zdalnymi

Wszyscy uczestnicy zdalni są reprezentowani przez RemoteParticipant typ i są dostępne za pośrednictwem remoteParticipants kolekcji w wystąpieniu wywołania.

Wyświetlanie listy uczestników połączenia

Kolekcja remoteParticipants zwraca listę uczestników zdalnych w danym wywołaniu:

List<RemoteParticipant> remoteParticipants = call.getRemoteParticipants(); // [remoteParticipant, remoteParticipant....]

Dodawanie uczestnika do połączenia

Aby dodać uczestnika do połączenia (użytkownika lub numeru telefonu), możesz wywołać metodę addParticipant. Spowoduje to synchronicznie zwrócenie wystąpienia uczestnika zdalnego.

const acsUser = new CommunicationUserIdentifier("<acs user id>");
const acsPhone = new PhoneNumberIdentifier("<phone number>");
RemoteParticipant remoteParticipant1 = call.addParticipant(acsUser);
AddPhoneNumberOptions addPhoneNumberOptions = new AddPhoneNumberOptions(new PhoneNumberIdentifier("<alternate phone number>"));
RemoteParticipant remoteParticipant2 = call.addParticipant(acsPhone, addPhoneNumberOptions);

Usuwanie uczestnika z połączenia

Aby usunąć uczestnika z połączenia (użytkownika lub numeru telefonu), możesz wywołać metodę removeParticipant. Spowoduje to rozwiązanie asynchroniczne po usunięciu uczestnika z wywołania. Uczestnik zostanie również usunięty z remoteParticipants kolekcji.

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

Właściwości uczestnika zdalnego

Każdy uczestnik zdalny ma skojarzony zestaw właściwości i kolekcji:

• Pobierz identyfikator tego uczestnika zdalnego. Tożsamość jest jednym z typów "Identyfikator"

  CommunicationIdentifier participantIdentifier = remoteParticipant.getIdentifier();
  

• Uzyskaj stan tego uczestnika zdalnego.

  ParticipantState state = remoteParticipant.getState();
  

Stan może być jednym z

• "IDLE" — stan początkowy

• "EARLY_MEDIA" — ogłoszenie jest odtwarzane przed połączeniem uczestnika

• "DZWONIENIE" — dzwonienie uczestnika

• "ŁĄCZENIE" — stan przejścia, gdy uczestnik nawiązuje połączenie z połączeniem

• "CONNECTED" — uczestnik jest połączony z połączeniem

• "HOLD" — uczestnik jest wstrzymany

• "IN_LOBBY" - uczestnik czeka w holu, aby zostać przyjęty. Obecnie używane tylko w scenariuszu międzyoperacyjności usługi Teams

• "ROZŁĄCZONE" — stan końcowy — uczestnik jest odłączony od połączenia

• Aby dowiedzieć się, dlaczego uczestnik opuścił połączenie, sprawdź callEndReason właściwość:

  CallEndReason callEndReason = remoteParticipant.getCallEndReason();
  

• Aby sprawdzić, czy ten uczestnik zdalny jest wyciszony, czy nie, sprawdź isMuted właściwość:

  boolean isParticipantMuted = remoteParticipant.isMuted();
  

• Aby sprawdzić, czy ten zdalny uczestnik mówi, czy nie, sprawdź isSpeaking właściwość:

  boolean isParticipantSpeaking = remoteParticipant.isSpeaking();
  

• Aby sprawdzić wszystkie strumienie wideo wysyłane przez danego uczestnika w tym wywołaniu, sprawdź videoStreams kolekcję:

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

Wycisz innych uczestników

Uwaga

Aby użyć tego interfejsu API, użyj usługi Azure Communication Services wywołujących zestaw Android SDK w wersji 2.11.0 lub nowszej.

Aby wyciszyć wszystkich innych uczestników wywołania, użyj interfejsu muteAllRemoteParticipants API podczas wywołania.

call.muteAllRemoteParticipants();

Aby wyciszyć określonego uczestnika zdalnego, użyj interfejsu mute API dla danego uczestnika zdalnego.

remoteParticipant.mute();

Aby powiadomić uczestnika lokalnego, że został wyciszony przez innych, zasubskrybuj onMutedByOthers wydarzenie.

Korzystanie z usług pierwszego planu

W przypadkach, gdy chcesz uruchomić zadanie widoczne dla użytkownika, nawet jeśli aplikacja jest w tle, możesz użyć usług Foreground Services.

Korzystając z usług Foreground Services, można na przykład zachować widoczne dla użytkownika powiadomienie, gdy aplikacja ma aktywne wywołanie. W ten sposób, nawet jeśli użytkownik przejdzie do ekranu głównego lub usunie aplikację z ostatniego ekranu, wywołanie będzie nadal aktywne.

Jeśli nie używasz usługi foreground podczas wywołania, przejście do ekranu głównego może zachować aktywne wywołanie, ale usunięcie aplikacji z ostatniego ekranu może zatrzymać wywołanie, jeśli system operacyjny Android zabije proces aplikacji.

Podczas uruchamiania/dołączania wywołania należy uruchomić usługę Foreground, na przykład:

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

Zatrzymaj usługę pierwszego planu, gdy zawieszasz się wywołanie lub stan wywołania jest rozłączony, na przykład:

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

Uwagi dotyczące korzystania z usług Foreground Services

Należy pamiętać, że scenariusze, takie jak zatrzymanie już uruchomionej usługi Foreground, gdy aplikacja zostanie usunięta z listy ostatnich, spowoduje usunięcie widocznego powiadomienia użytkownika, a system operacyjny Android może zachować proces aplikacji przez pewien dodatkowy czas, co oznacza, że wywołanie może być nadal aktywne w tym okresie.

Jeśli na przykład aplikacja zatrzymuje usługę Foreground Service w metodzie usługi onTaskRemoved , aplikacja może uruchamiać/zatrzymywać dźwięk i wideo zgodnie z cyklem życia działania, takimi jak zatrzymywanie dźwięku i wideo, gdy działanie zostanie zniszczone za pomocą onDestroy metody zastąpienia.

Konfigurowanie systemu

Wykonaj następujące kroki, aby skonfigurować system.

Tworzenie projektu Xcode

W programie Xcode utwórz nowy projekt systemu iOS i wybierz szablon Aplikacja z jednym widokiem. W tym artykule jest używana struktura SwiftUI, dlatego należy ustawić wartość Language na Swift i ustawić wartość Interface na SwiftUI.

Nie zamierzasz tworzyć testów w tym artykule. Możesz wyczyścić pole wyboru Uwzględnij testy .

Instalowanie pakietu i zależności przy użyciu narzędzia CocoaPods

1. Utwórz plik Podfile dla aplikacji, podobnie jak w tym przykładzie:

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

2. Uruchom program pod install.

3. Otwórz .xcworkspace za pomocą programu Xcode.

Żądanie dostępu do mikrofonu

Aby uzyskać dostęp do mikrofonu urządzenia, należy zaktualizować listę właściwości informacji aplikacji przy użyciu polecenia NSMicrophoneUsageDescription. Ustaw skojarzona wartość na ciąg zawarty w oknie dialogowym używanym przez system do żądania dostępu od użytkownika.

Kliknij prawym przyciskiem myszy wpis Info.plist drzewa projektu, a następnie wybierz pozycję Otwórz jako>kod źródłowy. Dodaj następujące wiersze w sekcji najwyższego poziomu <dict> , a następnie zapisz plik.

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

Konfigurowanie struktury aplikacji

Otwórz plik projektu ContentView.swift . Dodaj deklarację import na początku pliku, aby zaimportować bibliotekę AzureCommunicationCalling . Ponadto zaimportuj plik AVFoundation. Potrzebne są żądania uprawnień dźwięku w kodzie.

import AzureCommunicationCalling
import AVFoundation

Inicjowanie klasy CallAgent

Aby utworzyć CallAgent wystąpienie z CallClientklasy , należy użyć callClient.createCallAgent metody, która asynchronicznie zwraca CallAgent obiekt po zainicjowaniu.

Aby utworzyć klienta wywołania, przekaż CommunicationTokenCredential obiekt:

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

CommunicationTokenCredential Przekaż utworzony obiekt do CallClient, a następnie ustaw nazwę wyświetlaną:

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

Uwaga

Gdy aplikacja implementuje delegaty zdarzeń, musi przechowywać silne odwołanie do obiektów, które wymagają subskrypcji zdarzeń. Na przykład gdy RemoteParticipant obiekt jest zwracany podczas wywoływania metody, a aplikacja ustawia delegata do nasłuchiwania call.addParticipant w RemoteParticipantDelegatesystemie aplikacja musi przechowywać silne odwołanie do RemoteParticipant obiektu. W przeciwnym razie jeśli ten obiekt zostanie zebrany, delegat zgłosi krytyczny wyjątek, gdy zestaw SDK wywołujący spróbuje wywołać obiekt.

Umieszczanie połączenia wychodzącego

Aby utworzyć i uruchomić wywołanie, należy wywołać jeden z interfejsów API w usłudze CallAgent i udostępnić tożsamość usług komunikacyjnych użytkownika, który został aprowizowany przy użyciu zestawu SDK zarządzania usługami komunikacyjnymi.

Tworzenie wywołań i uruchamianie są synchroniczne. Otrzymasz wystąpienie wywołania, które umożliwia subskrybowanie wszystkich zdarzeń w wywołaniu.

Umieść połączenie 1:1 z użytkownikiem lub połączeniem 1:n z użytkownikami i siecią PSTN

let callees = [CommunicationUser(identifier: 'UserId')]
self.callAgent?.startCall(participants: callees, options: StartCallOptions()) { (call, error) in
     if error == nil {
         print("Successfully started outgoing call")
         self.call = call
     } else {
         print("Failed to start outgoing call")
     }
}

Umieść połączenie 1:n z użytkownikami i siecią PSTN

Uwaga

Sprawdź szczegóły oferty połączeń z siecią PSTN. Aby uzyskać dostęp do programu w wersji zapoznawczej, zastosuj się do programu wczesnego wdrażania.

Aby umieścić połączenie z siecią PSTN, należy określić numer telefonu uzyskany w usługach komunikacyjnych.

let pstnCallee = PhoneNumberIdentifier(phoneNumber: '+1999999999')
let callee = CommunicationUserIdentifier('UserId')
self.callAgent?.startCall(participants: [pstnCallee, callee], options: StartCallOptions()) { (groupCall, error) in
     if error == nil {
         print("Successfully started outgoing call to multiple participants")
         self.call = groupCall
     } else {
         print("Failed to start outgoing call to multiple participants")
     }
}

Dołącz do połączenia z pokojem

Aby dołączyć do wywołania room , określ roomId właściwość jako room identyfikator. Aby dołączyć wywołanie, użyj join metody i przekaż metodę roomCallLocator.

func joinRoomCall() {
    if self.callAgent == nil {
        print("CallAgent not initialized")
        return
    }
    
    if (self.roomId.isEmpty) {
        print("Room ID not set")
        return
    }
    
    // Join a call with a Room ID
    let options = JoinCallOptions()
    let audioOptions = AudioOptions()
    audioOptions.muted = self.muted
    
    options.audioOptions = audioOptions
    
    let roomCallLocator = RoomCallLocator(roomId: roomId)
    self.callAgent!.join(with: roomCallLocator, joinCallOptions: options) { (call, error) in
        self.setCallAndObserver(call: call, error: error)
    }
}

Usługa room oferuje deweloperom aplikacji lepszą kontrolę nad tym, kto może dołączyć do połączenia, gdy się spotka i jak współpracują. Aby dowiedzieć się więcej na temat roomsusługi , możesz przeczytać dokumentację koncepcyjną lub skorzystać z przewodnika Szybki start.

Dołączanie do połączenia grupowego

Aby dołączyć do wywołania, należy wywołać jeden z interfejsów API w usłudze CallAgent.

let groupCallLocator = GroupCallLocator(groupId: UUID(uuidString: "uuid_string")!)
self.callAgent?.join(with: groupCallLocator, joinCallOptions: JoinCallOptions()) { (call, error) in
    if error == nil {
        print("Successfully joined group call")
        self.call = call
    } else {
        print("Failed to join group call")
    }
}

Subskrybowanie połączenia przychodzącego

Subskrybuj zdarzenie połączenia przychodzącego.

final class IncomingCallHandler: NSObject, CallAgentDelegate, IncomingCallDelegate
{
    // Event raised when there is an incoming call
    public func callAgent(_ callAgent: CallAgent, didReceiveIncomingCall incomingcall: IncomingCall) {
        self.incomingCall = incomingcall
        // Subscribe to get OnCallEnded event
        self.incomingCall?.delegate = self
    }

    // Event raised when incoming call was not answered
    public func incomingCall(_ incomingCall: IncomingCall, didEnd args: PropertyChangedEventArgs) {
        print("Incoming call was not answered")
        self.incomingCall = nil
    }
}

Akceptowanie połączenia przychodzącego

Aby zaakceptować wywołanie, wywołaj accept metodę IncomingCall w obiekcie.

self.incomingCall!.accept(options: AcceptCallOptions()) { (call, error) in
   if (error == nil) {
       print("Successfully accepted incoming call")
       self.call = call
   } else {
       print("Failed to accept incoming call")
   }
}

let firstCamera: VideoDeviceInfo? = self.deviceManager!.cameras.first
localVideoStreams = [LocalVideoStream]()
localVideoStreams!.append(LocalVideoStream(camera: firstCamera!))
let acceptCallOptions = AcceptCallOptions()
acceptCallOptions.videoOptions = VideoOptions(localVideoStreams: localVideoStreams!)
if let incomingCall = self.incomingCall {
    incomingCall.accept(options: acceptCallOptions) { (call, error) in
        if error == nil {
            print("Incoming call accepted")
        } else {
            print("Failed to accept incoming call")
        }
    }
} else {
  print("No incoming call found to accept")
}

Wykonywanie operacji w połowie wywołania

Podczas wywołania można wykonywać różne operacje w celu zarządzania ustawieniami związanymi z wideo i audio.

Wycisz i Wyłącz wyciszenie

Aby wyciszyć lub cofnąć wyciszenie lokalnego punktu końcowego, możesz użyć mute interfejsów API asynchronicznych i unmute .

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

Użyj następującego kodu, aby usunąć asynchronicznie wyciszenie lokalnego punktu końcowego.

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

Zarządzanie uczestnikami zdalnymi

Wszyscy uczestnicy zdalni są reprezentowani przez RemoteParticipant typ i są dostępne za pośrednictwem remoteParticipants kolekcji w wystąpieniu wywołania.

Wyświetlanie listy uczestników połączenia

call.remoteParticipants

Dodawanie uczestnika do połączenia

Aby dodać uczestnika do połączenia (użytkownika lub numeru telefonu), możesz wywołać metodę addParticipant. To polecenie synchronicznie zwróci wystąpienie uczestnika zdalnego.

let remoteParticipantAdded: RemoteParticipant = call.add(participant: CommunicationUserIdentifier(identifier: "userId"))

Usuwanie uczestnika z połączenia

Aby usunąć uczestnika z połączenia (użytkownika lub numeru telefonu), możesz wywołać removeParticipant interfejs API. Spowoduje to rozwiązanie asynchroniczne.

call!.remove(participant: remoteParticipantAdded) { (error) in
    if (error == nil) {
        print("Successfully removed participant")
    } else {
        print("Failed to remove participant")
    }
}

Pobieranie właściwości uczestnika zdalnego

// [RemoteParticipantDelegate] delegate - an object you provide to receive events from this RemoteParticipant instance
var remoteParticipantDelegate = remoteParticipant.delegate

// [CommunicationIdentifier] identity - same as the one used to provision a token for another user
var identity = remoteParticipant.identifier

// ParticipantStateIdle = 0, ParticipantStateEarlyMedia = 1, ParticipantStateConnecting = 2, ParticipantStateConnected = 3, ParticipantStateOnHold = 4, ParticipantStateInLobby = 5, ParticipantStateDisconnected = 6
var state = remoteParticipant.state

// [Error] callEndReason - reason why participant left the call, contains code/subcode/message
var callEndReason = remoteParticipant.callEndReason

// [Bool] isMuted - indicating if participant is muted
var isMuted = remoteParticipant.isMuted

// [Bool] isSpeaking - indicating if participant is currently speaking
var isSpeaking = remoteParticipant.isSpeaking

// RemoteVideoStream[] - collection of video streams this participants has
var videoStreams = remoteParticipant.videoStreams // [RemoteVideoStream, RemoteVideoStream, ...]

Wycisz innych uczestników

Uwaga

Aby użyć tego interfejsu API, użyj usługi Azure Communication Services wywołujących zestaw SDK systemu iOS w wersji 2.13.0 lub nowszej.

Aby wyciszyć wszystkich innych uczestników wywołania, użyj interfejsu muteAllRemoteParticipants API podczas wywołania.

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

Aby wyciszyć określonego uczestnika zdalnego, użyj interfejsu mute API dla danego uczestnika zdalnego.

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

Aby powiadomić uczestnika lokalnego, że został wyciszony przez innych, zasubskrybuj onMutedByOthers wydarzenie.

Konfigurowanie systemu

Wykonaj następujące kroki, aby skonfigurować system.

Tworzenie projektu programu Visual Studio

W przypadku aplikacji platforma uniwersalna systemu Windows w programie Visual Studio 2022 utwórz nowy projekt Pusta aplikacja (uniwersalny system Windows). Po wprowadzeniu nazwy projektu możesz wybrać dowolny zestaw Windows SDK nowszy niż 10.0.17763.0.

W przypadku aplikacji WinUI 3 utwórz nowy projekt z pustą aplikacją, spakowanym szablonem (WinUI 3 w programie Desktop), aby skonfigurować jednostronicową aplikację WinUI 3. Wymagany jest zestaw Windows App SDK w wersji 1.3 lub nowszej.

Instalowanie pakietu i zależności przy użyciu Menedżer pakietów NuGet

Interfejsy API i biblioteki zestawu SDK wywołujących są publicznie dostępne za pośrednictwem pakietu NuGet.

Aby znaleźć, pobrać i zainstalować pakiet NuGet zestawu SDK wywołującego:

1. Otwórz Menedżer pakietów NuGet, wybierając pozycję Narzędzia>NuGet Menedżer pakietów> Zarządzanie pakietami NuGet dla rozwiązania.
2. Wybierz pozycję Przeglądaj, a następnie wprowadź ciąg Azure.Communication.Calling.WindowsClient w polu wyszukiwania.
3. Upewnij się, że pole wyboru Uwzględnij wersję wstępną zostało zaznaczone.
4. Wybierz pakiet Azure.Communication.Calling.WindowsClient, a następnie wybierz pozycję Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 lub nowszą wersję.
5. Zaznacz pole wyboru odpowiadające projektowi usług Azure Communication Services w okienku po prawej stronie.
6. Wybierz Zainstaluj.

Żądanie dostępu do mikrofonu

Aplikacja wymaga dostępu do mikrofonu, aby działał prawidłowo. W aplikacjach platformy UWP możliwość mikrofonu powinna być zadeklarowana w pliku manifestu aplikacji.

W poniższych krokach przedstawiono sposób, w jaki to osiągnąć.

1. Solution Explorer Na panelu kliknij dwukrotnie plik z .appxmanifest rozszerzeniem.
2. Kliknij kartę Capabilities .
3. Microphone Zaznacz pole wyboru z listy możliwości.

Tworzenie przycisków interfejsu użytkownika w celu umieszczania i zawieszania się wywołania

Ta prosta przykładowa aplikacja zawiera dwa przyciski. Jeden do umieszczenia połączenia, a drugi, aby zawiesić umieszczone połączenie. W poniższych krokach przedstawiono sposób dodawania tych przycisków do aplikacji.

1. Solution Explorer Na panelu kliknij dwukrotnie plik o nazwie MainPage.xaml dla platformy UWP lub MainWindows.xaml winUI 3.
2. Na panelu centralnym wyszukaj kod XAML w obszarze podglądu interfejsu użytkownika.
3. Zmodyfikuj kod XAML, korzystając z następującego fragmentu:

<TextBox x:Name="CalleeTextBox" PlaceholderText="Who would you like to call?" />
<StackPanel>
    <Button x:Name="CallButton" Content="Start/Join call" Click="CallButton_Click" />
    <Button x:Name="HangupButton" Content="Hang up" Click="HangupButton_Click" />
</StackPanel>

Konfigurowanie aplikacji przy użyciu wywoływanych interfejsów API zestawu SDK

Interfejsy API wywołującego zestawu SDK znajdują się w dwóch różnych przestrzeniach nazw. Poniższe kroki informują kompilator języka C# o tych przestrzeniach nazw, dzięki czemu funkcja IntelliSense programu Visual Studio może pomóc w tworzeniu kodu.

1. Solution Explorer W panelu kliknij strzałkę po lewej stronie pliku o nazwie MainPage.xaml dla platformy UWP lub MainWindows.xaml winUI 3.
2. Kliknij dwukrotnie plik o nazwie MainPage.xaml.cs lub MainWindows.xaml.cs.
3. Dodaj następujące polecenia w dolnej części bieżących using instrukcji.

using Azure.Communication.Calling.WindowsClient;

Zachowaj MainPage.xaml.cs lub MainWindows.xaml.cs otwórz. Następne kroki spowodują dodanie do niego większej liczby kodu.

Zezwalaj na interakcje aplikacji

Przyciski interfejsu użytkownika dodane wcześniej muszą działać na górze umieszczonego CommunicationCallelementu . Oznacza to, że element członkowski CommunicationCall danych powinien zostać dodany do MainPage klasy lub MainWindow . Ponadto aby umożliwić tworzenie operacji asynchronicznej w celu pomyślnego wykonania CallAgent , CallAgent należy również dodać element członkowski danych do tej samej klasy.

Dodaj następujące składowe danych do MainPage klasy pr MainWindow :

CallAgent callAgent;
CommunicationCall call;

Tworzenie procedur obsługi przycisków

Wcześniej do kodu XAML dodano dwa przyciski interfejsu użytkownika. Poniższy kod dodaje programy obsługi do wykonania po wybraniu przycisku przez użytkownika. Poniższy kod powinien zostać dodany po elementach członkowskich danych z poprzedniej sekcji.

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

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

Model obiektów

Następujące klasy i interfejsy obsługują niektóre główne funkcje biblioteki klienta wywołujących usługi Azure Communication Services dla platformy UWP.

Nazwa/nazwisko	opis
CallClient	Jest CallClient to główny punkt wejścia do biblioteki wywołującej klienta.
CallAgent	Element służy do uruchamiania CallAgent i dołączania wywołań.
CommunicationCall	Służy CommunicationCall do zarządzania umieszczonymi lub sprzężonym wywołaniami.
CommunicationTokenCredential	Element CommunicationTokenCredential jest używany jako poświadczenie tokenu w celu utworzenia wystąpienia elementu CallAgent.
CallAgentOptions	Zawiera CallAgentOptions informacje identyfikujące obiekt wywołujący.
HangupOptions	Informuje, HangupOptions czy połączenie powinno zostać zakończone dla wszystkich jego uczestników.

Inicjowanie klasy CallAgent

Aby utworzyć CallAgent wystąpienie z CallClientklasy , należy użyć CallClient.CreateCallAgentAsync metody, która asynchronicznie zwraca CallAgent obiekt po zainicjowaniu.

Aby utworzyć CallAgentobiekt , należy przekazać CallTokenCredential obiekt i CallAgentOptions obiekt. Należy pamiętać, że CallTokenCredential zgłasza błąd w przypadku przekazania źle sformułowanego tokenu.

Poniższy kod powinien zostać dodany wewnątrz funkcji pomocnika i wywoływany w inicjalizacji aplikacji.

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

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

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

Zmień element <AUTHENTICATION_TOKEN> przy użyciu prawidłowego tokenu poświadczeń dla zasobu. Jeśli token poświadczeń musi być źródłowy, zapoznaj się z dokumentacją tokenu dostępu użytkownika.

Tworzenie elementu CallAgent i umieszczanie wywołania

Obiekty potrzebne do utworzenia obiektu CallAgent są teraz gotowe. Nadszedł czas, aby asynchronicznie utworzyć CallAgent i umieścić wywołanie.

Po obsłudze wyjątku z poprzedniego kroku należy dodać następujący kod.

var startCallOptions = new StartCallOptions();
var callees = new [] { new UserCallIdentifier(CalleeTextBox.Text.Trim()) };

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

Możesz użyć polecenia , aby porozmawiać z 8:echo123 botem echo usług Azure Communication Services.

Wycisz i Wyłącz wyciszenie

Aby wyciszyć lub cofnąć wyciszenie wychodzącego dźwięku, możesz użyć MuteOutgoingAudioAsync interfejsów API asynchronicznych i UnmuteOutgoingAudioAsync :

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

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

Wycisz innych uczestników

Uwaga

Aby użyć tego interfejsu API, użyj usług Azure Communication Services wywołujących zestaw Windows SDK w wersji 1.9.0 lub nowszej.

Aby wyciszyć wszystkich innych uczestników lub wyciszyć określonego uczestnika, możesz użyć asynchronicznych interfejsów MuteAllRemoteParticipantsAsync API podczas wywołania i MuteAsync uczestnika zdalnego:

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

// mute specific participant in the call
await this.call.RemoteParticipants.FirstOrDefault().MuteAsync();

Aby powiadomić uczestnika lokalnego, że został wyciszony przez innych, zasubskrybuj MutedByOthers wydarzenie.

Kończ połączenie

Po umieszczeniu HangupAsync wywołania należy użyć metody CommunicationCall obiektu w celu zawieszenia wywołania.

Należy również użyć wystąpienia HangupOptions , aby poinformować, czy połączenie musi zostać zakończone dla wszystkich jego uczestników.

W pliku HangupButton_Clicknależy dodać następujący kod.

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

Uruchamianie kodu

Upewnij się, że program Visual Studio skompiluje aplikację dla x64x86 , lub ARM64, a następnie naciśnij polecenie F5 , aby rozpocząć uruchamianie aplikacji. Następnie kliknij Call przycisk, aby umieścić wywołanie do zdefiniowanej metody wywoływanej.

Pamiętaj, że przy pierwszym uruchomieniu aplikacji system monituje użytkownika o udzielenie dostępu do mikrofonu.

Następne kroki

• Dowiedz się, jak zarządzać filmem wideo
• Dowiedz się, jak rejestrować wywołania
• Dowiedz się, jak transkrybować wywołania