Qiscus SDK iOS

快速开始

创建新应用

使用您的电子邮件和密码在 https://www.qiscus.com/dashboard 上注册，然后创建新应用程序

您应该为每个服务创建一个应用程序，不论平台如何。例如，同时在 Android 和 iOS 上发布的应用程序只需要在仪表板上创建一个应用程序。

同一 Qiscus 应用程序中所有用户都可以相互通信，所有平台通用。这意味着使用 iOS、Android、Web 客户端等的用户都可以相互聊天。然而，不同 Qiscus 应用的用户无法相互交谈。

完成！现在您可以将 APP_ID 用于您的应用，并通过在应用程序中实现 Qiscus 来获取聊天功能。

将SDK集成到现有应用中

CocoaPods是Cocoa项目的依赖管理工具。您可以使用以下命令安装它：

$ gem install cocoapods

需要CocoaPods 1.1.0+。

Podfile

target 'Sample' do

  .....
  use_frameworks!

  .....
  pod 'Qiscus'
  .....

end

通过CocoaPods安装Qiscus

$ pod install

身份验证

使用App ID初始化

要启动Qiscus SDK，您需要导入Qiscus，然后在代码中需要使用的每个地方添加以下内容

Swift 3.0

import Qiscus


Qiscus.setup( withAppId: YOUR_APP_ID, 
              userEmail: CURRENT_USER_EMAIL, 
              userKey: CURRENT_USER_PASSWORD, 
              username: CURRENT_USER_USERNAME, 
              avatarURL: CURRENT_USER_AVATAR_URL, 
              delegate: self
)

在Objective-C中使用SDK

import Qiscus

[Qiscus setupWithAppId:<YOUR_APP_ID> 
        userEmail:<USER_EMAIL> 
        userKey:<USER_KEY> 
        username:<USER_NAME> 
        avatarURL:<USER_AVATAR_URL> 
        delegate:self 
        secureURl:<true|false>];

在AppDelegate.swift中的示例

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        let viewController = ViewController()
        let navigationController = UINavigationController(rootViewController: viewController)
        
        Qiscus.setup( withAppId: "DragonGo",
                      userEmail: "[email protected]",
                      userKey: "abcd1234",
                      username: "Steve Kusuma",
                      avatarURL: "",
                      delegate: nil
        )
        
        self.window = UIWindow(frame: UIScreen.main.bounds)
        window?.rootViewController = navigationController
        window?.makeKeyAndVisible()

        return true
}

更新用户资料和头像

通过重新初始化用户并使用新细节来更新用户的资料和详细信息

        Qiscus.setup( withAppId: "DragonGo",
                      userEmail: "[email protected]",
                      userKey: "abcd1234",
                      username: "Steve Kusuma New Name",
                      avatarURL: "https://myimage.com/myNewImage.png",
                      delegate: nil
        )

聊天室

创建1对1聊天

与目标开始聊天非常简单，您只需在代码中调用

Swift 3.0

      let email = targetField.text!
      let view = Qiscus.chatView(withUsers: [email])
      self.navigationController?.pushViewController(view, animated: true)

在你的代码里

例如，在你的ViewController中

Swift 3.0

import UIKit
import Qiscus

class ViewController: UIViewController {

.....

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        let button = UIButton(frame: CGRect(x: 100, y:100, width:100, height:30))
        button.backgroundColor = UIColor.green
        button.setTitle("Start Chat", for: .normal)
        button.addTarget(self, action: #selector(ViewController.startChat), for: .touchUpInside)
        self.view.addSubview(button)
        
    }
    
    func startChat(){
        let email = targetField.text!
        let view = Qiscus.chatView(withUsers: [email])
        self.navigationController?.pushViewController(view, animated: true)
    }

.....
}

创建群聊室

Qiscus 还支持群聊。要创建新的群聊，你只需要调用

Swift 3.0

Qiscus.createChatView(withUsers: ["TARGET_EMAIL_1, TARGET_EMAIL_2"], title: "CHAT_GROUP_TITLE")

例如，在你的ViewController中

Swift 3.0

import UIKit
import Qiscus

class ViewController: UIViewController {

    .....
    func goToChat(){
        let chatTargets = ["[email protected], [email protected]"]
        let view = Qiscus.createChatView(withUsers: chatTargets, title: "New Group Chat")
        self.navigationController?.pushViewController(view, animated: true)
    }
    .....
}

要通过这个调用访问创建的房间，你需要调用它时带上其 roomId。这个方法始终会在新聊天室中创建。

通过 ID 获取房间

