Skip to main content

You are looking at Video Calling v3.x Docs. The newest version is  Video Calling v4.x

Network Geofencing

Introduction

To meet the laws and regulations of different countries or regions, the Agora Video SDK supports geofencing. After enabling geofencing, the SDK only connects to Agora servers within the specified region, regardless of where your app users are located.

For example, if you specify North America as the region for connection, when two users attempt to connect to Agora servers from different locations, the result is as follows:

Specified region for connection App user location Actual region for connection User experience after connection 1
North America North America North America Normal
China Can be less than optimal 2
1 If there is no available server in the specified region, the SDK throws an error.
2 When the user's location is different from the specified region, the public network spanning between the user's location and the specified region might have a poor quality, which can make the audio and video experience less than optimal.
Do not enable geofencing if your scenarios do not have regional restrictions.

Implementation

As of v3.0.0.2, the Agora Video SDK Native SDK supports network geofencing.

When creating an RtcEngine instance by calling create, set the mAreaCode parameter in RtcEngineConfig to specify the region for connection.

  • AREA_CODE_GLOB: (Default) Global
  • AREA_CODE_CN: Mainland China
  • AREA_CODE_NA: North America
  • AREA_CODE_EU: Europe
  • AREA_CODE_AS: Asia, excluding Mainland China
  • AREA_CODE_JP: Japan
  • AREA_CODE_IN: India
  • The area codes listed above apply to the Video SDK Native SDK v3.1.1 and later. For area codes earlier than v3.1.1, you can refer to the API reference of a specified version.
  • The area codes support bitwise operation.

Sample code

  • Specify the region for connection as North America:


    _14
    private void initializeEngine() {
    _14
    try {
    _14
    RtcEngineConfig config = new RtcEngineConfig();
    _14
    config.mAppId = appId;
    _14
    config.mContext = mContext;
    _14
    config.mEventHandler = mEngineEventHandler.mRtcEventHandler;
    _14
    config.mAreaCode = AREA_CODE_NA;
    _14
    mRtcEngine = RtcEngine.create(config);
    _14
    } catch (Exception e) {
    _14
    Log.e(TAG, Log.getStackTraceString(e));
    _14
    throw new RuntimeException("NEED TO check rtc sdk init fatal error\n" + Log.getStackTraceString(e));
    _14
    }
    _14
    ...
    _14
    }

  • Exclude Mainland China from the regions for connection:


    _14
    private void initializeEngine() {
    _14
    try {
    _14
    RtcEngineConfig config = new RtcEngineConfig();
    _14
    config.mAppId = appId;
    _14
    config.mContext = mContext;
    _14
    config.mEventHandler = mEngineEventHandler.mRtcEventHandler;
    _14
    config.mAreaCode = AREA_CODE_GLOB ^ AREA_CODE_CN;
    _14
    mRtcEngine = RtcEngine.create(config);
    _14
    } catch (Exception e) {
    _14
    Log.e(TAG, Log.getStackTraceString(e));
    _14
    throw new RuntimeException("NEED TO check rtc sdk init fatal error\n" + Log.getStackTraceString(e));
    _14
    }
    _14
    ...
    _14
    }

  • Specify the regions for connection as North America, Europe, Asia, and India:


    _14
    private void initializeEngine() {
    _14
    try {
    _14
    RtcEngineConfig config = new RtcEngineConfig();
    _14
    config.mAppId = appId;
    _14
    config.mContext = mContext;
    _14
    config.mEventHandler = mEngineEventHandler.mRtcEventHandler;
    _14
    config.mAreaCode = AreaCode.AREA_CODE_NA | AreaCode.AREA_CODE_EU | AreaCode.AREA_CODE_AS | AreaCode.AREA_CODE_IN;
    _14
    mRtcEngine = RtcEngine.create(config);
    _14
    } catch (Exception e) {
    _14
    Log.e(TAG, Log.getStackTraceString(e));
    _14
    throw new RuntimeException("NEED TO check rtc sdk init fatal error\n" + Log.getStackTraceString(e));
    _14
    }
    _14
    ...
    _14
    }

Considerations

If a firewall is deployed in your network environment, ensure that you whitelist all domains and ports listed in Use Cloud Proxy.