524 lines
13 KiB
Plaintext
524 lines
13 KiB
Plaintext
# Android IM即时通讯应用 - API接口文档
|
||
|
||
## 项目概述
|
||
本文档详细记录了Android IM即时通讯应用中使用的所有API接口，包括HTTP API、IM服务API、第三方服务API等。
|
||
|
||
## 一、服务器配置
|
||
|
||
### 1.1 主要服务器地址
|
||
- **IM服务器**: `im.xunpaisoft.com` (野火IM服务器)
|
||
- **应用服务器**: `https://xingyao.xunpaisoft.com` (业务API服务器)
|
||
- **文件服务器**: `https://qn.xunpaisoft.com/` (七牛云存储)
|
||
- **分享链接**: `https://web.xunpaisoft.com/xingyao/share?value=`
|
||
|
||
### 1.2 音视频通话配置
|
||
- **TURN服务器**: `turn:dev-turn.xunpaisoft.com:3478`
|
||
- **用户名**: `xingyaoturn`
|
||
- **密码**: `xingyaoturn`
|
||
|
||
### 1.3 组织通讯录服务
|
||
- **地址**: `https://xingyao.xunpaisoft.com`
|
||
|
||
## 二、HTTP API接口
|
||
|
||
### 2.1 用户认证相关
|
||
|
||
#### 2.1.1 获取IM Token
|
||
- **接口**: `POST /api/user/getImToken`
|
||
- **功能**: 获取IM连接所需的Token
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"platform": 2,
|
||
"clientId": "客户端ID"
|
||
}
|
||
```
|
||
- **响应**: 返回IM Token用于连接IM服务器
|
||
|
||
#### 2.1.2 密码登录
|
||
- **接口**: `POST /api/user/passwordLogin`
|
||
- **功能**: 用户密码登录
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"mobile": "手机号",
|
||
"password": "密码"
|
||
}
|
||
```
|
||
|
||
#### 2.1.3 短信验证码登录
|
||
- **接口**: `POST /api/user/smsLogin`
|
||
- **功能**: 短信验证码登录
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"mobile": "手机号",
|
||
"code": "验证码"
|
||
}
|
||
```
|
||
|
||
#### 2.1.4 发送短信验证码
|
||
- **接口**: `POST /api/user/sendSmsCode`
|
||
- **功能**: 发送短信验证码
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"mobile": "手机号"
|
||
}
|
||
```
|
||
|
||
### 2.2 用户信息管理
|
||
|
||
#### 2.2.1 获取用户信息
|
||
- **接口**: `POST /api/user/getUserInfo`
|
||
- **功能**: 获取用户详细信息
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"user_id": "用户ID",
|
||
"is_friend": "是否好友(0/1)"
|
||
}
|
||
```
|
||
|
||
#### 2.2.2 更新用户资料
|
||
- **接口**: `POST /api/user/profile`
|
||
- **功能**: 修改用户个人信息
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"field": "字段名",
|
||
"value": "字段值"
|
||
}
|
||
```
|
||
|
||
#### 2.2.3 获取用户互动数据
|
||
- **接口**: `POST /api/user/interactiveData`
|
||
- **功能**: 获取粉丝、关注、点赞数
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"user_id": "用户ID"
|
||
}
|
||
```
|
||
|
||
#### 2.2.4 获取互动列表
|
||
- **接口**: `POST /api/user/interactiveList`
|
||
- **功能**: 获取粉丝列表/关注列表
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"type": "类型(follow/fans)",
|
||
"page": "页码",
|
||
"limit": "每页数量"
|
||
}
|
||
```
|
||
|
||
### 2.3 好友关系管理
|
||
|
||
#### 2.3.1 关注用户
|
||
- **接口**: `POST /api/user/follow`
|
||
- **功能**: 关注用户（发送好友请求）
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"target_user_id": "目标用户ID",
|
||
"reason": "申请理由"
|
||
}
|
||
```
|
||
|
||
#### 2.3.2 取消关注
|
||
- **接口**: `POST /api/user/unfollow`
|
||
- **功能**: 取消关注用户（删除好友）
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"target_user_id": "目标用户ID"
|
||
}
|
||
```
|
||
|
||
#### 2.3.3 设置好友备注
|
||
- **接口**: `POST /api/user/friendSetAlias`
|
||
- **功能**: 设置好友备注名
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"target_user_id": "目标用户ID",
|
||
"alias": "备注名"
|
||
}
|
||
```
|
||
|
||
### 2.4 社交功能API
|
||
|
||
#### 2.4.1 发布动态
|
||
- **接口**: `POST /api/post/post`
|
||
- **功能**: 发布朋友圈动态
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"content": "文字内容",
|
||
"images": "图片列表",
|
||
"videos": "视频列表",
|
||
"location": "位置信息"
|
||
}
|
||
```
|
||
|
||
#### 2.4.2 获取动态列表
|
||
- **接口**: `POST /api/post/postList`
|
||
- **功能**: 获取广场/朋友圈动态列表
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"type": "类型(guangchang/guanzhu)",
|
||
"page": "页码",
|
||
"limit": "每页数量"
|
||
}
|
||
```
|
||
|
||
#### 2.4.3 点赞动态
|
||
- **接口**: `POST /api/post/like`
|
||
- **功能**: 点赞/取消点赞动态
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"post_id": "动态ID",
|
||
"action": "操作(like/unlike)"
|
||
}
|
||
```
|
||
|
||
#### 2.4.4 收藏动态
|
||
- **接口**: `POST /api/post/collection`
|
||
- **功能**: 收藏/取消收藏动态
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"post_id": "动态ID",
|
||
"action": "操作(collect/uncollect)"
|
||
}
|
||
```
|
||
|
||
#### 2.4.5 评论动态
|
||
- **接口**: `POST /api/post/comment`
|
||
- **功能**: 评论动态
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"post_id": "动态ID",
|
||
"content": "评论内容",
|
||
"parent_id": "父评论ID(可选)"
|
||
}
|
||
```
|
||
|
||
#### 2.4.6 获取评论列表
|
||
- **接口**: `POST /api/post/commentsList`
|
||
- **功能**: 获取动态评论列表
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"post_id": "动态ID",
|
||
"page": "页码",
|
||
"limit": "每页数量"
|
||
}
|
||
```
|
||
|
||
#### 2.4.7 删除动态
|
||
- **接口**: `POST /api/post/postDelete`
|
||
- **功能**: 删除朋友圈动态
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"post_id": "动态ID"
|
||
}
|
||
```
|
||
|
||
### 2.5 群组管理API
|
||
|
||
#### 2.5.1 获取群公告
|
||
- **接口**: `POST /api/manage/getNotice`
|
||
- **功能**: 获取群公告信息
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"group_id": "群组ID"
|
||
}
|
||
```
|
||
|
||
#### 2.5.2 设置群公告
|
||
- **接口**: `POST /api/manage/createGroupNotice`
|
||
- **功能**: 创建/更新群公告
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"group_id": "群组ID",
|
||
"title": "公告标题",
|
||
"content": "公告内容"
|
||
}
|
||
```
|
||
|
||
### 2.6 相册管理API
|
||
|
||
#### 2.6.1 群相册管理
|
||
- **创建群相册**: `POST /api/image/createAlbum`
|
||
- **编辑群相册**: `POST /api/image/editAlbum`
|
||
- **删除群相册**: `POST /api/image/deleteAlbum`
|
||
- **获取群相册列表**: `POST /api/image/getAlbums`
|
||
- **上传到群相册**: `POST /api/image/uploadToGroup`
|
||
- **删除群相册图片**: `POST /api/image/delGroupAlbumImages`
|
||
- **获取群相册图片**: `POST /api/image/groupImages`
|
||
|
||
#### 2.6.2 用户相册管理
|
||
- **创建用户相册**: `POST /api/image/createUserAlbum`
|
||
- **编辑用户相册**: `POST /api/image/editUserAlbum`
|
||
- **删除用户相册**: `POST /api/image/deleteUserAlbum`
|
||
- **获取用户相册列表**: `POST /api/image/getUserAlbums`
|
||
- **上传到用户相册**: `POST /api/image/uploadToUserAlbum`
|
||
- **删除用户相册图片**: `POST /api/image/delUserAlbumImages`
|
||
- **获取用户相册图片**: `POST /api/image/userAlbumImages`
|
||
|
||
### 2.7 文件上传API
|
||
|
||
#### 2.7.1 获取七牛Token
|
||
- **接口**: `GET /api/common/getQNToken`
|
||
- **功能**: 获取七牛云上传Token
|
||
- **响应**: 返回七牛云上传凭证
|
||
|
||
#### 2.7.2 上传文件
|
||
- **接口**: `POST /api/common/upload`
|
||
- **功能**: 上传文件到服务器
|
||
- **请求参数**: 文件流数据
|
||
|
||
### 2.8 其他功能API
|
||
|
||
#### 2.8.1 意见反馈
|
||
- **接口**: `POST /api/other/sendSuggestion`
|
||
- **功能**: 提交意见反馈
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"content": "反馈内容",
|
||
"contact": "联系方式"
|
||
}
|
||
```
|
||
|
||
#### 2.8.2 投诉举报
|
||
- **接口**: `POST /api/other/sendReport`
|
||
- **功能**: 提交投诉举报
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"target_id": "被举报对象ID",
|
||
"type": "举报类型",
|
||
"reason": "举报原因",
|
||
"content": "详细说明"
|
||
}
|
||
```
|
||
|
||
#### 2.8.3 获取配置项
|
||
- **接口**: `POST /api/other/getOptions`
|
||
- **功能**: 获取应用配置项
|
||
- **响应**: 返回应用配置信息
|
||
|
||
#### 2.8.4 阅后即焚设置
|
||
- **获取状态**: `POST /api/manage/getBurnAfterReadingStatus`
|
||
- **设置状态**: `POST /api/manage/setBurnAfterReading`
|
||
- **功能**: 管理阅后即焚功能
|
||
|
||
#### 2.8.5 账号管理
|
||
- **修改手机号**: `POST /api/user/changemobile`
|
||
- **注销账号**: `POST /api/user/resignAccount`
|
||
|
||
## 三、IM服务API
|
||
|
||
### 3.1 连接管理
|
||
- **服务器地址**: `im.xunpaisoft.com`
|
||
- **连接方式**: WebSocket
|
||
- **认证方式**: Token认证
|
||
|
||
### 3.2 消息类型
|
||
- **文本消息**: TextMessageContent
|
||
- **图片消息**: ImageMessageContent
|
||
- **语音消息**: SoundMessageContent
|
||
- **视频消息**: VideoMessageContent
|
||
- **文件消息**: FileMessageContent
|
||
- **位置消息**: LocationMessageContent
|
||
- **引用消息**: QuoteMessageContent
|
||
- **撤回消息**: RecallMessageContent
|
||
- **会议邀请**: ConferenceInviteMessageContent
|
||
- **会议模式变更**: ConferenceChangeModeContent
|
||
- **会议命令**: ConferenceCommandContent
|
||
|
||
### 3.3 会话管理
|
||
- **单聊**: ConversationType.Single
|
||
- **群聊**: ConversationType.Group
|
||
- **频道**: ConversationType.Channel
|
||
- **聊天室**: ConversationType.ChatRoom
|
||
|
||
### 3.4 消息状态
|
||
- **发送中**: MessageStatus.Sending
|
||
- **已发送**: MessageStatus.Sent
|
||
- **已送达**: MessageStatus.Delivered
|
||
- **已读**: MessageStatus.Read
|
||
- **发送失败**: MessageStatus.Send_Failure
|
||
|
||
## 四、音视频通话API
|
||
|
||
### 4.1 通话类型
|
||
- **单人通话**: SingleCallActivity
|
||
- **多人通话**: MultiCallActivity
|
||
- **会议通话**: ConferenceActivity
|
||
|
||
### 4.2 通话控制
|
||
- **发起通话**: AVEngineKit.startCall()
|
||
- **接听通话**: AVEngineKit.answerCall()
|
||
- **挂断通话**: AVEngineKit.endCall()
|
||
- **静音控制**: session.muteAudio()
|
||
- **摄像头控制**: session.muteVideo()
|
||
- **屏幕共享**: session.startScreenShare()
|
||
|
||
### 4.3 会议管理
|
||
- **加入会议**: AVEngineKit.joinConference()
|
||
- **离开会议**: AVEngineKit.leaveConference()
|
||
- **会议模式切换**: ConferenceManager.changeMode()
|
||
|
||
## 五、第三方服务API
|
||
|
||
### 5.1 七牛云存储
|
||
- **SDK**: qiniu-android-sdk
|
||
- **功能**: 文件上传、图片处理
|
||
- **配置**:
|
||
```java
|
||
// 自动识别上传区域
|
||
AutoZone zone = new AutoZone();
|
||
// 分片上传阈值：4MB
|
||
.putThreshold(4 * 1024 * 1024)
|
||
// 开启分片上传
|
||
.useConcurrentResumeUpload(true)
|
||
```
|
||
|
||
### 5.2 腾讯地图服务
|
||
- **SDK**: tencent-map-vector-sdk
|
||
- **功能**: 地图显示、位置服务、路径规划
|
||
- **配置**:
|
||
```java
|
||
// 地图SDK版本: 6.3.0.250311.940c5007.146962199
|
||
// 基础库版本: 0.5.7.fc32fe3
|
||
// 组件库版本: 1.0.10
|
||
```
|
||
|
||
### 5.3 推送服务
|
||
- **小米推送**: MiPush_SDK_Client_3_6_9.jar
|
||
- **华为推送**: HMS Core
|
||
- **魅族推送**: Flyme推送
|
||
- **VIVO推送**: vivo_pushsdk_v2.3.1.jar
|
||
- **OPPO推送**: OPPO推送服务
|
||
- **Firebase推送**: firebase-messaging
|
||
|
||
### 5.4 图片处理
|
||
- **图片选择**: PictureSelector v3.0.9
|
||
- **图片压缩**: Luban 1.1.8
|
||
- **图片裁剪**: UCrop
|
||
- **图片查看**: PhotoView
|
||
|
||
## 六、网络请求配置
|
||
|
||
### 6.1 HTTP客户端配置
|
||
- **超时时间**: 30秒
|
||
- **请求头**:
|
||
- `token`: 用户认证Token
|
||
- `Content-Type`: application/json
|
||
- **响应格式**: JSON
|
||
|
||
### 6.2 请求拦截器
|
||
- **认证拦截**: 自动添加Token到请求头
|
||
- **响应拦截**: 统一处理响应结果
|
||
- **错误处理**: 统一错误码处理
|
||
|
||
### 6.3 分页配置
|
||
- **默认每页数量**: 20条
|
||
- **最大会话数**: 1000条
|
||
|
||
## 七、安全配置
|
||
|
||
### 7.1 数据加密
|
||
- **传输加密**: HTTPS
|
||
- **Token存储**: KeyStore加密存储
|
||
- **敏感信息**: 本地加密存储
|
||
|
||
### 7.2 权限控制
|
||
- **动态权限申请**: 运行时申请必要权限
|
||
- **权限说明**: 详细说明权限用途
|
||
- **降级处理**: 权限被拒绝时的替代方案
|
||
|
||
## 八、错误码说明
|
||
|
||
### 8.1 通用错误码
|
||
- **-1**: 网络错误
|
||
- **0**: 成功
|
||
- **1**: 参数错误
|
||
- **2**: 认证失败
|
||
- **3**: 权限不足
|
||
|
||
### 8.2 业务错误码
|
||
- **1001**: 用户不存在
|
||
- **1002**: 密码错误
|
||
- **1003**: 验证码错误
|
||
- **2001**: 好友关系不存在
|
||
- **2002**: 已经是好友
|
||
- **3001**: 动态不存在
|
||
- **3002**: 无权限操作
|
||
|
||
## 九、API调用示例
|
||
|
||
### 9.1 用户登录
|
||
```java
|
||
// 密码登录
|
||
AppService.Instance().passwordLogin(mobile, password, new AppService.LoginCallback() {
|
||
@Override
|
||
public void onUiSuccess(LoginResult loginResult) {
|
||
// 登录成功，保存Token
|
||
String token = loginResult.getUserinfo().getToken();
|
||
// 连接IM服务器
|
||
ChatManagerHolder.gChatManager.connect(userId, token);
|
||
}
|
||
|
||
@Override
|
||
public void onUiFailure(int code, String msg) {
|
||
// 登录失败处理
|
||
}
|
||
});
|
||
```
|
||
|
||
### 9.2 发送消息
|
||
```java
|
||
// 发送文本消息
|
||
Message message = new Message();
|
||
message.conversation = conversation;
|
||
message.content = new TextMessageContent("Hello World");
|
||
ChatManager.Instance().sendMessage(message, null);
|
||
```
|
||
|
||
### 9.3 文件上传
|
||
```java
|
||
// 上传文件到七牛云
|
||
QiniuUploadFile.uploadFile(key, token, file, new UploadCallBack() {
|
||
@Override
|
||
public void result(boolean success, String key) {
|
||
if (success) {
|
||
// 上传成功，使用返回的key
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
## 十、总结
|
||
|
||
本应用集成了丰富的API接口，包括：
|
||
- **用户认证**: 多种登录方式支持
|
||
- **即时通讯**: 完整的IM功能
|
||
- **社交功能**: 朋友圈、动态发布
|
||
- **音视频通话**: 单人、多人、会议通话
|
||
- **文件存储**: 七牛云存储服务
|
||
- **地图服务**: 腾讯地图集成
|
||
- **推送服务**: 多厂商推送支持
|
||
|
||
所有API都采用RESTful设计，支持JSON格式数据交换，具备完善的错误处理和安全机制。
|