Gist for Web

Build beautiful in-app flows with no code and deliver them instantly to your app/website. Zixflow

🚀 Quick Start

Installation

npm install zixflow-gist-web

📌 Embedded messages

An embedded message is one the host page supplies directly, rather than one delivered through a campaign or broadcast. The message travels in the page's own markup, so it renders on a landing page that has no other Zixflow setup.

Declare a container and a payload block:

<div data-zixflow-embed="emb_7Fq2xk"></div>
<script type="application/json" data-zixflow-embed-payload="emb_7Fq2xk">
  {
    "v": 1,
    "embedId": "emb_7Fq2xk",
    "display": { "frequency": "untilDismissed" },
    "message": {
      "messageId": "gist-html-9f2c8b",
      "properties": { "gist": { "encodedMessageHtml": "H4sIAAAA…" } }
    }
  }
</script>

Gist.mountEmbeds() renders every block on the page; Gist.embed(payload) renders one programmatically. Both initialize the SDK in embed-only mode when nothing else has set it up, and both are safe to call more than once — an embed already rendered on the page is skipped, so a host can call them again after injecting markup.

frequency decides how often the message comes back:

| Value | Behaviour | | ------------------ | -------------------------------------------------------------------------------- | | always (default) | Renders on every page load; closing hides it for that load only. Stores nothing. | | untilDismissed | Once closed, stays hidden. A snooze is not a close — see below. | | onceEver | Renders once per browser. |

A payload also carries the reporting identity for the message — contentId and templateId, both integers, in properties.gist, exactly as a broadcast carries its own. The content pipeline requires both and drops events without them, so an embed published without them renders but reports nothing (the analytics layer logs when that happens).

A snooze is not a dismissal: gist://snooze?showIn=<minutes> hides the message and shows it again once the time is up, whatever the frequency rule says.

Every embed's state lives in one key, gist.web.embeds: the ids that may not render, mapped to true for never again or to the moment a snooze makes them eligible again. Presence is the whole answer, so the lot clears in one call:

localStorage.removeItem('gist.web.embeds'); // or Gist.resetEmbed(embedId) for one

The record carries a rolling 365-day expiry, refreshed once on any page load that reads it — so onceEver and a permanent dismissal hold for as long as the visitor keeps coming back, while a record nobody has visited for a year is collected. Any storage failure resolves to "render", so a blocked store can never leave a hole in the customer's layout.

Embed-only mode (Gist.setup({ embedOnly: true })) starts none of the delivery machinery: no user queue, SSE, guest session, inbox or preview session, and user tokens are ignored. Leave it unset on a page that also receives in-app messages — embeds and queue-delivered messages work side by side.

Gist.mountEmbeds() initializes embed-only mode only when the page actually declares an embed, so a snippet can call it on pages that have none without consequence. On a page that has both embeds and in-app messaging, still call setup() first — otherwise the auto-init wins and delivery never starts (the SDK warns when that happens).

🧪 Development

Local Testing

1. Clone the repository
2. Install dependencies: npm install
3. Start the dev server: npm start
4. Navigate to: http://127.0.0.1:8081/examples/

Build Locally

npm run build:prod

Scripts

• npm test - Run tests
• npm run typecheck - Type check the project
• npm run lint - Lint the codebase
• npm run format - Format code with Prettier

📦 Releases

Releases are published to npm (zixflow-gist-web) from a maintainer machine with ./release.sh. The Zixflow web SDK (@zixflow/analytics-browser) installs it from npm, so there is no CDN step.

1. Merge the PR into develop and pull it.
2. Log in to npm as an account that can publish zixflow-gist-web (npm whoami → zixflowapps).
3. Run ./release.sh X.Y.Z — patch for fixes, minor for features, major for breaking changes.
4. The script checks the npm login, the branch, a clean tree and that the tag/version are unused; sets the version; runs npm ci, lint, typecheck, tests and build:prod; shows the package contents; asks before npm publish; then commits the version, tags X.Y.Z and asks before pushing.

The Visual Inbox renders with @zixflow/jist.