SDKsiOS

发送自定义信令

使用 OpenIM iOS SDK 在通话房间中发送和接收自定义信令。

调用自定义信令发送接口向指定通话房间发送轻量级业务协商数据，例如举手、切换布局提示或业务侧的状态同步。它不是聊天消息接口，也不能替代音视频媒体引擎的数据通道。

参数说明

参数	类型	说明
`roomID`	`NSString *`	当前通话房间 ID，必须与发送方正在处理的通话一致。
`customInfo`	`NSString *`	业务自定义字符串。使用 JSON 序列化时建议包含协议版本和业务幂等 ID。

NSDictionary *signal = @{
    @"version": @1,
    @"eventID": NSUUID.UUID.UUIDString.lowercaseString,
    @"type": @"hand-raised",
    @"userID": currentUserID,
    @"sentAt": @((NSInteger64)(NSDate.date.timeIntervalSince1970 * 1000)),
};

NSData *data = [NSJSONSerialization dataWithJSONObject:signal options:0 error:nil];
NSString *customInfo = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];

[[OIMManager manager] signalingSendCustomSignal:roomID
                                      customInfo:customInfo
                                       onSuccess:^{
    [self markSignalSubmitted:signal[@"eventID"]];
}
                                       onFailure:^(NSInteger code, NSString * _Nullable message) {
    [self showCallError:code message:message ?: @"发送自定义信令失败"];
}];

通话状态以 roomID 为合并标识，参与者状态同时结合用户 ID。

返回结果

成功回调 onSuccess 表示服务端已接受本次信令请求并向房间广播，不等于其他参与者已经处理完毕。自定义信令适合轻量、临时的通话协商，不提供大文件、聊天记录或长期状态的传输与保存能力。

接收信令

实现 OIMSignalingListener 的 onReceiveCustomSignal: 回调方法接收自定义信令。公开 delegate 提供原始字符串，应用需按照多端共同约定的数据格式解析 JSON，再校验房间与业务协议：

@interface CallSignalStore () <OIMSignalingListener>
@end

@implementation CallSignalStore

- (void)startListening {
    [[OIMManager callbacker] addSignalingListener:self];
}

- (void)stopListening {
    [[OIMManager callbacker] removeSignalingListener:self];
}

- (void)onReceiveCustomSignal:(NSString *)rawSignal {
    NSDictionary *signal = [self parseAndValidateCallSignal:rawSignal];
    if (signal == nil) return;
    if (![signal[@"roomID"] isEqualToString:self.activeRoomID]) return;
    if ([self hasAppliedSignal:signal[@"eventID"]]) return;

    [self applySignal:signal];
}

@end

必须使用同一个 listener 实例调用添加与移除监听方法；在退出登录、切换账号或离开通话界面时及时移除。

由于接收回调未提供独立的外层 roomID 字段，若业务需要按房间过滤，发送端应把 roomID 写入自定义协议载荷，并在接收端验证其与当前房间一致。建议使用协议中的 eventID 进行幂等去重，避免依赖事件到达顺序。

信令与持久状态

自定义信令只提供实时通知，不是可查询的持久业务状态。页面重新进入、设备离线或 listener 尚未注册时，都可能无法仅凭它恢复完整状态。需要稍后恢复的数据可通过业务数据或普通消息能力承载；需要确认通话房间和当前参与者时，使用查询群组通话房间重新查询。

这个页面有帮助吗？