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 WebRTC

La redirección WebRTC permite que las aplicaciones web que se ejecutan WorkSpaces dentro de las 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 redirección WebRTC e integrarlo en él.

Cuando la redirección WebRTC está habilitada en un WorkSpace, la extensión del 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 UserMedia get RTCPeerConnection y, a los dispositivos locales del usuario en lugar de a los dispositivos virtuales del WorkSpace control remoto. 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.

Su aplicación debe gestionar ambos casos: cuando se ejecuta dentro de 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, su aplicación puede recurrir 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 redireccionamiento, anular las API de WebRTC, mapear los elementos de audio y gestionar la reconexión.

Paso 1: Detectar el entorno de redireccionamiento

Agregue este código de inicialización a su aplicación. La devolución de llamada se ejecuta cuando el proxy está listo o después del 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 necesita acceder a las API originales del navegador (por ejemplo, para capturar vídeo desde el navegador remoto en lugar del 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: Mapea los elementos de audio

Para la reproducción de audio, llame mapAudioElement() antes srcObject de configurar 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: Gestionar la reconexión

El servicio de redireccionamiento 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 del corazón:

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 se conecta un auricular) se detectan automáticamente. Se utiliza makeMediaDevicesProxy() para escuchar los cambios del dispositivo en el cliente local:

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

Se utiliza proxy.clientInfo 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

Puede utilizar la API de audio web 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 muestra una integración completa con la inicialización, la gestión de la reconexión, la detección de cambios de dispositivo y la configuración de las 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 tu integración

Sin redireccionamiento

La aplicación funciona normalmente cuando la extensión no está instalada, cuando se ejecuta fuera de una WorkSpace o cuando la redirección WebRTC no está habilitada mediante una política de grupo. Pruébelo abriendo 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 WebRTC:

Resolución de problemas

No se detectó 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;
}