@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-calls/references/custom-ui.md

@@ -1,322 +0,0 @@
-# Custom call UI on iOS
-
-Same shape as the other families' custom-ui references. iOS-specific because of CallKit interplay (rule 1.7: CallKit owns standalone-mode incoming UI, so custom in-app incoming UI is additive-mode-only) and AVFoundation routing.
-
----
-
-## Two paths
-
-1. **Style the kit's `CometChatOngoingCall`** UIViewController via theming + property overrides. Cheapest. Covers most apps.
-2. **Build your own UIViewController on the SDK** — direct `CometChatCalls.generateToken` → `startSession` with your own UIView container. Maximum control.
-
-This reference covers path 2.
-
----
-
-## Architecture
-
-```
-Your UIViewController
-├── containerView for remote participant(s)    ← UIView the SDK draws into
-├── localPreviewView                            ← AVCaptureVideoPreviewLayer or SDK preview
-├── controlPanel (mute / camera / end / switch)
-└── statusLabel (call state, duration)
-```
-
-The Calls SDK draws video into UIViews you provide. You don't render WebRTC tracks yourself (unlike web/RN where you wire `<video>` elements).
-
----
-
-## Custom OngoingCallViewController
-
-```swift
-import UIKit
-import AVFoundation
-import CometChatCallsSDK
-
-class CustomOngoingCallViewController: UIViewController {
-  private let containerView = UIView()
-  private let localPreviewView = UIView()
-  private lazy var controlPanel = ControlPanelView()
-  private let statusLabel = UILabel()
-
-  private let sessionID: String
-  private let isAudioOnly: Bool
-  private var muted = false
-  private var cameraOff = false
-
-  init(sessionID: String, isAudioOnly: Bool) {
-    self.sessionID = sessionID
-    self.isAudioOnly = isAudioOnly
-    super.init(nibName: nil, bundle: nil)
-    modalPresentationStyle = .fullScreen
-  }
-
-  required init?(coder: NSCoder) { fatalError() }
-
-  override func viewDidLoad() {
-    super.viewDidLoad()
-    view.backgroundColor = .black
-    setupLayout()
-    startCall()
-  }
-
-  override func viewWillDisappear(_ animated: Bool) {
-    super.viewWillDisappear(animated)
-    cleanup()
-  }
-
-  private func startCall() {
-    // Build CallSettings via CallSettingsBuilder. The CallsEventsDelegate is
-    // wired with setDelegate(_:); there is no SessionSettings/SessionSettingsBuilder.
-    let settings = CallSettingsBuilder()
-      .setIsAudioOnly(isAudioOnly)
-      .setStartVideoMuted(isAudioOnly)
-      .setStartAudioMuted(false)
-      .setDelegate(self)
-      .build()
-
-    // Configure audio session BEFORE starting
-    try? configureAudioSession()
-
-    // Two-step: generateToken THEN startSession into your container UIView.
-    // There is no single-call joinSession on the iOS Calls SDK v5.
-    // authToken: pass CometChat.getUserAuthToken() in additive (chat + calls)
-    // integrations; nil for session-only apps.
-    CometChatCalls.generateToken(authToken: nil, sessionID: sessionID) { [weak self] token in
-      guard let self = self, let token = token else { return }
-      CometChatCalls.startSession(
-        callToken: token,
-        callSetting: settings,
-        view: self.containerView
-      ) { _ in
-        // session started — delegate already wired via setDelegate
-      } onError: { error in
-        print("startSession failed: \(error?.errorDescription ?? "unknown")")
-      }
-    } onError: { error in
-      print("generateToken failed: \(error?.errorDescription ?? "unknown")")
-    }
-  }
-
-  private func configureAudioSession() throws {
-    let session = AVAudioSession.sharedInstance()
-    try session.setCategory(
-      .playAndRecord,
-      mode: isAudioOnly ? .voiceChat : .videoChat,
-      options: [.allowBluetooth, .allowBluetoothA2DP, .defaultToSpeaker]
-    )
-    try session.setActive(true)
-  }
-
-  private func cleanup() {
-    CometChatCalls.endSession()   // EXISTS on the static facade in v5
-    try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
-  }
-
-  private func setupLayout() {
-    [containerView, localPreviewView, controlPanel, statusLabel].forEach {
-      $0.translatesAutoresizingMaskIntoConstraints = false
-      view.addSubview($0)
-    }
-
-    NSLayoutConstraint.activate([
-      containerView.topAnchor.constraint(equalTo: view.topAnchor),
-      containerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
-      containerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
-      containerView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
-
-      localPreviewView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 16),
-      localPreviewView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
-      localPreviewView.widthAnchor.constraint(equalToConstant: 120),
-      localPreviewView.heightAnchor.constraint(equalToConstant: 160),
-
-      controlPanel.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -16),
-      controlPanel.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
-      controlPanel.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
-      controlPanel.heightAnchor.constraint(equalToConstant: 80),
-
-      statusLabel.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 16),
-      statusLabel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
-    ])
-  }
-}
-
-extension CustomOngoingCallViewController: CallsEventsDelegate {
-  func onCallEnded() {
-    DispatchQueue.main.async { [weak self] in
-      self?.cleanup()
-      self?.dismiss(animated: true)
-    }
-  }
-
-  // swiftinterface: onUserListChanged(userList: NSArray) — payload is NSArray of [String: Any]
-  func onUserListChanged(userList: NSArray) {
-    DispatchQueue.main.async { [weak self] in
-      self?.statusLabel.text = "\(userList.count) participants"
-    }
-  }
-
-  // Note: CallsEventsDelegate has no onError callback. Surface generateToken /
-  // startSession failures from their onError closures (see startCall above).
-}
-```
-
-The `DispatchQueue.main.async` wrapping is the iOS equivalent of NgZone.run on Angular — SDK callbacks fire on background queues; UI updates must be on main.
-
----
-
-## Control panel
-
-```swift
-final class ControlPanelView: UIView {
-  let muteButton = UIButton(type: .system)
-  let cameraButton = UIButton(type: .system)
-  let switchCameraButton = UIButton(type: .system)
-  let endButton = UIButton(type: .system)
-
-  var onMute: (() -> Void)?
-  var onCamera: (() -> Void)?
-  var onSwitch: (() -> Void)?
-  var onEnd: (() -> Void)?
-
-  override init(frame: CGRect) {
-    super.init(frame: frame)
-    backgroundColor = UIColor(white: 0, alpha: 0.4)
-    layer.cornerRadius = 40
-
-    let stack = UIStackView(arrangedSubviews: [muteButton, cameraButton, switchCameraButton, endButton])
-    stack.distribution = .equalCentering
-    stack.alignment = .center
-    stack.translatesAutoresizingMaskIntoConstraints = false
-    addSubview(stack)
-
-    NSLayoutConstraint.activate([
-      stack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
-      stack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
-      stack.centerYAnchor.constraint(equalTo: centerYAnchor),
-    ])
-
-    muteButton.setTitle("Mute", for: .normal)
-    cameraButton.setTitle("Cam", for: .normal)
-    switchCameraButton.setTitle("Flip", for: .normal)
-    endButton.setTitle("End", for: .normal)
-    endButton.tintColor = .red
-
-    muteButton.addAction(UIAction { [weak self] _ in self?.onMute?() }, for: .touchUpInside)
-    cameraButton.addAction(UIAction { [weak self] _ in self?.onCamera?() }, for: .touchUpInside)
-    switchCameraButton.addAction(UIAction { [weak self] _ in self?.onSwitch?() }, for: .touchUpInside)
-    endButton.addAction(UIAction { [weak self] _ in self?.onEnd?() }, for: .touchUpInside)
-  }
-
-  required init?(coder: NSCoder) { fatalError() }
-}
-```
-
-Wire actions in the VC:
-
-```swift
-override func viewDidLoad() {
-  super.viewDidLoad()
-  // ...
-  controlPanel.onMute = { [weak self] in
-    guard let self = self else { return }
-    self.muted.toggle()
-    CometChatCalls.audioMuted(self.muted)   // NOT muteAudio
-  }
-  controlPanel.onCamera = { [weak self] in
-    guard let self = self else { return }
-    self.cameraOff.toggle()
-    CometChatCalls.videoPaused(self.cameraOff)   // NOT pauseVideo
-  }
-  controlPanel.onSwitch = { CometChatCalls.switchCamera() }
-  controlPanel.onEnd = { [weak self] in
-    self?.cleanup()
-    self?.dismiss(animated: true)
-  }
-}
-```
-
----
-
-## Local preview before connect
-
-```swift
-private lazy var captureSession = AVCaptureSession()
-private lazy var previewLayer = AVCaptureVideoPreviewLayer(session: captureSession)
-
-private func startLocalPreview() {
-  guard let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .front),
-        let input = try? AVCaptureDeviceInput(device: device) else { return }
-
-  captureSession.addInput(input)
-  previewLayer.frame = localPreviewView.bounds
-  previewLayer.videoGravity = .resizeAspectFill
-  localPreviewView.layer.addSublayer(previewLayer)
-
-  DispatchQueue.global(qos: .userInitiated).async {
-    self.captureSession.startRunning()
-  }
-}
-
-private func stopLocalPreview() {
-  captureSession.stopRunning()
-  previewLayer.removeFromSuperlayer()
-}
-```
-
-Stop the preview BEFORE `startSession` — the SDK takes over the camera and your `AVCaptureSession` will fight with it.
-
----
-
-## SwiftUI hosting
-
-Wrap with `UIViewControllerRepresentable` (see `references/swiftui-uikit-hosting.md`):
-
-```swift
-struct CustomOngoingCallView: UIViewControllerRepresentable {
-  let sessionID: String
-  let isAudioOnly: Bool
-
-  func makeUIViewController(context: Context) -> CustomOngoingCallViewController {
-    CustomOngoingCallViewController(sessionID: sessionID, isAudioOnly: isAudioOnly)
-  }
-
-  func updateUIViewController(_ vc: CustomOngoingCallViewController, context: Context) {}
-}
-```
-
-Present via `.fullScreenCover` (NOT `.sheet`).
-
----
-
-## Picture-in-picture
-
-iOS supports PiP for video calls via `AVPictureInPictureController`:
-
-```swift
-import AVKit
-
-class CustomOngoingCallViewController {
-  private var pipController: AVPictureInPictureController?
-
-  func setupPiP() {
-    guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
-    let layer = AVSampleBufferDisplayLayer()
-    containerView.layer.addSublayer(layer)
-    let contentSource = AVPictureInPictureController.ContentSource(sampleBufferDisplayLayer: layer, playbackDelegate: self)
-    pipController = AVPictureInPictureController(contentSource: contentSource)
-    pipController?.canStartPictureInPictureAutomaticallyFromInline = true
-  }
-}
-```
-
-Setting up your own `AVPictureInPictureController` for WebRTC video is involved — the SDK doesn't expose a `CMSampleBuffer` stream directly. For most apps, use the Calls SDK's built-in PiP instead: `CometChatCalls.enterPIPMode()` / `CometChatCalls.exitPIPMode()` toggle the SDK-managed picture-in-picture for the session view. See `references/picture-in-picture.md`.
-
----
-
-## When NOT to go custom
-
-The kit's `CometChatOngoingCall` covers 80% of apps. Custom is for design-system requirements that the kit's theming + property overrides can't reach. Same calculus as web/RN/Angular.
-
-The dispatcher asks before scaffolding custom and defaults to "no — use kit."

