Web SDK reference

The Web SDK (@lempert/taleart): the element, the page options, the functions, the texts, the hooks and the DOM events, and what happens when something goes wrong. For the steps, read the Web guide.

The element

Loading the SDK registers <taleart-view>. Each attribute has a property of the same meaning, named in camel case.

Attributes of <taleart-view>
Attribute	Property	Required	Type and meaning
`zone-key`	`zoneKey`	Yes	The zone's key, `tak_…`, issued in the dashboard. It names the zone, so the element needs no slug. Without it the element renders nothing.
`api-url`	`apiUrl`	No	The TaleArt API origin. Default: the page's `apiUrl` option, else the origin the script loaded from.
`locale`	`locale`	No	This element's locale (BCP 47, such as `he-IL`). Default: the page's `locale` option, else the page's `lang`, else `en`.
`theme`	`theme`	No	Theme fields for this element only: JSON in the attribute (a JSON object), an object in the property. A field left out falls through to the next source (see the theme section of the SDK's README).
`fallback`	`fallback`	No	What the element shows when its zone fails to load: `none` (default, nothing) or `message` (the SDK's text and a retry button). A child with `slot="fallback"` is shown instead when there is one.
`frequency`	`frequency`	No	How often a viewer sees a tale group: `once`, `daily`, `weekly`, or a whole number from 1 to 50 (hidden after that many views). Default: none. Counted in this browser only.
`analytics`	`analytics`	No	`off` stops this element's impression, open, view and click events. Any other value, or none, leaves it to the SDK's `analytics` option.
`dir`	`dir`	No	`ltr` or `rtl` sets this element's reading direction; `auto` (the default) takes the page's. The Web guide's Right-to-left section shows what turns.

Properties without an attribute
Property	Meaning
`zone`	The zone's slug, such as `home-top`, from the response. Set it only to name the zone for `configureZone` when the response does not carry the slug.
`strings`	This element's texts, per locale or flat, added to the page's `strings`. This element's texts win.
`hooks`	This element's hooks. They are called before the page's `hooks`.

The element's method retry() reads the zone again after a failed load. The button of fallback="message" calls it.

The props of a tale's elements, such as a countdown's endsAt, a promo code's code or a reaction's emojis, are set in Tale Studio, not on this element. Their types and limits are on the Interactive components page.

Taleart.init options

init(config) sets the page's options, before or after the elements connect. Every option is optional: an option left out keeps its value, and an element attribute overrides the option. null clears locale, strings, theme, externalUserId, tags, properties, hooks and frequency; fallback: null means none, analytics: null means on, and dir: null means auto. An invalid option logs one console warning that names it and keeps its value.

Options of Taleart.init
Option	Type	Default	Meaning
`apiUrl`	string	The origin the script loaded from	The TaleArt API origin. Needed with the npm package, which has no script origin. An element's `api-url` wins.
`locale`	string or null	`document.documentElement.lang`, then `en`	The locale of the SDK's texts (BCP 47). An element's `locale` wins.
`strings`	object or null	None: the SDK's English texts	Texts per locale, such as `{ he: { … } }`, or flat for every locale. See the strings table below.
`theme`	theme object or null	None: the project's theme	Theme fields for every element. A zone's `configureZone` theme and an element's own theme win over it.
`externalUserId`	string or null	None	The viewer's external user ID, for the user lists of the Audience page: an opaque ID, matched exactly, never an email address or a phone number.
`tags`	array of strings or null	None: every group shows	The viewer's targeting tags. Matched ignoring case and surrounding spaces. Same as `setTags`.
`properties`	object or null	None: every group shows	The viewer's properties for audience rules: a flat object of name to text, number, boolean or list of text. Same as `setProperties`. Never sent to TaleArt.
`hooks`	object or null	None	Hook functions for every element. See the hooks table below.
`fallback`	`'none'` or `'message'`, or null	`none`	What every element shows when its zone fails to load: nothing, or the SDK's text and a retry button. An element's `fallback` wins.
`frequency`	Number from 1 to 50, `once`, `daily`, `weekly`, or null	None: every group shows	How often a viewer sees a tale group, counted in this browser. An element's `frequency` wins.
`analytics`	`true` or `false`, or null	On	Whether elements report impressions, opens, tale views and clicks to the TaleArt API. An element's `analytics` attribute wins.
`dir`	`auto`, `ltr`, `rtl`, or null	`auto`	The reading direction of every element: `auto` takes the page's. An element's `dir` attribute wins.

Exported functions

The module (import … from the script's URL, or the npm package) exports the functions below. The script also sets a global Taleart object with the same functions, except getConfig.

Exports of the Web SDK
Export	Signature	Meaning
`init`	`init(config)`, returns nothing	Sets the page's options (above). Calling it again changes only the options it names.
`getConfig`	`getConfig()`	Returns every option with the value the SDK uses now. Module export only, not on the global object.
`configureZone`	`configureZone(zone, options?)`	Sets the theme of the zone with this slug: `options.theme`, the same fields as the theme option. `configureZone(zone)` with no theme removes it. Import it from exactly the script's URL.
`setExternalUserId`	`setExternalUserId(id)`	The same as `init` with `externalUserId`. Pass `null` after sign-out.
`setTags`	`setTags(tags)`	The same as `init` with `tags`. Rendered elements show the matching groups at once.
`setProperties`	`setProperties(properties)`	The same as `init` with `properties`. Pass `null` to clear them. Rendered elements show the groups that pass at once.
`setProperty`	`setProperty(name, value)`	Sets one property and keeps the others. A `null` value removes it. With no properties set yet, `setProperty(name, null)` changes nothing.
`defineTaleartElement`	`defineTaleartElement(tag?)`	Registers the element under `tag` (default `taleart-view`). Loading the SDK already does this.
`TaleartElement`	class	The custom element's class, for `instanceof` checks and typings.
`TALEART_ELEMENT_TAG`	`'taleart-view'`	The element's tag name.

Locale and strings

A text is looked up under the full locale (he-IL), then its language (he), then the flat strings option, then English. A key that nobody defines shows English, never the key itself. A {name} in a text is filled in by the SDK. The keys below are the SDK's texts; the English column is the default. Three defaults start with a space, so they follow a number or a name in a sentence.

Text keys of the SDK and their English defaults
Key	English default
`viewer.close`	Close
`viewer.play`	Play
`viewer.pause`	Pause
`viewer.previousTale`	Previous tale
`viewer.nextTale`	Next tale
`viewer.previousGroup`	Previous
`viewer.nextGroup`	Next
`viewer.previousGroupName`	Previous group: {name}
`viewer.nextGroupName`	Next group: {name}
`viewer.progress`	{group}, tale {tale} of {count}
`viewer.taleFallback`	Tale {number}
`banner.label`	Banner
`banner.carousel`	carousel
`banner.slide`	slide
`banner.slideOf`	{index} of {count}
`banner.previousSlide`	Previous slide
`banner.nextSlide`	Next slide
`banner.showGroup`	Show {name}
`banner.stopRotation`	Stop automatic slide show
`banner.startRotation`	Start automatic slide show
`banner.watch`	Watch
`banner.dismiss`	Dismiss banner
`bar.seen`	{name}, seen
`bar.story`	{count} story
`bar.stories`	{count} stories
`bar.newStory`	{count} new story
`bar.newStories`	{count} new stories
`bar.noNewStories`	No new stories
`load.failed`	Stories could not be loaded.
`load.retry`	Try again
`links.newTab`	(opens in a new tab)
`poll.voted`	You voted {label}.
`poll.chose`	You chose {label}.
`poll.previewNotRecorded`	Votes are not recorded in the preview.
`poll.failed`	Your vote could not be sent. Try again.
`poll.resultsAfterVote`	Results appear after you vote
`poll.results`	Results
`poll.vote`	{count} vote
`poll.votes`	{count} votes
`quiz.answered`	You answered {label}.
`quiz.right`	Right! You answered {label}.
`quiz.wrongAnswer`	Wrong: you answered {label}. The correct answer is {correct}.
`quiz.correct`	correct answer
`quiz.wrong`	wrong
`quiz.previewNotRecorded`	Answers are not recorded in the preview.
`quiz.failed`	Your answer could not be sent. Try again.
`rating.sliderLabel`	Your rating
`rating.valueText`	{value} out of {max}
`rating.ratedValueText`	You rated {value} out of {max}
`rating.send`	Send rating
`rating.sent`	You rated {value}.
`rating.previewRated`	You rated {value}. Ratings are not recorded in the preview.
`rating.failed`	Your rating could not be sent. Try again.
`rating.summary`	Average {average} from {total} {count}
`rating.singular`	rating
`rating.plural`	ratings
`countdown.ended`	Ended
`countdown.days`	Days
`countdown.hours`	Hours
`countdown.minutes`	Min
`countdown.seconds`	Sec
`promo.copy`	Copy
`promo.copied`	Copied
`promo.copyFailed`	Could not copy. Select the code and copy it yourself.
`reaction.count`	Reactions: {count}
`reaction.failed`	Your reaction could not be sent. Try again.
`preview.stop`	Stop preview
`preview.size.small`	Small
`preview.size.default`	Default
`preview.size.large`	Large

Hooks

Hooks are set with init({ hooks }) for every element, or with an element's hooks property for one. The element's hook runs first, then the page's. Each hook gets one event object with name, zoneKeyPrefix (the first 8 characters of the key: the full key is never in an event) and zoneSlug, plus the fields in the table. A hook that throws is logged with console.error, and the viewer keeps going.

Hooks
Hook	When it fires	Payload fields	Cancelable
`onLoaded`	The zone was read. Once per load.	none	No
`onLoadFailed`	The zone could not be read: a refused, unknown, rotated or revoked key, a network failure, a bad answer.	`error`: the message	No
`onGroupImpression`	A group's bar item or banner slide first is half on screen. Once per group per load.	`group`: `id`, `name`, `index` (from 0)	No
`onPresented`	The full-screen viewer opened on a group.	`group`	No
`onTaleShown`	A tale came on screen in the viewer.	`group`; `tale`: `id`, `index` (from 0 in the group), `title`	No
`onActionClicked`	A button, an image button or the swipe-up link was activated, before it navigates.	`group`, `tale`; `component`: `id`, `type`; `url`, `newTab`; `preventDefault()`, which stops the navigation	Yes
`onUserInteracted`	The server accepted a poll, quiz, rating or reaction answer.	`group`, `tale`; `component`: `id`, `type`, `value`	No
`onComponentEvent`	A component of a tale did something: a countdown `ended`, a promo code was `copied`, a poll, quiz, rating or reaction answer was `selected` (it fires with `onUserInteracted` for an answer).	`groupId`, `taleId`, `component` (the element type, such as `countdown`), `action`, `value` (the promo code, the option id, the answer id, the rating's number or the reaction's emoji, when there is one)	No
`onDismissed`	The viewer closed.	`group`	No
`onGroupCapped`	The frequency cap left a tale group out of the display. Once per group per render.	`groupId`, `rule` (the cap: `once`, `daily`, `weekly` or a number)	No
`onEvent`	Every event above, in one stream. Its argument is the event itself.	The same as the event	Only action clicked, as above

DOM events

Each event is also a DOM event on the <taleart-view> element: it bubbles and is composed, and its detail is the event's payload (the same fields as the hook, with name omitted). The name is taleart: plus the event's name in kebab case. Only taleart:action-clicked can be canceled, with preventDefault() on the event.

DOM events on the element
Event	Hook	Cancelable
`taleart:loaded`	`onLoaded`	No
`taleart:load-failed`	`onLoadFailed`	No
`taleart:group-impression`	`onGroupImpression`	No
`taleart:presented`	`onPresented`	No
`taleart:tale-shown`	`onTaleShown`	No
`taleart:action-clicked`	`onActionClicked`	Yes
`taleart:user-interacted`	`onUserInteracted`	No
`taleart:component-event`	`onComponentEvent`	No
`taleart:dismissed`	`onDismissed`	No
`taleart:group-capped`	`onGroupCapped`	No

Errors and edge behaviour

What the SDK does when something goes wrong
Situation	What happens
The zone key is missing, refused, rotated or revoked	The element renders nothing and logs one console error for it. Load failed fires.
A rate limit (HTTP 429) or a network failure	The element renders nothing and logs one console error. A reload later shows the zone again.
An invalid `init` option	One console warning names it, and the option keeps its value.
An invalid `fallback` or `frequency` attribute	One console warning names it, and the page's option (or none) applies.
The zone cannot be loaded, and the element has a `slot="fallback"` child or `fallback="message"`	The element shows the child, or the SDK's text and a retry button. `retry()` reads the zone again.
An invalid external user ID	One console warning, and no ID is sent.
An invalid theme field, or a `theme` attribute that is not a JSON object	The field, or the attribute, is ignored with one console warning, and the next source's value applies.
`configureZone` without a zone slug	One console warning, and the call is ignored.
An element with the old `site-key` attribute	One console warning, and nothing is placed with it. Use the element with `zone-key`.
A hook throws	The error is logged with `console.error`. The viewer keeps going.
A button's or the swipe-up link's destination is not an absolute `http` or `https` URL of at most 2,048 characters	The SDK does not draw that link.
The page sets no tags, or no external user ID	Every group shows, except those with user lists, which need the ID.

Edit this page on GitHub