Verwalten von Anrufen

In diesem Artikel wird beschrieben, wie Anrufe mithilfe des Azure Communication Services Calling SDK verwaltet werden. Zu den Themen zählen das Tätigen von Anrufen, das Verwalten von Teilnehmern und das Verwalten von Eigenschaften.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Eine bereitgestellte Communication Services-Ressource. Erstellen Sie eine Communication Services-Ressource.
• Ein User Access Token, um den Anrufclient zu aktivieren. Weitere Informationen zum Abrufen eines User Access Token
• Optional: Schließen Sie die ersten Schritte mit dem Hinzufügen von Aufrufen zu Ihrer Anwendung ab.

Unterstützung

In den folgenden Tabellen wird die Unterstützung für Gruppenräume in Azure Communication Services definiert.

Identitäten und Anruftypen

Die folgende Tabelle enthält eine Zusammenfassung der Unterstützung von Funktionen für bestimmte Anruftypen und Identitäten.

Identitäten	Teams-Besprechung	Raum	1:1-Anruf	Gruppenanruf	1:1 Teams-Interoperabilitätsanruf	Teams-Gruppeninteropanruf
Communication Services-Benutzer	✔️	✔️	✔️	✔️	✔️	✔️
Microsoft 365-Benutzer	✔️				✔️	✔️

Vorgänge

Die folgende Tabelle zeigt die Unterstützung einzelner APIs im Calling SDK im Zusammenhang mit einzelnen Identitätstypen.

Vorgänge	Communication Services-Benutzer	Microsoft 365-Benutzer
Einen Anruf an einen Communication Services-Benutzer starten	✔️
Einen Anruf an einen Microsoft 365-Benutzer starten	✔️	✔️
Einen Anruf an eine Telefonnummer starten	✔️	✔️
Einem Chatroom beitreten	✔️
Teilnehmen an einer Teams-Besprechung	✔️	✔️
Einem Anruf basierend auf der „groupId“ beitreten	✔️
Eingehenden Anruf annehmen oder ablehnen	✔️	✔️
Halten und Fortsetzen eines Anrufs	✔️	✔️
Teilnehmer abrufen	✔️	✔️
Communication Services-Benutzer hinzufügen	✔️
Communication Services-Benutzer entfernen	✔️	✔️
Einen Microsoft 365-Benutzer hinzufügen oder entfernen	✔️	✔️
Eine Telefonnummer hinzufügen oder entfernen	✔️	✔️
Einen Remoteteilnehmer stummschalten oder die Stummschaltung aufheben	✔️ [1]	✔️ [1]
Auflegen	✔️	✔️
Für alle das Gespräch beenden	✔️ [2]	✔️

[1] Die API wird nur in Gruppenaufrufen, Räumen und Teams-Besprechungen unterstützt. [2] Die API wird in Räumen nicht unterstützt.

SDKs

Die folgenden Tabellen zeigen die Unterstützung für die Funktionen in einzelnen Azure Communication Services SDKs.

Status der Unterstützung	das Internet	Web-Benutzeroberfläche	Ios	iOS-Benutzeroberfläche	Android	Android-Benutzeroberfläche	Fenster
Unterstützt	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Das SDK installieren

Verwenden Sie den Befehl npm install, um die Common und Calling SDKs von Azure Communication Services für JavaScript zu installieren:

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

Initialisieren erforderlicher Objekte

Für die meisten Anrufvorgänge ist eine CallClient-Instanz erforderlich. Wenn Sie eine neue CallClient-Instanz erstellen, können Sie diese mit benutzerdefinierten Optionen wie einer Logger-Instanz konfigurieren.

Mit der CallClient-Instanz können Sie eine CallAgent-Instanz erstellen, indem Sie createCallAgent aufrufen. Durch diese Methode wird ein CallAgent-Instanzobjekt asynchron zurückgegeben.

Die Methode createCallAgent verwendet CommunicationTokenCredential als Argument, welches ein Benutzerzugriffstoken akzeptiert.

Sie können die Methode getDeviceManager für die Instanz CallClient verwenden, um auf deviceManager zuzugreifen.

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()

Verwalten der SDK-Konnektivität mit der Microsoft-Infrastruktur

Die Call Agent-Instanz unterstützt Sie bei der Verwaltung von Anrufen (Annehmen oder Starten von Anrufen). Damit Ihr Calling SDK funktioniert, muss eine Verbindung mit der Microsoft-Infrastruktur hergestellt werden, um Benachrichtigungen über eingehende Anrufe zu erhalten und andere Anrufdetails zu koordinieren. Ihre Call Agent-Instanz kann zwei Status haben:

Connected (Verbunden) – Der connectionState-Wert Call Agent für Connected bedeutet, dass das Client-SDK verbunden ist und Benachrichtigungen von der Microsoft-Infrastruktur empfangen kann.

Disconnected (Getrennt) – Der connectionState-Wert Call Agent für Disconnected weist darauf hin, dass das SDK nicht ordnungsgemäß verbunden werden kann. Call Agent muss neu erstellt werden.

• invalidToken: Wenn ein Token abgelaufen oder ungültig ist, wird die Call Agent-Instanz mit diesem Fehler getrennt.
• connectionIssue: Wenn ein Problem mit der Verbindung zwischen dem Client und der Microsoft-Infrastruktur auftritt, gibt Call Agent nach mehreren Versuchen den connectionIssue-Fehler zurück.

Sie können überprüfen, ob Ihre lokale Call Agent-Instanz mit der Microsoft-Infrastruktur verbunden ist, indem Sie den aktuellen Wert der connectionState-Eigenschaft prüfen. Während eines aktiven Anrufs können Sie auf das connectionStateChanged-Ereignis lauschen, um zu bestimmen, ob sich der Call Agent-Status von Connected in Disconnected ändert.

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

Anruf tätigen

Um einen Anruf zu erstellen und zu starten, verwenden Sie eine der APIs für callAgent, und geben Sie ein Benutzerkonto an, das Sie über das Communication Services Identity SDK erstellt haben.

Erstellung und Start des Anrufs erfolgen synchron. Die call-Instanz ermöglicht Ihnen das Abonnieren von Anrufereignissen.

Tätigen eines 1:n-Anrufs an Benutzer*innen oder ein Telefonfestnetz

Um andere Communication Services-Benutzer*innen anzurufen, verwenden Sie die Methode startCall für callAgent, und übergeben Sie den CommunicationUserIdentifier, den Sie mit der Communication Services-Verwaltungsbibliothek erstellt haben.

Verwenden Sie für einen 1:1-Aufruf eines Benutzers den folgenden Code:

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

Um einen Anruf an ein PSTN (Public Switched Telephone Network) zu tätigen, verwenden Sie die Methode startCall für callAgent, und übergeben Sie den PhoneNumberIdentifier des Empfängers. Die Communication Services-Ressource muss so konfiguriert werden, dass Anrufe über das Telefonfestnetz möglich sind.

