Sdílet prostřednictvím

Správa hovorů

  • Článek

Zjistěte, jak spravovat volání pomocí sady SDK služby Azure Communication Services. Naučíme se, jak zavolat, spravovat jejich účastníky a vlastnosti.

Požadavky

Nainstalujte sadu SDK .

npm install Pomocí příkazu nainstalujte sadu AZURE Communication Services Common and Calling SDK pro JavaScript:

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

Inicializace požadovaných objektů

Pro CallClient většinu operací volání se vyžaduje instance. Když vytvoříte novou CallClient instanci, můžete ji nakonfigurovat s vlastními možnostmi, jako je Logger instance.

CallClient S instancí můžete vytvořit CallAgent instanci voláním createCallAgent. Tato metoda asynchronně vrátí CallAgent objekt instance.

Metoda createCallAgent se používá CommunicationTokenCredential jako argument. Přijímá přístupový token uživatele.

K přístupu deviceManagermůžete použít metodu getDeviceManager v CallClient instanci .

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 nejlépe spravovat připojení sady SDK k infrastruktuře Microsoftu

Tato Call Agent instance vám pomůže spravovat hovory (pro připojení nebo zahájení hovorů). Aby bylo možné pracovat s vaší sadou SDK volání, musí se připojit k infrastruktuře Microsoftu, aby bylo možné dostávat oznámení o příchozích hovorech a koordinovat další podrobnosti volání. Máte Call Agent dva možné stavy:

Připojeno – Call Agent Hodnota connectionStatue znamená, Connected že klientská sada SDK je připojená a dokáže přijímat oznámení z infrastruktury Microsoftu.

Odpojeno – Call Agent Hodnota Disconnected connectionStatue stavů existuje problém, který brání sadě SDK, aby se správně připojil. Call Agent by se mělo znovu vytvořit.

  • invalidToken: Pokud vypršela platnost tokenu nebo je neplatná Call Agent instance, odpojí se s touto chybou.
  • connectionIssue: Pokud došlo k problému s klientem, který se připojuje k infrascture Microsoftu, po mnoha opakovaných pokusech Call Agent connectionIssue se zobrazí chyba.

Zkontrolujte, jestli je vaše místní Call Agent infrastruktura připojená k infrastruktuře Microsoftu, a to kontrolou aktuální hodnoty connectionState vlastnosti. Během aktivního volání můžete naslouchat connectionStateChanged události a zjistit, jestli Call Agent se změny ze stavu Připojeno k Odpojeno .

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

Volání

K vytvoření a spuštění volání použijte jedno z rozhraní API callAgent a poskytněte uživateli, kterého jste vytvořili prostřednictvím sady SDK identity komunikačních služeb.

Vytváření a spouštění volání je synchronní. Instance call umožňuje přihlásit se k odběru událostí volání.

Volání uživatele nebo veřejné telefonní sítě 1:n

Pokud chcete volat jiného uživatele komunikačních služeb, použijte metodu startCall a callAgent předejte příjemce CommunicationUserIdentifier , který jste vytvořili pomocí knihovny pro správu komunikačních služeb.

Pro volání 1:1 pro uživatele použijte následující kód:

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

Chcete-li zavolat do veřejné telefonní sítě (PSTN), použijte metodu startCall zapnutou callAgent a předejte příjemce PhoneNumberIdentifier. Prostředek komunikační služby musí být nakonfigurovaný tak, aby umožňoval volání do veřejné telefonní sítě.

Při volání čísla veřejné telefonní sítě zadejte své alternativní ID volajícího. Alternativní ID volajícího je telefonní číslo (na základě standardu E.164), které identifikuje volajícího ve volání do veřejné telefonní sítě. Je to telefonní číslo, které příjemce hovoru uvidí pro příchozí hovor.

Poznámka:

Zkontrolujte podrobnosti o nabídce volání do veřejné telefonní sítě. Pokud chcete získat přístup k programům ve verzi Preview, použijte ho u dřívějšího osvojovacího programu.

Pro volání do veřejné telefonní sítě 1:1 použijte následující kód:

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

Pro volání uživatele a čísla veřejné telefonní sítě 1:n použijte následující kód:

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

Připojení k hovoru do místnosti

Chcete-li připojit room volání, můžete vytvořit instanci kontextového objektu roomId s vlastností jako room identifikátor. Ke spojení volání použijte metodu join a předejte instanci kontextu.

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

Nabízí room vývojářům aplikací lepší kontrolu nad tím, kdo se může připojit k hovoru, když se setká a jak spolupracují. Další informace najdete roomsv koncepční dokumentaci nebo postupujte podle úvodní příručky.

Připojení ke skupinovému hovoru

Poznámka:

Parametr groupId je považován za systémová metadata a může ho používat Microsoft pro operace, které jsou nutné ke spuštění systému. Do hodnoty nezahrnujte osobní údaje groupId . Microsoft s tímto parametrem nezachází jako s osobními údaji a jeho obsah může být viditelný zaměstnancům Microsoftu nebo uloženým dlouhodobým datům.

Parametr groupId vyžaduje, aby data byla ve formátu GUID. Doporučujeme používat náhodně generované identifikátory GUID, které nejsou ve vašich systémech považovány za osobní údaje.