package/skills/cometchat-ios-calls/references/device-management.md

@@ -1,171 +0,0 @@
-# Device management on iOS
-
-iOS handles audio routing at the system level via `AVAudioSession.sharedInstance().availableInputs`. The Calls SDK exposes camera switching (`switchCamera`) but defers audio device selection to the OS — the user picks via the system's audio route picker (`AVRoutePickerView`) or Control Center.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/device-management
-**Read first:** `references/avaudiosession-routing.md` — AVAudioSession setup + Bluetooth/AirPods routing rules.
-
----
-
-## Camera switching (front / back / external)
-
-```swift
-import CometChatCallsSDK
-
-CometChatCalls.switchCamera()
-```
-
-That's the SDK's primary camera control — toggles front/back. For iPad with attached external cameras (Studio Display, Continuity Camera), the user picks via the system Camera control center.
-
----
-
-## Audio inputs (mic / Bluetooth / AirPods)
-
-System-driven via `AVAudioSession`. The user picks from Control Center → Audio destination, or via your in-app `AVRoutePickerView`:
-
-```swift
-import AVKit
-
-class CallControlsView: UIView {
-  private let routePicker = AVRoutePickerView()
-
-  init() {
-    super.init(frame: .zero)
-    routePicker.translatesAutoresizingMaskIntoConstraints = false
-    routePicker.activeTintColor = .systemBlue
-    addSubview(routePicker)
-    NSLayoutConstraint.activate([
-      routePicker.widthAnchor.constraint(equalToConstant: 44),
-      routePicker.heightAnchor.constraint(equalToConstant: 44),
-    ])
-  }
-  required init?(coder: NSCoder) { fatalError() }
-}
-```
-
-`AVRoutePickerView` is the canonical iOS audio-route picker. Tapping shows the system sheet with all available outputs (Built-in Speaker, AirPods, CarPlay, Bluetooth speakers, etc.). System-styled; matches user expectations.
-
----
-
-## Speakerphone toggle
-
-Most calls want a quick speaker on/off without going through the route picker:
-
-```swift
-import AVFoundation
-
-func toggleSpeaker(on: Bool) {
-  do {
-    let session = AVAudioSession.sharedInstance()
-    if on {
-      try session.overrideOutputAudioPort(.speaker)
-    } else {
-      try session.overrideOutputAudioPort(.none)   // restore default routing
-    }
-  } catch {
-    print("Failed to switch speaker: \(error)")
-  }
-}
-```
-
-`.none` means "use the system default for current category" (typically receiver/earpiece for `playAndRecord` + `voiceChat`). NOT "no audio."
-
----
-
-## SwiftUI integration
-
-```swift
-struct CallControls: View {
-  @State private var speakerOn = false
-
-  var body: some View {
-    HStack(spacing: 16) {
-      // Speaker toggle
-      Button(action: {
-        speakerOn.toggle()
-        toggleSpeaker(on: speakerOn)
-      }) {
-        Image(systemName: speakerOn ? "speaker.wave.3.fill" : "speaker.fill")
-      }
-
-      // Camera flip
-      Button(action: { CometChatCalls.switchCamera() }) {
-        Image(systemName: "camera.rotate")
-      }
-
-      // System route picker (Bluetooth / AirPods)
-      AVRoutePickerViewWrapper()
-        .frame(width: 44, height: 44)
-    }
-  }
-}
-
-struct AVRoutePickerViewWrapper: UIViewRepresentable {
-  func makeUIView(context: Context) -> AVRoutePickerView {
-    let view = AVRoutePickerView()
-    view.activeTintColor = .systemBlue
-    return view
-  }
-  func updateUIView(_ view: AVRoutePickerView, context: Context) {}
-}
-```
-
----
-
-## Listen for route changes
-
-```swift
-NotificationCenter.default.addObserver(
-  forName: AVAudioSession.routeChangeNotification,
-  object: AVAudioSession.sharedInstance(),
-  queue: .main
-) { notification in
-  guard let userInfo = notification.userInfo,
-        let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
-        let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else { return }
-
-  switch reason {
-  case .newDeviceAvailable:
-    // AirPods connected, headphones plugged
-    print("New audio device available")
-  case .oldDeviceUnavailable:
-    // Headphones unplugged
-    print("Audio device unavailable")
-  default:
-    break
-  }
-}
-```
-
-The two reason codes that matter for UI: `.newDeviceAvailable` (show "AirPods connected" toast) and `.oldDeviceUnavailable` (audio routes back to speaker; might want to update UI button state).
-
----
-
-## Anti-patterns
-
-1. **Building a custom audio route picker** instead of using `AVRoutePickerView`. iOS users expect the system picker; custom feels off-brand.
-2. **Setting `overrideOutputAudioPort(.speaker)` from background.** AVAudioSession changes only work when session is active. Wrap in `setActive(true)` first.
-3. **Forgetting to listen for `routeChangeNotification`.** UI gets out of sync when user changes route via Control Center.
-4. **Calling `setActive(true)` repeatedly during a call.** AVAudioSession is sticky once activated; redundant calls produce warnings in console.
-5. **Not handling `.failed` errors from `overrideOutputAudioPort`.** Some Bluetooth devices reject the override; silently swallow OR show a toast.
-
----
-
-## Verification checklist
-
-- [ ] `AVRoutePickerView` rendered in call controls
-- [ ] Speaker toggle uses `overrideOutputAudioPort` correctly
-- [ ] `.routeChangeNotification` observer set up
-- [ ] All AVAudioSession calls on main queue
-- [ ] Real-device smoke: AirPods connect mid-call → toast shown, audio routes
-- [ ] Real-device smoke: Speaker toggle works
-- [ ] Real-device smoke: Camera flip works (front/back)
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/device-management.md` — web sister reference (different mechanism but UX shape)
-- `cometchat-ios-calls` SKILL.md — the seven hard rules
-- `references/avaudiosession-routing.md` — AVAudioSession setup details
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/device-management