更新时间:2021-12-31 该文档已不再维护,请看新版 3.X 文档。

新版文档地址:Java Server SDK

介绍

Server SDK 是对环信 IM 服务端 API 的封装,这样做是为了节省服务器端开发者对接环信 API 的时间,只需要配置自己的 appkey 相关信息即可使用。

功能

Server SDK 提供了用户、消息、群组、聊天室等资源的操作管理能力。

依赖

  • Java 1.8
  • Reactor(io.projectreactor:reactor-bom:2020.0.4)

安装

如果你的项目使用 Maven 构建,在 pom.xml 中添加下面代码:

<dependency>
    <groupId>com.easemob.im</groupId>
    <artifactId>im-sdk-core</artifactId>
    <version>0.5.2</version>
</dependency>

如果你的项目使用 Gradle 构建,可以在 build.grade 中添加下面代码:

implementation 'com.easemob.im:im-sdk-core:0.5.2'

准备

在使用 Server SDK 之前,需要准备环信 appkey、Client ID、ClientSecre。

如果你有环信管理后台账号并创建过应用,请先登录环信管理后台,点击 这里,然后到“应用列表” → 点击“查看”即可获取到 appkey、Client ID、ClientSecret。

如果你没有环信管理后台账号,请先注册账号,点击 这里,注册成功后请登录,然后点击“添加应用”,添加成功后点击“查看”即可获取到 appkey、Client ID、ClientSecret。

使用

EMService是所有API的入口,可以这样初始化:

1. 使用 Easemob App Credentials 的情况

建议写到配置类中,示例如下:
@Configuration
public class Config {

    @Bean
    public EMService service() {
        
        EMProperties properties = EMProperties.builder()
                .setAppkey("Appkey")
                .setClientId("Client ID")
                .setClientSecret("ClientSecret")
                .build();

        return new EMService(properties);
    }
}

根据业务资源,API 分为:

  • Attachment 用于上传下载附件
  • Block 用于限制访问(将用户加入黑名单、群组/聊天室禁言等)
  • Contact 用于管理联系人(添加好友等)
  • Group 用于管理群组
  • Message 用于发送消息
  • User 用于管理用户
  • UserMetadata 用于管理用户属性
  • Push 用于管理用户推送(设置推送免打扰等)
  • Token 用于获取用户Token
  • Room 用于管理聊天室

每个业务资源对应一个方法,例如,用户相关的 API,都可以在 .user() 找到。

举个例子,我们要注册一个用户,就可以这样写:

@Service
public class UserService {

    @Autowired
    private EMService service;

    private void createUser() {
        try {
            EMUser user = service.user().create("username", "password").block();
        } catch (EMException e) {
            e.getErrorCode();
            e.getMessage();
        }
        
    }
}

API的返回值是响应式的,如果希望阻塞,可以使用上面例子中的 .block()。

注意:如果你的项目不是响应式的编程,那么请在调用的 Server SDK API 的结尾添加 .block()

对使用的 api 添加 try/catch ,如果使用的 api 没有抛出异常,代表请求成功,反之则请求失败,通过异常EMException对象的 getErrorCode()/getMessage() 拿到错误码以及错误描述

参考

Server SDK 的 api 文档在 这里

Server SDK 开源地址在 这里


常见问题

集成问题

如果你想看 Server SDK 的请求与响应,可以在配置文件中添加:

logging.level.com.easemob.im.http=debug

注意事项

1.Server SDK 是对环信 IM 服务端 API 的封装,但并没有封装所有的 API,只封装了开发者常用的 API,点击 这里 查看 Server SDK API。

对于注册环信id的规则,Server SDK 有自己的限制, 正则为 ^[a-z][0-9a-z-]{1,32}$,这点与 官网文档 中说明的环信 id 规则是有区别的,这样做是因为目前环信 id 注册的限制范围比较广,Server SDK 考虑缩小环信 id 注册的限制范围使其更加规范,在此说明一下。

如果不想使用 Server SDK 注册环信 id 的限制,可以在初始化配置时添加 'turnOffUserNameValidation()' (sdk 需要使用 0.3.5 以上的版本)

强烈建议不要使用纯数字或者有规律的字符串来注册环信 id,否则自己的用户可能会遭受到攻击、垃圾消息等后果。

EMProperties properties = EMProperties.builder()
        .setAppkey("appkey")
        .setClientId("Client ID")
        .setClientSecret("ClientSecret")
        .turnOffUserNameValidation()
        .build();

2.使用代理的情况

前提需要你的代理支持 CONNECT 方法,确保你的代理配置文件中有 connectport 80 存在。

如果你使用的代代理不需要认证,那么需要传入自己的ip、端口。

EMProxy proxy = EMProxy.builder()
                .setIP("ip")
                .setPort(80)
                .build();

EMProperties properties = EMProperties.builder()
        .setProxy(proxy)
        .setAppkey("appkey")
        .setClientId("Client ID")
        .setClientSecret("ClientSecret")
        .build();                

如果你使用的代理需要认证,那么需要传入自己的ip、端口、账号以及密码。

EMProxy proxy = EMProxy.builder()
                .setIP("ip")
                .setPort(80)
                .setUsername("username")
                .setPassword("password")
                .build();

EMProperties properties = EMProperties.builder()
        .setProxy(proxy)
        .setAppkey("appkey")
        .setClientId("Client ID")
        .setClientSecret("ClientSecret")
        .build();                

更新日志

V0.5.2

  • 修改群组信息方法增加custom参数。
  • 新增群组转让方法。

以上更新内容请到GroupApi中查看。