Real Time Event Notifications

Objective

Real-time events are milestone notifications emitted by the SDK during the user's onboarding journey. These events provide visibility into the user's progress through each step of the process.

Key Feature

The Real-Time Event Notifications provides immediate insights into user journeys through event-based architecture.

These events can be integrated with your CRM systems or notification tools, enabling:

• Real-time tracking of user progress.
• Trigger-based interventions (e.g., reminders, agent calls).
• Enhanced funnel analytics and proactive drop-off management.

Important

Real-time event notifications must be enabled for your account before you can receive them. Even if you implement the event listeners correctly, you will not receive any events unless this feature is enabled. Please contact HyperVerge to enable real-time events for your account.

Event Details

When is it triggered?

Events are triggered when a user completes a major milestone (stage completion) in their journey. For example, when they finish the last module of a step that has event triggers enabled.

Sample Event

The following is a JSON structure for the step_ended event:

{
  "schemaVersion": "1.0.0",
  "eventName": "step_ended",
  "timestamp": "2025-04-21T10:35:40.321Z",
  "sdkVersion": "0.45.0",
  "transactionId": "transactionId_1234",
  "workflowId": "onboarding",
  "workflowVersion": "1.0.0",
  "appId": "abcdef",
  "stepId": "digilocker",
  "metadata": {}
}

Event Description

The following table describes all the details returned in the event notification:

Field	Type	Description
schemaVersion	string	The schema version to preserve contract compatibility for existing integrations
eventName	string	The name of the event
timestamp	string	The UTC time of the event — important for sequencing
sdkVersion	string	The version of SDK that sent the event
transactionId	string	The unique identifier of the application
stepId	string	The identifier of the stage completed
metadata	JSON object	The event-specific payload

SDK Integration

Use the SDK-provided addEventListener API to subscribe to real-time milestone events.

The following sections highlight how to implement real-time event listeners for each supported platform. Make sure to implement these listeners before launching the HyperKYC SDK to ensure you don't miss any events.

Android

Implement real-time event notifications in your Android app using Java or Kotlin.

Java

Java

HyperKyc.addEventListener(jsonObject -> {
    // Handle the step_ended event
    // ....
    return Unit.INSTANCE;
});

HyperKyc.removeAllEventListeners();

Kotlin

Kotlin

HyperKyc.addEventListener { event ->
    // Handle the step_ended event
}

HyperKyc.removeAllEventListeners()

iOS

Implement real-time event notifications in your iOS app using Swift closures.

Swift

HyperKyc.addEventListener { event in
    // Handle the step_ended event
}

HyperKyc.removeAllEventListeners()

React Native

Implement real-time event notifications in your React Native app using JavaScript callbacks.

Javascript

// Import HyperKyc from react-native-hyperkyc-sdk
import HyperKyc from 'react-native-hyperkyc-sdk';

// [Recommended] Attach event listeners before launching HyperKYC SDK
HyperKyc.addEventListener((event) => {
    // Handle the step_ended event
});

// [Recommended] Remove all event listeners after receiving the SDK response from HyperKYC SDK
HyperKyc.removeAllEventListeners();

Flutter

Implement real-time event notifications in your Flutter app using stream-based listeners.

Dart

// [Recommended] Attach event listeners before launching HyperKYC SDK
HyperKyc.addEventListener(listener: (event) {
    // Handle the step_ended event
});

// [Recommended] Remove all event listeners after receiving the SDK response from HyperKYC SDK
await HyperKyc.removeAllEventListeners();

Advanced Use Case

You only need to implement the following setup if:

• You are targeting devices where:
  • "Don't Keep Activities" is enabled, or
  • Low-memory scenarios are likely

Without this setup, addEventListener() and removeAllEventListeners() may stop working when navigating between native and Flutter screens in the above mentioned scenarios (Don't Keep Activities enabled or Low Memory scenarios)

Setup for Reliable Event Handling (Advanced Use Cases)

In MainApplication.java

Java

@Override
public void onCreate() {
    super.onCreate();
    FlutterEngine flutterEngine = new FlutterEngine(this);
    flutterEngine.getDartExecutor().executeDartEntrypoint(
        DartExecutor.DartEntrypoint.createDefault()
    );
    FlutterEngineCache.getInstance().put("unique_engine_id", flutterEngine);
}

In MainActivity.java

Java

public class MainActivity extends FlutterActivity {
    @Override
    public FlutterEngine provideFlutterEngine(Context context) {
        return FlutterEngineCache.getInstance().get("unique_engine_id");
    }
}

If your application already implements a cached FlutterEngine, you can reuse it instead of creating a new instance.

FAQs

Question	Answer
Do I need this setup in all cases?	No. Only if your app uses Flutter + native Android and may run on devices with aggressive memory clearing.
What happens without this setup?	addEventListener() and similar callbacks may stop working after FlutterActivity gets destroyed.
We already use a cached FlutterEngine. Can we reuse it?	Yes, reuse the same engine name.
Is this needed for iOS?	No. iOS retains the Flutter engine across transitions by default.

Risk Assessment

Touchpoint	Description	Risk	Impact
App Startup Time	Slightly slower due to FlutterEngine init	Low	~30–80ms
Memory Usage	One FlutterEngine stays in memory	Low–Medium	~5–15MB
Plugin Conflicts	Sharing engine with other plugins	Very Low	N/A
Dev Effort	Minor changes to MainActivity and MainApplication	Low	~10–15 lines
If Setup is Skipped	Event listeners may stop working	High	100% event loss in edge cases

Summary Table

Requirement	Purpose	Optional?	iOS Impact?	Can Be Shared?
provideFlutterEngine() override	Keeps Flutter alive across native screens	Only if needed	Not needed	Yes
FlutterEngineCache.put(...)	Globally accessible engine	Only if needed	Not needed	Yes

Final Recommendation

• Recommended: Add the setup only if your app frequently navigates between Flutter and native Android screens and you anticipate low-memory situations or "Don't Keep Activities" to be relevant for your user base.
• If a cached engine already exists, reuse it to reduce duplication.
• No action required for iOS — FlutterEngine detachment isn't an issue there.

Web

Implement real-time event notifications in your web application using the HyperKYCModule.

JavaScript

HyperKYCModule.addEventListener((event) => {
    // Handle the step_ended event
})

HyperKYCModule.removeAllEventListeners()

Important Notes

• addEventListener() is not the same as DOM event listeners; it simply acts as a callback mechanism.
• removeAllEventListeners() clears any internal references — must be called at the end of the journey to avoid dangling references.
• Calling removeAllEventListeners inside an event listener does not cancel pending future events (in Android & Web platforms, yet).

Best Practices

• Attach event listeners before launching the HyperKYC SDK.
• Do not execute blocking code (e.g., synchronous heavy logic) inside the event listener callback.
  • Especially important for JavaScript-based environments which run on a single thread.
  • Use async/await, setTimeout, or background queues.
• Do not execute main-thread blocking code inside the event listener callback.
• Always call removeAllEventListeners() after SDK completion to avoid memory leaks.