Debt Relief

Welcome to the Debt Relief React Native SDK Integration Guide

This guide walks you through the process of integrating the Debt Relief SDK into your React Native application. By using this SDK, you can easily connect to Engine by MoneyLion’s financial network, authenticate with the Engine API, and give your users access to personalized Debt Relief offers.

Setup Instructions

Step 1: Request an API token

Before you can use the Debt Relief Engine SDK, you’ll need to request a new 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

Platform Requirements

• React Native >= 0.71.0

• Node JS >= 18

• React >= 18.0.0

Peer Dependencies

Please note that react, react-native and @react-native-async-storage/async-storage are peer dependencies, meaning that you should ensure they are installed before installing the SDK.

Package Size:

• SDK Bundle Size: 1.99 MB (unpacked)

Step 3: Install the SDK

Install the SDK using your preferred package manager:

• npm: npm i @moneylion/react-native-debt-relief-sdk @react-native-async-storage/async-storage

• Yarn: yarn add @moneylion/react-native-debt-relief-sdk @react-native-async-storage/async-storage

• pnpm: pnpm add @moneylion/react-native-debt-relief-sdk @react-native-async-storage/async-storage

Step 4: Initialize the SDK

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

You can import the EngineSDK component into your app. At a minimum, you must provide the API token obtained in Step 1 (requesting a token from your Partner Manager) via the bearerToken prop, and pass the user's first name, last name, and email, as the Engine SDK does not request these three fields. For the full list of supported props, please refer to the Props section.

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

import { EngineSdk } from "@moneylion/react-native-debt-relief-sdk";

<EngineSdk 
   bearerToken={// API token obtained in Step 1} 
   prefilledData={{ 
       firstName: “John”,  
       lastName: “Doe”,  
       email:[e-mail]
       // more data that you don’t want to ask user again 
   }} 
    primaryColor=”#11AA34” 
    secondaryColor=”#444444” 
    clientTags={ ...optional Client Tags, please see following Client Tag section } 
    { ...optional event handlers, please see Event Handler section below } 
    />

User Experience & Demo

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": "[e-mail]", // 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": "[e-mail]", // 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.

UI Customization

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

Event Handlers

The Engine SDK includes a set of Event Handlers that give you greater visibility into SDK activity and can be used to support your internal reporting and application logic. Instructions here:

https://engine.tech/developer-center/loans-savings-second-look-marketplace/hosted/mobile-sdks/personal-loans-sdk/event-handlers-for-real-time-tracking-in-the-engine-mobile-sdkengine.tech

Connecting with Personal Loans

The Debt Relief Engine SDK is designed to match your consumer with the most suitable product. If the consumer does not appear to be a good fit for Debt Relief products, the SDK will automatically attempt to qualify them for a Personal Loan instead.

When a consumer meets both of the conditions below, the SDK will request additional Personal Loan fields to complete qualification:

• Requested amount is less than $5,000, and

• Self-assessed credit score is above 660

The additional Personal Loan fields are:

• Home-Owner vs Renter

• Education Level

• Employment Status

• Annual Income

• Social Security Number

EngineSDK Props

Name	Type	Default	Description
endpoint	string	https://api.engine.tech	Optional custom API endpoint. If not provided, the SDK will use https://api.engine.tech by default
bearerToken	string	Required	The API token obtained from Partner Manager. Used to authenticate requests to the Engine API.
prefilledData	PrefilledLeadData	Required: firstName, lastName, email	User information to prepopulate the Debt Relief flow. See the Prefilled Data section for details.
primaryColor	string (RGBA hex)	-	Primary theme color for the SDK UI (e.g., #FF0000FF).
secondaryColor	string (RGBA hex)	-	Secondary theme color for the SDK UI.
clientTags	ClientTags	-	Optional tags used for tracking performance of specific campaigns or users. See the ClientTags section for details.
onInitialize	(props) => void	-	Triggered when the SDK initializes. See the Events page.
onCreate	(props) => void	-	Called after a lead is created. See the Events page.
onUpdate	(props) => void	-	Called when a lead is updated. See the Events page.
onNavigate	(props) => void	-	Fired when the user navigates between SDK screens. See the Events page.
onSubmit	(props) => void	-	Fired when the user submits their information. See the Events page.
onRateTableRender	(props) => void	-	Called when the user submits their information to the Engine service and receives offers. See the Events Page
onOfferClick	(props) => void	-	Fired when a user clicks an offer. See the Events page.
onErrorPageView	(props) => void	-	Triggered when the user is driven to the Error page. See the Events page.
onErrorPageRetry	(props) => void	-	Trigger when the user taps “Retry” on the error page. See the Events page.
onError	(props) => void	-	Fired when an error occurs during SDK operations. See the Events page.
onExit	(props) => void	-	Fired when the user attempts to exit the SDK flow. See the Events page.