React Native

Welcome to the Offer Carousel React Native SDK Integration Guide

This guide walks you through the process of integrating the Offer Carousel 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 a wide range of financial products.

What’s Covered in This Guide

• Software Requirements: Prerequisites for Integrating the SDK

• Installation & Initialization: How to get started quickly

• Customization Options: Tailor the experience to match your app’s theme and branding

• Event Handling & Error Handling: Track SDK activity in real time and handle failures gracefully

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 subAccountToken is used to authenticate with the Engine API and provides access to different financial institutions. If you’re looking to have multiple instances of an offer carousel, leverage unique tokens per instance for distinct tracking and offer control.

Along with your unique subAccount token, you will receive a channel and zone value which is also required to define each unique instance of your SDK embed.

Optionally, your Partner Manager can generate a searchAPIToken on your behalf to enable you to control which product types appear in each offer carousel instance.

Step 2: Confirm Software Requirements

Requirements:

• React Native version >= 0.59.0

• Node.js >= 18

• TypeScript (optional but recommended)

Package Size:

• SDK Bundle Size: 1.62 MB Unpacked

Step 3: Install the SDK

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

• npm install @moneylion/react-native-offer-carousel

• yarn add @moneylion/react-native-offer-carousel

👉 Refer to our NPM readme to set up and run the example app: https://www.npmjs.com/package/@moneylion/react-native-offer-carousel

Step 4: Initialize the SDK

In your app, you’ll need to initialize the SDK by rendering the Offer Carousel React component. You would need to pass in the required properties to see your entitled static offers. Refer to the “Offer Carousel SDK Properties” section below.

To implement the Offer Carousel SDK into your app, render the MoneyLionOfferCarousel component with the required properties. Here is a complete example:

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.

import { MoneyLionOfferCarousel } from "@moneylion/react-native-offer-carousel";
import { Text, View } from "react-native";

export default function App() {
  return (
    <MoneyLionOfferCarousel
      subAccountToken={bearerToken}
      channel={channel}
      zone={zone}
      searchAPIToken={bearerToken} {/* optional */}
      productType={"CreditBuilderLoan"}
      query={"Student Loan"} {/* overrides productType; requires searchAPIToken */}
      fontFamily={{
        normal: "BatonTurbo-Regular",
        medium: "BatonTurbo-Medium",
        bold: "BatonTurbo-Regular",
      }}
      isDarkTheme={true}
      userData={{ email: "[email protected]" }}
      showCardBorder={true}
      showDescriptionPoints={true}
      title={"Your Credit Offers"}
      subtitle={""}
      showProductTypeLabel={true}
      fallbackUI={
        <View>
          <Text>Something went wrong</Text>
        </View>
      }
      tags={"tag.traffic=home_tab&tag.medium=offers_section"}
      {/* Refer to the full list of properties and callbacks in the
          Offer Carousel SDK Properties table below. */}
    />
  );
}

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.

UI Customizations

Fonts and Colors

To maintain brand consistency within your app experience, the Offer Carousel SDK supports font and color customization with the following requirements:

Fonts:

• Any custom fonts must be pre-installed in the host application (ie the partner’s app).

  • For example, if Partner ABC wants to use a custom font, that font must already be supported and linked within their hosted app.

  • The SDK will reference fonts by name via the fontFamily property.

Colors:

• The SDK supports the full range of hex color codes, consistent with what’s supported in the Payload platform across partner pages, embeds, and SDKs.

  • Ideally, partners should use an existing brand configuration (if one has been set up previously).

  • Alternatively, partners can provide their preferred hex codes, and we will apply them during setup.This includes all standard 16 million+ hex color values, like those found in this HTML color picker.

Branding

We manage branding for your Offer Carousel SDK by creating a unique brand for each partner, applied consistently across all carousels. The brand's color palette defines its visual style, with theme colors generated to match and establish the application's overall look and feel.

• Color Palette: A Brand's Palette defines the colors and style used in our experiences.

  • Note: any colors not defined will be generated such that they align with the colors provided.

• Theme Colors: The theme colors are used to define the look and feel of the application. The colors can be generated using the colors provided in the color palette above.

SDK Properties for Customization

The SDK provides the following properties to customize the appearance of the component:

isDarkTheme

By setting this property, you can configure the SDK to match your app’s theme.

Example Offer Carousel with isDarkTheme set to true

showProductTypeLabel:

This property controls the visibility of the offer type on top of the offer card.

Example Offer Carousel with showProductTypeLabel set to true for offers with type “Income Opportunities”

