As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Integre seu aplicativo web com o redirecionamento WebRTC

O redirecionamento WebRTC permite que aplicativos web executados WorkSpaces dentro das sessões usem dispositivos de áudio nativos do lado do cliente. Este tópico mostra aos desenvolvedores de aplicativos Web como detectar o ambiente de redirecionamento WebRTC e integrá-lo a ele.

Quando o redirecionamento WebRTC está habilitado em um, WorkSpace a extensão de navegador Amazon DCV WebRTC Redirection injeta um SDK proxy na página da web. Seu aplicativo pode detectar esse proxy e usá-lo para redirecionar as chamadas padrão da API WebRTC, incluindo UserMedia get RTCPeerConnection and, para os dispositivos locais do usuário em vez dos dispositivos virtuais remotos. WorkSpace Isso fornece desempenho significativamente melhor e menor latência em comparação com streaming de mídia por meio do protocolo de exibição DCV.

Seu aplicativo deve lidar com os dois casos: quando executado dentro de um WorkSpace com o redirecionamento WebRTC ativado e quando executado em um navegador padrão sem ele. O proxy é opcional - se não estiver presente, seu aplicativo pode voltar para o WebRTC padrão.

Pré-requisitos

Para usuários finais

Os usuários finais precisam do seguinte:

Para desenvolvedores

Seu aplicativo web deve:

Como integrar

A integração envolve quatro etapas: detectar o ambiente de redirecionamento, substituir as APIs do WebRTC, mapear elementos de áudio e lidar com a reconexão.

Etapa 1: Detectar o ambiente de redirecionamento

Adicione esse código de inicialização ao seu aplicativo. O retorno de chamada é executado quando o proxy está pronto ou após o tempo limite, se o redirecionamento não estiver disponível.

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

Principais pontos:

Etapa 2: usar APIs WebRTC padrão

Depois de ligaroverrideWebRTC(), use as APIs WebRTC normalmente. O proxy os redireciona de forma transparente para o 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);
            

Se você precisar acessar as APIs originais do navegador (por exemplo, para capturar vídeo do navegador remoto em vez do cliente local), elas serão preservadas emproxy.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
});
            

Etapa 3: mapear elementos de áudio

Para reprodução de áudio, ligue mapAudioElement() antes de configurar srcObject qualquer elemento de áudio.

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

Etapa 4: lidar com a reconexão

O serviço de redirecionamento pode ficar temporariamente indisponível, por exemplo, devido a problemas de rede ou reconexão do 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
}
            

Você pode personalizar o tempo de pulsação:

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

Enumeração de dispositivos

Alterações no dispositivo — por exemplo, um usuário conectando um fone de ouvido — são detectadas automaticamente. Use makeMediaDevicesProxy() para ouvir as alterações do dispositivo no cliente local:

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

Use proxy.clientInfo para determinar de qual plataforma de cliente o usuário está se conectando:

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

Avançado: processamento de áudio com a API de áudio da Web

Você pode usar a API de áudio da Web para processar fluxos de áudio antes de enviá-los por meio de uma conexão de mesmo nível:

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

Exemplo completo

O exemplo a seguir demonstra uma integração completa com inicialização, tratamento de reconexão, detecção de alterações no dispositivo e configuração de chamadas:

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

Testando sua integração

Sem redirecionamento

Seu aplicativo funciona normalmente quando a extensão não está instalada, quando executada fora de uma WorkSpace ou quando o redirecionamento WebRTC não está habilitado por meio da Política de Grupo. Teste abrindo seu aplicativo em um navegador comum.

Com redirecionamento

Para testar com o redirecionamento ativado:

Práticas recomendadas

Siga estas recomendações ao fazer a integração com o redirecionamento WebRTC:

Solução de problemas

Redirecionamento não detectado

Áudio ou vídeo não funcionam

Problemas de reconexão

Referência de API

O seguinte resume a 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;
}