文档

iOS端集成

更新时间:

互动消息是用于加强直播间消息沟通、提升交互体验的服务。提供了丰富、易集成的SDK,可在用户开发的直播应用中轻松集成评论、弹幕、点赞等能力。本文介绍iOS端集成互动消息的操作步骤。

前提条件

客户端集成前,请确保已经完成服务端集成,并提供客户端访问的获取鉴权Token的接口。服务端集成指引请参见服务端集成

环境要求

  • Xcode 12.0及以上版本,推荐使用最新正式版本

  • CocoaPods 1.9.3及以上版本

  • 真机调试需iOS 10.0及以上版本

集成SDK

  1. 在Podfile文件中添加依赖,SDK名称及版本依赖如下:

    pod 'AliVCInteractionMessage', '~> 1.3.0'
  2. 执行pod install --repo-update

使用SDK

SDK使用需遵循如下操作顺序:

  1. 初始化

  2. 登录

  3. 相关操作

  4. 登出

  5. 反初始化

其中相关操作包含群组操作和消息操作,详细说明如下:

相关操作

  • 群组操作

    • 创建群组(需要以管理员身份进行登录才能操作)

    • 关闭群组(仅限群主/群管理员操作)

    • 进入群组

    • 离开群组

    • 查询群组信息

    • 修改群组信息(仅限群主/群管理员操作)

    • 查询群组最近成员列表

    • 查询群组全部成员(仅限群主/群管理员操作)

    • 对群组进行禁言(仅限群主/群管理员操作)

    • 对群组取消禁言(仅限群主/群管理员操作)

    • 对群组的用户进行禁言(仅限群主/群管理员操作)

    • 对群组的用户取消禁言(仅限群主/群管理员操作)

    • 查询群组内被禁言的用户列表(仅限群主/群管理员操作)

  • 消息操作

    • 单发消息

    • 群发消息

    • 查询最近群发消息列表

    • 查询全部群发消息(仅限群主/群管理员操作)

    • 删除/撤回群消息

    • 查询历史消息

引入头文件

在调用API之前,请确保已经引入头文件。

#import <AliVCInteractionMessage/AliVCInteractionMessage.h>

初始化

在使用SDK前需要进行初始化,可以在相关业务模块的主入口设置。

展开查看代码

// setup初始化
AliVCIMEngineConfig *config = [AliVCIMEngineConfig new];
config.deviceId = @"xxxx";   // 设备id,可以使用该系统方法进行获取:[[UIDevice currentDevice] identifierForVendor].UUIDString;
config.appId = @"APP_ID";    // 开通应用后可以在控制台上拷贝
config.appSign = @"APP_SIGN"; // 开通应用后可以在控制台上拷贝
config.logLevel = AliVCIMLogLevelDebug; // 在Debug时设置
int ret = [[AliVCIMEngine sharedEngine] setup:config]; // 初始化返回非0,表示初始化失败,其中1001:重复初始化、1002:创建底层引擎失败、-1:底层重复初始化、-2:初始化配置信息有误
NSLog(@"API - setup result: %d", ret);


// 添加监听
[[AliVCIMEngine sharedEngine] addListener:self];


// 处理回调事件  AliVCIMEngineListenerProtocol
- (void)onIMEngineConnecting {
    NSLog(@"Event - onIMEngineConnecting");
}

- (void)onIMEngineConnectSuccess {
    NSLog(@"Event - onIMEngineConnectSuccess");
}

- (void)onIMEngineConnectFailed:(NSError *)error {
    NSLog(@"Event - onIMEngineConnectFailed error: %@", error);
}

- (void)onIMEngineDisconnect:(AliVCIMEngineDisconnectType)type {
    NSLog(@"Event - onIMEngineDisconnect: %d", type);
}

- (void)onIMEngineTokenExpired:(AliVCIMFetchAuthTokenBlock)fetchAuthTokenBlock {
    NSLog(@"Event - onIMEngineTokenExpired");
    // 需要你的服务端集成后,并提供给客户端的获取鉴权信息接口,客户端通过该接口返回后获取nonce和token
    if (fetchAuthTokenBlock) {
        AliVCIMAuthToken *auth = [AliVCIMAuthToken new];
        auth.timestamp = 22123123;  // 服务端返回timestamp值
        auth.nonce = @"xxx";        // 服务端返回nonce值
        auth.role = @"admin";       // admin角色,可以创建/关闭群组,如果不需要可以设置为空
        auth.token = @"xxx"         // 服务端返回token值
        fetchAuthTokenBlock(auth, nil);
    }
}

登录

登录需要鉴权信息,请确保提交,通过服务端获取到鉴权信息,包括:timestamp、nonce、token等值。

展开查看代码