Chcete-li zahájit nové skupinové volání nebo se připojit k probíhajícímu skupinovému volání, použijte join metodu a předejte objekt s groupId vlastností. Hodnota groupId musí být identifikátor GUID.

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

Přijetí příchozího hovoru

Instance callAgent vygeneruje incomingCall událost, když přihlášená identita přijme příchozí hovor. Pokud chcete naslouchat této události, přihlaste se k odběru pomocí jedné z těchto možností:

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

Událost incomingCall zahrnuje incomingCall instanci, kterou můžete přijmout nebo odmítnout.

Sada SDK pro volání komunikace Azure vyvolá funkci cameraStartFailed: diagnostika skutečného volání, pokud není kamera dostupná při spuštění, přijetí nebo připojování hovoru s povoleným videem. V tomto případě hovor začíná vypnutým videem. Kamera nemusí být dostupná, protože ji používá jiný proces nebo je v operačním systému zakázaná.

Blokování a obnovení hovoru

Poznámka:

V libovolném okamžiku by mělo existovat pouze 1 aktivní volání (ve Connected stavu s aktivním médiam). Všechna ostatní volání by měla být blokována uživatelem nebo programově aplikací. To je běžné ve scénářích, jako jsou kontaktní centra, kdy uživatel může potřebovat zpracovat více odchozích a příchozích volání, všechny neaktivní hovory by se měly blokovat a uživatel by měl komunikovat s ostatními jenom v aktivním hovoru.

K přidržování nebo obnovení hovoru můžete použít hold a resume asynchronní rozhraní API:

Blokování hovoru

await call.hold();

Při hold překladu rozhraní API je stav volání nastavený na LocalHoldhodnotu . V hovoru 1:1 je druhý účastník také přidržen a stav volání z pohledu tohoto účastníka je nastaven na RemoteHold. Později může druhý účastník přidržet svůj hovor, což by vedlo ke LocalHoldzměně stavu na . Ve skupinovém hovoru nebo schůzce – jedná se hold o místní operaci, která neudržuje hovor pro ostatní účastníky hovoru. Chcete-li obnovit volání, musí ho obnovit všichni uživatelé, kteří zahájili blokování.

Postup obnovení hovoru z blokování:

await call.resume();

resume Když se rozhraní API přeloží, stav volání se znovu nastaví na Connected.

Ztlumení a zrušení ztlumení hovoru

Pokud chcete ztlumit nebo zrušit ztlumení místního koncového bodu, můžete použít mute asynchronní unmute rozhraní API:

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

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

Ztlumení a zrušení ztlumení příchozího zvuku

Ztlumení příchozího zvuku nastaví hlasitost hovoru na 0. Pokud chcete ztlumit nebo zrušit ztlumení příchozího zvuku, můžete použít muteIncomingAudio asynchronní unmuteIncomingAudio rozhraní API:

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

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

Když je příchozí zvuk ztlumený, klientská sada SDK účastníka stále přijímá zvuk hovoru (zvuk vzdáleného účastníka). Zvuk hovoru není slyšet v mluvčím a účastník nemůže poslouchat, dokud není volána funkce call.unmuteIncomingAudio(). Můžeme ale použít filtr pro zvuk hovoru a přehrát filtrovaný zvuk.

Správa vzdálených účastníků

Všichni vzdálení účastníci jsou podrobně popsáni v objektu RemoteParticipant a jsou k dispozici prostřednictvím remoteParticipants kolekce v instanci volání. Je remoteParticipants přístupný z Call instance.

Zobrazení seznamu účastníků hovoru

Kolekce remoteParticipants vrátí seznam vzdálených účastníků volání:

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

Přidání účastníka do hovoru

Pokud chcete do hovoru přidat účastníka (buď uživatele, nebo telefonní číslo), můžete použít addParticipant rozhraní API. Zadejte jeden z typů Identifier . Synchronně vrátí remoteParticipant instanci. Událost remoteParticipantsUpdated z volání se vyvolá, když se účastník úspěšně přidá do hovoru.

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

Odebrání účastníka z hovoru

Pokud chcete účastníka (uživatele nebo telefonní číslo) z hovoru odebrat, můžete vyvolat removeParticipant. Musíte předat jeden z těchto Identifier typů. Tato metoda se vyřeší asynchronně po odebrání účastníka z volání. Účastník je také odebrán z remoteParticipants kolekce.

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

Přístup k vlastnostem vzdáleného účastníka

Vzdálení účastníci mají sadu přidružených vlastností a kolekcí:

  • CommunicationIdentifier: Získejte identifikátor vzdáleného účastníka. Identita je jedním z těchto CommunicationIdentifier typů:
const identifier = remoteParticipant.identifier;

  • Může to být jeden z následujících CommunicationIdentifier typů:

    • { communicationUserId: '<ACS_USER_ID'> }: Objekt představující uživatele Azure Communication Services.
    • { phoneNumber: '<E.164>' }: Objekt představující telefonní číslo ve formátu E.164.
    • { microsoftTeamsUserId: '<TEAMS_USER_ID>', isAnonymous?: boolean; cloud?: "public" | "dod" | "gcch" }: Objekt představující uživatele Teams.
    • { id: string }: objekt představující identifikátor, který neodpovídá žádnému z ostatních typů identifikátorů

  • state: Získejte stav vzdáleného účastníka.

