Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Intégrez votre application Web à la redirection WebRTC
La redirection WebRTC permet aux applications Web exécutées au WorkSpaces sein de sessions d'utiliser des périphériques audio natifs côté client. Cette rubrique explique aux développeurs d'applications Web comment détecter l'environnement de redirection WebRTC et l'intégrer à celui-ci.
Lorsque la redirection WebRTC est activée sur un WorkSpace, l'extension de navigateur Amazon DCV WebRTC Redirection injecte un SDK proxy dans la page Web. Votre application peut détecter ce proxy et l'utiliser pour rediriger les appels d'API WebRTC standard, y compris UserMedia get RTCPeerConnection et, vers les appareils locaux de l'utilisateur plutôt que vers les appareils virtuels de la WorkSpace télécommande. Cela permet d'obtenir des performances nettement meilleures et une latence plus faible par rapport au streaming multimédia via le protocole d'affichage DCV.
Votre application doit gérer les deux cas : lorsqu'elle s'exécute dans un navigateur WorkSpace avec la redirection WebRTC activée, et lorsqu'elle s'exécute dans un navigateur standard sans cette redirection. Le proxy est facultatif. S'il n'est pas présent, votre application peut revenir au WebRTC standard.
## Conditions préalables
### Pour les utilisateurs finaux
Les utilisateurs finaux ont besoin des éléments suivants :
+ A WorkSpace utilisant le protocole DCV. Pour de plus amples informations, veuillez consulter [Protocoles pour le WorkSpaces personnel](amazon-workspaces-networking.md#amazon-workspaces-protocols).
**Note**
La redirection WebRTC côté serveur n'est actuellement prise en charge que sous Windows. WorkSpaces
+ Un WorkSpaces client pris en charge par [clients.amazonworkspaces.com](https://clients.amazonworkspaces.com). Plateformes prises en charge : Windows, macOS, Linux (Ubuntu 22.04 et Ubuntu 24.04, amd64) et Web.
+ Redirection WebRTC activée via la stratégie de groupe. Lorsqu'elle est activée, la politique installe automatiquement l'extension de navigateur sur Chrome et Edge via le registre. Pour de plus amples informations, veuillez consulter [Gérez votre Windows WorkSpaces dans WorkSpaces Personal](group_policy.md). Si nécessaire, les utilisateurs peuvent installer l'extension manuellement : [Chrome](https://chromewebstore.google.com/detail/amazon-dcv-webrtc-redirec/diilpfplcnhehakckkpmcmibmhbingnd) et [Edge](https://microsoftedge.microsoft.com/addons/detail/amazon-dcv-webrtc-redirec/kjbbkjjiecchbcdoollhgffghfjnbhef).
### Pour les développeurs
Votre application Web doit :
+ Utilisez des API WebRTC standard (telles que get et) UserMedia RTCPeerConnection
+ Incluez le code de détection et d'initialisation comme décrit dans cette rubrique
## Comment intégrer
L'intégration comporte quatre étapes : détecter l'environnement de redirection, remplacer les API WebRTC, mapper les éléments audio et gérer la reconnexion.
### Étape 1 : détecter l'environnement de redirection
Ajoutez ce code d'initialisation à votre application. Le rappel s'exécute lorsque le proxy est prêt ou après le délai d'expiration si la redirection n'est pas 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);
}
```
Points clés :
+ Vérifiez `globalThis.DCVWebRTCPeerConnectionProxyV2` pour détecter l'extension
+ Appelez `setInitCallback()` votre gestionnaire et un délai d'attente de 5 000 ms est recommandé
+ Le rappel reçoit un objet de résultat avec un `success` booléen et soit `proxy` `error`
+ Appel `proxy.overrideWebRTC()` pour rediriger les API WebRTC standard
### Étape 2 : Utiliser les API WebRTC standard
Après l'appel`overrideWebRTC()`, utilisez les API WebRTC normalement. Le proxy les redirige de manière transparente vers le client local.
**Note**
La redirection vidéo n'est pas prise en charge actuellement. Définissez `video: false` des `getUserMedia` demandes.
```
// 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 vous devez accéder aux API du navigateur d'origine (par exemple, pour capturer des vidéos depuis le navigateur distant plutôt que depuis le client local), elles sont conservées dans `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
});
```
### Étape 3 : cartographier les éléments audio
Pour la lecture audio, appelez `mapAudioElement()` avant `srcObject` de régler un élément 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);
```
### Étape 4 : Gérer la reconnexion
Le service de redirection peut devenir temporairement indisponible, par exemple en raison de problèmes réseau ou de reconnexion du client.
**Important**
Après la reconnexion, tous les objets proxy créés précédemment deviennent invalides car le contexte du navigateur client est complètement rechargé. Vous devez fermer les connexions existantes et créer de nouveaux objets 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
}
```
Vous pouvez personnaliser le rythme cardiaque :
```
proxy.resetHeartbeat({
heartbeatTimeoutMs: 5000, // Time before marking unavailable
heartbeatIntervalPeriodMs: 500 // How often to check
});
```
## Énumération des appareils
Les modifications apportées à l'appareil, par exemple le branchement d'un casque par un utilisateur, sont automatiquement détectées. `makeMediaDevicesProxy()`À utiliser pour écouter les modifications apportées à l'appareil sur le client local :
```
const mediaDevices = proxy.makeMediaDevicesProxy();
mediaDevices.ondevicechange = async () => {
const devices = await navigator.mediaDevices.enumerateDevices();
updateDeviceList(devices);
};
```
`proxy.clientInfo`À utiliser pour déterminer la plate-forme client à partir de laquelle l'utilisateur se connecte :
```
// 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;
}
```
## Avancé : traitement audio avec l'API Web Audio
Vous pouvez utiliser l'API Web Audio pour traiter les flux audio avant de les envoyer via une connexion homologue :
```
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);
```
## Exemple complet
L'exemple suivant illustre une intégration complète avec l'initialisation, la gestion des reconnexions, la détection des changements d'appareil et la configuration des appels :
```
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();
```
## Tester votre intégration
### Sans redirection
Votre application fonctionne normalement lorsque l'extension n'est pas installée, lorsqu'elle est exécutée en dehors d'un WorkSpace ou lorsque la redirection WebRTC n'est pas activée via la stratégie de groupe. Testez en ouvrant votre application dans un navigateur classique.
### Avec redirection
Pour effectuer un test avec la redirection activée, procédez comme suit :
1. Créez un WorkSpace protocole DCV et activez le paramètre de stratégie de groupe de redirection WebRTC. Consultez [Gérez votre Windows WorkSpaces dans WorkSpaces Personal](group_policy.md).
1. Téléchargez et installez un WorkSpaces client depuis [clients.amazonworkspaces.com](https://clients.amazonworkspaces.com) et connectez-vous au. WorkSpace Vérifiez que l'extension Chrome ou Edge est installée (automatique lorsque le GPO est défini).
1. Ouvrez votre application Web dans le WorkSpace navigateur. Vérifiez la présence du message « Redirection WebRTC activée » sur la console. Vérifiez la fonctionnalité audio avec les appareils locaux, testez l'énumération et la commutation des appareils, et vérifiez la gestion des reconnexions.
## Bonnes pratiques
Suivez ces recommandations lors de l'intégration à la redirection WebRTC :
+ Vérifiez toujours la disponibilité de la redirection, ne supposez jamais que le proxy existe
+ Appelez `overrideWebRTC()` tôt, avant de créer un objet WebRTC
+ Mappez les éléments audio avant utilisation - appelez `mapAudioElement()` avant le réglage `srcObject`
+ Gérer la reconnexion : après la reconnexion, tous les objets proxy ne sont pas valides ; créez toujours de nouveaux objets WebRTC
+ Testez les deux modes : assurez-vous que votre application fonctionne correctement avec et sans redirection
+ Utilisez des API WebRTC standard : le proxy les redirige de manière transparente ; aucune API personnalisée n'est nécessaire pour une utilisation de base
+ Nettoyez les ressources : supprimez les auditeurs d'événements et fermez les connexions lorsque vous avez terminé
## Résolution des problèmes
### Redirection non détectée
+ Vérifiez que l'extension de navigateur est installée et activée (vérifier`chrome://extensions`)
+ Vérifiez que la stratégie de groupe de redirection WebRTC est activée sur le WorkSpace
+ Vérifiez que vous WorkSpace utilisez un protocole DCV
+ Vérifiez la présence de messages d'initialisation dans la console du navigateur
+ Vérifiez que la version du WorkSpaces client prend en charge la redirection WebRTC (Windows 5.21.0 ou version ultérieure, macOS 5.31.0 ou version ultérieure, Linux 2026.0 ou version ultérieure, ou client Web)
### L'audio ou la vidéo ne fonctionne pas
+ Verify `overrideWebRTC()` a été appelé avant de créer un objet WebRTC
+ Vérifiez que les éléments audio sont mappés `mapAudioElement()` avant le réglage `srcObject`
+ Vérifiez la présence d'erreurs dans la console du navigateur
+ Vérifiez que les autorisations de l'appareil sont accordées
### Problèmes de reconnexion
+ Mettre en œuvre `addStatusChangeEventListener()` pour détecter les changements de disponibilité
+ Après la reconnexion, créez toujours de nouveaux RTCPeerConnection MediaStream objets. Les anciens proxys ne sont pas valides et seront lancés
+ Vérifiez la configuration du rythme cardiaque si l'indisponibilité est détectée trop lentement ou trop rapidement
## Référence des API
Voici un résumé de l'API 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;
}
```