AliVCIMUser *user = [AliVCIMUser new];
user.userId = @"abc";  // 当前app登录的用户id,最长64位,仅限于A~Z,a~z, 0~9及“-”, 不能包含其他字符
user.userExtension = @"{}"; // 用户扩展信息,可以是头像、昵称等封装为json字符串
AliVCIMAuthToken *auth = [AliVCIMAuthToken new];
auth.timestamp = 122222; // 服务端返回timestamp值
auth.nonce = @"xxx";     // 服务端返回nonce值
auth.role = @"admin";    // admin角色,可以创建/关闭群组,如果不需要可以设置为空
auth.token = @"xxx";     // 服务端返回token值
AliVCIMLoginReq *req = [AliVCIMLoginReq new];
req.currentUser = user;
req.authToken = auth;
[[AliVCIMEngine sharedEngine] login:req completed:^(NSError * _Nullable error) {
    NSLog(@"API - login result: %@", error ? error.description : @"success");
    if (!error) {
        // 登录成功
    }
}];

群组操作

获取群组管理器

// 必须确保已经初始化,否则会返回空值
AliVCIMGroupManager *groupManager = [[AliVCIMEngine sharedEngine] getGroupManager];

添加和移除群组操作监听器

// 在适当的时机(例如进入房间后,且完成登录后)添加群组操作事件监听器
[[[AliVCIMEngine sharedEngine] getGroupManager] addListener:self];

// 如不需要时,需要移除监听器
[[[AliVCIMEngine sharedEngine] getGroupManager] removeListener:self];

// 处理群组事件 AliVCIMGroupListenerProtocol
- (void)imGroup:(NSString *)groupId onJoined:(AliVCIMUser *)user {
    // 有人进入群组
    NSLog(@"Event - imGroup:%@ onJoin: %@", groupId, user);
}

- (void)imGroup:(NSString *)groupId onLeaved:(AliVCIMUser *)user {
    // 有人离开了群组
    NSLog(@"Event - imGroup:%@ onLeave: %@", groupId, user);
}

- (void)imGroup:(NSString *)groupId onExited:(int)reason {
    // 群组被关闭了
    NSLog(@"Event - imGroup:%@ onExited: %d", groupId, reason);
}

- (void)imGroup:(NSString *)groupId onInfoChanged:(AliVCIMGroupInfoStatus *)status {
    // 群组的信息发生了变化
    NSLog(@"Event - imGroup:%@ onInfoChanged: %@", groupId, status);
}

- (void)imGroup:(NSString *)groupId onMuteChanged:(AliVCIMGroupMuteStatus *)status {
    // 群组的禁言状态发生了变化
    NSLog(@"Event - imGroup:%@ onMuteChanged: %@", groupId, status);
}

创建群组

需要以管理员身份进行登录才能调用成功。

AliVCIMCreateGroupReq *req = [AliVCIMCreateGroupReq new];
req.groupId = nil;   // 群组id,为空时,系统创建新群组后会返回唯一id;不为空时,groupId最长64位,仅限于A~Z,a~z, 0~9及“-”, 不能包含其他字符
req.groupName = @"xxx"; // 群组昵称,一定要设置,否则会失败
req.groupMeta = @"xxx"; // 群组扩展信息,如果有多个字段可以考虑封装为json字符串
[[[AliVCIMEngine sharedEngine] getGroupManager] createGroup:req completed:^(AliVCIMCreateGroupRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - createGroup rsp: %@", rsp);
    }
}];

关闭群组

仅限群主/管理员调用,否则会调用失败。

AliVCIMCloseGroupReq *req = [AliVCIMCloseGroupReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] closeGroup:req completed:^(NSError * _Nullable error) {
    
}];

进入群组

AliVCIMJoinGroupReq *req = [AliVCIMJoinGroupReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] joinGroup:req completed:^(AliVCIMJoinGroupRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - joinGroup rsp: %@", rsp);
    }
}];

离开群组

AliVCIMLeaveGroupReq *req = [AliVCIMLeaveGroupReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] leaveGroup:req completed:^(NSError * _Nullable error) {

}];

查询群组信息

AliVCIMQueryGroupReq *req = [AliVCIMQueryGroupReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] queryGroup:req completed:^(AliVCIMQueryGroupRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - queryGroup rsp: %@", rsp);
    }
}];

修改群组信息

支持修改群扩展信息和设置管理员,仅限群主/群管理员调用,否则会调用失败。

AliVCIMModifyGroupReq *req = [AliVCIMModifyGroupReq new];
req.groupId = @"xxx";  // 群组id
req.groupMeta = @"xxx";  // 添加群拓展信息;若需要清空,则不需要设置,同时设置req.forceUpdateGroupMeta=YES;
req.admins = @[@"xxx"];  // 指定群管理员ID列表,最多设置3个管理员;若需要清空列表,则配置空列表(不需要设置即可),同时设置req.forceUpdateAdmins=YES;
[[[AliVCIMEngine sharedEngine] getGroupManager] modifyGroup:req completed:^(NSError * _Nullable error) {

}];

