Heartbeat Functionality in Nuclei SDK
Problem Statement
In mobile applications, maintaining user session validity is essential to deliver a seamless and secure experience. For embedded SDKs like Nuclei, partners need to know when the user is actively engaging with the SDK screen to avoid unintended session expiries.
Without a mechanism to signal ongoing engagement, partners may:
- Expire sessions for users who are actually active
- Interrupt flows such as browsing, form-filling, or payment
- Cause user frustration and increased drop-offs
Our Solution: Heartbeat
To solve this, the Nuclei SDK introduces a Heartbeat mechanism — a lightweight signal sent to the parent app to indicate that the user is still actively engaging with the SDK.
The parent app receives this signal via a callback:
onNucleiHeartBeat()
This allows the host app (or partner system) to extend session timeouts or trigger custom logic while the user is still “alive” on the SDK screen.
When Heartbeat is Triggered
Scenario | Heartbeat Sent? | Notes |
---|---|---|
✅ User is interacting with Nuclei screen | Yes | e.g., tapping, scrolling, typing |
✅ Continuous interaction | Yes | Sent at fixed intervals during activity |
❌ User is idle with screen open | No | No touch or interaction for a duration |
❌ User goes to Recents / background | No | Resuming alone doesn't count as interaction |
❌ User navigates away from SDK screen | No | Heartbeat stops completely |
Heartbeat Frequency
- Configurable interval: Heartbeats are sent based on a predefined delay (e.g., every 1 second).
- On each interaction:
- A timer starts.
- If the interaction continues, heartbeats are sent at the set frequency.
- If no interaction occurs, the timer stops and no heartbeat is sent.
Example
If the delay is set to 1 second:
- Tap →
onNucleiHeartBeat()
triggered - Scroll for 5 seconds → 5 heartbeats sent at 1s intervals
- Pause → heartbeats stop
- Tap again → heartbeat resumes
Business Value
- Prevents unnecessary session expiry for engaged users
- Helps partners accurately measure time spent within Nuclei
- Enables smarter workflows:
- Keeping forms alive
- Resuming drafts
- Boosting conversions
- Works out-of-the-box — partner only needs to handle the callback
FAQs
Q: What exactly counts as interaction?
A: Touch events like taps, scrolls, typing — not just visibility.
Q: Can I change the heartbeat frequency?
A: Yes, it’s configurable. Partners can contact the Nuclei team as per their requirement.
Q: What should I do in onNucleiHeartBeat()
?
A: Extend session timeout, refresh auth tokens, or log engagement metrics.
Q: Will the heartbeat work if there's no network?
A: Heartbeats are delivered via callback to the parent app — no external request involved. It’s up to the app to decide what to do with them.