103 lines
3.3 KiB
Markdown
103 lines
3.3 KiB
Markdown
# Universal Embed Contract
|
|
|
|
> **Documentation contract only.** No embed SDK, iframe host, or token issuer implementation.
|
|
> Architecture: [published-resource-architecture.md](../architecture/published-resource-architecture.md) · [ADR-022](../architecture/adr/ADR-022.md)
|
|
> Contract version: `universal-embed.v1` (additive; open embed-type registry)
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
Published Resources may be **embedded** into external websites or applications. Experience owns **embed metadata** (presentation, theming hooks, allowed origins refs). Business logic for actions inside the embed remains with owning services. All embed contexts identify the surface by **`publish_id`**.
|
|
|
|
---
|
|
|
|
## 2. Reserved embed types (open)
|
|
|
|
| Embed type key | Meaning |
|
|
| --- | --- |
|
|
| `iframe` | Hosted iframe pointing at public/embed URL |
|
|
| `javascript_sdk` | Script loader + mount API |
|
|
| `widget` | Prebuilt widget shell |
|
|
| `popup` | Popup window |
|
|
| `inline` | Inline DOM mount |
|
|
| `modal` | Modal overlay |
|
|
| `floating_button` | Floating launcher |
|
|
| *future.*\* | Unlimited future types |
|
|
|
|
---
|
|
|
|
## 3. Embed metadata (conceptual)
|
|
|
|
```
|
|
EmbedDescriptor {
|
|
publish_id
|
|
tenant_id
|
|
embed_types_allowed[]
|
|
responsive_sizing { mode, min_height?, aspect_ratio? }
|
|
theme_inheritance { inherit_host, token_ref? }
|
|
security {
|
|
sandbox_flags[]
|
|
allowed_origins[]
|
|
origin_validation
|
|
}
|
|
permission_delegation { scopes[], permission_prefix? }
|
|
token_passing { mode } # e.g. postMessage, query, header — owned by Identity patterns
|
|
analytics_propagation { publish_id, embed_session_ref? }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Contract requirements
|
|
|
|
### Responsive sizing
|
|
|
|
- Descriptors MUST support fluid width and documented height strategies (`auto`, `fixed`, `aspect`).
|
|
- Host pages MUST NOT be required to hardcode Experience internal layout ids.
|
|
|
|
### Security & sandbox
|
|
|
|
- Iframe embeds SHOULD declare sandbox flags and CSP expectations (edge/frontend responsibility when implemented).
|
|
- **Origin validation** is mandatory for SDK/postMessage flows.
|
|
- Secrets MUST NOT be embedded in public HTML; use short-lived tokens via Identity/platform patterns.
|
|
|
|
### Permission delegation
|
|
|
|
- Embeds may request limited scopes; evaluation remains Identity/Core.
|
|
- Experience stores which scopes an embed *advertises*, not the auth decision.
|
|
|
|
### Token passing
|
|
|
|
- Modes are reserved: `postMessage`, `signed_query`, `authorization_header`.
|
|
- Experience does not become token issuer of record.
|
|
|
|
### Theming inheritance
|
|
|
|
- Optional inherit-host tokens; Experience theme packs remain Experience-owned when applied to the resource itself.
|
|
|
|
### Analytics propagation
|
|
|
|
- All embed events record **`publish_id`** (and optional `embed_session_ref`).
|
|
- Analytics ownership rules unchanged ([ADR-022](../architecture/adr/ADR-022.md)).
|
|
|
|
---
|
|
|
|
## 5. Ownership
|
|
|
|
| Concern | Owner |
|
|
| --- | --- |
|
|
| Embed metadata / rendering presentation | Experience |
|
|
| Business action execution inside embed | Owning service of the action |
|
|
| Auth tokens | Identity / Core |
|
|
| Paid unlock inside embed | Payment |
|
|
| Host page integration UI | Frontend / external developers |
|
|
|
|
---
|
|
|
|
## 6. Related
|
|
|
|
- [Published Action Registry](published-action-registry.md)
|
|
- [Public Access Contract](public-access-contract.md)
|
|
- [Published Resource Contracts](published-resource-contracts.md)
|