Install

React

Drop-in TugBanner, TugCard and TugModal components that count themselves.

Install#

Shell

npm install tug-sdk

React 18 or 19 is a peer dependency. Wrap your app once in TugProvider, then place a component where a message should appear.

App.tsx · React (TSX)

import { TugProvider, TugBanner } from "tug-sdk/react";
import "tug-sdk/styles.css"; // optional default look

export function App() {
  return (
    <TugProvider publicKey="phk_live_…" baseUrl="https://tughq.com/api/v1">
      <TugBanner userId={user?.id} />
    </TugProvider>
  );
}

Each component:

  • renders nothing until there is an approved message for that user;
  • renders nothing for holdout users, but still reports them so lift stays fair;
  • reports shown, clicked and dismissed for you.

userId can be undefined or null while your auth loads (user?.id). Nothing is fetched until it has a value.

Banner, card and modal#

One component per surface. The notification surface uses the banner component.

React (TSX)

import { TugBanner, TugCard, TugModal } from "tug-sdk/react";

<TugCard userId={user.id} />                          {/* surface: dashboard_card */}
<TugModal userId={user.id} />                         {/* surface: modal */}
<TugBanner userId={user.id} surface="notification" /> {/* surface: notification */}

If the project requires identity verification, pass userHash to TugProvider.

Styling#

Components are unstyled. They output tug-banner, tug-card and tug-modal classes (with __title, __body, __cta and __dismiss parts) and no inline styles.

For a small default look, import tug-sdk/styles.css and theme it with three variables. Its rules use one class at most, so one class of your own overrides them.

theme.css · CSS

:root {
  --tug-color: #4f46e5;  /* buttons and banner tint */
  --tug-radius: 12px;
  --tug-font: inherit;
}

Your own markup#

Pass renderDecision to draw the message yourself. Call the actions you receive, so clicks and dismissals are still measured.

React (TSX)

<TugBanner
  userId={user.id}
  renderDecision={(d, { clickCta, dismiss }) => (
    <MyBanner title={d.title} body={d.body} onCta={clickCta} onClose={dismiss} />
  )}
/>

Server Components#

In a Server Component or API route that renders the message straight away, use TugClient with a server API key and shown: true. That counts the serve in the same call.

app/dashboard/page.tsx · React (TSX)

import { TugClient } from "tug-sdk";

const tug = new TugClient({ publicKey: process.env.TUG_PUBLIC_KEY, apiKey: process.env.TUG_API_KEY });

export default async function Dashboard({ userId }: { userId: string }) {
  // Counted as shown in the same call, because it renders now
  const d = await tug.getDecision({ surface: "dashboard_card", userId, shown: true });
  return d ? <MyCard title={d.title} body={d.body} href={d.ctaUrl} /> : null;
}

Then send clicked and dismissed with tug.feedback() so the message is measured. See Node and server.

  • 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