🧭 Overview

The REL-ID SDK is built on a callback-driven architecture that promotes asynchronous, event-based handling of authentication and identity verification workflows.

Instead of returning values directly, the SDK triggers event callbacks that your application must implement. These events signal key moments in the authentication or KYC flow—such as when to collect input, show UI screens, or respond to verification results.

👤 User-Driven Callback Flows

User-driven callback flows in the REL-ID SDK are initiated directly by user actions in the app interface. These flows empower the app to react securely and dynamically to each step the user performs — from login attempts to biometric approvals.

🚦 How It Works

1. The user performs an action (e.g., taps a button, submits a form).
2. The app calls a corresponding SDK API (e.g., setPassword(), generateTOTP()).
3. The SDK performs internal operations like validation, encryption, or authentication.
4. The SDK emits an event callback once processing is complete.
5. The app listens for the event and executes UI updates, navigations, or further API calls.

🧪 Examples of User-Driven Events

🧠 Why These Matter

• Enable responsive and secure UX for authentication and transaction flows.
• Keep your application event-driven, avoiding direct synchronous API responses.
• Promote clean separation between UI logic and authentication flow handling.

📊 Example: Generate OTP Flow

This flow showcases how a simple user action results in an asynchronous, secure, and verifiable response via the REL-ID SDK.

sequenceDiagram
    participant 👆 App User
    participant 🧩 App
    participant ⚙️ REL-ID SDK
    participant 🔁 SDK Event Callback
    participant 🧠 App Listener

    👆 App User->>🧩 App: Tap "Generate TOTP"
    🧩 App->>⚙️ REL-ID SDK: Call generateTOTP()
    ⚙️ REL-ID SDK->>⚙️ REL-ID SDK: Validate session and generate OTP
    ⚙️ REL-ID SDK-->>🔁 SDK Event Callback: Emit onTOTPGenerated
    🔁 SDK Event Callback-->>🧠 App Listener: Trigger onTOTPGenerated handler
    🧠 App Listener-->>🧩 App: Display OTP to user

⚙️ SDK-Initiated Event Flows (No User Action Required)

Unlike user-driven flows, SDK-initiated events are triggered internally by the SDK without direct user interaction. These flows are essential for maintaining security, session state, and ongoing background operations. They ensure the app stays in sync with authentication states and threat detection logic.

🔁 When Do SDK-Initiated Events Occur?

🔧 Initialization & Setup

After calling initialize(), the SDK performs internal checks and emits events such as:

• onInitializeProgress: Indicates progress of initialization stages.
• onUserConsentThreats / onTerminateWithThreats: Triggered if mobile threats are detected.

🔐 Authentication & Consent

SDK may require confirmation or credentials:

• getPassword: When the SDK requires the user’s password.
• getDeviceToken: If the device push token is missing or invalid.
• getUserConsentForLDA: When biometric consent is needed.

🛡️ Threat Detection (MTD)

Triggered during or after initialization or runtime if threats are detected:

• onUserConsentThreats: Threats detected that require user confirmation.
• onTerminateWithThreats: Critical threats that require SDK to terminate session.

🧩 Credential Lifecycle Management

When SDK detects credentials can or must be updated:

• onCredentialsAvailableForUpdate: Prompts update.
• onUpdateCredentialResponse: Responds after update API is called.

⏳ Session State Management

Triggered when session timing or state needs to be handled:

• onSessionTimeout: Inactivity detected; session needs renewal or logout.
• onSessionExtensionResponse: SDK response after extending session via API.

✅ Why Are These Important?

• These flows ensure security is not compromised, even when a user is idle.
• They allow your app to proactively respond to changes in device trust, session validity, and authentication configuration.
• Most of these events require the app to either:
  • Prompt the user (e.g., for password or biometric)
  • Acknowledge a state (e.g., session timeout)
  • Call a follow-up API (e.g., setPassword() or takeActionOnThreats())