Sdílet prostřednictvím

Přihlášení k odběru událostí sady SDK

  • Článek

Sady SDK služby Azure Communication Services jsou dynamické a obsahují mnoho vlastností. Když se tyto změny změní, můžete jako vývojář vědět, kdy a co je důležitější. Tady je postup!

Události v sadě SDK pro volání komunikace Azure

Tato příručka popisuje různé události nebo vlastnosti, ke které se vaše aplikace může přihlásit. Přihlášení k odběru těchto událostí umožňuje, aby vaše aplikace byla informována o změně stavu v volající sadě SDK a odpovídajícím způsobem reagovala.

Sledování událostí je zásadní, protože umožňuje, aby stav vaší aplikace zůstal synchronizovaný se stavem architektury ACSCalling, aniž byste museli implementovat mechanismus vyžádání obsahu na objektech sady SDK.

V této příručce se předpokládá, že jste prošli rychlým startem nebo jste implementovali aplikaci, která dokáže provádět a přijímat volání. Pokud jste nedokončili úvodní příručku, projděte si náš rychlý start.

Každý objekt v javascriptové volající sadě SDK má properties a collections. Jejich hodnoty se mění po celou dobu životnosti objektu. Tuto metodu on() použijte k odběru událostí objektů a použijte metodu off() k odhlášení odběru událostí objektů.

Vlastnosti

Můžete se přihlásit k odběru '<property>Changed' události, abyste naslouchali změnám hodnot ve vlastnosti.

Příklad předplatného u vlastnosti

V tomto příkladu se přihlásíme k odběru změn v hodnotě isLocalVideoStarted vlastnosti.

call.on('isLocalVideoStartedChanged', () => {
    // At that point the value call.isLocalVideoStarted is updated
    console.log(`isLocalVideoStarted changed: ${call.isLocalVideoStarted}`);
});

Kolekce

Můžete se přihlásit k odběru události "<collection>Updated" a dostávat oznámení o změnách v kolekci objektů. <Událost Collection>Updated se aktivuje při každém přidání nebo odebrání prvků z kolekce, kterou monitorujete.

  • Datová '<collection>Updated' část události obsahuje added pole obsahující hodnoty přidané do kolekce.
  • Datová '<collection>Updated' část události má removed také pole obsahující hodnoty, které byly z kolekce odebrány.

Příklad předplatného v kolekci

V tomto příkladu se přihlásíme k odběru změn v hodnotách call objektu LocalVideoStream.

call.on('localVideoStreamsUpdated', updateEvent => {
    updateEvent.added.forEach(async (localVideoStream) => {
        // Contains an array of LocalVideoStream that were added to the call
        // Add a preview and start any processing if needed
        handleAddedLocalVideoStream(localVideoStream )
    });
    updateEvent.removed.forEach(localVideoStream => {
        // Contains an array of LocalVideoStream that were removed from the call
        // Remove the preview and stop any processing if needed
        handleRemovedLocalVideoStream(localVideoStream ) 
    });
});

Události objektu CallAgent

Název události: incomingCall

Událost incomingCall se aktivuje, když klient přijímá příchozí hovor.

Jak by vaše aplikace měla reagovat na událost?

Aplikace by měla uživatele informovat o příchozím hovoru. Výzva k oznámení by měla navrhnout uživateli, aby hovor přijal nebo odmítl.

Ukázka kódu:

