@blotout/qinto-sdk-browser
v0.1.22
Published
Qinto browser SDK: the cookie-backed WebSocket client for the identity graph, and the source of the /q.js tag. Zero runtime dependencies.
Readme
@blotout/qinto-sdk-browser
The Qinto browser client. It sends events, identity, and consent from your page to your own Qinto host over one WebSocket connection, and gives you a promise per call that settles when the edge accepted it. Zero runtime dependencies.
Why we built it
A page normally carries one script per vendor: one for the ad platform, one for analytics, one for the CRM. Each is a separate connection to a separate company, a separate copy of your tracking code, and a separate thing to keep working.
Qinto turns that around. Your site sends each action once, to a Qinto host on your own domain. The edge resolves who the visitor is, applies the consent that visitor gave, and fans the action out server-side to every app the site has installed. Adding or removing a destination is a change in the Qinto platform — not a change in your page.
This package is the client for that connection:
- First-party. The socket goes to your own hostname, and the visitor id is a first-party cookie your Qinto host sets. No vendor origin, no third-party pixel.
- One integration, not one per vendor. Destinations are installed on the site; your page never learns their names.
- Acknowledged. Every method returns a promise that settles when the edge accepted the action, so you can
awaitaPurchasebefore you navigate away from the page. - Typed, and dependency-free. The types ship with the package, and installing it pulls in nothing else.
If you would rather paste a <script> tag than bundle a client, you do not need this package: the Qinto platform gives
you a snippet built from this same source. Install the package when you build your site — an SPA, a framework, a
TypeScript app — and want the client in your bundle. The tag lists what differs.
Install
npm i @blotout/qinto-sdk-browserConnect
Call init once, where your app starts. Nothing to await, nothing to keep:
import { init } from '@blotout/qinto-sdk-browser'
init({ destination: 'https://q.example.com' })Then import the calls you need from any file:
import { track } from '@blotout/qinto-sdk-browser'
await track('PageView')destination is your site's Qinto host — the same origin the platform's snippet loads /q.js from. The Qinto platform
shows it on the site's snippet page: your own mapped hostname (q.example.com), or the site's development URL while
DNS is still pending.
| Option | Default | What it does |
| --- | --- | --- |
| destination | — | Required. The origin of your Qinto host. |
| globalName | qinto | The window property this instance lives on. Change it when the page already has a window.qinto, or to run a second host. |
| onError | — | Receives connection errors that belong to no single call — a dropped socket, an unreadable frame. |
| requestTimeoutMs | 10000 | How long one call waits for its acknowledgement before it rejects with QintoTimeoutError. |
| pageContext | — | A function that names the real page when the client runs in a sandboxed frame. See Sandboxed pages. |
The instance lives on window[globalName], and every call goes through it. A call made before init has connected
waits there and is sent, in order, once the connection is open — so a component can track on mount without knowing
whether init has finished. If that first connection fails, init rejects and so does every call that was waiting.
init does two things, in order. It loads the browser code of the apps the site installed from
<destination>/q.js?tag=0 — the same script the snippet loads, minus the client this package already is — and then opens
the connection. It resolves, to the same handle client(globalName) returns, once both are done, so the first call you
make already runs through every app. A page with a Content Security Policy must allow the destination in
script-src (for /q.js) and wss://<destination host> in connect-src (for /open): an https: source never
matches a wss: URL, and a blocked socket leaves init pending with every queued call.
That wait is capped at three seconds, because your events matter more than the apps. A script that is still loading at
that point no longer holds init: the client connects, your calls go out, a line in the console says so, and the apps
activate the moment the script lands. A script that fails to load is logged the same way and leaves the site's browser
apps off for this page. After the first connection the client reconnects on its own with an exponential backoff up to
30 seconds; a call made while the socket is down waits in a queue and is sent on the next open, up to its timeout.
Call init once per page. A second init on a name that is already running rejects with QintoError rather than run
every app twice. If the page pasted the snippet as well, init takes over its global: the calls the snippet buffered are
sent by this client, and the tag skips its own boot.
init runs in a browser only. On a server it throws QintoEnvironmentError — every reconnect there would mint a new
anonymous visitor. Use @blotout/qinto-sdk-server instead.
A second host
A page that sends to two Qinto hosts starts each under its own name, and addresses the second by that name:
init({ destination: 'https://q.example.com' })
init({ destination: 'https://q.partner.com', globalName: 'partner' })
import { client, track } from '@blotout/qinto-sdk-browser'
await track('AddToCart', { value: 10.5 })
await client('partner').track('AddToCart', { value: 10.5 })client(name) looks the instance up on window[name]; it creates nothing and holds only the name, so it can be written
at every call site. The module-level functions are client('qinto').
Sandboxed pages
In a sandboxed frame, such as a Shopify custom pixel, window.location and document.referrer name the frame, not
the page the visitor sees, and the site's cookies do not reach the connection. Give the client a pageContext function
that returns the real page and the visitor the server reported on an earlier connect:
init({
destination: 'https://q.example.com',
pageContext: () => ({
url: shopPage.url,
referrer: shopPage.referrer,
visitor: stored === undefined ? undefined : { id: stored.anonId, session: stored.session }
})
})The tag reads the same function from its global. Set it on the snippet's holder before the tag loads:
var t = { _q: 1, q: [], pageContext: function () { return { url: shopPage.url } } }The client calls it on every connect, reconnect and call, so it must return at once. url is the page's absolute URL.
url and referrer name the page for the connection, the calls, the apps and query-parameter capture. visitor goes
to the connection only: id continues that visitor, and session (<session id>.<startedAt>) continues that visit.
Leave id and session off until the server has reported them in a qinto:connect
event; the server mints both. If the function throws, or returns a url that is not an absolute URL, the client uses
the frame's own location and referrer.
visitor.fallbackId takes the place of the site's recovery cookie, which a sandboxed frame cannot send. Return the
value that cookie would hold, such as the Shopify customer event's clientId. When the connection has no valid id,
the server looks the value up under the cookie name set in Settings → Capturing data and continues the visitor
it recovers, or binds the new visitor to the value. With no cookie name set, the server ignores it.
For a Shopify store, the Qinto team sets this up with the Shopify custom pixel guide (docs/shopify-pixel/README.md in
the Qinto repo).
Send
import { alias, identify, track } from '@blotout/qinto-sdk-browser'
await track('AddToCart', { currency: 'USD', value: 10.5 })
await identify({ email: '[email protected]', plan: 'pro' })
await identify({ plan: 'pro' }, 'crm-user-8412')
await alias('crm-user-8412')| Method | What it does |
| --- | --- |
| track(event, properties?, options?) | Records something the visitor did. Resolves to { eventId }. |
| identify(traits?, id?) | Merges identity traits into the visitor's profile, and links id — an identifier of your own — to them. |
| alias(alias) | Links an identifier of your own to the visitor without touching traits. |
| consent(input) | Records the visitor's consent choices. See Consent. |
Details worth knowing:
- Event names are free-form, but the eleven standard events are the vocabulary apps recognize without per-site configuration. An app that does not know your own name does nothing with it.
trackreturns the event id. A payload carrying a non-emptyorderIduses that as the event id, so a purchase you also send from your backend deduplicates across the two. Otherwise one is minted. Pass your own withtrack(event, properties, { eventId }); a supplied id always wins.options.installspicks the app installs that receive a track.{ mode: 'except', installIds }reaches every install but the listed ones, and{ mode: 'only', installIds }reaches the listed ones alone. An unknown id is ignored. An emptyonlylist reaches no install, but the event is still sent and stored as usual. On the page, an install the rule leaves out does not see the event in itsonEvent; on the server, it does not receive it, though its transform still runs.options.appspicks the apps that receive a track, by slug.{ mode: 'only', slugs: ['facebook'] }reaches every install of the listed apps, an install added later included, andexceptreaches every app but the listed ones. It follows the same rules asinstalls, and when you pass both, an install receives the event only if both allow it.- Traits merge. Only the traits you send change. A trait sent as
nullclears the stored one, soidentify({ plan: null })is an unset, not a no-op. - A trait never links an identifier. An
emailorphonetrait is stored as a standard trait, nothing more; callaliaswith the value so a later call from your server can address the same person by it. - A link is permanent. Repeating
aliasis safe, and an identifier that already belongs to someone else does not move.
Standard traits
Eight trait keys are the visitor's identity fields. Qinto stores them as such, and apps read them by these names; any other key is a custom trait, kept as sent.
| Key | Meaning | Handling |
| --- | --- | --- |
| email | Email address | Trimmed and lowercased. Must look like [email protected], or the trait is dropped. |
| phone | Phone number | Trimmed; spaces, (), . and - removed; a leading + kept. Needs at least 7 digits and no other characters, or the trait is dropped. |
| first_name | Given name | Stored as sent. |
| last_name | Family name | Stored as sent. |
| country | Country | Stored as sent. |
| state | State or region | Stored as sent. |
| city | City | Stored as sent. |
| postal_code | Postal or ZIP code | Stored as sent. |
await identify({ firstName: 'Ada', email: ' [email protected] ', phone: '+1 (415) 555-0142' })
// stored: first_name 'Ada', email '[email protected]', phone '+14155550142'- camelCase keys fold to these names.
firstNameandfirst_nameare the same field, as arepostalCodeandpostal_code. - A dropped value changes nothing. An invalid
emailorphoneleaves the stored one in place; the other traits in the same call still apply. - Values are not hashed. The SDK sends what you pass, over HTTPS. A non-string value on a standard key other than
emailorphoneis stored as its JSON.
Read
import { getVisitor } from '@blotout/qinto-sdk-browser'
const { anonId, globalId, ip, geo } = await getVisitor()| Method | What it returns |
| --- | --- |
| getVisitor() | { anonId, globalId, ip, geo } — visitor identity plus the server-observed IP and narrow Cloudflare location. geo contains country, EdgeTag-compatible subdivision code region, full subdivision name state, and isEU; unavailable values are null. It asks the server each time, so globalId reflects an identify that just linked the visitor. |
| getAnonId() | The anon_… id alone, from the socket's connect. It sends nothing. |
| getConsent() | The consent state stored for this visitor, as the server last sent it. It sends nothing. |
The server sends the consent state when the socket connects, answers each consent() call with the state it stored,
and pushes every later change, including one the visitor made in another tab or on another device.
The qinto:connect event
The client dispatches a qinto:connect event on window each time the socket connects, reconnects included. Both the
tag and init() dispatch it; there is no option to set.
window.addEventListener('qinto:connect', (event) => {
const { name, anonId, session, reconnect } = (event as CustomEvent).detail
})| Field | Value |
| --- | --- |
| name | The global that connected: 'qinto', or the name a second instance uses. |
| anonId | The visitor's id: an anon_… id, or the EdgeTag id Qinto adopted for a visitor EdgeTag saw first. |
| session | { id, isNew, startedAt }: the visit the server put this connection in, the same session apps get on actions and in onConnect. startedAt is in epoch milliseconds. Absent when the site's worker is older than this client. |
| reconnect | false on the first connect of this instance, true on every later one. It does not tell a new visit from a continued one; session.isNew does. |
The event leaves out ip, geo and globalId, because every script on the page can read it. Use getVisitor() for
those. A sandboxed page stores anonId and session from this event and returns them from
pageContext on the next page.
Consent
import { consent } from '@blotout/qinto-sdk-browser'
await consent({ categories: { analytics: true, marketing: false } })
await consent({ apps: { 'facebook-capi': false } })Choices merge, so a banner can send one toggle at a time. The five categories are exported as CONSENT_CATEGORIES:
necessary, functional, analytics, marketing, salesOfData. necessary is always granted and accepts only
true.
Consent decides which apps receive an action: an app is delivered to only when the visitor granted the category its manifest declares, and the per-app map overrides that for one app. It is not a switch on whether Qinto accepts the action. A site that collects no consent at all turns enforcement off in the platform instead.
Geo filters
An install can have a geo filter: the visitor locations where it runs. You set it in the Qinto
platform, on the install's card under Site → Apps, or through the API or the MCP tool
qinto_set_install_geo_filter. Your page code does not change.
A geo filter has a list of locations to include ("Run only in"), a list to exclude ("Never run in"), or both. Each entry is one of these:
| Entry | Example | Matches |
| --- | --- | --- |
| Country code (ISO 3166-1 alpha-2) | SI | A visitor in that country |
| EU | EU | A visitor in a European Union country |
| US state code (ISO 3166-2) | US-CA | A US visitor in that state. The 50 states and DC; US territories use their own country codes |
An install with a geo filter runs for a visitor only when the location is known, the include list
is empty or one of its entries matches, and no exclude entry matches. The exclude list wins:
include US with exclude US-CA runs everywhere in the US except California. The location is
where the visitor is on this page load, not where they first visited the site.
An unknown location turns the install off, because a geo filter is a compliance control. The location is unknown when:
- the visitor's country is not known (no country,
XX, orT1for Tor); - a list names a US state, and a US visitor's state is not known;
- a list holds
EU, and the request does not say whether the country is in the EU.
What it covers. The visitor's browser session: the app's browser code, the connect call, the events and transforms from the page, pushes to the page, stored click ids and cookies, and calls to the app's visitor endpoints. It does not limit events sent with the server SDK or the HTTP API, the app's schedules, its webhooks and API endpoints, MCP tools, or calls from other apps.
A new install runs in all locations. You cannot give an install a geo filter when you create it, and a new install is on and deploys at once, so it runs until you turn it off or save its geo filter. To add an install that must never run in the wrong location, turn the whole app off on the site first, add the install, save its geo filter, then turn the app on. The app's other installs are off for that time too.
When a change takes effect. Saving a geo filter redeploys an active site. The server applies
it as soon as the deploy is done; on a site that shares another site's identity graph, pushes,
stored click ids and cookies, and the browser's answer can take up to 60 seconds more. A page loaded after that gets a changed list at once; after you
add or remove a geo filter, it can take about 10 minutes, because q.js is cached. A page that is
already open keeps the installs it started with until it reloads.
What it costs the page. On a site with a geo-filtered install, the client asks once, when it
connects, which of those installs it may run, and holds the page's first calls until the answer
arrives. If the request fails, those installs stay off for the page and the console says so; all
other tracking continues. A site with no geo filter sends no extra request. Every app's browser code
still downloads in q.js, as it does for an app the visitor has not consented to; it does not run.
Close
import { close } from '@blotout/qinto-sdk-browser'
await close()Stops reconnecting and rejects every call still in flight. A page that lives for its whole session rarely needs it.
Errors
Every error the client throws extends QintoError.
| Class | When |
| --- | --- |
| QintoEnvironmentError | init or a call was made outside a browser. |
| QintoError | window[globalName] belongs to something else on the page, or init was called on a name that is already running. |
| QintoTimeoutError | The call waited requestTimeoutMs with no acknowledgement. |
| QintoProtocolError | The edge refused the frame, or the socket closed with the call in flight. Its message is the edge's own. |
import { QintoTimeoutError } from '@blotout/qinto-sdk-browser'
try {
await track('Purchase', { currency: 'USD', value: 20.5, orderId: '190315' })
} catch (error) {
if (error instanceof QintoTimeoutError) {
// queue it and retry: the order id keeps the retry from double-counting
}
}The tag
The Qinto platform also gives you a <script> snippet, built from this same source, that binds a global (window.qinto
by default) and queues calls made before it finishes loading. Both talk to the same edge and mint the same ids, so a
site can move from one to the other without losing a visitor.
The apps the site installed run in both, init fetches their browser bundles from the same /q.js, consent gates
them the same way, and both queue a call made before the connection is open. Two things differ in this package:
- You choose when it loads. The snippet loads the tag as soon as the page parses it; here,
initruns when your code calls it, and the calls are typed imports rather thanwindow.qinto. - The page load is yours. The tag can record it for you; here,
track('PageView')is yours to call.
Types
QintoBrowserClient (what client(name) and init return), QintoInitOptions, ConsentCategory, ConsentInput, ConsentState, InstallRule, Properties,
VisitorInfo, TrackOptions, and Traits are all exported.
Documentation
The standard events, the identity model, and the platform itself are documented at docs.blotout.io.
