Agora Communications as a Service (CaaS) is a global network that provides native and web Software Development Kits (SDKs) for application developers to add voice and video conferencing, interactive broadcast, and gaming communication functionalities to their applications.
The Agora SDK¶
The Agora SDK consists of a Native and Web SDK that allows you to easily integrate communication functionalities into your app or website. This allows thousands of users to communicate through a computer or mobile device – across every operating system and around the world in real time. From documentation to integration, the Agora Application Programming Interface (API) is straightforward and built on simplicity. Adding a few lines of code gives your users limitless communication possibilities.
This document provides an introduction to the concepts related to the Agora API, and to help developers understand the Agora API from a high level. This is separate from the API reference, which provides more detail.
The Agora Native SDK¶
The Agora Native SDK is available to developers on iOS, Android, Windows, and Mac platforms. It has all the necessary voice and video codecs built-in, along with the logic to access the Agora Global Network and automatically respond to disconnections and varying network conditions. Developers simply need the provided high-level APIs. Everything else is built in.
The Agora Web SDK¶
The Agora Web SDK enables the development of web apps that have virtually the same functionalities as native apps developed with the Native SDK.
The Agora Global Network¶
Everything you need is in the SDKs. You do not need to deploy any servers. The Agora Global Network is the server, with a network of more than 100 servers around the world. A few function calls from your client app will enable instances of your client app communicating.
To get started, sign up for a developer account at http://dashboard.agora.io.
Once you have signed up, use the dashboard to create one or more App ID**s. An **App ID creates a communications space used by all instances of your application. This space is separated from the spaces used by other applications and organizations.
Channels are central to how Agora’s SDKs work. Think of a channel as a meeting room. To set up communications between two or more instances of an application, the instances will join the same channel. Channel names are unique within the domain of an App ID. The process for app instances to exchange channel names is managed outside the SDK, and is handled by the application developer.
A channel will automatically be created the first time an app instance tries to join. There is no need to create the channel as a separate step.
A Video Communications Session at a High Level¶
The SDK can support voice and video communications. The process of setting up a communications session is pretty simple. At a high level, the app follows these steps:
- Initialize the SDK
- Join a channel
- Send the media
- Display the media
A Video Communications Session in Detail¶
Let us look at the details on how to perform the aforementioned steps. See the API reference for more details.
Initializing the SDK¶
- Create the RTC engine object by calling createAgoraRtcEngine(…).
- Initialize the SDK providing your App ID by calling initialize(…).
Joining a Channel¶
For a typical multiparty conference call or 1:1 session, set the channel type to “Communication” by calling setChannelProfile(…).
Then, join the channel by calling joinChannel(…), and by specifying the channel name.
Send the local video by calling enableVideo(…).
You can control the video profile (resolution, frame rate, and bitrate) by calling setVideoProfile(….). The SDK may adjust the profile parameters in real time when the communication conditions are not favorable.
Call setupLocalVideo(…) to display the video.
Communication, Live broadcast, and Gaming¶
Agora’s SDK supports three different communication modes:
Communication: This mode is similar to traditional video conferencing, where two or more users join in a room and each user can see and talk to each other. Participation is symmetrical in this regard.
Live Broadcast: This is a non-symmetrical mode of communications where the media from a host will be broadcast to a number of viewers. Live broadcast also supports roundtable broadcast functionality where a small set of hosts will communicate with each other as if in a “Communications” channel. The media from these hosts will be broadcast to a large number of viewers.
Gaming: This is a special communications mode optimized for use in game play on mobile devices.
The communications mode is specified by calling the setChannelProfile() API.
Authorization is a means to ensure only authorized app instances or users are connected to the communications session.
Use of Dynamic Keys for Increased Security¶
Each “vendor” organization using the Agora SDK (across platforms) has a unique App ID which identifies their organization. All the communication sessions that are created across the Agora Global Network for one App ID are isolated from all other sessions for other App ID**s. Therefore, communication sessions will not be connected together across vendors. Statistics, management, and billing are linked to each **App ID. If an organization has multiple applications that should be kept completely separate, like they are built by completely different teams, then they would use multiple App ID**s. If applications need to communicate with each other, then a single **App ID should be used.
App ID**s are used in the RtcEngine step to identify your organization in the Agora Global Network, and then the joinChannel() method is used to join a one-to-one or conferencing session using a unique channel name for your **App ID. Using your App ID directly is easy and works well for initial application development.
Anyone with your App ID can perform the same operations in their own client applications. This will allow anyone with your App ID to join sessions that belong to you and are billed to you. To prevent your communications from being intercepted and to secure your applications, consider using dynamic keys (tokens) for large-scale production applications.
Billing and Pricing¶
For more information about how to calculate Agora’s real-time communications and recording charges, see bill.