const state = remoteParticipant.state;

  • Stav může být následující:

    • Idle:Počáteční stav.
    • Connecting: Stav přechodu, když se účastník připojuje k hovoru.
    • Ringing: Účastník vyzvání.
    • Connected: Účastník je připojen k hovoru.
    • Hold: Účastník je přidržený.
    • EarlyMedia: Oznámení, které se přehraje před tím, než se účastník připojí k hovoru.
    • InLobby: Označuje, že vzdálený účastník je v předsálí.
    • Disconnected:Koncový stav. Účastník se od hovoru odpojí. Pokud vzdálený účastník ztratí připojení k síti, změní se stav po Disconnected dvou minutách.

  • callEndReason: Pokud chcete zjistit, proč účastník opustil hovor, zkontrolujte callEndReason vlastnost:

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

    Poznámka:

    • Tato vlastnost je nastavena pouze při přidávání vzdáleného účastníka prostřednictvím call.addParticipant() API a vzdálený účastník například odmítne.
    • Ve scénáři, kdy UserB nakopne UserC z pohledu uživatele UserA, userA nezobrazuje tento příznak get set pro UserC. Jinými slovy, UserA nevidí vlastnost UserC's callEndReason nastavena vůbec.

  • isMuted stav: Pokud chcete zjistit, jestli je vzdálený účastník ztlumený, zkontrolujte isMuted vlastnost. BooleanVrátí .

    const isMuted = remoteParticipant.isMuted;

  • isSpeaking stav: Pokud chcete zjistit, jestli vzdálený účastník mluví, zkontrolujte isSpeaking vlastnost. BooleanVrátí .

    const isSpeaking = remoteParticipant.isSpeaking;

  • videoStreams: Chcete-li zkontrolovat všechny streamy videa, které daný účastník odesílá v tomto hovoru, zkontrolujte kolekci videoStreams . Obsahuje RemoteVideoStream objekty.

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

  • displayName: Chcete-li získat zobrazovaný název tohoto vzdáleného účastníka, zkontrolujte displayName vlastnost, která vrací řetězec.

    const displayName = remoteParticipant.displayName;

  • endpointDetails: Získejte podrobnosti o všech koncových bodech pro tohoto vzdáleného účastníka.

        const endpointDetails: EndpointDetails[] = remoteParticipant.endpointDetails;

    Poznámka: Vzdálený účastník může být ve volání z mnoha koncových bodů a každý koncový bod má svůj vlastní jedinečný participantId. participantId liší se od nezpracovaného ID remoteParticipant.identifier.

Ztlumení ostatních účastníků

Poznámka:

Pokud chcete použít toto rozhraní API, použijte webovou sadu SDK pro volání služeb Azure Communication Services verze 1.26.1 nebo vyšší.

Pokud chcete ztlumit všechny ostatní účastníky nebo ztlumit konkrétního účastníka, který je připojený k hovoru, můžete použít asynchronní rozhraní API muteAllRemoteParticipants pro hovor a mute vzdálený účastník. Událost mutedByOthers z volání se vyvolá, když místní účastník ztlumí ostatní.

Poznámka: Scénáře ztlumení účastníků veřejné telefonní sítě nebo účastníků hovoru 1:1 se nepodporují.

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

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

Kontrola vlastností volání

Získejte jedinečné ID (řetězec) pro volání:

const callId: string = call.id;

Získejte ID místního účastníka:

const participantId: string = call.info.participantId;

Poznámka: Identita služby Azure Communication Services může používat sadu SDK pro webové volání v mnoha koncových bodech a každý koncový bod má svůj vlastní jedinečný participantId. participantId liší se od nezpracovaného ID identity služby Azure Communication Services.

Pokud se připojíte ke schůzce Teams, načtěte ID vlákna:

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

Získejte informace o hovoru:

const callInfo = call.info;

Seznamte se s dalšími účastníky hovoru kontrolou remoteParticipants kolekce v instanci volání:

const remoteParticipants = call.remoteParticipants;

Identifikujte volajícího příchozího hovoru:

const callerIdentity = call.callerInfo.identifier;

identifier je jedním z CommunicationIdentifier typů.

Získání stavu volání:

const callState = call.state;

Vrátí řetězec představující aktuální stav volání:

  • None: Počáteční stav volání.
  • Connecting: Počáteční stav přechodu při umístění nebo přijetí volání.
  • Ringing: U odchozího hovoru označuje, že hovor vyzváněl vzdáleným účastníkům. Je to Incoming na jejich straně.
  • EarlyMedia: Označuje stav, ve kterém se před připojením hovoru přehraje oznámení.
  • Connected: Označuje, že je hovor připojen.
  • LocalHold: Označuje, že místní účastník hovor přidržil. Mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
  • RemoteHold: Označuje, že vzdálený účastník hovor přidrží. Mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
  • InLobby: Označuje, že uživatel je v předsálí.
  • Disconnecting: Stav přechodu před voláním Disconnected do stavu.
  • Disconnected: Konečný stav volání. Pokud dojde ke ztrátě síťového připojení, stav se změní na Disconnected po dvou minutách.