callClient.on('incomingCall', (async (incomimgCallEvent) => {
    try {
        // Store a reference to the call object
        incomingCall = incomimgCallEvent.incomingCall; 
        // Update your UI to allow
        acceptCallButton.disabled = false; 
        callButton.disabled = true;
    } catch (error) {
        console.error(error);
    }
});

Název události: callsUpdated

Aktualizovaná callsUpdated událost se aktivuje, když se volání odebere nebo přidá do agenta volání. K této události dochází, když uživatel provede, přijme nebo ukončí hovor.

Jak by vaše aplikace měla reagovat na událost? Aplikace by měla aktualizovat své uživatelské rozhraní na základě počtu aktivních volání instance CallAgent.

Název události: connectionStateChanged

Událost connectionStateChanged se aktivovala při aktualizaci signalizačního CallAgent stavu.

Jak by vaše aplikace měla reagovat na událost?

Aplikace by měla aktualizovat své uživatelské rozhraní na základě nového stavu. Možné hodnoty stavu připojení jsou Connected a Disconnected

Ukázka kódu:

callClient.on('connectionStateChanged', (async (connectionStateChangedEvent) => {
    if (connectionStateChangedEvent.newState === "Connected") {
        enableCallControls() // Enable all UI element that allow user to make a call
    }

    if (connectionStateChangedEvent.newState === 'Disconnected') {
        if (typeof connectionStateChangedEvent.reason !== 'undefined') {
            alert(`Disconnected reason: ${connectionStateChangedEvent.reason}`)
        } 
        disableCallControls() // Disable all the UI element that allows the user to make a call
    }
});

Události objektu Call

Název události: stateChanged

Událost stateChanged se aktivuje, když se stav volání změní. Například když volání přejde z connected do disconnected.

Jak by vaše aplikace měla reagovat na událost?

Aplikace by měla odpovídajícím způsobem aktualizovat své uživatelské rozhraní. Zakázání nebo povolení příslušných tlačítek a dalších prvků uživatelského rozhraní na základě nového stavu volání

Ukázka kódu:

call.on('stateChanged', (async (connectionStateChangedEvent) => {
  if(call.state === 'Connected') {
      connectedLabel.hidden = false;
      acceptCallButton.disabled = true;
      startCallButton.disabled = true;
      startVideoButton.disabled = false;
      stopVideoButton.disabled = false
  } else if (call.state === 'Disconnected') {
      connectedLabel.hidden = true;
      startCallButton.disabled = false;
      console.log(`Call ended, call end reason={code=${call.callEndReason.code}, subCode=${call.callEndReason.subCode}}`);
  }
});

Akce: idChanged

Událost idChanged se aktivuje, když se ZMĚNÍ ID volání. ID volání se změní, když se hovor přesune ze connecting stavu do connected. Po připojení hovoru zůstane ID hovoru stejné.

Jak může vaše aplikace reagovat na událost?

Aplikace by měla nové ID volání uložit, ale v případě potřeby se dá z objektu volání načíst i později.

Ukázka kódu:

let callId = "";
call.on('idChanged', (async (callIdChangedEvent) => {
  callId = call.id; // You can log it as the call ID is useful for debugging call issues
});

Akce: isMutedChanged

Událost isMutedChanged se aktivuje při ztlumení nebo zrušení ztlumení místního zvuku.

Jak může vaše aplikace reagovat na událost?

Aplikace by měla aktualizovat tlačítko ztlumení nebo zrušení ztlumení na správný stav.

Ukázka kódu:

call.on('isMutedChanged', (async (isMutedChangedEvent) => {
    microphoneButton.disabled = call.isMuted;       
});

Akce: isScreenSharingOnChanged

Událost isScreenSharingOnChanged se aktivuje, když je povolené nebo zakázané sdílení obrazovky místního uživatele.

Jak může vaše aplikace reagovat na událost?

Pokud se sdílení obrazovky stalo, měla by aplikace uživateli zobrazit náhled nebo upozornění. Pokud sdílení obrazovky vypnulo, měla by aplikace odebrat náhled a upozornění.

Ukázka kódu:

call.on('isScreenSharingOnChanged', () => {
  if (!this.call.isScreenSharing) {
      displayStartScreenSharingButton();
      hideScreenSharingWarning()
      removeScreenSharingPreview();    
  } else {
      displayScreenSharingWarning()
      displayStopScreenSharingButton();
      renderScreenSharingPreview(); 
  }
});

Akce: isLocalVideoStartedChanged

Událost isLocalVideoStartedChanged se aktivuje, když uživatel povolil naše místní video.

Jak může vaše aplikace reagovat na událost?

Aplikace by měla zobrazit náhled místního videa a povolit nebo zakázat tlačítko aktivace fotoaparátu.

Ukázka kódu:

call.on('isLocalVideoStartedChanged', () => {
    showdDisableCameraButton(call.isLocalVideoStarted);
});

Akce: remoteParticipantsUpdated

Vaše aplikace by se měla přihlásit k odběru události pro každou přidanou RemoteParticipants událost a odhlásit odběr událostí účastníkům, kteří hovor opustili.

Jak může vaše aplikace reagovat na událost? Aplikace by měla zobrazit náhled místního videa a povolit nebo zakázat tlačítko aktivace fotoaparátu.

Ukázka kódu:

call.on('remoteParticipantsUpdated', (remoteParticipantsUpdatedEvent) => {
    remoteParticipantsUpdatedEvent.added.forEach(participant => {
        // handleParticipant should
        //   - subscribe to the remote participants events 
        //   - update the UI 
        handleParticipant(participant);
    });
    
    remoteParticipantsUpdatedEvent.removed.forEach(participant => {
        // removeParticipant should
        //   - unsubcribe from the remote participants events 
        //   - update the UI  
        removeParticipant(participant);
    });
});

Akce: localVideoStreamsUpdated

Událost localVideoStreamsUpdated se aktivuje, když se změní seznam místních streamů videa. K těmto změnám dochází, když uživatel spustí nebo odebere stream videa.

Jak může vaše aplikace reagovat na událost?

U každé přidané LocalVideoStream aplikace by se měly zobrazovat náhledy. Vaše aplikace by měla odebrat náhled a zastavit zpracování pro každou LocalVideoStream odebranou verzi.

Ukázka kódu:

call.on('localVideoStreamsUpdated', (localVideoStreamUpdatedEvent) => {
    localVideoStreamUpdatedEvent.added.forEach(addedLocalVideoStream => { 
        // Add a preview and start any processing if needed
        handleAddedLocalVideoStream(addedLocalVideoStream) 
    });

    localVideoStreamUpdatedEvent.removed.forEach(removedLocalVideoStream => {
         // Remove the preview and stop any processing if needed
        this.handleRemovedLocalVideoStream(removedLocalVideoStream) 
    });
});

Akce: remoteAudioStreamsUpdated

Událost remoteAudioStreamsUpdated se aktivuje, když se změní seznam vzdálených zvukových proudů. K těmto změnám dochází, když vzdálení účastníci do hovoru přidají nebo odeberou zvukové streamy.

Jak může vaše aplikace reagovat na událost?

Pokud se stream zpracovával a je odebraný, mělo by se zpracování zastavit. Na druhou stranu, pokud je přidán stream, pak je příjem událostí dobrým místem pro zahájení zpracování nového zvukového streamu.

Akce: totalParticipantCountChanged

Aktivuje se totalParticipantCountChanged , když se v hovoru změnil počet totalParticipant.

Jak může vaše aplikace reagovat na událost?

Pokud aplikace zobrazuje čítač účastníka, může aplikace aktualizovat čítač účastníka při přijetí události.

Ukázka kódu:

call.on('totalParticipantCountChanged', () => {
    participantCounterElement.innerText = call.totalParticipantCount;
});

Akce: roleChanged

Účastník roleChanged se aktivuje, když se v hovoru změní role localParticipant. Příkladem může být, když se místní účastník stane prezentujícím ACSCallParticipantRolePresenter v hovoru.

Jak může vaše aplikace reagovat na událost? Aplikace by měla na základě nové role uživatele povolit nebo zakázat tlačítko.

Ukázka kódu:

call.on('roleChanged', () => {
    this.roleElement = call.role;
});

Akce: mutedByOthers

Událost mutedByOthers nastane, když místní účastník ztlumí ostatní účastníky hovoru.

Jak může vaše aplikace reagovat na událost? Aplikace by měla uživateli zobrazit zprávu s oznámením, že byla ztlumený.

Ukázka kódu:

call.on('mutedByOthers', () => {
    messageBanner.innerText = "You have been muted by other participant in this call";
});

Události objektu RemoteParticipant

Akce: roleChanged

Událost roleChanged se aktivuje, když se RemotePartipant role změní ve volání. Příkladem může být, když se RemoteParticipant stane prezentujícím ACSCallParticipantRolePresenter ve volání.

Jak může vaše aplikace reagovat na událost? Aplikace by měla aktualizovat své uživatelské rozhraní na RemoteParticipant základě nové role.

Ukázka kódu:

remoteParticipant.on('roleChanged', () => {
    updateRole(remoteParticipant);
});

Akce: isMutedChanged

Událost isMutedChanged se aktivuje, když některý z RemoteParticipant nich ztlumí nebo zruší ztlumení mikrofonu.

Jak může vaše aplikace reagovat na událost?

Vaše aplikace může zobrazit ikonu v blízkosti zobrazení, které zobrazuje účastníka.

Ukázka kódu:

remoteParticipant.on('isMutedChanged', () => {
    updateMuteStatus(remoteParticipant); // Update the UI based on the mute state of the participant
});

Akce: displayNameChanged

Při displayNameChanged aktualizaci názvu RemoteParticipant .

Jak může vaše aplikace reagovat na událost?

Pokud se aplikace zobrazí v uživatelském rozhraní, měla by aktualizovat jméno účastníka.

Ukázka kódu:

remoteParticipant.on('displayNameChanged', () => {
    remoteParticipant.nameLabel.innerText = remoteParticipant.displayName;
});

Akce: isSpeakingChanged

Když isSpeakingChanged se dominantní mluvčí v hovoru změní.

Jak může vaše aplikace reagovat na událost?

Uživatelské rozhraní aplikace by mělo dát přednost zobrazení RemotePartipant toho, kdo se stal dominantním mluvčím.

Ukázka kódu:

remoteParticipant.on('isSpeakingChanged', () => {
    showAsRemoteSpeaker(remoteParticipant) // Display a speaking icon near the participant
});

Akce: videoStreamsUpdated

Když videoStreamsUpdated vzdálený účastník přidá nebo odebere VideoStream do/z volání.

Jak může vaše aplikace reagovat na událost?

Pokud vaše aplikace zpracovávala stream, který se odebral. Vaše aplikace by měla zastavit zpracování. Po přidání nového datového proudu může vaše aplikace chtít vykreslit nebo zpracovat.

Ukázka kódu:

remoteParticipant.on('videoStreamsUpdated', (videoStreamsUpdatedEvent) => {

     videoStreamsUpdatedEvent.added.forEach(addedRemoteVideoStream => { 
       // Remove a renderer and start processing the stream if any processing is needed
        handleAddedRemoteVideoStream(addedRemoteVideoStream) 
    });

    videoStreamsUpdatedEvent.removed.forEach(removedRemoteVideoStream => {
        // Remove the renderer and stop processing the stream if any processing is ongoing
        this.handleRemovedRemoteVideoStream(removedRemoteVideoStream) 
    });
});

Událost objektu AudioEffectsFeature

Akce: effectsStarted

Tato událost nastane, když je vybraný zvukový efekt použit u zvukového streamu. Když například někdo zapne potlačení šumu, effectsStarted aktivuje se.

Jak může vaše aplikace reagovat na událost?

Aplikace může zobrazit nebo povolit tlačítko, které uživateli umožní zakázat zvukový efekt.

Ukázka kódu:

audioEffectsFeature.on('effectsStarted', (effects) => {
    stopEffectButton.style.visibility = "visible"; 
});

Akce: effectsStopped

Tato událost nastane, když je vybraný zvukový efekt použit u zvukového streamu. Když například někdo vypne potlačení šumu, effectsStopped aktivuje se.

Jak může vaše aplikace reagovat na událost?

Aplikace může zobrazit nebo povolit tlačítko, které uživateli umožní povolit zvukový efekt.

Ukázka kódu:

audioEffectsFeature.on('effectsStopped', (effects) => {
    startEffectButton.style.visibility = "visible"; 
});

Akce: effectsError

K této události dochází, když dojde k chybě při spuštění nebo použití zvukového efektu.

Jak může vaše aplikace reagovat na událost?

Aplikace by měla zobrazit upozornění nebo chybovou zprávu, že zvukový efekt nefunguje podle očekávání.

Ukázka kódu:

audioEffectsFeature.on('effectsError', (error) => {
    console.log(`Error with the audio effect ${error}`);
    alert(`Error with the audio effect`);
});

Nainstalujte sadu SDK .

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

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

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

Potom do souboru build.gradle na úrovni 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 createCallAgentCallClient 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();

S naší sadou Android SDK se můžete přihlásit k odběru většiny vlastností a kolekcí, které budou při změně hodnot upozorněny.

Vlastnosti

Přihlášení k odběru property changed událostí:

// subscribe
PropertyChangedListener callStateChangeListener = new PropertyChangedListener()
{
    @Override
    public void onPropertyChanged(PropertyChangedEvent args)
    {
        Log.d("The call state has changed.");
    }
}
call.addOnStateChangedListener(callStateChangeListener);

//unsubscribe
call.removeOnStateChangedListener(callStateChangeListener);

Pokud používáte naslouchací procesy událostí definované ve stejné třídě, vytvořte vazbu naslouchací proces na proměnnou. Předejte proměnnou jako argument pro přidání a odebrání metod naslouchacího procesu.

Pokud se pokusíte předat naslouchací proces přímo jako argument, ztratíte odkaz na tento naslouchací proces. Java vytváří nové instance těchto naslouchacích procesů a neodkazuje na dříve vytvořené instance. Pořád se vyhodí správně, ale nejde je odebrat, protože už na ně nebudete mít odkaz.

Kolekce

Přihlášení k odběru collection updated událostí:

LocalVideoStreamsChangedListener localVideoStreamsChangedListener = new LocalVideoStreamsChangedListener()
{
    @Override
    public void onLocalVideoStreamsUpdated(LocalVideoStreamsEvent localVideoStreamsEventArgs) {
        Log.d(localVideoStreamsEventArgs.getAddedStreams().size());
        Log.d(localVideoStreamsEventArgs.getRemovedStreams().size());
    }
}
call.addOnLocalVideoStreamsChangedListener(localVideoStreamsChangedListener);
// To unsubscribe
call.removeOnLocalVideoStreamsChangedListener(localVideoStreamsChangedListener);

Nastavení systému

Vytvoření projektu Xcode

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

Během tohoto rychlého startu 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. Přidruženou hodnotu nastavíte na řetězec, který bude zahrnutý v dialogovém okně, 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 ContentView.swift projektu. import Přidejte deklaraci do horní části souboru pro import AzureCommunicationCalling knihovny. Kromě toho import AVFoundation. Budete ho potřebovat 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")
        }
})

S naší sadou SDK pro iOS se můžete přihlásit k odběru většiny vlastností a kolekcí, které budou při změně hodnot upozorněny.

Vlastnosti

Pokud se chcete přihlásit k odběru property changed událostí, použijte následující kód.

call.delegate = self
// Get the property of the call state by getting on the call's state member
public func call(_ call: Call, didChangeState args: PropertyChangedEventArgs) {
{
    print("Callback from SDK when the call state changes, current state: " + call.state.rawValue)
}

// to unsubscribe
self.call.delegate = nil

Kolekce

Pokud se chcete přihlásit k odběru collection updated událostí, použijte následující kód.

call.delegate = self
// Collection contains the streams that were added or removed only
public func call(_ call: Call, didUpdateLocalVideoStreams args: LocalVideoStreamsUpdatedEventArgs) {
{
    print(args.addedStreams.count)
    print(args.removedStreams.count)
}
// to unsubscribe
self.call.delegate = nil

Další kroky