# Android 原生接入 RTC

原生 Android SDK 使用设备上的 WebRTC 采集和渲染。你的 Activity 负责布局、按钮和系统授权；SDK 负责房间、媒体和状态。先用 `viewer` 票据完成只看入会，再给需要发布的成员签发相应能力票据。

```mermaid
flowchart LR
    A["Activity 创建 SDK"] --> B["joinWithAccessTicket"]
    B --> C["onJoined / onError"]
    C --> D["远端轨道绑定 Renderer"]
    D --> E["leave → close"]
```

## 接入同批依赖

使用交付的 AAR 或源码 `:sdk` 模块，并保留该包声明的 WebRTC、OkHttp 与原生依赖。不要只复制 AAR 然后删除依赖，也不要同时引入另一套不同版本的 WebRTC 库。当前 SDK 最低 Android API 26；Manifest 与运行时都要提供实际使用的相机、麦克风权限。

若以交付 AAR 接入，Gradle 还需与本次 SDK 构建匹配的外部依赖；当前源码使用：

```kotlin
dependencies {
    implementation(files("libs/AKStreamRtcSDK.aar"))
    implementation("io.github.webrtc-sdk:android:144.7559.09")
    implementation("com.squareup.okhttp3:okhttp:5.3.0")
}
```

使用源码 `:sdk` 模块时由模块声明这些依赖。下一批交付若升级依赖版本，应以那批 AAR 的说明为准，不把本例当作永久固定版本。

SDK 创建方式：

```java
TransformSurfaceViewRenderer localView = new TransformSurfaceViewRenderer(this);
AkNativeRtcClient client = new AkNativeRtcClient(this, localView, listener);
client.setInitialMediaEnabled(false, false);
client.joinWithAccessTicket(serverUrl, roomId, accessTicket, passcode);
```

这段代码位于 Activity，`listener` 是宿主实现的 `AkNativeRtcClient.Listener`，入会信息来自业务后端。调用返回只表示已发起入会；以 `onJoined`、`onError`、媒体状态回调判断结果。SDK 已初始化本地渲染器，宿主不要再次 `init()`。

最少处理 `onJoined`、`onRemoteVideo`、`onRemoteVideoRemoved`、`onError` 和 `onLeft`；界面状态还要处理 `onLocalMediaState` 与 `onMediaPermissionChanged`。这些回调可能不在 UI 线程，更新 Android 视图时切回主线程。先看到远端真实帧并听到远端声音，再测试本机发布。

| 回调/结果 | Activity 应做什么 | 不应误判成什么 |
|---|---|---|
| `onJoined(participantId)` | 记录当前成员身份，展示会议页 | 远端媒体一定已经到达 |
| `onRemoteVideo(publicationId, track)` | 为该路创建 Renderer，绑定 track | 同名成员的所有发布都可共用一个视图 |
| `onLocalMediaState(mic,camera)` | 更新真实麦克风/相机按钮 | 点击按钮就等于启停成功 |
| `onMediaPermissionChanged(kind,allowed)` | 解释主持限制，禁止无效操作 | 主持解禁会自动打开设备 |
| `onContinuousRecordingChanged(recording)` | 显示当前录制状态或空状态 | 返回 `Stopping` 就已经有可下载文件 |
| `onHttpError(error)` | 保留状态码，401 重新取票、403 显示权限 | 无限自动重试旧票据 |

## 画面、声音和生命周期

远端 `onRemoteVideo(publicationId, VideoTrack)` 到达时，为这一路建立渲染视图并绑定轨道；`onRemoteVideoRemoved` 只移除对应发布。切换麦克风、相机或输出设备时用 SDK 返回的真实设备 ID，最后以状态回调确定是否生效。

屏幕共享依赖系统 MediaProjection 授权和前台服务；宿主按 SDK 控制器要求转交 Activity 生命周期与授权结果。选择附件等外部 Activity 期间应保留会议状态。正常离会调用 `leave()`，最终销毁调用 `close()`，不能只移除页面上的 video 控件。

后台恢复时分别核对成员是否仍在线、本机发送帧和接收端解码帧。某些 Android 设备可能限制后台相机或麦克风；前台服务和悬浮小窗出现，不代表媒体一定持续发送。用第二台设备看画面和听声音，必要时记录采集/发送统计。

`onContinuousRecordingChanged` 通知录制状态，主持人可调用 `startContinuousRecording(RoomCallback)` 与 `stopContinuousRecording(recordingId, RoomCallback)`；普通成员用 `getContinuousRecording(RoomCallback)` 查询。SDK 只给出数据，录制和回放按钮由宿主实现。这些接口已进入 匹配目标版本 对应源码和发布包，安装旧 APK 不会自动具备。全部公开函数的入参、回调和特殊情况见[Android 函数参考](android-api.md)。

完整依赖版本、线程与系统授权细节以交付包内 Android SDK README 和实际 AAR 为准。上线前按[端侧验收清单](acceptance.md)安装真机包验证。

如果 App 一直显示重连，先确认配置的服务器地址是手机可到达的 HTTPS 地址，而不是开发电脑自己的 `127.0.0.1`；再分别检查证书、房间票据、WebSocket 和媒体端口。安装被系统取消应先解决安装确认，不能把旧安装包的行为当作新 SDK 的结果。