iOS SDK 接入指南

项目配置

• pod 'gobelieve', :git => 'git@github.com:GoBelieveIO/im_ios.git'

IMSDK

• imsdk只包含消息基础通讯功能

配置服务地址

//app可以单独部署服务器，给予第三方应用更多的灵活性
[IMHttpAPI instance].apiURL = @"api.gobelieve.io"
[IMService instance].host = @"imnode.gobelieve.io"

初始化IM

启动im服务只需要设置用户的access token，调用启动接口并添加消息的监听对象。

[IMService instance].deviceID = [[[UIDevice currentDevice] identifierForVendor] UUIDString];

//监听网络状态变化
[[IMService instance] startRechabilityNotifier];

用户登录成功后启动IM，设置用户的accesstoken并启动im

[IMHttpAPI instance].accessToken = accessToken;
[IMService instance].accessToken = accessToken;
[IMService instance].uid = uid;
[[IMService instance] start];

绑定当前用户的devicetoken用于离线消息推送

[IMHttpAPI bindDeviceToken];

用户注销后清空用户的devicetoken并停止IM

[IMHttpAPI unbindDeviceToken];
[IMService instance].accessToken = @"";
[[IMService instance] stop];

应用切到后台暂停IM,此后所有的消息将通过推送通道下发

[[IMService instance] enterBackground];

应用切到前台恢复IM

[[IMService instance] enterForeground];

发送消息

• 启动IM服务设置好用户id之后便可以开始发送消息,消息发送的代码需要在UI线程中调用(消息内容大小限制为4k) :

    IMMessage *im = [[IMMessage alloc] init];
    //设置发送方id
    im.sender = sender;
    //设置接收方id
    im.receiver = receiver;
    //消息本地id
    im.msgLocalID = msgLocalID;
    im.content = @"消息内容";
    [[IMService instance] sendPeerMessage:im];
  

类IMService

设置当前用户的access token

属性名：String accessToken
功能：在调用start之前必须要设置用户的accessToken，token是由第三方应用服务器调用IM服务器RestAPI所得。

设置当前用户id

属性名:int64_t uid
功能：在调用start之前必须要设置用户的uid

设置当前设备id

属性名：String deviceID
功能：设备id可以用户多点登陆的唯一性判断,可选调用

监控网络变化

方法名: -(void) startRechabilityNotifier
功能: 可以及时的根据网络变化情况，断开，建立socket链接。

设置观察者

方法名: -(void) addConnectionObserver:(id<IMConnectionObserver>)observer
功能：设置observer，在observer中处理接受到的消息。
参数说明： 
    * observer 观察者
返回值：无返回值

设置点对点消息的接受者

方法名: -(void) addPeerMessageObserver:(id<PeerMessageObserver>)observer
功能：设置observer，在observer中处理接受到的消息。
参数说明： 
    * observer 观察者
返回值：无返回值

设置群组消息的接受者

方法名: -(void) addGroupMessageObserver:(id<GroupMessageObserver>)observer
功能：设置observer，在observer中处理接受到的消息。
参数说明： 
    * observer 观察者
返回值：无返回值

开始接受消息

方法名：-(void) start
功能：用户登陆成功后，连接im服务器来接受在线消息。

停止接受消息

方法名：-(void) stop
功能：用户注销后，断开和im服务器的连接，从而终止接受在线消息。

应用进入到前台

方法名：-(void) enterForeground
功能：应用进入前台，im服务器将停止将消息推送到通知栏

应用进入到后台

方法名：-(void) enterBackground
功能：应用进入后台，im服务器会将将消息推送到通知栏

发送消息

方法名: -(BOOL) sendPeerMessage:(IMMessage*)msg
功能：发送im消息，如果当前连接处于断开状态，消息会发送失败, 函数返回YES，也不能表明服务器已经接收到消息。
参数说明：
    *msg 消息对象
返回值:BOOL

发送群组消息

方法名: -(BOOL) sendGroupMessage:(IMMessage*)msg
功能：发送im消息，如果当前连接处于断开状态，消息会发送失败, 函数返回YES，也不能表明服务器已经接收到消息。
参数说明：
    *msg 消息对象
