All pages
Home blocks
A Resident’s Home is a stack of sections (text, links, galleries, offers). With home_block your app adds a section of its own. After installing, the Resident can turn on On your Home from the app’s page in Your apps to place it on their main Home right away, or add, reorder, title and configure it per Home in Your Home.
Two ways to render
- Framed (
block.render: "frame", default): craving embedsblock.urlin a sandboxed iframe and your page draws the UI. - Drawn (
block.render: "json"): your server returns a structured JSON document atblock.content_url, and craving renders it natively with the Home’s own components and theme on both web and mobile. No iframe or third-party JavaScript runs on the Home, and the content is included in the initial server render. See Drawn blocks.
Rendering a framed block
craving loads block.url on your declared origin with the session JWT in the URL fragment. The iframe runs with sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox" and allow="clipboard-write", isolated from the parent page’s cookies and DOM. Your page:
- Reads
#craving_sessionfromlocation.hashand verifies the ES256 JWT (Authentication). - Reads
settingsfrom the token (the Resident’s saved answers tosettings_schema, with per-block overrides already merged). - Renders the UI and posts
craving:readytoparent.
<script>
const params = new URLSearchParams(location.hash.slice(1));
const session = params.get('craving_session');
const theme = params.get('theme'); // 'dark' | 'light' | 'auto'
// Verify `session` on your server or against the JWKS, then render:
parent.postMessage({ type: 'craving:ready' }, '*');
// For auto-height blocks (clamped to 40..1200 px):
parent.postMessage({ type: 'craving:resize', height: document.body.scrollHeight }, '*');
// Record a click in your daily app stats:
parent.postMessage({ type: 'craving:track', event: 'click' }, '*');
</script>Messages from origins outside your manifest’s origins list are ignored. If a framed block does not post craving:ready within 6 seconds, a fallback placeholder is shown.
Height
Set block.height.mode to "fixed" (px from 40 to 1200), "aspect" (ratio such as "16:9", scaled to the Home’s width) or "auto" (starts at estimated_px, default 240, then updates when your frame posts craving:resize, clamped to 40–1200 px). Homes pack sections into screens using the estimated height.
Settings
settings_schema generates a native settings form on the installed app’s page in Your apps (defaults across Homes) and inside Your Home (overrides for a single block). craving validates every save against your schema and passes the merged object in the session token, the drawn block content_url request and GET /v1/me. Your server can also update default settings via PATCH /v1/installations/{id}.
Drawn blocks
The document has a JSON Schema, block-document.json, with an example of every item.
Set "render": "json" and declare content_url on one of your origins. Whenever the block needs fresh content, craving sends a POST signed with X-Craving-Signature:
{
"format": "1",
"installation_id": "…",
"block_id": "…",
"settings": { "city": "Ghent" }
}settings contains the effective settings for that block (per-block overrides over installation defaults, with schema default values filled in). Respond with a format: "1" JSON document (up to 256 KB within 20 seconds). You may include an ETag response header; craving sends If-None-Match on the next refresh and keeps the cached document when you answer 304 Not Modified.
{
"format": "1",
"items": [
{ "type": "text", "text": "This week's picks", "size": "lg" },
{
"type": "cards",
"layout": "carousel",
"cards": [
{
"title": "Linen shirt",
"price": "$49",
"image": "https://app.example.com/shirt.jpg",
"action": {
"type": "open_url",
"url": "https://shop.example.com/shirt",
"sponsored": true
}
}
]
},
{ "type": "button", "label": "Notify me", "action": { "type": "subscribe" } }
]
}| Item | Fields and limits |
|---|---|
text | text (2000 chars), size (sm, md, lg), tone (default, muted) |
row | title (120), subtitle (300), meta (40), image, badge (24), date (YYYY-MM-DD, wall time, or ISO 8601 with offset), action, valid_until |
cards | layout (grid, carousel), cards[] (up to 24): title (120), subtitle (300), price (40), badge (24), image, code (40), action, valid_until |
stats | stats[] (up to 6): label (40), value (24) |
countdown | until (ISO 8601 with offset), label (120), done_text (120); repeating countdowns add ends and next |
accordion | entries[] (up to 30): title (200), body (2000) |
button | label (40), action, style (primary, secondary), show (counting before zero or at_zero while at zero) |
image | src, alt (300), ratio (1:1, 4:3, 3:4, 16:9), action |
divider | No extra fields |
table | columns[] (up to 4, 80 chars each), rows[][] (up to 30 rows, 80 chars per cell) |
choice | id, question (200), options[] (2 to 8): id, label (120); results, total, show_results (always, after_vote, never), closed, sign_in |
A document holds at most 40 items and 256 KB. All text is plain text (no HTML or Markdown) and all external URLs must use https://. Unrecognized items are skipped and strings over their character cap are truncated, so one bad item never blanks the block. Rows and cards with an ISO valid_until timestamp drop off automatically once that moment passes. A card’s code renders a discount code the Visitor can copy in one tap.
Actions are executed by the Home:
open_url:{ "type": "open_url", "url": "https://…", "label": "…", "sponsored": true }opens in a new tab (rel="noopener noreferrer", plussponsoredwhen marked).copy:{ "type": "copy", "text": "SAVE20", "label": "…" }copies the text and confirms to the Visitor.subscribe:{ "type": "subscribe", "label": "Notify me" }opens craving’s native email capture form. The Visitor becomes the Resident’s lead (lead_captureplan feature); no Visitor address is sent to your server.- Voting on a
choice: when a Visitor picks an option, craving POSTs{ "type": "choice", "block_id": "…", "installation_id": "…", "item_id": "…", "option": "…", "visitor": "…" }to yourblock.action_url(signed withX-Craving-Signature, 5-second timeout, 64 KB response cap).visitoris a per-installation pseudonymous digest. Return{ "item": { …updated choice item with results and total… } }or{}.
Refresh lifecycle: craving fetches content_url when a block is placed or edited, in the background after a page view when the cached document is older than block.refresh_seconds (300 to 86400, default 3600), and after you call POST /v1/blocks/refresh. Failed refreshes keep the last good document and back off exponentially (starting at 5 minutes, doubling up to refresh_seconds); documents not refreshed for 7 days stop showing. Referenced images are copied into craving storage so a Visitor’s browser never connects to your server.
Rules
- Visitors are anonymous to your block: you receive the installer, the block and its settings, never Visitor identities. Do not fingerprint or track Visitors.
- Never render payment or card forms inside a frame. All checkouts run on craving (Billing and payouts).
- Framed block URLs must allow embedding on craving (
frame-ancestors https://craving.com https://*.craving.com, and noX-Frame-Options: DENYorSAMEORIGIN). The automated reviewer verifies this. - Keep content safe for work. Adult content is allowed only on adult Homes, when the app’s audience is
adultorall. - Respect the
themehint; Homes default to a dark surface.
Stats
Each framed block session records a view (block_impressions) and each craving:track click event records a click (block_clicks). Both appear in the 30-day breakdown under Usage by day on your app page.