前置准备

• 在这个集成教程中，我们使用已创建的Demo应用，向您展示如何快速地集成OpenIMKit(iOS)。

• 一般地，您需要入驻开发者并且创建应用后，才能集成云旺（OpenIM）并且发布您的App。

注意： 您完全可以先跳过前置准备，使用我们预先申请的Demo应用，来完成快速集成。

注意： 但是在您正式发布应用之前，您务必将一些内容替换为您所申请应用的特定内容。对于这些需要替换的内容，会在教程中以注意点的形式标识出。

• 联系我们

  咨询	链接
  开发者论坛

Step1 下载SDK包

• 如果您已经获得Demo包，则可以跳过这一步

• 打开Demo下载页面

• 下载iOS Demo并解压缩。

Step2 添加OpenIM SDK Framework

• 将云旺（OpenIM） Demo中的WXFrameworks目录直接拖入你的Xcode工程中

• 在弹出的对话框中勾选Copy items if needed后，点击Finish。

  注意：如果没有添加WXOpenIMSDKResource.bundle，会引起异常Crash。

  注意：如果没有添加WXOUIModuleResources.bundle，您可能在打开IM页面时界面元素为空白。

  注意：目录中包含的身份图片yw_1222.jpg不能被重命名

  注意：在你正式发布应用之前，您务必需要使用自己申请的身份图片，并测试IM功能是否正常。现在，您可以暂时跳过这一步，以便快速的完成集成工作。您可以从以下链接中了解如何申请您自己的身份图片。

• 参见：应用创建和管理

• 参见：您的专属身份图片

Step3 添加系统库

云旺（OpenIM）依赖于这些系统库，您需要将他们添加到工程中：

• UIKit.framework
• AddressBook.framework
• SystemConfiguration.framework
• CoreLocation.framework
• CoreTelephony.framework
• CoreData.framework
• libz.tbd
• libstdc++.6.0.9.tbd
• libsqlite3.0.tbd
• libresolv.tbd
• MobileCoreServices.framework
• ImageIO.framework
• AudioToolbox.framework
• AVFoundation.framework
• AssetsLibrary.framework
• CoreMotion.framework

注意：在xcode7之前的版本，没有.tbd的库，而是.dylib

不知道如何添加系统库？请参考：如何添加系统库图例

Step4 修改编译选项

• 云旺（OpenIM） SDK内部使用了ObjectiveC的Category，所以开发者需要在Target->Linking->Other Linker Flags中添加-ObjC选项，以保证这些Category能够正常工作。

  不知道如何修改编译选项？请参考：如何修改编译选项

  注意：请注意-ObjC的大小写。

  注意：如果您没有添加-ObjC编译选项，在初始化WXOSdk时会发生crash。

• 完成以上5步后，您的链接库和资源拷贝应该类似于：

  

Step5 拖入胶水代码，最快捷的集成方式

• 胶水代码

  顾名思义就是将您的App和IMSDK粘合起来的中间代码。其中包含对IMSDK主流程接口的调用代码，例如初始化、登录准备、登录、注销、打开会话列表、打开聊天页面等。

  注意：Demo提供了基础的胶水代码，你可以将其拖动到工程中。并且在didFinishLaunchingWithOptions:、你App的用户登录成功、你App的用户注销这几个函数中调用几个基础入口胶水函数，可完成初步的集成。

  • 基础入口胶水函数:我们把在相同时刻调用的多个胶水函数汇聚到了几个入口胶水函数中，如下:
    • callThisInDidFinishLaunching
    • callThisAfterISVAccountLoginSuccessWithYWLoginId
    • callThisBeforeISVAccountLogout

  注意：进一步地，胶水代码(SPKitExample.m)中包含了特地设置的#warning，请仔细阅读这些warning的注释，根据实际情况调整代码，以符合你的需求。

• 拖动到工程

  在WXOpenIMSampleRelease/WXOpenIMSampleDev/目录找到MainLogic和Customize这两个子目录，拖动到工程中，在弹出的对话框中勾选Copy items if needed后，点击Finish

• 注意：

  胶水代码并不属于IMSDK的一部分，而只是对IMSDK接口调用的进一步集中整合，你当然也可以不通过胶水代码的方式集成IMSDK，参考Demo工程胶水代码对IMSDK的使用方式，自己编写胶水代码。

