Restrict media zones

Updated

Control and customize video SDK data routing in your app

When a user joins a channel, Voice SDK automatically connects them to the Agora SDRTN® media zone that is geographically closest to the user. However, to meet the laws and regulations of the user's country, you may need to specify, or filter out connections to a specific geographical zone. Agora enables you to control and customize data routing in your app by specifying the Agora SDRTN® media zone users connect to.

This is an advanced feature suitable only for use-cases with access security restrictions.

Understand the tech

After you turn on the restricted media zones feature, the SDK only accesses the Agora server in the specified zone(s), irrespective of the geographical location of the user. As an example, the following table shows the outcome if you specify North America as the access zone, and users connect to Agora SDRTN® from North America and China respectively:

Designated access zoneUser's locationZone actually accessed by the SDKUser experience
North AmericaNorth AmericaNorth AmericaNormal
North AmericaChinaNorth AmericaQuality may be affected
  • If a server in the specified zone is not available, the SDK reports an error.
  • Due to cross-regional public internet between the designated zone and the geographical location where the app user is located, the audio and video experience may be affected.

The following figure shows the workflow you implement to restrict access to media zones:

Restrict media zones

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implement restricted media zones

This section shows you how to restrict access to media zones in your app.

You specify the media zone by setting the context.areaCode parameter before calling the initialize method to create an IRtcEngine instance. The available media zones are:

  • AREA_CODE_GLOB: Global (Default)
  • AREA_CODE_CN : Mainland China
  • AREA_CODE_NA : North America
  • AREA_CODE_EU : Europe
  • AREA_CODE_AS : Asia except Mainland China
  • AREA_CODE_JP : Japan
  • AREA_CODE_IN : India

Media zones support bitwise operations.

Include a media zone

To limit access to servers in only one media zone, such as North America, set context.areaCode = AREA_CODE_NA; before calling the initialize method:

// Initialize Agora SDK
bool CAgoraRegionConnDlg::InitAgora() {
  // Create AgoraRtcEngine instance
  m_rtcEngine = createAgoraRtcEngine();
  if (!m_rtcEngine) {
    m_lstInfo.InsertString(m_lstInfo.GetCount() - 1, _T("createAgoraRtcEngine failed"));
    return false;
  }
  m_eventHandler.SetMsgReceiver(m_hWnd);

  RtcEngineContext context;
  std::string strAppID = GET_APP_ID;
  context.appId = strAppID.c_str();
  CString area_code;
  m_cmbAreaCode.GetWindowText(area_code);

  // Restrict access to servers in North America
  context.areaCode = AREA_CODE_NA;

  // Initialize RtcEngineContext
  int ret = m_rtcEngine->initialize(context);
  if (ret != 0) {
    m_initialize = false;
    CString strInfo;
    strInfo.Format(_T("initialize failed: %d"), ret);
    m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
    return false;
  } else {
    m_initialize = true;
    m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("initialize success"));
  }

  return true;
}

Exclude a media zone

To exclude servers in a region, such as Mainland China, set context.areaCode = AREA_CODE_GLOB ^ AREA_CODE_CN; before calling the initialize method:

// Initialize Agora SDK
bool CAgoraRegionConnDlg::InitAgora() {
	// Create AgoraRtcEngine instance
	m_rtcEngine = createAgoraRtcEngine();
	if (!m_rtcEngine) {
		m_lstInfo.InsertString(m_lstInfo.GetCount() - 1,
		            _T("createAgoraRtcEngine failed"));
		return false;
	}
	m_eventHandler.SetMsgReceiver(m_hWnd);

	RtcEngineContext context;
	std::string strAppID = GET_APP_ID;
	context.appId = strAppID.c_str();
	CString area_code;
	m_cmbAreaCode.GetWindowText(area_code);

	// Exclude Mainland China from access area
  context.areaCode = AREA_CODE_GLOB ^ AREA_CODE_CN;

	// Initialize RtcEngineContext
	int ret = m_rtcEngine->initialize(context);
	if (ret != 0) {
		m_initialize = false;
		CString strInfo;
		strInfo.Format(_T("initialize failed: %d"), ret);
		m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
		return false;
	} else
		m_initialize = true;
	m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("initialize success"));
}

Reference

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

API reference