如何实现同域页面跳转时WebRTC音频Widget的连接持久化

Great question! When building an embedded widget that needs to keep an Agora WebRTC audio connection alive as users navigate between same-domain pages of a third-party site, there are several reliable approaches to avoid re-establishing the connection on every page load. Let’s break down the most practical solutions:

1. Use a Shared Worker (Most Recommended) #

Shared Workers run in a separate, persistent thread that’s shared across all same-origin pages. This makes them perfect for hosting your Agora client instance—since the worker doesn’t get destroyed when the user navigates away from a page, the audio connection stays intact.

How it works: #

• Initialize the Agora RTC client inside the Shared Worker instead of the main page context.
• Your widget’s frontend code (on each page) communicates with the worker using postMessage() to send commands (like joining a channel, muting audio) and receive updates (connection state, audio levels).
• When a user navigates to a new same-domain page, the new page connects to the existing Shared Worker and syncs with the active connection state immediately.

Example Code Snippets: #

Shared Worker File (agora-worker.js):

let agoraClient = null;
let isConnected = false;

// Handle connections from page contexts
self.onconnect = (e) => {
  const port = e.ports[0];
  port.start();

  port.onmessage = (msg) => {
    switch (msg.data.type) {
      case 'INIT_AGORA':
        if (!agoraClient) {
          initAgoraClient(msg.data.appId, msg.data.channel, port);
        } else if (isConnected) {
          // Sync existing connection state with the new page
          port.postMessage({ type: 'CONNECTION_STATUS', status: 'connected' });
        }
        break;
      case 'MUTE_AUDIO':
        agoraClient?.muteLocalAudioStream(msg.data.mute);
        break;
      // Add other commands (unmute, leave channel, etc.) as needed
    }
  };
};

function initAgoraClient(appId, channel, port) {
  // Initialize Agora client
  agoraClient = AgoraRTC.createClient({ mode: 'rtc', codec: 'opus' });
  
  // Set up event listeners to sync state with pages
  agoraClient.on('connection-state-change', (state) => {
    isConnected = state === 'CONNECTED';
    // Broadcast state to all connected pages
    self.clients.forEach(clientPort => {
      clientPort.postMessage({ type: 'CONNECTION_STATUS', status: state });
    });
  });

  // Join the channel (add your token logic here for production)
  agoraClient.join(appId, channel, null, null)
    .then(() => {
      port.postMessage({ type: 'CONNECTION_STATUS', status: 'connected' });
    })
    .catch(err => {
      port.postMessage({ type: 'ERROR', error: err.message });
    });
}

Widget Frontend Code (on each page):

// Connect to the Shared Worker
const agoraWorker = new SharedWorker('/path/to/agora-worker.js');
const workerPort = agoraWorker.port;
workerPort.start();

// Request initial connection state
workerPort.postMessage({ 
  type: 'INIT_AGORA', 
  appId: 'YOUR_AGORA_APP_ID', 
  channel: 'YOUR_CHANNEL_NAME' 
});

// Listen for updates from the worker
workerPort.onmessage = (msg) => {
  switch (msg.data.type) {
    case 'CONNECTION_STATUS':
      // Update your widget's UI based on connection state
      console.log('Connection state:', msg.data.status);
      break;
    case 'ERROR':
      console.error('Agora error:', msg.data.error);
      break;
  }
};

// Example: Mute audio button handler
document.getElementById('mute-btn').addEventListener('click', () => {
  workerPort.postMessage({ type: 'MUTE_AUDIO', mute: true });
});

Key Notes: #

• Browser Support: Shared Workers are supported in all modern browsers (Chrome, Firefox, Edge, Safari 16.4+).
• Agora SDK Compatibility: Ensure you’re using a recent version of the Agora Web SDK that supports running in a Worker context (most v4+ versions work).
• Security: The worker file must be hosted on the same origin as the third-party site (or use CORS if needed, though same-origin is simpler).

2. Service Worker (For Background Persistence) #

Service Workers act as a proxy between your pages and the network, and can run in the background even when no pages are open. While not designed specifically for shared state, they can be used to maintain an Agora connection across page navigations.

How it works: #

• Host the Agora client instance in the Service Worker.
• Use Client.postMessage() to communicate between the Service Worker and your widget’s frontend.
• Add heartbeat logic to prevent the browser from terminating the Service Worker (browsers may idle inactive workers to save resources).

Caveats: #

• Service Workers have stricter lifecycle rules—they can be terminated by the browser if idle for too long, so you’ll need to implement periodic ping/pong messages to keep them alive.
• Debugging Service Workers is more complex than Shared Workers.

3. Leverage SPA Architecture (If Host Site Supports It) #

If the third-party site is a Single-Page Application (SPA) that uses client-side routing (no full page reloads), your widget can simply persist the Agora client instance in memory. Since the page never fully reloads, the connection stays active as users navigate between routes.

Limitation: #

• This only works if the host site uses SPA routing—you can’t rely on this for all third-party sites, so it’s not a universal solution.

Final Recommendations #

• Primary Choice: Shared Workers are the most straightforward and reliable solution for maintaining persistent Agora connections across same-domain page navigations. They’re purpose-built for shared state across pages and have minimal lifecycle overhead.
• Backup: Use a Service Worker if you need the connection to stay alive even when all tabs are closed (though this requires more maintenance).

内容的提问来源于stack exchange，提问作者user14407845