NowChatService 클래스 - iOS

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 19분

    • NowChatService 클래스는 가상 및 라이브 에이전트 채팅 기능을 제공합니다.

    이 클래스를 사용하여 채팅 서비스를 시작 및 중지하고, 채팅 세션을 시작하고, 채팅 사용자 인터페이스를 만들고, 읽지 않은 메시지를 구독/구독 취소할 수 있습니다.

    표 1. 속성
    이름 설명
    구성 서비스가 초기화될 때 제공된 구성 설정입니다.

    데이터 유형: NowServiceConfiguration
    인스턴스 버전 연결된 ServiceNow 인스턴스의 버전입니다(예: Vancouver 또는 Xanadu).

    데이터 유형: 문자열
    네트워크 서비스 이 채팅 서비스와 연결된 네트워크 서비스입니다.

    데이터 유형: NetworkService
    세션 유형 세션의 유형입니다.
    가능한 값:
    • 인증
    • 게스트
    • 가장
    • 알 수 없음

    데이터 유형: SessionType

    NowChatService - init(구성: NowServiceConfiguration, 위임자: NowChatServiceDelegate?, coreServiceProvider: NowCoreServiceProviding? = nil)

    새 NowChatService 인스턴스를 초기화합니다.

    표 2. 매개변수
    이름 유형 설명
    구성 NowServiceConfiguration 서비스를 올바르게 초기화하는 데 필요한 구성 정보입니다.
    위임 NowChatServiceDelegate 옵션입니다. NowChatServiceDelegate 프로토콜을 구현하는 NowChat 콜백 대리자 객체입니다.

    기본값: nil
    코어서비스제공자 NowCoreServiceProviding 옵션입니다. NowCoreServiceProviding 프로토콜을 구현하는 객체입니다. NowChat 서비스에 대한 액세스를 제공합니다.

    기본값: nil

    다음 코드 예제에서는 이 함수를 호출하는 방법을 보여 줍니다.

    guard let coreService = NowSDK.core() else {
  // Error with NowServiceError.sdkNotConfigured
  return
}

guard 
  let instanceUrl = URL(string: "http://sample.service-now.com"), 
  let serviceConfig = NowSDK.makeServiceConfiguration(for: instanceUrl) else {
    // Could not create service – 
    // NowServiceError.serviceConfigurationInvalid
    return
  }
    
let chatService = NowChatService(configuration: serviceConfig, delegate: delegate, coreServiceProvider: coreService)

    NowChatService - makeChatUI(theme: NowChatThemeable, chatConfiguration: NowChatConfiguration? = nil) -> Result<UIViewController, NowChatServiceError>)

    채팅 사용자 인터페이스를 호스트하는 UIViewController 를 만듭니다.

    이 함수는 채팅 UI를 생성하지만 startChat() 함수를 호출하여 채팅 세션을 시작해야 합니다. 채팅 UI가 표시될 때 이 전화를 걸어야 합니다. 자세한 내용은 관련 샘플 응용 프로그램 및 Mobile SDK 개발자 가이드 - iOS.

    표 3. 매개변수
    이름 유형 설명
    주제 NowChatThemeable 프로토콜 - iOS 채팅 UI에서 생성할 테마 정보입니다.
    chatConfiguration NowChatConfiguration을 사용하시겠습니까? 옵션입니다. 채팅 세션에 적용할 옵션입니다.
    표 4. 반환
    유형 설명
    객체 성공: UI 뷰 컨트롤러 구성 정보를 포함하는 UIViewController 개체입니다.

    실패: NowChatServiceError 객체입니다.

    가능한 오류:
    • chatServiceInvalid
    • coreServiceInvalid
    • guestUserNotAllowed
    • 유효하지 않은 자격 증명
    • 세션 없음
    • 알 수 없음
    • 지원되지 않는 서버

    다음 코드 예제에서는 이 함수를 호출하여 채팅 UI를 만드는 방법을 보여 줍니다.

    func makeChatScreen() -> UIViewController? {
  guard let chatService = chatService else { return nil } 

  let closePrompt = NowChatConfiguration.ClosePrompt(header: "Close Window",
    message: "Are you sure you want to close the chat window?",
    acceptButtonTitle: "Yes",
    declineButtonTitle: "No") 

  let attachmentUploadButton = NowChatConfiguration.AttachmentUploadButton(isVisible: false) // default isVisible = true

  let chatConfiguration = NowChatConfiguration(closePrompt: closePrompt,
    disabledFeatures: [.startNewConversation],
    conversationOptions: [.forceNewConversation, .endConversationOnExit],
    uiConfiguration: NowChatConfiguration.UIConfiguration(closeButton: closeButtonImage(name: "arrow.left"), attachmentUploadButton: attachmentUploadButton))

  let result = chatService.makeChatUI(theme: CarrascoChatTheme(chatColors: ChatColors()), chatConfiguration: chatConfiguration)    

  switch result {
    case .success(let chatViewController):
      return chatViewController
    case .failure(let error):
      debugPrint("Chat screen creation failed with error: \(error)") 
      return nil
  }
}

    NowChatService - 종료()

    활성 채팅 세션을 포함하여 채팅 서비스를 종료합니다.

    이 함수를 호출한 후에는 연결된 NowChatService 가 비활성화되어 다시 사용할 수 없습니다. 다른 채팅 세션을 설정하려면 NowChat.makeChatService() 함수를 호출하여 새 NowChatService 인스턴스를 생성합니다.

    표 5. 매개변수
    이름 유형 설명
    없음
    표 6. 반환
    유형 설명
    없음

    다음 코드 예제에서는 이 함수를 호출하는 방법을 보여 줍니다.

    private func resetChat() {
  chatService?.shutdown()
  chatService = nil
  initializeChatService()
  viewState = makeViewState()
}

func initializeChatService() {
  NowChat.makeChatService(instanceUrl: instanceUrl, delegate: self) { [weak self] result in
    guard let self = self else { return }
            
    switch result {
    case .success(let service):
      self.chatService = service
    case .failure(let error):
      debugPrint("Creating the chat service failed with error: \(error)")
    }
    self.viewState = self.makeViewState()
}

func makeViewState() -> ViewState {
  ViewState(chatEnabled: chatService != nil,
    menuItems: menuItems)
}

    NowChatService - startChat(contextData: [String: Any]? = nil, _ completion: @escaping (결과<무효, NowChatServiceError>) -> 무효)

    채팅 세션을 시작하고 채팅 세션이 시작된 후 완료 블록을 실행합니다.

    표 7. 매개변수
    이름 유형 설명
    컨텍스트데이터 [문자열: any]? 옵션입니다. 채팅 세션에 전달되는 채팅 컨텍스트 변수를 포함하는 딕셔너리입니다.

    채팅 컨텍스트 변수에 대한 자세한 내용은 다음 문서를 참조하십시오 Live agent chat context variables.
    완료 객체 채팅 세션이 시작된 후 실행할 완성 블록입니다.
    표 8. 반환
    유형 설명
    void 또는 String
    완성 블록에 대한 반환 값:
    • 성공: 무효
    • 오류: NowChatServiceError
    가능한 오류:
    • chatServiceInvalid
    • coreServiceInvalid
    • guestUserNotAllowed
    • 유효하지 않은 자격 증명
    • 세션 없음
    • 알 수 없음
    • 지원되지 않는 서버

    다음 코드 예제에서는 컨텍스트 데이터 없이 이 함수를 호출하는 방법을 보여 줍니다.

    func startChat() {
  guard let chatService = chatService else {
    debugPrint("Chat service is invalid")
    viewState = makeViewState()
    return
  }
  chatService.startChat { [weak self] result in
    if case .failure(let error) = result {
      debugPrint("Chat session initialization failed with error: \(error)")
      self?.resetChat()
    }
  }
}

func makeViewState() -> ViewState {
  ViewState(chatEnabled: chatService != nil,
    menuItems: menuItems)
}

    다음 코드 예제에서는 컨텍스트 데이터를 사용하여 이 함수를 호출하는 방법을 보여 줍니다.

    func startChat() {
  guard let chatService = chatService else {
    debugPrint("Chat service is invalid")
    viewState = makeViewState()
    return
  }

  let contextData = ["sys_id": "123456789", "table_name": "wm_task", "active": true] as [String: Any]
  chatService.startChat(contextData: contextData) { [weak self] result in
    if case .failure(let error) = result {
      debugPrint("Chat session initialization failed with error: \(error)")
      self?.resetChat()
    }
  }
}

func makeViewState() -> ViewState {
  ViewState(chatEnabled: chatService != nil,
    menuItems: menuItems)
}

    NowChatService - subscribeToUnreadMessageCount(pollingInterval: TimeInterval, completion: @escaping (Int) -> 무효)

    읽지 않은 메시지 카운트 수신기를 구독합니다.

    표 9. 매개변수
    이름 유형 설명
    폴링간격 시간 간격 읽지 않은 채팅 메시지 수에 대해 웹 서비스를 폴링할 빈도입니다.

    단위: 초
    완료 @escaping(int) - > 무효) 읽지 않은 채팅 메시지 수를 보고하기 위해 호출하는 완료 핸들러입니다.

    Int: 읽지 않은 채팅 메시지 수입니다.
    표 10. 반환
    유형 설명
    없음

    다음 코드 예제에서는 이 함수를 호출하는 방법을 보여 줍니다.

    …
