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:
+ A WorkSpace utilizando el protocolo DCV. Para obtener más información, consulte [Protocolos para WorkSpaces uso personal](amazon-workspaces-networking.md#amazon-workspaces-protocols).
**nota**
Actualmente, la redirección WebRTC en el lado del servidor solo se admite en Windows. WorkSpaces
+ [Un WorkSpaces cliente compatible de clients.amazonworkspaces.com.](https://clients.amazonworkspaces.com) Plataformas compatibles: Windows, macOS, Linux (Ubuntu 22.04 y Ubuntu 24.04, amd64) y Web.
+ La redirección WebRTC está habilitada mediante una política de grupo. Cuando está habilitada, la política instala automáticamente la extensión del navegador en Chrome y Edge a través del registro. Para obtener más información, consulte [Administre su Windows WorkSpaces en WorkSpaces Personal](group_policy.md). Si es necesario, los usuarios pueden instalar la extensión manualmente: [Chrome](https://chromewebstore.google.com/detail/amazon-dcv-webrtc-redirec/diilpfplcnhehakckkpmcmibmhbingnd) y [Edge](https://microsoftedge.microsoft.com/addons/detail/amazon-dcv-webrtc-redirec/kjbbkjjiecchbcdoollhgffghfjnbhef).
### Para desarrolladores
Su aplicación web debe:
+ Utilice las API WebRTC estándar (como get y) UserMedia RTCPeerConnection
+ Incluya el código de detección e inicialización como se describe en este tema
## 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:
+ Compruebe si se detecta `globalThis.DCVWebRTCPeerConnectionProxyV2` la extensión
+ Llame `setInitCallback()` a su controlador y se recomienda un tiempo de espera de 5000 ms
+ La llamada de retorno recibe un objeto de resultado con un valor `success` booleano y una o `proxy` `error`
+ Llamada `proxy.overrideWebRTC()` para redirigir las API WebRTC estándar
### Paso 2: Utilice las API WebRTC estándar
Después de llamar`overrideWebRTC()`, utilice las API de WebRTC con normalidad. El proxy las redirige de forma transparente al cliente local.
**nota**
Actualmente, no se admite la redirección de vídeo. Configure `video: false` las `getUserMedia` solicitudes.
```
// 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 en`proxy.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.
**importante**
Tras la reconexión, todos los objetos proxy creados anteriormente dejan de ser válidos porque el contexto del navegador del cliente se vuelve a cargar por completo. Debe cerrar las conexiones existentes y crear nuevos objetos WebRTC.
```
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:
1. Cree un protocolo DCV que WorkSpace utilice y habilite la configuración de política de grupo de redirección WebRTC. Consulte [Administre su Windows WorkSpaces en WorkSpaces Personal](group_policy.md).
1. Descargue e instale un WorkSpaces cliente desde [clients.amazonworkspaces.com](https://clients.amazonworkspaces.com) y conéctese al. WorkSpace Comprueba que la extensión Chrome o Edge esté instalada (automática cuando se establece el GPO).
1. Abre la aplicación web en el WorkSpace navegador. Busque en la consola el mensaje «Redireccionamiento WebRTC activado». Compruebe el funcionamiento del audio con los dispositivos locales, pruebe la enumeración y la conmutación de los dispositivos y compruebe la gestión de la reconexión.
## Prácticas recomendadas
Siga estas recomendaciones al realizar la integración con la redirección WebRTC:
+ Compruebe siempre la disponibilidad de la redirección; nunca dé por sentado que el proxy existe
+ Llame con `overrideWebRTC()` antelación, antes de crear cualquier objeto WebRTC
+ Mapee los elementos de audio antes de usarlos; llame `mapAudioElement()` antes de configurarlos `srcObject`
+ Controlar la reconexión: después de la reconexión, todos los objetos proxy no son válidos; cree siempre nuevos objetos WebRTC
+ Pruebe ambos modos: asegúrese de que su aplicación funcione correctamente con y sin redireccionamiento
+ Utilice las API WebRTC estándar: el proxy las redirige de forma transparente; no se necesitan API personalizadas para el uso básico
+ Limpie los recursos: elimine los detectores de eventos y cierre las conexiones cuando haya terminado
## Resolución de problemas
### No se detectó la redirección
+ Compruebe que la extensión del navegador esté instalada y habilitada (comprobar`chrome://extensions`)
+ Confirme que la política de grupo de redireccionamiento WebRTC esté habilitada en el WorkSpace
+ Compruebe que se está ejecutando dentro de un protocolo DCV WorkSpace
+ Compruebe si hay mensajes de inicialización en la consola del navegador
+ Compruebe que la versión del WorkSpaces cliente admite la redirección WebRTC (Windows 5.21.0 o posterior, macOS 5.31.0 o posterior, Linux 2026.0 o posterior, o cliente web)
### El audio o el vídeo no funcionan
+ Verifique `overrideWebRTC()` que se haya llamado antes de crear cualquier objeto WebRTC
+ Compruebe que los elementos de audio estén mapeados antes de realizar la configuración `mapAudioElement()` `srcObject`
+ Compruebe si hay errores en la consola del navegador
+ Compruebe que se concedan los permisos del dispositivo
### Problemas de reconexión
+ Implemente `addStatusChangeEventListener()` para detectar cambios de disponibilidad
+ Después de la reconexión, cree siempre MediaStream objetos nuevos RTCPeerConnection ; los proxies antiguos no son válidos y se eliminarán
+ Revise la configuración de Heartbeat si detecta una falta de disponibilidad demasiado lenta o demasiado rápido
## 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;
}
interface StatusChangeEvent {
status: 'available' | 'unavailable';
lastHeartbeat?: number;
}
```