window.openArtifacts. Polls, trackers, and checklists all work this way. The data belongs to the artifact, not a version, so a new version sees the same data.
Ready and theme
openArtifacts.ready is a promise that resolves once the viewer shell has connected; wait for it before your first call. Outside the viewer, with no shell, it resolves at once.
openArtifacts.theme is "light" or "dark". It starts from the viewer’s system setting and follows the shell’s theme once it connects. onTheme(callback) calls back whenever it changes and returns a function that stops listening.
Capabilities
An artifact declares what it uses when it’s published, for examplecapabilities: { db: true, viewer: true }. Calls to anything it didn’t declare are rejected.
Shared data: db
db.collection(name) returns a collection with:
get(id)to read one document, ornulllist({ cursor, limit })andquery(filter)to read many. Each returns a page,{ items, nextCursor }; passnextCursorback ascursorfor the next page.query({ where, orderBy, order, limit, cursor })filters on equal values and sorts by one field. WithwhereororderBy, it reads the whole collection, so it works only while the collection holds up to 2 MB; past that it fails withquery_too_large. For bigger data, uselist()and filter in the page, or split it into smaller collections (for example, one per day).set(id, doc),update(id, patch), anddelete(id)to writesubscribe(callback)for live updates when anyone changes the collection. It returns a function that unsubscribes.
{ id, data, updatedAt, updatedBy }, with your value in data.
Each subscribe callback gets { docs, deleted }: the documents that changed and the ids of those deleted. If the live connection drops and reconnects, changes may have been missed, so the callback gets { docs: [], deleted: [], resync: true } instead. On resync, refetch with list() or query().
If the live connection is refused or keeps failing, the callback gets { docs: [], deleted: [], offline: true }, once per outage: live changes are paused. Tell the viewer (for example, “Live updates paused. Reload to retry.”). When the connection comes back, the callback gets resync.
The viewer: viewer
viewer.get() returns { email, name }, or null for an anonymous viewer of a public artifact.
viewer.anonId() returns an anonymous viewer’s id on an artifact whose viewers can change its data (dataWriters: "viewers"), and null otherwise (logged-in viewers included).
Anonymous ids
On a public artifact that lets viewers change its data, each anonymous browser gets an id fromviewer.anonId(), so a game or poll can tell two anonymous players apart. Their documents carry updatedBy: "anon:<anonId>". Only documents written before anonymous ids existed still say "anon".
- It belongs to one browser on one device. Another browser or device gets a different id, and clearing site data resets it.
- Each artifact sees a different id for the same browser, so ids can’t be matched across artifacts.
- It is not a person or an account, so don’t treat it as proof of who someone is.
- It is signed by the server: no one can forge someone else’s id, but anyone can reset their own.
- It expires after a fixed period, but a write after about half of that period renews it with the same id, so a guest who keeps using the page keeps their id. An expired (or legacy) token is never renewed: the browser’s next write gets a new id, and it can no longer edit or delete comments it wrote under the old one (they stay visible with their display name). This is how a leaked token stops working.
- It is only issued on artifacts with
dataWriters: "viewers". Logged-in viewers never get one.
anonId is a label, not a permission. Any anonymous viewer can still overwrite or delete any document, so use it to show who did what (for example, a seat claimed by anonId) and expect conflicts.
Per-viewer data: storage
storage keeps documents keyed to the current viewer, such as which boxes they ticked, with get(key), set(key, value), delete(key), and list(), which returns the viewer’s keys.
Who can write
- Anyone who can view the artifact can read and change its live data.
- Set
dataWriters: "editors"to limit writes to its editors. Other viewers can still read, and their writes fail withdata_editors_only. - Writes from anonymous viewers of a public artifact are rate-limited per IP address.
Public live pages checklist
Before you share a public page that writes data, check each item:- Published public with every capability the page calls (
db,viewer). Anyone who can see it can change its data by default; a page only its editors or the owner’s agent should change (a dashboard, a scoreboard fed by an agent) getsdataWriters: "editors". - Every write has a rejection path the visitor can see:
data_editors_onlyorunauthorized(show the page as read-only),capability_denied,rate_limited,quota_exceeded,no_shell, and a generic “didn’t save” for anything else. Never catch and ignore a write. - The visitor’s id comes from
viewer.anonId(), read once at start and retried a few times if it rejects. A made-up fallback id changes on reload, so the visitor loses their vote or seat. - Two tabs of one browser share one
anonId: treat them as the same visitor. - Anonymous writes are limited per network, shared by everyone behind it (an office, a classroom). Write on user actions only.
- The page subscribes, refetches when
resyncis true, shows that live updates are paused whenofflineis true, and adopts the doc its own write returns. - Tested as an anonymous visitor in two separate browsers (not two tabs): writes show up in both, a refused write shows its message, and the page works at phone width.
Limits
Errors
Every call returns a promise. A failed call rejects with an error that has acode and a message:
Handle
no_shell by showing the page without live data:
How it works
The artifact runs in a sandboxed iframe with no credentials. Each call goes bypostMessage to the viewer shell around it, which checks the call and makes it with the viewer’s session. Opened outside the viewer, the artifact has no shell, so every call rejects at once with no_shell.
Live data works on the page the viewer first opens. If the artifact navigates its own frame to another page, for example through a link to another of its files, calls on that page fail with no_shell, and reloading the viewer restores them. If a multi-page artifact needs live data, switch views within one page instead of linking between files.
Links: a link to another site, or to another artifact by its /a/<id> page, takes target="_blank" rel="noopener" and opens in a new tab. A link to another of the artifact’s own files is relative and takes no target: it loads in the frame, where live data stops (see above). Never link the dashboard or settings pages, or another artifact’s or version’s /p/ or /c/ URL: a plain one is refused with a notice, and with a target it opens instead, landing on the wrong page.