Personal Loans

How to get started with your Personal Loans Mobile React Native SDK integration

Welcome to Engine by MoneyLion’s Personal Loans React Native SDK Integration Guide. This guide covers software requirements, installing and initializing the SDK, and leveraging its customizable features to optimize the user journey. Finally, there are sample screenshots of how the SDK looks (which may vary depending on your color customizations).

Screenshot of Engine Mobile SDK: Splash Page

Setup Instructions

Step 1: Request an API token

Before you can use the Engine SDK, you’ll need to request an API token from your Partner Manager. This is used to authenticate with the Engine API and provides access to different financial institutions. You may want to use multiple API tokens depending on how many entry points your app has into the SDK.

Step 2: Confirm Software Requirements

Requirements:

• React Native

Package Size:

• SDK Bundle Size: 1.27MB Unpacked

Step 3: Install the SDK

Install the SDK from npm using the command using your package manager, e.g.

• npm install –save @moneylion/react-native-engine-sdk

• yarn add @moneylion/react-native-engine-sdk

Step 4: Initialize the SDK

In your app, you’ll need to initialize the SDK by rendering its React component. As props, you’ll need to pass your provided bearer token (Step 1 - request a token from your Partner Manager), the Engine endpoint you’re connecting to, and any information you already have about the user if you don’t want the user to enter it again.

There are certain fields that must be provided to the Engine SDK component on initialization:

• API endpoint

• Bearer token

• Required prefilled data (the Engine SDK does not ask for these 3 fields):

  • First name

  • Last name

  • Email address

• Lead IP Address is captured automatically by the SDK from the user's device; you do not need to pass this field in your integration.

Here is a sample code snippet of how you might implement the Mobile SDK into your app:

