Skip to main content

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

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

These events can be integrated with your CRM systems, analytics tools, 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.

Prerequisites

Before integrating real-time events, ensure your SDK meets the following version requirements:

PlatformRequirement
Web SDKVersion ≥ 10.0.0
Mobile SDKs (Android, iOS, React Native, Flutter)Webcore must be enabled with version ≥ 10.0.0. Contact HyperVerge support to confirm the minimum native SDK version for your platform.

Event Details

When is it triggered?

Events are triggered when a user reaches a milestone in their journey, such as starting or completing a step or substep with event triggers enabled.

Supported Events

Real-time event notifications emit the following six events:

Event NameTriggered When
workflow_startedThe user begins the onboarding workflow
step_startedThe user begins a step
substep_startedThe user begins a substep
step_completedThe user completes a step
substep_completedThe user completes a substep
workflow_completedThe user completes the onboarding workflow

Event Schema

All events follow this generic schema:

{
"schemaVersion": "2.0.0",
"eventName": "step_completed",
"timestamp": "2025-04-21T10:35:40.321Z",
"sdkVersion": "0.45.0",
"transactionId": "transactionId_1234",
"workflowId": "onboarding",
"workflowVersion": "1.2.3",
"appId": "abcdef",
"stepId": "digilocker",
"subStepId": "digilocker_instructions_form",
"properties": {}
}

Field Descriptions

FieldTypeDescription
schemaVersionstringThe schema version. Use this to distinguish v2 events from v1
eventNamestringThe name of the event
timestampstringThe UTC time of the event. Important for sequencing
sdkVersionstringThe version of the SDK that sent the event
transactionIdstringThe unique identifier of the application
workflowIdstringThe unique identifier of the workflow
workflowVersionstringThe version of the workflow configuration
appIdstringThe appId mapped to the application
stepIdstringThe identifier of the step. Empty for workflow-level events
subStepIdstringThe identifier of the substep. Present only for substep-related events, empty otherwise
propertiesJSON objectAdditional attributes configured via the workflow builder, forwarded in all events

Event Payload Examples

{
"eventName": "workflow_started",
"stepId": "",
"subStepId": "",
"properties": {
"key": "value"
}
}
{
"eventName": "step_completed",
"stepId": "step_A",
"subStepId": "",
"properties": {
"key": "value"
}
}

SDK Integration

Use the SDK-provided addEventListener API to subscribe to real-time milestone events. 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
HyperKyc.addEventListener(jsonObject -> {
// Handle real-time events
// ....
return Unit.INSTANCE;
});

HyperKyc.removeAllEventListeners();

iOS

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

Swift
HyperKyc.addEventListener { event in
// Handle real-time events
}

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 real-time events
});

// [Recommended] Remove all event listeners after receiving the SDK response
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 real-time events
});

// [Recommended] Remove all event listeners after receiving the SDK response
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.

Setup for Reliable Event Handling

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

QuestionAnswer
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

TouchpointDescriptionRiskImpact
App Startup TimeSlightly slower due to FlutterEngine initLow~30–80ms
Memory UsageOne FlutterEngine stays in memoryLow–Medium~5–15MB
Plugin ConflictsSharing engine with other pluginsVery LowN/A
Dev EffortMinor changes to MainActivity and MainApplicationLow~10–15 lines
If Setup is SkippedEvent listeners may stop workingHigh100% event loss in edge cases

Summary Table

RequirementPurposeOptional?iOS Impact?Can Be Shared?
provideFlutterEngine() overrideKeeps Flutter alive across native screensOnly if neededNot neededYes
FlutterEngineCache.put(...)Globally accessible engineOnly if neededNot neededYes

Recommendation

  • Add this 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 real-time events
})

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.
Was this helpful?
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: