Real-time Events SOP

This SOP helps the team perform Level 0 debugging when clients report issues related to SDK event listeners (e.g., "I didn't receive step_ended events"). Follow these steps to triage issues before escalating to Engineering.

info

As of May 21, 2025, this feature is available only in Web HyperKYC, native Android HyperKYC, native iOS HyperKYC, Flutter HyperKYC, and React Native HyperKYC. LinkKYC support will be considered if there's a confirmed requirement.

1. Gather basic information from the client

Before analysis, ask the client for:

Parameter	Description
Platform	Android / iOS / Flutter / React Native / Web (WebApp / WebView).
SDK version	The exact version of HyperKYC SDK used.
App ID	Client's appId.
Transaction ID	Essential for analytics debugging.
Workflow ID	Workflow used.
Reported issue	E.g., "Didn't receive step_ended event after upload module".
Code snippet	Code used for addEventListener, launching of the SDK, and removeAllEventListeners.
Logs or screenshots	Optional but helpful for correlating with analytics.

2. Step-by-step L0 debugging (for event not received)

Step 1 — validate SDK version compatibility

• Confirm the client's SDK version supports event listeners.
• If the version is too old, suggest upgrading to the latest SDK.

Step 2 — review client code

Ask for and review how the client attaches and removes listeners. Check:

• Listener is attached before SDK launch.
• No blocking code (e.g., alert, confirm, heavy sync code) inside the listener.
• Listener is not removed too early (before SDK completes).
• Client uses removeAllEventListeners() only at the right time (post-closure of the SDK).

Step 3 — confirm stepId configuration

• If the client expects a step_ended event, ensure the stepId has been configured properly in the workflow config.

Step 4 — check analytics in Metabase

Refer to the Transaction Analytics Dashboard in Metabase and look for the Step Ended Event Triggered event.

TODO

Screenshots: Step Ended Event Triggered analytics entry and Event Trigger Failed analytics entry. (Pending migration from Notion.)

Raw Metabase query (reference)

For Mobile SDK:

SELECT *
FROM "public"."mobile_sdk_analytics"
WHERE "public"."mobile_sdk_analytics"."common_app_id" = 'v9rb5g'
  AND "public"."mobile_sdk_analytics"."common_transaction_id" = 'transaction_xyz'
  AND "public"."mobile_sdk_analytics"."event_name" = 'Step Ended Event Triggered'
ORDER BY created_at DESC;

For Web SDK:

SELECT *
FROM "public"."web_sdk_analytics"
WHERE "public"."web_sdk_analytics"."common_app_id" = 'v9rb5g'
  AND "public"."web_sdk_analytics"."common_transaction_id" = 'transaction_xyz'
  AND "public"."web_sdk_analytics"."event_name" = 'Step Ended Event Triggered'
ORDER BY created_at DESC;

What to check:

• Is Step Ended Event Triggered event recorded in the analytics?

  • ✅ Yes → SDK triggered it. Issue is client-side (listener not attached, or code inside the listener has issues).
  • ❌ No → SDK did not trigger it. Issue may be in configuration (stepId), workflow, or SDK behaviour — report to Engineering.

• Is Event Trigger Failed event recorded in the analytics?

  • ✅ Yes
    • Flutter HyperKYC SDK used?
      • ✅ Yes → Likely caused by low-memory or "Don't Keep Activities" enabled. Request the client to follow the Flutter advanced-use-case steps to ensure persistent FlutterEngine setup.
      • ❌ No → SDK triggered it, but the issue is client-side (listener not attached, or code in the listener has issues).
  • ❌ No → SDK did not trigger it. Issue may be in configuration (stepId), workflow, or SDK behaviour — report to Engineering.

3. Possible client mistakes

• Not calling addEventListener before launching the SDK.
• Calling removeAllEventListeners too early.
• Using blocking functions (alerts, sync loops) inside the listener.
• Using an old SDK version without support for event listeners.
• stepId misconfigured in the workflow config.

4. Best practices for clients

• Always keep the SDK up to date.
• Ensure workflow steps have consistent and correct stepId configuration.

5. FAQs

Question	Answer
Can I use multiple listeners?	Yes, but use removeAllEventListeners after the session to avoid leaks.
Can this be used in Flutter or RN?	Yes. Logic is identical, exposed via platform channels.
What's the difference between module_ended and step_ended?	module_ended is triggered per module and only fires the analytics event. step_ended is triggered when an entire step is completed — both analytics event and client event listeners fire. Depending on workflow configuration, a step could be a single module or a group of modules.
What if analytics shows the event but the client didn't receive it?	If Event Trigger Failed event is also observed, follow step 4. Otherwise, the issue is most likely in listener attachment (timing/code).
What if analytics shows no event at all?	May be a misconfigured workflow or stepId — report to Engineering with details.

6. When to report to Engineering (L1)

Report only if:

• SDK version is valid and supports event listeners.
• Listener is properly attached before SDK launch.
• removeAllEventListeners is not called early.
• Analytics table has no record of the expected event.
• Client confirms that the stepId was correctly configured.

When escalating, provide:

• App ID + Transaction ID
• SDK version + Platform
• Workflow ID + Step name + Module involved
• Code snippet used to attach the listener
• Metabase query result (or screenshot)