Back to Engine.tech

Mobile SDK

How to get started with an Engine by MoneyLion marketplace Mobile SDK integration for Personal Loans

Welcome to Engine by MoneyLion’s React Native SDK Integration Guide. This document provides the necessary steps to seamlessly integrate the Engine SDK into your React Native application. With this SDK, you can effortlessly connect to Engine by MoneyLion’s network, authenticate with the Engine API, and provide users access to a variety of financial institutions. The 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 (pending your brand's color customizations).

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: Software Requirements

React Native

SDK Bundle Size: 4.96MB 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 token from Step 1, 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. See the example below:

<EngineSDK
bearerToken="your token here"
endpoint="https://api.engine.tech"
primaryColor=”#11aa34”
secondaryColor=”#444444”
prefilledData={/* any data you don't want to ask for again */}
clientTags={{ “userTrackingId”: [“80”] }}
      onExit={() => { /* handler */ }}
onInitialize={(savedLeadUuid, savedLeadData) => { /* handler */ }}
onCreate={(leadUuid, leadData, page, editingPage) => { /* handler */ }}
onUpdate={(leadUuid, leadData, page, editingPage) => { /* handler */ }}
onNavigate={(leadUuid, leadData, page, nextPage, editingPage) => { /* handler */ }}
onSubmit={(leadUuid, leadData) => { /* handler */ }}
/>

How it Works

Implementation/Prefilled Data

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

Beyond those, you can pass any other information you have already collected, so the user isn’t asked for it again.

Prefilled Data

Here is an example of prefilledData as a Javascript Object:

{
  "firstName": "Bob",
  "lastName": "Dylan",
  "email": "[email protected]",
  "loanAmount": 6500,
  "purpose": "credit_card_refi",
  "dateOfBirth": new Date("1990-01-01"),
  "address": {
    "city": "Washington",
    "state": "DC",
    "street": "1600 Pennsylvania Avenue",
    "zip": "20500"
  },
  "primaryPhone": "2325624852",
  "creditRating": "good",
  "propertyStatus": "own_with_mortgage",
  "educationLevel": "associate",
  "employmentStatus": "employed",
  "annualIncome": "20000",
  "hasDirectDeposit": false,
  "ssn": "512-54-7862"
}

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

interface PrefilledLeadData {
    firstName: string;
    lastName: string;
    email: string;
    loanAmount?: number; // whole numbers only
    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;
}

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:

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";

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 First Name/Last Name/Email/other prefilledData fields need to be updated, that should be done in the app the SDK is installed into.

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.

Customization

You can also customize some of the branding by changing the primary and secondary colors to match your own brand.

Client Tags

The Mobile SDK supports adding your own unique Client Tags to track performance of specific campaigns or users. All Client Tag data is attributed to the lead level. Client tags should be structured as a Javascript object of key-value pairs, where the values are arrays 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.

Supported Client Tag keys

These are the 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. Please note that the keys below are case-sensitive.

  • agentId

  • campaignId

  • clientId

  • deviceid

  • medium

  • sourceId

  • subid

  • subid1

  • subid2

  • subid3

  • target

  • trafficsource

  • userid

Event Handlers

There are 6 Event Handlers you can supply that will be called when a user goes through the SDK flow. Channel Partners Typically use Event Handlers to call their own endpoints when their leads hit specific funnel stages, for tracking, retargeting, or other purposes.

  1. The `onInitialize` handler 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.

  2. The `onCreate` handler 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.

  3. The `onUpdate` handler is called whenever the SDK updates a lead with the Engine service. It receives the same data that the onCreate handler receives.

  4. The `onNavigate` handler 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.

  5. The `onSubmit` handler is called when the user submits their information to the Engine service and receives offers. The submitted data is supplied to the handler.

  6. Lastly, the `onExit` handler is called when the user attempts to exit the SDK flow. It is important to supply this handler so that you can redirect the user back to where they were before starting the Engine SDK 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. The user will navigate through each screen to collect any missing information before, being presented with a summary of the information collected. If they are not missing any information (i.e. all info is prefilled), the summary screen is immediately presented. From the summary screen, they have a chance to correct any info* before submitting it and receiving their offers.

*Note: only info submitted by the user can be edited. PrefilledData cannot be edited at this time.

Screenshots of sample SDK Implementation

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

PreviousAdding Client Tags to ReportsNextNative API (Build Your Own)

Last updated