Troubleshooting
Common iOS integration problems and how to resolve them.
No result ever arrives
If onResult never fires, the capture is not accumulating enough clean signal.
Watch the live signal quality from onRealtime and guide
the user:
- Poor quality persists — improve lighting, ask the user to hold still, and make sure the face fills the frame without being too close.
- Frame rate too low — ensure your capture runs at ~30 fps and you are not dropping frames before calling
processFrame.
No live heart rate
onRealtime surfaces a heart rate only once the pulse stabilizes (about 10
seconds of clean signal). If it never appears, the signal quality is staying low —
check lighting and stillness.
HRV, breathing, or stress come back null
These need many clean beats. In a short or noisy session they can legitimately be
null. Encourage a longer, stiller capture, and always handle null in your UI.
See Signal quality.
Timestamps
processFrame expects timestampSeconds in seconds (for example
CMTimeGetSeconds(...)), increasing monotonically. Passing milliseconds or a
non-monotonic clock corrupts the timing and degrades every metric.
Camera permission
The SDK does not open the camera — you feed it frames. Make sure your app has
camera permission and an NSCameraUsageDescription in Info.plist; see
Installation.
Authentication errors
If measurement submission to the API fails, confirm your key id and secret are correct and your device clock is within the ±300 s window. See Authentication and Errors.