Install
React
Drop-in TugBanner, TugCard and TugModal components that count themselves.
Install#
Shell
npm install tug-sdkReact 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,clickedanddismissedfor 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.