uniapp實現IM即時通訊仿微信聊天功能

本文介紹如何基於 UNIAPP 使用 即時通訊SDK ZIM SDK 快速實現基本的消息收發功能。

1 uniapp im 即時通訊功能 方案介紹

即時通訊SDK ZIM SDK 提供瞭如下接入方案：

在此方案中，您需要通過您自己的業務系統實現以下業務邏輯：

• 搭建客戶端的用戶管理邏輯，並下發用戶 ID 用於客戶端登錄。
• 鑒權 Token，建議由您的業務後臺自行實現，保證鑒權數據安全。

uni-app SDK 是一個基於原生 iOS/Android 平臺 ZIM SDK 的 uni-app Wrapper。開發者如需使用 uni-app 開發 Web 或小程式平臺的應用，請下載對應的 SDK 集成使用：下載 Web SDK 和 下載小程式 SDK。

2 集成 IM 即時通訊SDK 的前提條件

在使用 IM即時通訊 SDK ZIM SDK 前，請確保：

• 已在 ZEGO 控制台 創建項目，獲取到了接入 IM即時通訊 ZIM SDK 服務所需的 AppID 和 ServerSecret。ZIM 服務許可權不是預設開啟的，使用前，請先在 ZEGO 控制台 自助開通 ZIM 即時通訊 服務（詳情請參考 項目管理 - 即時通訊），若無法開通 ZIM即時通訊 服務，請聯繫 ZEGO 技術支持開通。
• 已獲取登錄 即時通訊 SDK 所需的 Token，詳情請參考 使用 Token 鑒權。

3 集成 uniapp IM 即時通訊 SDK

3.1 （可選）新建項目

此步驟以如何創建新項目為例，如果是集成到已有項目，可忽略此步。

1. 啟動 HBuilderX，選擇“文件 > 新建 > 項目”菜單。
   

2. 在出現的表單中，選擇 “uni-app” 平臺，並填寫項目名稱。
   

3. 單擊“創建”，即可創建項目。

3.2 導入ZIM 即時通訊 SDK

以下兩種方式可以任選一種導入。

方式一：在 ZEGO即構科技 官網下載 ZIM 即時通訊 SDK

1. 請參考 下載 頁面，獲取最新版本的 SDK 到本地，並將得到的 “zego-ZIMUniPlugin.zip” 文件解壓縮。

2. 將解壓縮後的文件夾，直接複製到項目工程根目錄下的 “nativeplugins” 文件夾，如果沒有該目錄，請手動創建。
   

方式二：通過 uni-app 插件市場獲取 ZIM uni-app SDK

通過 uni-app 插件市場也有兩種方式導入，請任選一種：

• 單擊 “購買（0元） for 雲打包”，選擇相應的項目導入。

• 單擊 “下載 for 離線打包”，離線導入。

  1. 下載 SDK 到本地，並將得到的 “zego-ZIMUniPlugin.zip” 文件解壓縮。
  2. 將解壓縮後的文件夾，直接複製到項目工程根目錄下的 “nativeplugins” 文件夾，如果沒有該目錄，請手動創建。

3.3 在 uni-app 項目中導入插件

1. 單擊項目目錄的 “manifest.json” 文件後，單擊 “App原生插件配置” 中的 “選擇本地插件” 或 “選擇雲端插件”。
   

2. 在彈出的選擇框中，選擇 “Zego ZIM 即時通訊 SDK” 後，單擊“確認”，即添加成功。

3.4 自定義調試基座

3.4.1 製作自定義調試基座

uni-app 官方自定義調試基座使用說明，請參考 什麼是自定義調試基座及使用說明 。

1. 選擇 “運行 > 運行到手機或模擬器 > 製作自定義調試基座” 菜單。
   

2. 在彈出的界面中，按照 uni-app 教程，填寫相關信息，並單擊“打包”進行雲打包。
   

   打包成功後，控制台會收到 uni-app 的相關提示。
   

3.4.2 切換運行基座為自定義調試基座

自定義調試基座，請選擇“運行 > 運行到手機或模擬器 > 運行基座選擇 > 自定義調試基座”菜單。

3.5 集成 JS 封裝層

3.5.1 導入 JS 封裝層

以下兩種方式可以任選一種導入。

• 方式一：請參考 下載 頁面，獲取最新版本的 JS 封裝層到本地，並將得到的 “zego-ZIMUniPlugin-JS.zip” 文件解壓縮。

  下載的 JS 封裝層可以拷貝到 HBuilderX 的 “js_sdk” 目錄中。（如無該目錄，請創建一個）
  

• 方式二：在插件市場的 Zego ZIM 即時通訊原生插件（JS 封裝層） 界面單擊右側的 “使用 HBuilderX 導入插件”。
  

  導入的 JS 封裝層將存儲在 “js_sdk” 目錄中。
  

3.5.2 在項目中引入 JS 封裝層

導入後，可以在業務代碼中引入 JS 封裝層，並調用 ZIM 相關介面，示例如下：

import { ZIM } from 'zego-zim-react-native';

或

const ZIM = require('zego-zim-react-native').ZIM;

