# 快速开始

5 分钟接入 XuqmGroup IM，实现消息收发。

## 1. 选择部署形态

| 形态 | 适用场景 | SDK |
|------|----------|-----|
| 公有化 | 使用 XuqmGroup 公有云控制台 | 当前公有化 SDK |
| 私有化 | 使用客户独立部署环境 | 独立私有化 SDK |

公有化控制台地址：<https://dev.xuqinmin.com>

私有化环境由部署仓库生成控制台地址、文档站地址和 `xuqm-private-sdk.json`，接入时以客户环境输出为准。

## 2. 创建或获取应用

公有化：

1. 登录公有化控制台。
2. 注册开发者账号。
3. 创建应用并记录 `appKey`。

私有化：

1. 使用部署时内置的主租户登录客户控制台。
2. 使用初始化默认应用，或在控制台创建新应用。
3. 下载或读取 `xuqm-private-sdk.json`。

## 3. 选择平台

### 客户端 SDK

| 平台 | 接入文档 |
|------|----------|
| Android | [Android SDK](/android/) |
| iOS | [iOS SDK](/ios/) |
| React Native | [RN SDK](/rn/) |
| Vue3 / Web | [Vue3 SDK](/vue3/) |
| HarmonyOS | [HarmonyOS SDK](/harmony/) |
| Flutter | [Flutter SDK](/flutter/) |
| 微信小程序 | [小程序 SDK](/miniprogram/) |
| H5 / 纯 JS | [H5 SDK](/h5/) |

### 服务端 SDK

| 语言 | 接入文档 |
|------|----------|
| Go | [Go Server SDK](/server/go-sdk) |
| Java | [Java Server SDK](/server/java-sdk) |
| Python | [Python Server SDK](/server/python-sdk) |

## 4. 配置文件

平台控制台支持为应用下载 `.xuqmconfig` 配置文件（例如 `识校宝.xuqmconfig`），该文件包含应用的 appKey、服务端地址等信息。将文件放到各平台指定位置后，SDK 会自动读取并完成初始化，无需在代码中手动传入 `appKey`。

各平台放置位置：

| 平台 | 路径 | 说明 |
|------|------|------|
| Android | `src/main/assets/config/` 或 `assets/xuqm/` | 放入任一目录即可，Gradle 插件自动识别 |
| iOS | App Bundle 的 `xuqm/` 目录 | 随 App 一起打包 |
| React Native | `src/assets/config/` | `withXuqmConfig` Metro 插件自动注入 |
| Flutter | `assets/config/` | `pubspec.yaml` 中声明 `assets` |
| HarmonyOS | `src/main/resources/rawfile/config/` | 随 HAP 打包 |

> 文件名不限，只要扩展名为 `.xuqmconfig` 即可。

## 5. 公有化初始化

```kotlin
XuqmSDK.initialize(
    context = this,
    appKey = "ak_your_app_key"
)
```

## 6. 私有化初始化

私有化 SDK 使用部署仓库生成的本地 JSON 初始化：

```kotlin
XuqmPrivateSDK.initialize(
    context = this,
    configAsset = "xuqm-private-sdk.json"
)
```

JSON 内容由私有化部署仓库生成，示例：

```json
{
  "schemaVersion": 1,
  "deployment": "PRIVATE",
  "appKey": "ak_private_default",
  "controlBaseUrl": "https://tenant.customer.com",
  "imApiBaseUrl": "https://im.customer.com",
  "imWsUrl": "wss://im.customer.com/ws/im",
  "pushBaseUrl": "https://push.customer.com",
  "updateBaseUrl": "https://update.customer.com",
  "fileBaseUrl": "https://file.customer.com"
}
```

## 7. 登录与收发消息

```text
业务客户端
  -> 调用业务登录
  -> 业务服务端签发 UserSig
  -> 客户端调用 SDK login
  -> IM 连接建立
  -> 收发消息、推送、更新能力按模块启用
```

安全要求：`appSecret` 只能保存在业务服务端，不允许下发到客户端。
