Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Connect through restricted networks with Cloud Proxy

You use Agora Cloud Proxy to ensure reliable connectivity for your users when they connect from an environment with a restricted network.

Understand the tech

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

  • Automatic (Default mode)

    By default, Voice SDK first attempts a direct connection to Agora SD-RTN™. If the attempt fails, Voice SDK automatically falls back and sends media securely on TLS 443. This is best practice when you are not sure if your end users are behind a firewall. While transmitting media over TLS 443 may not provide as high quality as using UDP. a connection on TLS 443 works through most firewalls. This is the default behavior of Voice SDK when cloud proxy type is set to NONE (default); you don't need to write any code to enable it.

  • Force UDP

    In the Force UDP mode of Cloud Proxy, Voice SDK securely sends media over UDP only. Your end users’ firewall must be configured to trust a list of allowed IP address. This is best practice when your end users are behind a firewall and require media with the highest possible quality. This mode does not support pushing streams to the CDN or relaying streams across channels.

  • Force TCP

    In the Force TCP mode of Cloud Proxy, Voice SDK securely sends media over TLS 443 only. This is best practice when your end users are behind a firewall and the firewall’s security policies only allow media to flow through TLS 443. In some cases the firewall might trust any traffic over TLS 443. However, in many cases the firewall is configured to trust only a specific range of IP addresses sending traffic over TLS 443. In this case, your end user’s firewall must be configured to trust a list of allowed IP address. Media quality might be impacted if network conditions degrade.

Agora recommends upgrading to the latest SDK version, which supports all three operating modes.

The following figure shows the Cloud Proxy workflow:

cloud proxy

The steps you need to implement Cloud Proxy in your app are:

  1. Attempt to join a channel using the default Automatic mode.

    If the attempt fails, Voice SDK automatically falls back and sends media securely on TLS 443.

  2. If communication on TLS 443 also fails, set Cloud Proxy type to UDP and join a channel.

  3. When the request succeeds, Cloud Proxy sends back the proxy information.

  4. Voice SDK sends signaling and media data to Cloud Proxy, which forwards this data to Agora SD-RTN™.

  5. Agora SD-RTN™ sends signaling and media data to Cloud Proxy, which forwards it to Voice SDK.

Prerequisites

  • Android Studio 4.1 or higher.
  • Android SDK API Level 24 or higher.
  • A mobile device that runs Android 4.1 or higher.
  • An Agora account and project.

  • A computer with Internet access.

    Ensure that no firewall is blocking your network communication.

  • Configured your firewall to allow communication through the Cloud Proxy allowed IP address.

Project setup

In order to create the environment necessary to use Cloud Proxy feature in your app, do the following:

  1. Enable and disable Cloud Proxy:

    • If your estimated Peak Concurrent Users (PCU) during a month exceeds 200, and you want to use either Force UDP or Force TCP mode, contact Agora Customer Support to activate Cloud Proxy.

    • If your estimated PCU during a month is 200 or less:

      1. In Agora Console, click the Project Management icon on the left.

      2. In Project Management, click Config for the project you want to enable Cloud Proxy for.

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

      4. Read the Enable Cloud Proxy information carefully. Check the box showing you have read the page, then click Enable.

        Your app has access to Cloud Proxy within 24 hours.

      5. Check the Status of Cloud Proxy (Force UDP and Force TCP modes). Once you see Enabled, Your app has access to Cloud Proxy.

      After activation, you can deactivate Cloud Proxy at any time using Agora Console. Cloud Proxy is deactivated immediately.

  2. Open your app:

    In your IDE, open the SDK quickstart Voice Calling project you created previously.

Implement communication using Cloud Proxy

This section shows how to use the Voice SDK to implement Cloud Proxy in your app, step-by-step.

  1. Import the connection and Cloud Proxy constants

    Add the following line to the list of import statements:


    _1
    import static io.agora.rtc2.Constants.*;

  2. Define a variable to keep track of failed connection attempts

    Add the following declaration to the MainActivity class:


    _1
    private boolean directConnectionFailed = false;

  3. Use the onConnectionStateChanged callback to enable Cloud Proxy

    When an attempt to connect directly to Agora SD-RTN™ fails, you set directConnectionFailed to true.


    _10
    @Override
    _10
    public void onConnectionStateChanged(int state, int reason) {
    _10
    if (state == CONNECTION_STATE_FAILED
    _10
    && reason == CONNECTION_CHANGED_JOIN_FAILED ) {
    _10
    directConnectionFailed = true;
    _10
    showMessage("Join failed, reason: " + reason);
    _10
    } else if (state == CONNECTION_CHANGED_SETTING_PROXY_SERVER) {
    _10
    showMessage("Proxy server setting changed");
    _10
    }
    _10
    }

  4. Set Cloud Proxy mode to UDP before you join a channel

    If your previous attempt to join a channel failed, call setCloudProxy and pass TRANSPORT_TYPE_UDP_PROXY as a parameter to select the UDP mode for Cloud Proxy. The setCloudProxy method returns 0 upon successful initiation of cloud proxy service.

    In the joinChannel method of the MainActivity class, add the following code before agoraEngine.joinChannel(...);:


    _9
    if (directConnectionFailed) {
    _9
    // Start cloud proxy service and set automatic UDP mode.
    _9
    int proxyStatus = agoraEngine.setCloudProxy(TRANSPORT_TYPE_UDP_PROXY);
    _9
    if (proxyStatus == 0) {
    _9
    showMessage("Proxy service setup successful");
    _9
    } else {
    _9
    showMessage("Proxy service setup failed with error :" + proxyStatus);
    _9
    }
    _9
    }

Test your implementation

To ensure that you have implemented Cloud Proxy in your app:

  1. Generate a temporary token in Agora Console .

  2. In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

  1. In Android Studio, open app/java/com.example.<projectname>/MainActivity, and update appId, channelName and token with the values for your temporary token.

  2. Connect a physical Android device to your development device.

  3. In Android Studio, click Run app. A moment later you see the project installed on your device.

    If this is the first time you run the project, grant microphone and camera access to your app.

  1. Click Join to start a call.

    If your initial attempt to join a channel fails due to a restricted network environment, the cloud proxy service is enabled and your second attempt to join a channel is successful.

Reference

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

Voice Calling