Wenn Sie eine Telefonfestnetznummer anrufen, geben Sie Ihre alternative Anrufer-ID an. Eine alternative Anrufer-ID bezieht sich auf eine Telefonnummer (basierend auf dem E.164-Standard), die den Anrufer in einem PSTN-Anruf identifiziert. Dies ist die Telefonnummer, die dem Anrufempfänger bei einem eingehenden Anruf angezeigt wird.

Hinweis

Details zum PstN-Anrufangebot anzeigen. Um Zugriff auf das Vorschauprogramm zu erhalten, bewerben Sie sich für das Early Adopter-Programm.

Verwenden Sie für einen 1:1-Anruf einer PSTN-Nummer den folgenden Code:

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

Verwenden Sie für einen 1:n-Anruf an einen Benutzer und eine PSTN-Nummer den folgenden Code:

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

Teilnehmen an einem Raumanruf

Um einem room-Anruf beizutreten, können Sie ein Kontextobjekt mit der roomId-Eigenschaft als room-Bezeichner instanziieren. Wenn Sie an dem Anruf teilnehmen möchten, verwenden Sie die join-Methode und übergeben die Kontextinstanz.

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

Ein room bietet Anwendungsentwicklern bessere Kontrolle darüber, wer an einem Anruf teilnehmen kann, wann die Teilnehmer sich „treffen“ und wie sie zusammenarbeiten. Weitere Informationen zu Räumen finden Sie unter Räume-API für strukturierte Besprechungen und einem Raumanruf beitreten.

An einem Gruppenanruf teilnehmen

Hinweis

Der groupId Parameter ist Systemmetadaten, die von Microsoft für Vorgänge verwendet werden, die zum Ausführen des Systems erforderlich sind. Fügen Sie keine personenbezogenen Daten in den groupId-Wert ein. Microsoft behandelt diesen Parameter nicht wie personenbezogene Daten. Seine Inhalte sind möglicherweise für Microsoft-Mitarbeiter sichtbar oder werden langfristig gespeichert.

Der groupId-Parameter erfordert, dass Daten im GUID-Format vorliegen. Es wird empfohlen, zufällig generierte GUIDs zu verwenden, die in Ihren Systemen nicht als personenbezogene Daten betrachtet werden.

Um einen neuen Gruppenanruf zu starten oder an einem aktuellen Gruppenanruf teilzunehmen, müssen Sie die Methode join aufrufen und ein Objekt mit einer groupId-Eigenschaft übergeben. Der groupId-Wert muss eine GUID (ein eindeutiger Bezeichner) sein.

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

Eingehenden Anruf entgegennehmen

Die callAgent-Instanz gibt das Ereignis incomingCall aus, wenn die angemeldete Identität einen eingehenden Anruf empfängt. Um auf dieses Ereignis zu lauschen, abonnieren Sie es mithilfe einer der folgenden Optionen:

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

Das incomingCall-Ereignis umfasst eine incomingCall-Instanz, die Sie akzeptieren oder ablehnen können.

Das Azure Communication Calling SDK löst eine cameraStartFailed: true Anrufdiagnose aus, wenn die Kamera beim Starten, Annehmen oder Beitreten zu einem Anruf mit aktiviertem Video nicht verfügbar ist. In diesem Fall beginnt der Anruf mit deaktiviertem Video. Die Kamera ist möglicherweise nicht verfügbar, da sie von einem anderen Prozess verwendet wird oder im Betriebssystem deaktiviert ist.

Halten und Fortsetzen eines Anrufs

Hinweis

Zu einem bestimmten Zeitpunkt darf nur ein (1) aktiver Anruf im Connected Zustand mit aktiven Medien vorhanden sein. Alle anderen Anrufe müssen von einer benutzenden Person oder programmgesteuert von der Anwendung in die Warteschleife gesetzt werden. Dieses Szenario ist in Szenarien wie Kontaktcentern üblich, in denen ein Benutzer möglicherweise mehrere ausgehende und eingehende Anrufe verarbeiten muss. In diesem Fall sollten alle inaktiven Anrufe gehalten werden, und der Benutzer sollte nur im aktiven Anruf mit anderen interagieren.

Verwenden Sie zum Halten oder Fortsetzen des Anrufs die asynchronen holdresume APIs:

So halten Sie den Anruf:

await call.hold();

Wenn der Vorgang hold abgeschlossen ist, wird der Anrufstatus auf LocalHold eingestellt. In einem 1:1-Anruf wird der andere Teilnehmer ebenfalls in die Warteschleife gesetzt, und der Status des Anrufs aus der Perspektive dieses Teilnehmers wird auf RemoteHoldfestgelegt. Später hält der andere Teilnehmer ggf. seinen Anruf, wodurch sich der Zustand in LocalHold ändert.

In Gruppenanrufen oder Besprechungen ist hold ein lokaler Vorgang und führt nicht dazu, dass der Anruf für andere Anrufteilnehmer gehalten wird.

Um den Anruf fortzusetzen, muss er von allen Benutzenden, die das Halten des Anrufs initiiert haben, wieder aufgenommen werden.

So setzen Sie den Anruf aus der Warteschleife fort:

await call.resume();

Wenn der resume Vorgang aufgelöst wird, stellt sich der Aufrufstatus erneut auf Connected.

Stummschalten und Entsperren eines Anrufs

Verwenden Sie zum Stummschalten oder Aufheben der Stummschaltung des lokalen Endpunkts die asynchronen mute und unmute APIs:

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

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

Stummschalten und Aufheben der Stummschaltung eingehender Audiodaten

Das Stummschalten eingehender Audio legt die Anruflautstärke auf 0 fest. Um den eingehenden Ton stumm zu schalten oder die Stummschaltung aufzuheben, verwenden Sie die asynchronen Vorgänge muteIncomingAudio und unmuteIncomingAudio:

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

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

Wenn das eingehende Audio stummgeschaltet wird, empfängt das Client-SDK des Teilnehmers weiterhin das Anrufaudio (Audio des Remoteteilnehmers). Das Anrufaudio ist nicht zu hören im Lautsprecher, und der Teilnehmer kann nicht zuhören, bis call.unmuteIncomingAudio() angerufen wird. Wir können jedoch einen Filter auf Anrufaudio anwenden und die gefilterten Audiodaten wiedergeben.

Verwalten von Remoteteilnehmern

Alle Remoteteilnehmer sind im RemoteParticipant Objekt enthalten und über die remoteParticipants Auflistung in einer Anrufinstanz verfügbar. Auf das remoteParticipants Objekt kann über eine Call Instanz zugegriffen werden.

Auflisten der Teilnehmer*innen an einem Anruf

Die remoteParticipants-Sammlung gibt eine Liste der Remoteteilnehmer eines Anrufs zurück:

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

Hinzufügen eines Teilnehmers zu einem Anruf

Um einen Teilnehmer (entweder ein Benutzer oder eine Telefonnummer) zu einem Anruf hinzuzufügen, verwenden Sie den addParticipant Vorgang. Geben Sie einen der Identifier-Typen an. Dadurch wird die Instanz remoteParticipant synchron zurückgegeben. Das Ereignis remoteParticipantsUpdated des Anrufs wird ausgelöst, wenn eine teilnehmende Person erfolgreich dem Aufruf hinzugefügt wurde.

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

