基於融雲的IM

融雲IM

前言

沒什麼好說，先從官方把知識點摘抄一遍，慢慢理解…

正文

基礎概念

業務篇

單聊
指兩個用戶一對一進行聊天，兩個用戶間可以是好友也可以是陌生人，融雲不對用戶的關係進行維護管理，會話關係由融雲負責建立並保持，當 App 在後臺運行或者 App 進程被殺死後，有新消息時會收到推送通知。

羣組聊天
羣組指兩個以上用戶一起進行聊天，羣組成員信息由 App 提供並進行維繫，融雲只負責將消息傳達給羣組中的所有用戶， App 在後臺運行或者 App 進程被殺死後可以收到推送通知。同一個用戶最多可支持加入 500 個羣，每個羣最大人數上限爲 3000 人，App 內的羣組數量沒有限制。

討論組
討論組指兩個以上用戶一起進行聊天，用戶可以自行添加好友生成一個討論組聊天， App 在後臺運行或者 App 進程被殺死後可以收到推送通知，與羣組不同的是，討論組會話關係由融雲負責建立並保持，同一個用戶最多可加入 500 個討論組，討論組中成員上限不超過 500 人。

聊天室
聊天室成員不設用戶上限，海量消息併發即時到達，用戶退出聊天界面後即視爲離開聊天室，不會再接收到任何聊天室中消息，沒有推送通知功能。會話關係由融雲負責建立並保持連接，通過 SDK 相關接口，可以讓用戶加入或者退出聊天室。

客服消息
用戶與您的 App 後臺客服進行消息通訊，支持文字、圖片、位置、語音、表情、圖文等消息類型，支持單客服和多客服服務，提供“機器人”和“人工”配合使用，可設置“機器人”或者“人工”優先接待功能。

音視頻通話
指通過 IP 網絡，使兩個用戶建立一對一、一對多的音視頻通話。融雲音視頻 SDK 包括兩部分：CallKit 和 CallLib 。

應用公衆服務
爲 App 開發者提供 App 內建公衆服務能力，通過在融雲開發者站點創建 App 公衆號，幫助 App 快速覆蓋用戶需求。

公衆服務
是在應用開發者和公衆帳號運營者之間建立的對接平臺，應用開發者可以通過平臺引入公衆服務資源，幫助 App 快速覆蓋用戶需求。

會話列表
指各種會話依照順序先後排列的界面，其中會話列表中的每一個列表項稱之爲一條會話。排列的先後順序會依賴於置頂、最新會話、未讀會話和時間等因素，聊天室類型的會話不會進入到會話列表中。

聊天界面
指聊天的具體界面，顯示聊天的標題、成員頭像、聊天內容、輸入框等。

通知
通知（Notification）是一種用戶界面展現概念，是指在設備端以某種形式彈出一條提示。

通知分爲本地通知（Local Notification）和遠程通知（Remote Notification）。儘管您看到的是一樣的界面展現，但是他們分別來自本地發起和遠程發起。

本地通知指的是您的應用程序在前臺、或者在後臺但仍然在生命週期存活，此時收到消息，會直接通過前臺的應用程序彈出提示窗口。

遠程通知指的是您的應用程序已經完全退出，應用進程已經不存在，此時通過 iOS 上的 APNS 系統服務或者 Android 上的服務進程收到消息，並彈出提示欄。大家開發和調試過程中，務必要清楚本地通知和遠程通知的區別。

推送
推送（Push）是一種技術概念，是指從服務端實時發送信息到客戶端。

大家概念中的典型推送服務是類似 APNS（Apple Push Notification Service）、GCM（Google Cloud Messaging） 等服務。在國內，由於谷歌服務不能使用，因此您的應用必須使用第三方或者自己研發的服務來推送。

因爲融雲是使用長連接技術來實現 IM 服務的，和典型的 Push 服務具有相同的長連接機制，所以，很多開發者也會直接使用融雲來實現推送功能。

在某些場合，iOS 平臺的推送（通過 APNS 的 Push）和遠程通知（Remote Notification）表示相同的意思，可以互相替換使用。