Step6 初始化IMSDK

• 引入胶水代码头文件SPKitExample.h，调用基础入口胶水函数：callThisInDidFinishLaunching

  一般在-[AppDelegate didFinishLaunchingWithOptions:]函数中初始化IMSDK

  #import "SPKitExample.h"
  @implementation AppDelegate
  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Override point for customization after application launch.
      [[SPKitExample sharedInstance] callThisInDidFinishLaunching];
  
      return YES;
  }

• 基础入口胶水函数：callThisInDidFinishLaunching，其中包含：

  步骤	函数
  初始化	exampleInit
  设置APNSPush处理回调	exampleHandleAPNSPush
  设置全局导航栏颜色	exampleCustomGlobleNavigationBar

  注意： exampleInit中23015524是Demo中使用的示例AppKey。您需要在申请App成功后，替换为您的AppKey。在快速集成时，你可以先跳过申请App这个步骤。
  * 更多参考：查看AppKey

Step7 登录IMSDK

• 一般在用户登录您App的账号成功后，调用基础入口胶水函数：callThisAfterISVAccountLoginSuccessWithYWLoginId，登录IMSDK

  //应用登陆成功后，调用SDK
  [[SPKitExample sharedInstance] callThisAfterISVAccountLoginSuccessWithYWLoginId:self.textFieldUserID.text
                                                                         passWord:self.textFieldPassword.text
                                                                    preloginedBlock:^{
      /// 可以显示会话列表页面
  } successBlock:^{
      //  到这里已经完成SDK接入并登录成功，你可以通过exampleMakeConversationListControllerWithSelectItemBlock获得会话列表
      /// 可以显示会话列表页面        
  } failedBlock:^(NSError *aError) {        
      if (aError.code == YWLoginErrorCodePasswordError || aError.code == YWLoginErrorCodePasswordInvalid || aError.code == YWLoginErrorCodeUserNotExsit) {
      /// 可以显示错误提示
      }
  }];

• 基础入口胶水函数：callThisAfterISVAccountLoginSuccessWithYWLoginId，其中包含：

  步骤	函数
  监听连接状态	exampleListenConnectionStatus
  设置头像风格	exampleSetAvatarStyle
  提供Profile信息	exampleSetProfile
  设置最大气泡宽度	exampleSetMaxBubbleWidth
  监听新消息	exampleListenNewMessage
  监听头像点击事件	exampleListenOnClickAvatar
  监听链接点击事件	exampleListenOnClickUrl
  监听预览大图事件	exampleListenOnPreviewImage
  自定义皮肤	exampleCustomUISkin
  预登陆	examplePreLoginWithLoginId:successBlock:
  真正登录	exampleLoginWithUserID:password:successBlock:failedBlock:

注意： 您可以使用“visitor1” - “visitor1000”，密码为“taobao1234”，登录我们的Demo进行体验

注意： 一般地，你需要根据App中当前登录的用户，登录到给该用户对应的云旺（OpenIM）帐号。您可能会关注如何集成云旺（OpenIM）帐号，但是在快速集成中可以先跳过这一步。

注意： 目前要求callThisAfterISVAccountLoginSuccessWithYWLoginId以及登录操作，必须在主线程调用（底层CoreData的NSFetchedResultsController需要在主线程创建才能在主线程回调），否则一些回调比如未读数变更的回调，将会无效。

• 更多参考：如何集成云旺（OpenIM）账号

• 基础入口胶水函数：callThisBeforeISVAccountLogout，在用户退出你App的账号前，请务必调用此入口函数退出IMSDK的登录

Step8 打开会话列表和聊天页面

• 打开会话列表

  使用如下的函数创建会话列表页面

  注意：下面的代码只是展示了如何调用API创建会话列表页面，你需要在你的代码中调用上面的代码，取得返回的Controller对象，然后使用Push、Present或者添加到UITabBarController等方式，将其展示出来。

  /**
   *  创建会话列表页面
   */
  - (YWConversationListViewController *)exampleMakeConversationListControllerWithSelectItemBlock:(YWConversationsListDidSelectItemBlock)aSelectItemBlock
  {
      YWConversationListViewController *result = [self.appDelegate.ywIMKit makeConversationListViewController];
  
      [result setDidSelectItemBlock:aSelectItemBlock];
  
      return result;
  }

