Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Integrieren Sie Ihre Webanwendung mit der WebRTC-Umleitung

Die WebRTC-Umleitung ermöglicht es Webanwendungen, die innerhalb von WorkSpaces Sitzungen ausgeführt werden, native clientseitige Audiogeräte zu verwenden. Dieses Thema zeigt Entwicklern von Webanwendungen, wie sie die WebRTC-Umleitungsumgebung erkennen und in sie integrieren können.

Wenn die WebRTC-Umleitung auf einem aktiviert ist WorkSpace, fügt die Amazon DCV WebRTC-Redirection-Browsererweiterung ein Proxy-SDK in die Webseite ein. Ihre Anwendung kann diesen Proxy erkennen und ihn verwenden, um standardmäßige WebRTC-API-Aufrufe — einschließlich get UserMedia und RTCPeerConnection — an die lokalen Geräte des Benutzers und nicht an die virtuellen Geräte der Fernbedienung umzuleiten. WorkSpace Dies bietet eine deutlich bessere Leistung und eine geringere Latenz als beim Streamen von Medien über das DCV-Anzeigeprotokoll.

Ihre Anwendung muss beide Fälle behandeln: wenn sie in einem WorkSpace mit aktivierter WebRTC-Umleitung ausgeführt wird, und wenn sie in einem Standardbrowser ohne sie ausgeführt wird. Der Proxy ist optional — wenn er nicht vorhanden ist, kann Ihre Anwendung auf Standard-WebRTC zurückgreifen.

Voraussetzungen

Für Endanwender

Endbenutzer benötigen Folgendes:

Für Entwickler

Ihre Webanwendung muss:

Wie integriere ich

Die Integration umfasst vier Schritte: Erkennen der Umleitungsumgebung, Überschreiben der WebRTC-APIs, Zuordnen von Audioelementen und Bearbeitung der Wiederverbindung.

Schritt 1: Ermitteln Sie die Umleitungsumgebung

Fügen Sie diesen Initialisierungscode zu Ihrer Anwendung hinzu. Der Callback wird ausgeführt, wenn der Proxy bereit ist, oder nach Ablauf des Timeouts, wenn die Umleitung nicht verfügbar ist.

let proxy = null;

function handleInitCallback(result) {
    if (result.success) {
        // Redirection is available
        proxy = result.proxy;
        console.log('WebRTC redirection enabled, version:', proxy.getVersion());
        console.log('Client info:', proxy.clientInfo);

        // Override WebRTC APIs to use redirection
        proxy.overrideWebRTC();

        // Set up reconnection handling
        setupReconnectionHandling();
    } else {
        // Not in a redirection environment  - use standard WebRTC
        console.log('WebRTC redirection not available:', result.error);
    }
}

// Register the initialization callback
if (globalThis.DCVWebRTCPeerConnectionProxyV2) {
    globalThis.DCVWebRTCPeerConnectionProxyV2.setInitCallback(handleInitCallback, 5000);
}
            

Die wichtigsten Punkte:

Schritt 2: Verwenden Sie Standard-WebRTC-APIs

Verwenden Sie nach dem Aufruf overrideWebRTC() die WebRTC-APIs normal. Der Proxy leitet sie transparent an den lokalen Client weiter.

// Get user media  - automatically redirected
const stream = await navigator.mediaDevices.getUserMedia({
    audio: true,
    video: false   // Video redirection not yet supported
});

// Create peer connection  - automatically redirected
const pc = new RTCPeerConnection(configuration);

// Everything else works as standard WebRTC
pc.addTrack(stream.getAudioTracks()[0], stream);
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
            

Wenn Sie auf die ursprünglichen Browser-APIs zugreifen müssen (z. B. um Videos über den Remote-Browser statt über den lokalen Client aufzunehmen), werden diese gespeichert inproxy.overridenApis:

// Get the original getUserMedia (runs in remote browser, not redirected)
const originalGetUserMedia = proxy.overridenApis.get('navigator.mediaDevices.getUserMedia');