廣播
廣播（Broadcast）是一種業務概念，是通過後臺管理界面或者調用服務端接口，向 App 中的所有用戶發送一條消息。通常“廣播”和“推送”是開發者容易產生混淆的地方。

系統消息
系統消息（System Message）是一種業務概念，是指利用系統帳號（非用戶帳號，用戶不可登錄）向用戶發送的消息，既可以是通過調用廣播接口發送給所有人的消息，也可以是加好友等單條通知消息。

在融雲平臺中，其實並不存在系統消息的概念，一般系統消息特指會話類型（ConversationType）爲“系統（SYSTEM）”的會話中的消息。

開發篇

App Key / Secret
App Key / Secret 相當於您的 App 在融雲的帳號和密碼。是融雲 SDK 連接服務器所必需的標識，每一個 App 對應一套 App Key / Secret。

融雲提供了兩套環境，開發環境和生產環境，前者是方便您集成開發和測試的，後者是 App 上線之後真正運營的商業環境。兩者間數據隔離，避免開發環境數據和線上生產環境數據互相沖突。針對開發者的生產環境和開發環境，我們提供兩套 App Key / Secret ，在正式上線前，請務必切換到生產環境。

Token
Token 即用戶令牌，相當於您 APP 上當前用戶連接融雲的身份憑證。每個用戶連接服務器都需要一個 Token，用戶更換即需要更換 Token。每次初始化連接服務器時，都需要向服務器提交 Token。

IM基礎服務開發指南（Web SDK開發指南）

1.引入SDK

獲取官方 Web SDK (目前版本爲 2.2.5 ) 地址加入到自己頁面中 如下:
<script src="http(s)://cdn.ronghub.com/RongIMLib-2.2.5.min.js"></script>

融雲 Web SDK 從 0.9.9 版本起將開始支持 seaJs 和 requireJs 等模塊加載器。

使用 requireJs 進行模塊加載:

require.config({
    paths: {
     protobuf: 'http(s)://cdn.ronghub.com/protobuf-2.1.5.min',
     RongIMLib: 'http(s)://cdn.ronghub.com/RongIMLib-2.2.5.min'
    }
});

require(['protobuf','RongIMLib'], function(protobuf,RongIMLib) {
     //初始化
     RongIMLib.RongIMClient.init();
     //dosomething...
});

使用 seaJs 進行模塊加載

seajs.config({
 alias: {
   "RongIMLib":'http(s)://cdn.ronghub.com/RongIMLib-2.2.5.min.js'
  }
});

seajs.use("RongIMLib",function(){
   //dosomething...
});

2.編寫代碼

初始化SDK
請使用您前面從融雲開發者平臺註冊得到的 App Key，傳入 init 方法，初始化 SDK 。在整個應用程序全局，只需要調用一次 init 方法。

// 初始化
// RongIMClient.init(appkey, [dataAccessProvider],[options]);
// appKey: 官網註冊的appkey
// dataAccessProvider:自定義本地存儲方案的實例，不傳默認爲內存存儲，自定義需要實現WebSQLDataProvider所有的方法，此參數必須是傳入實例後的對象
RongIMClient.init("e7x8xycsx6flq");

設置監聽器
必須設置監聽器後，再連接融雲服務器，代碼示例如下：

// 設置連接監聽狀態（status標識當前連接狀態）
// 連接狀態監聽器
RongIMClient.setConnectionStatusListener({
    onChanged: function(status) {
        switch (status) {
            case RongIMLib.ConnectionStatus.CONNECTED:
                console.log("鏈接成功");
                break;
            case RongIMLib.ConnectionStatus.CONNECTING:
                console.log("正在鏈接");
                break;
            case RongIMLib.ConnectionStatus.DISCONNECTED:
                console.log("斷開鏈接");
                break;
            case RongIMLib.ConnectionStatus.KICKED_OFFLINE_BY_OTHER_CLIENT:
                console.log("其他設備登錄");
                break;
            case RongIMLib.ConnectionStatus.NETWORK_UNAVAILABLE:
                console.log("網絡不可用");
                break;
        }
    }
})

