English | 简体中文

Spring Boot independent Java SDK for Agora: RTC / RTM / signaling token generation, Cloud Recording and Channel Management REST APIs, and the on-premise recording bridge.

• 1. Project Overview
• 2. Features & Status
• 3. Requirements & Compatibility
• 4. Architecture & Modules
• 5. Installation
• 6. Quick Start
• 7. Configuration
• 8. Core Usage / API
• 9. Testing & Build
• 10. Versioning & Branches
• 11. Contributing & License

agora-java-sdk is a plain-Java (Spring Boot independent) SDK that wraps the Agora (声网) platform services commonly needed by server-side applications:

• Token generation — RTC tokens (RtcTokenBuilder), RTM tokens (RtmTokenBuilder), signaling tokens (SignalingToken) and the low-level AccessToken builder.
• Cloud Recording — REST client operations: acquire resource, start / update / query / stop recording, and layout updates.
• Channel Management — REST client operations: query channel user state, channel user list and channel list.
• On-premise Recording — a JNI bridge (RecordingSDK) to the Agora recording native library for local / on-premise recording scenarios.

The whole SDK (including the io.agora.cloud REST facade with AgoraTemplate and AgoraProperties) is a plain POJO layer — no Spring classes are required to compile or run it. Spring Boot integration is provided by the separate agora-spring-boot-starter project.

What it is not:

• Not a client-side RTC SDK (no audio/video capture, encoding or transport).
• Not a replacement for the Agora Recording SDK native binaries — the io.agora.recording package requires the native recording library to be installed on the host.

Typical scenarios:

Version lines:

+------------------+   +------------------------------------------+
| RTC client app   |   | agora-java-sdk (single jar)              |
| (channel / uid)  |-->|  media   : RtcTokenBuilder, AccessToken  |
| Agora Console    |   |  rtm/sig : RtmTokenBuilder, Signaling    |
| (AppId / Cert)   |   |  cloud : AgoraTemplate, Operations |
|                  |   |  recording : RecordingSDK (native)       |
+------------------+   +---------------------+--------------------+
                                            |
                                            v
                     +-------------------------------------------+
                     | Agora REST API / RTC network              |
                     +-------------------------------------------+

Single-module Maven project (packaging: jar). No child modules.

The project is not yet published to Maven Central. Snapshots/releases are distributed through the Aliyun Maven repository and GitHub Releases. Add the repository to your Maven settings.xml / pom.xml, then:

Maven:

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>agora-java-sdk</artifactId>
    <version>2.0.x.x.20260630-SNAPSHOT</version>
</dependency>

Gradle:

implementation 'io.github.easy4j:agora-java-sdk:2.0.x.x.20260630-SNAPSHOT'

Generate an RTC token (no configuration required):

import io.agora.media.RtcTokenBuilder;

public class TokenDemo {

    public static void main(String[] args) {
        RtcTokenBuilder builder = new RtcTokenBuilder();
        // token valid for 1 hour
        int expireTs = (int) (System.currentTimeMillis() / 1000) + 3600;
        String token = builder.buildTokenWithUid(
                "YOUR_APP_ID",
                "YOUR_APP_CERTIFICATE",
                "channel-1",
                123456,                                  // numeric uid
                RtcTokenBuilder.Role.Role_Publisher,
                expireTs);
        System.out.println("RTC token: " + token);
    }
}

Expected result: a non-empty base64-encoded access token that the Agora server accepts for the channel until the expiry timestamp.

This library has no runtime configuration file of its own. When used with the io.agora.cloud facade, AgoraProperties defines the property prefix agora (constant AgoraProperties.PREFIX). In Spring Boot, bind it with @ConfigurationProperties(prefix = "agora").

Example (application.yml):

agora:
  app-id: your-app-id
  app-certificate: your-app-certificate
  expiration-time-in-seconds: 3600
  login-key: your-restful-login-key
  login-secret: your-restful-login-secret

AgoraTemplate is constructed from three collaborators: an AgoraUserIdProvider (identity mapping between user id and channel name), an AgoraOkHttp3Template (HTTP client) and AgoraProperties.

import com.fasterxml.jackson.databind.ObjectMapper;
import io.agora.cloud.*;
import okhttp3.OkHttpClient;

AgoraProperties props = new AgoraProperties();
props.setAppId("YOUR_APP_ID");
props.setAppCertificate("YOUR_APP_CERTIFICATE");
props.setLoginKey("YOUR_LOGIN_KEY");
props.setLoginSecret("YOUR_LOGIN_SECRET");

AgoraUserIdProvider userIdProvider = new AgoraUserIdProvider() { /* defaults map user <-> channel 1:1 */ };
AgoraOkHttp3Template http = new AgoraOkHttp3Template(new OkHttpClient(), new ObjectMapper(), props);
AgoraTemplate template = new AgoraTemplate(userIdProvider, http, props);

// 1. Issue a token for a channel
String token = template.generateToken("user-1", "room-1"); // Role_Publisher by default

// 2. Cloud recording: acquire a resource id, then start recording
AcquireResourceResponse acquire = template.opsForCloudRecording().acquireId("user-1", "10001");
CloudRecordingStartResponse start = template.opsForCloudRecording().startRecording(
        "room-1", "10001", token, acquire.getResourceId(), new RecordingStorageConfig());

The operations follow the official Agora REST flow and map 1:1 to documented APIs:

acquireId(userId, uid) → startRecording(channelName, uid, token, resourceId, mode, storageConfig, ...) → updateMixRecording(...) / updateIndividualRecording(...) / updateLayout(...) → queryRecording(channelName, uid, resourceId, sid, mode) → stopRecording(channelName, uid, resourceId, sid, mode, asyncStop).

Request/response models live in io.agora.cloud.req and io.agora.cloud.resp (e.g. RecordingStorageConfig, TranscodingConfig, CloudRecordingQueryResponse).

./mvnw clean verify

• The build is configured with the JaCoCo Maven plugin (report + check goal with a 90% line-coverage rule bound to the verify phase; haltOnFailure=false).
• Assumption: the 1.0.x branch currently checks in no test sources under src/test; coverage thresholds are therefore enforced only when tests exist.
• No CI workflow files are present under .github/ in this worktree.

Maintenance policy: the 1.0.x line receives bug fixes and compatibility updates for the JDK 8 baseline. New features targeting newer JDKs land on the 2.0.x / 3.0.x lines. Releases are published to the Aliyun Maven repository and as GitHub Releases; the project is not yet published to Maven Central.

Contributions are welcome — please open issues or pull requests on GitHub.

Licensed under the Apache License, Version 2.0.