# Event Handlers for Real-Time Tracking The Engine Mobile SDK has real-time **Event Handlers** so you can track lead progression through the flow in real time (accessing lead data and notifications when leads progress through each step of the SDK, up to and including offer click). ## Implementation There are 11 Event Handlers you can implement that will be called as a user progresses through the SDK flow. \ Here is a screenshot of a sample code snippet of how you might implement the Mobile SDK into your app, with all 11 implemented (you can choose any or all of these to implement):
For your convenience, the same code snippet is pasted below as text, so you can copy-paste the bulk of the code. Please wrap the following snippet in a self closing \`<\` and \`/>\`, following the screenshot above (the text below omits the wrapping \`\\` so as not to trigger a CSS attack warning on this page) ``` EngineSdk bearer="{your_token}" primaryColor=”#11aa34” secondaryColor=”#444444” prefilledData={ any data you don't want to ask for again } clientTags={ ...optional Client Tags, please see previous Client Tag section } onInitialize={(storedLeadUuid, storedLeadData) => { your handler logic }} onCreate={(leadUuid, leadData, page, editingPage) => { your handler logic }} onUpdate={(leadUuid, leadData, page, editingPage) => { your handler logic }} onNavigate={(leadUuid, leadData, currentPage, nextPage, editingPage) => { your handler logic }} onSubmit={(leadUuid, leadData) => { your handler logic }} onRateTableRender={({ timestamp, rateTableUuid, loanOffers, specialOffers }) => { your handler logic }} onOfferClick={({ timestamp, leadUuid, offerUuid, financialInstitutionName, financialInstitutionUuid, productType, productSubType, loanAmount, apr, termLength, monthlyPayment }) => { your handler logic }} onErrorPageView={({ timestamp, leadUuid, leadData, toPage, editingPage? })} =? { your handler logic } onErrorPageRetryProps={({ timestamp, leadUuid, leadData, toPage, editingPage? })} =? { your handler logic } onExit={() => { your handler logic }} onError={({ code, severity, message, timestamp, sdkVersion, error, statusCode, additionalInfo }) => { your handler logic in the case of errors }} ``` `{ your handler logic }` is a placeholder for any function you actually want to execute when that handler is called. Channel Partners typically use Event Handlers to call their own endpoints when leads hit specific funnel stages, for tracking, retargeting, or other purposes. {% hint style="info" %} Each handler takes a structure object as an argument. Feel free to choose whichever arguments are useful to include in your handler logic, and omit the rest. {% endhint %} ## Descriptions Below are descriptions of the various event handlers and the data each one has access to when it fires. All event handlers have access to `timestamp`, which is a string representation of the moment (in UTC) the handler was called. 1. `onInitialize` is called when the SDK is initialized, after any data saved to local storage has been loaded. The saved data is supplied to the handler. `onInitialize` has access to the savedLeadUuid and savedLeadData, if the user's data was stored on the device from a previous session.
``` interface onInitializeProps { timestamp: string; storedLeadUuid: string | null; storedLeadData: PrefilledLeadData | null; } { /* storedLeadUuid and storedLeadData will be retried from device storage if the user previouly went through the app and the SDK stored those items to local storage */ } ``` \ All page names provided to the handlers, such as `page`, `nextPage`, and `editingPage`, will be in snake\_case format.

*Note: PrefilledLeadData here here and for the rest of this page indicates the data type, i.e. what fields/data formats might be present. This will include all fields set on the lead at that point, regardless of whether the data was initially prefilled, or later submitted by the user.


