Install
Script tag (tug.js)
One script tag: tracks visitors, identifies them after login and fetches messages.
Install#
Add this to the <head> of every page. Tug serves tug.js itself, so you always run the current version.
index.html · HTML
<script src="https://tughq.com/tug.js" defer></script>
<script>
window.tugConfig = { publicKey: "phk_live_…" };
</script>That's all it takes to start collecting pageviews. The script exposes window.tug and gives each visitor an anonymous ID (kept in localStorage).
Identify and track#
Every method acts on the current visitor, so track takes no user ID. After login, call identify with your own user ID; later calls use it.
JavaScript
// After login: switch from the anonymous visitor ID to your user ID
tug.identify("user_123", { plan: "trial" });
// Custom events for the current user (no user ID needed)
tug.track("pricing_viewed", { plan: "pro" });Render a message#
Ask for a placement, render its decision if there is one, and call shown() once the slot is on screen.
JavaScript
// Fetching is free and safe to repeat.
const placement = await tug.getPlacement({ surface: "banner", userId: "user_123" });
const d = placement.decision;
if (d) {
renderBanner({
title: d.title,
body: d.body,
cta: { label: d.ctaLabel, href: d.ctaUrl },
onClick: () => tug.feedback({ logId: d.logId, action: "clicked" }),
onDismiss: () => tug.feedback({ logId: d.logId, action: "dismissed" }),
});
}
// Once the slot is on screen, message or not. This is what counts,
// for holdout users too, so both groups are measured the same way.
placement.shown();getDecision(…) still works and resolves with just the message. Then you report shown yourself with tug.feedback, and holdout users aren't counted. Prefer getPlacement.
Drop-in banner#
No React and no custom markup? tug-embed.js renders a styled banner into an element and reports shown, clicked and dismissed for you.
Banner without React · HTML
<link rel="stylesheet" href="https://tughq.com/tug.css">
<div id="tug-banner"></div>
<script src="https://tughq.com/tug-embed.js"></script>
<script>
Tug.mountBanner("#tug-banner", {
publicKey: "phk_live_…",
userId: "user_123",
});
</script>tugConfig reference#
| Option | What it does |
|---|---|
publicKey | Required. Your project's phk_live_… key. |
baseUrl | Optional. Defaults to the host that served the script, plus /api/v1. |
userHash | Optional. The signed-in user's hash for identity verification. Or pass it later with tug.identify(id, traits, { userHash }) or tug.setUserHash(hash). |
mock | Optional. When true, makes no network calls. |
mockDecisions | Optional. Messages to return in mock mode, keyed by surface. |
Automatic pageviews#
Unless mock is on, the script sends $pageview on load and whenever the path or query string changes (pushState, replaceState, back and forward). A replaceState that leaves the URL unchanged sends nothing.
When a call fails#
Nothing throws into your page. Methods return promises that resolve, with null when a call fails. When Tugrefuses a call (unknown key, blocked origin, trial ended, rate limit, invalid input) or can't be reached, the console gets one [tug] warning that says what to fix.
Mock mode#
Set mock: true and mockDecisions in tugConfigto render your UI with no network calls. Good for Storybook and CI. It doesn't replace one real end-to-end check.