4 實現仿微信的基本收發消息聊天功能

以下流程中，我們以客戶端 A 和 B 的消息交互為例，實現 1v1 通信功能：

4.1 uniapp 即時通訊 實現流程

請參考 跑通示例源碼 獲取源碼。

1. 導入ZIM 即時通訊 SDK 文件

請參考 3.2 導入 SDK，導入 SDK 文件。

2. 創建 ZIM即時通訊 實例

首先我們需要在項目中創建 ZIM 實例，一個實例對應的是一個用戶，表示一個用戶以客戶端的身份登錄系統。

例如，客戶端 A、B 分別調用 create(@create) 介面，傳入在 2 前提條件 中獲取到的 AppID，創建了 A、B 的實例：

var appID = xxxx;
// 靜態同步方法，創建 zim 實例，傳入 AppID
var zim = ZIM.create(appID);

3. 監聽回調事件

在客戶端登錄前，開發者可以通過調用 on 介面，自定義 ZIM 中的事件回調，接收到 SDK 異常、消息通知回調等的通知。

// 註冊監聽“運行時錯誤信息”的回調  
zim.on('error', function (zim, errorInfo) {
    console.log('error', errorInfo.code, errorInfo.message);
});

// 註冊監聽“網路連接狀態變更”的回調
zim.on('connectionStateChanged', function (zim, { state, event, extendedData }) {
    console.log('connectionStateChanged', state, event, extendedData);
});

// 註冊監聽“收到單聊消息”的回調
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log('receivePeerMessage', messageList, fromConversationID);
});

// 註冊監聽“令牌即將過期”的回調
zim.on('tokenWillExpire', function (zim, { second }) {
    console.log('tokenWillExpire', second);
    // 可以在這裡調用 renewToken 介面來更新 token
    // 新 token 生成可以參考上文
    zim.renewToken(token)
        .then(function({ token }){
            // 更新成功
        })
        .catch(function(err){
            // 更新失敗
        })
});

4. 登錄 ZIM 即時通訊

創建實例後，客戶端 A 和 B 需要登錄 ZIM，只有登錄成功後才可以開始發送、接收消息、更新 Token 等。

客戶端需要使用各自的用戶信息和 Token 進行登錄。調用 login 介面進行登錄，傳入用戶信息 ZIMUserInfo 對象，以及在 2 前提條件 中獲取到的 Token 進行鑒權，鑒權通過後才能登錄成功。

• “userID”、“userName” 支持開發者自定義規則生成。建議開發者將 “userID” 設置為一個有意義的值，可將其與自己的業務賬號系統進行關聯。
• 如果 Token 過期，需要在 tokenWillExpire 即將過期回調介面中，調用 renewToken 介面，更新 Token 後才能正常使用 SDK。

// 登錄時，需要開發者 按照 "使用 Token 鑒權" 文檔生成 token 即可
// userID 和 userName，最大 32 位元組的字元串。僅支持數字，英文字元 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'。
var userInfo = { userID: 'xxxx', userName: 'xxxx' };
var token = '';

zim.login(userInfo, token)
    .then(function () {
        // 登錄成功
    })
    .catch(function (err) {
        // 登錄失敗
    });

5. 發送消息聊天驗證

客戶端 A 登錄成功後，可以向客戶端 B 發送消息。

目前 ZIM 支持的消息類型如下：

以下為發送單聊文本消息為例：客戶端 A 可以調用 sendPeerMessage 介面，傳入客戶端 B 的 userID、消息內容等信息，即可發送一條文本消息到 B 的客戶端。

var toUserID = 'xxxx1';
var config = { 
    priority: 1 // 消息優先順序，取值為 低:1 預設,中:2,高:3
};

// 發送單聊 `Text` 信息
var messageTextObj = { type: 1, message: '文本消息內容' };
zim.sendPeerMessage(messageTextObj, toUserID, config)
    .then(function ({ message }) {
        // 發送成功
    })
    .catch(function (err) {
        // 發送失敗
    });

6. 接收消息聊天驗證

客戶端 B 登錄 ZIM 後，將會收到在 on 回調中設置的 receivePeerMessage 監聽介面，收到客戶端 A 發送過來的消息。

// 註冊監聽“收到單聊消息”的回調
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log('receivePeerMessage', messageList, fromConversationID);
});

7. 退出登錄

如果客戶端需要退出登錄，直接調用 logout 介面即可。

zim.logout();

8. 銷毀 ZIM 實例

如果不需要 ZIM 實例，可直接調用 destroy 介面，銷毀實例。

zim.destroy();

4.2 API 時序圖

通過以上的實現流程描述，API 介面調用時序圖如下：

5 uniapp跨平臺框架接入ZIM 即時通訊 SDK更多幫助

獲取本文即時通訊框架接入IM 即時通訊聊天的開發文檔、技術支持，訪問即構文檔中心IM即時通訊開發文檔頁，可多平臺實現聊天社交IM即時通訊功能；

近期有開發規劃的開發者可上即構官網查看，恰逢即構七周年全線音視頻產品1折的優惠，聯繫商務獲取"IM即時通訊一個月免費試用 "產品優惠；