Swift

Swift Personal Loans Mobile SDK Integration Guide

Overview

The Personal Loans vertical is delivered through the Engine Mobile SDK for iOS. This guide covers installation, prerequisites, the core configuration props (channel, zone, productTypes), a basic usage example, prefilling lead data, client tags, and event handlers.

You'll need the correct channel and zone values for your integration. Ask your Partner Manager to provide these values for Personal Loans.

Before you start, request an API token from your Partner Manager. It authenticates with the Engine API and is required to use the Prefill API. You may want multiple tokens depending on how many entry points your app has into the SDK.

Requirements

• Xcode 15 or higher

• iOS 15.0 or higher deployment target

• Swift 5.9 or higher

Install

Add the package via Swift Package Manager. In Xcode, select your project → Package Dependencies → “+”, enter the repository URL, then choose a version rule (Up to Next Major Version is recommended) and add the SwiftEngineSDK library to your app target. Use the latest published release — check the repository's Releases for the current version:

https://github.com/MoneyLion/engine-mobile-native-sdk.git

Because the repo is public, no GitHub account or token is required — SwiftPM downloads the binary directly.

Or add it to your Package.swift:

dependencies: [
    .package(
        url: "https://github.com/MoneyLion/engine-mobile-native-sdk.git",
        from: "1.0.0" // use the latest published release
    )
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "SwiftEngineSDK", package: "engine-mobile-native-sdk")
        ]
    )
]

Initialize

Import the SDK in any file where you want to render the Engine flow:

import SwiftEngineSDK

Basic Example

EngineSDK is a UIView — construct it with its convenience initializer and add it to your view hierarchy. Use [.loan] for productTypes to render the Personal Loans flow. Your channel and zone values are provided by your Partner Manager.

let sdk = EngineSDK(
    channel: "your-channel",
    zone: "your-zone",
    productTypes: [.loan],
    onExit: { _ in
        // handle exit / navigation
    }
    // ...optional event handlers, see Event Handlers
)

view.addSubview(sdk)

Retain the EngineSDK view (e.g. as a property on your view controller or a SwiftUI coordinator). If it deallocates, the embed stops working.

Properties

Prop	Type	Required	Description
channel	String	Yes	Identifies your integration in Engine. Provided by your Partner Manager (e.g. "direct").
zone	String	Yes	Identifies the placement or distribution surface for the SDK. Provided by your Partner Manager (e.g. "marketplace").
productTypes	[ProductType]	Yes	Product flow(s) to render. ProductType is imported from the Engine SDK package — use [.loan] for Personal Loans, which maps to the string value "loan".
bearerToken	String	For prefill	API token from your Partner Manager. Required to use the Prefill API. Without it, the standard non-prefilled flow renders.
personalInformation	LeadPersonalInformation	No	Prefill data. See Prefilling Lead Data.
loanInformation	LeadLoanInformationJson	No	Prefill data. See Prefilling Lead Data.
mortgageInformation	LeadMortgageInformationJson	No	Prefill data. See Prefilling Lead Data.
creditInformation	LeadCreditInformationJson	No	Prefill data. See Prefilling Lead Data.
financialInformation	LeadFinancialInformation	No	Prefill data. See Prefilling Lead Data.
employmentInformation	LeadEmploymentInformationJson	No	Prefill data. See Prefilling Lead Data.
legalInformation	LeadLegalInformationJson	No	Prefill data. See Prefilling Lead Data.
educationInformation	LeadEducationInformationJson	No	Prefill data. See Prefilling Lead Data.
clientTags	[String: [String]]	No	Reporting/attribution tags. See Client Tags.
onExit	EngineSDKCallbacks.OnExit	Yes	Fired when the user exits the flow. Passed directly to EngineSDK(...).
onInitialize, onCreate, onUpdate, onNavigate, onSubmit, onRateTableRender, onOfferClick, onErrorPageView, onErrorPageRetry, onEmbedError, onEmbedErrorRetry	Callbacks	No	Optional tracking hooks passed to EngineSDK(...). See Event Handlers.

Prefilling Lead Data

Prefill any user data you already have to reduce what the user has to type in-flow. Prefilled data is grouped into typed information objects, each passed to EngineSDK(...) (e.g. personalInformation, loanInformation, financialInformation).