Entfernen eines Teilnehmers aus einem Anruf

Um einen Teilnehmer (ein Benutzer oder eine Telefonnummer) aus einem Anruf zu entfernen, können Sie anrufen removeParticipant. Sie müssen einen der Identifier-Typen übergeben. Diese Methode wird asynchron aufgelöst, nachdem der Teilnehmer aus dem Aufruf entfernt wurde. Der Teilnehmer wird auch aus der remoteParticipants-Sammlung entfernt.

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

Zugreifen auf Eigenschaften von Remoteteilnehmern

Remoteteilnehmern ist ein Satz von Eigenschaften und Sammlungen zugeordnet:

• CommunicationIdentifier: Ruft den Bezeichner eines Remoteteilnehmers ab. „Identity“ ist einer der CommunicationIdentifier-Typen:

  const identifier = remoteParticipant.identifier;
  

• Es kann sich um eine der folgenden CommunicationIdentifier-Typen handeln:

  • { communicationUserId: '<ACS_USER_ID'> }: Objekt, das den Azure Communication Services-Benutzer darstellt.
  • { phoneNumber: '<E.164>' }: Objekt, das die Telefonnummer im E.164-Format darstellt.
  • { microsoftTeamsUserId: '<TEAMS_USER_ID>', isAnonymous?: boolean; cloud?: "public" | "dod" | "gcch" }: Objekt, das den Teams-Benutzer darstellt.
  • { id: string }: Objekt, das den Bezeichner darstellt, der keinem der anderen Bezeichnertypen entspricht.

• state: Ermittelt den Zustand eines Remote-Teilnehmers.

  const state = remoteParticipant.state;
  

• Der Zustand kann sein:

  • Idle: Anfangszustand.
  • Connecting: Übergangszustand, während sich der Teilnehmer mit dem Anruf verbindet.
  • Ringing: Für den Teilnehmeranruf ertönt ein Klingeln.
  • Connected: Der Teilnehmer ist mit dem Anruf verbunden.
  • Hold: Teilnehmer*in wird gehalten.
  • EarlyMedia: Ansage, die vor dem Verbinden eines Teilnehmers mit dem Anruf wiedergegeben wird.
  • InLobby: Gibt an, dass sich der Remoteteilnehmer im Wartebereich befindet.
  • Disconnected: Endzustand. Teilnehmer*in wird vom Anruf getrennt. Wenn der Remoteteilnehmer seine Netzwerkkonnektivität verliert, ändert sich der Zustand nach zwei Minuten in Disconnected.

• callEndReason: Um zu erfahren, warum ein Teilnehmer den Anruf verlassen hat, prüfen Sie die Eigenschaft callEndReason:

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

  Hinweis

  Diese Eigenschaft wird nur festgelegt, wenn ein Remoteteilnehmer über die Call.addParticipant()-API hinzugefügt wird und der Remoteteilnehmer beispielsweise ablehnt.

  Wenn beispielsweise UserC durch UserB entfernt wird, sieht UserA nicht, dass dieses Flag für UserC festgelegt wird. UserA bekommt also vom Festlegen der callEndReason-Eigenschaft von UserC überhaupt nichts mit.

• isMuted-Status: Um herauszufinden, ob ein Remoteteilnehmer stummgeschaltet wurde, überprüfen Sie die Eigenschaft isMuted. Er gibt Boolean zurück.

  const isMuted = remoteParticipant.isMuted;
  

• isSpeaking-Status: Um herauszufinden, ob ein Remoteteilnehmer gerade spricht, überprüfen Sie die Eigenschaft isSpeaking. Er gibt Boolean zurück.

  const isSpeaking = remoteParticipant.isSpeaking;
  

• videoStreams: Um alle Videostreams zu prüfen, die ein bestimmter Teilnehmer im Rahmen dieses Anrufs sendet, sehen Sie sich die videoStreams-Sammlung an. Sie enthält RemoteVideoStream-Objekte.

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

• displayName: Um den Anzeigenamen für diesen Remoteteilnehmer zu erhalten, überprüfen Sie die zurückgegebene Zeichenfolge der Eigenschaft displayName.

  const displayName = remoteParticipant.displayName;
  

• endpointDetails: Details aller Endpunkte für diesen Remoteteilnehmer abrufen

  const endpointDetails: EndpointDetails[] = remoteParticipant.endpointDetails;
  

  Hinweis

  Ein Remote-Teilnehmer kann von vielen verschiedenen Endpunkten aus an einem Anruf teilnehmen, und jeder Endpunkt hat seinen eigenen einzigartigen participantId. participantId unterscheidet sich von der unformatierten ID des RemoteParticipant Bezeichners.

Andere Teilnehmer stummschalten

Hinweis

Um andere VoIP-Teilnehmer stummzuschalten, müssen Sie azure Communication Services Calling Web SDK Version 1.26.1 GA-Version oder höher verwenden. Zum Stummschalten von PSTN-Endpunkten müssen Sie GA 1.33.1 des WebJS (oder höher) verwenden.

Hinweis

Das Stummschalten anderer Personen bei einem 1:1-Anruf wird nicht unterstützt.

Um alle anderen Teilnehmer oder einen bestimmten Teilnehmer stummzuschalten, die mit einem Anruf verbunden sind, können Sie die asynchronen APIs muteAllRemoteParticipants für den Anruf und mute für den Remote-Teilnehmer verwenden. Das mutedByOthers-Ereignis im Anruf wird ausgelöst, wenn die lokale teilnehmende Person von anderen Teilnehmenden stummgeschaltet wird.

Das Stummschalten eines PSTN-Endpunkts mit dem Calling-WebJS-SDK ist aktuell allgemein verfügbar und steht in Build 1.34.1 1.34.1 und höheren Versionen zur Verfügung.

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

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

Überprüfung der Anruf-Eigenschaften

Abrufen der eindeutigen ID (Zeichenfolge) für einen Anruf:

const callId: string = call.id;

Rufen Sie die lokale Teilnehmer-ID ab:

const participantId: string = call.info.participantId;

Hinweis

Eine Azure Communication Services-Identität kann das Web Calling SDK an vielen Endpunkten verwenden, und jeder Endpunkt verfügt über eine eigene eindeutige Teilnehmer-ID (participantId). participantId unterscheidet sich von der unformatierten ID der Azure Communication Services-Identität.

Rufen Sie die Thread-ID ab, wenn Sie an einer Teams-Besprechung teilnehmen:

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

Abrufen von Informationen zum Anruf:

const callInfo = call.info;

Erfahren Sie mehr über andere Teilnehmer des Anrufs, indem Sie die remoteParticipants Sammlung für die call Instanz prüfen:

const remoteParticipants = call.remoteParticipants;

Identifizieren des Anrufers eines eingehenden Anrufs:

const callerIdentity = call.callerInfo.identifier;