// 消息監聽器
 RongIMClient.setOnReceiveMessageListener({
    // 接收到的消息
    onReceived: function (message) {
        // 判斷消息類型
        switch(message.messageType){
            case RongIMClient.MessageType.TextMessage:
                   // 發送的消息內容將會被打印
                console.log(message.content.content);
                break;
            case RongIMClient.MessageType.VoiceMessage:
                // 對聲音進行預加載                
                // message.content.content 格式爲 AMR 格式的 base64 碼
                RongIMLib.RongIMVoice.preLoaded(message.content.content);
                break;
            case RongIMClient.MessageType.ImageMessage:
                // do something...
                break;
            case RongIMClient.MessageType.DiscussionNotificationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.LocationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.RichContentMessage:
                // do something...
                break;
            case RongIMClient.MessageType.DiscussionNotificationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.InformationNotificationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.ContactNotificationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.ProfileNotificationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.CommandNotificationMessage:
                // do something...
                break;
            case RongIMClient.MessageType.CommandMessage:
                // do something...
                break;
            case RongIMClient.MessageType.UnknownMessage:
                // do something...
                break;
            default:
                // 自定義消息
                // do something...
        }
    }
});

獲取Token
Token也叫用戶令牌，是SDK端用來連接融雲服務器的憑證，每個用戶鏈接服務器都需要一個Token。每次初始化連接服務器時，都需要向服務器提交Token。

要想獲取用戶Token，流程如下：首先需要您的App查詢您的應用程序服務器，然後您的應用程序服務器再訪問融雲服務器獲取，最後返回給App，App用返回的Token連接服務器登錄。

連接服務器
將您在上一節請求身份認證服務器時獲取的Token傳入connect方法，開始連接服務器。在整個應用程序全局，只需要調用一次connect方法，SDK會負責自動重連。

您可以用在上一節介紹的API調試工具生成一個Token，這裏我們假設您生成Token時使用的參數如下：
用戶Id： userId=“1”
用戶在融雲系統中唯一的身份Id，可爲任意數字或字符串，但必須保證全局唯一。
用戶名稱： name=“韓梅梅”
用戶的顯示名稱，用來在Push推送時，或者客戶端沒有提供用戶信息時，顯示用戶的名稱。
用戶頭像地址： portraitUri=”http://rongcloud-web.qiniudn.com/docs_demo_rongcloud_logo.png”
這裏爲了測試，您可以隨意提供一個地址，如果此圖片不存在，會顯示默認的投降。
假設返回的Token是

mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==

代碼示例

// 初始化
RongIMClient.init("e7x8xycsx6flq");
var token = "mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==";

// 連接融雲服務器。
      RongIMClient.connect(token, {
        onSuccess: function(userId) {
          console.log("Login successfully." + userId);
        },
        onTokenIncorrect: function() {
          console.log('token無效');
        },
        onError:function(errorCode){
              var info = '';
              switch (errorCode) {
                case RongIMLib.ErrorCode.TIMEOUT:
                  info = '超時';
                  break;
                case RongIMLib.ErrorCode.UNKNOWN_ERROR:
                  info = '未知錯誤';
                  break;
                case RongIMLib.ErrorCode.UNACCEPTABLE_PaROTOCOL_VERSION:
                  info = '不可接受的協議版本';
                  break;
                case RongIMLib.ErrorCode.IDENTIFIER_REJECTED:
                  info = 'appkey不正確';
                  break;
                case RongIMLib.ErrorCode.SERVER_UNAVAILABLE:
                  info = '服務器不可用';
                  break;
              }
              console.log(errorCode);
            }
      });