// Available original APIs:
// 'navigator.mediaDevices.getUserMedia'
// 'navigator.mediaDevices.addEventListener'
// 'navigator.mediaDevices.removeEventListener'
// 'navigator.mediaDevices.enumerateDevices'
// 'navigator.mediaDevices.getDisplayMedia'
// 'window.RTCPeerConnection'
// 'window.RTCPeerConnection.generateCertificate'
// 'window.AudioContext'
// 'window.Worker' (experimental)

const remoteStream = await originalGetUserMedia.call(navigator.mediaDevices, {
    audio: false,
    video: true
});
            

Schritt 3: Ordnen Sie Audioelemente zu

Rufen Sie für die Audiowiedergabe srcObject auf, mapAudioElement() bevor Sie ein Audioelement einstellen.

const audioElement = document.querySelector('audio#remote-audio');

// Map the audio element before setting srcObject
proxy.mapAudioElement(audioElement);

// Now use the audio element normally
audioElement.srcObject = remoteStream;
await audioElement.play();

// Control playback
audioElement.pause();
audioElement.volume = 0.8;
audioElement.muted = false;

// Change output device
await audioElement.setSinkId(deviceId);
            

Schritt 4: Führen Sie die Wiederverbindung durch

Der Umleitungsdienst kann vorübergehend nicht verfügbar sein, z. B. aufgrund von Netzwerkproblemen oder der Wiederverbindung von Clients.

function setupReconnectionHandling() {
    proxy.addStatusChangeEventListener((event) => {
        switch (event.status) {
            case 'unavailable':
                console.error('Redirection lost');
                handleRedirectionLost();
                break;
            case 'available':
                console.info('Redirection restored');
                handleRedirectionRestored();
                break;
        }
    });
}

function handleRedirectionLost() {
    // Try to close cleanly  - proxies may throw exceptions after reconnection
    try {
        if (peerConnection) { peerConnection.close(); }
    } catch (error) {
        console.warn('Error closing peer connection (proxy may be invalid):', error);
    }
    showReconnectingMessage();
}

function handleRedirectionRestored() {
    // IMPORTANT: All existing proxy objects are invalid after reconnection.
    // Create new RTCPeerConnection, MediaStream, and other WebRTC objects.
    hideReconnectingMessage();
    restartCall(); // Must create fresh WebRTC objects
}
            

Sie können das Heartbeat-Timing anpassen:

proxy.resetHeartbeat({
    heartbeatTimeoutMs: 5000,      // Time before marking unavailable
    heartbeatIntervalPeriodMs: 500 // How often to check
});
            

Aufzählung der Geräte

Geräteänderungen, z. B. wenn ein Benutzer ein Headset anschließt, werden automatisch erkannt. Wird verwendetmakeMediaDevicesProxy(), um auf dem lokalen Client auf Geräteänderungen zu achten:

const mediaDevices = proxy.makeMediaDevicesProxy();
mediaDevices.ondevicechange = async () => {
    const devices = await navigator.mediaDevices.enumerateDevices();
    updateDeviceList(devices);
};
        

Wird verwendetproxy.clientInfo, um zu ermitteln, von welcher Client-Plattform aus der Benutzer eine Verbindung herstellt:

// clientInfo contains:
// - platform: 'web' | 'windows' | 'macOS' | 'linux'
// - version: SDK version string
// - userAgent: browser user agent string
// - browserDetails: { browser: string, version: string }

switch (proxy.clientInfo.platform) {
    case 'web':     console.log('Connecting from web client'); break;
    case 'windows': console.log('Connecting from Windows native client'); break;
    case 'macOS':   console.log('Connecting from macOS native client'); break;
    case 'linux':   console.log('Connecting from Linux native client'); break;
}
        

Fortgeschritten: Audioverarbeitung mit Web Audio API

Sie können die Web Audio API verwenden, um Audiostreams zu verarbeiten, bevor Sie sie über eine Peer-Verbindung senden:

const audioContext = new AudioContext();
const source = audioContext.createMediaStreamSource(micStream);
const gainNode = audioContext.createGain();
const destination = audioContext.createMediaStreamDestination();

source.connect(gainNode);
gainNode.connect(destination);

// Control microphone volume
gainNode.gain.value = 0.5; // 50% volume

// Use the processed stream
pc.addTrack(destination.stream.getAudioTracks()[0], destination.stream);
        

Vollständiges Beispiel

