Embeds

Embeds put Lucra's own screens inside your app: onboarding, programs, payments, ads, messages and the creator wallet. Each one runs in an iframe served by Lucra, so card, bank and sign-in details never touch your page.

How it works

1. Add your site's origin, like https://app.example.com, to your key's Embed origins in Settings → Developers → API.
2. On your server, open an embed for a brand or creator with POST /v1/embeds.
3. In the browser, mount it with @lucra/sdk/embed or @lucra/sdk/react. Or skip the frontend and send the person to the embed's hosted url.

Open an embed on your server

Act for the brand (acct_…) or roster creator (crtr_…) the screens are for, list the components to allow, and return the clientSecret to your frontend:

const { data: embed } = await lucra.as("crtr_026UYfiw1Y6OvUpuKWiOpeL").embeds.create({
  body: { components: ["onboarding", "creator_programs", "wallet"] },
})
res.json({ clientSecret: embed.clientSecret })

The clientSecret works once, from an allowed origin, for about 10 minutes. The hosted url lasts 24 hours and needs no allowed origin. End an embed early with PATCH /v1/embeds/:id and status: "expired".

Mount it in React

Wrap your components in LucraProvider once. fetchClientSecret calls your server route above, once per mounted component:

import { loadLucra, LucraProvider, LucraOnboarding } from "@lucra/sdk/react"

const lucra = loadLucra({
  fetchClientSecret: () => fetch("/api/lucra-embed", { method: "POST" }).then((r) => r.json()).then((r) => r.clientSecret),
})

export const Setup = () => (
  <LucraProvider lucra={lucra}>
    <LucraOnboarding onComplete={() => window.location.assign("/dashboard")} />
  </LucraProvider>
)

Each component has its own export: LucraOnboarding, LucraCreatorPrograms, LucraWallet, LucraPrograms, LucraPayments, LucraAds and LucraMessages.

Mount it without React

@lucra/sdk/embed mounts a component into any element, and reports what happens in it:

import { loadLucra } from "@lucra/sdk/embed"

const lucra = loadLucra({ fetchClientSecret })
lucra.mount("wallet", document.querySelector("#wallet")!)
lucra.on("complete", ({ component }) => console.log(`${component} finished`))

lucra.defineElements() registers custom elements instead, like <lucra-wallet></lucra-wallet>.

Components

Open onboarding whenever an account still has a setup step, like a brand with no payment method or a creator who hasn't verified their identity.

Appearance

Components look like Lucra's app. Pass appearance to loadLucra (or to one component) with theme (light, dark or auto), colors.primary (a #rrggbb accent) and radius (0–24 px).

Events

Components emit ready, change, complete, error and close. In React, use the matching onReady, onChange, onComplete, onError and onClose props. When a component creates something, the event's event and id say what, like submission.created with the new sub_… ID.

Your Content Security Policy needs frame-src https://api.onlucra.com.

Endpoints

const { data } = await lucra.embeds.create({
  body: { components: ["onboarding"] },
})

const { data } = await lucra.embeds.list()

const { data } = await lucra.embeds.retrieve({
  path: { id: "emb_…" },
})

const { data } = await lucra.embeds.update({
  path: { id: "emb_…" },
  body: { status: "expired" },
})