Zjistěte, proč volání skončilo kontrolou callEndReason vlastnosti:

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

Zjistěte, jestli je aktuální hovor příchozí nebo odchozí kontrolou direction vlastnosti. CallDirectionVrátí .

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

Zkontrolujte aktivní streamy videa a aktivní streamy sdílení obrazovky kontrolou localVideoStreams kolekce. Rozhraní localVideoStreams API vrací LocalVideoStream objekty typu Video, ScreenSharingnebo RawMedia.

const localVideoStreams = call.localVideoStreams;

Zkontrolujte, jestli je aktuální mikrofon ztlumený. BooleanVrátí .

const muted = call.isMuted;

Zkontrolujte, jestli je ztlumený aktuální příchozí zvuk (reproduktor). BooleanVrátí .

const incomingAudioMuted = call.isIncomingAudioMuted;

Zkontrolujte, jestli je zapnuté video. BooleanVrátí .

const isLocalVideoStarted = call.isLocalVideoStarted;

Zkontrolujte, jestli je zapnuté sdílení obrazovky. BooleanVrátí .

const isScreenSharingOn = call.isScreenSharingOn;

Nainstalujte sadu SDK .

Vyhledejte soubor na úrovni build.gradle projektu a přidejte mavenCentral() ho do seznamu úložišť v části buildscript a allprojects:

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

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

Potom do souboru na úrovni build.gradle modulu přidejte do oddílu dependencies následující řádky:

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

Inicializace požadovaných objektů

Pokud chcete vytvořit CallAgent instanci, musíte metodu createCallAgent CallClient volat v instanci. Toto volání asynchronně vrátí CallAgent objekt instance.

Metoda createCallAgent přebírá CommunicationUserCredential jako argument, který zapouzdřuje přístupový token.

Pokud chcete získat přístup DeviceManager, musíte nejprve vytvořit callAgent instanci. Pak můžete použít metodu CallClient.getDeviceManager získat 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();

Pokud chcete nastavit zobrazovaný název volajícího, použijte tuto alternativní metodu:

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

Volání

Chcete-li vytvořit a zahájit volání, musíte volat metodu CallAgent.startCall() a poskytnout Identifier volané(y). Pokud se chcete připojit ke skupinovému volání, musíte volat metodu CallAgent.join() a zadat id skupiny. ID skupiny musí být ve formátu GUID nebo UUID.

Vytváření a spouštění volání je synchronní. Instance volání umožňuje přihlásit se k odběru všech událostí volání.

Umístění hovoru 1:1 uživateli

Pokud chcete volat jinému uživateli komunikační služby, zavolejte metodu call callAgent a předejte objekt s communicationUserId klíčem.

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 hovor s uživateli a veřejnou telefonní skupinou

Poznámka:

Zkontrolujte podrobnosti o nabídce volání do veřejné telefonní sítě. Pokud chcete získat přístup k programům ve verzi Preview, použijte ho u dřívějšího osvojovacího programu.

Pokud chcete uživateli volat 1:n a číslo veřejné telefonní sítě, musíte zadat telefonní číslo volaného. Prostředek komunikační služby musí být nakonfigurovaný tak, aby umožňoval volání do veřejné telefonní sítě:

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

Přijmout hovor

Pokud chcete přijmout volání, zavolejte metodu accept u objektu volání.

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

Přijetí hovoru s videokamerou na:

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

Příchozí hovor lze získat přihlášením k odběru onIncomingCall události v objektu callAgent :

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

Připojení k hovoru do místnosti

CallAgent Pomocí volání RoomCallLocator do místnosti a připojit se k ní zadáním .roomId Metoda CallAgent.join vrátí Call objekt:

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

Nabízí room vývojářům aplikací lepší kontrolu nad tím, kdo se může připojit k hovoru, když se setká a jak spolupracují. Další informace najdete roomsv koncepční dokumentaci nebo postupujte podle úvodní příručky.

Připojení ke skupinovému hovoru

Pokud chcete zahájit nové skupinové volání nebo se připojit k probíhajícímu skupinovému volání, musíte volat metodu join a předat objekt s groupId vlastností. Hodnota musí být identifikátor GUID.

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

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

Vlastnosti volání

Získejte jedinečné ID pro tento hovor:

String callId = call.getId();

Další informace o dalších účastnících kolekce kontroly remoteParticipant volání v call instanci:

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

Identita volajícího, pokud je hovor příchozí:

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

Získejte stav hovoru:

CallState callState = call.getState();

Vrátí řetězec představující aktuální stav volání:

  • NONE – počáteční stav volání
  • "EARLY_MEDIA" – označuje stav, ve kterém se před připojením hovoru přehraje oznámení.
  • PŘIPOJENÍ – počáteční stav přechodu po umístění nebo přijetí volání
  • Vyzvánění – pro odchozí hovor – indikuje, že hovor vyzvání pro vzdálené účastníky
  • CONNECTED - hovor je připojený
  • "LOCAL_HOLD" – hovor je přidržen místním účastníkem, mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
  • "REMOTE_HOLD" – hovor je přidržen vzdáleným účastníkem, mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
  • ODPOJENÍ – stav přechodu před voláním do stavu Odpojeno
  • Odpojeno – stav konečného volání
  • "IN_LOBBY" – v předsálí pro interoperabilitu schůzek Teams