Das folgende Beispiel zeigt eine vollständige Integration mit Initialisierung, Wiederherstellung der Verbindung, Erkennung von Geräteänderungen und Einrichtung von Anrufen:

let proxy = null;
let peerConnection = null;
let localStream = null;

function initializeRedirection() {
    if (globalThis.DCVWebRTCPeerConnectionProxyV2) {
        globalThis.DCVWebRTCPeerConnectionProxyV2.setInitCallback((result) => {
            if (result.success) {
                proxy = result.proxy;
                proxy.overrideWebRTC();
                proxy.addStatusChangeEventListener(handleStatusChange);
                proxy.resetHeartbeat({ heartbeatTimeoutMs: 5000, heartbeatIntervalPeriodMs: 500 });
                setupDeviceChangeListener();
            } else {
                console.log('Redirection not available:', result.error);
            }
        }, 5000);
    }
}

function handleStatusChange(event) {
    if (event.status === 'unavailable') {
        try {
            if (peerConnection) { peerConnection.close(); peerConnection = null; }
            if (localStream) { localStream.getTracks().forEach(t => t.stop()); localStream = null; }
        } catch (error) {
            console.warn('Error cleaning up (proxies invalid):', error);
            peerConnection = null;
            localStream = null;
        }
    } else if (event.status === 'available') {
        startCall(); // Create fresh WebRTC objects
    }
}

function setupDeviceChangeListener() {
    const mediaDevices = proxy.makeMediaDevicesProxy();
    mediaDevices.ondevicechange = async () => {
        const devices = await navigator.mediaDevices.enumerateDevices();
        updateDeviceUI(devices);
    };
}

async function startCall() {
    try {
        localStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
        peerConnection = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
        localStream.getTracks().forEach(track => peerConnection.addTrack(track, localStream));

        peerConnection.ontrack = (event) => {
            const remoteAudio = document.querySelector('audio#remote');
            if (proxy) { proxy.mapAudioElement(remoteAudio); }
            remoteAudio.srcObject = event.streams[0];
            remoteAudio.play();
        };

        peerConnection.onicecandidate = (event) => {
            if (event.candidate) { sendToSignalingServer({ type: 'ice-candidate', candidate: event.candidate }); }
        };

        const offer = await peerConnection.createOffer();
        await peerConnection.setLocalDescription(offer);
        sendToSignalingServer({ type: 'offer', sdp: offer });
    } catch (error) {
        console.error('Failed to start call:', error);
    }
}

initializeRedirection();
        

Testen Sie Ihre Integration

Ohne Umleitung

Ihre Anwendung funktioniert normal, wenn die Erweiterung nicht installiert ist, wenn sie außerhalb von ausgeführt wird oder wenn die WebRTC-Umleitung nicht über die Gruppenrichtlinie aktiviert ist. WorkSpace Testen Sie, indem Sie Ihre Anwendung in einem normalen Browser öffnen.

Mit Umleitung

Um mit aktivierter Umleitung zu testen:

Bewährte Methoden

Beachten Sie bei der Integration mit der WebRTC-Umleitung die folgenden Empfehlungen:

Fehlerbehebung

Die Umleitung wurde nicht erkannt

Audio oder Video funktionieren nicht

Probleme bei der Wiederverbindung

API-Referenz

Im Folgenden wird die Proxy-API zusammengefasst:

interface DCVWebRTCProxy {
    // Version and client info
    getVersion(): string;
    clientInfo: {
        platform: 'web' | 'windows' | 'macOS' | 'linux';
        version: string;
        userAgent: string;
        browserDetails: { browser: string; version: string; };
    };

    // Core methods
    overrideWebRTC(): void;
    mapAudioElement(element: HTMLAudioElement): void;

    // Device management
    makeMediaDevicesProxy(): MediaDevices;

    // Status monitoring
    addStatusChangeEventListener(callback: (event: StatusChangeEvent) => void): void;
    resetHeartbeat(config: { heartbeatTimeoutMs: number, heartbeatIntervalPeriodMs: number }): void;

    // Access original (non-redirected) browser APIs
    overridenApis: Map<string, Function>;
}

interface StatusChangeEvent {
    status: 'available' | 'unavailable';
    lastHeartbeat?: number;
}