identifier ist einer der CommunicationIdentifier-Typen.

Abrufen des Anrufzustands:

const callState = call.state;

Gibt eine Zeichenfolge zurück, die den aktuellen Zustand eines Anrufs darstellt:

• None: anfänglicher Anrufzustand.
• Connecting: anfänglicher Übergangszustand, wenn ein Anruf getätigt oder angenommen wird.
• Ringing: Weist bei einem ausgehenden Anruf darauf hin, dass ein Anruf für Remoteteilnehmer klingelt. Auf deren Seite lautet der Status Incoming.
• EarlyMedia: Gibt einen Zustand an, in dem vor dem Verbinden des Anrufs eine Ansage wiedergegeben wird.
• Connected: Gibt an, dass der Anruf verbunden wurde.
• LocalHold: Gibt an, dass der Anruf von einem lokalen Teilnehmer gehalten wird. Zwischen dem lokalen Endpunkt und den Remoteteilnehmern werden keine Medien übertragen.
• RemoteHold: Gibt an, dass der Anruf von einem Remoteteilnehmer gehalten wird. Zwischen dem lokalen Endpunkt und den Remoteteilnehmern werden keine Medien übertragen.
• InLobby: Gibt an, dass sich der Benutzer im Wartebereich befindet.
• Disconnecting: Übergangszustand, bevor der Anruf in einen Disconnected-Zustand wechselt.
• Disconnected: Abschließender Anrufzustand. Wenn die Netzwerkverbindung unterbrochen wird, ändert sich der Zustand nach zwei Minuten in Disconnected.

Ermitteln Sie, warum der Anruf beendet wurde, indem Sie die Eigenschaft callEndReason überprüfen:

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

Erfahren Sie, ob der aktuelle Anruf ein- oder ausgeht, indem Sie die Eigenschaft direction überprüfen. Er gibt CallDirection zurück.

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

Überprüfen Sie die aktiven Videodatenströme und Bildschirmfreigabe-Datenströme, indem Sie die localVideoStreams-Sammlung überprüfen. Der localVideoStreams Vorgang gibt LocalVideoStream Objekte vom Typ Video, ScreenSharing, oder RawMedia.

const localVideoStreams = call.localVideoStreams;

Stellen Sie fest, ob das aktuelle Mikrofon stummgeschaltet ist. Er gibt Boolean zurück.

const muted = call.isMuted;

Überprüfen Sie, ob das aktuelle eingehende Audio (Lautsprecher) stummgeschaltet ist. Er gibt Boolean zurück.

const incomingAudioMuted = call.isIncomingAudioMuted;

Überprüfen Sie, ob das Video aktiviert ist. Er gibt Boolean zurück.

const isLocalVideoStarted = call.isLocalVideoStarted;

Überprüfen Sie, ob die Bildschirmfreigabe aktiviert ist. Er gibt Boolean zurück.

const isScreenSharingOn = call.isScreenSharingOn;

Auflegen

Es gibt zwei Möglichkeiten, den Anruf zu beenden.

• Der erste Anrufer kann den Anruf verlassen, und die anderen Teilnehmer bleiben im Anruf.
• Wenn der ursprüngliche Anrufer den Anruf verlässt, wird er für alle Teilnehmer beendet.

Um den Anruf zu verlassen, verwenden Sie Folgendes:

call.hangUp();

Beenden Sie den Anruf für alle Teilnehmer, indem Sie angeben HangUpOptions.

Hinweis

Dieser Vorgang ist in Räumen nicht verfügbar.

call.hangUp( forEveryone: true);

Das SDK installieren

Wählen Sie Ihre Datei build.gradle auf Projektebene aus, und fügen Sie mavenCentral() der Liste der Repositorys unter buildscript und allprojects hinzu:

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

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

Fügen Sie anschließend in der Datei build.gradle auf Modulebene die folgenden Zeilen im Abschnitt dependencies hinzu:

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

Initialisieren der erforderlichen Objekte

Zum Erstellen einer CallAgent-Instanz müssen Sie die createCallAgent-Methode für eine CallClient-Instanz aufrufen. Dieser Aufruf gibt asynchron ein CallAgent-Instanzobjekt zurück.

Die createCallAgent-Methode verwendet CommunicationUserCredential als Argument, womit ein Zugriffstoken gekapselt wird.

Um auf DeviceManager zuzugreifen, müssen Sie zuerst eine callAgent-Instanz erstellen. Anschließend können Sie die CallClient.getDeviceManager-Methode zum Abrufen von DeviceManager verwenden.

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

Zum Festlegen eines Anzeigenamens für den Anrufer verwenden Sie diese alternative Methode:

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

Anruf tätigen

Um einen Anruf zu erstellen und zu starten, müssen Sie die CallAgent.startCall()-Methode aufrufen und Identifier der angerufenen Person angeben.

Um einem Gruppenanruf beizutreten, müssen Sie die CallAgent.join()-Methode aufrufen und die groupId übergeben. Gruppen-IDs müssen im GUID- oder UUID-Format vorliegen.

Erstellung und Start des Anrufs erfolgen synchron. Mit der Anrufinstanz können Sie alle Anrufereignisse abonnieren.

Einen 1:1-Anruf an einen Benutzer tätigen

Um einen Anruf eines anderen Communication Services-Benutzers zu tätigen, rufen Sie die call-Methode für callAgent auf und übergeben ein Objekt mit communicationUserId-Schlüssel.

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

1:n-Anruf mit Benutzenden und Festnetznummern

Hinweis

Details zum PstN-Anrufangebot anzeigen. Um Zugriff auf das Vorschauprogramm zu erhalten, bewerben Sie sich für das Early Adopter-Programm.

Um einen 1:n-Anruf an einen Benutzer und eine PSTN-Nummer (Public Switched Telephone Network) zu tätigen, müssen Sie die Telefonnummer des Empfängers oder der Empfänger angeben.

Ihre Kommunikationsdiensteressource muss so konfiguriert sein, dass PSTN-Anrufe aktiviert werden:

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

Einen Anruf annehmen

Rufen Sie zum Annehmen eines Aufrufs die accept Methode für ein Aufrufobjekt auf.

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

Annehmen eines Anrufs mit eingeschalteter Videokamera:

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

Rufen Sie den eingehenden Anruf ab, indem Sie das onIncomingCall-Ereignis auf dem callAgent-Objekt abonnieren.

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

Teilnehmen an einem Raumanruf

Verwenden Sie CallAgent und RoomCallLocator, um an einem Raumanruf teilzunehmen, indem Sie ein roomId angeben. Die CallAgent.join Methode gibt ein Call Objekt zurück:

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

Ein room bietet Anwendungsentwicklern bessere Kontrolle darüber, wer an einem Anruf teilnehmen kann, wann die Teilnehmer sich „treffen“ und wie sie zusammenarbeiten. Weitere Informationen zu Räumen finden Sie unter Räume-API für strukturierte Besprechungen und einem Raumanruf beitreten.

An einem Gruppenanruf teilnehmen

