Initialize the Ditto ID SDK

⚙️ Overview: Ditto ID SDK Initialization

The Ditto ID SDK initialization is the first and essential step before any authentication or activation flow. It sets up a secure environment, validates device integrity, and connects to the Ditto ID backend infrastructure.

🧩 Purpose

• Establish a secure communication session with the Ditto ID server.
• Perform local and remote security checks (e.g., emulator detection, root/jailbreak status).
• Load configuration and prepare the SDK for further operations like login or activation.

🔄 Initialization Sequence

1. App Calls initialize()

   • The SDK initialization begins when the app explicitly calls the initialize() method.

2. Progress Feedback via onInitializeProgress()

   • This callback is invoked multiple times to notify the app of the current progress (e.g., STARTED, IN_PROGRESS, COMPLETED, INIT_FAILED).

3. Threat Detection

   • The SDK performs both local and server-side threat evaluations.
   • If non-terminating threats are detected:
     • onUserConsentThreats() is triggered, and the app must respond via takeActionOnThreats() to continue or terminate.
   • If terminating threats are found:
     • The SDK emits onTerminateWithThreats() and halts further execution.

4. Error Handling viaonInitializeError()

   • If any issue arises during setup (e.g., misconfiguration, network failure), onInitializeError this event is emitted with error details.

5. Successful Completion

   • Upon passing all checks, onInitialized() is emitted, confirming that the SDK is now ready for user-related operations.

6. Post-Initialization:getUser()

   • The SDK automatically calls getUser() to indicate it’s ready to accept a user ID for login or activation.
     • The app must respond using setUser() .

🧭 Initialization Flow Diagram

flowchart TD
    A[Start: App calls initialize] --> B[SDK emits onInitializeProgress: STARTED]
    B --> C[Perform threat checks and validations]
    C --> D[SDK emits onInitializeProgress: IN_PROGRESS]

    D --> E{Are threats detected?}
    E -- Yes --> F[Threats detected]

    F --> G{Are threats terminating?}
    G -- Yes --> H[SDK emits onTerminateWithThreats]
    H --> Z[End: Initialization Aborted]
    G -- No --> I[SDK emits onUserConsentThreats]
    I --> J{App calls takeActionOnThreats to proceed?}
    J -- No --> Z
    J -- Yes --> K[Continue initialization]

    E -- No --> K
    K --> L{Any initialization error?}
    L -- Yes --> M[SDK emits onInitializeError]
    M --> Z
    L -- No --> N[SDK emits onInitialized]
    N --> O[SDK triggers getUser]
    O --> P[App should call setUser]
    P --> Q[End: Ready for authentication]

✅ Best Practices

• Always ensure the SDK is fully initialized before triggering login or activation flows.
• Properly handle onUserConsentThreats() to provide a seamless UX in case of non-critical threats.
• Log or report errors from onInitializeError() for debugging and support.