From 20a287ca6f62ae076395977bab289f3de2522bfe Mon Sep 17 00:00:00 2001
From: DCloud__JSON <linju@dcloud.io>
Date: Tue, 14 Feb 2023 20:24:17 +0800
Subject: [PATCH] Update uni-im.md

---
 docs/uniCloud/uni-im.md | 170 ++++++++++++++++++++++++----------------
 1 file changed, 102 insertions(+), 68 deletions(-)

diff --git a/docs/uniCloud/uni-im.md b/docs/uniCloud/uni-im.md
index 30fe683e2..a5ce92082 100644
--- a/docs/uniCloud/uni-im.md
+++ b/docs/uniCloud/uni-im.md
@@ -1,4 +1,4 @@
-> 本插件APP端需要HBuilderX 3.6.9 及其以上版本支持，微信小程序和网页端需要HBuilderX 3.6.4 及其以上版本支持。
+> 本插件需要HBuilderX 3.6.9 及其以上版本支持。
 
 # 简介
 uni-im是云端一体的、全平台的、免费的、开源即时通讯系统。
@@ -6,8 +6,10 @@ uni-im是云端一体的、全平台的、免费的、开源即时通讯系统
 - 基于uniCloud，前后端都使用js开发
 - 基于[uni-push2](https://uniapp.dcloud.net.cn/unipush-v2.html)，专业稳定的全端推送系统
 - 基于[uni-id](https://uniapp.dcloud.net.cn/uniCloud/uni-id-summary.html)，完善的账户体系
+- 支持服务端为非uniCloud（比如：应用服务端的开发语言是php、java、go、.net、python、c#等）或 不基于uni-id-pages 开发的项目接入
 
-案例：打开[插件市场](https://ext.dcloud.net.cn/plugin?id=55)，点击咨询作者按钮
+
+案例：打开[插件市场](https://ext.dcloud.net.cn/plugin?id=55)，点击咨询作者按钮，即可看到基于uni-im搭建的客服系统
 
 下载地址：[https://ext.dcloud.net.cn/plugin?name=uni-im](https://ext.dcloud.net.cn/plugin?name=uni-im)
 
@@ -19,6 +21,24 @@ uni-im是云端一体的、全平台的、免费的、开源即时通讯系统
 - 中心化响应式数据管理，切换会话不重头加载数据，更流畅的体验
 - App端聚合多个手机厂商推送通道，app不在线也可以收到消息
 
+## 版本计划  
+### 已上线
+- 应用内嵌入uni-im，使用户方便、实时的与App运营者互动，咨询问题、反馈意见、进行投诉。
+- 可发送文字、图片、音频、视频、代码、任意文件
+- im交友场景：群聊、好友关系
+
+### 后续计划
+1. 通信方式扩展：音频通话、视频通话
+2. 细节完善：聊天记录识别电话邮件、消息删除和批删、消息回复、消息转发和批转、消息撤回、勿扰设置、会话置顶、留言转文字、图片提取文字
+3. 客服场景：管理端支持座席
+
+优先开发哪些，取决于开发者的反馈。同时也欢迎开发者共建这个开源项目。
+
+> uni-im相关功能建议或问题交流，暂时请加QQ群号:[854520009](https://qm.qq.com/cgi-bin/qm/qr?k=DJNSajXAYHnYcr9pouOfxF9Rwwl1AJHc&jump_from=webapi&authKey=HZ1fG58Eudp3o0GCoyx1/UPMY9Fv1sGT5jdqYqPJlTGT0XVUip3Bk8E+UyToQOMo)。后续uni-im支持群聊后会废除QQ改为uni-im。
+
+### 已知bug
+- Mac端Safari浏览器，消息列表界面滚动到顶部无法自动加载历史消息
+
 ## 使用uniCloud产生的费用说明@cost
 
 uni-im本身并不收费，实际使用中需要依赖uniCloud云服务，会产生费用；而uniCloud的价格很实惠：  
@@ -51,34 +71,17 @@ uni-im本身并不收费，实际使用中需要依赖uniCloud云服务，会产
 
 相比市面上同类型产品，使用uni-im仅需花费如此便宜的uniCloud（serverless服务器）费用；在价格这块uni-im性价比极高。
 
-## 版本计划  
-### 已上线
-- 应用内嵌入uni-im，使用户方便、实时的与App运营者互动，咨询问题、反馈意见、进行投诉。
-- 可发送文字、图片、音频、视频、代码、任意文件
-- im交友场景：群聊、好友关系
-
-### 后续计划
-1. 通信方式扩展：音频通话、视频通话
-2. 细节完善：聊天记录识别电话邮件、消息删除和批删、消息回复、消息转发和批转、消息撤回、勿扰设置、会话置顶、留言转文字、图片提取文字
-3. 客服场景：管理端支持座席
-
-优先开发哪些，取决于开发者的反馈。同时也欢迎开发者共建这个开源项目。
-
-> uni-im相关功能建议或问题交流，暂时请加QQ群号:[854520009](https://qm.qq.com/cgi-bin/qm/qr?k=DJNSajXAYHnYcr9pouOfxF9Rwwl1AJHc&jump_from=webapi&authKey=HZ1fG58Eudp3o0GCoyx1/UPMY9Fv1sGT5jdqYqPJlTGT0XVUip3Bk8E+UyToQOMo)。后续uni-im支持群聊后会废除QQ改为uni-im。
-
-### 已知bug
-- Mac端Safari浏览器，消息列表界面滚动到顶部无法自动加载历史消息
-
 # 快速部署体验
 ## 前提条件
-1. 开通uniCloud并创建服务空间 [控制面板](https://unicloud.dcloud.net.cn/)
-2. 开通`uni-push2.0`[详情参考](https://uniapp.dcloud.net.cn/unipush-v2.html#%E7%AC%AC%E4%B8%80%E6%AD%A5-%E5%BC%80%E9%80%9A)
+1. 开通uniCloud并创建服务空间 [控制面板](https://unicloud.dcloud.net.cn/)  
+	传统的IM产品服务端代码托管在服务商名下的服务器内，你只拥有代码和产生的数据的使用权，并非所有权；而uni-im的前后端代码都是开源的，是将代码托管在你名下的unicloud（[serverless](https://uniapp.dcloud.net.cn/uniCloud/#%E4%BB%80%E4%B9%88%E6%98%AFserverless)服务器）内。
+2. 开通`uni-push2.0`（无论是APP、小程序、web端都需要开通，否则消息将无法实时更新）[详情参考](https://uniapp.dcloud.net.cn/unipush-v2.html#%E7%AC%AC%E4%B8%80%E6%AD%A5-%E5%BC%80%E9%80%9A)
 
 ## 体验步骤
 
 1. 打开`uni-im`插件下载地址：[https://ext.dcloud.net.cn/plugin?name=uni-im](https://ext.dcloud.net.cn/plugin?name=uni-im)
 2. 点击`使用HBuilderX导入示例项目`
-3. 按提示，通过云服务空间初始化向导部署项目（注意：选择绑定的服务空间，须在uni-push2.0的[web控制台](https://dev.dcloud.net.cn/pages/app/push2/info)关联）
+3. 对项目根目录uniCloud点右键选择“云服务空间初始化向导”界面按提示部署项目（注意：选择绑定的服务空间，须在uni-push2.0的[web控制台](https://dev.dcloud.net.cn/pages/app/push2/info)关联）
 4. `运行项目`到2个不同的浏览器，因为在同一个浏览器打开相同网络地址（ip或者域名）的uni-im项目，socket会相互占线。
 	所以需要使用两个浏览器（或者使用浏览器`打开新的无痕式窗口`功能充当第二个浏览器）分别`注册账号并登录`，
 	到此部署已经结束
@@ -87,12 +90,12 @@ uni-im本身并不收费，实际使用中需要依赖uniCloud云服务，会产
 ## 部署到自己的项目
 1. 打开`uni-im`插件下载地址：[https://ext.dcloud.net.cn/plugin?name=uni-im](https://ext.dcloud.net.cn/plugin?name=uni-im)
 2. 点击`使用HBuilderX导入插件`，选择你的项目，点击确定（同时会自动导入依赖的uni_modules`uni-id-pages`）按提示操作自动配置`pages.json`
-3. 打开项目根目录的App.vue文件，初始化uni-id-pages和uniIm模块
+3. 打开项目根目录的App.vue文件，初始化uni-id-pages和uniIm模块  
 示例如下：
 
 ```html
 <script>
-	//1. 导入uni身份信息管理模块
+	//1. 导入统一身份信息管理模块
 	import uniIdPagesInit from '@/uni_modules/uni-id-pages/init.js';
 	//2. 导入uniIm的Utils工具类
 	import uniImUtils from '@/uni_modules/uni-im/common/utils.js';
@@ -169,50 +172,79 @@ uni-im本身并不收费，实际使用中需要依赖uniCloud云服务，会产
 	export default store
 ```
 
-5. 账号打通
+5. 设置表的读取权限  
+参考示例项目的用户表的表结构，设置读取权限；路径：`/uni_modules/uni-id-pages/uniCloud/database/uni-id-users.schema.json` 将：根节点和properties下avatar_file、email、mobile、nickname、username的permission下"read"值设置为：true。表示允许客户端读取这些字段（不用担心数据泄露，uni-im预置了用户表的触发器，会对相关字段做脱敏处理，比如手机号会变成180*&#42;&#42;6606）
 
-uni-im经常用于嵌入其他App中，成为其中的一个模块。比如客服模块。这就涉及现有应用和uni-im的账户打通问题。
+6. 部署到uniCloud  
+对项目根目录uniCloud点右键，选择“云服务空间初始化向导” 按提示部署项目（注意：选择绑定的服务空间，须在uni-push2.0的[web控制台](https://dev.dcloud.net.cn/pages/app/push2/info)关联）
 
-uni-im的账户体系是uni-id的。如果开发者的现有应用要接入uni-im，但账户体系并不在uni-id里，或使用的是老版uni-id，就需要参考本章节打通账户。
+7. 登录uni-im  
 
-- 基于`uni-id-pages`的项目，直接登录即可，无需额外打通工作。
-- 基于`uni-id-co`的项目，需要在登录成功和用户信息更新时，同步更新uniId store内的当前用户信息（uni-im显示当前用户头像、昵称时会用到）示例代码：
-```js
-	//导入uniCloud客户端账户体系，用户信息状态管理模块
-	import {mutations as uniIdMutations} from '@/uni_modules/uni-id-pages/common/store.js';
-	await uniIdMutations.updateUserInfo()
-```
-- 基于老版uni-id(版本号：3.x) 开发的项目，需要如下改造：
-	1. 在登录成功和token续期后，绑定当前账号与设备推送标识的关联关系。示例代码：
-```js
-	const uniIdCo = uniCloud.importObject("uni-id-co", {customUI: true})
-	uni.getPushClientId({
-		success: async function(e) {
-			console.log(e)
-			let pushClientId = e.cid
-			let res = await uniIdCo.setPushCid({
-				pushClientId
-			})
-			console.log('getPushClientId', res);
+	uni-im的服务端代码托管在uniCloud下，账户体系是[uni-id](https://uniapp.dcloud.net.cn/uniCloud/uni-id-summary.html)的；
+	uni-app生态下绝大部分项目的架构与uni-im相同，所以不需要考虑账号打通问题，用户登录项目后，不需要额外登录uni-im。
+
+	而有些传统项目，服务端的开发语言是php、java、go、.net、python、c#等，是自己设计的账号体系；用户登录所获得的token，与uni-im所需的token不是同一个账号体系；需要通过[uni-id的外部系统联登](https://uniapp.dcloud.net.cn/uniCloud/uni-id-pages.html#external)同步你项目的账号数据到uni-im用户体系并获得uni-id的token，客户端再调用uniImUtils的login方法登录uni-im；示例代码如下：
+
+	```js
+	import uniImUtils from '@/uni_modules/uni-im/common/utils.js';
+
+	uni.request({
+		url: 'https://www.example.com/login', //仅为示例，并非真实接口地址。
+		data: {
+			username: 'test',
+			password: '123456'
 		},
-		fail(e) {
-			console.error(e)
+		success:async (res) => {
+			console.log(res.data); 
+			// 得到你自己项目的token和uni-id的token
+			// uniImToken 是一个对象：{token,tokenExpired}
+			let {token,uniImToken} = res.data
+			uni.setStorageSync('token',token)
+			await uniImUtils.login(uniImToken)
 		}
-	})
-```
-	2. 在登录成功和用户信息更新时，同步更新uniId store内的当前用户信息（uni-im显示当前用户头像、昵称时会用到）示例代码：
-```js
-	//导入uniCloud客户端账户体系，用户信息状态管理模块
-	import {mutations as uniIdMutations} from '@/uni_modules/uni-id-pages/common/store.js';
-	await uniIdMutations.updateUserInfo()
-```
-- 客户端是uni-app的，但服务器不是uniCloud的情况。需开通uniCloud，然后在客户端通过uni-im-co的loginWithJWT方法实现联登，因内容较多，需另见[文档](#uniImCoLoginWithJWT)。
-- 客户端如果不是uni-app的，如果是网页，可iframe内嵌。如果是app，可嵌入[uni小程序sdk](https://nativesupport.dcloud.net.cn/README)
+	});
+
+	```
+
+	其他情况：  
 
-6. 确保账户对接成功后，打开“用户列表页”，路径：`/uni_modules/uni-im/pages/userList/userList`可以看到所有的注册用户（默认仅登录的账号为超级管理员才有权限访问，你也可以根据自己的业务需求修改`uniCloud/database/uni-id-users.schema.json`配置权限[更多详情](https://uniapp.dcloud.net.cn/uniCloud/schema.html#permission)）
-7. 点击某个用户，会自动创建与该用户的会话，并打开“聊天对话页”（路径：`/uni_modules/uni-im/pages/chat/chat`），然后就可以开始聊天了。
-8. 还可以导入uni-im的示例项目作为管理员端与用户聊天。
-9. 如果你是2个不同appId的应用相互通讯（比如：淘宝的买家端和卖家端通讯）的场景，请打开聊天对话文件（路径：`/uni_modules/uni-im/pages/chat/chat`）搜索`data.appId = this.systemInfo.appId`修改`this.systemInfo.appId`为相对的appId
+	- 客户端如果不是uni-app的，如果是网页，可iframe内嵌。如果是原生app，可嵌入[uni小程序sdk](https://nativesupport.dcloud.net.cn/README)
+
+	- 不基于`uni-id-pages`的客户端代码，仅基于`uni-id-co`的项目，需要在登录成功和用户信息更新时，同步更新uniId store内的当前用户信息（uni-im显示当前用户头像、昵称时会用到）示例代码：
+	```js
+		//导入uniCloud客户端账户体系，用户信息状态管理模块
+		import {mutations as uniIdMutations} from '@/uni_modules/uni-id-pages/common/store.js';
+		await uniIdMutations.updateUserInfo()
+	```
+	- 基于老版uni-id(版本号：3.x) 开发的项目，需要如下改造：
+		1. 在登录成功和token续期后，绑定当前账号与设备推送标识的关联关系。示例代码：
+	```js
+		const uniIdCo = uniCloud.importObject("uni-id-co", {customUI: true})
+		uni.getPushClientId({
+			success: async function(e) {
+				console.log(e)
+				let pushClientId = e.cid
+				let res = await uniIdCo.setPushCid({
+					pushClientId
+				})
+				console.log('getPushClientId', res);
+			},
+			fail(e) {
+				console.error(e)
+			}
+		})
+	```
+		2. 在登录成功和用户信息更新时，同步更新uniId store内的当前用户信息（uni-im显示当前用户头像、昵称时会用到）示例代码：
+	```js
+		//导入uniCloud客户端账户体系，用户信息状态管理模块
+		import {mutations as uniIdMutations} from '@/uni_modules/uni-id-pages/common/store.js';
+		await uniIdMutations.updateUserInfo()
+	```
+
+8. 确保账户对接成功后，打开“用户列表页”，路径：`/uni_modules/uni-im/pages/userList/userList`可以看到所有的注册用户（默认仅登录的账号为超级管理员才有权限访问，你也可以根据自己的业务需求修改`uniCloud/database/uni-id-users.schema.json`配置权限[更多详情](https://uniapp.dcloud.net.cn/uniCloud/schema.html#permission)）
+9. 点击某个用户，会自动创建与该用户的会话，并打开“聊天对话页”（路径：`/uni_modules/uni-im/pages/chat/chat`），然后就可以开始聊天了。
+10. 还可以导入uni-im的示例项目作为管理员端与用户聊天。
+11. 如果你是2个不同appId的应用相互通讯（比如：淘宝的买家端和卖家端通讯）的场景，请打开聊天对话文件（路径：`/uni_modules/uni-im/pages/chat/chat`）搜索`data.appId = this.systemInfo.appId`修改`this.systemInfo.appId`为相对的appId
 
 
 **补充：**（基于uni-id-pages开发的项目可忽略）
@@ -291,14 +323,16 @@ uni-im v1.0.0 暂时比较简单，云端有1个云对象`uni-im-co`，2个opend
 
 ## uni-im-co 云函数（云对象）
 ### API列表
-|API				|描述											|
-|--					|--												|
-|loginWithJWT		|基于jwt签名的账号登录方式[见下方](#uniImCoLoginWithJWT)				|
-|getConversationList|获取会话列表[见下方](#coGetConversationList)	|
-|sendMsg			|发送聊天消息[见下方](#coSendMsg)				|
+|API										|描述													|
+|--											|--														|
+|loginWithJWT（已过期，请使用[uni-id的外部系统联登](https://uniapp.dcloud.net.cn/uniCloud/uni-id-pages.html#external)）	|基于jwt签名的账号登录方式[见下方](#uniImCoLoginWithJWT)|
+|getConversationList						|获取会话列表[见下方](#coGetConversationList)			|
+|sendMsg									|发送聊天消息[见下方](#coSendMsg)						|
 
 #### 账号登录loginWithJWT@uniImCoLoginWithJWT
 
+此登录方式已经过期，仅为旧项目保留。新项目请使用[uni-id的外部系统联登](https://uniapp.dcloud.net.cn/uniCloud/uni-id-pages.html#external)
+
 如果你的项目是基于非uniCloud开发的项目（比如：应用服务端的开发语言是php、java等，用户信息并没未存储在uniCloud云数据库中）需要通过跨平台签名认证的方式，向uniCloud账户体系新增用户（创建过则更新用户信息）并获取token实现登录。
 
 前置要求：添加`uni-im`配置文件，打开：`/uni_modules/uni-config-center/uniCloud/cloudfunctions/common/uni-config-center/`；新建`uni-im`文件夹和`config.json`文件，示例如下：
-- 
GitLab