Skip to main content

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

ScenarioHeartbeat Sent?Notes
✅ User is interacting with Nuclei screenYese.g., tapping, scrolling, typing
✅ Continuous interactionYesSent at fixed intervals during activity
❌ User is idle with screen openNoNo touch or interaction for a duration
❌ User goes to Recents / backgroundNoResuming alone doesn't count as interaction
❌ User navigates away from SDK screenNoHeartbeat 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:

  • TaponNucleiHeartBeat() 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.