用户管理 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

用户管理

更新时间： 2024/11/05 16:24:35

网易云信即时通讯 SDK（NetEase IM SDK，简称 NIM SDK）提供用户信息的托管，实现用户资料和黑名单的统一管理和共享。

支持平台

本文内容适用的开发平台或框架如下表所示：

Android	iOS	macOS/Windows	Web/uni-app/小程序	HarmonyOS	Flutter
✔️️️️	✔️️️️	✔️️️️	✔️️️️	✔️️️️	✔️️️️

技术原理

NIM SDK 支持更新自己的用户信息，更新自己的黑名单列表等操作，其中用户资料包括用户昵称、性别、头像、签名、手机、邮箱、生日等信息。

对于用户黑名单，如果一个用户被加入了黑名单，那么就不再会收到此用户发送的任何消息。如果一个用户被从黑名单移除，那么会重新收到此用户发送的消息。

NIM SDK 会将用户资料缓存到本地，但是除自身的资料外，SDK 不保证其他用户资料的实时更新。以下事件会触发其他用户资料的更新：

登录时会同步好友用户资料（注册数据同步 addLoginDetailListener.onDataSync 回调，完成会发出通知）。
收到其他用户发来消息时，如果消息发送者的用户资料有更新，则 SDK 会同步更新对方的用户资料。
直接调用 SDK 接口从服务器拉取最新的用户资料，具体请参考本文的获取用户资料。

如果既不是好友，也未收到该用户发送的消息，则 SDK 不会更新对方的用户资料。
如果需要同步的用户资料较多，SDK 的同步时间会相对较长。

前提条件

已实现登录 IM。

监听用户相关事件

在进行用户相关操作前，您可以提前注册相关事件。注册成功后，当用户相关事件发生时，SDK 会触发对应回调通知。

用户相关回调：

onUserProfileChanged：用户资料变更回调，返回变更的用户资料列表。
onBlockListAdded：黑名单新增用户回调，返回新加入黑名单的用户列表。当客户端本端添加用户到黑名单，或者其他端同步添加用户到黑名单时触发该回调。
onBlockListRemoved：黑名单移除用户回调，返回移出黑名单的用户列表。当客户端本端从黑名单移除用户，或者其他端同步从黑名单移除用户时触发该回调。

调用方法注册用户相关监听器，监听用户资料变更、黑名单新增以及移出黑名单等事件。

Android/iOS/macOS/Windows：addUserListener

示例代码：

Android

JavaNIMClient.getService(V2NIMUserService.class).addUserListener(new V2NIMUserListener() {
    @Override
    public void onUserProfileChanged(List<V2NIMUser> users) {

    }

    @Override
    public void onBlockListAdded(V2NIMUser user) {

    }

    @Override
    public void onBlockListRemoved(String accountId) {

    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] addUserListener:self];
- (void)onUserProfileChanged:(NSArray<V2NIMUser *> *)users {
}
- (void)onBlockListAdded:(V2NIMUser *)user {
}
- (void)onBlockListRemoved:(NSString *)accountId {
}

macOS/Windows

C++V2NIMUserListener listener;
listener.onUserProfileChanged = [](std::vector<V2NIMUser> users) {
    // user profile changed
};
listener.onBlockListAdded = [](V2NIMUser user) {
    // user added to blocklist
};
listener.onBlockListRemoved = [](std::string accountId) {
    // user removed from blocklist
};
userService.addUserListener(listener);

如需移除用户相关监听器，可调用 removeUserListener 方法。

Android

JavaNIMClient.getService(V2NIMUserService.class).removeUserListener(listener);

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] removeUserListener:self];

macOS/Windows

C++V2NIMUserListener listener;
// ...
userService.addUserListener(listener);
// ...
userService.removeUserListener(listener);

Web/uni-app/小程序/HarmonyOS：on("EventName")

示例代码：

Web/uni-app/小程序

TypeScriptnim.V2NIMUserService.on("onUserProfileChanged", function (users: V2NIMUser[]) {})
nim.V2NIMUserService.on("onBlockListAdded", function (user: V2NIMUser) {})
nim.V2NIMUserService.on("onBlockListRemoved", function (accountId: string) {})

HarmonyOS

TypeScriptnim.userService.on("onUserProfileChanged", function (users: V2NIMUser[]) {})
nim.userService.on("onBlockListAdded", function (user: V2NIMUser) {})
nim.userService.on("onBlockListRemoved", function (accountId: string) {})

如需移除用户相关监听器，可调用 off("EventName") 方法。