Pokud chcete zjistit, proč hovor skončil, zkontrolujte callEndReason vlastnost. Obsahuje kód nebo podkód:

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

Pokud chcete zjistit, jestli je aktuální hovor příchozí nebo odchozí hovor, zkontrolujte callDirection vlastnost:

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

Pokud chcete zjistit, jestli je aktuální mikrofon ztlumený, zkontrolujte muted vlastnost:

boolean muted = call.isMuted();

Pokud chcete zkontrolovat aktivní streamy videa, zkontrolujte kolekci localVideoStreams :

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

Vypnutí a zapnutí zvuku

Pokud chcete ztlumit nebo zrušit ztlumení místního koncového bodu, můžete použít mute asynchronní unmute rozhraní API:

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

Změna hlasitosti hovoru

Během hovoru by měly klíče hardwarového svazku na telefonu umožnit uživateli změnit hlasitost hovoru. To se provádí pomocí metody setVolumeControlStream s typem AudioManager.STREAM_VOICE_CALL datového proudu v aktivitě, kde je volání umístěné. Díky tomu můžou hardwarové klávesy hlasitosti měnit hlasitost hovoru (označené ikonou telefonu nebo něco podobného na posuvníku hlasitosti), aby se zabránilo změně hlasitosti pro jiné zvukové profily, jako jsou alarmy, média nebo široký hlasitost systému. Další informace najdete v tématu Zpracování změn ve zvukovém výstupu | Vývojáři pro Android.

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

Vzdálená správa účastníků

Všichni vzdálení účastníci jsou reprezentováni typem RemoteParticipant a jsou k dispozici prostřednictvím remoteParticipants kolekce v instanci volání.

Vypsání účastníků hovoru

Kolekce remoteParticipants vrátí seznam vzdálených účastníků v daném hovoru:

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

Přidání účastníka do hovoru

Pokud chcete přidat účastníka do hovoru (buď uživatele, nebo telefonní číslo), můžete vyvolat addParticipant. Tím se synchronně vrátí instance vzdáleného účastníka.

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

Odebrání účastníka z hovoru

Pokud chcete účastníka odebrat z hovoru (buď uživatele, nebo telefonní číslo), můžete vyvolat removeParticipant. Tím se asynchronně vyřeší, jakmile se účastník odebere z hovoru. Účastník bude také odebrán z remoteParticipants kolekce.

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

Vlastnosti vzdáleného účastníka

Každý vzdálený účastník má přiřazenou sadu vlastností a kolekcí:

  • Získejte identifikátor tohoto vzdáleného účastníka. Identita je jedním z typů Identifikátor.

    CommunicationIdentifier participantIdentifier = remoteParticipant.getIdentifier();

  • Získejte stav tohoto vzdáleného účastníka.

    ParticipantState state = remoteParticipant.getState();

Stát může být jedním z

  • Nečinnost – počáteční stav

  • "EARLY_MEDIA" – oznámení se přehrával před připojením účastníka k hovoru.

  • Vyzvánění – hovor účastníka vyzvánění

  • PŘIPOJENÍ – přechodový stav, když se účastník připojuje k hovoru

  • "CONNECTED" - účastník je připojen k hovoru

  • Hold – účastník je přidržený

  • "IN_LOBBY" – účastník čeká v předsálí, aby byl přijat. Aktuálně se používá jenom ve scénáři spolupráce v Teams.

  • Odpojeno – konečný stav – účastník se od hovoru odpojí.

  • Pokud chcete zjistit, proč účastník opustil hovor, zkontrolujte callEndReason vlastnost:

    CallEndReason callEndReason = remoteParticipant.getCallEndReason();

  • Pokud chcete zkontrolovat, jestli je tento vzdálený účastník ztlumený nebo ne, zkontrolujte isMuted vlastnost:

    boolean isParticipantMuted = remoteParticipant.isMuted();

  • Pokud chcete zkontrolovat, jestli tento vzdálený účastník mluví nebo ne, zkontrolujte isSpeaking vlastnost:

    boolean isParticipantSpeaking = remoteParticipant.isSpeaking();

  • Pokud chcete zkontrolovat všechny streamy videa, které daný účastník odesílá v tomto hovoru, zkontrolujte kolekci videoStreams :

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

Ztlumení ostatních účastníků

Poznámka:

Pokud chcete toto rozhraní API použít, použijte sadu Azure Communication Services Volající sadu Android SDK verze 2.11.0 nebo vyšší.

Pokud chcete ztlumit všechny ostatní účastníky hovoru, použijte muteAllRemoteParticipants k volání rozhraní API.

call.muteAllRemoteParticipants();

Pokud chcete ztlumit konkrétního vzdáleného účastníka, použijte mute rozhraní API daného vzdáleného účastníka.

remoteParticipant.mute();

Pokud chcete místnímu účastníkovi oznámit, že byli ztlumený jinými uživateli, přihlaste se k odběru onMutedByOthers události.

