Agora 声网 - Cocos API

基础库 3.10.0 开始支持，低版本需要做兼容处理

与Cocos 游戏引擎的声网API保持一致

使用方法

Cocos 接入 Agora Voice 的方式不变，导出小游戏后，需要按以下步骤引入:

1. 在游戏包根目录下执行 npm install small-game-lib-agora 命令;
2. 引入 SDK：

// 引入 cocos adapter:
require('adapter-min.js');
// 引入B站小游戏 adapter:
require('blapp-adapter-cocos.js'); // * 具体参考文档：快速开始/引擎导出/Cocos;
// 引入声网 SDK：
require('./node_modules/small-game-lib-agora'); // 1）注意这里要带上 node_modules 一层目录！
                                                // 2）一定要在 cocos 框架文件之前引入！
// 初始化 adapter:
__globalAdapter.init();
// 引入 cocos 框架:
require('cocos/cocos2d-js-min.js');
// 其他代码，关于如何初始化声网 SDK，请参见 文后 Demo
// ...

3. 初始化（详见 注意事项 和 文后 Demo）

注意事项

在b站小游戏环境下使用声网服务，需要使用bl.loadAgora能力确保声网服务已经载入，详细使用请看 文后 Demo

由于声网SDK的一些局限性（仅支持存在一个实例），为保证 bilibili App 的其他业务使用声网服务正常，在小游戏进入到后台（拉起控制中心，点击Home键盘，右上角暂停按钮等），会销毁声网服务的实例，接入方需要重新初始化声网服务，并做一些恢复逻辑，详见 文后 Demo

agora的部分功能，需要提供参数，如果由于某些异常情况导致未传参数，会返回错误Code：103，如果agora未初始化，调用其他功能会返回错误Code：7000

接口说明

agora.init(appid)

初始化 Agora，在整个应用全局，开发者只需要对引擎做一次初始化。

agora.setChannelProfile(profile)

设置频道属性

参数

agora.setClientRole(role)

设置用户角色

参数

agora.joinChannel(token, channelId, [info], [uid])

加入频道

参数

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的应用程序是不能互通的。如果已在通话中，用户必须调用 agora.leaveChannel() 退出当前通话，才能进入下一个频道。 同一个频道里不能出现两个相同的 UID。如果你的 App 支持多设备同时登录，即同一个用户账号可以在不同的设备上同时登录(例如微信支持在 PC 端和移动端同时登录)，请保证传入的 UID 不相同。 例如你之前都是用同一个用户标识作为 UID, 建议从现在开始加上设备 ID, 以保证传入的 UID 不相同 。如果你的 App 不支持多设备同时登录，例如在电脑上登录时，手机上会自动退出，这种情况下就不需要在 UID 上添加设备 ID。

agora.leaveChannel()

离开频道 离开频道，即挂断或退出通话。 joinChannel 后，必须调用 leaveChannel 以结束通话，否则不能进行下一次通话。不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。如果成功，则返回值为 0。leaveChannel 会把会话相关的所有资源释放掉。 leaveChannel 是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。

agora.enableAudio()

打开音频

该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。

agora.muteLocalAudioStream(mute)

将自己静音

参数

静音/取消静音。该方法用于允许/禁止往网络发送本地音频流。

agora.enableLocalAudio(enabled)

关闭/重启本地语音功能

参数

当用户加入频道时，语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能，停止或重新开始本地音频采集及处理。 该方法不影响接收或播放远端音频流，适用于只听不发的用户场景。

该方法需要在 joinChannel 之后调用才能生效。 该方法与 muteLocalAudioStream 的区别在于：

• enableLocalAudio：开启或关闭本地语音采集及处理
• muteLocalAudioStream：停止或继续发送本地音频流

agora.muteAllRemoteAudioStreams(mute)

静音所有远端音频

参数

该方法用于允许/禁止播放远端用户的音频流，即对所有远端用户进行静音与否。

agora.muteRemoteAudioStream(uid, mute)

静音指定用户音频

参数

静音指定远端用户/对指定远端用户取消静音。

如果之前有调用过 muteAllRemoteAudioStreams (true) 对所有远端音频进行静音，在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false) 。 muteAllRemoteAudioStreams 是全局控制，muteRemoteAudioStream 是精细控制。

agora.enableAudioVolumeIndication(interval, smooth)

启用说话者音量提示

agora.enableAudioVolumeIndication(1000, 3)

参数

该方法允许 SDK 定期向应用程序反馈当前谁在说话以及说话者的音量。启用该方法后，无论频道内是否有人说话，都会在 onAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

