# Flutter Callbacks Events for Tracking

The EngineSDK widget exposes optional event callback props that notify your app when key moments occur during the user's personal loan journey. All callbacks receive a strongly-typed event object containing a timestamp (ISO 8601 UTC) and event-specific fields.

## Usage

All callbacks are optional. If a callback is not provided, the SDK will still log the event to the debug console in development mode.

Pass any combination of callbacks when constructing the EngineSDK widget:

```dart
EngineSDK(
channel: 'your_channel',
zone: 'your_zone',
experience: 'search',
bearerToken: '{your_token}',
onInitialize: (event) {
print('SDK initialized at ${event.timestamp}');
},
onCreate: (event) {
print('Lead created: ${event.leadUuid}');
},
onSubmit: (event) {
print('Lead submitted: ${event.leadUuid}');
},
onOfferClick: (event) {
print('Offer clicked: ${event.offerUuid}');
print('Lender: ${event.financialInstitutionName}');
print('APR: ${event.apr}');
},
onExit: (event) {
print('User exited at ${event.timestamp}');
// Navigate the user back or perform cleanup
},
// ...other callbacks
)
```

## Available Events & Properties

| Callback              | Event Type           | Trigger                          |
| --------------------- | -------------------- | -------------------------------- |
| **onInitialize**      | InitializeEvent      | SDK finished loading             |
| **onCreate**          | CreateEvent          | New lead created                 |
| **onUpdate**          | UpdateEvent          | Lead data updated                |
| **onNavigate**        | NavigateEvent        | Page navigation                  |
| **onSubmit**          | SubmitEvent          | Lead form submitted              |
| **onRateTableRender** | RateTableRenderEvent | Rate table displayed with offers |
| **onOfferClick**      | OfferClickEvent      | User clicked a loan offer        |
| **onErrorPageView**   | ErrorPageViewEvent   | Error page displayed in flow     |
| **onErrorPageRetry**  | ErrorPageRetryEvent  | User retried from error page     |
| **onExit**            | ExitEvent            | User exited the SDK              |
| **onEmbedError**      | EmbedErrorEvent      | Web embed failed to load         |
| **onEmbedErrorRetry** | EmbedErrorRetryEvent | User retried after embed failure |

### onInitialize

Fired when the SDK finishes loading the embedded experience.

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| **timestamp** | String | ISO 8601 UTC timestamp of when the event was emitted |

### onCreate

Fired when a new lead is created in the system.

| Field           | Type   | Description                                          |
| --------------- | ------ | ---------------------------------------------------- |
| **timestamp**   | String | ISO 8601 UTC timestamp of when the event was emitted |
| **leadUuid**    | String | Unique identifier for the newly created lead         |
| **createPage**  | String | The page where the lead was created                  |
| **editingPage** | String | The page that the user is currently editing          |

### onUpdate

| Field           | Type   | Description                                          |
| --------------- | ------ | ---------------------------------------------------- |
| **timestamp**   | String | ISO 8601 UTC timestamp of when the event was emitted |
| **leadUuid**    | String | Unique identifier for the lead                       |
| **createPage**  | String | The page where the updated occurred                  |
| **editingPage** | String | The page that the user is currently editing          |

### onNavigate

Fired on page navigation within the flow.

| Field           | Type   | Description                                          |
| --------------- | ------ | ---------------------------------------------------- |
| **timestamp**   | String | ISO 8601 UTC timestamp of when the event was emitted |
| **leadUuid**    | String | Unique identifier for the lead                       |
| **fromPage**    | String | The page the user is navigating away from            |
| **toPage**      | String | The page the user is navigating to                   |
| **editingPage** | String | The page that the user is currently editing          |

### onSubmit

Fired when the lead form is submitted for offer matching.

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| **timestamp** | String | ISO 8601 UTC timestamp of when the event was emitted |
| **leadUuid**  | String | Unique identifier for the submitted lead             |

### onRateTableRender

Fired when the rate table is rendered with loan offers.

| Field             | Type   | Description                                          |
| ----------------- | ------ | ---------------------------------------------------- |
| **timestamp**     | String | ISO 8601 UTC timestamp of when the event was emitted |
| **rateTableUuid** | String | Unique identifier for the Engine rate table          |
| **loanOffers**    | List   | Array of loan offers returned for the lead           |
| **specialOffers** | List   | Array of special offers returned for the lead        |

### onOfferClick

Fired when the user clicks on a loan offer.

<table><thead><tr><th>Field</th><th width="221.1666259765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>timestamp</strong></td><td>String</td><td>ISO 8601 UTC timestamp of when the event was emitted</td></tr><tr><td><strong>leadUuid</strong></td><td>String</td><td>Unique identifier for the lead</td></tr><tr><td><strong>offerUuid</strong></td><td>String</td><td>Unique identifier for the clicked offer</td></tr><tr><td><strong>financialInstitutionName</strong></td><td>String</td><td>Name of the lending institution</td></tr><tr><td><strong>financialInstitutionUuid</strong></td><td>String</td><td>Unique identifier for the lending institution</td></tr><tr><td><strong>productType</strong></td><td>String</td><td>Type of product (e.g. "loan")</td></tr><tr><td><strong>productSubType</strong></td><td>String</td><td>Sub-type of product</td></tr><tr><td><strong>loanAmount</strong></td><td></td><td>Loan amount offered</td></tr><tr><td><strong>apr</strong></td><td></td><td>Annual percentage rate</td></tr><tr><td><strong>termLength</strong></td><td></td><td>Length of the loan term</td></tr><tr><td><strong>monthlyPayment</strong></td><td></td><td>Estimated monthly payment</td></tr></tbody></table>

### onErrorPageView

Fired when the error page is displayed within the embedded flow.

| Field           | Type   | Description                                          |
| --------------- | ------ | ---------------------------------------------------- |
| **timestamp**   | String | ISO 8601 UTC timestamp of when the event was emitted |
| **leadUuid**    | String | Unique identifier for the lead                       |
| **fromPage**    | String | The page the user was on before the error            |
| **editingPage** | String | The page that the user was editing                   |

### onErrorPageRetry

Fired when the user taps "Retry" on the error page within the embedded flow.

| Field           | Type   | Description                                          |
| --------------- | ------ | ---------------------------------------------------- |
| **timestamp**   | String | ISO 8601 UTC timestamp of when the event was emitted |
| **leadUuid**    | String | Unique identifier for the lead                       |
| **toPage**      | String | The page the user is retrying to navigate to         |
| **editingPage** | String | The page that the user was editing                   |

### onExit

Fired when the user exits the SDK flow (e.g., taps the close button).

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| **timestamp** | String | ISO 8601 UTC timestamp of when the event was emitted |

### onEmbedError

Fired when the embedded web view fails to load (network error, HTTP 4xx/5xx, etc.).

| Field            | Type   | Description                                          |
| ---------------- | ------ | ---------------------------------------------------- |
| **timestamp**    | String | ISO 8601 UTC timestamp of when the event was emitted |
| **errorMessage** | String | Description of the error that occurred               |

### onEmbedErrorRetry

Fired when the user taps "Retry" after an embed load failure.

| Field            | Type   | Description                                                |
| ---------------- | ------ | ---------------------------------------------------------- |
| **timestamp**    | String | ISO 8601 UTC timestamp of when the event was emitted       |
| **errorMessage** | String | Description of the original error that triggered the retry |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://even-financial.gitbook.io/developer-center/embeddable-integrations/mobile-sdks/flutter/flutter-callbacks-events-for-tracking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.