Skip to content

Commit

Permalink
docs: update uniapp doc (#217)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lgz5689
lgz5689 authored Nov 26, 2024
1 parent 2d8aeb8 commit 308197a
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 57 deletions.
52 changes: 23 additions & 29 deletions docs/sdks/quickstart/uniapp.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,51 +4,49 @@ hide_title: true
sidebar_position: 6
---

## 🚀使用 Demo
## 使用 Demo
> 注意：Demo 只是用于演示 SDK 的引入与使用，并不是不是一个完整的应用。
我们强烈建议您首先运行我们为您准备的框架相关的示例 [DEMO](https://github.com/openimsdk/open-im-uniapp-demo) 。这不仅可以让您直观体验 OpenIM SDK 的功能，还将帮助您在实际集成过程中迅速定位和解决问题。

## ❗️提示
## ❗️常见问题

### 1. 服务端准备
### 1. 仅开发 H5、小程序

- 如果使用到 [纯 JS 版本 SDK](docs/sdks/quickstart/miniProgram.mdx) ，服务端(OpenIM Server)版本需要在 3.8.2 以上。
- 不开发 App 端的情况下，使用 uniapp 开发 h5 和 小程序直接使用 [JSSDK](docs/sdks/quickstart/miniProgram.mdx) ，***不需要*** 参考下面步骤。

### 2. 使用 Uni 开发多端 ( APP、H5、小程序 )
### 2. 使用 Uni 同时开发多端 ( APP、H5、小程序 )

- 最新的 npm 包已经支持在 uni-app 上开发多端应用了，但是需要使用较多的 ***条件编译*** 语法，建议开发前先参考 Demo ，里面展示了如何在跨端情况下进行开发。
- 运行 iOS 和 Android ***必须*** 安装原生插件，中间层 `openim-uniapp-polyfill` 结合 App 原生插件和 JSSDK 能力，兼容一套代码同时开发 APP、H5、小程序（ SDK 和 im-server 版本 >= 3.8.2 ）。

### 3. 仅开发 H5/小程序
### 3. 关于依赖项

- 使用 uniapp 开发 h5 和 小程序 (或原生小程序) 直接使用 [纯 JS 版本 SDK](docs/sdks/quickstart/miniProgram.mdx) ，***不需要*** 参考下面步骤。
- @openim/client-sdk : JSSDK，是运行 H5、小程序时必须的依赖项。

---
- App 原生语言插件：运行 iOS 和 Android 时必须的依赖项。

- openim-uniapp-polyfill : 必须安装， 统一封装 JSSDK 和原生插件， 兼容一套代码同时开发多平台。

## 集成步骤
---

包含 APP 端开发，**必须** 按照下面的步骤，使用云插件导入 SDK ，使用 npm 包调用。因为 APP 端的实现方式都是通过 [App 原生语言插件](https://uniapp.dcloud.net.cn/plugin/native-plugin.html) 实现。
## ⚙️ 集成步骤

### 1. 添加依赖

> 官方插件已上传至 [dcloud 插件市场](https://ext.dcloud.net.cn/plugin?id=6577)
- 使用 npm 安装依赖

- 选择对应项目和包名引入 SDK
```bash
npm install openim-uniapp-polyfill @openim/client-sdk
```

- [dcloud 插件市场](https://ext.dcloud.net.cn/plugin?id=6577) 选择对应项目和包名引入 SDK

![uni_import](./assets/uni_import.png)

- 打开引入 SDK 项目根目录下 `manifest.json` 文件，选择 **App 原生插件配置**，选择云端插件进行导入。

![uni_import_manifest](./assets/uni_import_manifest.png)

- 下载 npm 包，简化对 SDK 的引入和使用，并封装 API 为 Promse 形式。

> openim-uniapp-polyfill >= 1.3.0 以上版本在非 APP 端情况下使用 [纯 JS 版本 SDK](docs/sdks/quickstart/miniProgram.mdx) 。
```bash
npm install openim-uniapp-polyfill open-im-sdk
```

### 2. 在项目中引入 ( 纯 APP 项目 )

```javascript
Expand All @@ -70,13 +68,9 @@ IMSDK.unsubscribe(IMSDK.IMEvents.OnConnectSuccess, onConnectSuccess);

### 3. 在项目中引入 ( APP、H5、小程序 )

> 需要使用云插件导入 SDK ，新版 npm 包在非 APP 端，使用 [纯 JS 版本 SDK](docs/sdks/quickstart/miniProgram.mdx) 。
- 注意1： `openim-uniapp-polyfill` 版本需要 >= 1.3.0 ，`open-im-sdk` 版本需要 >= 3.5.1-alpha.8 。

- 注意2：监听器使用 uniapp 的方式调用监听器，传入 `IMSDK.IMEvents` 中的方法，因为 JSSDK 与 APP 的监听器大小写有区别 , npm 包中已经做自动转换。
- 注意1：监听器使用 uniapp 的方式调用监听器，传入 `IMSDK.IMEvents` 中的方法，因为 JSSDK 与 APP 的监听器大小写有区别 , npm 包中已经做自动转换。

- 注意3：在部分 API 中不同端可能因为平台的支持，用法上会有所区别，使用时查看对应平台 API 的文档，注意差别：
- 注意2：在部分 API 中不同端可能因为平台的支持，用法上会有所区别，使用时查看对应平台 API 的文档，注意差别：
- 要根据平台去传入正确的 platformID
- Login API 参数不一致
- APP 端需要 [initSDK](docs/sdks/api/initialization/initSDK.mdx) 后才能使用
Expand Down Expand Up @@ -108,7 +102,7 @@ IMSDK.asyncApi('login', IMSDK.uuid(), {
userID : '123',
token: 'token',
platformID: 5,
wsAddr: 'ws://your-server-ip:10003',
wsAddr: 'ws://your-server-ip:10001',
apiAddr: 'http://your-server-ip:10002',
});
// #endif
Expand All @@ -129,7 +123,7 @@ IMSDK.asyncApi('login', IMSDK.uuid(), {
![uni_build](./assets/uni_build.png)

#### 4.2. 运行到自定义调试基座启动
#### 4.2. 运行到自定义调试基座启动 （ iOS 仅支持在真机调试 ）

> 本地进行 APP 端调试时，必须打包自定义基座，在启动自定义基座进行调试。
Expand Down
50 changes: 22 additions & 28 deletions i18n/en/docusaurus-plugin-content-docs-sdks/current/quickstart/uniapp.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,46 +9,44 @@ sidebar_position: 6
We strongly recommend that you first run the framework-related examples we have prepared for you [DEMO](https://github.com/openimsdk/open-im-uniapp-demo). This will not only allow you to intuitively experience the functionality of OpenIMSDK but also help you quickly identify and resolve issues during the actual integration process.

## ❗️Tips
## ❗️Common Questions

### 1. Server Preparation
### 1. Developing Only H5 and Mini Programs

- If you are using the [pure JS version SDK](/sdks/quickstart/miniProgram), your server(OpenIM Server) version needs to be greater than 3.8.2.
- If you are not developing for the App platform, use the [JSSDK](/sdks/quickstart/miniProgram) for H5 and Mini Program development. ***No need*** to follow the steps below.

### 2. Developing Cross-Platform Applications (APP, H5, Mini Programs) with Uni
### 2. Using Uni for Multi-Platform Development (APP, H5, Mini Programs)

- The latest npm package now supports the development of cross-platform applications on uni-app. However, it requires the use of **conditional compilation** syntax. It is recommended to refer to the demo before starting development, as it demonstrates how to develop in a cross-platform scenario.
- To run on iOS and Android, it is ***mandatory*** to install native plugins. The middle layer `openim-uniapp-polyfill` combines App native plugins and JSSDK capabilities, enabling unified development across APP, H5, and Mini Programs with the same codebase (SDK and im-server version >= 3.8.2).

### 2. Development for H5/Mini Programs Only
### 3. About Dependencies

- If you are developing for H5 and Mini Programs (or native Mini Programs) using uniapp, simply use the [pure JS version SDK](/sdks/quickstart/miniProgram) ***without*** following the steps below.
- **@openim/client-sdk**: JSSDK, required for running H5 and Mini Programs.

---
- **App native language plugins**: Required for running on iOS and Android.

- **openim-uniapp-polyfill**: Mandatory. It encapsulates JSSDK and native plugins, enabling unified development across multiple platforms.

## Integration Steps
---

Including APP-side development, it is **essential** to follow the steps below to import the SDK using cloud plugins and npm packages. This is because the implementation for the APP side is done through [App Native Language Plugins](https://uniapp.dcloud.net.cn/plugin/native-plugin.html).
## ⚙️ Integration Steps

### 1. Add Dependencies

> Official plugins have been uploaded to the [dcloud plugin market](https://ext.dcloud.net.cn/plugin?id=6577).
- Install dependencies using npm:

- Choose the corresponding project and package name to import the SDK.
```bash
npm install openim-uniapp-polyfill @openim/client-sdk
```

- [dcloud Plugins Market](https://ext.dcloud.net.cn/plugin?id=6577) Select the appropriate project and package name to import the SDK

![uni_import](./assets/uni_import.png)

- Open the `manifest.json` file in the root directory of the imported SDK project, select **App Native Plugin Configuration**, and import the cloud plugin.

![uni_import_manifest](./assets/uni_import_manifest.png)

- Download the npm package to simplify the import and use of the SDK and wrap the API in Promise form.

> For versions of openim-uniapp-polyfill >= 1.3.0, use the [pure JS version SDK](/sdks/quickstart/miniProgram) for non-APP platforms.
```bash
npm install openim-uniapp-polyfill open-im-sdk
```

### 2. Import in Project (Pure APP Project)

```javascript
Expand All @@ -70,13 +68,9 @@ IMSDK.unsubscribe(IMSDK.IMEvents.OnConnectSuccess, onConnectSuccess);

### 3. Import in Project (APP、H5、Mini Program Project)

> You need to use cloud plugins to import the SDK. For the new npm package, use the [pure JS version SDK](/sdks/quickstart/miniProgram) for non-APP platforms.
- Note 1: `openim-uniapp-polyfill` version should be >= 1.2.0 ,`open-im-sdk` version should be >= 3.5.1-alpha.8 .

- Note 2: Use uniapp's method to call listeners, passing in methods from `IMSDK.IMEvents`, as there is a difference in case sensitivity between JSSDK and APP. This conversion is already handled in the npm package.
- Note 1: Use uniapp's method to call listeners, passing in methods from `IMSDK.IMEvents`, as there is a difference in case sensitivity between JSSDK and APP. This conversion is already handled in the npm package.

- Note 3: In some APIs, there may be differences between platforms due to platform support. When using them, check the documentation for the respective platform's API and note the differences:
- Note 2: In some APIs, there may be differences between platforms due to platform support. When using them, check the documentation for the respective platform's API and note the differences:
- Depending on the platform, pass the correct `platformID`.
- Login API parameters may vary.
- On APP you need to [initSDK](/sdks/api/initialization/initSDK) before using it.
Expand Down Expand Up @@ -108,7 +102,7 @@ IMSDK.asyncApi('login', IMSDK.uuid(), {
userID : '123',
token: 'token',
platformID: 5,
wsAddr: 'ws://your-server-ip:10003',
wsAddr: 'ws://your-server-ip:10001',
apiAddr: 'http://your-server-ip:10002',
});
// #endif
Expand All @@ -129,7 +123,7 @@ IMSDK.asyncApi('login', IMSDK.uuid(), {
![uni_build](./assets/uni_build.png)

#### 4.2. Run on Custom Debug Base
#### 4.2. Run on Custom Debug Base (iOS Only Supports Real Device Debugging)

> When debugging the APP side locally, you must package a custom base and start debugging on it.
Expand Down

0 comments on commit 308197a

Please sign in to comment.