138 行
3.0 KiB
Markdown
138 行
3.0 KiB
Markdown
|
# 接入流程
|
|||
|
|
|
|||
|
|
完整的 XuqmGroup SDK 接入流程，从注册账号到客户端收发消息。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 注册开发者账号
|
|||
|
|
|
|||
|
|
1. 访问 [XuqmGroup 控制台](https://dev.xuqinmin.com)
|
|||
|
|
2. 点击注册，填写企业/个人信息
|
|||
|
|
3. 完成邮箱/手机验证
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 创建应用
|
|||
|
|
|
|||
|
|
1. 登录控制台 → 应用管理 → 创建应用
|
|||
|
|
2. 填写应用名称、平台类型（Android / iOS / Web / RN / 小程序 / HarmonyOS）
|
|||
|
|
3. 创建成功后获得：
|
|||
|
|
- `appKey`（客户端使用）
|
|||
|
|
- `appSecret`（服务端使用，**不可泄露**）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 获取 AppKey
|
|||
|
|
|
|||
|
|
在应用详情页复制 `appKey`，用于客户端 SDK 初始化：
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
// Android
|
|||
|
|
XuqmSDK.initialize(context, appKey = "your_app_key")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```swift
|
|||
|
|
// iOS
|
|||
|
|
let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret")
|
|||
|
|
XuqmSDK.shared.initialize(config: config)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
// Vue3 / Web
|
|||
|
|
init({ appKey: 'your_app_key', appSecret: 'your_app_secret' })
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 服务端签发 UserSig
|
|||
|
|
|
|||
|
|
`appSecret` 只应保存在业务服务端，用于为每个用户签发 `userSig`。
|
|||
|
|
|
|||
|
|
### 签发逻辑（示例）
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
// Node.js
|
|||
|
|
import jwt from 'jsonwebtoken'
|
|||
|
|
|
|||
|
|
function generateUserSig(userId: string, appKey: string, appSecret: string): string {
|
|||
|
|
return jwt.sign(
|
|||
|
|
{ userId, appKey },
|
|||
|
|
appSecret,
|
|||
|
|
{ algorithm: 'HS256' }
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# Python
|
|||
|
|
import jwt
|
|||
|
|
|
|||
|
|
def generate_user_sig(user_id: str, app_key: str, app_secret: str) -> str:
|
|||
|
|
return jwt.encode(
|
|||
|
|
{"userId": user_id, "appKey": app_key},
|
|||
|
|
app_secret,
|
|||
|
|
algorithm="HS256"
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// Go
|
|||
|
|
import "github.com/golang-jwt/jwt/v5"
|
|||
|
|
|
|||
|
|
func GenerateUserSig(userID, appKey, appSecret string) (string, error) {
|
|||
|
|
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
|
|||
|
|
"userId": userID,
|
|||
|
|
"appKey": appKey,
|
|||
|
|
})
|
|||
|
|
return token.SignedString([]byte(appSecret))
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 接口设计建议
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/auth/xuqm-login
|
|||
|
|
Headers: Authorization: Bearer {your-app-auth-token}
|
|||
|
|
Body: { "userId": "user_001" }
|
|||
|
|
Response: { "userSig": "jwt_token_string" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 客户端接入 SDK
|
|||
|
|
|
|||
|
|
### 登录流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
客户端
|
|||
|
|
→ 业务登录（用户名/密码）
|
|||
|
|
→ 业务服务端验证成功
|
|||
|
|
→ 业务服务端调用 generateUserSig(userId, appKey, appSecret)
|
|||
|
|
→ 返回 userSig 给客户端
|
|||
|
|
→ 客户端调用 XuqmSDK.login(userId, userSig)
|
|||
|
|
→ SDK 自动连接 WebSocket
|
|||
|
|
→ 开始收发消息
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 各平台接入
|
|||
|
|
|
|||
|
|
| 平台 | 文档 |
|
|||
|
|
|------|------|
|
|||
|
|
| Android | [Android SDK →](/android/) |
|
|||
|
|
| iOS | [iOS SDK →](/ios/) |
|
|||
|
|
| React Native | [RN SDK →](/rn/) |
|
|||
|
|
| Vue3 / Web | [Vue3 SDK →](/vue3/) |
|
|||
|
|
| HarmonyOS | [HarmonyOS SDK →](/harmony/) |
|
|||
|
|
| 微信小程序 | [小程序 SDK →](/miniprogram/) |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 安全提示
|
|||
|
|
|
|||
|
|
- `appSecret` **绝不下发到客户端**，仅用于服务端签发 UserSig
|
|||
|
|
- 若需撤销用户权限，可在租户平台重置 `appSecret` 或拉黑账号
|
|||
|
|
- 所有 API 通信使用 HTTPS / WSS
|
|||
|
|
- UserSig 当前版本不过期，业务方可自行控制签发逻辑
|
|||
|
|
|
|||
|
|
[→ 快速开始 →](./quickstart)
|
