Analytics reference

What the zone's Analytics tab counts, how the Web SDK sends the events, what is stored and what is never sent, how to turn sending off, and the two API endpoints behind the numbers. For the steps to read the tab, see the Read your analytics guide.

Metrics

The Analytics tab shows these seven metrics for a period of the last 7, 30 or 90 days (UTC days, today included.). Each definition is the published one: the tab shows the same text.

Metric definitions
Metric	Definition
Impressions	Number of impression events.
Reach	Distinct visitors with at least one impression in the period.
Opens	Number of open events.
Tale views	Number of view events.
Clicks	Number of click events.
Engagement rate	Engaged visitors ÷ Reach, as a percentage, one decimal, where engaged visitors are the distinct visitors with at least one impression AND at least one open in the period (the same group, for a group's row). Engaged visitors are part of Reach, so the rate never exceeds 100. 0 when Reach is 0.
CTR (click-through rate)	Clicks ÷ Tale views, as a percentage, one decimal. 0 when there are no views.

Reach is distinct per row: the Reach of a total is not the sum of its rows.

The engagement rate is the visitors who both saw a group (an impression) and opened it (an open), divided by Reach. Read per group, each group's row counts its own impressions and opens.

Events

The Web SDK sends four event types. Each carries its type, its tale group's id, its tale's id (views and clicks only) and the time in UTC. The Delivery API accepts only these four (impression, open, view and click).

Events the Web SDK sends
Event	When it is sent	Ids it carries
`impression`	A tale group's circle or banner is half on screen for the first time in a render. The same moment as the `onGroupImpression` hook.	Group
`open`	The viewer opens the tale group.	Group
`view`	A tale is shown in the viewer. The same moment as the `onTaleShown` hook.	Group and tale
`click`	A tale's button, image button or swipe-up link is activated, whether or not the host cancels the navigation. The same moment as the `onActionClicked` hook.	Group and tale

An answer to an interactive component (a reaction, for one) is not an event: the responses store counts it, not the analytics store.

What is stored and what is never sent

Stored and not sent
Stored for each event	Never sent, never stored
The zone, the tale group and (for views and clicks) the tale; the event type; the time in UTC; and the visitor, as a hash: SHA-256 of the project id and the visitor id. The hash is per project, so the same visitor does not link across projects, and the raw visitor id is not stored.	The external user id, tags and user attributes; the IP address; the user agent; and anything else from the page. Raw events are kept 400 days, then deleted.

Turn sending off

Analytics are on by default. Turn them off for the whole page with the SDK's option, or for one element with its attribute. The element's attribute wins: any value other than off leaves the element to the option.

Taleart.init({ analytics: false });

<taleart-view zone-key="YOUR_ZONE_KEY" analytics="off"></taleart-view>

The option is analytics (default true) and the attribute is analytics. Both are in the Web SDK reference.

Batching and sending

The SDK keeps events in memory and sends them together: every 5 seconds while any wait, when 20 are waiting, and when the page is hidden. The page-hidden send uses navigator.sendBeacon, which cannot set headers, so the beacon carries the zone key as a key field and the visitor id as a visitor field of its body; the Delivery API accepts those two fields on this endpoint only. A failed send is retried once, then dropped without a message. A zone that failed to load sends nothing, and so does the Tale Studio preview.

Delivery endpoint

POST /delivery/v1/events takes a batch of events with a zone key. The SDK calls it; a server can call it too, with the same rules.

POST /delivery/v1/events
Authorization: Bearer tak_…
X-TaleArt-Visitor: 3f1c9a52-7d4e-4b8a-9c21-6e0f5a8d2b47
Content-Type: application/json

{
  "events": [
    { "type": "impression", "groupId": "…", "at": "2026-10-29T09:15:02.418Z" },
    { "type": "open", "groupId": "…", "at": "2026-10-29T09:15:09.007Z" },
    { "type": "view", "groupId": "…", "taleId": "…", "at": "2026-10-29T09:15:10.330Z" },
    { "type": "click", "groupId": "…", "taleId": "…", "at": "2026-10-29T09:15:18.764Z" }
  ]
}

Limits and answers of POST /delivery/v1/events
Rule	Value
Authorization	`Bearer tak_…`, the zone key. A site key, a revoked key or no key answers 401 `invalid_site_key`.
Visitor id	The `X-TaleArt-Visitor` header (a lowercase UUID), or the `visitor` field of a beacon. Missing or invalid answers 400 `visitor_id_required`.
Events per request	At most 50. More answers 400 `validation_failed`, and the body is at most 32 KB.
Accepted time	Not older than 7 days and not more than 1 hour in the future (UTC, `Z` required). An event outside the window is dropped.
Checked per event	The four fields only; a known type; a tale id for views and clicks, none for the others; and a group, and a tale, placed in the key's zone. An event that fails is dropped.
Rate limit	Per visitor: a burst of 30 requests, refilled at one request every 2 seconds. Over the limit answers 429 `rate_limited` with `Retry-After`.
Answer	202 with `{ "accepted": n, "dropped": m }`: the events kept and the events dropped.

Management endpoint

GET /zones/{zoneId}/analytics?period=7d|30d|90d returns a zone's metrics, for a project member. The period defaults to 30d. A zone the caller cannot reach, and an unknown one, answer 404 zone_not_found. The Analytics tab reads this endpoint.

Fields of the response
Field	Type	Meaning
`period`	String	`7d`, `30d` or `90d`.
`totals`	Object	The seven metrics of the period: `impressions`, `reach`, `opens`, `taleViews`, `clicks`, `engagementRate` and `ctr`. Rates are percentages with one decimal.
`daily`	Array	One entry per UTC day, oldest first: `date` (`YYYY-MM-DD`), `impressions`, `clicks`, `opens` and `taleViews`. A day with no events is zero.
`groups`	Array	One row per tale group with events, most impressions first: `groupId`, `name` and the seven metrics for that group.
`tales`	Array	One row per tale with views or clicks, most views first: `taleId`, `name`, `groupId`, `taleViews`, `clicks` and `ctr`. Its `impressions`, `reach`, `opens` and `engagementRate` are `null`: they name a group, not a tale.

Reach is distinct per row: the Reach of a total is not the sum of its rows. Days and rows are counted in UTC.

Retention and limits

Raw events are kept 400 days, then deleted by the retention job. The metrics are counted from them.
The Web SDK sends events. The Android and iOS SDKs do not send analytics events yet, so their visitors are not counted.
There is no per-group endpoint for analytics yet: the rows of GET /zones/{zoneId}/analytics are the group figures.

Edit this page on GitHub