Používání služeb v popředí

V případech, kdy chcete spustit úlohu viditelnou uživatelem i v případě, že je vaše aplikace na pozadí, můžete použít služby Foreground Services.

Pomocí služeb Foreground Můžete například udržovat uživatele viditelné oznámení, když má vaše aplikace aktivní volání. Tímto způsobem, i když uživatel přejde na domovskou obrazovku nebo odebere aplikaci z poslední obrazovky, bude hovor i nadále aktivní.

Pokud během hovoru nepoužíváte službu Foreground, přechod na domovskou obrazovku může zůstat aktivní, ale odebrání aplikace z poslední obrazovky může hovor zastavit, pokud operační systém Android ukončí proces vaší aplikace.

Službu Foreground byste měli spustit při spuštění nebo připojení k volání, například:

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

Službu Foreground zastavte, když zavěsíte hovor nebo se stav hovoru odpojí, například:

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

Poznámky k používání služeb Foreground

Mějte na paměti, že scénáře, jako je zastavení již spuštěné služby Foreground, když je aplikace odebrána ze seznamu posledních, odebere viditelné oznámení uživatele a operační systém Android může udržet proces aplikace naživu po určitou dobu navíc, což znamená, že volání může být během tohoto období stále aktivní.

Pokud vaše aplikace zastavuje službu Foreground v metodě služby onTaskRemoved , vaše aplikace může například spustit nebo zastavit zvuk a video podle vašeho životního cyklu aktivity, jako je zastavení zvuku a videa, když je vaše aktivita zničena přepsání onDestroy metody.

Nastavení systému

Podle těchto kroků nastavte systém.

Vytvoření projektu Xcode

V Xcode vytvořte nový projekt pro iOS a vyberte šablonu aplikace s jedním zobrazením . Tento článek používá architekturu SwiftUI, takže byste měli nastavit jazyk na Swift a nastavit rozhraní na SwiftUI.

V tomto článku nebudete vytvářet testy. Zrušte zaškrtnutí políčka Zahrnout testy .

Snímek obrazovky znázorňující okno pro vytvoření projektu v Xcode

Instalace balíčku a závislostí pomocí CocoaPods

  1. Vytvořte pro aplikaci soubor Podfile, například v tomto příkladu:

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

  2. Spusťte pod install.

  3. Otevřete .xcworkspace pomocí Xcode.

Vyžádání přístupu k mikrofonu

Pokud chcete získat přístup k mikrofonu zařízení, musíte aktualizovat seznam vlastností informací aplikace pomocí NSMicrophoneUsageDescription. Nastavte přidruženou hodnotu na řetězec, který je součástí dialogového okna, který systém používá k vyžádání přístupu od uživatele.

Klikněte pravým tlačítkem myši na položku Info.plist stromu projektu a pak vyberte Open As>Source Code. Do oddílu nejvyšší úrovně <dict> přidejte následující řádky a pak soubor uložte.

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

Nastavení architektury aplikace

Otevřete soubor projektu ContentView.swift . import Přidejte deklaraci do horní části souboru pro import AzureCommunicationCalling knihovny. Kromě toho import AVFoundation. Potřebujete ho pro žádosti o zvuková oprávnění v kódu.

import AzureCommunicationCalling
import AVFoundation

Inicializace callagentu

Chcete-li vytvořit CallAgent instanci z CallClient, musíte použít metodu callClient.createCallAgent , která asynchronně vrátí CallAgent objekt po inicializaci.

Pokud chcete vytvořit klienta volání, předejte CommunicationTokenCredential objekt:

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 Předejte objekt, který jste vytvořiliCallClient, a nastavte zobrazovaný název:

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

Poznámka:

Když aplikace implementuje delegáty událostí, musí obsahovat silný odkaz na objekty, které vyžadují odběry událostí. Například při vrácení objektu RemoteParticipant při vyvolání call.addParticipant metody a aplikace nastaví delegáta na RemoteParticipantDelegatenaslouchání , aplikace musí obsahovat silný odkaz na RemoteParticipant objekt. Jinak pokud se tento objekt shromažďuje, delegát vyvolá závažnou výjimku, když se volající sada SDK pokusí vyvolat objekt.

Umístění odchozího hovoru

Pokud chcete vytvořit a spustit volání, musíte volat jedno z rozhraní API CallAgent a poskytnout identitu komunikační služby uživatele, kterého jste zřídili pomocí sady SDK pro správu komunikačních služeb.

Vytváření a spouštění volání je synchronní. Obdržíte instanci volání, která vám umožní přihlásit se k odběru všech událostí volání.

Volání uživatele 1:1 nebo 1:n s uživateli a veřejnou telefonní skupinou

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 hovor s uživateli a veřejnou telefonní skupinou

Poznámka:

Zkontrolujte podrobnosti o nabídce volání do veřejné telefonní sítě. Pokud chcete získat přístup k programům ve verzi Preview, použijte ho u dřívějšího osvojovacího programu.

Pokud chcete zavolat do veřejné telefonní sítě, musíte zadat telefonní číslo získané pomocí komunikačních služeb.

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

Připojení k hovoru do místnosti