Um einen neuen Gruppenaufruf zu starten oder einem laufenden Gruppenaufruf beizutreten, müssen Sie die join Methode aufrufen und ein Objekt mit einer groupId Eigenschaft übergeben. Der Wert muss eine GUID sein.

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

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

Anrufeigenschaften

Ruft die eindeutige ID für diesen Anruf ab:

String callId = call.getId();

Um mehr über andere Anrufteilnehmer zu erfahren, sehen Sie sich die remoteParticipant-Sammlung für die call-Instanz an:

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

Die Identität des Anrufers bei einem eingehenden Anruf:

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

Ruft den Zustand des Anrufs ab:

CallState callState = call.getState();

Gibt eine Zeichenfolge zurück, die den aktuellen Zustand eines Anrufs darstellt:

• NONE - Anfänglicher Anrufstatus
• EARLY_MEDIA – gibt einen Zustand an, in dem eine Ankündigung wiedergegeben wird, bevor der Anruf verbunden ist.
• CONNECTING – Anfänglicher Übergangszustand, nachdem der Anruf getätigt oder angenommen wurde
• RINGING – für einen ausgehenden Anruf – gibt an, dass der Anruf für Remoteteilnehmer klingelt.
• CONNECTED – Anruf verbunden
• LOCAL_HOLD: Ein von einer lokalen teilnehmenden Person in die Warteschleife gesetzter Anruf ohne Medien, die zwischen dem lokalen Endpunkt und Remoteteilnehmenden übertragen werden
• REMOTE_HOLD – Ein von einem Remoteteilnehmer gehalten Anruf, bei dem kein Medienfluss zwischen dem lokalen Endpunkt und den Remoteteilnehmern stattfindet.
• DISCONNECTING – Übergangszustand, bevor der Anruf in den Disconnected Zustand wechselt
• DISCONNECTED - Endgültiger Anrufstatus
• IN_LOBBY: Im Wartebereich für eine Teams-Besprechungsinteroperabilität

Um zu erfahren, warum ein Anruf beendet wurde, überprüfen Sie die callEndReason-Eigenschaft. Sie enthält Code/Subcode:

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

Um festzustellen, ob der aktuelle Anruf ein- oder ausgehend ist, untersuchen Sie die callDirection-Eigenschaft:

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

Um festzustellen, ob das aktuelle Mikrofon stummgeschaltet ist, prüfen Sie die muted-Eigenschaft:

boolean muted = call.isMuted();

Um aktive Videostreams zu prüfen, sehen Sie sich die localVideoStreams-Sammlung an:

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

Stummschalten und Aufheben der Stummschaltung

Zum Stummschalten oder Aufheben der Stummschaltung des lokalen Endpunkts können Sie die asynchronen APIs mute und unmute verwenden:

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

Ändern der Lautstärke des Anrufs

Während sich teilnehmer in einem Anruf befinden, sollten die Hardwarelautstärketasten auf dem Telefon dem Benutzer ermöglichen, die Anruflautstärke zu ändern.

Verwenden Sie die Methode setVolumeControlStream mit dem Datenstromtyp AudioManager.STREAM_VOICE_CALL für die Aktivität, in der der Aufruf stattfindet.

Diese Methode ermöglicht es den Hardwarelautstärketasten, die Lautstärke des Anrufs zu ändern, die durch ein Telefonsymbol oder etwas ähnliches auf dem Lautstärkeregler angegeben wird. Außerdem werden Änderungen an der Lautstärke durch andere Soundprofile wie Alarme, Medien oder systemweite Lautstärke verhindert. Weitere Informationen finden Sie unter Behandeln von Änderungen in der Audioausgabe | Android-Entwickler.

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

Verwaltung von Remoteteilnehmern

Alle Remoteteilnehmer haben den RemoteParticipant Typ und sind über die remoteParticipants Sammlung für eine Anrufinstanz verfügbar.

Teilnehmer eines Anrufs auflisten

Die remoteParticipants-Sammlung gibt eine Liste der Remoteteilnehmer an einem angegebenen Anruf zurück:

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

Hinzufügen eines Teilnehmers zu einem Anruf

Um einen Teilnehmer zu einem Anruf hinzuzufügen (entweder ein Benutzer oder eine Telefonnummer), können Sie den addParticipant Vorgang anrufen.

Dieser Vorgang gibt die Remoteteilnehmerinstanz synchron zurück.

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

Entfernen eines Teilnehmers aus einem Anruf

Um einen Teilnehmer aus einem Anruf (einem Benutzer oder einer Telefonnummer) zu entfernen, können Sie den removeParticipant-Vorgang aufrufen.

Dieser Vorgang wird asynchron aufgelöst, sobald der Teilnehmer aus dem Anruf entfernt wird.

Der Teilnehmer wird auch aus der remoteParticipants Sammlung entfernt.

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

Eigenschaften von Remoteteilnehmern

Ein entfernter Teilnehmer verfügt über eine Reihe zugeordneter Eigenschaften und Sammlungen.

• Ruft den Bezeichner des Teilnehmers aus der Ferne ab.

„Identity“ ist einer der Identifier-Typen:

CommunicationIdentifier participantIdentifier = remoteParticipant.getIdentifier();

• Rufen Sie den Status dieses Remoteteilnehmers ab.

  ParticipantState state = remoteParticipant.getState();
  

Folgende Werte sind hierfür möglich:

• IDLE - Anfangszustand

• EARLY_MEDIA – Ankündigung wird wiedergegeben, bevor der Teilnehmer mit dem Anruf verbunden ist

• RINGING - Teilnehmeranruf klingelt

• CONNECTING – Übergangszustand, während der Teilnehmer eine Verbindung mit dem Anruf herstellt

• CONNECTED – Teilnehmer ist mit dem Anruf verbunden

• HOLD - Teilnehmer ist in der Warteschleife

• IN_LOBBY - Der Teilnehmer wartet auf die Zulassung im Wartebereich. Wird derzeit nur in Teams-Interoperabilitätsszenarien verwendet.

• DISCONNECTED - Endgültiger Zustand – Teilnehmer wird vom Anruf getrennt

• Um zu erfahren, warum ein Teilnehmer den Anruf verlassen hat, prüfen Sie die callEndReason-Eigenschaft:

  CallEndReason callEndReason = remoteParticipant.getCallEndReason();
  

• Um zu prüfen, ob dieser Remoteteilnehmer stummgeschaltet ist oder nicht, prüfen Sie die isMuted-Eigenschaft:

  boolean isParticipantMuted = remoteParticipant.isMuted();
  

• Um zu prüfen, ob dieser Remoteteilnehmer spricht oder nicht, prüfen Sie die isSpeaking-Eigenschaft:

  boolean isParticipantSpeaking = remoteParticipant.isSpeaking();
  

• Um alle Videostreams zu prüfen, die ein bestimmter Teilnehmer im Rahmen dieses Anrufs sendet, sehen Sie sich die videoStreams-Sammlung an:

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

Andere Teilnehmer stummschalten

