便於記錄檢視地址，方便查詢 NIM SDK 使用指南

SDK 概述

網易雲信 SDK (NIM SDK) 為移動應用提供完善的 IM 開發框架，遮蔽其內部複雜細節，對外提供較為簡潔的 API 介面，方便第三方應用快速整合 IM 功能。SDK 相容 iOS 7.0+ ，Demo 相容 iOS 8.0+ 。

開發準備

NIM SDK 提供兩種整合方式：您既可以通過 CocoaPods 自動整合我們的 SDK，也可以通過手動下載 SDK, 然後新增到您的專案中。

我們提供兩個下載地址。分別為：

• 官網 SDK 下載入口。

• 我們提供了 GitHub 釋出倉庫 。NIMSDK，此倉庫包含 IM 和音視訊功能，您可以根據自己的需求選擇下載。

手動新增 SDK

• 根據自己工程需要，下載對應版本的 NIM SDK，得到 NIMSDK.framework 檔案 ( 如果選擇音視訊版本，還將得到 NIMAVChat.framework 檔案 ) ，以及未連線的全部三方依賴庫 ^注1 ，將他們匯入工程。

• 新增其他 NIM SDK 依賴庫

  • MobileCoreServices.framework
  • SystemConfiguration.framework
  • AVFoundation.framwork
  • CoreTelephony.framework
  • CoreMedia.framework
  • AudioToolbox.framework
  • VideoToolbox.framework
  • libc++.tbd ^注2
  • libsqlite3.0.tbd
  • libz.tbd

  注¹ ：開發者應根據自身專案，將不衝突的依賴庫也新增進工程。
  注² ：在 SDK 3.0.0 以前版本 (包括 3.0.0) ，c++ 庫請使用 libstdc++6.0.9.tbd , 之後的版本統一替換成 libc++.tbd 。

• 在 Build Settings -> Other Linker Flags 裡，新增選項 -ObjC。

• 在需要使用即時通訊 SDK 的地方 import <NIMSDK/NIMSDK.h> ，在需要使用實時音視訊 SDK 的地方 import <NIMAVChat/NIMAVChat.h>

   。

通過 CocoaPods 整合

在 Podfile 檔案中加入

  pod 'NIMSDK'

安裝

  pod install

如果無法安裝 SDK 最新版本，執行以下命令更新本地的 CocoaPods 倉庫列表

  pod repo update

SDK 類說明

NIM SDK 主要提供瞭如下類(協議)與方法

• NIMSDK 整個SDK的主入口，單例，主要提供初始化，註冊，內部管理類管理的功能
• NIMLoginManager 登入管理類，負責登入，登出和相應的回撥收發
• NIMChatManager 聊天管理類，負責訊息的收發
• NIMConversationManager 會話管理類，負責訊息，最近會話的管理
• NIMTeamManager 群組管理類，負責群組各種操作
• NIMMediaManager 媒體管理類，負責多媒體相關的介面，比如錄音
• NIMSystemNotificationManager 系統通知管理類，負責系統訊息的接收和儲存
• NIMApnsManager 推送管理類，負責推送的設定和接收
• NIMResourceManager 資源管理類，負責檔案的上傳和下載
• NIMUserManager 好友管理類，負責對好友的增刪查，以及對其會話的訊息設定
• NIMChatroomManager 聊天室管理類，負責聊天室狀態管理和資料拉取及設定
• NIMDocTranscodingManager 文件轉碼管理類，負責文件轉碼的查詢和刪除等

NIMAVChat 主要提供瞭如下類(協議)與方法

• NIMAVChat 是 NIMSDK 的音視訊和實時會話擴充套件，封裝了網路通話、實時會話和網路探測等的管理
• NIMNetCallManager 音視訊網路通話管理類，提供音視訊網路通話功能
• NIMRTSManager 實時會話管理類，提供資料通道 (TCP/語音通道) 來滿足實時會話的需求
• NIMRTSConferenceManager 多人實時會話管理類，提供多人資料通道 (TCP) 來滿足多人實時會話的需求
• NIMAVChatNetDetectManager 音視訊網路探測管理類，提供音視訊網路狀態診斷功能

配置 HTTPS 支援

在預設情況下，SDK 認為使用者資料頭像，群頭像，聊天室類使用者頭像等資訊都是預設託管在雲信上，所以 SDK 會針對他們自動開啟 HTTPS 支援，開發者不需要任何額外配置。

但如果開發者需要將這些資訊都託管在自己的伺服器上，需要在 NIMSDKConfig.h 中，將

@property (nonatomic,assign)    BOOL    enabledHttpsForInfo
@property (nonatomic,assign)    BOOL    enabledHttpsForMessage;

