Best practices

These recommendations help you ship a polished video experience with the Video SDK for iOS.

Permissions

The SDK cannot capture from the camera until the user has granted camera access. Add an NSCameraUsageDescription entry to your Info.plist and request permission before you call startVideo.

  • Request camera access at the moment the user takes an action that needs video (such as tapping a "Start camera" button), not at app launch. This makes the prompt feel justified.
  • If the user denies access, surface a clear message and a path to retry. For example, open UIApplication.openSettingsURLString so they can grant the permission in Settings.
  • If you also need audio, add an NSMicrophoneUsageDescription entry and request microphone access at the same time.

See Requesting authorization to capture and save media for the iOS permission flow.

Camera selection

  • Offer a chooser: Use getCameraDeviceList to populate a settings UI so users can pick their preferred camera.
  • Default to the front camera: Most users joining a video call expect the front camera initially.
  • Mirror the front camera preview: Call mirrorMyVideo(true) on front-facing cameras so users see themselves the way they would in a mirror. Don't mirror back-camera video. Toggle the mirror when the user switches cameras.

Layout and density

The SDK doesn't enforce a maximum number of rendered videos, but performance and screen real estate do. For a balance of clarity and performance, the following layouts work well on most iOS devices:

  • iPhone (portrait): 2x2 grid (4 videos per page)
  • iPhone (landscape) and smaller iPad: 3x2 grid (6 videos per page)
  • Larger iPad: 3x3 grid (9 videos per page)

When the number of users exceeds your grid size, paginate rather than scaling videos down further. When video tiles are too small, the content is no longer useful.

Aspect ratio and orientation

  • Use Auto Layout constraints (or an aspect-ratio constraint) on the parent of each video UIView so videos resize predictably with the container.
  • When the device rotates, call rotateMyVideo with the new orientation so remote users see your video the right way up. Observe UIDevice.orientationDidChangeNotification to detect rotation.
  • The ZoomVideoSDKVideoAspect_Original aspect mode is the safest default. It never crops or distorts. Use Full_Filled only when you control the source aspect ratio.

Show video status in your UI

When a user has their camera off, render a placeholder (an avatar, initials, or a "camera off" icon) instead of a blank tile. Implement onUserVideoStatusChanged so you can switch between the rendered video and the placeholder as users toggle their cameras.

Lifecycle

  • Subscribe canvases when a view appears (viewWillAppear) and unsubscribe when it disappears (viewWillDisappear or on session leave) to avoid leaking renderers.
  • iOS suspends camera access when your app moves to the background, so capture stops on its own. You generally don't need to call stopVideo when backgrounding. Stop video when the user explicitly leaves the session.
  • Keep video-related state in your view model so it survives view reloads.

Network resilience

Use setVideoQualityPreference to bias the SDK toward smoothness or sharpness depending on your use case. For most video conferencing scenarios, the default Balance mode is appropriate; switch to Sharpness for content where image detail matters (medical imaging, document cameras) and Smoothness for motion-heavy content (sports, demos).

Hardware

Check isDeviceSupportAlphaChannelMode before exposing alpha-channel video features, since not all devices support them.