2. `onCreate` is called when the SDK first creates a lead with the Engine service. The data used to create the lead is supplied along with the current page and the page the user is editing, if any.
``` interface onCreateProps { timestamp: string; leadUuid: string | null; leadData: PrefilledLeadData; createPage: PageName; editingPage?: EditablePageName | null; } { /* leadUuid may be null in rare cases where the POST request to the Engine API fails - if it fails, the SDK will try again on the next step of the user flow */ } { /* editingPage is present/available if the lead most recently came from an "Edit Selected Field" page */ } ```
3. `onUpdate` is called whenever the SDK updates a lead with the Engine service. It receives the same data that the onCreate handler receives.
``` interface onUpdateProps { timestamp: string; leadUuid: string; leadData: PrefilledLeadData; updatePage: PageName; editingPage?: EditablePageName | null; } { /* editingPage is present/available if the lead most recently came from an "Edit Selected Field" page */ } ```
4. `onNavigate` is called whenever the user navigates to a new page. It receives the current lead data, the current page, the next page, and the page the user is editing if any.
``` interface onNavigateProps { timestamp: string; leadUuid: string | null; leadData: PrefilledLeadData; fromPage: PageName; toPage: PageName; editingPage?: EditablePageName | null; } { /* leadUuid may be null in rare cases where the POST request to the Engine API fails - if it fails, the SDK will try again on the next step of the user flow */ } { /* editingPage is present/available if the lead most recently came from an "Edit Selected Field" page */ } ```
5. `onSubmit` is called when the user submits their information to the Engine service and receives offers. The submitted data is supplied to the handler.
``` export interface onSubmitProps { timestamp: string; leadUuid: string | null; leadData: PrefilledLeadData; } ``` s 6. `onRateTableRender` is called when the user submits their information to the Engine service and receives offers. The submitted data is supplied to the handler.
``` interface onRateTableRenderProps { timestamp: string; rateTableUuid: string; loanOffers: object[]; specialOffers: object[]; } ``` 7. `onOfferClick` is called when the user submits their information to the Engine service and receives offers. The submitted data is supplied to the handler.
``` interface onOfferClickProps { timestamp: string; leadUuid: string; offerUuid: string; financialInstitutionName: string; financialInstitutionUuid: string; productType: string; productSubType: string; loanAmount: number | string; apr: number | string; termLength: number | string; monthlyPayment: number | string; } { /* loanAmount, apr, termLength, and monthlyPayment only exist on loanOffers. If the offer clicked comes from the specialOffers array, the string value for each of the 4 parameters will be "undefined for specialOffers". */ } ``` 8. `onErrorPageView` is called when the user is driven to the Error page ("Something Went Wrong"). This alerts you to when there may be an issue with Engine's servers, and when your users are not able to complete their application and submit for offers successfully.
``` interface onErrorPageViewProps { timestamp: string; leadUuid: string | null; leadData: PrefilledLeadData; fromPage: PageName; editingPage?: EditablePageName | null; } ``` 9. `onErrorPageRetry` is called when the user taps "Retry" on the error page. This informs you when the user attempts to retry on the previous page.
``` interface onErrorPageRetryProps { timestamp: string; leadUuid: string | null; leadData: PrefilledLeadData; toPage: PageName; editingPage?: EditablePageName | null; } ``` 10. `onExit` is called when the user attempts to exit the SDK flow. It is important to supply this handler in order to understand when the user exited the SDK and retarget the user to complete the flow.
``` interface onExitProps { timestamp: string } ``` 11. `OnError` is called when an error occurs during SDK operations. You may use this to log errors to your error tracking service or implement custom error handling logic.
``` interface EngineSdkError { code: ErrorCodes; severity: "warning" | "error"; message: string; timestamp: string; sdkVersion: string; error?: Error | unknown; statusCode?: number; additionalInfo?: Record; } enum ErrorCodes { // Configuration MISSING_CONFIG = "MISSING_CONFIG", // Storage DATA_READ_ERROR = "DATA_READ_ERROR", DATA_WRITE_ERROR = "DATA_WRITE_ERROR", // Flow FLOW_ERROR = "FLOW_ERROR", // UI UI_CRASH = "UI_CRASH", // Network NETWORK_REQUEST_ERROR = "NETWORK_REQUEST_ERROR", NETWORK_SERVER_ERROR = "NETWORK_SERVER_ERROR", NETWORK_OTHER_ERROR = "NETWORK_OTHER_ERROR", NETWORK_TIMEOUT = "NETWORK_TIMEOUT", } ``` \ `additionalInfo` contains additional information that is relevant to the error that occured. Some examples of what information it could contain:\ • `leadData` (Record\) - The lead data object at the time of error\ • `leadUuid` (string) - The lead UUID • `page` (string) - The current page where the error occurred • `productTypes` (string) - Product types being processed • `clientTags` (Record\ - Client tags • `rateTableUuid` (string) - Rate table UUID {% hint style="info" %} All page names provided to the handlers, such as `page`, `nextPage`, and `editingPage`, will be in snake\_case format. {% endhint %} ## Example Event Handler Calls ### Scenario 1: No user info is prefilled #### 1. `onInitialize` When the user first enters the SDK and reaches the splash page:
`onInitialize` fires with: `onInitialize({ timestamp, storedLeadUuid,storedLeadData })` {% hint style="info" %} \*Note: unless a lead has already begun, exited, and re-entered the SDK, `storedLeadUuid` and `storedLeadData` will be `null`. If the user re-enters the SDK after a previous session where a leadUuid was created and leadData was stored in local storage on their device, the handler will fire with those values. {% endhint %} #### 2. `onNavigate` and `onCreate` When the user navigates to the following screen (which differs depending how much user info is prefilled), `onNavigate` and `onCreate` will fire. For example, if no info is prefilled, the user will navigate away from the splash screen, where `onNavigate` fires: `onNavigate({ timestamp, leadUuid, leadData, currentPage, nextPage })` Values will be as follows: * **leadUuid**: null (unless the user returned from a previous session, where the `leadUuid` was stored in local storage) * **leadData**: any user info prefilled, e.g. `{firstName: "Bob", lastName: "Dylan", email: "bobdylan@tambourineman.com", {...other prefilled data, if provided}}` * **currentPage**: `splash` * **nextPage**: `loan_amount` `onCreate({ timestamp, leadUuid, leadData, createPage })` Values will be as follows: * **leadUuid**: `{UUID string in UUID Format}` ([Info on UUID formats](https://www.uuidtools.com/what-is-uuid)) * **leadData**: `{firstName: "Bob", lastName: "Dylan", email: "bobdylan@tambourineman.com", ipAddress: "x.x.x.x"}` * **createPage**: `splash` The user will then navigate into the `loan_amount` screen (again, assuming `loanAmount` is not prefilled):
When the user presses `Continue`, `onNavigate` will fire: `onNavigate({ timestamp, leadUuid, leadData, currentPage, nextPage })` Values will be as follows: * **leadUuid**: {the lead's UUID as a string} * **leadData**: `{"firstName":"Bob","lastName":"Dylan","email":"bobdylan@tambourineman.com","ipAddress":"x.x.x.x"}` * **currentPage**: `loan_amount` * **nextPage**: `loan_purpose` The lead is also updated at this point, so `onUpdate` fires: `onUpdate({ timestamp, leadUuid, leadData, page })` Values will be as follows: * **leadUuid**: {the lead's UUID as a string} * **leadData**: `{"firstName":"Bob","lastName":"Dylan","email":"bobdylan@tambourineman.com","ipAddress":"x.x.x.x","loanAmount":5000}` * **page**: `loan_amount` #### 3. Subsequent `onNavigate` and `onUpdate` calls `onNavigate` and `onUpdate` will fire at each user navigation, with the `leadData` object growing as fields are updated onto the lead. `currentPage` / `nextPage` values are as follows: * `loan_purpose` * `date_of_birth` * `address` * `phone` * `credit_rating` * `property_status` * `education_level` * `employment_status` * `annual_income` * `ssn` * `confirm_details` * `offers` #### 4. `onSubmit` When the user presses `See my offers` on the confirm\_details screen:
The Event Handlers that fire are: `onSubmit({ timestamp, leadUuid, leadData })` `onNavigate({ timestamp, leadUuid, leadData, currentPage, nextPage })` `onUpdate({ timestamp, leadUuid, leadData, page })` * `currentPage` and `page` here will = `confirm_details` * `nextPage` will = `offers` #### 5. `onRateTableRender` When the user lands on the offer page, `onRateTableRender` fires with a `rateTableUuid`, a `leadUuid`, and two arrays: `loanOffers` and `specialOffers` **rateTableUuid** This is associated with that application from that lead. Useful to identify and map with the `leadUuid`. **loanOffers** This is an array of objects. Each object will have the following attributes: * offerUuid * financialInstitutionName * financialInstitutionUuid * productType * productSubType * loanAmount * apr * termLength * monthlyPayment **specialOffers** This is an array of objects. Each object has the following attributes: * offerUuid * name * financialInstitutionName * financialInstitutionUuid * productSubType 6. `onOfferClick` onOfferClick fires when a lead clicks on an offer from the offer table. The `financialInstitutionName` , `productType`, and `productSubType` will indicate whether the user clicked a loan offer or special offer. ### Scenario 2: Some (but not all) user info is prefilled When some user info is prefilled, the first `onNavigate` fire away from the splash screen will have: * `currentPage=splash` * `nextPage={the first page in the flow that was not prefilled}` The rest of the flow will be the same as Scenario 1 above. ### Scenario 3: All user info is prefilled When some user info is prefilled, the first `onNavigate` fire on the first navigation away from the splash screen will have: * `currentPage=splash` * `nextPage=confirm_details` `onCreate` will also fire at this point, since this is when the `leadUuid` is created by posting the lead to the Engine API. The user will submit by pressing `See my offers`, and `onSubmit`, `onNavigate`, and `onUpdate` will function the same as in Scenario 1. {% hint style="info" %} Note: `onUpdate` will still fire when the user presses `See my offers` on the confirm\_details screen because this is when legal consents are accepted / set to the lead object. {% endhint %} ### `onExit` - wherever a user exits the flow `onExit` will fire whenever a user leaves the Engine Mobile SDK, regardless of where in the flow the user left the flow. You can use this to infer whether a lead completed / submitted the loan form, depending what other Event Handler callbacks have fired (assuming you set those up as well). More details in the next section: ### `onError` - when an error occur For example, if the SDK API call to synchronize a lead fails, the `onError` callback is invoked with these props ``` { “code”: “NETWORK_REQUEST_ERROR”, “severity”: “error”, “message”: “Failed to synchronize lead data”, “timestamp”: “Mon, 10 Nov 2025 05:46:47 GMT, “sdkVersion”: “1.5.7”, “error”: Error, “statusCode”: 401, “additionalInfo”: { “leadData”: { “firstName”: “Bob”, “lastName”: “Smith”, “email”: “test@email.com”, } } } ``` ## How to use Event Handlers for Tracking Event handlers can be used to track how far a lead progressed in the flow, i.e. if your Event Handler callbacks fire an `onExit` but do not fire an `onSubmit`, and/or if your `onNavigate` handlers never fire with `nextPage=offers`, you can infer that the lead exited the flow before submitting to see offers. This allows you to retarget the lead accordingly to entice them to complete the form and see their offers. Similarly, if your Event Handler fires indicate the lead submitted the form (i.e. `onSubmit` fires and/or `onNavigate` fires with `nextPage=offers`, but you do not receive reporting/notifications that the lead converted on a loan or other product, you may retarget the lead to entice them to re-enter the SDK, immediately see their offers (since on re-entry the user will be directed straight to the `offers` screen, and ideally convert on an available offer. See [Reporting Options for Channel Partners](https://engine.tech/developer-center/loans-savings-second-look-marketplace/reporting-options-for-channel-partners) for your available options for receiving conversion reporting from Engine by MoneyLion.