Web/uni-app/小程序

TypeScriptnim.V2NIMUserService.off("onUserProfileChanged", function (users: V2NIMUser[]) {})
nim.V2NIMUserService.off("onBlockListAdded", function (user: V2NIMUser) {})
nim.V2NIMUserService.off("onBlockListRemoved", function (accountId: string) {})

HarmonyOS

TypeScriptnim.userService.off("onUserProfileChanged", function (users: V2NIMUser[]) {})
nim.userService.off("onBlockListAdded", function (user: V2NIMUser) {})
nim.userService.off("onBlockListRemoved", function (accountId: string) {})

Flutter：add

示例代码：

dartsubsriptions.add(NimCore.instance.userService.onUserProfileChanged.listen((e) {
      //do something
    }));

  subsriptions.add(NimCore.instance.userService.onBlockListAdded.listen((e) {
    //do something
  }));

  subsriptions.add(NimCore.instance.userService.onBlockListRemoved.listen((e) {
    //do something
  }));

如需移除用户相关监听器，可调用 cancel 方法。

示例代码：

dartsubsriptions.forEach((subsription) {
    subsription.cancel();
  });

更新本人用户资料

调用 updateSelfUserProfile 方法更新自己的用户资料。

更新用户资料成功后，SDK 会返回用户资料变更回调 onUserProfileChanged，并同步缓存到本地。

示例代码：

Android

JavaV2NIMUserUpdateParams updateParams = V2NIMUserUpdateParams.V2NIMUserUpdateParamsBuilder.builder()
    .withAvatar(avatar)
    .withBirthday(birthday)
    .withEmail(email)
    .withGender(gender)
    .withMobile(mobile)
    .withName(name)
    .withServerExtension(serverExtension)
    .withSign(sign)
    .build();

NIMClient.getService(V2NIMUserService.class).updateSelfUserProfile(updateParams,
new V2NIMSuccessCallback<List<Void>>() {
    @Override
    public void onSuccess(List<Void> voids) {
        // 处理成功回调
    }
},
new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        // 处理失败回调
    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] updateSelfUserProfile:userService success:^{
    //成功回调
} failure:^(V2NIMError * _Nonnull error) {
    //失败回调
}];

macOS/Windows

C++V2NIMUserUpdateParams updateParams;
updateParams.name = "name";
userService.updateSelfUserProfile(
    updateParams,
    []() {
        // update success
    },
    [](V2NIMError error) {
        // update failed, handle error
    });

Web/uni-app/小程序

TypeScriptnim.V2UserService.updateSelfUserProfile({
    name: 'ab',
});

HarmonyOS

TypeScriptnim.userService.updateSelfUserProfile({
    name: 'ab'
})
    });

Flutter

dartawait NimCore.instance.userService.updateSelfUserProfile(param)

获取用户资料

调用 getUserList 方法根据用户账号 ID 批量查询用户资料列表。

该方法根据用户账号 ID 先从客户端本地获取用户资料数据，若本地数据缺失或不足，再查询服务端中的用户资料数据。

单次最多查询 150 个用户资料。
若传入的账号 ID 都不存在，则调用接口失败。若部分账号 ID 存在，则调用接口成功。调用结果只返回账号 ID 存在的用户资料，错误的账号 ID 不返回。

示例代码：

Android

JavaNIMClient.getService(V2NIMUserService.class).getUserList(accountIds,
    new V2NIMSuccessCallback<List<V2NIMUser>>() {
        @Override
        public void onSuccess(List<V2NIMUser> v2NIMUsers) {
            // TODO: Implement onSuccess logic
        }
    },
    new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            // TODO: Implement onFailure logic
        }
    });

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] getUserList:@[@"accountId1",@"accountId2"] success:^(NSArray<V2NIMUser *> * _Nonnull result) {
    // 成功回调
} failure:^(V2NIMError * _Nonnull error) {
    // 失败回调
}];

macOS/Windows