Chcete-li připojit volání room , zadejte roomId vlastnost jako room identifikátor. Chcete-li se připojit k volání, použijte metodu join a předejte 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)
    }
}

Nabízí room vývojářům aplikací lepší kontrolu nad tím, kdo se může připojit k hovoru, když se setká a jak spolupracují. Další informace najdete roomsv koncepční dokumentaci nebo postupujte podle úvodní příručky.

Připojení ke skupinovému hovoru

Pokud se chcete připojit k hovoru, musíte volat jedno z rozhraní API na .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")
    }
}

Přihlášení k odběru příchozího hovoru

Přihlaste se k odběru události příchozího hovoru.

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

Přijetí příchozího hovoru

Chcete-li přijmout volání, zavolejte accept metodu objektu IncomingCall .

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

Provádění operací uprostřed volání

Během hovoru můžete provádět různé operace a spravovat nastavení související s videem a zvukem.

Vypnutí a zapnutí zvuku

Pokud chcete ztlumit nebo zrušit ztlumení místního koncového bodu, můžete použít mute asynchronní unmute rozhraní API.

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

Pomocí následujícího kódu můžete asynchronně zrušit ztlumení místního koncového bodu.

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

Správa vzdálených účastníků

Všichni vzdálení účastníci jsou reprezentováni typem RemoteParticipant a jsou k dispozici prostřednictvím remoteParticipants kolekce v instanci volání.

Vypsání účastníků hovoru

call.remoteParticipants

Přidání účastníka do hovoru

Pokud chcete přidat účastníka do hovoru (buď uživatele, nebo telefonní číslo), můžete vyvolat addParticipant. Tento příkaz synchronně vrátí instanci vzdáleného účastníka.

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

Odebrání účastníka z hovoru

Pokud chcete účastníka odebrat z hovoru (uživatele nebo telefonní číslo), můžete vyvolat removeParticipant rozhraní API. Tím se vyřeší asynchronně.

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

Získání vlastností vzdáleného účastníka

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

Ztlumení ostatních účastníků

Poznámka:

Pokud chcete toto rozhraní API použít, použijte sadu Azure Communication Services Call iOS SDK verze 2.13.0 nebo vyšší.

Pokud chcete ztlumit všechny ostatní účastníky hovoru, použijte muteAllRemoteParticipants k volání rozhraní API.

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

Pokud chcete ztlumit konkrétního vzdáleného účastníka, použijte mute rozhraní API daného vzdáleného účastníka.

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

Pokud chcete místnímu účastníkovi oznámit, že byli ztlumený jinými uživateli, přihlaste se k odběru onMutedByOthers události.

Nastavení systému

Podle těchto kroků nastavte systém.

Vytvoření projektu sady Visual Studio

V případě Univerzální platforma Windows aplikace vytvořte v sadě Visual Studio 2022 nový projekt Prázdná aplikace (Universal Windows). Po zadání názvu projektu si můžete vybrat libovolnou sadu Windows SDK později než 10.0.17763.0.

V případě aplikace WinUI 3 vytvořte nový projekt pomocí šablony Prázdná aplikace zabalená (WinUI 3 v desktopové verzi) pro nastavení jednostráňové aplikace WinUI 3. Vyžaduje se sada Windows App SDK verze 1.3 nebo novější.

Instalace balíčku a závislostí pomocí Správce balíčků NuGet

Rozhraní API a knihovny volající sady SDK jsou veřejně dostupné prostřednictvím balíčku NuGet.

Vyhledání, stažení a instalace balíčku NuGet volající sady SDK:

  1. Otevřete Správce balíčků NuGet výběrem nástrojů>NuGet Správce balíčků> Nabídky NuGet pro řešení.
  2. Vyberte Procházet a do vyhledávacího pole zadejte Azure.Communication.Calling.WindowsClient .
  3. Ujistěte se, že je zaškrtnuté políčko Zahrnout předběžné verze .
  4. Vyberte balíček Azure.Communication.Calling.WindowsClient a pak vyberte Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 nebo novější verzi.
  5. Zaškrtněte políčko odpovídající projektu Azure Communication Services v pravém podokně.
  6. Vyberte volbu Instalovat.

Vyžádání přístupu k mikrofonu

Aby aplikace fungovala správně, vyžaduje přístup k mikrofonu. V aplikacích pro UPW by měla být funkce mikrofonu deklarována v souboru manifestu aplikace.

Následující kroky ukazují, jak toho dosáhnout.

  1. Na panelu Solution Explorer poklikejte na soubor s příponou .appxmanifest .
  2. Klikněte na Capabilities kartu.
  3. Microphone V seznamu možností zaškrtněte políčko.

Vytvoření tlačítek uživatelského rozhraní pro umístění a zavěsit hovor

Tato jednoduchá ukázková aplikace obsahuje dvě tlačítka. Jeden pro umístění hovoru a druhý zavěsit umístěný hovor. Následující postup ukazuje, jak tato tlačítka přidat do aplikace.

  1. Na panelu Solution Explorer poklikejte na soubor s názvem MainPage.xaml UPW nebo MainWindows.xaml WinUI 3.
  2. Na centrálním panelu vyhledejte kód XAML v náhledu uživatelského rozhraní.
  3. Upravte kód XAML následujícím výňatkem:
<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>

Nastavení aplikace pomocí rozhraní API pro volání sady SDK

Rozhraní API volající sady SDK jsou ve dvou různých oborech názvů. Následující kroky informují kompilátor jazyka C# o těchto oborech názvů, což umožňuje intellisense sady Visual Studio pomáhat s vývojem kódu.

  1. Na panelu Solution Explorer klikněte na šipku na levé straně souboru s názvem MainPage.xaml UPW nebo MainWindows.xaml WinUI 3.
  2. Poklikejte na soubor s názvem MainPage.xaml.cs nebo MainWindows.xaml.cs.
  3. Na konec aktuálních using příkazů přidejte následující příkazy.
using Azure.Communication.Calling.WindowsClient;

Nechte MainPage.xaml.cs nebo MainWindows.xaml.cs otevřete. Další kroky do něj přidají další kód.

Povolit interakce aplikací

Tlačítka uživatelského rozhraní, která byla přidána, musí pracovat nad umístěním CommunicationCall. To znamená, že CommunicationCall datový člen by měl být přidán do MainPage třídy nebo MainWindow třídy. Kromě toho, aby bylo možné úspěšně vytvořit CallAgent asynchronní operaci, CallAgent by měl být také přidán datový člen do stejné třídy.

Do třídy pr MainWindow přidejte následující datové členyMainPage:

CallAgent callAgent;
CommunicationCall call;

Vytváření obslužných rutin tlačítek

Dříve byly do kódu XAML přidány dvě tlačítka uživatelského rozhraní. Následující kód přidá obslužné rutiny, které se mají spustit, když uživatel tlačítko vybere. Následující kód by se měl přidat za datové členy z předchozí části.

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

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

Objektový model

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí klientské knihovny volání služeb Azure Communication Services pro UPW.

Název Popis
CallClient Jedná se CallClient o hlavní vstupní bod do klientské knihovny volání.
CallAgent Slouží CallAgent ke spuštění a připojení k voláním.
CommunicationCall Slouží CommunicationCall ke správě umístěných nebo připojených hovorů.
CommunicationTokenCredential Slouží CommunicationTokenCredential jako přihlašovací údaje tokenu k vytvoření instance CallAgent.
CallAgentOptions Obsahuje CallAgentOptions informace pro identifikaci volajícího.
HangupOptions Informuje HangupOptions , jestli má být hovor ukončen všem účastníkům.

Inicializace callagentu

Chcete-li vytvořit CallAgent instanci z CallClient, musíte použít CallClient.CreateCallAgentAsync metodu, která asynchronně vrátí CallAgent objekt po inicializaci.

Chcete-li vytvořit CallAgent, musíte předat CallTokenCredential objekt a CallAgentOptions objekt. Mějte na paměti, že CallTokenCredential pokud je předán poškozený token.

Do pomocné funkce by se měl přidat následující kód, který se má volat při inicializaci aplikace.

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

<AUTHENTICATION_TOKEN> Změňte platný token přihlašovacích údajů pro váš prostředek. Informace o přístupovém tokenu uživatele najdete v dokumentaci, pokud musí být zdrojový token přihlašovacích údajů.

Vytvoření callagentu a umístění hovoru

Objekty potřebné k vytvoření CallAgent jsou teď připravené. Je čas asynchronně vytvořit CallAgent a umístit volání.

Po zpracování výjimky z předchozího kroku by se měl přidat následující kód.

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;

Nebojte se používat 8:echo123 ke komunikaci s robotem echo služby Azure Communication Services.

Vypnutí a zapnutí zvuku

Pokud chcete ztlumit nebo zrušit ztlumení odchozího zvuku, můžete použít MuteOutgoingAudioAsync asynchronní UnmuteOutgoingAudioAsync rozhraní API:

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

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

Ztlumení ostatních účastníků

Poznámka:

Pokud chcete toto rozhraní API použít, použijte sadu Windows SDK pro volání služby Azure Communication Services verze 1.9.0 nebo vyšší.

Pokud chcete ztlumit všechny ostatní účastníky nebo ztlumit konkrétního účastníka, můžete použít asynchronní rozhraní API MuteAllRemoteParticipantsAsync pro volání a MuteAsync vzdáleného účastníka:

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

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

Pokud chcete místnímu účastníkovi oznámit, že byli ztlumený jinými uživateli, přihlaste se k odběru MutedByOthers události.

Ukončení hovoru

Po umístění HangupAsync volání by metoda objektu CommunicationCall měla být použita k zablokování volání.

Instance HangupOptions by měla být také použita k informování, zda musí být hovor ukončen všem účastníkům.

Následující kód by měl být přidán dovnitř HangupButton_Click.

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

Spuštění kódu

Ujistěte se, že Visual Studio sestaví aplikaci pro x64x86 aplikaci nebo ARM64a pak stiskněte klávesu a F5 spusťte aplikaci. Potom kliknutím na Call tlačítko umístíte volání do volané.

Mějte na paměti, že při prvním spuštění aplikace systém vyzve uživatele k udělení přístupu k mikrofonu.

Další kroky