agora.adjustRecordingSignalVolume(volume)

调节录音信号音量

参数

agora.adjustPlaybackSignalVolume(volume)

调节播放信号音量

参数

该方法调节录音信号音量。

agora.setDefaultAudioRouteToSpeakerphone(bVal)

修改默认的语音路由

参数

• 该方法只在纯音频模式下工作，在有视频的模式下不工作。
• 该方法需要在 joinChannel 前设置，否则不生效。 如有必要，调用该方法修改默认的语音路由。默认的语音路由如下:

已调用 disableVideo 或 已调用 muteLocalVideoStream 或 muteAllRemoteVideoStreams

agora.setParameters(profile)

自定义参数

参数

通过 JSON 配置 SDK 提供技术预览或特别定制功能。

agora.getVersion()

查询 SDK 版本号 该方法返回 SDK 版本号的字符串。

agora.setLogFile(filePath)

设置日志文件

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。应用程序必须保证指定的目录存在而且可写。

agora.setLogFilter(filter)

设置日志过滤器等级

参数

设置 SDK 的输出日志过滤等级。不同的过滤等级可以单独或组合使用 日志级别顺序依次为 OFF_、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。 例如，你选择 WARNING 级别，就可以看到在 CRITICAL、_ERROR 和 WARNING 级别上的所有日志信息。

agora.on(event, callback, target)

监听事件信息

加入频道成功回调

agora.on('join-channel-success', (channel, uid, elapsed) => {}, this);

回调参数

说话声音音量提示回调

agora.on('audio-volume-indication', (speakers, speakerNumber, totalVolume) => {}, this);

回调参数

发生错误回调

agora.on('error', (err, msg) => {}, this)

回调参数

离开频道回调

agora.on('leave-channel', (stat) => {}, this)

回调参数

其他用户加入当前频道回调

agora.on('user-joined', (uid, elapsed) => {}, this);

回调参数

其他用户离开当前频道回调

agora.on('user-offline', (uid, reason) => {}, this);

回调参数

用户被静音回调

agora.on('user-mute-audio', (uid, muted) => {}, this);

回调参数

网络中断回调

agora.on('connection-interrupted', () => {}, this);

Token 过期回调

agora.on('request-token', () => {}, this);

上下麦回调

agora.on('client-role-changed', (oldRole, newRole) => {}, this);

回调参数

重新加入频道成功回调

agora.on('rejoin-channel-success', (channel, uid, elapsed) => {}, this);

回调参数

声音质量回调

agora.on('audio-quality', (uid, quality, delay, lost) => {}, this);

回调参数

发生警告回调

agora.on('warning', (warn, msg) => {}, this);

回调参数

频道内网络质量报告回调

agora.on('network-quality', (uid, txQuality, rxQuality) => {}, this);

回调参数

声音路由发生变化

agora.on('audio-routing-changed', (routing) => {}, this);

连接丢失回调

agora.on('connection-lost', () => {}, this);

连接已被禁止回调

agora.on('connection-banned', () => {}, this);

agora 初始化成功

agora.on("init-success", () => {}, this);

录音设备发生变化回调

agora.on('recording-device-changed', (state, device) => {}, this);

回调参数

声网 SDK 初始化 Demo

let channelId = ''; // 用于临时存储当前已加入的房间
// **必须** 先确保 Agora 模块已载入
let agoraSDKLoaded = false;

function loadAgoraSDK() {
    return new Promise((resolve, reject) => {
        if (agoraSDKLoaded) {
            resolve();
            return;
        }
        bl.loadAgora({
            success() {
                agoraSDKLoaded = true;
                resolve();
            },
            fail: reject
        });
    });
}

// 调用 Agora 能力前**必须**先授权录音权限
function authorizeRecord() {
    return new Promise((resolve, reject) => {
        bl.authorize({
            scope: 'scope.record',
            success: resolve,
            fail: reject
        });
    });
}

// 每次打开时需要恢复声网 SDK：
bl.onShow(() => {
    // 在这里恢复引擎、以及加入过的房间
    loadAgoraSDK()
        .then(authorizeRecord)
        .then(() => {
            agora.init( /*<Agora AppId>*/ );
            if (channelId.length > 0) {
                agora.on('join-channel-success', () => {
                    // 加入成功逻辑处理
                });
                agora.joinChannel('', channelId, '', '<用户 ID>');
            }
        })
        .catch(err => {
            // 处理异常
        });
});

// 每次离开时记录当前的房间，以备下次打开时重新进入：
bl.onHide(() => {
    channelId = '<当前房间 ID>';
});