Hinweis

Verwenden Sie das Azure Communication Services Calling Android SDK, Version 2.11.0 oder höher.

Wenn ein PSTN-Teilnehmer stummgeschaltet ist, erhält er eine Ankündigung, dass er stummgeschaltet ist und dass er eine Tastenkombination (z. B. *6) drücken kann, um die Stummschaltung selbst aufzuheben. Wenn sie *6 drücken, werden sie stummgeschaltet.

Verwenden Sie den muteAllRemoteParticipants API-Vorgang, um alle anderen Teilnehmer in einem Aufruf stummzuschalten.

call.muteAllRemoteParticipants();

Verwenden Sie zum Stummschalten eines bestimmten Remoteteilnehmers den mute API-Vorgang für einen bestimmten Remoteteilnehmer.

remoteParticipant.mute();

Um den lokalen Teilnehmer darüber zu informieren, dass er von anderen stummgeschaltet wird, abonnieren Sie das onMutedByOthers Ereignis.

Verwenden von Vordergrunddiensten

Wenn Sie eine vom Benutzer sichtbare Aufgabe auch dann ausführen möchten, wenn sich Ihre Anwendung im Hintergrund befindet, können Sie Vordergrunddienste verwenden.

Verwenden Sie Vordergrunddienste, um Benutzern beispielsweise eine sichtbare Benachrichtigung bereitzustellen, wenn Ihre Anwendung über einen aktiven Aufruf verfügt. Auf diese Weise ist der Aufruf auch dann aktiv, wenn der Benutzer zum Startbildschirm wechselt oder die Anwendung aus dem Bildschirm "Zuletzt verwendet" entfernt.

Wenn Sie während eines Anrufs keinen Vordergrunddienst verwenden, kann die Navigation zum Startbildschirm den Anruf aktiv halten. Wenn Sie die Anwendung jedoch aus dem Bildschirm „Zuletzt verwendet“ entfernen, kann der Anruf beendet werden, wenn das Android-Betriebssystem den Prozess Ihrer Anwendung beendet.

Sie sollten den Vordergrunddienst starten, wenn ein Benutzer einen Anruf startet oder beitritt, z. B.:

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

Sie sollten den Vordergrunddienst außerdem beenden, wenn Sie auflegen oder der Status des Anrufs „Getrennt“ lautet, z. B.:

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

Details zum Vordergrunddienst

Beachten Sie, dass Szenarien wie das Beenden eines bereits ausgeführten Vordergrunddiensts die für Benutzende sichtbare Benachrichtigung entfernen, wenn die App aus der Liste der zuletzt verwendeten Apps entfernt wird. In diesem Fall kann das Android-Betriebssystem Ihren Anwendungsprozess für einen längeren Zeitraum aktiv halten, was bedeutet, dass der Aufruf während dieses Zeitraums aktiv bleiben kann.

Wenn Ihre Anwendung beispielsweise den Vordergrunddienst in der Dienstmethode onTaskRemoved beendet, kann sie Audio und Video entsprechend Ihrem Aktivitätslebenszyklus starten oder beenden. Etwa das Beenden von Audio und Video, wenn Ihre Aktivität durch das Überschreiben der onDestroy-Methode zerstört wird.

Einrichten des Systems

Führen Sie die unten angegebenen Schritte aus, um Ihr System einzurichten.

Erstellen des Xcode-Projekts

Erstellen Sie in Xcode ein neues iOS-Projekt, und wählen Sie die Vorlage Single View App (Einzelansicht-App) aus. In diesem Artikel wird das SwiftUI-Framework verwendet. Legen Sie daher Sprache auf Swift und Schnittstelle auf SwiftUI fest.

Sie werden in diesem Artikel keine Tests erstellen. Sie können das Kontrollkästchen Tests einschließen deaktivieren.

Installieren des Pakets und der Abhängigkeiten mithilfe von CocoaPods

1. Erstellen Sie eine Podfile-Datei für die Anwendung, wie in diesem Beispiel:

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

2. Führen Sie pod install aus.

3. Öffnen Sie .xcworkspace mithilfe von Xcode.

Anfordern des Zugriffs auf das Mikrofon

Um auf das Mikrofon des Geräts zuzugreifen, müssen Sie die Liste der Informationseigenschaften Ihrer App mithilfe von NSMicrophoneUsageDescription aktualisieren. Legen Sie den zugehörigen Wert auf eine Zeichenfolge fest. Diese wird in den Dialog aufgenommen, mit dem das System den Zugriff beim Benutzer anfordert.

Klicken Sie mit der rechten Maustaste auf den Eintrag info.plist in der Projektstruktur, und wählen Sie dann Öffnen als>Quellcode aus. Fügen Sie im Abschnitt <dict> der obersten Ebene die folgenden Zeilen hinzu, und speichern Sie dann die Datei.

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

Einrichten des App-Frameworks

Öffnen Sie die Datei ContentView.swift Ihres Projekts. Fügen Sie am Anfang der Datei eine import-Deklaration hinzu, um die AzureCommunicationCalling-Bibliothek zu importieren. Importieren Sie außerdem AVFoundation. Sie ist für Audioberechtigungsanforderungen im Code erforderlich.

import AzureCommunicationCalling
import AVFoundation

Initialisieren von „CallAgent“

Um eine CallAgent-Instanz auf der Grundlage von CallClient zu erstellen, müssen Sie eine Methode vom Typ callClient.createCallAgent verwenden, die asynchron ein Objekt vom Typ CallAgent zurückgibt, nachdem es initialisiert wurde.

Übergeben Sie für die Erstellung eines Anrufclients ein Objekt vom Typ CommunicationTokenCredential:

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

Übergeben Sie das von Ihnen erstellte Objekt vom Typ CommunicationTokenCredential an CallClient, und legen Sie den Anzeigenamen fest:

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

Hinweis

Wenn die Anwendung Ereignisdelegaten implementiert, muss sie einen starken Verweis auf die Objekte aufrechterhalten, die Ereignisabonnements benötigen. Wenn Sie beispielsweise die call.addParticipant Methode aufrufen und ein RemoteParticipant Objekt zurückgeben. Anschließend legt die Anwendung den Delegaten so fest, dass er auf RemoteParticipantDelegate lauscht, und die Anwendung muss einen starken Verweis auf das RemoteParticipant-Objekt haben. Andernfalls löst der Delegat, wenn dieses Objekt erfasst wird, eine schwerwiegende Ausnahme aus, wenn das Calling SDK versucht, das Objekt aufzurufen.

Einen ausgehenden Anruf tätigen

Um einen Anruf zu erstellen und zu starten, müssen Sie eine der APIs für CallAgent aufrufen und die Communication Services-Identität eines Benutzers angeben, den Sie unter Verwendung des Verwaltungs-SDK von Communication Services bereitgestellt haben.

Erstellung und Start des Anrufs erfolgen synchron. Sie erhalten eine Anrufinstanz, die es Ihnen ermöglicht, alle Ereignisse im Zusammenhang mit dem Anruf zu abonnieren.

