DocumentationHosted ExperienceFront-End Integrations

Exit Button

Hosted Experience can show an Exit button in the borrower header. Use this when Hosted is opened inside your website, mobile app, or partner demo surface and you want the borrower to return to your app instead of staying inside the Aarthik Labs journey shell.

The button is optional for direct Hosted integrations. Enable it only on the Hosted URL instances where your app is ready to handle the exit event.

When To Use It

Use the Exit button when:

  • Hosted is embedded in your web app through an iframe
  • Hosted is opened inside your mobile app or webview
  • your product has its own home screen, dashboard, or loan marketplace that the borrower should return to
  • you want a clear borrower-controlled way to leave the Hosted journey

You do not need it when Hosted opens as a standalone browser journey and the borrower can use normal browser navigation.

Enable The Button

First, create the Hosted URL from your back-end with POST /api/lab/sessions.

Then, before opening the returned URL in your front-end, add:

show_exit=true

as a query parameter on the embedURL.

Example:

1const response = await fetch("/api/loan-journeys/session", {
2  method: "POST",
3});
4const { embedURL } = (await response.json()) as { embedURL: string };
5
6const hostedURL = new URL(embedURL);
7hostedURL.searchParams.set("show_exit", "true");
8
9iframe.src = hostedURL.toString();

If you are building the URL manually for a test, keep the query parameter before the # fragment:

https://credit.aarthiklabs.com/lab/embed?tenant_id=...&show_exit=true#bt_live_...

Do not remove or log the URL fragment. It contains short-lived session material.

What The Borrower Sees

When show_exit=true is present, Hosted shows an Exit button in the header.

When the borrower selects it, Hosted:

  1. clears the borrower session from the Hosted browser surface
  2. clears the applied Hosted theme from the page
  3. sends an aarthik-labs:exit event to the parent web page or mobile bridge

Your app decides what happens next. Common actions are closing the iframe, hiding the Hosted screen, navigating to your app home page, or reopening your product dashboard.

Web iframe Handling

If Hosted runs inside your web page, listen for message events from the Hosted frame.

1const handleHostedMessage = (event: MessageEvent) => {
2  if (event.data?.type !== "aarthik-labs:exit") return;
3
4  // Close or hide the Hosted surface, then show your own app screen.
5  setHostedURL(null);
6  navigateToAppHome();
7};
8
9window.addEventListener("message", handleHostedMessage);

The event payload looks like this:

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}

Use borrowerProviderID and timestamp for support logs or analytics. Do not treat this event as a loan outcome. It only means the borrower pressed Exit.

Mobile App Handling

If Hosted runs inside a mobile app, register the mobile bridge before loading the Hosted URL.

Hosted can send the exit event through the supported mobile bridge surfaces, including:

  • ReactNativeWebView.postMessage
  • webkit.messageHandlers.AarthikLabs.postMessage
  • flutter_inappwebview.callHandler("onAarthikLabsExit", ...)
  • AarthikLabs.postMessage

When your app receives aarthik-labs:exit, close the Hosted webview or route the borrower back to your app-owned screen.

Read Mobile App Bridge for the full bridge contract.

For a clean borrower experience:

  • show your own loading state while Hosted is closing
  • close or hide the Hosted container after receiving aarthik-labs:exit
  • return the borrower to a safe app-owned screen
  • create a fresh Hosted URL if the borrower starts again later
  • log the event type, timestamp, and borrower reference for support

Avoid trying to reuse the same embedURL after exit. If the borrower wants to continue later, call your back-end again and create a fresh URL for the same borrowerProviderID.

Testing Checklist

Before launch, test:

  • Hosted URL opens with show_exit=true
  • the Exit button is visible in the Hosted header
  • clicking Exit sends aarthik-labs:exit
  • your web page, webview, or app shell closes or hides Hosted
  • the borrower lands on the intended app-owned screen
  • starting again creates a fresh Hosted URL
  • mobile bridge handling works on real Android and iOS devices, if applicable