Prefilling requires a bearerToken. Pass only the fields you have — omitted fields are collected from the user in-flow.

Example

let sdk = EngineSDK(
    channel: "your-channel",
    zone: "your-zone",
    bearerToken: "{your_token}",
    productTypes: [.loan],
    personalInformation: LeadPersonalInformation(
        firstName: "Bob",
        lastName: "Dylan",
        email: "[email protected]",
        dateOfBirth: Calendar.current.date(from: DateComponents(year: 1990, month: 1, day: 1)),
        primaryPhone: "2325624852",
        address1: "1600 Pennsylvania Avenue",
        address2: "Apt 2",
        city: "Washington",
        state: .dc,
        zipcode: "20500",
        ssn: "512-54-7862"
    ),
    loanInformation: LeadLoanInformationJson(
        purpose: .creditCardRefi,
        loanAmount: 7500
    ),
    mortgageInformation: LeadMortgageInformationJson(
        propertyStatus: .ownWithMortgage
    ),
    creditInformation: LeadCreditInformationJson(
        providedCreditRating: .good
    ),
    financialInformation: LeadFinancialInformation(
        employmentStatus: .employedFullTime,
        employmentPayFrequency: .biweekly,
        annualIncome: 20000,
        bankRoutingNumber: "123456789",
        bankAccountNumber: "55555555555"
    ),
    employmentInformation: LeadEmploymentInformationJson(
        directDeposit: false
    ),
    legalInformation: LeadLegalInformationJson(
        consentsToSms: true
    ),
    educationInformation: LeadEducationInformationJson(
        educationLevel: .associate
    ),
    onExit: { _ in }
)

view.addSubview(sdk)

Type Definitions

Every prop and field is optional — pass only what you have.

struct LeadPersonalInformation {
    var firstName: String?
    var lastName: String?
    var email: String?
    var dateOfBirth: Date?
    var primaryPhone: String?   // 10 digits, no "+" or "-" chars
    var address1: String?
    var address2: String?       // optional apartment / suite
    var city: String?
    var state: State?           // 2-letter state enum (e.g. .dc)
    var zipcode: String?
    var ssn: String?            // 9 digits with or without hyphens
}

struct LeadLoanInformationJson {
    var purpose: LoanPurpose?
    var loanAmount: Int?        // whole numbers only
}

struct LeadMortgageInformationJson {
    var propertyStatus: PropertyStatus?
}

struct LeadCreditInformationJson {
    var providedCreditRating: ProvidedCreditRating?
}

struct LeadFinancialInformation {
    var employmentStatus: EmploymentStatus?
    var employmentPayFrequency: EmploymentPayFrequency?
    var annualIncome: Int?          // raw integer value (e.g. 20000)
    var bankRoutingNumber: String?  // must be exactly 9 digits
    var bankAccountNumber: String?
}

struct LeadEmploymentInformationJson {
    var directDeposit: Bool?
}

struct LeadLegalInformationJson {
    var consentsToSms: Bool?    // lead agrees to receive SMS
}

struct LeadEducationInformationJson {
    var educationLevel: EducationLevel?
}

Enums / Accepted Values

Fields backed by an enum must use a valid value.

enum LoanPurpose {
    case auto
    case autoPurchase
    case autoRefinance
    case baby
    case boat
    case business
    case carRepair
    case cosmetic
    case creditCardRefi
    case debtConsolidation
    case emergency
    case engagement
    case green
    case homeImprovement
    case homePurchase
    case homeRefi
    case householdExpenses
    case largePurchases
    case lifeEvent
    case medicalDental
    case motorcycle
    case movingRelocation
    case other
    case rv
    case specialOccasion
    case studentLoan
    case studentLoanRefi
    case taxes
    case vacation
    case wedding
}

enum ProvidedCreditRating {
    case excellent
    case good
    case fair
    case poor
    case limited
}

enum PropertyStatus {
    case ownOutright
    case ownWithMortgage
    case rent
}

enum EducationLevel {
    case highSchool
    case associate
    case bachelors
    case masters
    case doctorate
    case otherGradDegree
    case certificate
    case didNotGraduate
    case stillEnrolled
    case other
}

enum EmploymentStatus {
    case employed
    case employedFullTime
    case employedPartTime
    case military
    case notEmployed
    case selfEmployed
    case retired
    case other
}