Tätigen eines 1:1-Anrufs eines Benutzers oder eines 1:n-Anrufs mit Benutzer*innen und Festnetznummern

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

1:n-Anruf mit Benutzenden und Festnetznummern

Hinweis

Details zum PstN-Anrufangebot anzeigen. Um Zugriff auf das Vorschauprogramm zu erhalten, bewerben Sie sich für das Early Adopter-Programm.

Um einen 1:n-Anruf an einen Benutzer und ein öffentliches Telefonnetz (PSTN) zu tätigen, müssen Sie eine Telefonnummer angeben, die mit Kommunikationsdiensten erworben wurde.

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

Teilnehmen an einem Raumanruf

Um einem room-Anruf beizutreten, geben Sie die roomId-Eigenschaft als room-Bezeichner an. Um an dem Anruf teilzunehmen, verwenden Sie die join-Methode, und übergeben Sie den 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)
    }
}

Ein room bietet Anwendungsentwicklern bessere Kontrolle darüber, wer an einem Anruf teilnehmen kann, wann die Teilnehmer sich „treffen“ und wie sie zusammenarbeiten. Weitere Informationen zu Räumen finden Sie unter Räume-API für strukturierte Besprechungen und einem Raumanruf beitreten.

An einem Gruppenanruf teilnehmen

Um an einem Anruf teilzunehmen, müssen Sie eine der APIs für CallAgent aufrufen.

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

Abonnieren eines eingehenden Anrufs

Abonnieren Sie ein Ereignis für einen eingehenden Anruf.

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

Annehmen eines eingehenden Anrufs

Rufen Sie zum Annehmen eines Anrufs die Methode accept für ein IncomingCall-Objekt auf.

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

Ausführen von Vorgängen während eines Anrufs

Sie können Vorgänge während eines Anrufs ausführen, um Einstellungen im Zusammenhang mit Video und Audio zu verwalten.

Stummschalten und Aufheben der Stummschaltung

Zum Stummschalten oder Aufheben der Stummschaltung des lokalen Endpunkts können Sie die asynchronen APIs mute und unmute verwenden.

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

Verwenden Sie den folgenden Code, um die Stummschaltung des lokalen Endpunkts asynchron aufzuheben:

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

Verwalten von Remoteteilnehmern

Der RemoteParticipant Typ stellt alle Remoteteilnehmer dar. Sie sind über die Sammlung remoteParticipants in einer Anrufinstanz verfügbar.

Teilnehmer eines Anrufs auflisten

call.remoteParticipants

Hinzufügen eines Teilnehmers zu einem Anruf

Wenn Sie einen Teilnehmer zu einem Anruf als Benutzer oder als Telefonnummer hinzufügen möchten, rufen Sie den addParticipant Vorgang an. Dieser Vorgang gibt synchron eine Remoteteilnehmerinstanz zurück.

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

Entfernen eines Teilnehmers aus einem Anruf

Um einen Teilnehmer aus einem Anruf als Benutzer oder als Telefonnummer zu entfernen, rufen Sie den removeParticipant Vorgang an. Dieser Vorgang löst sich asynchron aus.

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

Abrufen von Eigenschaften von Remoteteilnehmern

// [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, ...]

Andere Teilnehmer stummschalten

Hinweis

Verwenden Sie die Azure Communication Services Calling iOS SDK Version 2.13.0 oder höher.

Wenn ein PSTN-Teilnehmer stummgeschaltet ist, erhält er eine Ankündigung, dass er stummgeschaltet ist und dass er eine Tastenkombination (z. B. *6) drücken kann, um die Stummschaltung selbst aufzuheben. Wenn sie *6 drücken, wird die Stummschaltung aufgehoben.

Um alle anderen Teilnehmer in einem Anruf stummzuschalten, verwenden Sie den muteAllRemoteParticipants Vorgang für den Anruf.

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

Um einen bestimmten Remoteteilnehmer stummzuschalten, verwenden Sie den mute Vorgang für einen bestimmten Remoteteilnehmer.

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

Um den lokalen Teilnehmer darüber zu informieren, dass er von anderen stummgeschaltet wird, abonnieren Sie das onMutedByOthers Ereignis.

Einrichten des Systems

Führen Sie die unten angegebenen Schritte aus, um Ihr System einzurichten.

Erstellen des Visual Studio-Projekts

Erstellen Sie für eine UWP-App (Universelle Windows-Plattform) in Visual Studio 2022 ein neues Projekt vom Typ Leere App (universelles Windows). Nachdem Sie den Projektnamen eingegeben haben, können Sie ein beliebiges Windows SDK höher als Version 10.0.17763.0 auswählen.

Für eine WinUI 3-App erstellen Sie ein neues Projekt mit der Vorlage Leere App, Gepackt (WinUI 3 in Desktop), um eine WinUI 3-Single-Page-Webanwendung einzurichten. Windows-App SDK-Version 1.3 oder höher ist erforderlich.

Installieren Sie das Paket und die Abhängigkeiten mit dem NuGet-Paket-Manager

Die Calling SDK-APIs und -Bibliotheken sind über ein NuGet-Paket öffentlich verfügbar.

So können Sie das NuGet-Paket für das Calling SDK suchen, herunterladen und installieren:

1. Öffnen Sie den NuGet-Paket-Manager, indem Sie Tools>NuGet-Paket-Manager>NuGet-Pakete für Lösung verwalten auswählen.
2. Wählen Sie Durchsuchen aus, und geben Sie dann Azure.Communication.Calling.WindowsClient in das Suchfeld ein.
3. Stellen Sie sicher, dass das Kontrollkästchen Vorabversion einbeziehen aktiviert ist.
4. Wählen Sie das Paket Azure.Communication.Calling.WindowsClient und dann Azure.Communication.Calling.WindowsClient1.4.0-beta.1 oder eine neuere Version aus.
5. Aktivieren Sie das Kontrollkästchen für das Azure Communication Services-Projekt im rechten Bereich.
6. Wählen Sie Installieren aus.

Implementieren der Beispiel-App in Visual Studio

In diesem Abschnitt wird beschrieben, wie Sie die App entwickeln, um Anrufe zu verwalten, die in Visual Studio funktionieren.

Anfordern des Zugriffs auf das Mikrofon

Die App benötigt Zugriff auf das Mikrofon. In UWP-Apps (Universelle Windows-Plattform) muss die Mikrofonfunktion in der App-Manifestdatei deklariert werden.

So greifen Sie auf das Mikrofon zu:

1. Doppelklicken Sie im Panel Solution Explorer auf die Datei mit der Erweiterung .appxmanifest.
2. Klicken Sie auf die Registerkarte Capabilities.
3. Aktivieren Sie in der Liste der Funktionen das Kontrollkästchen Microphone.

Benutzeroberflächenschaltflächen zum Annehmen und Beenden des Anrufs erstellen

Diese Beispiel-App enthält zwei Schaltflächen. Eine zum Tätigen und eine weitere zum Beenden des Anrufs.

