Choosing an embed mode
POLST exposes five embedding surfaces. They share the same resource model, the same authentication layers, and the same data shapes — they differ only in how the polst reaches the host page.
1. Iframe
Section titled “1. Iframe”What it is: A pre-built polst page loaded inside an <iframe> via a short
snippet the brand pastes into any webpage or CMS.
Who it’s for: Content publishers placing a polst in an article without touching code — blog posts, newsletters, help centres, landing pages built in a CMS.
Tradeoff: Fastest to deploy. The polst sits in a fixed frame, so it can’t flow with the surrounding layout the way a native element would.
2. JS widget
Section titled “2. JS widget”What it is: A script tag that renders a polst directly into the host page’s DOM — not inside a frame. Fully themeable and styleable by the brand.
Who it’s for: Brands that run their own website and want polsts to look indistinguishable from the rest of the site.
Tradeoff: Needs one line in the page template rather than just a pasted snippet. In return, the polst becomes a first-class element of the page.
3. JS SDK
Section titled “3. JS SDK”What it is: A published npm package (@polst/sdk) giving a brand’s developers
programmatic access to fetch polsts, cast votes, and render widgets inside their
own React, Next.js, or Node applications.
Who it’s for: Brands with an in-house engineering team building bespoke experiences — voting hubs, campaign microsites, custom dashboards, internal tooling.
Tradeoff: Requires engineering time, but delivers complete control and is the foundation for the most sophisticated integrations.
4. Native mobile SDKs (iOS, Android, React Native)
Section titled “4. Native mobile SDKs (iOS, Android, React Native)”What they are: First-party libraries for Swift, Kotlin, and React Native that render polsts as native views inside mobile apps. Not a WebView wrapper.
Who they’re for: Brands with their own mobile apps that need a polst to feel like a first-party feature of the app.
Tradeoff: Largest integration lift on the brand side and the largest build on ours. Also the only path to a truly native mobile experience and the strongest commercial moat in that segment.
5. REST API
Section titled “5. REST API”What it is: The HTTP interface every other mode is built on top of. Brands can read polsts and campaigns, create and update them, cast votes, pull analytics, and receive webhook notifications when votes happen.
Who it’s for: Server-side and tooling integrations — CMS content pipelines, data warehouses, CRM automation, agency tools managing multiple brands.
Tradeoff: Lowest level of the stack. Fewest customers touch it directly, but it powers everything else and unlocks use cases no UI surface could anticipate.
Cheat sheet — when to recommend which
Section titled “Cheat sheet — when to recommend which”| Customer profile | Recommend |
|---|---|
| Content publisher, CMS user, marketer — “just give me a snippet” | Iframe |
| Brand website owner who wants polsts to match the site exactly | JS widget |
| Engineering team building a custom voting experience | JS SDK |
| Brand with a mobile app wanting a native feel | iOS / Android / React Native |
| Agency, data team, backend integration, webhooks | REST API |
Brands typically use several modes in combination: a widget on the website, a native SDK inside the mobile app, and REST webhooks piping votes into their CRM.
- Authentication & device identity — how each mode authenticates and votes.
- Data shapes — the JSON every mode returns.