<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 following Client Tag section }
    { ...optional event handlers, please see Event Handler section below 
    />

There are certain fields that must be provided to the Engine SDK component on initialization:

• Bearer token

• Required prefilled data (the Engine SDK does not ask for these 3 fields):

• First name

• Last name

• Email address

  There are certain fields that must be provided to the Engine SDK component on initialization:

  • Bearer token

  • Required prefilled data (the Engine SDK does not ask for these 3 fields):

  • First name

  • Last name

  • Email address

User Experience & Demo

Note: any screen where that info is prefilled will be skipped.

Engine Mobile SDK Screen 1: Splash Page

Engine Mobile SDK Screen 2: Loan Amount

Engine Mobile SDK Screen 3: Loan Purpose

Engine Mobile SDK Screen 4: Date of Birth

Engine Mobile SDK Screen 5: Address

Engine Mobile SDK Screen 6: Phone Number

Engine Mobile SDK Screen 7: Credit Rating

Engine Mobile SDK Screen 8: Property Status

Engine Mobile SDK Screen 9: Highest Level of Education

Engine Mobile SDK Screen 10: Employment Status

Engine Mobile SDK Screen 11: Annual Income

Engine Mobile SDK Screen 13: SSN

Engine Mobile SDK Screen 13: Confirm Details

Engine Mobile SDK Screen 14: Offer Wall

Adding Client Tags for Reporting

The Engine Mobile SDK supports adding your unique Client Tags to track performance of specific campaigns or users. All Client Tag data is attributed to the lead level.

Client Tags can be added by including a clientTags attribute at the top level of the request body, where the value is an array of strings. We strongly recommend only including one element per array for ease of reporting/attribution - if you want two separate tags, include the second tag under a different key. There is no limit to the number of keys in the clientTags object.

Example

Here is a sample code snippet of how you might implement the Mobile SDK into your app, with sample clientTags appended:

<EngineSdk
    bearer="{your_token}"
    primaryColor=”#11aa34”
    secondaryColor=”#444444”
    prefilledData={ any data you don't want to ask for again }
    "clientTags": {
        "clientId": ["client1"],
        "trafficsource": ["email"],
        "campaignId": ["campaign1"]
    }
    { ...optional Event Handlers, please see Event Handler section }
/>

See our GET Lead Client Tags endpoint for information on attributing lead analytics to your own client tags, if you decide to hit our Analytics API for reporting.

Supported Client Tag Keys

If you plan for the Engine team to set up reporting (i.e. you do not plan to hit our Analytics API), these are the only keys that are currently fully supported. If a different key is needed, please reach out to your partner manager - we may be able to accommodate, but adding nonstandard keys will increase the time it takes Engine to report Client Tag values back to you, and is therefore not recommended.

• agentId

• campaignId

• clientId

• deviceid

• medium

• sourceId

• subid

• subid1

• subid2

• subid3

• target

• trafficsource

• userid

Prefilling Lead Data

The prefilledData object should be structured with any fields you want the user not to have to answer themselves, if you already have that info available. Here is an example of prefilledData as a Javascript Object. You may prefill as many of these fields as desired; the only 3 required are firstName, lastName, and email.

{
    "firstName": "Bob", // required
    "lastName": "Dylan", // required
    "email": "[email protected]", // required
    "loanAmount": 7500, 
          // you can instead use "defaultSliderLoanAmount", if you want to suggest a default loan amount but still allow the user to edit it.
          // if "loanAmount" is prefilled, "defaultSliderLoanAmount" will be ignored
    "purpose": "credit_card_refi",
    "dateOfBirth": new Date("1990-01-01"),
    "address": {
      "street": "1600 Pennsylvania Avenue",
      "city": "Washington",
      "state": "DC",
      "zip": "20500"
    },
    "primaryPhone": "2325624852",
    "creditRating": "good",
    "propertyStatus": "own_with_mortgage",
    "educationLevel": "associate",
    "employmentStatus": "employed",
    "annualIncome": "20000",
    "hasDirectDeposit": false,
    "ssn": "512-54-7862",
    "bankRoutingNumber": "123456789",
    "bankAccountNumber": "55555555555"
}

Prefilled values cannot be edited by the user on the final confirm-details screen (before submitting the form). If the user's info is incorrect (e.g. Address is incorrect outdated), the user should edit the info in your app directly.

Example React Native Implementation

Here is a sample code snippet of how you might implement the Mobile SDK into your app, with all prefilledData fields populated:

<EngineSdk
    bearer="{your_token}"
    primaryColor=”#11aa34”
    secondaryColor=”#444444”
    prefilledData={
              "firstName": "Bob", // required
              "lastName": "Dylan", // required
              "email": "[email protected]", // required
              "loanAmount": 7500, 
                    // you can instead use "defaultSliderLoanAmount", if you want to suggest a default loan amount but still allow the user to edit it.
                    // if "loanAmount" is prefilled, "defaultSliderLoanAmount" will be ignored
              "purpose": "credit_card_refi",
              "dateOfBirth": new Date("1990-01-01"),
              "address": {
                "street": "1600 Pennsylvania Avenue",
                "city": "Washington",
                "state": "DC",
                "zip": "20500"
              },
              "primaryPhone": "2325624852",
              "creditRating": "good",
              "propertyStatus": "own_with_mortgage",
              "educationLevel": "associate",
              "employmentStatus": "employed",
              "annualIncome": "20000",
              "hasDirectDeposit": false,
              "ssn": "512-54-7862",
              "bankRoutingNumber": "123456789",
              "bankAccountNumber": "55555555555"
            }
    clientTags={ ...optional Client Tags, please see following Client Tag section }
    {...optional Event Handlers, please see Event Handler section}
    />

For any of these fields, DO NOT prefill any fields that are empty or otherwise unavailable. If you do not have info for a particular field available to prefill, omit that field in your prefilledDataobject.

For example, this is incorrect:

{..."firstName": "Bob", "lastName": "Dylan", "address": {}, ...otherAttributes}  
// empty address is prefilled, which prevents the user from submitting complete info, and they will not receive offers

This is correct:

{"firstName": "Bob", "lastName": "Dylan", ...otherAttributes} 
//address is not prefilled, which forces the user to input their address in the UI and will allow them to submit complete info and be considered for offers

PrefilledData Type Validations

The data should follow a type schema, described here in Typescript notation:

interface PrefilledLeadData {
    firstName: string;
    lastName: string;
    email: string;
    loanAmount?: number; // whole numbers only
    defaultSliderLoanAmount?: number | string; // if you want the loan amount slider to default to something other than 5000 but want to allow the user to edit the amount, enter it here
    purpose?: LoanPurpose; // enum below
    dateOfBirth?: Date;
    address?: AddressData; // enum below
    primaryPhone?: string; // leading 1 is fine, but no "+" or "-" chars allowed
    phoneConsent?: boolean;
    ssn?: string; // 9 digits with or without hyphens
    creditRating?: CreditRating; // enum below
    propertyStatus?: PropertyStatus; // enum below
    educationLevel?: EducationLevel; // enum below
    employmentStatus?: EmploymentStatus; // enum below
    annualIncome?: AnnualIncomeBracket; // enum below
    hasDirectDeposit?: boolean;
    bankRoutingNumber?: string; (must be exactly 9 digits)
    bankAccountNumber?: string;
}

interface AddressData {
/** Primary street address */
    street?: string;
    /** (Optional) Apartment Suite */
    apartment?: string;
    city?: string;
    state?: string; // must be a valid 2-letter abbreviation
    zip?: string;
}

Enums/Accepted Values for Certain Fields

Certain fields, although strings, must be within a predetermined list of accepted values. Here are those values:

type LoanPurpose = "debt_consolidation" | "credit_card_refi" | 
"home_improvement" | "large_purchases" | "other";

type CreditRating = "excellent" | "good" | "fair" | "poor" | "limited";

type PropertyStatus = "own_with_mortgage" | "rent";

type EducationLevel = "high_school" | "associate" |  "bachelors" |  "masters" |
"other_grad_degree" |  "other";

type EmploymentStatus = "employed" | "self_employed" | "not_employed" | "retired" | 
"military" | "other";

type AnnualIncomeBracket = "20000" | "40000" | "60000" | "100000" | "120000" | "121000";

PrefilledData Sanitization

Prefilled Data must align with the type validations above, and any fields with an accepted value enum must be within that enum. If you (the partner) prefill user data, and any type/value is invalid, that attribute will be stripped, and the lead will have to enter it again manually.

User Flow

When the EngineSdk component is rendered, it will first determine how much information it needs to ask from the user (if not provided in prefilledData). It will then present the user with a splash screen explaining the process to them. When they continue, if all info is prefilled, they are taken directly to the summary screen with their info and can immediately submit to see their offers. Otherwise, they navigate through subsequent screens to collect any missing information, before being presented with the summary screen. From the summary screen, the user is able to correct any info* before submitting it and receiving their offers.

*Note: only info submitted directly by the user can be edited; prefilledData cannot be edited at this time. If firstName/lastName/email or other `prefilledData` fields need to be updated, that should be done in the host app, not the SDK data capture.

At each step through the loan form, the information is saved to the phone and an attempt is made to submit it to the Engine API (updating lead info to track progress/dropoff). If no network is available, the SDK will proceed to the next step without submitting to the Engine API. A network is only required for the final step of submitting the form and receiving offers.

Dropoff and Reentry

Any time a user exits and re-enters the Engine Mobile SDK, they will restart at the same point they were before they exited the SDK.

• If a user was in the middle of the form but did not submit, they will start back on that step (and all previously entered info will be retrieved from local storage so they will not need to enter it again).

• If a user submitted a form and saw offers before exiting, the next time they re-enter the SDK (within the offer expiration period of 31 days), they will be directed back to their offer screen. If offers have expired (>31 days later), they will start at the beginning of the form (save for any prefilled info that will be skipped).

Offer Expiration

Offers will expire 31 days after initially received by the user. Any time within the valid period, users re-entering the SDK will see the same available offers (consumers are unlikely to have material changes to their credit worthiness within that period, which is why offers are cached for that time duration). Users entering the SDK >31 days after they initially received those offers will start the form again as a new lead (minus any prefilled info).

Customization

You can also customize some of the branding by changing the primary and secondary colors to match your own brand. use the primaryColor and secondaryColor attributes to accomplish this.

*Dark mode is not currently available in the Engine Mobile SDK . This will be coming in a future update.