Agora Native SDK for Web Reference Manual

Introduction

The Agora Native SDK for Web provides web browsers with open access to the Agora Global Network.

The Agora Native SDK for Web allows you to perform the following operations:

  • Session setup: Join and leave shared Agora conferencing sessions (identified by unique channel names), where there may be many global users conferenced together or simply one other user for one-to-one communication. Your application code should create and manage unique channel names; these usually originate in user, session, and date/time information that your application is already managing.
  • Media control: Enable and disable voice and video (allowing muting) and set various voice and video parameters that help the Agora Native SDK optimize communications. Many of the SDK operations are automated and do not require developer intervention if these parameter settings are not provided.
  • Device control: Access the microphone or speakerphone, set the volume, select from alternative cameras, and set the video window display.
  • Session control: Receive events when other users join or leave a conferencing session (channel), and understanding who’s speaking, who’s muted, and who’s viewing the session. These events allow the application to decide when to make changes to the delivery of video and audio streams, and other application-specific user and status information.
  • Quality management: Obtain statistics and quality indicators about network conditions, run built-in tests, submit ratings and complaints about sessions and enable different levels of error logging.
  • Recording: Record audio or video and audio in one or multiple channels simultaneously. This function is only applicable to the users who have adopted the Recording Key schema.For details, refer to Agora Recording Server.
  • Data Encryption: Encrypt the audio and video packets.
  • Whiteboard: Provide a simple collaboration platform on the whiteboard where users from different locations can draw, annotate, and share PDF documents to visualize and simplify the communication. For details, refer to Agora Whiteboard SDK.
  • Screen Sharing: Share the desktop or window with another user. When the screen sharing function is enabled, the other person’s screen displays your shared desktop or window instead of the camera video.

The Agora Native SDK for Web provides three straightforward JavaScript classes to deliver these features, which support:

  • A single Client object for establishing and controlling sessions.
  • Multiple Stream objects for managing different voice and video media streams.
  • Top-level AgoraRTC object for creating the appropriate Client and Stream objects.

For details on the API definition and sample code, see API Reference - Agora Native SDK for Web.

The Agora Native SDK returns some error codes or warning code when calling APIs or running. For details, see Agora Native SDK in Error and Warning Messages.

Compatibilities

Native SDK 1.3 or later

Supported Browsers

Platform Browser Requirement
Windows Edge 25.10586.0.0
Windows 10 Chrome 51.0.2704.103 (64 bit)
Mac Safari 9.1.1(11601.6.17)

Note

  • Do not use an unsupported browser, for example, Opera, Firefox, and Chrome browsers are not supported and will behave unpredictably.
  • Chrome is supported on Windows at 640x480p 30fps resolution. Other higher resolutions will be supported in future releases.

Operating System Requirements

OS Requirements
Windows Windows 7 or later
Mac OS X v10.10 or later

Capabilities and Limitations

  • The maximum supported video resolution:720p 15fps and 480p 30fps.
  • A PC can only have one instance running.

Getting Started

Obtaining SDK

Download the latest SDK from http://www.agora.io/downloads/ or contact sales@agora.io.

Component Description
./agent It includes the following applications:
AgoraWebAgent.pkg
AgoraWebAgentSetup.exe
./client Sample web application.
./doc Agora Web SDK Documentation:
Agora Native SDK for Web Reference Manual v1_6_EN.pdf
Agora Native SDK for Web Reference Manual v1_6_CHS.pdf
./lib Required libraries
./server Web service-side sample code

About keys

This section describes the concepts and use of App ID, App Certificate, Dynamic Key, Channel Key and Recording Key. For details, see Agora Keys User Guide.

Developing and Deploying Application

Applications using the Agora Native SDK for Web are standard JavaScript applications. To deploy the application, you need to load the Agora JS library and also need access to the JS extension libraries provided with the SDK.

Load the Agora JS library AgoraRTCSDK-1.6.0js which can be downloaded from:

https://rtcsdk.agora.io/AgoraRtcAgentSDK-1.6.0.js or http://rtcsdk.agora.io/AgoraRtcAgentSDK-1.6.0.js

Running the Sample Web Application

Client

