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"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
What each part of the zone means
PathMeaning
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

The calls for zone data
CallWhat 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.

Loading the Web SDK…

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.

The result

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.

Features with and without a backend
FeatureWith zone data
The bar, the banner and the full-screen viewerWork as usual, with every layout and variant.
Tags, viewer properties and audience rulesWork: 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 ringWork: they are kept in this browser.
Theme, configureZone, locale, strings and right-to-left pagesWork.
Hooks and DOM events Work, with an empty zoneKeyPrefix. Use them to send your own analytics.
Analytics in the dashboardOff. 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 linksWork: they run in the browser.
Pictures and videoAny URL the page can load: absolute, relative to the page or a data: URI.
Tale Studio, scheduling and the media libraryNot 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 curl with 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 DeliveryZone schema 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.

The calls on Android and iOS
PlatformShow the JSONCheck it
ComposeTaleartZone(zoneJson = json)TaleartSdk.parseZoneJson(json)
Android viewview.zoneJson = jsonthe same
iOSTaleartZoneView(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.

The Android bar drawn from inline JSON on an emulator, with no backend running.
Android emulator: the bar from inline JSON, nothing listening on the API.
The iOS bar drawn from inline JSON on the simulator, with no backend running.
iOS simulator: the same zone JSON.

What it looks like

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

A bar of three rings with the groups Dawn, Night and Sea, each drawn from a picture in the zone JSON: warm hills, a night city and a blue sea.
The live bar: three groups from inline JSON, no zone key and no request.
The full-screen viewer open on the Dawn group: a hills picture, two progress segments, the group name, pause and close buttons.
Tapping a ring opens the same full-screen viewer as with a fetched zone.
A banner slide of the hills picture with the title Hills at dawn and a Watch button, previous and next arrows and three dots.
The live banner, from the zone registered with Taleart.setZoneData.
The editor with broken JSON: a red message says Not valid, 3 problems, and lists each path with what is wrong, beside the last valid render.
validateZone on broken JSON: each line names the path and the problem, and the last valid render stays.

See also