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#

OptionWhat it does
publicKeyRequired. Your project's phk_live_… key.
baseUrlOptional. Defaults to the host that served the script, plus /api/v1.
userHashOptional. The signed-in user's hash for identity verification. Or pass it later with tug.identify(id, traits, { userHash }) or tug.setUserHash(hash).
mockOptional. When true, makes no network calls.
mockDecisionsOptional. 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.

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides