NowChatService クラス - iOS

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：20分

    • NowChatService クラスは、仮想チャット機能とライブエージェントチャット機能を提供します。

    このクラスを使用すると、チャットサービスの開始と停止、チャットセッションの開始、チャットユーザーインターフェイスの作成、未読メッセージの登録/登録解除を行うことができます。

    表 : 1. プロパティ
    名前 説明
    構成 サービスの初期化時に指定された構成設定。

    データタイプ: NowServiceConfiguration
    instanceVersion 関連付けられた ServiceNow インスタンスのバージョン (Vancouver や Xanadu など)。

    データタイプ：文字列
    ネットワークサービス このチャットサービスに関連付けられたネットワークサービス。

    データタイプ:NetworkService
    セッションタイプ セッションのタイプ。
    可能な値：
    • 認証
    • ゲスト
    • 偽装
    • 不明

    データタイプ: SessionType

    NowChatService - init(configuration: NowServiceConfiguration, delegate: 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. パラメーター
    名前 タイプ 説明
    theme NowChatThemeable プロトコル: iOS 作成するチャット UI のテーマ情報。
    チャット構成 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:shutdown()

    アクティブなチャットセッションを含むチャットサービスをシャットダウンします。

    この関数を呼び出した後は、関連付けられた 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 (Result<Void, NowChatServiceError>) -> Void)

    チャットセッションを開始し、チャットセッションの開始後に補完ブロックを実行します。

    表 : 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) -> Void)

    未読メッセージ数リスナーに登録します。

    表 : 9. パラメーター
    名前 タイプ 説明
    ポーリング間隔 時間間隔 未読チャットメッセージ数について Web サービスをポーリングする頻度。

    単位：秒
    完了 @escaping (int) -> void) 未読チャットメッセージ数を報告するために呼び出す補完ハンドラー。

    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)

    NowChat UI テーマを指定された UI テーマで更新します。テーマを明から暗に変更する場合など、 makeChatUI() 関数で最初に設定したチャット UI テーマを更新するには、この機能を使用します。

    表 : 13. パラメーター
    名前 タイプ 説明
    theme Now チャットテーマ可能 チャット 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())
}