發送消息
發送單聊、羣組及聊天室消息，發送消息必須在執行初始化SDK方法及連接融雲服務器connect成功之後進行。

 // 定義消息類型,文字消息使用 RongIMLib.TextMessage
 var msg = new RongIMLib.TextMessage({content:"hello",extra:"附加信息"});
 //或者使用RongIMLib.TextMessage.obtain 方法.具體使用請參見文檔
 //var msg = RongIMLib.TextMessage.obtain("hello");
 var conversationtype = RongIMLib.ConversationType.PRIVATE; // 私聊
 var targetId = "xxx"; // 目標 Id
 RongIMClient.getInstance().sendMessage(conversationtype, targetId, msg, {
                // 發送消息成功
                onSuccess: function (message) {
                    //message 爲發送的消息對象並且包含服務器返回的消息唯一Id和發送消息時間戳
                    console.log("Send successfully");
                },
                onError: function (errorCode,message) {
                    var info = '';
                    switch (errorCode) {
                        case RongIMLib.ErrorCode.TIMEOUT:
                            info = '超時';
                            break;
                        case RongIMLib.ErrorCode.UNKNOWN_ERROR:
                            info = '未知錯誤';
                            break;
                        case RongIMLib.ErrorCode.REJECTED_BY_BLACKLIST:
                            info = '在黑名單中，無法向對方發送消息';
                            break;
                        case RongIMLib.ErrorCode.NOT_IN_DISCUSSION:
                            info = '不在討論組中';
                            break;
                        case RongIMLib.ErrorCode.NOT_IN_GROUP:
                            info = '不在羣組中';
                            break;
                        case RongIMLib.ErrorCode.NOT_IN_CHATROOM:
                            info = '不在聊天室中';
                            break;
                        default :
                            info = x;
                            break;
                    }
                    console.log('發送失敗:' + info);
                }
            }
        );

同步會話列表
在瀏覽器中使用融雲Web SDK與在移動端中使用 融雲IOS、Android SDK不同的是瀏覽器一刷新頁面，之前已經存在在內存中存好的會話列表都將會清空。

Web SDK提供getConversationList來獲取會話列表，如果本地不存在會話記錄，SDK會自動向服務器拉去，此方法必須在執行初始化SDK方法init及連接融雲服務器connect成功之後進行。

// getConversationList示例

RongIMClient.getInstance().getConversationList({
    onSuccess: function(list) {
        console.log(list);
    };
    onError: function(error) {
        // do something
    }
}, null)

獲取歷史消息
通過getHistoryMessages來幫助開發者獲取歷史消息記錄。此方法必須在執行初始化SDK方法及連接融雲服務器connect成功之後記性，使用此方法前提是APP必須開啓單羣聊消息雲存儲，如APP沒有開啓則執行onError方法。

單羣聊消息雲存儲不支持聊天室消息雲存儲，拉去歷史消息最多一次性拉去20條消息。拉取順序按時間倒序拉取，如果本地不存在歷史消息，SDK會自動向服務器拉取。

拉取歷史消息爲循環拉取，舉例:
條件：歷史記錄爲 45 條，每次拉取 20 條。
第一次拉取 list 長度爲 20，hasMsg 爲 true。
第二次拉取 list 長度爲 20，hasMsg 爲 true。
第三次拉取 list 長度爲 5，hasMsg 爲 false。
第四次拉取 list 長度爲 0，hasMsg 爲 false。
第四次拉取：重複第一次拉取，以此循環

//getHistoryMessages
 RongIMClient.getInstance().getHistoryMessages(RongIMLib.ConversationType.PRIVATE, 'targetId', null, 20, {
          onSuccess: function(list, hasMsg) {
            // hasMsg爲boolean值，如果爲true則表示還有剩餘歷史消息可拉取，爲false的話表示沒有剩餘歷史消息可供拉取。
               // list 爲拉取到的歷史消息列表
          },
          onError: function(error) {
              // APP未開啓消息漫遊或處理異常
                   // throw new ERROR ......
          }
        });

自定義消息（未做太多標記）
1.自定義消息支持方式
2.自定消息類型參數說明
3.自定消息注意事項

檢測未讀消息
此接口用來查詢當前傳入Token是否有未讀消息，此方法必須在執行初始化SDK方法init及連接融雲服務器connect成功之後進行。

// 此接口必須在init()方法之後調用。
RongIMClient.getInstance().hasRemoteUnreadMessages('mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==',{
    onSuccess:function(hasMessage){
        if(hasMessage){
            // 有未讀的消息
        }else{
            // 沒有未讀的消息
        }
    },onError:function(err){
        // 錯誤處理...
    }
});

參考文獻

1. 融雲官網
   http://www.rongcloud.cn/docs/quick_start.html