{"id":18438160,"url":"https://github.com/easemob/easemob-im-server-sdk","last_synced_at":"2025-05-11T15:43:17.111Z","repository":{"id":38273276,"uuid":"330103419","full_name":"easemob/easemob-im-server-sdk","owner":"easemob","description":"IM server SDK","archived":false,"fork":false,"pushed_at":"2025-04-22T09:09:59.000Z","size":8870,"stargazers_count":23,"open_issues_count":6,"forks_count":29,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-22T09:37:56.719Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/easemob.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-16T06:54:28.000Z","updated_at":"2025-02-28T18:41:46.000Z","dependencies_parsed_at":"2023-02-09T02:30:44.479Z","dependency_job_id":"cf02c866-6a0c-4376-9f51-3af4388db1e7","html_url":"https://github.com/easemob/easemob-im-server-sdk","commit_stats":null,"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easemob%2Feasemob-im-server-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easemob%2Feasemob-im-server-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easemob%2Feasemob-im-server-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easemob%2Feasemob-im-server-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/easemob","download_url":"https://codeload.github.com/easemob/easemob-im-server-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253432338,"owners_count":21907729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T06:18:54.226Z","updated_at":"2025-05-10T14:42:33.070Z","avatar_url":"https://github.com/easemob.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Easemob IM Java SDK [![build](https://github.com/easemob/easemob-im-server-sdk/workflows/Build/badge.svg)](https://github.com/easemob/easemob-im-server-sdk/actions) [![codecov](https://codecov.io/gh/easemob/easemob-im-server-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/easemob/easemob-im-server-sdk)\n\n**Easemob IM Java SDK** 是对环信 IM [服务端 API](http://docs-im.easemob.com/im/server/ready/intro) 的封装。\n\n提供用户、群组等资源的操作管理能力。\n\n## 依赖\n\n- Java 1.8\n- [Reactor](https://projectreactor.io)(io.projectreactor:reactor-bom:2020.0.4)\n\n## 安装\n\n如果你的项目使用 Maven 构建，在 pom.xml 中添加下面代码即可：\n\n``` xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.easemob.im\u003c/groupId\u003e\n    \u003cartifactId\u003eim-sdk-core\u003c/artifactId\u003e\n    \u003cversion\u003e0.5.4\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n如果你的项目使用 Gradle 构建，可以在 build.grade 中添加下面代码：\n\n``` gradle\nimplementation 'com.easemob.im:im-sdk-core:0.5.4'\n```\n\n## 准备\n使用 Server SDK 的前提需要您准备:\n* 1. 环信 appKey\n* 2. 两种 appCredentials 中的其中之一:\n    - 2.1 环信 clientId, clientSecret\n    - 2.2 声网 appId, appCert\n\n### 获取环信 appKey, clientId, clientSecret\n\n如果您有环信管理后台账号并创建过应用，请进入 [这里](https://console.easemob.com/user/login) 进行登录。\n![图片](https://user-images.githubusercontent.com/15087647/114996679-a34cb980-9ed1-11eb-89ae-a22c1af7d69d.png)\n\n如图点击查看后，可以看到自己的 appkey、Client ID、ClientSecret，用于 SDK 的初始化。\n\n如果您没有环信管理后台账号，请进入 [这里](https://console.easemob.com/user/register) 进行注册账号，注册成功后请进行登录。\n![图片](https://user-images.githubusercontent.com/15087647/114997381-59180800-9ed2-11eb-968a-a29406c78021.png)\n\n如图先添加应用(也就是创建 appkey，自动生成 Client ID、ClientSecret)，添加成功后在应用列表中可以看到应用信息，点击查看可以看到自己的 appkey、Client ID、ClientSecret，用于 SDK 的初始化。\n\n### 获取声网 appId, appCert\n\n如果您有声网 Console 后台账号并创建过项目，请先登录声网 Console  后台，点击[这里](https://sso.agora.io/cn/login/)，然后到\"项目列表\" -\u003e 找到自己的项目点击\"编辑\"图标后，即可看到 App ID、APP 证书。\n\n如果您没有声网Console后台账号，请先注册账号，点击[这里](https://sso.agora.io/cn/v4/signup)，注册成功后按照步骤1操作。\n\n\n## 使用\n\n[EMService](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/EMService.html) 是所有 API 的入口，可以这样初始化：\n\n### 1. 使用 Easemob App Credentials 的情况\n``` java\n建议写到配置类中，示例如下：\n@Configuration\npublic class Config {\n\n    @Bean\n    public EMService service() {\n        \n        EMProperties properties = EMProperties.builder()\n                .setAppkey(\"Appkey\")\n                .setClientId(\"Client ID\")\n                .setClientSecret(\"ClientSecret\")\n                .build();\n\n        return new EMService(properties);\n    }\n}\n```\n\n根据业务资源，API 分为：\n\n- [Attachment](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/attachment/AttachmentApi.html)\n  用于上传下载附件\n- [Block](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/block/BlockApi.html)\n  用于限制访问(将用户加入黑名单、群组/聊天室禁言等)\n- [Contact](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/contact/ContactApi.html)\n  用于管理联系人(添加好友等)\n- [Group](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/group/GroupApi.html)\n  用于管理群组\n- [Message](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/message/MessageApi.html)\n  用于发送消息\n- [User](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/user/UserApi.html)\n  用于管理用户\n- [UserMetadata](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/metadata/MetadataApi.html)\n  用于管理用户属性\n- [Push](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/push/PushApi.html)\n  用于管理用户推送(设置推送免打扰等)  \n- [Token](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/token/TokenApi.html)\n  用于获取用户Token\n- [Room](https://easemob.github.io/easemob-im-server-sdk/com/easemob/im/server/api/room/RoomApi.html)\n  用于管理聊天室\n\n每个业务资源对应一个方法，例如，用户相关的 API，都可以在 `.user()` 找到。\n\n举个例子，我们要注册一个用户，就可以这样写：\n\n``` java\n@Service\npublic class UserService {\n\n    @Autowired\n    private EMService service;\n\n    private void createUser() {\n        try {\n            EMUser user = service.user().create(\"username\", \"password\").block();\n        } catch (EMException e) {\n            e.getErrorCode();\n            e.getMessage();\n        }\n        \n    }\n}\n```\n\nAPI 的返回值是响应式的，如果希望阻塞，可以使用上面例子中的 `.block()`。\n\n注意：如果你的项目不是响应式的编程，那么请在调用的 server sdk api 的结尾添加 `.block()`。\n\n对使用的 API 添加 `try/catch` ，如果使用的 API 没有抛出异常，代表请求成功，反之则请求失败，通过 `EMException` 异常对象的 `getErrorCode()/getMessage()` 拿到错误码以及错误描述。\n\n## 参考\n\nSDK 的 api 文档在[这里](https://easemob.github.io/easemob-im-server-sdk/) 。\n\n## 常见问题\n如果你想看 Server SDK 的请求与响应，可以在配置文件中添加:\n``` java\nlogging.level.com.easemob.im.http=debug\n```\n\n## 注意事项\n\nServer SDK 是对环信 IM [服务端 API](http://docs-im.easemob.com/im/server/ready/intro) 的封装，但并没有封装所有的 API，只封装了开发者常用的 API。\n\n对于注册环信id的规则，Server SDK 有自己的限制, 正则为 `^[a-z][0-9a-z-]{1,32}$`，这点与 [官网文档](https://docs-im.easemob.com/im/server/ready/user#%E7%8E%AF%E4%BF%A1_id_%E4%BD%BF%E7%94%A8%E8%A7%84%E5%88%99) 中说明的环信id规则是有区别的，这样做是因为目前环信id注册的限制范围比较广，Server SDK 考虑缩小环信 id 注册的限制范围使其更加规范，在此说明一下。\n\n如果不想使用 Server SDK 注册环信 id 的限制，可以在初始化配置时添加 `turnOffUserNameValidation()` （sdk 需要使用 0.3.5 以上的版本）。\n\n强烈建议不要使用纯数字或者有规律的字符串来注册环信 id，否则自己的用户可能会遭受到攻击、垃圾消息等后果。\n``` java\nEMProperties properties = EMProperties.builder()\n        .setAppkey(\"appkey\")\n        .setClientId(\"Client ID\")\n        .setClientSecret(\"ClientSecret\")\n        .turnOffUserNameValidation()\n        .build();\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasemob%2Feasemob-im-server-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feasemob%2Feasemob-im-server-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasemob%2Feasemob-im-server-sdk/lists"}