showCardBorder:

Improve visibility of the offer cards by making them more distinct from the background. This is particularly useful when the container's background color is similar to the offer card's background color.

With showCardBorder set to false

With showCardBorder set to true

fontFamily:

This property updates the fonts used by the offer carousel. By default, the SDK will use system fonts.

Example offer with Montserrat font

Example offer with Baton Turbo font

All SDK Properties

Property Name	Type	Required	Default	Description	Example
channel	string	Yes	-	The distribution channel identifier	"direct"
zone	string	Yes	-	The zone identifier for offer targeting	"marketplace"
subAccountToken	string	Yes	-	Unique token to fetch relevant offers	"eyJhbG..."
searchAPIToken	string	No	-	Token for the search API	"search_token_xyz"
productType	string	No	-	Specific product type to filter offers	DebtSettlement CreditBuilderLoan CashAdvance EarnedWageAccess
query	string	No	-	Search query for filtering offers. Note: This Make sure to get searchAPIToken before using this prop.	"credit cards"
tags	string	No	-	Custom tags for offer filtering. Each item must be prefixed with tag.	"tag.tag1=value1&tag.tag2=value2"
fontFamily	Partial<FontFamily>	No	Fallbacks to system font	Custom font family configuration. Make sure the fonts are properly installed in your app.	{ regular: "Roboto-Regular", medium: "Roboto-Medium", bold: "Roboto-Bold" }
showCardBorder	boolean	No	false	Show a border around the offer cards	true
showDescriptionPoints	boolean	No	true	Display the offer description as bullet points	false
title	string	No	-	Custom title for the carousel	"Featured Offers"
subtitle	string	No	-	Custom subtitle for the carousel	"Personalized for you"
isDarkTheme	boolean	No	false	Enable dark theme mode.	true
showProductTypeLabel	boolean	No	false	Whether to display product type labels	true
fallbackUI	React.ReactNode	No	-	Custom UI to show on error	<ErrorComponent />
userData	{ email?: string }	No	-	User data for offer personalization	{ email: "[email protected]" }

Event Handlers for Real-Time Tracking in the Offer Carousel Mobile SDK

The Engine Offer Carousel SDK has multiple real-time Event Handlers so you can track activity in the SDK in real time.

Event Property	Type	Required	Description	Example
onLoad	(numOffers: number) => void	No	Called when offers are loaded. Make sure to use the callback value to show the appropriate UI.	(count) => console.log(${count} offers loaded)
onInitialize	(props: onInitializeProps) => void onInitializeProps { timestamp: string; }	No	Called when the SDK is initialized.	(props) => console.log(props)
onRateTableSubmit	(props: onRateTableSubmitProps) => void onRateTableSubmitProps { timestamp: string; productTypes: string[]; resultType: ResultType; defaultProductType: string; }	No	Called when a rate table submission is made.	(props) => console.log(props)
onRateTableResponse	(props: onRateTableResponseProps) => void onRateTableResponseProps { timestamp: string; isError: boolean; offers: BaseOffer[]; rateTableUuid: string; leadUuid: string; }	No	Called when a response for a rate table is received.	(props) => console.log(props)
onOfferDisplayInViewport	(props: onOfferDisplayInViewportProps) => void onOfferDisplayInViewportProps { timestamp: string; offerUuid: string; rateTableUuid: string; leadUuid: string; offer: BaseOffer; offerIndex: number; context: "horizontal_scroll" | "vertical_scroll"; }	No	Called when an offer is displayed in the viewport.	(props) => console.log(props)
onOfferClick	(props: onOfferClickProps) => void onOfferClickProps { timestamp: string; offerUuid: string; rateTableUuid: string; leadUuid: string; offer: BaseOffer; offerIndex: number; context: "horizontal_scroll" | "vertical_scroll" | "offer_details"; }	No	Called when an offer is clicked.	(props) => console.log(props)
onOfferDetailsPageOpen	(props: onOfferDetailsPageOpenProps) => void onOfferDetailsPageOpenProps { timestamp: string; offerUuid: string; rateTableUuid: string; leadUuid: string; offer: BaseOffer; offerIndex: number; context: "horizontal_scroll" | "vertical_scroll"; }	No	Called when the offer details page is opened.	(props) => console.log(props)
onOfferDetailsPageClose	(props: onOfferDetailsPageCloseProps) => void onOfferDetailsPageCloseProps { timestamp: string; offerUuid: string; rateTableUuid: string; leadUuid: string; offer: BaseOffer; offerIndex: number; }	No	Called when the offer details page is closed.	(props) => console.log(props)
onError	(error: MoneyLionOfferCarouselError) => void MoneyLionOfferCarouselError { code: ErrorCodes; severity: "warning" | "error"; message: string; timestamp: string; sdkVersion: string; error?: Error | unknown; statusCode?: number; additionalInfo?: Record<string, unknown>; }	No	Called when an error occurs.	{ code: “NETWORK_REQUEST_ERROR”, message: “Failed to fetch offers for product types", timestamp:”2025-07-24T10:12:02.492Z", error: Error: 400, version: “1.7.3”, statusCode: 400, additionalInfo: { context: ... } }

