Getting started overview

Getting started with Agora.io involves a series of steps designed to integrate real-time communication functionalities into a new or existing application. This process typically begins with account creation, followed by the generation of necessary credentials such as an App ID. Developers then select an appropriate SDK based on their target platform (e.g., Web, Android, iOS) and proceed to initialize the SDK within their application. The final stage involves implementing core functionalities, such as joining a channel and publishing/subscribing to audio and video streams, to establish a working real-time connection. Agora.io offers a free tier of 10,000 HD video minutes per month for initial development and testing.

The following table outlines the key steps to get an Agora.io application operational:

Step What to Do Where
1. Create Account Register for a developer account. Agora.io homepage
2. Get Credentials Obtain an App ID and App Certificate from the Console. Agora Console documentation
3. Choose SDK Select the SDK for your development platform (e.g., Web, Android, iOS). Agora SDK downloads
4. Install SDK Integrate the chosen SDK into your project. Agora SDK installation guides
5. Initialize Client Set up the Agora client with your App ID. Agora Web SDK quickstart
6. Join Channel Connect to a real-time communication channel. Agora Web SDK channel joining
7. Publish/Subscribe Send and receive audio/video streams. Agora Web SDK stream management

Create an account and get keys

To begin development with Agora.io, the first step is to create a developer account. This can be done by visiting the Agora.io website and following the registration process. Once an account is created and verified, you will gain access to the Agora Console, which is the centralized management interface for all Agora.io projects and services.

Within the Agora Console, you need to create a new project. Each project is assigned a unique App ID, which is a fundamental credential required to initialize any Agora SDK. The App ID serves as the primary identifier for your application when interacting with Agora's services. Additionally, for enhanced security, Agora.io recommends using an App Certificate, especially in production environments to generate temporary tokens. A token is a dynamic key generated on your application's server to authenticate users before they join an Agora channel, providing a layer of security over relying solely on the App ID. You can find detailed instructions on how to obtain an App ID and generate tokens in the official documentation.

When creating a project, you'll have the option to enable or disable an App Certificate. While it's possible to start development without an App Certificate (using only the App ID), it's strongly advised to enable and use it for any application intended for public release. The App Certificate is used to generate temporary tokens, which expire after a set duration, significantly reducing the risk of unauthorized access if your App ID were to be compromised. The process for generating a token with the App Certificate typically involves a backend server-side implementation. This best practice aligns with general API security guidelines, such as those discussed in OAuth 2.0 specifications for secure authorization.

To retrieve your App ID and App Certificate:

  1. Log in to the Agora Console.
  2. Navigate to the 'Project Management' section.
  3. Create a new project or select an existing one.
  4. The App ID will be displayed prominently. If an App Certificate is enabled, you can also copy it from this section.

Your first request

Making your first request with Agora.io typically involves setting up a basic real-time video or voice call. This example will focus on a web-based video call, utilizing the Agora Web SDK. The principles, however, are similar across other SDKs like Android or iOS, requiring SDK initialization, joining a channel, and managing media streams.

Prerequisites:

  • An Agora.io account with an App ID.
  • A basic understanding of HTML, CSS, and JavaScript.
  • A web server to host your HTML file (even a simple local server will suffice).

Step-by-step Web SDK example:

1. Create an HTML file (index.html):

This file will host the video elements and the JavaScript logic.

<!DOCTYPE html>
<html>
<head>
    <title>Agora Web SDK Quickstart</title>
    <script src="https://download.agora.io/sdk/release/AgoraRTC_N.js"></script>
    <style>
        #local-player, #remote-player {
            width: 320px; height: 240px; border: 1px solid black;
            margin: 10px;
        }
    </style>
</head>
<body>
    <h1>Agora Web SDK Video Call</h1>
    <div id="local-player"></div>
    <div id="remote-player"></div>
    <button id="join">Join</button>
    <button id="leave">Leave</button>

    <script>
        // Your JavaScript code will go here
    </script>
</body>
</html>

2. Add JavaScript logic (inside the <script> tags):

Replace YOUR_APP_ID with your actual Agora App ID. For simplicity, this example uses a temporary token (null) but in production, you should generate one securely on your server.

const client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });

let localTracks = {
    videoTrack: null,
    audioTrack: null
};
let remoteUsers = {};

const options = {
    appId: "YOUR_APP_ID", // Replace with your App ID
    channel: "demo_channel",
    token: null // For production, generate a token on your server
};

async function handleUserPublished(user, mediaType) {
    const uid = user.uid;
    remoteUsers[uid] = user;
    await client.subscribe(user, mediaType);

    if (mediaType === 'video') {
        const remotePlayerDiv = document.getElementById('remote-player');
        remotePlayerDiv.textContent = ''; // Clear previous content
        user.videoTrack.play(remotePlayerDiv);
    }
    if (mediaType === 'audio') {
        user.audioTrack.play();
    }
}

function handleUserUnpublished(user) {
    delete remoteUsers[user.uid];
    const remotePlayerDiv = document.getElementById('remote-player');
    if (remotePlayerDiv.querySelector(`#player-${user.uid}`)) {
        remotePlayerDiv.querySelector(`#player-${user.uid}`).remove();
    }
}

document.getElementById('join').onclick = async function () {
    await client.join(options.appId, options.channel, options.token, null);

    localTracks.audioTrack = await AgoraRTC.createMicrophoneAudioTrack();
    localTracks.videoTrack = await AgoraRTC.createCameraVideoTrack();

    document.getElementById('local-player').textContent = '';
    localTracks.videoTrack.play('local-player');
    await client.publish(Object.values(localTracks));
    console.log("publish success");
};

