本文將直白且詳細的描述一下如何集成環信web端的IM SDK，（小程序、Uni-app通用）。這是一篇快速集成攻略，其中更多的是對于官網文檔的一篇注釋說明，相信很多的小伙伴在準備將環信的IM即時通訊能力集成或移植在自己的項目上都會出現或多或少的一些問題，甚至會出現一頭霧水或無從下手的感覺，即使看遍了官方文檔也不免心生疑問......

“啥？！啥？！啥？！這是啥？！文檔寫的是個啥？！”

所以我決定更加直白且詳細的描述一下如何集成web端的IM SDK，（小程序、Uni-app通用）以下是概覽：

一、?注冊環信console，創建自己的應用，拿到Appkey。

二、?粗略瀏覽官方文檔，熟悉大致流程及接口。

三、?Clone?Demo，挑出必選引入文件。

四、?Hello?World!?（從注冊登陸開始）。

常見問題以及error報錯查詢入口：

?http://docs-im.easemob.com/faq

?Web 常見錯誤代碼 [IM 開發文檔]

常見錯誤代碼 [IM 開發文檔]

以下為較為詳細的描述一些集成步驟，如一些步驟已非常了解且已操作完成請自行跳過。

一、注冊環信console，創建自己的應用，拿到Appkey

PS:這一步驟，各端通用。

1.?注冊console?管理后臺

相信經常使用第三方服務的小伙伴都非常熟悉這一步（不熟悉？沒關系，照著葫蘆畫瓢就行），打開開發者平臺進行注冊登錄創建等操作，這一點我就不過多贅述，直接上注冊平臺鏈接：環信即時通訊云

注冊成功之后會跳轉到這樣的一個界面：

這個就是console后臺管理頁面，這個實際就屬于一個后臺管理系統，創建自己的項目應用，監測日活，統計注冊用戶數，常見的一些增刪改查操作都可以執行，沒事可以搗鼓搗鼓看看有哪些功能，這里我就不多介紹了，咱們接著往下進行。

2.?創建應用

創建應用這一步擱咱們JavaScript其實可以理解為?new?了一個空對象，var了一個空變量等等隨意怎么比喻都可以。如果放在現實當中其實更像是創建了一個公司，這個公司有公司名也就是Appname,而每個公司肯定有一個唯一的公司代碼（公司的身份證ID號），也就是Appkey。公司人數也就是創建出來的應用下注冊的用戶數量等等。

點擊添加應用開始創建：

創建應用的詳情頁：

這里我特意框住是因為經常有人告訴我：“創建出來的appkey在客戶端測試時候點擊注冊沒法注冊，報錯描述是401無權限是怎么回事？”

最后發現是創建應用的時候注冊模式選的是授權注冊，你選個授權注冊，看眼描述就知道這種注冊模式相當于注冊是要經過審批的，如果測試階段可以使用開放注冊，后期還可以修改注冊模式。

這個是創建成功之后點擊進入應用的基本信息描述，分別對應的是什么功能也有描述，Appkey也就成功拿到了，由orgname?+“#”+appname組成的appkey。如圖：

這里特別說下這個Client ID和Client Secret?，有了Client ID和Client Secret就可以獲取到管理員token從而可以在應用下隨意增刪改查，發消息，之前有遇到泄露導致客戶端用戶莫名其妙收到一些騷擾信息，當然這都算輕的，所以正式環境下一定要保管好Client ID和Client Secret?！！！

?

二、粗略瀏覽官方文檔，熟悉大致流程及接口

PS：這一步驟，各端通用

可能有的小伙伴覺得這一步我再拉出來講意義不是很大沒什么用，其實不然，因為在協助一些小伙伴集成SDK中發現有的朋友對于在自己項目中要用到的接口都還不知道在哪，更談不上如何使用。文檔通篇一字不落看下來也不太現實，但是大致知道一些后期咱們的項目中有哪些接口可能會用到，知道大概在哪能找到調用方式還是很有必要的。

一篇文檔中我們可以從這些方向看：

SDK功能分類，更新日志（了解SDK更新周期，新增功能，修復問題），Demo的使用介紹，兼容性以及常見問題。

Uni-app打包雙端的介紹，運行平臺描述，源碼的GitHub地址。

而且文檔中也有描述一些可能會遇到的坑，一些解決方案。例如：發送URL類型的圖片消息需要在config配置文件中配置。

通過“WebIM.conn.mr_cache = []?”方法可以重置拉取歷史消息的游標。

常用的新消息提示如何去處理，等等都會有一些描述，磨刀不誤砍柴工，因此我強烈建議各位在正式開始集成之前首先瀏覽一下咱們對應端的文檔。

在此我也正好有幾個常用的功能場景提供給大家，文檔中有介紹，為了方便各位也還是直接上鏈接。

