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 enable the cloud proxy service for Tier 1 directly from 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.
• 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 enabled 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 disable the Cloud Proxy Force UDP or Force TCP modes at any time on Agora Console, and this takes effect immediately. 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 Agora Console

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

1. Log in to 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 Features, 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.

   

   Now you can see the Config action besides Cloud Proxy (Force UDP and Force TCP modes). Click Config to go to the configuration page, and the switch toggle shows Enabled. You can use UDP and Force TCP modes in your SDKs by following the implementation guide.
   

   You can click Agora Allowed IP List for Agora Cloud Proxy allowed IP List.

Notes

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

Using Cloud Proxy Force UDP and Force TCP Modes in the SDKs

Prerequisites

Before using 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 is Enabled.
3. You have integrated the SDK and prepared the development environment. For details, see QuickStart Guide.

Implementation

To use 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 stop using Force UDP or Force TCP cloud proxy mode, call setCloudProxy, and set proxyType as NONE_PROXY(0), which enables the SDK to return to 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.

Disabling Cloud Proxy Force UDP and Force TCP Modes from Agora Console

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

1. Log in to 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 disable the cloud proxy service.
   

3. Under Features, find Cloud Proxy (Force UDP and Force TCP modes) and click Config.
   

4. On the Cloud Proxy (Force UDP and Force TCP modes) Configuration page, click the Status toggle.
   

5. Read the pop-up prompt carefully, and click Disable.
   
   Force UDP and Force TCP modes in Cloud Proxy are now disabled.