document.getElementById('leave').onclick = async function () {
    for (let trackName in localTracks) {
        let track = localTracks[trackName];
        if (track) {
            track.stop();
            track.close();
            localTracks[trackName] = null;
        }
    }
    await client.unpublish(Object.values(localTracks));
    await client.leave();
    document.getElementById('local-player').textContent = '';
    document.getElementById('remote-player').textContent = '';
    console.log("client leaves channel success");
};

client.on("user-published", handleUserPublished);
client.on("user-unpublished", handleUserUnpublished);

3. Run the application:

Host your index.html file on a web server. Open it in a browser, grant camera and microphone permissions, and click 'Join'. If you open it in two separate browser tabs or instances, you should see both local and remote video streams. This example provides a foundational setup, and further customization for UI/UX and advanced features can be built upon this base. More comprehensive web quickstart guides are available in the Agora Web SDK documentation.

Common next steps

After successfully establishing a basic real-time communication connection, developers typically explore several common next steps to enhance their applications:

  • Token Generation Server: For production environments, it is crucial to implement a secure token generation server. Instead of using a null token or hardcoding the App Certificate, a backend server should generate temporary tokens for users based on their UID, channel name, and expiry time. This ensures that users are authenticated and authorized before joining a channel, protecting against unauthorized access. Agora provides server-side token generation examples for various languages.
  • UI Customization: The basic setup often uses minimal UI elements. Developers will want to customize the user interface to match their application's branding and provide a better user experience. This includes designing controls for muting audio, toggling video, switching cameras, and displaying participant lists. Frameworks like React, Angular, or Vue.js can be used to build rich and interactive UIs around the Agora SDK. For instance, a common pattern for managing UI state in JavaScript applications is to use a state management library like Redux or Vuex, which can be integrated with Agora SDK events.
  • Advanced Features: Agora.io offers a wide array of advanced features beyond basic video and voice calls. These include screen sharing, in-app chat (RTM SDK), interactive live streaming, recording, whiteboarding, and AI noise suppression. Exploring these features can add significant value to the application. For example, the Interactive Whiteboard SDK allows for collaborative drawing and annotation during live sessions.
  • Error Handling and Monitoring: Implementing robust error handling and monitoring is essential for production applications. This involves listening to SDK events for errors, network interruptions, and user state changes, and providing appropriate feedback to the user. Agora's SDKs provide various callbacks and event listeners for monitoring connection status, user join/leave events, and media stream issues. Integrating with application performance monitoring (APM) tools can also help track real-time communication quality.
  • Scalability and Performance Optimization: As usage grows, optimizing the application for scalability and performance becomes critical. This includes managing bandwidth, adjusting video profiles, and optimizing network conditions. Agora.io's client role settings (e.g., 'host' vs. 'audience') and video profile configurations can help manage resource consumption effectively.
  • Platform-Specific Integrations: If targeting multiple platforms (e.g., mobile and web), developers will need to understand the nuances of each SDK and platform-specific integration patterns. For instance, mobile SDKs often require specific permissions handling and lifecycle management that differ from web applications. The Firebase Android setup guide, while not Agora-specific, illustrates common mobile integration patterns for external SDKs.

Troubleshooting the first call

Encountering issues during the initial setup of an Agora.io application is common. Here are some frequent problems and their solutions:

  • Invalid App ID:
    • Symptom: The SDK fails to initialize or join a channel, often returning an error related to authentication or invalid credentials.
    • Solution: Double-check that the App ID copied from the Agora Console is exactly correct and has no leading/trailing spaces. Ensure it's being passed correctly to the createClient or equivalent initialization method. Reference the Agora App ID documentation for verification.
  • Microphone/Camera Access Denied:
    • Symptom: Local audio/video streams are not published, or the user is prompted repeatedly for media permissions.
    • Solution: Ensure your browser (for web apps) or operating system (for desktop/mobile apps) has granted permission for your application to access the microphone and camera. For web applications, ensure your site is served over HTTPS, as many browsers restrict media access on insecure HTTP connections. Check browser settings for media permissions.
  • Network Connectivity Issues:
    • Symptom: Users cannot join a channel, or streams are frequently interrupted/lagging.
    • Solution: Verify network connectivity. Firewalls or corporate proxies might be blocking Agora's required ports (UDP ports 443, 3478, 4000-60000). Refer to the Agora network test tool and firewall configuration guide for detailed port requirements. A simple network test can often diagnose if the issue is local or related to internet access.
  • Token Related Errors (for projects with App Certificate enabled):
    • Symptom: Users fail to join a channel with authentication errors, even with a correct App ID.
    • Solution: If your project uses an App Certificate, you must generate a token on your server and pass it to the SDK's join method. Using a null token will fail if the App Certificate is enabled. Ensure the token generation logic on your server is correct and the token hasn't expired. Consult the Agora token generation documentation.
  • SDK Version Mismatch/Compatibility:
    • Symptom: Unexpected behavior, errors, or crashes when using the SDK.
    • Solution: Ensure you are using a compatible version of the SDK with your development environment and that all dependencies are met. Check the Agora SDK download page for the latest stable versions and release notes. Sometimes, using outdated SDKs can lead to unforeseen issues.
  • No Remote Video/Audio:
    • Symptom: A user can see their own video/hear their own audio (local stream) but cannot see or hear other participants (remote streams).
    • Solution: Verify that the client.subscribe method is being called for remote users. Ensure that the handleUserPublished event listener is correctly implemented and that the remote tracks are being played into appropriate DOM elements (for web) or views (for mobile/desktop). Confirm that both participants are joining the same channel name.
  • Console Errors/Warnings:
    • Symptom: The browser's developer console or IDE's output shows error messages or warnings.
    • Solution: Always check the console for specific error messages. These often provide direct clues about what went wrong, such as syntax errors, network request failures, or SDK-specific warnings. The Mozilla Web Console documentation can help interpret common browser console messages.