消息回執（涉及到web端已讀未讀的處理）：

http://docs-im.easemob.com/im/web/basics/message#%E6%B6%88%E6%81%AF%E5%9B%9E%E6%89%A7

消息漫游（涉及到web端拉取歷史SDK接口）：

http://docs-im.easemob.com/im/web/basics/message#%E6%B6%88%E6%81%AF%E6%BC%AB%E6%B8%B8

昵稱與頭像（涉及到昵稱與頭像的處理）：

昵稱和頭像的顯示與更新 [IM 開發文檔]

獲取管理員token（一些服務端rest接口的調用需獲取管理員token）：

使用環信 App Token 鑒權 | 環信 IM 文檔

拉取歷史消息文件（將聊天產生的歷史消息保存到本地服務器）：

????????https://docs-im-beta.easemob.com/document/server-side/message.html#%E8%8E%B7%E5%8F%96%E5%8E%86%E5%8F%B2%E6%B6%88%E6%81%AF%E8%AE%B0%E5%BD%95

更多常用實現場景可以參考文檔常見方案一欄，里面可能有些只有IOS?和?Android?解決方案，但是web端實際也是相似的處理方式，瞜一眼相信會有些啟發。

直播聊天室集成介紹 [IM 開發文檔]

文檔已瀏覽完畢，接著往下進行。

三、Clone?Demo、挑選出必要文件

其實這一步主要面向于直接下載了官網Demo，但是不知道如何把將Demo往里引入的同學，在協助集成的過程中，我經常遇到有些朋友啟動Demo測試完成之后，直接就把所有Demo文件拷貝到了原有項目當中，我們知道前端的部署打包的性能優化是與壓縮精簡代碼，減少請求數量，頁面結構，瀏覽器緩存等因素是相關的，我并不建議完全將Demo拷貝到咱們的原項目當中。

首先我想說下現有PCweb-Demo?uni-appDemo?微信小程序Demo等Demo?的意義是為我們開發者小伙伴展示功能接口的實際運用，即時通訊能力的接口測驗，各接口組合使用的運用邏輯及調用順序?，當然更是給了咱們在實際項目開發當中有了一定的參考作用。由于其功能性的考慮并沒有按照線上產品的標準去做，所以其代碼內部接口中有些接口的調用以及請求并未考慮性能因素，功能并未完全實現展示。

相信通過我的描述，也就明白了為什么不建議將Demo完全拷貝到原有項目中，因為可能會對咱們的性能優化造成一定的影響，并且可能會有很多代碼對項目中的功能實現并無任何幫助，有些組件關聯，運行可能會有更多難以排查的報錯，更多是建議可以參考一下Demo當中的寫法。

下面我先介紹一下uni-app-Demo集成?IMSDK的操作：

Uni-App-Demo?GitHub地址：

GitHub - easemob/webim-uniapp-demo

1.?將clone下來Demo于HbuilderX中打開，首先咱們不急著運行先了解一下目錄下各個文件的作用。

<!-- 截圖來自uni-appDemo中的README.md文件，詳細可以自行查看 -->

2.?將核心文件導入到自己的測試項目或正式項目中。

隨著環信3.x?IM SDK的更新，現在引入依賴文件相對之前2.x?IM SDK的集成引數個文件無疑是簡單了許多。

Uni-app-Demo中需要引用的文件截圖：

其實除SDK必須引入之外，WebIMConfig.js?以及WebIM.js也可以不引用，但是在項目中必須要存在，聽起來很矛盾，但實際含義就是WebIMConfig.js該有的配置你必須要配置，WebIM.js中的初始化這一步你也必須要進行初始化，至于你要命名為其他文件名，放在其他位置也不是不可以的。

SDK包：PCWeb端：websdk3.x.js?小程序/Uni-app：wxsdk3.x.js

WebIMConfig.js：這個文件的作用就是將引入的WebIMSDK進行自定義配置：

如圖文檔上有對各個配置項的作用詳細介紹，建議在集成過程中的配置頁可以參考Demo中的配置進行配置，但是各個配置項的開啟與否，參數設置請自行按需設置。

依然是在協助小伙伴集成環信IM的過程經常會遇到有小伙伴問配置項中的：“socket Server地址：socketServer: '//im-api-v2.easemob.com/ws', ???// ”和“rest Server地址：restServer: '//a1.easemob.com' ”，“需不需要配置成自己項目地址，或者自己去定義這兩個參數？”，對于這個問題，我只能回答說千萬別！這個是定義好了的，你要做的基本就只需要將appkey：改成自己申請的，其他幾乎不用動。

WebIM.js：將SDK的配置以及引入的SDK進一步做處理簡稱：初始化。