当你已经知道房间 id 时，你可以轻松地进入该房间。只需调用

Swift 3.0

Qiscus.chatView(withRoomId: roomId)

例如，在你的ViewController中

Swift 3.0

import UIKit
import Qiscus

class ViewController: UIViewController {

.....

  func goToChat(){
          let roomId = Int(targetField.text!)
          let view = Qiscus.chatView(withRoomId: roomId)
          self.navigationController?.pushViewController(view, animated: true)
  }

.....
}

通过定义的 ID 创建或加入房间

你可能想要为创建的房间设置定义的 ID，以便用作用户参考。

此功能的常规用途是当创建普通房间或渠道，预期其他用户可以知道渠道名称或 ID 并加入该渠道时，你可以使用渠道名称或 ID 作为 qiscus 房间定义 ID。

附加说明：如果预先定义的唯一 ID 房间不存在，则将创建一个新房间，请求者作为唯一的参与者。否则，如果预先定义的唯一 ID 房间已存在，它将返回该房间并将请求者添加为参与者。

在第一次调用（房间不存在）时，如果请求者没有发送 avatar_url 和/或房间名称，将使用默认值。但是，在第二次调用（房间存在）后，如果用户（请求者）发送 avatar_url 和/或房间名称，它将更新为该值。在第一个调用中变化的对象将是 true，并且在 avatar_url 或房间名称更新时。

Swift 3.0

Qiscus.chatView(withRoomUniqueId: uniqueId)

例如，在你的ViewController中

Swift 3.0

import UIKit
import Qiscus

class ViewController: UIViewController {

.....

  func goToChat(){
          let roomId = Int(targetField.text!)
          let view = Qiscus.chatView(withRoomUniqueId: uniqueId)
          self.navigationController?.pushViewController(view, animated: true)
  }

.....
}

邀请用户加入现有房间

目前我们建议通过我们的 REST API 邀请用户加入现有房间，因为这样做既简单又安全。

离开群聊房间

目前我们推荐通过我们简单的、安全的 REST API 来踢用户出群，以提高效率和安全

获取房间列表

我们可以通过执行此函数获取用户的房间列表，但是没有返回 view。该函数只返回房间的数据

Qiscus.roomList(withLimit: 100, page: page, onSuccess: { (rooms, totalRoom, currentPage) in
            print("room list: \(rooms)")
        }) { (error) in
            print("\(error)")
        }

事件处理

QiscusConfigDelegate

class MainView: UIViewController, QiscusConfigDelegate {

    // MARK: - QiscusConfigDelegate
    func qiscusFailToConnect(_ withMessage:String){
        print(withMessage)
        ...
    }
    func qiscusConnected(){
        appDelegate.goToChatNavigationView()
        ...
    }
}

QiscusRoomDelegate

class SampleAppRealtime: QiscusRoomDelegate {
    
    // MARK: - Member of QiscusRoomDelegate
    internal func gotNewComment(_ comments: CommentModel) {
        print("getting new messages")
    }
    
    internal func didFinishLoadRoom(onRoom room: RoomModel) {
        print("did finish load roomId: \(localRoom.roomId), roomName: \(localRoom.roomName)")
    }
    
    internal func didFailLoadRoom(withError error: String) {
        print("did fail load room error: \(error)")
    }

    func didFinishUpdateRoom(onRoom room: RoomModel) {
        print("did finish update room roomId: \(localRoom.roomId), roomName: \(localRoom.roomName)")
    }
    
    func didFailUpdateRoom(withError error:String) {
        print("did fail update room: \(error)")
    }
    
}

UI 定制化

主题定制化

在我们的聊天室内部，很多组件可以根据需要进行修改。以下是一些易于实现的定制的例子

 
  let qiscusColor = Qiscus.style.color
  qiscusColor.welcomeIconColor = colorConfig.chatWelcomeIconColor
  qiscusColor.leftBaloonColor = colorConfig.chatLeftBaloonColor
  qiscusColor.leftBaloonTextColor = colorConfig.chatLeftTextColor
  qiscusColor.leftBaloonLinkColor = colorConfig.chatLeftBaloonLinkColor
  qiscusColor.rightBaloonColor = colorConfig.chatRightBaloonColor
  qiscusColor.rightBaloonTextColor = colorConfig.chatRightTextColor
        
  Qiscus.setNavigationColor(colorConfig.baseNavigateColor, tintColor: colorConfig.baseNavigateTextColor)

  let fontSize: CGFloat = CGFloat(17).flexibleIphoneFont()
  Qiscus.style.chatFont = UIFont.systemFont(ofSize: fontSize)
  

