Introduction

Enterprises with high-security requirements usually have firewalls that restrict employees from visiting unauthorized sites to protect internal information.

To ensure that enterprise users can connect to Agora's services through a firewall, Agora provides the cloud proxy service.

Working principles

The following figure shows the working principles of the Agora cloud proxy service.

1. Before connecting to Agora SD-RTN™, the SDK sends the request to the cloud proxy service.
2. The cloud proxy service sends back the proxy information.
3. The SDK sends the data to the cloud proxy service, and the cloud proxy service forwards the data to Agora SD-RTN™.
4. Agora SD-RTN™ sends the data to the cloud proxy service, and the cloud proxy service forwards the data to the SDK.

Implementation

v4.3.0 or later

The Web SDK v4.3.0 optimizes the Agora cloud proxy architecture and enhances its connectivity in environments with restricted network access. The optimized Agora cloud proxy service also supports regional connection. If you use the Web SDK v4.3.0 or later, follow these steps to set up a cloud proxy service:

1. Apply for the cloud proxy

Contact support@agora.io and provide the following information:

• Your App ID
• The regions using the cloud proxy
• Concurrent scale
• Network operators

2. Enable the cloud proxy on the client

Before joining a channel, call the startProxyServer method to enable the cloud proxy service and set mode as 3, and then test if the audio call and video call or the live streaming works.

As of v4.4.0, the Web SDK provides the client.on("is-using-cloud-proxy") event. The SDK triggers this event after the local client successfully publishes a media stream to indicate whether the media stream is forwarded by the cloud proxy service.

const client = AgoraRTC.createClient({mode: 'live',codec: 'vp8'});

// Enable the cloud proxy.
client.startProxyServer(3);
// Join a channel.
client.join("<YOUR TOKEN>", "<YOUR CHANNEL>").then(() => {
  /** ... **/
});

3. Disable the cloud proxy on the client

To disable the cloud proxy, call the stopProxyServer method after leaving the channel.

// After enabling the cloud proxy and joining the channel.
/** ... **/

// Leave the channel.
client.leave();

// Disable the cloud proxy.
client.stopProxyServer();

// Join the channel.
client.join("<YOUR TOKEN>", "<YOUR CHANNEL>").then(() => {
  /** ... **/
});

v4.0.0 to v4.2.1

If you use any version between the Web SDK v4.0.0 to v4.2.1, follow these steps to set up a cloud proxy service:

1. Apply for the cloud proxy

Contact support@agora.io and provide the following information:

• Your App ID
• The regions using the cloud proxy
• Concurrent scale
• Network operators

2. Add IP addresses and ports to your whitelist

Add the following test IP addresses and ports to your whitelist.

The sources are the clients that integrate the Web SDK.

3. Enable the cloud proxy on the client

Before joining a channel, call the startProxyServer method to enable the cloud proxy service and set mode as 3, and then test if the audio call and video call or the live streaming works.

const client = AgoraRTC.createClient({mode: 'live',codec: 'vp8'});

// Enable the cloud proxy service.
client.startProxyServer();
// Join a channel.
client.join("<YOUR TOKEN>", "<YOUR CHANNEL>").then(() => {
  /** ... **/
});

Agora provides the IP addresses and ports for you to use the cloud proxy service in a production environment. Add the IP address and ports to your whitelist.

4. Disable the cloud proxy on the client

To disable the cloud proxy, call the stopProxyServer method after leaving the channel.

// Enable the cloud proxy service and join a channel.
/** ... **/

// Leave the channel.
client.leave();

// Disable the cloud proxy service.
client.stopProxyServer();

// Rejoin a channel.
client.join("<YOUR TOKEN>", "<YOUR CHANNEL>").then(() => {
  /** ... **/
});

API reference

• startProxyServer
• stopProxyServer

Considerations

startProxyServer must be called before joining the channel, and stopProxyServer must be called after leaving the channel.