Fügen Sie der App zwei Schaltflächen hinzu.

1. Doppelklicken Sie im Bereich Solution Explorer für UWP auf die Datei namens MainPage.xaml bzw. für WinUI 3 auf MainWindows.xaml.
2. Suchen Sie im zentralen Panel in der Vorschau der Benutzeroberfläche nach dem XAML-Code.
3. Ersetzen Sie den XAML-Code durch den folgenden Auszug:

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

Einrichten der App mit Calling-SDK-APIs

Die Calling SDK-APIs befinden sich in zwei verschiedenen Namespaces.

Durch die folgenden Schritte wird der C#-Compiler über diese Namespaces informiert, wodurch IntelliSense in Visual Studio die Codeentwicklung erleichtert.

1. Klicken Sie im Bereich Solution Explorer für UWP auf den Pfeil links neben der Datei mit dem Namen MainPage.xaml bzw. für WinUI 3 auf MainWindows.xaml.
2. Doppelklicken Sie auf die Datei namens MainPage.xaml.cs oder MainWindows.xaml.cs.
3. Fügen Sie am Ende der aktuellen using-Anweisungen die folgenden Befehle hinzu.

using Azure.Communication.Calling.WindowsClient;

MainPage.xaml.cs oder MainWindows.xaml.cs offen halten. Die nächsten Schritte fügen weiteren Code hinzu.

Aktivieren von App-Interaktionen

Die zuvor hinzugefügten Schaltflächen sind von CommunicationCall abhängig. Das bedeutet, dass ein CommunicationCall-Datenelement zur Klasse MainPage oder MainWindow hinzugefügt werden muss. Darüber hinaus muss derselben Klasse ein CallAgent-Datenelement hinzugefügt werden, damit der asynchrone Vorgang für die Erstellung von CallAgent erfolgreich ist.

Fügen Sie der Klasse MainPage oder MainWindow die folgenden Datenelemente hinzu:

CallAgent callAgent;
CommunicationCall call;

Erstellen von Schaltflächenhandlern

Zuvor wurden dem XAML-Code zwei Schaltflächen hinzugefügt. Der folgende Code fügt die Handler hinzu, die ausgeführt werden sollen, wenn ein Benutzer die Schaltfläche auswählt. Der folgende Code sollte nach den Datenelementen aus dem vorherigen Abschnitt hinzugefügt werden.

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

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

Objektmodell

Die folgenden Klassen und Schnittstellen befassen sich mit einigen der wichtigsten Features der Azure Communication Services-Clientbibliothek „Calling“ für UWP.

Name	BESCHREIBUNG
CallClient	CallClient ist der Haupteinstiegspunkt der Calling-Client-Bibliothek.
CallAgent	CallAgent dient dazu, Anrufe zu starten und daran teilzunehmen.
CommunicationCall	CommunicationCall dient zum Verwalten von Anrufen, die getätigt wurden oder an denen teilgenommen wurde.
CommunicationTokenCredential	CommunicationTokenCredential dient als tokengestützte Anmeldeinformation zum Instanziieren von CallAgent.
CallAgentOptions	Die CallAgentOptions enthält Informationen zum Identifizieren des Anrufers.
HangupOptions	HangupOptions gibt an, ob ein Anruf für alle Teilnehmer beendet werden soll.

Initialisieren von „CallAgent“

Zum Erzeugen einer CallAgent-Instanz anhand von CallClient müssen Sie die Methode CallClient.CreateCallAgentAsync verwenden, die ein CallAgent-Objekt asynchron zurückgibt, nachdem es initialisiert wurde.

Zum Erstellen von CallAgent müssen Sie ein CallTokenCredential-Objekt und ein CallAgentOptions-Objekt übergeben. Denken Sie daran, dass CallTokenCredential eine Ausnahme auslöst, wenn ein falsch formatiertes Token übergeben wird.

Um während der App-Initialisierung aufzurufen, fügen Sie den folgenden Code innerhalb einer Hilfsfunktion hinzu.

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

Ersetzen Sie das <AUTHENTICATION_TOKEN> durch ein gültiges Zugangstoken für Ihre Ressource. Wenn Sie ein Anmeldeinformationstoken beschaffen müssen, lesen Sie die Informationen zum Benutzerzugriffstoken.

Erstellen von CallAgent und Tätigen eines Anrufs

Die Objekte, die Sie für die Erstellung eines CallAgent benötigen, sind jetzt bereit. Es ist an der Zeit, CallAgent zu erstellen und asynchron einen Anruf zu tätigen.

Fügen Sie den folgenden Code nach der Behandlung der Ausnahme aus dem vorherigen Schritt hinzu.

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;

Verwenden Sie 8:echo123, um mit dem Echo-Bot von Azure Communication Services zu sprechen.

Stummschalten und Aufheben der Stummschaltung

Zum Stummschalten oder Aufheben der Stummschaltung des ausgehenden Audiosignals verwenden Sie die asynchronen Vorgänge MuteOutgoingAudioAsync und UnmuteOutgoingAudioAsync.

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

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

Andere Teilnehmer stummschalten

Hinweis

Verwenden Sie die Azure Communication Services Calling Windows SDK Version 1.9.0 oder höher.

Wenn ein PSTN-Teilnehmer stummgeschaltet ist, muss er eine Ankündigung erhalten, dass er stummgeschaltet wurde und dass er eine Tastenkombination (z. B. *6) drücken kann, um die Stummschaltung selbst aufzuheben. Wenn sie *6 drücken, muss die Stummschaltung aufgehoben werden.

Um alle anderen Teilnehmer stummzuschalten oder einen bestimmten Teilnehmer stummzuschalten, verwenden Sie die asynchronen Vorgänge MuteAllRemoteParticipantsAsync für den Anruf und MuteAsync den Remoteteilnehmer:

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

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

Um den lokalen Teilnehmer darüber zu informieren, dass er von anderen stummgeschaltet wird, abonnieren Sie das MutedByOthers Ereignis.

Beenden eines Anrufs

Nachdem ein Anruf getätigt wurde, verwenden Sie die HangupAsync Methode des CommunicationCall Objekts, um den Anruf zu beenden.

Verwenden Sie eine Instanz, HangupOptions um alle Teilnehmer darüber zu informieren, ob der Anruf beendet werden muss.

Fügen Sie den folgenden Code in HangupButton_Click:

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

Ausführen des Codes

1. Stellen Sie sicher, dass Visual Studio die App für x64, x86 oder ARM64 erzeugt.
2. Drücken Sie F5 , um mit der Ausführung der App zu beginnen.
3. Sobald die App ausgeführt wird, klicken Sie auf die Schaltfläche " Anrufen ", um einen Anruf an den definierten Empfänger zu tätigen.

Wenn die App zum ersten Mal ausgeführt wird, fordert das System den Benutzer auf, zugriff auf das Mikrofon zu gewähren.

Nächste Schritte

• Lernen Sie das Verwalten von Videos
• Informationen zum Aufzeichnen von Anrufen
• Lernen, wie man Anrufe transkribiert