if viewModel.isPolling {
  viewModel.unsubscribeFromUnreadMessageCount()
  viewState.pollingInterval = ""
} else {
  viewModel.subscribeToUnreadMessageCount(pollingInterval: timeInterval)
}
…

func subscribeToUnreadMessageCount(pollingInterval: TimeInterval) {
  chatService.subscribeToUnreadMessageCount(pollingInterval: pollingInterval) { [weak self] count in
    self?.unreadMessageCount = count
  }
  isPolling = true
}

    NowChatService - unsubscribeFromUnreadMessageCount()

    읽지 않은 메시지 카운트 수신기 수신을 구독 취소합니다.

    표 11. 매개변수
    이름 유형 설명
    없음
    표 12. 반환
    유형 설명
    없음

    다음 코드 예제에서는 이 함수를 호출하는 방법을 보여 줍니다.

    …
if viewModel.isPolling {
  viewModel.unsubscribeFromUnreadMessageCount()
  viewState.pollingInterval = ""
} else {
  viewModel.subscribeToUnreadMessageCount(pollingInterval: timeInterval)
}
…
func unsubscribeFromUnreadMessageCount() {
  chatService.unsubscribeFromUnreadMessageCount()
  isPolling = false
  unreadMessageCount = 0
}

    NowChatService - updateTheme(테마: NowChatThemeable)

    지정된 UI 테마로 NowChat UI 테마를 업데이트합니다. 이 함수를 사용하면 테마를 밝은 색에서 어두운 색으로 변경할 때와 같이 makeChatUI() 함수를 사용하여 채팅 UI 테마를 처음 설정한 후 업데이트할 수 있습니다.

    표 13. 매개변수
    이름 유형 설명
    주제 NowChat테마 가능 채팅 UI를 업데이트할 테마입니다.
    표 14. 반환
    유형 설명
    없음

    다음 코드 예제에서는 updateTheme() 함수를 사용하여 밝은 UI 테마를 어두운 UI 테마로 업데이트하는 방법을 보여 줍니다.

    struct LightNowChatColoring: NowChatColoring {
  let nowUIColor: NowUIColoring = LightNowUIColor()
  let brand = UIColor.now_color(withHexString: "#032D42")
  let primary = UIColor.now_color(withHexString: "#00566E")
  let secondary = UIColor.now_color(withHexString: "#002832")
  let destructive = UIColor.now_color(withHexString: "#E52239")
  let textPrimary = UIColor.now_color(withHexString: "#10171A")
  let textSecondary = UIColor.now_color(withHexString: "#232E33")
  let textTertiary = UIColor.now_color(withHexString: "#37444A")
  let textActionable = UIColor.now_color(withHexString: "#ffffff")
  let screenHeaderText = UIColor.now_color(withHexString: "#ffffff")
  let backgroundPrimary = UIColor.now_color(withHexString: "#ffffff")
  let backgroundSecondary = UIColor.now_color(withHexString: "#F5F6F7")
  let backgroundTertiary = UIColor.now_color(withHexString: "#E2E5E7")
  let backgroundPrimaryActionable = UIColor.now_color(withHexString: "#10171A")
  let backgroundSecondaryActionable = UIColor.now_color(withHexString: "#232E33")
  let brandBackground = UIColor.now_color(withHexString: "#BDDEE7")
  let borderTertiary = UIColor.now_color(withHexString: "#d3d6dc")
  let separatorPrimary = UIColor.now_color(withHexString: "#859095")
  let separatorTertiary = UIColor.now_color(withHexString: "#CFD5D7")
  let alertCritical0 = UIColor.now_color(withHexString: "#F9C8CE")
  let alertCritical3 = UIColor.now_color(withHexString: "#E52239")
  let shadow = UIColor.now_color(withHexString: "#10171A")
  let linkPrimary = UIColor.now_color(withHexString: "#1955BE")
  let linkSecondary = UIColor.now_color(withHexString: "#113A82")
  let notification = UIColor.now_color(withHexString: "#E52239")
  let highlightBlue = UIColor.now_color(withHexString: "#C4DBFE")
  let highlightGray = UIColor.now_color(withHexString: "#DCDDDE")
}