UI 源代码

如果您希望进行全面定制，可以根据自己的需求扩展我们的 QiscusChatVC 来修改视图上的所有内容。

以下是扩展我们的 QiscusChatVC 的修改示例

class QChatView: QiscusChatVC {
    var actions : [ChatAction]? = nil
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        // self.collectionViewTopMargin.constant = 100
        self.backgroundView.isHidden    = true

        let iconCall        = UIImage(named: "ic_phone_call", in: QChat.bundle, compatibleWith: nil)
        let iconCallVideo   = UIImage(named: "ic_video_call", in: QChat.bundle, compatibleWith: nil)
        let iconEnd         = UIImage(named: "ic_end_consultation", in: QChat.bundle, compatibleWith: nil)
        
        let endButton = UIButton(frame: CGRect(x: 0, y: 0, width: 40, height: 20))
        endButton.setBackgroundImage(iconEnd, for: .normal)
        endButton.imageView?.contentMode = UIViewContentMode.scaleAspectFit
        endButton.addTarget(self, action: #selector(endConsultation), for: .touchUpInside)
        let barButtonEnd    = UIBarButtonItem(customView: endButton)

        let callButton = UIButton(frame: CGRect(x: 0, y: 0, width: 20, height: 20))
        callButton.setBackgroundImage(iconCall, for: .normal)
        callButton.imageView?.contentMode = UIViewContentMode.scaleAspectFit
        callButton.addTarget(self, action: #selector(addTapped), for: .touchUpInside)
        let barButtonCall    = UIBarButtonItem(customView: callButton)
        
        let callVideoButton = UIButton(frame: CGRect(x: 0, y: 0, width: 30, height: 20))
        callVideoButton.setBackgroundImage(iconCallVideo, for: .normal)
        callVideoButton.imageView?.contentMode = UIViewContentMode.scaleAspectFit
        callVideoButton.addTarget(self, action: #selector(addTapped), for: .touchUpInside)
        let barButtonCallVideo    = UIBarButtonItem(customView: callVideoButton)
        
        navigationItem.rightBarButtonItems = [barButtonEnd, barButtonCallVideo, barButtonCall]
    }
    
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        self.tabBarController?.tabBar.isHidden = true
    }
    
    func addTapped() {
        print("something")
    }
    
    func endConsultation() {
        postComment(type: "endConsultation", payload: "Semoga Lekas sembuh")
    }
    
    func postComment(type: String, payload: String) {
        let newComment = self.chatRoom?.newCustomComment(type: type, payload: payload, text: "Pesan Doktor")
        self.chatRoom?.post(comment: newComment!)
    }
    
    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }
    
    override func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        
        return super.collectionView(collectionView, cellForItemAt: indexPath)
    }
}

推送通知

目前我们推荐使用我们的Webhook-API，将通知从您的服务器推送到客户端应用程序，以实现简单和灵活的处理。

离线消息

发送消息

在发送消息时，如果您没有互联网连接，消息将本地存储，一旦您的互联网连接恢复，消息将自动发送。

获取消息

消息本地存储，因此即使在您没有互联网连接的情况下，您也可以访问这些消息。然而，一旦您的互联网连接恢复，您将不会收到任何新消息。

备注

请勿忘记在您的 **info.plist** 中添加对相机、照片库和麦克风的用途描述，以便在聊天SDK中使用我们的附件功能。

<key>NSCameraUsageDescription</key>
<string>Need camera access for uploading Images</string>
<key>NSContactsUsageDescription</key>
<string>Need access for sync contact</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>$(PRODUCT_NAME) location use</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) location use</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) microphone use</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>NeedLibrary access for uploading and Images</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>NeedLibrary access for uploading and Images</string>

安全披露

如果您认为您已识别出QiscusCore的安全漏洞，请尽快通过邮件报告，电子邮箱为 [email protected]。请不要将其发布在公共问题中。

常见问题解答（FAQ）

我们为什么选择使用Qiscus而不是QiscusCore或QiscusUI？

QiscusCore是轻量级的聊天SDK，如果您想构建自己的聊天UI，最佳选择是使用QiscusCore。但是，如果您需要快速在应用程序中使用聊天功能，建议使用包含UI和简单配置的Qiscus Chat SDK。请访问Qiscus以使用Qiscus Chat SDK。QiscusUI允许您构建自己的聊天UI，QiscusUI提供了聊天组件，使开发特定类型的聊天单元变得容易。QiscusUI中的每个组件都是基本的，但Qiscus还提供了标准功能，如渲染图像、文本、文件，以及发送图像、视频等。