返回值:BOOL

接口IMConnectionObserver

连接状态

方法名:-(void) onConnectState:(int)state
功能:连接状态变更通知
参数说明:
    *state 连接的状态 STATE_UNCONNECTED, STATE_CONNECTING, STATE_CONNECTED, STATE_CONNECTFAIL
返回值:无返回值

异地登陆

方法名: -(void) onLoginPoint:(LoginPoint*)lp
功能:当前登陆用户在异地登陆
参数说明:
    *lp 登录点信息
返回值:无返回值

接口PeerMessageObserver

消息

方法名:-(void) onPeerMessage:(IMMessage*)msg
功能：接受到一条im消息
参数说明：
    *msg 消息对象
返回值:无返回值

消息ACK

方法名:-(void) onPeerMessageACK:(int)msgLocalID uid:(int64_t)uid
功能:服务器对收到消息的ack,此时这条消息才能标志为发送成功
参数说明:
    *msgLocalID 消息的本地ID
    *uid 消息接受者
返回值:无返回值

消息接受者ACK

方法名:-(void)onPeerMessageRemoteACK:(int)msgLocalID uid:(int64_t) uid
功能:消息已经被对端接收到。
参数说明:
    *msgLocalID 消息的本地ID
    *uid 消息接受者
返回值:无返回值

消息发送失败

方法名:-(void) onPeerMessageFailure:(int)msgLocalID uid:(int64_t)uid
功能：消息发出后，未收到服务器的ack，在和服务器的连接断开后，会通知消息发送失败。
参数说明:
    *msgLocalID 消息的本地ID
    *uid 消息接受者
返回值:无返回值

接口GroupMessageObserver

群组消息

方法名:-(void) onGroupMessage:(IMMessage*)msg
功能：接受到一条im消息
参数说明：
    *msg 消息对象
返回值:无返回值

群组消息ACK

方法名:-(void) onGroupMessageACK:(int)msgLocalID gid:(int64_t)gid
功能:服务器对收到消息的ack,此时这条消息才能标志为发送成功
参数说明:
    *msgLocalID 消息的本地ID
    *gid 群组ID
返回值:无返回值

群组消息发送失败

方法名:-(void) onGroupMessageFailure:(int)msgLocalID gid:(int64_t)gid
功能：消息发出后，未收到服务器的ack，在和服务器的连接断开后，会通知消息发送失败。
参数说明:
    *msgLocalID 消息的本地ID
    *gid 群组ID
返回值:无返回值

群组通知

方法名:-(void) onGroupNotification:(NSString*)notification
功能：群组创建，解散和群组成员变更的通知消息
参数说明:
    *notification 通知内容

返回值:无返回值

类IMApi

设置当前用户的device token

方法名:-(BOOL) bindDeviceToken:(NSString*)deviceToken success:(void (^)())success fail:(void (^)())fail
功能:设置device token后，im服务器会对用户推送离线消息
参数说明:
    *deviceToken APNS的deviceToken
返回值:boolean 是否设置成功。

清空当前用户关联的device token

方法名:-(BOOL) unbindDeviceToken:(NSString*)deviceToken success:(void (^)())success fail:(void (^)())fail
功能:im服务器不会再对这台设备推送离线消息
参数说明:
    *deviceToken APNS的deviceToken
    *accessToken 用户当前的accessToken
返回值:boolean 是否清空成功。

IMKit

• 除了imsdk必要的初始化动作外，使用imkit需要初始化存储类

    //setDBPath必须要在引用PeerMessageHandler，GroupMessageHandler之前调用
    //设置的路径名中可以包含用户id，这样就可以同时保存多个用户的聊天历史
    //否则用户注销后，必须要清空目录
    [MessageDB setDBPath:path];
    [IMService instance].peerMessageHandler = [PeerMessageHandler instance];
    [IMService instance].groupMessageHandler = [GroupMessageHandler instance];

打开聊天界面

MessageViewController* msgController = [[MessageViewController alloc] init];
msgController.peerUID = peerUID;
msgController.peerName = peerName;
msgController.currentUID = currentUID;
[self.navigationController pushViewController:msgController animated: YES];