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 :

Pour les développeurs

Votre application Web doit :

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 :

Étape 2 : Utiliser les API WebRTC standard

Après l'appeloverrideWebRTC(), utilisez les API WebRTC normalement. Le proxy les redirige de manière transparente vers le client 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 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.

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 :

Bonnes pratiques

Suivez ces recommandations lors de l'intégration à la redirection WebRTC :

Résolution des problèmes

Redirection non détectée

L'audio ou la vidéo ne fonctionne pas

Problèmes de reconnexion

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<string, Function>;
}

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