Plan a referral flow for a Lovable app
A concrete two-user signup example for a Lovable-built app, with a backend contract checklist and visible states for capture failures. This walkthrough is an unverified preview.
RefRef technical guide · Reviewed against source and official client documentation on 3 October 2026 · Review preview
Prerequisites
- A signed-in Lovable account and a disposable app you can edit without paid actions.
- An authenticated application backend capable of same-origin capture, HttpOnly cookies and server-side signing; a visual frontend alone is insufficient.
- A Sandbox RefRef Project with published referral configuration and backend credentials stored only in server secrets.
- For optional MCP configuration: a reachable RefRef endpoint and a Lovable workspace that permits custom MCP servers. Compatibility must be tested in that workspace.
Keep the MCP setup reference and application integration contract open. Configuration and runtime tracking are separate steps.
1. Start with the invite experience
Use a disposable project. The example is an app where one person invites another to create an account. Build the UI first with clearly labeled fixtures; do not display fabricated earnings or referral counts.
Build a referral invite screen for my existing app. Use its current design system. Show the signed-in person’s sharing link, a Copy link button with an accessible confirmation, and states for loading, not enrolled and request failure. Use labeled fixture data until the backend is connected. Do not show reward history or payment status. Keep signup blocked while referral capture is pending or has failed, with an explicit retry action.2. Locate the runtime backend
Provide the application integration reference below, then run this prompt. A chat connector supplies build-time context; it is not the deployed app’s event sender. Stop at a backend gap rather than putting a secret in frontend code.
Inspect this Lovable app and identify where trusted backend code runs. Can it serve same-origin POST /refref/capture, set a signed HttpOnly cookie, authorize the signed-in identity and keep a Project signing secret private? Show the actual routes and deployment origins. Use the supplied RefRef application integration contract. If these requirements cannot be met, report the gap and leave the UI in fixture mode. Do not replace signed evidence with localStorage, an email match or an unsigned refcode cookie.3. Optionally connect build-time MCP
Lovable’s documented catalog has a + action for MCP server. Use the operator-provided RefRef server URL and OAuth. Ask it to retrieve the integration workflow, then discover Workspaces and select the Sandbox Project explicitly. This connection has not been validated with RefRef. If authorization or tool discovery fails, retain the documented backend approach and record the failure; do not substitute a Workspace key as MCP authentication.
4. Wire one signup, then inspect the preview
After verifying backend support, replace fixtures with authenticated enrollment/link reads and the capture flow. Ask Lovable to show exactly where it waits for capture before signup and where it retains evidence for retries. Use its app preview for UI inspection, and a secure test deployment for browser-cookie and cross-origin behavior. Neither a successful build nor an attractive invite screen proves attribution.
5. Run the two-user example
Create disposable app user A, enroll A, and copy the returned sharing link. Open it in a separate browser session and create B. Record the capture response, signup Event ID, and referral participants. Repeat signup delivery with the same retained evidence. Use the following checklist as the acceptance record, with actual results rather than expected-result screenshots.
An invite screen with three honest states
Use this fixture specification in the Lovable preview before connecting real data. Replace fixtures only after each backend response has been verified.
01
Not enrolled
Show ‘Invites are not available for this account yet.’ Do not generate a placeholder referral link or report a referral count.
02
Ready to share
Render the authenticated participant’s returned link. Copy must copy that exact link and announce success. A user can still select the link manually.
03
Capture failed
Show ‘We could not save your referral visit. Retry to continue.’ Retain the signed handoff for retry and prevent signup until capture succeeds.
Record actual results beside these checks
- CHECK 01A opens the invite screen before and after enrollment.
- Expected resultNot enrolled is explicit; after enrollment, the displayed link belongs to A in the intended referral Program.
- CHECK 02B follows A’s link, then capture is deliberately made to fail.
- Expected resultThe page shows a retry state and does not submit signup with invented empty evidence.
- CHECK 03Restore capture and complete B’s signup in a separate browser session.
- Expected resultInspect the real accepted Event and qualifying preserved referral; A and B are distinct participant IDs.
- CHECK 04Repeat delivery and inspect client network requests.
- Expected resultNo duplicate canonical Event; no backend credentials sent to the browser. Record the actual result and any pending reason.
An earned Reward is an accounting result. It does not establish that cash, credit or a discount was delivered.
What has actually been validated
Official Lovable connector documentation was reviewed. The embedded browser reached Lovable’s login page without an authenticated session on 3 October 2026. No Lovable project was generated, no connector was authorized, and no two-user journey was run. This page must remain a review preview until that tool-specific example passes.