• 打开某个会话

  使用如下的函数打开某个会话

  注意：下面的代码展示了如何使用API构建聊天页面，并且使用UINavigationController将其展示出来。你可以根据你App的实际结构，使用Present等不同的方式将其展示。

  注意：目前的IMSDK不支持同时存在两个及以上相同聊天对象的聊天页面，所以下面的代码中先检查了是否已有该对象的聊天页面，如有则使用已有的界面。你的app中应该也要做这样的处理。

  /**
   *  打开某个会话
   */
  - (void)exampleOpenConversationViewControllerWithConversation:(YWConversation *)aConversation fromNavigationController:(UINavigationController *)aNavigationController
  {
      __block YWConversationViewController *alreadyController = nil;
      [aNavigationController.viewControllers enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
          if ([obj isKindOfClass:[YWConversationViewController class]]) {
              YWConversationViewController *c = obj;
              if (aConversation.conversationId && [c.conversation.conversationId isEqualToString:aConversation.conversationId]) {
                  alreadyController = c;
                  *stop = YES;
              }
          }
      }];
  
      if (alreadyController) {
          /// 必须判断当前是否已有该会话，如果有，则直接显示已有会话
          /// @note 目前IMSDK不允许同时存在两个相同会话的Controller
          [aNavigationController popToViewController:alreadyController animated:YES];
          [aNavigationController setNavigationBarHidden:NO];
          return;
      } else {
          YWConversationViewController *conversationController = [self.ywIMKit makeConversationViewControllerWithConversationId:aConversation.conversationId];
  
          __weak typeof(conversationController) weakController = conversationController;
          [conversationController setViewWillAppearBlock:^(BOOL aAnimated) {
              [weakController.navigationController setNavigationBarHidden:NO animated:aAnimated];
          }];
  
          [aNavigationController pushViewController:conversationController animated:YES];
  
          /// 添加自定义插件
          [self exampleAddInputViewPluginToConversationController:conversationController];
  
          /// 添加自定义表情
          [self exampleShowCustomEmotionWithConversationController:conversationController];
  
          /// 设置显示自定义消息
          [self exampleShowCustomMessageWithConversationController:conversationController];
      }
  }

• 胶水代码打开会话入口函数：exampleOpenConversationViewControllerWithConversation:...，其中包含：

  步骤	函数
  判断该会话页面是否存在
  创建会话页面	-[YWIMKit makeConversationViewControllerWithConversationId:]
  添加自定义插件	exampleAddInputViewPluginToConversationController:
  添加自定义表情	exampleShowCustomEmotionWithConversationController:
  设置显示自定义消息	exampleShowCustomMessageWithConversationController:

• 打开单聊页面

  打开与其他用户的单聊页面也非常简单，例如在用户点击发送消息的按钮回调函数中：

  /**
   *  打开单聊页面
   */
  - (void)exampleOpenConversationViewControllerWithPerson:(YWPerson *)aPerson fromNavigationController:(UINavigationController *)aNavigationController
  {
      YWConversation *conversation = [YWP2PConversation fetchConversationByPerson:aPerson creatIfNotExist:YES baseContext:self.appDelegate.ywIMKit.IMCore];
  
      [self exampleOpenConversationViewControllerWithConversation:conversation fromNavigationController:aNavigationController];
  }

• 打开群聊页面

  /**
   *  打开群聊页面
   */
  - (void)exampleOpenConversationViewControllerWithTribe:(YWTribe *)aTribe fromNavigationController:(UINavigationController *)aNavigationController
  {
      YWConversation *conversation = [YWTribeConversation fetchConversationByTribe:aTribe createIfNotExist:YES baseContext:self.appDelegate.ywIMKit.IMCore];
  
      [self exampleOpenConversationViewControllerWithConversation:conversation fromNavigationController:aNavigationController];
  }

更多功能

上述的快速集成文档能够让您以最快的速度完成iOS OpenIM SDK的集成。您可能会对如下主题感兴趣：

• 如何进行UI定制
• 头像修改如何实现
• 消息推送怎么处理
• 群聊怎么实现
• 客服功能怎么使用
• 常见错误排查

FAQ

注册账号