Developer docs
Connect your CMS, review questions and embed polls in your articles.
Connect your server once · Install the embed once · No wallet required
Get a key
Your publisher ID and private key
Connect a story
Select → generate → editorial review
Start participation
Install the embed and share results
01. Get your publisher key
Send the operator your newsroom name, article domain, logo URL and technical contact. The operator verifies your domain and privately issues your key.
Newsroom: [your newsroom]
Domains: https://news.example.com
Logo URL: [public HTTPS image URL]
Technical contact: [your developer]
Request: publisher ID and private server API keyKeep your integration key on the CMS server. Never include it in public code or embeds.
02. Connect one selected article
Submit stories selected through your CMS toggle or a leading [POLL] / [VOTE] headline marker. A marker alone does not connect an article: the CMS must call the API below.
import { Tokensensus } from './tokensensus.mjs';
const client = new Tokensensus({
apiKey: process.env.TOKENSENSUS_PUBLISHER_KEY,
});
// CMS background job: only after an editor selects this story.
const result = await client.submitArticle({
articleId: String(article.id),
url: article.canonicalUrl,
title: article.title,
body: article.plainText, // 200–40,000 characters
imageUrl: article.thumbnailUrl,
language: 'en',
pollEnabled: true,
});
// Review the draft in /publishers before publishing.
// result.article can be null when the article is skipped.Save the SDK and type file together. Replace article and placeholders with CMS values. Body length is 200–40,000 characters. Preparation can take up to 90 seconds, so run it separately from reader page requests.
Check source evidence, question and choices in the studio, then publish. Rejected stories remain private. Published choices cannot be changed.
Open publisher studio03. Add the embed below your article
Fill in the fields to generate your embed code. Use the article ID submitted in step 2.
<div data-tokensensus data-publisher="YOUR_PUBLISHER_ID" data-article-id="YOUR_CMS_ARTICLE_ID" data-lang="en"></div>
<script src="https://tokensensus.vercel.app/embed.js" defer></script>No API key is included. The widget stays hidden until publication. Ingestion sets question language; data-lang sets controls and notices without translating existing choices.
Using CSP, or is the widget missing?
Allow https://tokensensus.vercel.app in script-src, frame-src and connect-src. Check IDs and publication status. Do not retry generation failures (502) or quotas (429) on reader visits.
Installation checklist 0/5
A manual developer checklist. Checking items does not verify installation on the server.
Frequently asked questions
Can several articles share one question?
Yes. Reuse the existing question’s publisher ID and CMS article ID in the embed. Votes share one poll ID without another AI call. Original publisher and source attribution remain; per-placement reporting and automatic merging of similar questions are not supported. An editor should first check that wording, choices, timeframe and context match.
Does every story need a poll?
No. Only opted-in stories are processed. pollEnabled: false overrides markers. An embed does not call AI.
Where do images come from?
Register your logo URL and send the original thumbnail URL. Published questions appear on Tokensensus with publisher information.
Can market-price stories be used?
Yes. Review balanced choices grounded in the story, such as higher, lower or sideways, to collect reader opinions.
What are the usage limits?
Contact the operator for your newsroom’s allowance. On HTTP 429, stop retrying and check when requests can resume. Views and votes do not generate questions.
The kit includes the SDK, English/Korean guides and examples. Share the actual key through a separate secure channel.