設定為 NO，避免 SDK 自動將開發者設定的 HTTP URL 自動轉換為 HTTPS URL。

因為蘋果的 ATS 政策，如果應用中使用了 HTTP 請求，需要將工程配置檔案中的 info.plist 檔案，NSAppTransportSecurity 條目中適配好 NSExceptionDomains。需要注意的是，2017 年以後，應用中存在 HTTP 請求會有稽核被拒的風險。

初始化 SDK

• 在需要使用 SDK 的地方匯入標頭檔案 <NIMSDK/NIMSDK.h> 。

• 新增 SDK 初始化方法。

  -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
          NIMSDKOption *option    = [NIMSDKOption optionWithAppKey:appKey];
          option.apnsCername      = // APNS 推送證書名
         option.pkCername        = //Pushkit 證書名
        [[NIMSDK sharedSDK] registerWithOption:option];
        return YES;
    }

推薦在 APP 啟動時儘快註冊 NIM SDK。

登入與登出

在使用 SDK 之前，需要對雲信的體系流程有基本的認知，推薦開發者首先閱讀這裡 。

手動登入

呼叫

[[[NIMSDK sharedSDK] loginManager] login:account
                                   token:token
                              completion:^(NSError *error) {}];

error為登入錯誤資訊，成功則為nil。不要在登入完成的回撥中直接獲取 SDK 快取資料，而應該在 同步完成的回撥裡獲取資料 或者 監聽相應的資料變動回撥後獲取 。

注：在不特殊說明的情況下，SDK 的所有回撥都是在主執行緒中發起，無論是以 block 還是 delegate 的形式，也推薦開發者僅在主執行緒呼叫 SDK 相關介面。

獲取登入帳號的雲信 id:

NSString *userID = [NIMSDK sharedSDK].loginManager.currentAccount;

SDK 不支援直接新增網易雲通訊使用者，請參考服務端API文件 的 建立網易雲通訊 ID 章節，在您的應用伺服器上使用 Http 介面進行新增。

自動登入

NIM SDK 有兩種自動登入的場景：

1.SDK 發起的自動登入：登入完畢後因網路發生切換，斷網等情況發生而需要重連，SDK 將自動進行重連重登，無需 APP 干預。

2.APP 發起的自動登入：APP 啟動時，如果已儲存使用者名稱和密碼可以選擇呼叫自動登入介面，並立刻開啟主介面。此時 APP 可以在無網路，未登入成功的狀態下直接訪問使用者本地資料。

//APP主動發起自動登入
- (void)autoLogin:(NIMAutoLoginData *)loginData

NIMAutoLoginData 中的 forcedMode 為強制模式開關。非強制模式下的自動登入，伺服器將檢查當前登入裝置是否為上一次登入裝置，如果不是，伺服器將拒絕這次自動登入(返回 error code 為 417 的錯誤)；強制模式下的自動登入，伺服器將不檢查當前登入裝置是否為上一次登入裝置，安全性較低，但較為便捷。

和手動登入不同，自動登入通過委託通知登入狀態。 APP 需要實現如下回調 (手動登入也會收到同樣的委託回撥)

- (void)onLogin:(NIMLoginStep)step

自動登入過程不需要 APP 加以干預，SDK 會在有網路的情況下有策略地不斷重試直到登入為止。但下面兩種異常情況需要 APP 處理：被踢和特殊的登入錯誤。

• 被踢的回撥

-(void)onKick:(NIMKickReason)code 
   clientType:(NIMLoginClientType)clientType

APP收到被踢回調後需要進行登出並切換到登入介面。

• 自動登入失敗的回撥

- (void)onAutoLoginFailed:(NSError *)error

大部分自動登入回撥錯誤 APP 並不需要關心，只需注意如下幾種情況：

1.使用者名稱密碼錯誤導致自動登入失敗，error code 為 302。這種情況一般發生於使用者在其他裝置上修改了密碼。

2.已有一端登入導致自動登入失敗，error code 為 417。這種情況發生於非強制登入模式下已有一端線上而當前裝置進行自動登入(設定為只允許一端同時登入時)，出於安全方面的考慮，雲信伺服器判定當前端需要重新手動輸入使用者密碼進行登入，故拒絕登入。

3.NIMSDKConfig 設定了 maxAutoLoginRetryTimes 屬性，即 App 設定當前 SDK 自動登入失敗的重試次數，那麼在當前會話中如果登入出錯超過預定次數，將丟擲 code 為 NIMLocalErrorCodeAutoLoginRetryLimit 的本地錯誤

一旦發生如上情況，APP 同樣需要進行額外處理：登出或重試。

登出

呼叫

[[[NIMSDK sharedSDK] loginManager] logout:^(NSError *error){}];

