Headless client
init() from @getrollout/js gives you the same data the widget uses, without any UI.
import { init } from '@getrollout/js'
const rollout = init({ projectKey: 'pk_live_…', apiUrl: 'https://api.rollout.so', token: () => fetch('/api/rollout-token').then((r) => r.text()),})
const unsubscribe = rollout.subscribe(({ status, announcements, unreadCount, hasMore, error }) => { // render your own UI})Options
Section titled “Options”| Option | Default | Description |
|---|---|---|
projectKey |
Required. Publishable key (pk_live_…). |
|
apiUrl |
Required. Base URL of the rollout API. | |
token |
Signed identity token, or a function returning one. Called once, then again after a 401. | |
user |
Unverified identity { id, org?, createdAt?, attrs? }. Ignored when token is set. |
|
refresh.onLoad |
true |
Load the feed immediately. |
refresh.onFocus |
true |
Reload when the tab becomes visible again. |
refresh.intervalMs |
0 |
Poll every n milliseconds; 0 disables polling. |
pageSize |
20 |
Announcements per page (at most 50). |
highlight |
false |
Also load the highlight to tease (state.highlight) with every refresh. |
fetch |
A custom fetch, e.g. for tests or server rendering. |
You must pass token or user; see Identity. With a token, user is ignored:
if the token function returns nothing, requests go out without an identity (and fail) rather
than falling back to an unverified user.
subscribe(listener) calls your listener right away and after every change. It returns a function
that unsubscribes. getState() returns the current state.
| Field | Description |
|---|---|
status |
idle, loading, ready or error. |
announcements |
The loaded announcements, newest first. |
unreadCount |
Unread announcements for this user, across all pages. |
hasMore |
Older announcements can be loaded with loadMore(). |
highlight |
The highlight to tease now, or null; see Highlight. |
error |
A RolloutError (status, code, message) when loading failed. |
Each announcement has:
| Field | Description |
|---|---|
id |
Announcement id (ann_…). |
title |
Title. |
publishedAt |
ISO timestamp. |
image |
Lead image or null: url (up to 1600px wide), thumbnailUrl (up to 320px), alt, width, height. |
tags |
Snippet categories in order: new, improved, fixed. |
highlight |
null, or one snippet to tease in a small card: snippetId, title, tag, text (optional teaser text), image (the snippet’s image, else the lead image). |
html |
Rendered body (hero, intro, snippets), without the title. |
markdown |
The same body as Markdown, or null for old announcements. |
text |
Plain text. |
read |
Whether this user has read it. |
Methods
Section titled “Methods”| Method | Description |
|---|---|
refresh() |
Reloads the feed, keeping pages loaded with loadMore(). |
loadMore() |
Appends the next page of older announcements. |
markRead(id) |
Marks one announcement read. Updates the state right away. |
markAllRead() |
Marks everything read. Updates the state right away. |
getAnnouncement(id) |
One announcement in full (loaded if it isn’t in the list). |
enableHighlight() |
Starts loading state.highlight, and loads it now. |
dismissHighlight() |
Closes the current highlight’s teaser for this user. |
destroy() |
Stops polling and removes listeners. |
markRead and markAllRead update the state before the request finishes; the next refresh
reconciles it if the request failed.
Highlight
Section titled “Highlight”With highlight: true (or after enableHighlight()), state.highlight holds the highlight of
the newest unread announcement that has one: announcementId, announcementTitle, title,
tag, text (the optional teaser text) and image. Build your own teaser from it:
rollout.subscribe(({ highlight }) => { corner.hidden = !highlight if (highlight) corner.querySelector('h3').textContent = highlight.title})closeButton.onclick = () => rollout.dismissHighlight()Dismissing hides the teaser on every device but leaves the announcement unread; the next highlight, if any, takes its place. Reading the announcement hides its teaser too.
Code blocks
Section titled “Code blocks”Code blocks in html arrive syntax-highlighted, as <pre><code class="language-ts hljs"> with
highlight.js token classes (hljs-keyword, hljs-string, …). Add any
highlight.js theme stylesheet to colour them; without one they render as plain code.
Errors
Section titled “Errors”Failed requests reject with RolloutError: status (HTTP status, 0 for network errors),
code (for example invalid_token, origin_not_allowed) and message. With a token function,
a 401 fetches a fresh token and retries once.
With the widget
Section titled “With the widget”Pass the client to the widget’s client property to share one connection, for example to show
your own unread badge next to the widget. See Widget → Your own trigger.