查询群组最近成员列表

AliVCIMListRecentGroupUserReq *req = [AliVCIMListRecentGroupUserReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] listRecentGroupUser:req completed:^(AliVCIMListRecentGroupUserRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - listRecentGroupUser rsp: %@", rsp);
    }
}];

查询群组全部成员

仅限群主/群管理员调用,否则会调用失败。

AliVCIMListGroupUserReq *req = [AliVCIMListGroupUserReq new];
req.groupId = @"xxx";  // 群组id
req.nextPageToken = @"xxx";  //不传时表示第一页,遍历时服务端会返回下一页Token,客户端获取下一页时应带上
req.pageSize = 10;
req.sortType = AliVCIMSortType_ASC;
[[[AliVCIMEngine sharedEngine] getGroupManager] listGroupUser:req completed:^(AliVCIMListGroupUserRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - listGroupUser rsp: %@", rsp);
    }
}];

对群组进行禁言

仅限群主/群管理员调用,否则会调用失败。

AliVCIMMuteAllReq *req = [AliVCIMMuteAllReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] muteAll:req completed:^(NSError * _Nullable error) {

}];

对群组取消禁言

仅限群主/群管理员调用,否则会调用失败。

AliVCIMCancelMuteAllReq *req = [AliVCIMCancelMuteAllReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] cancelMuteAll:req completed:^(NSError * _Nullable error) {

}];

对群组的用户进行禁言

仅限群主/群管理员调用,否则会调用失败。

AliVCIMMuteUserReq *req = [AliVCIMMuteUserReq new];
req.groupId = @"xxx";  // 群组id
req.userList = @[@"xxx"]; // 需要禁言的用户id列表
[[[AliVCIMEngine sharedEngine] getGroupManager] muteUser:req completed:^(NSError * _Nullable error) {

}];

对群组的用户取消禁言

仅限群主/群管理员调用,否则会调用失败。

AliVCIMCancelMuteUserReq *req = [AliVCIMCancelMuteUserReq new];
req.groupId = @"xxx";  // 群组id
req.userList = @[@"xxx"]; // 需要取消禁言的用户id列表
[[[AliVCIMEngine sharedEngine] getGroupManager] cancelMuteUser:req completed:^(NSError * _Nullable error) {

}];

查询群组内被禁言的用户列表

仅限群主/群管理员调用,否则会调用失败。

AliVCIMListMuteUsersReq *req = [AliVCIMListMuteUsersReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getGroupManager] listMuteUsers:req completed:^(AliVCIMListMuteUsersRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - listMuteUsers rsp: %@", rsp);
    }
}];

消息操作

获取消息管理器

// 必须确保已经初始化,否则会返回空值
AliVCIMMessageManager *messageManager = [[AliVCIMEngine sharedEngine] getMessageManager];

添加和移除群组操作监听器

// 在适当的时机(例如进入房间后,且完成登录后)添加消息操作事件监听器
[[[AliVCIMEngine sharedEngine] getMessageManager] addListener:self];

// 如不需要时,需要移除监听器
[[[AliVCIMEngine sharedEngine] getMessageManager] removeListener:self];

// 处理消息事件 AliVCIMMessageListenerProtocol
- (void)onIMReceivedC2CMessage:(AliVCIMMessage *)message {
    // 收到其他用户发来的单聊消息
    NSLog(@"Event - onIMReceivedC2CMessage: %@", message);
}

- (void)onIMReceivedGroupMessage:(AliVCIMMessage *)message {
    // 收到群聊消息
    NSLog(@"Event - onIMReceivedGroupMessage: %@", message);
}

- (void)onIMDeleteMessage:(NSString *)messageId groupId:(NSString *)groupId {
    // 消息被撤回/删除
    NSLog(@"Event - onIMDeleteMessage:%@ groupId: %@", messageId, groupId);

单发消息

AliVCIMSendMessageToUserReq *req = [AliVCIMSendMessageToUserReq new];
req.reveiverId = @"xxx";   // 接受者id,需确保对方在线,否则会返回错误码424,此时建议待对方上线后再重发
req.data = @"xxx";         // 发送消息内容,如果是结构化可考虑使用json字符串
req.type = 88888;          // 自定义消息类型,需大于10000
req.skipAudit = YES;       // 跳过安全审核,YES:发送的消息不经过阿里云安全审核服务审核;NO:发送的消息经过阿里云安全审核服务审核,审核失败则不发送。
req.level =  AliVCIMMessageLevel_Normal; // 消息分级,需要高可靠时,使用AliVCIMMessageLevel_High
[[[AliVCIMEngine sharedEngine] getMessageManager] sendC2CMessage:req completed:^(AliVCIMSendMessageToUserRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - sendC2CMessage rsp: %@", rsp);
    }
}];

