# Embeds

> Put Lucra's screens inside your app.

Source: https://www.onlucra.com/docs/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:

```ts
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:

```tsx
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:

```ts
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

| Component          | For      | Does                                         |
| ------------------ | -------- | -------------------------------------------- |
| `onboarding`       | Both     | Profile, payment setup and connected accounts |
| `creator_programs` | Creators | Find programs, apply and submit work         |
| `wallet`           | Creators | Balance, earnings and withdrawals            |
| `programs`         | Brands   | Create programs and review work              |
| `payments`         | Brands   | Pay creators and offer retainers             |
| `ads`              | Brands   | Create and manage campaigns                  |
| `messages`         | Both     | Conversations                                |

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

- `POST /v1/embeds` (write, SDK `lucra.embeds.create`): Open Lucra UI for a brand or creator, hosted or embedded
- `GET /v1/embeds` (read, SDK `lucra.embeds.list`): List the embeds you opened for a brand or creator
- `GET /v1/embeds/:id` (read, SDK `lucra.embeds.retrieve`): Get an embed
- `PATCH /v1/embeds/:id` (write, SDK `lucra.embeds.update`): End an embed early