Event Handlers for Real-Time Tracking in the Engine Mobile SDK

Instructions for using event handlers in the Engine Mobile SDK

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 steps up to and including receiving offers on a Rate Table).

There are 6 Event Handlers you can implement that will be called as a user progresses through the SDK flow. Here is how you can implement them into your SDK implementation (you can choose any or all of these to implement):

<EngineSdk
    {...other attributes}
    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 }}
    onExit={() => { your handler logic }}
/>

{ 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.

Here are descriptions of the handlers and the data each one has access to when it fires:

  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.

    onInitialize?: (
        storedLeadUuid: string | null,
        storedLeadData: PrefilledLeadData | null
    ) => void;
    
    { /* 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.

    onCreate?: (
        leadUuid: string | null,
        leadData: PrefilledLeadData,
        page: PageName,
        editingPage?: EditablePageName | null
    ) => void;
    
    { /* 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.

    onUpdate?: (
        leadUuid: string,
        leadData: PrefilledLeadData,
        page: PageName,
        editingPage?: EditablePageName | null
    ) => void;
    { /* 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.

    onNavigate?: (
        leadUuid: string | null,
        leadData: PrefilledLeadData,
        page: PageName,
        nextPage: PageName,
        editPage?: EditablePageName | null
    ) => void;
    
    { /* leadUuid may be null in rare cases where the POST request to the Engine API fails on the first user navigation - 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.

    onSubmit?: (
        leadUuid: string | null, 
        leadData: PrefilledLeadData
    ) => void;

  6. 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.

    onExit?: () => void;
    { /* onExit does not take any arguments */}

All page names provided to the handlers, such as page, nextPage, and editingPage, will be in snake_case format.

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(storedLeadUuid,storedLeadData)

*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.

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(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: "[email protected]", {...other prefilled data, if provided}}

  • currentPage: splash

  • nextPage: loan_amount

onCreate(leadUuid, leadData, createPage)

Values will be as follows:

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(leadUuid, leadData, currentPage, nextPage)

Values will be as follows:

  • leadUuid: {the lead's UUID as a string}

  • leadData: {"firstName":"Bob","lastName":"Dylan","email":"[email protected]","ipAddress":"x.x.x.x"}

  • currentPage: loan_amount

  • nextPage: loan_purpose

The lead is also updated at this point, so onUpdate fires:

onUpdate(leadUuid, leadData, page)

Values will be as follows:

  • leadUuid: {the lead's UUID as a string}

  • leadData: {"firstName":"Bob","lastName":"Dylan","email":"[email protected]","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(leadUuid, leadData)

onNavigate(leadUuid, leadData, currentPage, nextPage)

onUpdate(leadUuid, leadData, page)

  • currentPage and page here will = confirm_details

  • nextPage will = offers

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.

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.

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:

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 for your available options for receiving conversion reporting from Engine by MoneyLion.

Last updated