群发消息

//需确保已经加入群成功(即在joinGroup回调成功之后),再发送群组消息,否则会返回错误码425
AliVCIMSendMessageToGroupReq *req = [AliVCIMSendMessageToGroupReq new];
req.groupId = @"xxx";     // 群组id
req.data = @"xxx";        // 发送消息内容,如果是结构化可考虑使用json字符串
req.type = 99999;         // 自定义消息类型,需大于10000
req.skipMuteCheck = YES;  // 跳过禁言检测,YES:忽略被禁言用户,还可发消息;NO:当被禁言时,消息无法发送
req.skipAudit = YES;      // 跳过安全审核,YES:发送的消息不经过阿里云安全审核服务审核;NO:发送的消息经过阿里云安全审核服务审核,审核失败则不发送。
req.level =  AliVCIMMessageLevel_Normal; // 消息分级,需要高可靠时,使用AliVCIMMessageLevel_High
req.noStorage = YES; // YES:表示该消息不需要存储,也无法拉取查询;NO:消息进行存储,可以拉取查询。如果在直播间的弹幕场景,需要设置为NO
req.repeatCount = 1; // 本消息重复数量,默认1。内容完成一样的消息可以使用该字段进行聚合,并发送一次即可。
[[[AliVCIMEngine sharedEngine] getMessageManager] sendGroupMessage:req completed:^(AliVCIMSendMessageToGroupRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - sendGroupMessage rsp: %@", rsp);
    }
}];

删除/撤回群消息

AliVCIMDeleteMessageReq *req = [AliVCIMDeleteMessageReq new];
req.groupId = @"xxx";        // 群组id
req.messageId = @"yyy"; // 消息id
NSLOG(@"API - deleteMessage req: %@", req);
[[[AliVCIMEngine sharedEngine] getMessageManager] deleteMessage:req completed:^(NSError * _Nullable error) {
    NSLOG(@"API - deleteMessage result: %@", error ? error.description : @"success");
}];

查询最近群发消息列表

AliVCIMListRecentMessageReq *req = [AliVCIMListRecentMessageReq new];
req.groupId = @"xxx";  // 群组id
[[[AliVCIMEngine sharedEngine] getMessageManager] listRecentMessage:req completed:^(AliVCIMListRecentMessageRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - listRecentMessage rsp: %@", rsp);
    }
}];

查询全部群发消息

仅限群主/群管理员调用,否则会调用失败。

AliVCIMListMessageReq *req = [AliVCIMListMessageReq new];
req.groupId = @"xxx";        // 群组id
req.nextPageToken = @"xxx";  //不传时表示第一页,遍历时服务端会返回下一页Token,客户端获取下一页时应带上
req.type = 99999;            // 自定义消息类型,需大于10000
req.sortType = AliVCIMSortType_ASC;
req.pageSize = 20;
[[[AliVCIMEngine sharedEngine] getMessageManager] listMessage:req completed:^(AliVCIMListMessageRsp * _Nullable rsp, NSError * _Nullable error) {
    if (rsp) {
        // 成功
        NSLog(@"API - listMessage rsp: %@", rsp);
    }
}];

查询历史消息

AliVCIMListHistoryMessageReq *req = [[AliVCIMListHistoryMessageReq alloc] init];
req.groupId = gid;  // 群id
req.nextPageToken = @"xxx";  //不传时表示第一页,遍历时服务端会返回下一页Token,客户端获取下一页时应带上
req.type = 99999;            // 自定义消息类型,需大于10000
req.sortType = AliVCIMSortType_ASC;
req.pageSize = 20;
req.beginTime = 0; // 按时间范围遍历,开始时间,单位秒,为0时表示最早时间
req.endTime = 0;   // 按时间范围遍历,结束时间,单位秒,为0时表示最晚时间
NSLOG(@"API - listHistoryMessage req: %@", req);
[[[AliVCIMEngine sharedEngine] getMessageManager] listHistoryMessage:req completed:^(AliVCIMListHistoryMessageRsp * _Nullable rsp, NSError * _Nullable error) {
    NSLOG(@"API - listHistoryMessage result: %@", error ? error.description : @"success");
    if (rsp) {
        NSLOG(@"API - listHistoryMessage rsp: %@", rsp);
    }
}];

登出

[[AliVCIMEngine sharedEngine] logout:^(NSError * _Nullable error) {
    NSLog(@"API - logout result: %@", error ? error.description : @"success");
}];

反初始化

登出后如无需再进行登录,可以进行反初始化操作,SDK会对底层操作实例进行释放。

int ret = [[AliVCIMEngine sharedEngine] destroy];
NSLog(@"API - destroy result: %d", ret);
  • 本页导读 (1)