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.