Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Integre su aplicación web con la redirección de WebRTC

La redirección de WebRTC permite que las aplicaciones web que se ejecutan dentro de las WorkSpaces sesiones utilicen dispositivos de audio nativos del lado del cliente. En este tema se muestra a los desarrolladores de aplicaciones web cómo detectar el entorno de redireccionamiento de WebRTC e integrarlo en él.

Cuando el redireccionamiento WebRTC está habilitado en un navegador WorkSpace, la extensión de navegador Amazon DCV WebRTC Redirection inyecta un SDK de proxy en la página web. Su aplicación puede detectar este proxy y usarlo para redirigir las llamadas a la API WebRTC estándar (incluidas las llamadas get UserMedia y) a los dispositivos locales del usuario, en lugar de a los RTCPeerConnection dispositivos virtuales del control remoto. WorkSpace Esto proporciona un rendimiento significativamente mejor y una latencia más baja en comparación con la transmisión de contenido multimedia a través del protocolo de visualización DCV.

La aplicación debe gestionar ambos casos: cuando se ejecuta en un navegador WorkSpace con la redirección WebRTC habilitada y cuando se ejecuta en un navegador estándar sin ella. El proxy es opcional; si no está presente, la aplicación puede volver al WebRTC estándar.

Requisitos previos

Para usuarios finales

Los usuarios finales necesitan lo siguiente:

Para desarrolladores

Su aplicación web debe:

Cómo realizar la integración

La integración consta de cuatro pasos: detectar el entorno de redirección, anular las API de WebRTC, asignar los elementos de audio y gestionar la reconexión.

Paso 1: Detectar el entorno de redirección

Agregue este código de inicialización a su aplicación. La devolución de llamada se ejecuta cuando el proxy está listo o cuando se agota el tiempo de espera si la redirección no está disponible.

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

Puntos clave:

Paso 2: Utilice las API WebRTC estándar

Después de llamaroverrideWebRTC(), utilice las API de WebRTC con normalidad. El proxy las redirige de forma transparente al cliente local.

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

Si necesitas acceder a las API del navegador originales (por ejemplo, para capturar vídeo desde el navegador remoto en lugar de hacerlo desde el cliente local), se conservan enproxy.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
});
            

Paso 3: mapear los elementos de audio

Para reproducir audio, llama mapAudioElement() antes de configurar srcObject cualquier elemento de audio.

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

Paso 4: Gestiona la reconexión

El servicio de redirección puede dejar de estar disponible temporalmente, por ejemplo, debido a problemas de red o a la reconexión del cliente.

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
}
            

Puede personalizar la frecuencia de los latidos:

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

Enumeración de dispositivos

Los cambios en el dispositivo (por ejemplo, cuando un usuario conecta unos auriculares) se detectan automáticamente. makeMediaDevicesProxy()Utilícelo para detectar los cambios del dispositivo en el cliente local:

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

proxy.clientInfoUtilícelo para determinar desde qué plataforma de cliente se conecta el usuario:

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

Avanzado: procesamiento de audio con la API de audio web

Puedes usar la API de Web Audio para procesar las transmisiones de audio antes de enviarlas a través de una conexión entre pares:

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

Ejemplo completo

El siguiente ejemplo demuestra una integración completa con la inicialización, la gestión de la reconexión, la detección de cambios en el dispositivo y la configuración de llamadas:

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

Probando su integración

Sin redirección

La aplicación funciona normalmente cuando la extensión no está instalada, cuando se ejecuta fuera de una WorkSpace o cuando la redirección de WebRTC no está habilitada mediante la política de grupo. Para probarlo, abre la aplicación en un navegador normal.

Con redirección

Para realizar una prueba con la redirección habilitada:

Prácticas recomendadas

Siga estas recomendaciones al realizar la integración con la redirección de WebRTC:

Resolución de problemas

No se ha detectado la redirección

El audio o el vídeo no funcionan

Problemas de reconexión

Referencia de la API

A continuación se resume la API de proxy:

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