Use without a backend
Show tales on a page with no TaleArt server: you pass the zone JSON yourself, to the element or to one function. The Web SDK renders it exactly as it renders a zone it fetched, and sends nothing to the Delivery API.
When to use it
- A static site, a landing page, a prototype or a demo that must work with no server of yours or ours.
- An app that already has its stories in its own data, and wants the TaleArt look and viewer for them.
- Tests and screenshots, where a network call would be noise.
Choose the normal setup (the Web guide) when editors should change tales in Tale Studio without a deploy, or when you want analytics and poll results in the dashboard. Without a backend the JSON is part of your page: changing a tale means changing the JSON and publishing the page again.
The JSON
The input is exactly the body of GET /delivery/v1/zone: one zone with its display (frame) and its tale groups. The smallest useful zone is one bar with one group of two tales, a picture and a line of text:
{
"frame": {
"type": "bar",
"settings": {
"layout": "ring",
"size": "large"
}
},
"taleGroups": [
{
"id": "spring",
"name": "Spring",
"tales": [
{
"id": "spring-1",
"title": "Hills at dawn",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-hills.jpg"
}
},
{
"id": "spring-2",
"title": "A line of text",
"document": {
"canvas": {
"background": {
"type": "color",
"color": "#2b829f"
}
},
"elements": [
{
"id": "hello",
"type": "text",
"box": {
"x": 0.1,
"y": 0.42,
"w": 0.8,
"h": 0.14,
"rotation": 0
},
"a11y": {},
"props": {
"text": "Hello from a page with no backend",
"size": 0.06,
"weight": "bold",
"color": "#ffffff",
"align": "center"
}
}
]
}
}
]
}
]
}| Path | Meaning |
|---|---|
frame | The display. type is bar or banner, and settings are its options (the layout, the size, the banner variant). null shows nothing. |
taleGroups[] | The groups, in the order they show. Each needs an id (unique in the zone), a name (the title under its ring) and its tales. Optional: tags, tagMatch and audience for targeting, and cover. |
tales[] | A tale needs an id and a title and something to show: media (an image or a video) or a document (a canvas and its elements: text, shapes, buttons, polls, a countdown). |
media.url | Absolute (https://cdn.example.com/a.jpg), relative to the page (images/a.jpg) or a data: URI. |
theme, id, name, slug | Optional. Without a theme the display takes the page's look; set it, or use configureZone, to style it (Theme and fonts). |
The three calls
| Call | What it does |
|---|---|
element.data = zone | This element renders zone, an object or JSON text. Set it again to render again; set null to remove it. |
Taleart.setZoneData(name, zone) | Gives the zone named name its data, so every <taleart-view zone="name">, now or added later, renders it. A later call re-renders them; null removes the data. |
Taleart.validateZone(json) | Checks the JSON and answers { ok: true } or { ok: false, errors: [...] }. It renders and sends nothing. |
An element needs no zone key and no API URL. If more than one source is present the order is: the element's own data, then the data registered for its zone, then the network. All three also exist as module exports (setZoneData, validateZone) when you bundle the SDK from npm.
<script type="module" src="https://cdn.example.com/taleart/index.js"></script>
<taleart-view id="stories"></taleart-view>
<taleart-view zone="home-top"></taleart-view>
<script>
// 1. One element: an object, or the JSON text.
document.getElementById('stories').data = zoneJson;
// 2. By zone name: every <taleart-view zone="home-top">, now and added later. Call it again to re-render.
Taleart.setZoneData('home-top', zoneJson);
Taleart.setZoneData('home-top', null); // remove it
// 3. Check it first.
const result = Taleart.validateZone(zoneJson); // { ok: true } or { ok: false, errors: [...] }
</script>Live: a bar
This is the real Web SDK, loaded from this site, rendering the JSON below it with no key and no request. Tap a ring to open it; the second group's last tale has a poll that you can answer, and the answer stays on your device.
The zone this bar renders
{
"id": "docs-bar",
"name": "Docs bar",
"slug": "docs-bar",
"frame": {
"type": "bar",
"settings": {
"layout": "ring",
"size": "large",
"gap": 14
}
},
"taleGroups": [
{
"id": "dawn",
"name": "Dawn",
"tales": [
{
"id": "dawn-1",
"title": "Hills at dawn",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-hills.jpg"
}
},
{
"id": "dawn-2",
"title": "Meadow",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-meadow.jpg"
}
}
]
},
{
"id": "night",
"name": "Night",
"tales": [
{
"id": "night-1",
"title": "The city",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-city.jpg"
}
},
{
"id": "night-2",
"title": "A vote",
"media": null,
"document": {
"canvas": {
"background": {
"type": "color",
"color": "#1d2a4a"
}
},
"elements": [
{
"id": "night-poll",
"type": "poll",
"box": {
"x": 0.08,
"y": 0.3,
"w": 0.84,
"h": 0.34,
"rotation": 0
},
"a11y": {},
"props": {
"question": "Day or night?",
"options": [
{
"id": "day",
"label": "Day"
},
{
"id": "night",
"label": "Night"
}
],
"theme": "dark",
"view": "embed"
}
}
]
}
}
]
},
{
"id": "sea",
"name": "Sea",
"tales": [
{
"id": "sea-1",
"title": "The sea",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-sea.jpg"
}
}
]
}
]
}Live: a banner
The same call with a banner display, set from a registered name: Taleart.setZoneData('docs-banner', zone) and <taleart-view zone="docs-banner">.
The zone this banner renders
{
"id": "docs-banner",
"name": "Docs banner",
"slug": "docs-banner",
"frame": {
"type": "banner",
"settings": {
"variant": "carousel",
"aspectRatio": "16:9",
"autoplay": false,
"showDots": true
}
},
"taleGroups": [
{
"id": "b-hills",
"name": "Hills at dawn",
"tales": [
{
"id": "b-hills-1",
"title": "Hills at dawn",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-hills.jpg"
}
}
]
},
{
"id": "b-sea",
"name": "The sea",
"tales": [
{
"id": "b-sea-1",
"title": "The sea",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-sea.jpg"
}
}
]
},
{
"id": "b-meadow",
"name": "Meadow",
"tales": [
{
"id": "b-meadow-1",
"title": "Meadow",
"media": {
"kind": "image",
"contentType": "image/jpeg",
"url": "images/no-backend/art-meadow.jpg"
}
}
]
}
]
}Live: edit the JSON
Change the JSON on the left. It is checked with Taleart.validateZone as you type, and rendered with element.data as soon as it is valid. Break it on purpose, to see the messages.
The JSON is checked in your browser.
What is active, and what is not
With zone data the SDK makes no request to the Delivery API at all: no read of the zone, no analytics events and no posted answers. The rest works as with a fetched zone.
| Feature | With zone data |
|---|---|
| The bar, the banner and the full-screen viewer | Work as usual, with every layout and variant. |
| Tags, viewer properties and audience rules | Work: the SDK compares the rules in your JSON with setTags and setProperties. |
| User lists and the external user ID | Not used. The server decides user lists; with no server, put in the JSON the groups you want this visitor to see. |
| Frequency cap and the seen ring | Work: they are kept in this browser. |
Theme, configureZone, locale, strings and right-to-left pages | Work. |
| Hooks and DOM events | Work, with an empty zoneKeyPrefix. Use them to send your own analytics. |
| Analytics in the dashboard | Off. Nothing is sent, so nothing is counted. |
| Polls, quizzes, ratings and reactions | The visitor can answer and sees their own answer, kept on the device (localStorage). Nothing is posted, so there are no shared results: a poll shows the visitor's choice as 100%. |
| Countdowns, promo codes, buttons and links | Work: they run in the browser. |
| Pictures and video | Any URL the page can load: absolute, relative to the page or a data: URI. |
| Tale Studio, scheduling and the media library | Not part of it. You write or export the JSON yourself. |
| Invalid data | The same as a failed load: one console error that lists the problems, the loadFailed hook, the element's fallback. It never throws. |
Get the JSON
- Copy it from a real zone. Open the zone's Delivery API address in a browser tool or run
curlwith the zone key, and save the body. Media URLs in it point at the API's media: keep them, or replace them with your own.curl -H "Authorization: Bearer $ZONE_KEY" https://api.example.com/delivery/v1/zone > zone.json - Write it by hand, starting from the smallest zone above. The fields are those of the
DeliveryZoneschema in the API reference. - Let your editor help. The schema of the data is published at
schemas/zone.schema.json. Point a file at it with"$schema"as the first key (the SDK ignores it) and the editor completes the field names and flags the wrong ones:{ "$schema": "https://taleart.lempert.site/schemas/zone.schema.json", "frame": { "type": "bar", "settings": {} }, "taleGroups": [] }
Debug with validateZone
validateZone answers with one line per problem, each naming the path and what is wrong. It accepts the object or the text, so it also catches a missing comma. The SDK logs the same lines when it cannot render the data.
const result = Taleart.validateZone(text);
if (!result.ok) console.log(result.errors.join('\n'));
// taleGroups[0].tales[1].media.url: is missing (it must be text)
// taleGroups[1].tagMatch: must be "any" or "all", but is "some"
// the zone is not valid JSON (Unexpected token } in JSON at position 41)In a framework
Install the package (npm i @lempert/taleart) or load the script, then set the property. The element is a custom element, so each framework sets data the way it sets any property.
Plain HTML
<script type="module" src="https://api.example.com/sdk/v1/taleart.js"></script>
<taleart-view id="stories"></taleart-view>
<script>
fetch('/stories.json')
.then((res) => res.json())
.then((zone) => { document.getElementById('stories').data = zone; });
</script>React
import '@lempert/taleart';
import { useEffect, useRef } from 'react';
export function Stories({ zone }) {
const ref = useRef(null);
useEffect(() => { ref.current.data = zone; }, [zone]);
return <taleart-view ref={ref} />;
}Angular
<!-- import '@lempert/taleart' once, and add CUSTOM_ELEMENTS_SCHEMA to the component -->
<taleart-view [data]="zone"></taleart-view>Vue
<!-- import '@lempert/taleart' once, and list taleart-view in compilerOptions.isCustomElement -->
<taleart-view :data.prop="zone" />On Android and iOS
The native SDKs take the same JSON: the exact body of GET /delivery/v1/zone. Nothing is read from or sent to the API: no zone request, no analytics, and a poll answer is marked on the device only. Tags, properties, audience rules, the frequency cap, the theme, listener events (onLoaded and onLoadFailed, with an empty key prefix), right-to-left layouts, and the bar, banner and viewer behave as with a fetched zone. Media URLs must be absolute http(s) URLs. JSON that is not a zone is a failed read (logged once, onLoadFailed, the fallback shown), never a crash.
| Platform | Show the JSON | Check it |
|---|---|---|
| Compose | TaleartZone(zoneJson = json) | TaleartSdk.parseZoneJson(json) |
| Android view | view.zoneJson = json | the same |
| iOS | TaleartZoneView(zoneJson: json) | TaleartSdk.shared.parseZoneJson(json: json) |
Kotlin
// Compose or View, no key and no API URL
TaleartZone(zoneJson = ZONE_JSON)
taleartView.zoneJson = ZONE_JSON
when (val parsed = TaleartSdk.parseZoneJson(ZONE_JSON)) {
is ZoneParse.Success -> Log.d("TaleArt", "valid: " + parsed.zone.slug)
is ZoneParse.Failure -> parsed.errors.forEach { Log.w("TaleArt", it) }
}Swift
let zone = TaleartZoneView(zoneJson: zoneJson) // embed zone.viewController
let parsed = TaleartSdk.shared.parseZoneJson(json: zoneJson)
if let failure = parsed as? ZoneParseFailure { failure.errors.forEach { print($0) } }More in the Android guide and the iOS guide, and every member in the Android and iOS references.


What it looks like
Real screenshots of the live examples above, for when you read this page without scripts.



Taleart.setZoneData.
See also
- Web guide, the normal setup with a zone key.
- Web SDK reference, for the element, the functions and the errors.
- Targeting, for tags and audience rules in the JSON.