The default sample code only requires your static App ID (which is simply entered into the sample application web page). To run the provided sample web application:

  1. Ensure that you have a local web server installed, such as Apache, NginX, or Node.js.
  2. Deploy the files under./client/ to your web server.
  3. Access the sample application page on your web server using one of the browsers listed in Supported Browsers.

Do the following if you want to run the sample application with a Channel Key:

  1. Set up and launch the key-generation server.
  2. Make an http/https request from the client to the key-generation server to fetch the generated Channel Key.
  3. Call AgoraRTC.client.join.

Server

This code is only required when you want to experiment with using more secure Channel Key. In production use, you integrate this logic into your own server-side applications and (re)code this in the programming languages you are already using for your server-based functionality.

The sample code is in JavaScript and requires a standard Node.js server.

  1. Install a standard Node.js server in your server or cloud infrastructure.
  2. Run npm install under ../server/nodejs/.
  3. Fill in the values of your VENDOR_KEY and SIGN_KEY in ../server/nodejs/DemoServer.js.
  4. Launch the server with node DemoServer.js.

Installing AgoraWebAgent on Windows or Mac

After your deployment, the client will ask your users to install the AgoraWebAgent application on their Windows or Mac according to the system prompt. The system prompt includes a download link and an installation guide provided by Agora, and your users can directly use them or you can customize them to redirect the users to your website. The following shows the installation guide again for your customization convenience:

On Windows

  1. Double-click the AgoraWebAgent.exe downloaded from the system prompt.
../_images/webagent_windows_1.png
  1. Select the language for installation: English.
  2. Click Browse... if you want to select a different folder. Otherwise, click Next>.
  3. Click Install and wait until the progress bar is completed.
../_images/webagent_windows_4.png
  1. Select Run AgoraWebAgent.exe and then click Finish.
../_images/webagent_windows_5.png

Once the program is installed, a shortcut is displayed on the Desktop and AgoraWebAgent starts up automatically whenever starting the computer. An icon will display at the lower right part of the toolbar if AgoraWebAgent is running. Users can disable/enable the automatic start-up in the task manager. If the plugin program is closed while using the Agora Video Call on the browser, restart it by clicking the shortcut on desktop. Once it is restarted, it starts up automatically again whenever starting the computer.

../_images/webagent_windows_6.png

On Mac

  1. Double-click the AgoraWebAgent.pkg downloaded from the system prompt.
  2. Click Continue on the installer.
../_images/webagent_mac_2.png
  1. Click Continue.
  2. Click Install to install the application on the default location.
  3. Enter your computer username and password. Proceed with Install Software.
  4. When the following message displays, the installation is complete. Click Close.
../_images/webagent_mac_6.png

Once AgoraWebAgent is installed, it is in the Applications directory by default, and it starts up automatically whenever starting the computer. An icon will display at the upper right part of the toolbar if AgoraWebAgent is running. You can disable/enable the automatic start-up by right-clicking the icon. If the program is closed while using the Agora Video Call on browser, restart it by clicking the icon in ‘/Applications’ . Once it is restarted, it starts up automatically again whenever starting the computer.

Uninstalling AgoraWebAgent on Windows or Mac

On Windows

The uninstallation procedure is the same as uninstalling any other application on Windows XP, Windows 7, Windows 8, and so on.

Take Windows 8 for example:

  1. Go to Desktop> Control Panel.
  2. Click Uninstalling the Applications under Applications.
  3. Find AgoraWebAgent.exe and right click it to select uninstall.
  4. Wait until the progress is finished.

On Mac

  1. Go to Finder on the Docker.
  2. Click and enter the folder Applications.
  3. Find the installed AgoraWebAgent and right click it to select Move to Trash.

Encrypting data

The Agora Native SDK supports built-in encryption using the AES-128 or AES-256 encryption algorithm. If your application has integrated the built-in encryption of Agora SDK, then users are able to record an encrypted channel.

You can call setEncryptionSecret to enable the encryption function and then call setEncryptionMode to set the mode to be used. For details, see API Reference - Agora Native SDK for Web.

The following diagram depicts the built-in encryption/decryption process:

../_images/agora-encryption.png