struct DarkNowChatColoring: NowChatColoring {
  let nowUIColor: NowUIColoring = DarkNowUIColor()
  let brand = UIColor.now_color(withHexString: "#032D42")
  let primary = UIColor.now_color(withHexString: "#6CBBD0")
  let secondary = UIColor.now_color(withHexString: "#99C6D2")
  let destructive = UIColor.now_color(withHexString: "#E46775")
  let textPrimary = UIColor.now_color(withHexString: "#FFFFFF")
  let textSecondary = UIColor.now_color(withHexString: "#E2E5E7")
  let textTertiary = UIColor.now_color(withHexString: "#BCC3C7")
  let textActionable = UIColor.now_color(withHexString: "#050809")
  let backgroundPrimary = UIColor.now_color(withHexString: "#050809")
  let backgroundSecondary = UIColor.now_color(withHexString: "#161F23")
  let backgroundTertiary = UIColor.now_color(withHexString: "#1D272B")
  let backgroundPrimaryActionable = UIColor.now_color(withHexString: "#FFFFFF")
  let backgroundSecondaryActionable = UIColor.now_color(withHexString: "#BCC3C7")
  let brandBackground = UIColor.now_color(withHexString: "#002934")
  let separatorPrimary = UIColor.now_color(withHexString: "#97A2A6")
  let separatorTertiary = UIColor.now_color(withHexString: "#4F5C62")
  let borderTertiary = UIColor.now_color(withHexString: "#454d5b")
  let screenHeaderText = UIColor.now_color(withHexString: "#FFFFFF")
  let alertCritical0 = UIColor.now_color(withHexString: "#7B1D28")
  let alertCritical3 = UIColor.now_color(withHexString: "#E46775")
  let shadow = UIColor.now_color(withHexString: "#10171A")
  let notification = UIColor.now_color(withHexString: "#E46775")
  let linkPrimary = UIColor.now_color(withHexString: "#339EFC")
  let linkSecondary = UIColor.now_color(withHexString: "#70BBFD")
  let highlightBlue = UIColor.now_color(withHexString: "#004652")
  let highlightGray = UIColor.now_color(withHexString: "#363D3D")
}

struct LightNowChatTheme: NowChatThemeable {
  let color: NowChatColoring = LightNowChatColoring()
}

struct DarkNowChatTheme: NowChatThemeable {
  let color: NowChatColoring = DarkNowChatColoring()
}

func chatService(_ chatService: NowChat.NowChatService, systemThemeDidChange traitCollection: UITraitCollection) {
  // The systemThemeDidChange delegate method can be used to call updateTheme() to apply theme changes when the system theme changes.
  debugPrint("System Theme did change")
  chatService.updateTheme(theme: traitCollection.userInterfaceStyle == .dark ? DarkNowChatTheme() : LightNowChatTheme())
}