Developer Docs / Web React SDK

GrowthCat Web React SDK

Use the TypeScript and React SDK for referrals, attribution, self-promotion ads, sponsorships, and feedback. Built-in components and headless APIs can be mixed within the same app.

Create GrowthCat Account Web React overview Developer docs

Package

@growthcat/web with React exports from @growthcat/web/react.

Install

Install once, then follow the package guide for the product surface you are adding.

Initialization

Call GrowthCat.initialize once. The bootstrap configures referral flags and ads for every package.

Install The SDK

React components and hooks are exported from the React subpath.

bash

npm install @growthcat/web react react-dom
# or
yarn add @growthcat/web react react-dom

Install the GrowthCat integration skill

The WebSDK repository includes an agent skill that inspects your app, checks the installed SDK types, and adds referrals, attribution, ads, sponsorships, or feedback using your existing architecture.

bash

npx skills add . --skill growthcat-web-integration

Run this from a local GrowthCatSDK-Web checkout. For a remote install, replace the dot with the repository Git URL. Then tell your coding agent which capability and placement you want.

Use $growthcat-web-integration to add a feedback board to my settings page.

Initialize Once

The default essential measurement mode keeps aggregate delivery and operational events without attaching an app user ID to ordinary impressions. Switch to analytics only after establishing consent or another valid legal basis.

import { GrowthCat } from "@growthcat/web";

GrowthCat.initialize({
  apiKey: process.env.NEXT_PUBLIC_GROWTHCAT_KEY!,
  workspace: "live",
  logsEnabled: process.env.NODE_ENV !== "production",
  measurementMode: "essential",
});

// Optional: await this before reading bootstrap flags immediately.
await GrowthCat.ready();

// If this site receives GrowthCat attribution links:
GrowthCat.setAppUserId(currentUser.id);
const assignment = await GrowthCat.handleCurrentUrl();

if (
  assignment?.deepLinkValue?.startsWith("/") &&
  !assignment.deepLinkValue.startsWith("//")
) {
  router.push(assignment.deepLinkValue);
}

Identity and sign-out

Set the app user ID only when you have a known signed-in user. Call GrowthCat.clearAppUserId() from your existing sign-out flow.

Referrals And Attribution

Use GrowthCatReferralForm or useReferral for React UI, or call the client directly. Keep one session ID across optional funnel events when analytics measurement is enabled.

tsx

import { GrowthCatReferralForm } from "@growthcat/web/react";

export function SettingsPage() {
  return (
    <GrowthCatReferralForm
      onSuccess={(result) => grantAccess(result.normalizedCode)}
      onError={(error) => console.error(error.message)}
    />
  );
}

const result = await GrowthCat.shared.validateReferralCode("MARCO20");

const link = await GrowthCat.shared.generateShareLink({
  campaignKey: "influencer_spring",
  deepLinkValue: "/welcome",
});

const assignment = await GrowthCat.shared.handleLink(link.publicUrl);
if (
  assignment?.deepLinkValue?.startsWith("/") &&
  !assignment.deepLinkValue.startsWith("//")
) {
  router.push(assignment.deepLinkValue);
}

useReferralLinksAnalytics

Referrals & Attribution

Validate promo codes, record referral funnels, claim attribution URLs, generate share links, and resolve assignments.

Open docs

useSponsorCalendarCustom UI

Sponsorships

Render public sponsor availability, built-in banners, or custom sponsor UI with qualified impression and click tracking.

Open docs

InitBannersRewarded

In-App Advertising

Initialize ads config, show banners and interstitials, render custom ad UI, and validate rewards.

Open docs

InitThemeBoard

Feedback SDK

Initialize GrowthCat, configure feedback identity and theme, submit feedback, and render boards.

Open docs