導出SDK?并引入WebIMConfig.js文件,將SDK重命名為WebIM掛載到window或uni或wx下，視情況決定。

同樣這一步文檔也有詳細的描述：

3.?完成文件導入掛載，開始配置并添加監聽回調。

如圖，監聽僅截圖一部分：

在集成Web端（包括小程序以及Uni-app）IM中，所有的事件監聽都是要靠WebIM.conn.listen( )，由此可以看出其重要性。

所以在初始化階段結束后我們首要將監聽配置添加上。

至于監聽的具體位置應該添加在哪里這個實際并沒有嚴格的要求，PCwebDemo中是將監聽寫在了WebIM.js中，微信小程序Demo是將監聽寫在了app.js，uni-app是將監聽寫在了App.vue根組件中，多數是寫在了全局。但其實監聽也可以寫在局部，前提局部能夠訪問到WebIM，然后在局部添加上監聽回調，不管是全局監聽還是局部監聽都要在SDK接口調用之前布置好監聽并開啟監聽。

下面我們再來聊一下監聽中的個別監聽回調的作用以及實際運用，其監聽的作用文檔已有詳細描寫且較為好了解，這里就不再一一贅述。

onOpened: function ( ) {}, ? ? ? ? //連接成功回調?

此監聽為與環信連接成功之后觸發的監聽回調，經常會出現一個問題就是明明環信conn.open登陸接口都已經返回success都已經返回token了，可是發送消息依然報錯，接收消息也接收不到。那么我們首要檢查的就是該監聽有沒有觸發，放個console.log( )看下登陸之后的該回調有沒有成功的打印，如果打印了那么說明成功與環信建立了連接！也就可以進行其他的操作了。

經常有朋友問：“登陸成功之后打印message形參為什么是undefined?是不是登陸有問題？”，其實不是這個message并不會有任何返回，登陸是否成功一切以onOpened監聽回調是否執行為準！

在該監聽的實際運用中Demo中其實也做了很好的演示，就是登陸之后的頁面跳轉，這個非常常用，因為IM聊天功能是否可以使用首要的判斷必然是與環信是否建立連接成功，成功那么跳轉進入聊天頁面。

onClosed: function ( message ) {}, ? ? ? ?//連接關閉回調

此監聽為與環信連接關閉的監聽回調，其實也沒有具體要描述的地方，更多的是該監聽經常用來處理在與環信斷開連接時候的一些UI層面的提示，或者再意外斷開連接之后退回到login頁面，以及有些場景下進行手動重連。

onMessage：function?( message ) {}, ??//監聽收到消息的回調

這里的onMessage是對所有收到消息的回調的一個簡稱，例如：onTextMessage?監聽文本消息、onPictureMessage?監聽圖片消息、onAudioMessage 監聽音頻消息，等等...?這個監聽相信不用過多描述就可以清楚其功能，消息監聽回調非常的核心，所有的消息都是仰仗這幾個監聽回調拿到的。測試的時候可以在監聽回調中定義形參并控制臺打印參數查看消息監聽是否正常觸發并接收數據。

截圖為onTextMessage監聽收到的單聊消息

onError: function ( message ) {},? ? ? ? ? //失敗回調

此監聽回調可監聽SDK中大多數的error拋出，在集成開發過程中幫助更快定位問題原因，并且可在回調中根據error信息從UI層面進行提示，因此其實際運用相對也常用。

截圖為Uni-appDemo利用onError監聽做出的提示以及一些操作。

當然有些error出現之后大家可能不知道其具體含義下面為分析一下error異常的判斷思路，

首先onError監聽回調的message字段就已經給出了大致error原因：

例圖中onError回調返回的對象中的message字段value的值中給出了“login?failed”登陸異常，接著我們看data字段下給出的具體原因，不難看出invalid?password?不打開百度翻譯也能猜出密碼有問題，那么我們也就可以以此判斷，登陸密碼錯誤，或者對用戶做出彈窗提示。

同樣的type：1,同樣的message：“login?failed”，error詳情就又不一樣了，error介紹：“user?not?found”?用戶找不到，所以具體的判斷error原因還是要以data下的error_description給出的原因去定位。

當然有些error也會出現一些其他的情況，并不返回message 參數，data也是空的，只給出了一個type類型，像這種情況其實就是在沒有登陸的情況下調用了SDK接口，那么這時首先要判斷的就是是否登錄了環信，或者已經登陸但是又斷開了與環信的連接。

截圖為未登錄調用了獲取群組詳情返回的error。

在已登錄的情況下查詢群組詳情，error詳情直接給出了找不到?group?ID為XXXXXX的群組，此時就可以以此判斷，或給出提示查找不到群ID為...的詳情

onPresence: function ( message ) {}, ? ? ? //處理“廣播”或“發布-訂閱”消息，如聯系人訂閱請求、處理群組、聊天室被踢解散等消息。