Error Handling

The SDK provides a comprehensive onError callback to manage various issues. This callback is invoked for configuration errors, network errors, flow errors, and potential UI errors. The coverage of errors includes the following, each with a corresponding error code:

ErrorCodes { 
  // Configuration 
  MISSING_CONFIG = "MISSING_CONFIG", 

  // UI
  UI_CRASH = "UI_CRASH", 

  // Flow 
  FLOW_ERROR = "FLOW_ERROR", 

  // Network 
  NETWORK_REQUEST_ERROR = "NETWORK_REQUEST_ERROR", 
  NETWORK_SERVER_ERROR = "NETWORK_SERVER_ERROR", 
  NETWORK_OTHER_ERROR = "NETWORK_OTHER_ERROR", 

  // Offers
  NO_OFFERS_FOUND = "NO_OFFERS_FOUND", 

  // Geo
  NON_US = "NON_US", 
}

For configuration and server errors, the onError callback returns a statusCode representing the HTTP error response.

{ 
  code: "NETWORK_SERVER_ERROR”, 
  statusCode: 500, 
  message: “Failed to fetch configuration ", 
  timestamp:”2025-07-24T10:12:02.492Z", 
  severity: “error”, 
  version: “1.7.3”, 
  additionalInfo: { channel: “channel”, } 
}

additionalInfo contains additional information that is relevant to the error that occured. Some examples of what information it could contain:

• `channel` (string) - Configuration channel identifier

• `zone` (string) - Configuration zone identifier

• `query` (string) - Search query string

• `Context` (object) - Configuration context object containing brand, subaccount, signals, etc.

• `pageDataParams` (object) - Parameters used to fetch page data including `productType`, `query`, `tags`, etc.

• `pageData` - Result object containing fetched page data (offers), including `leadUuid`,

• rateTableUuid`, etc.

• `productTypes` (string[]) - Array of product type strings

• `customClientTags` (Record<string, string[]>) - Custom client tags as key-value pairs

• `payload` (object) - Request payload object for API requests

To provide a fallback UI in case of failure, you can utilize the fallbackUI property to pass in a custom React component. Note that this will only show when there’s some error in rendering logic. API errors should be handled by the onError callback.

Changelog

View the full React Native Offer Carousel SDK changelog

2.1.1 (2026-07-28)

• Updated styling for the "See All" button in the offer carousel component

• Migrated offer carousel to use a more performant endpoint for fetching offer data

2.1.0 (2026-07-21)

• Upgraded build tooling to support latest React Native features and improvements

• Added error code handling for scenarios where no loan offers are available

2.0.0 (2026-07-07)

• Replaced deprecated React Native SafeAreaView usage with react-native-safe-area-context to align with the current React Native recommendations and improve compatibility

• Added react-native-safe-area-context as a required peer dependency

• Fixed an issue where horizontally scrolling offers did not always trigger viewport detection correctly

1.11.1 (2026-06-09)

• Improved app responsiveness by replacing deprecated animation scheduling with modern frame-based timing

1.11.0 (2026-06-02)

• Updated the offer carousel component to use an improved markdown rendering library

1.10.2 (2026-05-19)

• Reduced bundle size through dependency cleanup and import optimization.

1.10.1 (2026-04-21)

• Improved type definitions

1.10.0 (2026-04-14)

• Updated behavior to return region-specific error codes for users outside the United States

• Standardized error handling by introducing a consistent error code mapping and deprecating the existing error enum

• Removed a deprecated dependency to address security vulnerabilities and improve stability

1.9.1 (31 Mar 2026)

• Removed query and searchApiToken props

• Deprecated EWS search endpoint

• Removed third-party search functionality

1.9.0 (25 Mar 2026)

• Moved react-native-svg to peer dependencies (required version: >=15.11.0 <16)

• Removed the VideosCard component

• Removed the ThumbsUpIcon component from BaseOfferCard