文档中心

setGameQueryAudioOptionsListener ​

设置音频选项查询监听器 ​

setGameQueryAudioOptionsListener: 是 SUDRTGameAudioSession 协议中的策略注入方法。它用于在 App 与游戏引擎之间建立一个音频属性协商通道。当游戏引擎需要确定某些关键音频行为（如是否允许混音、是否强制开启扬声器）时，会通过此监听器向 App 发起询问。

方法声明 ​

objc
/**
 * 设置音频选项查询监听器。
 * @param listener 实现了 SUDRTGameQueryAudioOptionsListener 协议的对象。传入 nil 则移除监听。
 */
- (void)setGameQueryAudioOptionsListener:(nullable id<SUDRTGameQueryAudioOptionsListener>)listener;

运行行为 ​

  1. 策略委托：调用此方法后，SDK 将音频策略的决定权移交给 App。每当音频环境初始化或配置变更时，SDK 会触发监听器的 onQueryAudioSession:appId:options: 回调。
  2. 异步协商：App 收到回调后，可以根据当前业务状态（例如：是否正在直播、是否处于后台）动态调整音频选项，并通过 handle 告知 SDK。
  3. 覆盖默认值：如果未设置监听器，SDK 通常会采用一套预设的保守音频配置。设置监听器后，App 可以精细化定制每一项 SUDRT_KEY_AUDIO_ 开头的配置。

代码示例 ​

配置监听器以动态处理游戏音频策略：

objc
- (void)configureAudioSession {
    // 1. 将当前类（或专门的音频管理器）设置为监听器
    [self.audioSession setGameQueryAudioOptionsListener:self];
}

#pragma mark - SUDRTGameQueryAudioOptionsListener

- (void)onQueryAudioSession:(id<SUDRTGameQueryAudioOptionsHandle>)handle 
                      appId:(NSString *)appId 
                    options:(NSDictionary *)options {
    
    // 2. 模拟业务判断：如果当前 App 正在播放背景音乐，则允许游戏混音
    BOOL shouldMix = YES; 
    
    // 3. 通过 handle 返回最终决策结果
    // 这里的 success:YES 表示 App 已处理该请求
    [handle complete:shouldMix error:nil];
}

注意事项 ​

  • 必须闭环：在监听器的回调方法中，务必调用 [handle complete:error:]。如果不调用，SDK 可能会因为无法获取音频策略而导致游戏声音初始化卡死或无声。
  • 强弱引用建议：虽然协议声明为 nullable，但 SDK 内部通常不会对 listener 进行强引用。建议 App 侧使用专门的单例或生命周期稳定的对象（如 AudioManager）来持有监听逻辑。
  • 解绑时机：当退出游戏房间或销毁游戏实例时，建议调用 [session setGameQueryAudioOptionsListener:nil] 以解除引用，防止不必要的内存占用或回调污染。