此監聽正如描述所講，處理“廣播”或“發布-訂閱消息”，至于發布-訂閱消息可以去了解一下設計模式，發布訂閱者模式，這里就不再進行解釋了，這里主要講的是該監聽如果在實際運用中的作用是什么。

我們先看下Uni-appDemo中的示例：

通過觀察我們看到了示例中運用到了switch?case?語句通過回調里message中不同的type類型從而對應執行不同的提示或其他邏輯操作。

在實際SDK集成過程中，例如：“申請添加好友、刪除好友，邀請入群，他人退群，新增群組管理員、他人加入聊天室，退出聊天室”等操作均會觸發此監聽的執行并回調出對應行為類型的type字段，根據type類型我們從而可以給出對應的UI層面的提示，或發布-訂閱事件，uni-appDemo中的disp.fire(‘XXXX’),正是發布-訂閱模式中的發布事件。

如果我們需要詳細的類型，則可以在文檔中的事件監聽找到：

n?好友狀態事件監聽：

現有的好友事件監聽，已新增對應的回調監聽：

群組事件監聽：

文檔地址：

群組 [IM 開發文檔]

聊天室事件監聽：

文檔地址：

http://docs-im.easemob.com/im/web/basics/chatroom#%E8%81%8A%E5%A4%A9%E5%AE%A4%E4%BA%8B%E4%BB%B6%E7%9B%91%E5%90%AC

以上變為常用的幾個監聽的介紹，具體的使用還是以咱們實際項目中的邏輯為準。

SDK，config配置，以及初始化，監聽都已配置完畢，下面我們就開始注冊、登陸環信ID，發出我們的第一條消息吧！

四、Hello World ! (從注冊登錄開始)

環信所有的功能性SDK接口調用都是要從注冊及登陸成功方可有效使用，如已注冊，登陸則是客戶端調用的第一個接口。

下面我將從注冊接口開始講起：

注冊，web端注冊接口如圖：

客戶端是否能夠直接調用注冊接口，需要先去環信IM管理后臺檢查該Appkey的注冊模式是否為開放注冊，授權模式的話，此接口調用注冊會直接出現下圖情況

Open registration doesn't allow, so register user need token

開放注冊不允許，所以注冊用戶需要token

注冊成功會觸發注冊接口中的success回調,并有注冊信息的返回如圖：返回字段包含創建時間，appname，orgname等信息。

注冊完成之后便可以開始調用登陸接口完成登錄操作。

下面我們來了解SDK提供的兩種登陸方式：

1.?用戶名密碼登陸（環信ID、密碼登陸），截圖為文檔——登陸接口：

user: String //環信ID

pwd：String //注冊時的密碼

appKey??//?appkey?初始化后appkey

2.?token登陸（使用token進行免密登陸）

該登陸方式可以進行免密登陸，常見用于刷新頁面之后的二次登陸。

比較常用到的場景，例如從login頁面跳轉到chat頁面，用戶在當前頁面刷新之后不再進行login頁面登陸直接正常進行聊天。（刷新頁面是會斷開與環信的連接，如不登陸則無法調用SDK接口）。

token獲取：token的獲取是在用戶名密碼登陸成功后的success回調中返回獲取。

access_token字段為token。

expires_in字段為token有效期，單位為秒，有效期內token可重復使用。

uni-app-demo中的用戶名密碼登陸的接口調用

Uni-app-demo中的token登陸：

有時我們會遇到success成功的返回了token，可是發送消息或者調用其他接口還是會出現報錯，或者提示未登錄的error，這時我們首要排查的情況還是檢查一下onOpened監聽是否成功觸發，與環信的連接建立還是要以onOpened監聽觸發為準！

監聽成功打印，意味著登陸成功！

這里順便給大家兩個檢驗是否登錄的方法。

1.?WebIM.conn方法下有一個logOut字段，該字段為true時表明未登錄狀態，該字段為false時表明登陸：

2.?WebIM.conn.isOpened ()?方法有三個狀態，undefined為未登錄狀態，true為已登錄狀態，false為未登錄狀態，可以根據這三個狀態去判斷是否登錄：

到這里登陸就說完了，至于為什么沒有講下去也是因為只要登錄成功，其他接口就可以按需調用，相信以各位小伙伴的能力接著往下進行也不是很困難了，當然也說不定有些奇葩問題搞不定，那么建議咱們可以去環信官網去尋求我們支持同事的幫助，將遇到的問題描述清楚，問題將在24H以內得到回復。

最后愿JavaScript之父布蘭登·艾克

保佑各位項目順利上線！

總結

以上是生活随笔為你收集整理的【快速上手教程】PC Web、Uni-App、小程序集成环信IM都在这里了的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。