應用層登出/登出自己的賬號時需要呼叫 SDK 的登出操作，該操作會通知雲信伺服器進行 APNS 推送資訊的解綁操作，避免使用者已登出但推送依然傳送到當前裝置的情況發生。

考慮到使用者體驗，登出的超時時間會比其他請求短一些。上層應用不管登出請求是否成功，UI 表現上都應該做出登出行為。

多端登入

當用戶在某個客戶端登入時，其他沒有被踢掉的端會觸發回撥:

- (void)onMultiLoginClientsChanged;

同時，可以查詢當前時間登入的裝置列表:

- (NSArray<NIMLoginClient *> *)currentLoginClients;

雲信內建踢人策略為：移動端(Android,iOS)互踢，桌面端(PC,Web)互踢，移動端和桌面端共存。

如果當前的互踢策略無法滿足業務需求的話，可以聯絡我們取消內建互踢，根據多端登入的回撥和當前的裝置列表，判斷本裝置是否需要被踢出。如果需要踢出，直接呼叫登出介面並在介面上給出相關提示即可。

登入與使用者資訊同步

NIM SDK 的登入一共有大約十個步驟，包括正在連線，連線成功，正在登入等。詳見 NIMLoginStep 列舉。其中重要的兩個步驟為：登入成功 (NIMLoginStepLoginOK) 和 同步成功 (NIMLoginStepSyncOK)。

• 登入成功 SDK 已成功登入，獲取到基本資訊，並開始同步資料
• 同步成功 SDK 已同步完成所有 IM 資訊

NIM SDK 在登入後會同步群資訊，離線訊息，漫遊訊息，系統通知等資料。

基礎訊息功能

訊息功能概述

SDK 中使用者與同一個物件的聊天資訊集合，稱為一個會話，用 NIMSession 來表示。會話有單人會話，群組會話，聊天室會話等型別。

SDK 中用於表示訊息的結構為 NIMMessage，目前提供如下幾種訊息型別，不同的訊息型別對應不同的 MessageObject

訊息格式	MessageObject
文字訊息	nil
圖片訊息	NIMImageObject
音訊訊息	NIMAudioObject
視訊訊息	NIMVideoObject
檔案訊息	NIMFileObject
地理位置訊息	NIMLocationObject
通知訊息	NIMNotificationObject
提醒訊息	NIMTipObject
自定義訊息	NIMCustomObject

訊息 NIMMessage 定義了一些額外的狀態屬性，推薦只在主執行緒對這些屬性進行讀寫：

• 訊息的接收狀態 isReceivedMsg

  由於漫遊訊息的存在，所以自己發出的訊息漫遊下來後仍舊是 收到的訊息 ，這個欄位用於訊息出錯時，判斷需要重發還是重收。

• 訊息的排版狀態 isOutgoingMsg

  用於鑑別是否為發出去的訊息。使用者可以選擇和自己發起對話，所以並不是所有來源是自己的訊息都是往外發的訊息，這個欄位主要用於判斷頭像排版位置，往外發的訊息氣泡放右邊，其他訊息氣泡放左邊。

• 訊息的投遞狀態 deliveryState

  此狀態僅對傳送的訊息有效。訊息的投遞狀態有 傳送中 ， 傳送失敗 ， 傳送成功 三種。

• 訊息附件的下載狀態 attachmentDownloadState

  此狀態僅對收到的且帶有附件的訊息有效。 下載狀態有 下載失敗 ， 下載中 ， 下載成功 三種。

• 訊息的刪除狀態 isDeleted

  訊息是否標記為已刪除,已刪除的訊息在獲取本地訊息列表時會被過濾掉，只有根據messageId獲取訊息的介面可能會返回已刪除訊息。

• 訊息的播放狀態 isPlayed

  用於鑑別音訊類的訊息是否播放過。 上層應用可以根據業務修改這個屬性。注意不要頻繁修改這個屬性值，每次對這個屬性做出修改，就會自動更新一次資料庫。

• 訊息伺服器擴充套件欄位 remoteExt

  此欄位會發送到其他端,上層需要保證 NSDictionary 可以轉換為 JSON。

• 訊息本地擴充套件欄位 localExt

  此欄位只在本地儲存，不會發送至對端,上層需要保證 NSDictionary 可以轉換為 JSON。

• 訊息傳送方的顯示名 senderName

  伺服器內建的訊息傳送者名字，當傳送者是自己時,這個值為空。在本地沒法獲取到相應傳送者資訊時推薦時使用這個值。

• 對端已讀 isRemoteRead

  接收對端已讀回執後，所有小於已讀回執時間戳的訊息都會被置為 對端已讀 。

傳送訊息

1.構造併發送訊息