C++nstd::vector<nstd::string> accountIds = {"test1", "test2"};
userService.getUserList(
    accountIds,
    [](nstd::vector<V2NIMUser> users) {
        for (auto&& user : users) {
            // do something
        }
    },
    [](V2NIMError error) {
        // get user list failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst userProfiles = await nim.V2NIMUserService.getUserList(['accid1', 'accid2'])

HarmonyOS

TypeScriptconst userProfiles = await nim.userService.getUserList(['accid1', 'accid2'])

Flutter

dartawait NimCore.instance.userService.getUserList(accountIds)

根据关键字搜索用户信息

调用 searchUserByOption 方法根据关键字信息搜索用户的资料信息。

该方法默认搜索用户的昵称，若有需要，也可以指定同时搜索用户账号和手机号。

示例代码：

Android

JavaV2NIMUserSearchOption option = V2NIMUserSearchOption.V2NIMUserSearchOptionBuilder.builder("搜索关键字")
//             按需配置
//            .withSearchAccountId()
//            .withSearchMobile()
//            .withSearchName()
            .build();
    NIMClient.getService(V2NIMUserService.class).searchUserByOption(option,
            new V2NIMSuccessCallback<List<V2NIMUser>>() {
                @Override
                public void onSuccess(List<V2NIMUser> v2NIMUsers) {

                }
            }, new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {

                }
            });

iOS

Objective-CV2NIMUserSearchOption *option = [V2NIMUserSearchOption optionWithKeyword:@"keyword"];
// 按需配置
option.searchName = YES;
option.searchAccountId = YES;
option.searchMobile = YES;
[NIMSDK.sharedSDK.v2UserService searchUserByOption:option
                                        success:^(NSArray <V2NIMUser *> *result)
                                        {

                                        }
                                        failure:^(V2NIMError *error)
                                        {

                                        }];

macOS/Windows

C++V2NIMUserSearchOption option;
option.keyword = "test";
userService.searchUserByOption(
option,
[](nstd::vector<V2NIMUser> users) {
for (auto&& user : users) {
// do something
}
},
[](V2NIMError error) {
// search user failed, handle error
});

Web/uni-app/小程序

TypeScripttry {
    const users = await nim.V2NIMUserService.searchUserByOption({
        keyword: 'nick',
        searchName: true,
        searchAccountId: false,
        searchMobile: true
    })
} catch(err) {
    console.error('searchUserByOption Error:', err)
}

HarmonyOS

TypeScripttry {
    const users = await nim.userService.searchUserByOption({
        keyword: 'nick',
        searchName: true,
        searchAccountId: false,
        searchMobile: true
    })
} catch(err) {
    console.error('searchUserByOption Error:', err)
}

Flutter

dartawait NimCore.instance.userService.searchUserByOption(userSearchOption)

云端获取用户信息

调用 getUserListFromCloud 方法根据用户账号列表从服务器获取用户信息。

查询用户信息一般建议使用 getUserList 接口，只有需要强制拉取最新用户信息才需要调用 getUserListFromCloud 接口。

示例代码：

Android

JavaList<String> accountIds = new ArrayList<>();
accountIds.add("test01");
accountIds.add("test02");
NIMClient.getService(V2NIMUserService.class).getUserListFromCloud(accountIds, users -> {
    //Query successful
}, error -> {
    //Query failed
});

iOS

Objective-C[NIMSDK.sharedSDK.v2UserService getUserListFromCloud:@[@"accounId1",@"accountId2"] success:^(NSArray<V2NIMUser *> * _Nonnull result) {
        // 成功回调
    } failure:^(V2NIMError * _Nonnull error) {
        // 失败回调
    }];

macOS/Windows

C++nstd::vector<nstd::string> accountIds = {"test1", "test2"};
userService.getUserListFromCloud(
    accountIds,
    [](nstd::vector<V2NIMUser> usersList) {
        for (auto&& user : usersList) {
            // do something
        }
    },
    [](V2NIMError error) {
        // get UserListFromCloud failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst users = await nim.V2NIMUserService.getUserListFromCloud(["AccountID1", "AccountID2"])

HarmonyOS

TypeScriptconst users = await nim.userService.getUserListFromCloud(["AccountID1", "AccountID2"])

Flutter

dartawait NimCore.instance.userService.getUserListFromCloud(accountIds)

添加指定用户进黑名单

调用 addUserToBlockList 方法将指定用户添加进黑名单。添加成功后，SDK 会返回黑名单用户新增回调 onBlockListAdded 通知。

如果指定用户被加入了黑名单，那么就不再会收到此用户发送的任何消息。但是对于指定用户而言，不受影响。例如：A 用户将 B 用户加入黑名单，B 用户发送的消息，A 用户将接收不到。但是 A 用户发送的消息，B 用户依然可以接收到。

示例代码：

Android

JavaNIMClient.getService(V2NIMUserService.class).addUserToBlockList(accountId,
new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {

    }
},
new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {

    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] addUserToBlockList:@"accountId" success:^{

    } failure:^(V2NIMError * _Nonnull error) {

    }];

macOS/Windows

C++userService.addUserToBlockList(
    "account1",
    []() {
        // add user to blocklist success
    },
    [](V2NIMError error) {
        // add user to blocklist failed, handle error
    }
);

Web/uni-app/小程序

TypeScriptnim.V2NIMUserService.addUserToBlockList('accid');

HarmonyOS

TypeScriptnim.userService.addUserToBlockList('accid')

Flutter

dartawait NimCore.instance.userService.addUserToBlockList(accountId)

将指定用户移出黑名单

调用 removeUserFromBlockList 方法将指定用户移出黑名单。移除成功后，SDK 会返回黑名单用户移除回调 onBlockListRemoved 通知。

如果一个用户被从黑名单移除，那么会重新收到此用户发送的消息。

示例代码：

Android

JavaNIMClient.getService(V2NIMUserService.class).removeUserFromBlockList(accountId, new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {

    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {

    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] removeUserFromBlockList:@"accountId" success:^{

    } failure:^(V2NIMError * _Nonnull error) {

    }];

macOS/Windows

C++userService.removeUserFromBlockList(
    "account1",
    []() {
        // remove user from blocklist success
    },
    [](V2NIMError error) {
        // remove user from blocklist failed, handle error
    });

Web/uni-app/小程序

TypeScriptnim.V2NIMUserService.removeUserFromBlockList('accid');

HarmonyOS

TypeScriptnim.userService.removeUserFromBlockList('accid')

Flutter

dartawait NimCore.instance.userService.removeUserFromBlockList(accountId)

获取黑名单用户

调用 getBlockList 方法获取黑名单用户列表。

示例代码：

Android

JavaNIMClient.getService(V2NIMUserService.class).getBlockList(
    new V2NIMSuccessCallback<List<String>>() {
        @Override
        public void onSuccess(List<String> strings) {

        }
    },
    new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {

        }
    }
);

iOS

Objective-C[[[NIMSDK sharedSDK] v2UserService] getBlockList:^(NSArray<NSString *> * _Nonnull result) {

} failure:^(V2NIMError * _Nonnull error) {

}];

macOS/Windows

C++userService.getBlockList(
    [](std::vector<std::string> accountIds) {
        for (auto&& accountId : accountIds) {
            // do something
        }
    },
    [](V2NIMError error) {
        // get blocklist failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst blockList = await nim.V2NIMUserService.getBlockList()

HarmonyOS

TypeScriptconst blockList = await nim.userService.getBlockList()

Flutter

dartawait NimCore.instance.userService.getBlockList()

涉及接口

Android/iOS/macOS/Windows

API	说明
`addUserListener`	注册用户资料相关监听器
`removeUserListener`	取消注册用户资料相关监听器
`updateSelfUserProfile`	更新自己的用户资料
`getUserList`	根据用户账号 ID 列表获取用户资料
`searchUserByOption`	根据关键字信息搜索用户信息
`getUserListFromCloud`	根据用户账号列表从服务器获取用户信息
`addUserToBlockList`	添加指定用户进黑名单
`removeUserFromBlockList`	将指定用户移出黑名单
`getBlockList`	获取黑名单用户列表

Web/uni-app/小程序/HarmonyOS

API	说明
`on("EventName")`	注册用户资料相关监听器
`off("EventName")`	取消注册用户资料相关监听器
`updateSelfUserProfile`	更新自己的用户资料
`getUserList`	根据用户账号 ID 列表获取用户资料
`searchUserByOption`	根据关键字信息搜索用户信息
`getUserListFromCloud`	根据用户账号列表从服务器获取用户信息
`addUserToBlockList`	添加指定用户进黑名单
`removeUserFromBlockList`	将指定用户移出黑名单
`getBlockList`	获取黑名单用户列表

Flutter

API	说明
`add`	注册用户资料相关监听器
`cancel`	取消注册用户资料相关监听器
`updateSelfUserProfile`	更新自己的用户资料
`getUserList`	根据用户账号 ID 列表获取用户资料
`searchUserByOption`	根据关键字信息搜索用户信息
`getUserListFromCloud`	根据用户账号列表从服务器获取用户信息
`addUserToBlockList`	添加指定用户进黑名单
`removeUserFromBlockList`	将指定用户移出黑名单
`getBlockList`	获取黑名单用户列表

此文档是否对你有帮助？

有帮助

去反馈

支持平台
技术原理
前提条件
监听用户相关事件
更新本人用户资料
获取用户资料
根据关键字搜索用户信息
云端获取用户信息
添加指定用户进黑名单
将指定用户移出黑名单
获取黑名单用户
涉及接口