Mobile App Bridge

Hosted Experience can run inside a customer mobile app. During a borrower journey, some steps may need to open lender-owned pages outside the main Hosted surface, such as KYC, e-mandate, e-sign, or a lender redirection flow.

On desktop browsers, these pages often open in a new tab or window. Inside mobile apps, that browser model only works if the parent app explicitly supports it. Without this handling, a borrower may complete a lender step and remain stuck on a lender success page instead of returning to Hosted Experience.

The mobile app bridge makes this handoff explicit.

What The App Needs To Do

When Hosted Experience asks your app to open an external lender step, your app should:

1. receive the bridge event from Hosted
2. read the event payload
3. open the lender-owned external_url in an app-controlled surface
4. give the borrower a clear way back, such as “Done” or “Back to application”
5. return to the existing Hosted surface when possible
6. open resume_url if the original Hosted surface is no longer available

Your app does not need to understand Aarthik Labs journey states or decide the next loan step. Hosted Experience decides the next correct state when the borrower returns.

Where This Applies

Use the bridge whenever Hosted Experience is opened inside a customer-controlled mobile app container.

This includes:

• a direct Hosted Experience URL
• a Hosted URL created by POST /api/lab/sessions
• a Hosted handoff URL opened after a Hybrid Experience flow
• a resume_url reopened after an external lender step

The entry path does not change the bridge contract. If Hosted is running inside your app container, register the bridge before loading the URL.

Bridge Channel

Expose a native message bridge named:

AarthikLabs

Channel names and event names are case-sensitive.

Depending on your mobile container, bridge messages may arrive as a JSON string or as an object. Parse defensively and route by the type field.

If your container uses named handlers instead of a named post-message object, map external-step messages to:

onAarthikLabsExternalOpen

and exit messages to:

onAarthikLabsExit

Open External Event

Hosted sends this event when the app should open a lender-owned external step.

1
{
2
  "type": "aarthik-labs:open-external",
3
  "version": 1,
4
  "payload": {
5
    "external_url": "https://lender.example.com/kyc/session/abc123",
6
    "resume_url": "https://credit.aarthiklabs.com/lab/handoff?handoff=...",
7
    "step": "E_KYC",
8
    "journey_id": "journey-123",
9
    "offer_id": "offer-456",
10
    "lender_name": "Example Lender",
11
    "title": "Complete KYC",
12
    "tenant_id": "tenant-123",
13
    "application_id": "application-123",
14
    "borrower_id": "borrower-123",
15
    "timestamp": "2026-05-01T08:00:00.000Z"
16
  }
17
}

Payload Fields

Step Values

Use step for display labels, logging, analytics, or app-level routing. Do not use it to decide the next Hosted journey step.

Exit Event

Hosted may send this event when the borrower uses a Hosted exit action.

1
{
2
  "type": "aarthik-labs:exit",
3
  "version": 1,
4
  "payload": {
5
    "tenantID": "tenant-123",
6
    "applicationID": "application-123",
7
    "borrowerProviderID": "borrower-provider-123",
8
    "timestamp": "2026-05-01T08:00:00.000Z"
9
  }
10
}

When your app receives this event, it can close the Hosted screen, return the borrower to your app home screen, or perform another app-owned exit behavior.

Recommended Handling Logic

Use this flow:

Hosted emits aarthik-labs:open-external
        |
        v
App opens payload.external_url in an app-controlled surface
        |
        v
Borrower completes or closes the lender step
        |
        +--> if Hosted is still alive:
        |       return to the existing Hosted surface
        |
        +--> if Hosted is not alive:
                open payload.resume_url

When the borrower returns, Hosted refreshes the journey state and decides what to show next. The borrower may move forward, see a waiting state, see a retry path, or see a rejection/terminal state depending on the lender response.

App-Controlled External Surface

The external lender step should open above or alongside the Hosted surface in a way your app controls.

Recommended behavior:

• keep the original Hosted surface alive underneath when possible
• open the lender URL in a separate app-controlled screen, tab, modal, or browser surface
• show a visible return action
• support lender pages that call window.close()
• return the borrower to Hosted after the external surface closes
• use resume_url only when the original Hosted surface is gone

Avoid replacing the Hosted surface with the lender page unless your app has a reliable way to reopen Hosted afterward.

WebView Requirements For Lender Steps

The app container should behave like a mobile browser for Hosted and lender pages.

Your implementation should support:

• JavaScript
• DOM storage
• cookies and session storage needed by Hosted and lender pages
• window.open and target-blank navigation
• child window or popup creation
• closing a child surface when the lender page requests close
• returning to the parent Hosted surface
• approved Hosted and lender domains
• continuing Hosted polling or refresh after the borrower returns

If one of these is missing, KYC, e-mandate, loan agreement, document upload, or lender redirection steps may fail inside the app even if they work in a normal browser.

Error Handling

Handle bridge failures without crashing the app.

Logging Recommendations

Log enough to support debugging without storing sensitive URLs or borrower data unnecessarily.

Useful log points:

• Hosted URL started loading
• Hosted URL finished loading
• bridge registered
• bridge event received
• event type and version
• external step
• external URL host
• journey ID
• offer ID, if present
• lender name, if present
• external step opened
• borrower returned to Hosted
• resume URL used
• parse, open, or close failures

Avoid logging full external_url or resume_url values into long-term analytics systems unless your security policy allows it.

Security Notes

• Register the bridge only for trusted Hosted origins.
• Parse messages defensively.
• Do not execute arbitrary instructions from bridge payloads.
• Do not expose resume_url outside the app flow.
• Do not read lender page contents or borrower credentials from the external page.
• Do not infer success or failure just because the borrower closed the lender page.

Testing Checklist

Before launch, test on real devices:

• Hosted loads inside the app.
• The bridge is registered before Hosted loads.
• The app receives aarthik-labs:open-external.
• The app opens payload.external_url.
• The app provides a clear return action.
• Returning reveals the original Hosted surface when it is still alive.
• Returning uses payload.resume_url when Hosted was destroyed.
• The app handles a null resume_url safely.
• KYC external step can be opened and returned from.
• E-mandate external step can be opened and returned from.
• E-sign external step can be opened and returned from.
• Lender redirection can be opened and returned from.
• Hosted shows the correct state after return.
• Invalid bridge messages do not crash the app.
• The app receives and handles aarthik-labs:exit if Hosted exit is enabled.

Final Rule

The mobile app controls the shell around Hosted Experience. Hosted controls the credit journey.

Your app only needs to listen for bridge events, open the external URL, give the borrower a way back, and reopen Hosted with resume_url when needed.