Use Cloud Proxy

Agora Cloud Proxy is a feature of Agora's Voice and Video SDKs. It ensures reliable audio and video connectivity for end users when they connect from restricted network environments.

The following figure illustrates how Agora Cloud Proxy works:

1. Before connecting to Agora SD-RTN™, the Agora SDK sends a request to the cloud proxy service.
2. When the request succeeds, the cloud proxy service sends back the proxy information.
3. The Agora SDK sends signaling and media data to the cloud proxy service, which then forwards the data to Agora SD-RTN™.
4. Agora SD-RTN™ sends signaling and media data to the cloud proxy service, which then forwards the data to the Agora SDK.

Operating modes

To accommodate your end users’ firewall settings and business needs, Agora Cloud Proxy offers the following operating modes:

• Automatic: This is the default setting in the latest version of the Agora RTC Native SDK and Agora Web SDK. In this mode, the Agora SDK first attempts a direct connection to Agora SD-RTN™; if the attempt fails, the Agora SDK automatically falls back to securely send media over TCP/TLS 443. This mode is recommended when you are not sure if your end users are behind a firewall.

  Media over TCP/TLS 443 may not have as high quality as media over UDP. However, a connection on TCP/TLS 443 typically works through most end users’ firewalls.

• Force UDP: The Agora SDK securely sends media over UDP only. Your end users’ firewall must be configured to trust a list of allowed IP addresses (see Allowed IP List on Agora Console). This mode is recommended when your end users are behind a firewall and require media with the highest possible quality.

• Force TCP: The Agora SDK securely sends media over TCP/TLS 443 only. This mode is recommended when your end users are behind a firewall and the firewall's security policies only allow media to flow through TCP/TLS 443. In some cases the firewall might trust any traffic over TCP/TLS 443; however, in many cases the firewall is configured to trust only a specific range of IP addresses sending traffic over TCP/TLS 443. In this case, your end user's firewall must be configured to trust a list of allowed IP addresses (see Allowed IP List on Agora Console).

  Media quality might be impacted if network conditions degrade.

If you do not select a specific proxy mode within the Native or Web SDK, the SDK always uses Automatic mode.

Pricing and billing

Automatic mode is free of charge and covers the majority of customer scenarios. Force UDP and Force TCP modes are provided for a fee.

Agora offers Force UDP and Force TCP cloud proxy modes with tiered capacity and sets a minimum monthly base fee for each tier. Once you enable the Force UDP or Force TCP cloud proxy service at a specified capacity, Agora charges either a usage-based fee or a minimum monthly base fee according to the following rule:

• If your monthly usage-based fee, including volume discounts, exceeds the minimum monthly base fee, Agora bills your account based on your total monthly usage.
• If your monthly usage-based fee, including volume discounts, is lower than the minimum monthly base fee, Agora charges the minimum monthly base fee.

Minimum monthly base fee

The Agora Cloud Proxy service has a tiered capacity structure based on your monthly Peak Concurrent Users (PCU). The minimum monthly base fee for each tier is as follows:

Notes

• Typically, about 5% to 10% of the audio and video traffic from your end users may require the cloud proxy service.
• Tier 1 is the default capacity of the Agora Cloud Proxy service. You can activate the cloud proxy service for Tier 1 directly from the Agora Console. If you want to use the cloud proxy service for a Tier higher than Tier 1, you must contact Agora Customer Support to help with activation or deactivation.
• Agora offers a 10% overage allowance for all tiers of PCU at no additional charge. Agora notifies you when your PCU exceeds the 10% overage allowance. Upon receiving this notice, contact Agora Customer Support to upgrade to the next tier to ensure you have sufficient capacity in the future. Before your upgrade, Agora does try to provide the required capacity beyond the 10% overage allowance; however, the quality of service for an overage of greater than 10% is not guaranteed.

Usage-based fee

The usage of the Force UDP or Force TCP cloud proxy service is measured in minutes and is calculated separately based on the media type. The unit prices are as follows:

Volume discounts for usage-based fee

Force UDP and Force TCP cloud proxy minutes count toward the 10,000 free-of-charge minutes that Agora provides to every account. In addition, Agora automatically applies the following tiered discounts when your Force UDP and Force TCP cloud proxy usage exceeds 100,000 minutes:

Notes

• The discount applies to the usage within that tier only.
• Volume discounts do not apply to the minimum monthly base fee.

Billing

Once the Force UDP or Force TCP cloud proxy service is activated per your request, you are billed according to the minimum monthly base fee or based upon minutes of usage, whichever is greater. Billing occurs at the end of each calendar month.

You can deactivate the Cloud Proxy Force UDP or Force TCP modes at any time on the Agora Console. The deactivation takes effect immediately, and you are billed either the minimum monthly base fee or the usage-based fee for that month, whichever is greater.

Developer Guide

Enabling Cloud Proxy Force UDP and Force TCP Modes from the Agora Console

Follow these steps to enable the Force UDP or Force TCP cloud proxy service on the Agora Console:

1. Log in to the Agora Console, and click the Project Management icon on the left navigation panel.

2. On the Project Management page, click Config for the project for which you want to enable the cloud proxy service.
   

3. Under Real-time engagement core, find Cloud Proxy (Force UDP and Force TCP modes), and click Enable.

   

4. Read the pop-up prompt carefully, check the box at the bottom, and click Enable.

   

5. Check the Status of Cloud Proxy (Force UDP and Force TCP modes). Once it turns to Enabled, you can configure your SDKs by following the implementation guide.
   

   You can click Config to get the Cloud Proxy Allowed IP List on the Cloud Proxy Configuration page.

Notes

• If your estimated PCU during a month exceeds 200, and you want to use either Force UDP or Force TCP mode,
  you cannot activate the service on the Agora Console directly. Contact Agora Customer Support for help with the activation.
• If your estimated PCU during a month is 200 or fewer, you can activate either the Force UDP or Force TCP mode directly on the Agora Console, and it takes effect within 24 hours.
• After activation, you can deactivate the service at any time on the Agora Console, and the deactivation takes effect immediately.

Enabling Cloud Proxy Force UDP and Force TCP Modes from the SDKs

Prerequisites

Before enabling the cloud proxy modes in the SDK, ensure you meet the following prerequisites:

1. Your end users have configured their firewalls to trust the Cloud Proxy Allowed IP List (see Allowed IP List on Agora Console).
2. You have enabled Cloud Proxy Force UDP and Force TCP modes, either through the Agora Console (for capacity Tier 1) or by contacting Agora Customer Support. The status on the Console indicates Enabled.
3. You have integrated the SDK and prepared the development environment. For details, see QuickStart Guide.

Implementation

To enable Force UDP or Force TCP cloud proxy mode, do the following:

1. Before joining a channel, call setCloudProxy, and set proxyType as UDP_PROXY(1) or TCP_PROXY(2).
2. Test the audio and video call functionality.

To disable Force UDP or Force TCP cloud proxy mode, call setCloudProxy, and set proxyType as NONE_PROXY(0), which enables the SDK to return Automatic (default) mode.

API reference

• Android：setCloudProxy
• iOS：setCloudProxy
• macOS：setCloudProxy
• Windows: setCloudProxy

Considerations

• Agora recommends that you call setCloudProxy before joining the channel or after leaving the channel.
• Force UDP cloud proxy mode does not support pushing streams to the CDN or relaying streams across channels.