enum EmploymentPayFrequency {
    case biweekly
    case monthly
    case twiceMonthly
    case weekly
}

// State is a 2-letter US state enum, e.g. .ca, .dc, .ny

Do not prefill any fields that are empty or unavailable — omit them so the user is prompted in-flow. Prefilled data must match the type definitions above, and any field backed by an enum must use a valid value. If a value is invalid, that attribute is stripped and the user will have to enter it again manually.

Client Tags

The Engine 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 are added via the clientTags parameter on EngineSDK, a map of string keys to lists of string values. We strongly recommend including only one element per list for ease of reporting and attribution — if you want two separate tags, include the second tag under a different key. There is no limit to the number of keys.

let sdk = EngineSDK(
    channel: "your-channel",
    zone: "your-zone",
    bearerToken: "{your_token}",
    productTypes: [.loan],
    personalInformation: LeadPersonalInformation(/* ...any data you don't want to ask for again */),
    clientTags: [
        "clientId": ["client1"],
        "trafficsource": ["email"],
        "campaignId": ["campaign1"]
    ],
    onExit: { _ in }
)

view.addSubview(sdk)

Note: Client Tags are only sent as part of a prefill request. You must provide both a bearerToken and prefill data (via the information props such as personalInformation). If no prefill data is supplied, the SDK makes no prefill call and any clientTags you pass are ignored.

Supported Client Tag Keys for Reporting

If you plan for the Engine team to set up reporting (i.e., you do not plan to hit the 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.

• agentId

• campaignId

• clientId

• deviceid

• medium

• sourceId

• subid

• subid1

• subid2

• subid3

• target

• trafficsource

• userid

Event Handlers

EngineSDK accepts optional callbacks that notify your app when key moments occur during the user's journey. Each callback receives an event object containing a timestamp (ISO 8601 UTC) and event-specific fields.

All callbacks are optional. Pass any combination when constructing EngineSDK. If a callback is not provided, the SDK will still log the event to the debug console in development mode.

let sdk = EngineSDK(
    channel: "your-channel",
    zone: "your-zone",
    productTypes: [.loan],
    onInitialize: { event in print("onInitialize \(event.timestamp)") },
    onCreate: { event in print("onCreate \(event.leadUuid)") },
    onSubmit: { event in print("onSubmit \(event.leadUuid)") },
    onOfferClick: { event in print("onOfferClick \(event.offerUuid)") },
    onExit: { event in
        // Navigate the user back or perform cleanup
    }
    // ...other callbacks
)

view.addSubview(sdk)

Available Events

Callback	Trigger
onInitialize	SDK finished loading the embed
onCreate	New lead created
onUpdate	Lead data updated
onNavigate	Page navigation within the flow
onSubmit	Lead form submitted
onRateTableRender	Rate table displayed with offers
onOfferClick	User clicked an offer
onErrorPageView	Error page displayed in the flow
onErrorPageRetry	User retried from the error page
onExit	User exited the SDK
onEmbedError	Web embed failed to load
onEmbedErrorRetry	User retried after embed failure

For Personal Loans, onRateTableRender populates loanOffers and specialOffers, and onOfferClick includes loan-specific fields such as financialInstitutionName, loanAmount, apr, termLength, and monthlyPayment. Every event includes a timestamp (ISO 8601 UTC).

Signing process

The Swift SDK's XCFramework binaries are code-signed with an Apple Distribution certificate (Apple Distribution: MoneyLion Inc) using Apple's codesign. This lets Apple and Xcode confirm that the framework was produced by Engine and has not been tampered with.

Verifying the artifact

Verification is automatic — Xcode and iOS validate the signature when the framework is integrated into your app. To check it manually:

1. Download xcframework.zip from the releases page:

https://github.com/MoneyLion/engine-mobile-native-sdk/releases

1. Extract the zip to get the .xcframework.

2. Run codesign against the framework:

codesign -dvvv <Framework>.xcframework

Confirm the output shows Authority=Apple Distribution: MoneyLion Inc.

Changelog

View the full Swift Personal Loan SDK changelog

1.0.1 (2026-08-04)

• Bug fixes and general improvement

1.0.0 (2026-08-03)

• Initial release of the Swift Engine SDK.