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) => console.log(result.normalizedCode)}
      onError={(error) => console.error(error.message)}
    />
  );
}

The original GrowthCatReferralForm and useReferral handle influencer codes. For friend programs or combined entry, use the unified form below.

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);
}

Friend programs & combined code entry

Choose "influencers", "friends", or "both" for one validated input. Friend enrollment requires a signed-in app user and a short-lived identity token issued by your own server. Account management API keys never belong in browser code.

GrowthCat.initialize({
  apiKey: process.env.NEXT_PUBLIC_GROWTHCAT_KEY!,
  identityTokenProvider: async ({ appUserId, scope, forceRefresh }) => {
    const response = await fetch("/api/growthcat/identity", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ appUserId, scope, forceRefresh }),
    });
    if (!response.ok) throw new Error("Identity verification unavailable");
    const payload = await response.json();
    return payload.token;
  },
});
GrowthCat.setAppUserId(currentUser.id);

Your identity endpoint must authenticate the current session and authorize the requested app user. Issue the signed token on the server; never trust an arbitrary appUserId sent by the browser.

tsx

import { GrowthCatReferralCodeForm, useReferralCode } from "@growthcat/web/react";

// Built-in combined input, suitable for onboarding or settings:
<GrowthCatReferralCodeForm
  mode="both"
  onSuccess={(result) => {
    console.log(result.kind); // "friend" or "influencer"
  }}
/>

// Or use useReferralCode({ mode: "friends" }) in your own component.

const client = GrowthCat.shared;
const programs = await client.referralPrograms();
const program = programs.find((item) => item.acceptingNewReferrals);
if (program) {
  const invite = await client.referralInvite(program.id);
  // Share invite.url or show invite.code; the user invite code stays stable.
}
const state = await client.referralState();
for (const progress of state.progress) {
  console.log(progress.qualifiedCount, progress.remainingCount);
  console.log(progress.milestones); // Configured thresholds and labels
}
console.log(state.rewards); // Review, delivery, and redemption state

// Clear account-specific identity and state when signing out:
GrowthCat.clearAppUserId();

tsx

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

// Settings UI follows single, repeat and tiered rules from the dashboard.
<GrowthCatFriendReferralPanel
  programId={programId}
  strings={{
    title: "Invite friends",
    remaining: (count) => `${count} friends until your next reward`,
  }}
  onSelectOffering={(offeringId) => presentPaywall(offeringId)}
  renderReward={(reward) => reward.featureKey === "vip_coaching"
    ? <a href="/account/coaching">View your coaching benefit</a> : null}
/>

The panel shows configured benefits, remaining friends, delivered rewards, and Copy/Share actions with a selectable-link fallback. Replace all labels, count formats, benefits and statuses through strings; use style and className to match your app. useFriendReferrals exposes isCreatingInvite for custom sharing UI. Optional onSelectOffering and renderReward callbacks handle usable delivered offerings and custom benefits; pending, expired and simulated rewards cannot trigger them. Offering selection does not grant a trial or entitlement.

Remote availability and new-user eligibility

Friend referrals are off by default per app. Enable them from the Referrals page or SDK settings; active program status alone does not enable recruitment. The React components read the remote flag and authenticated server eligibility before showing invitation or friend-code actions, while retaining earned rewards and progress. Existing users may invite new friends. By default, invited friends must enter a code within 7 days of account creation and can receive one welcome benefit across this app's referral programs in the workspace. Configure the age window, existing-invitee policy, welcome limit, thresholds and benefits from the dashboard. Account creation dates come from your signed server identity claims, never browser input. Direct enrollment calls are checked on the server, including accepted retries. Influencer codes remain independent. Plan capacities and reset policy.

Website arrival attribution

Create a Website acquisition campaign and share its GrowthCat tracking link. The redirect carries a gc_token to the destination. After the applicable consent, the web SDK captures the token and claims attribution with verified identity. A website arrival is not an app install.

// Enable analytics only after obtaining the required consent.
GrowthCat.initialize({
  apiKey: process.env.NEXT_PUBLIC_GROWTHCAT_KEY!,
  measurementMode: "analytics",
  identityTokenProvider,
});
// Capture now; if sign-in is pending, the SDK can claim after identity is set.
await GrowthCat.captureWebArrival();
GrowthCat.setAppUserId(currentUser.id);

tsx

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

function AttributionStatus({ hasConsent }: { hasConsent: boolean }) {
  const arrival = useWebAttribution({ enabled: hasConsent });
  // Use the returned arrival state in your UI as needed.
  return null;
}

Use the initialized singleton directly or the React hook; no extra provider is required. Reports separate website clicks and attributed website arrivals from store clicks and app installs. Existing tracking continues at the signed acquisition attribution upgrade threshold; new campaign activations require spare capacity. Link-event traffic review thresholds are advisory and do not restrict activation. No automatic overage charges apply. Acquisition setup guide.

useReferralLinksAnalytics

Referrals & Attribution

Validate influencer or friend codes, show program progress and rewards, and capture app or website campaign attribution.

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

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

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) => console.log(result.normalizedCode)}
      onError={(error) => console.error(error.message)}
    />
  );
}

The original GrowthCatReferralForm and useReferral handle influencer codes. For friend programs or combined entry, use the unified form below.

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);
}

Friend programs & combined code entry

GrowthCat.initialize({
  apiKey: process.env.NEXT_PUBLIC_GROWTHCAT_KEY!,
  identityTokenProvider: async ({ appUserId, scope, forceRefresh }) => {
    const response = await fetch("/api/growthcat/identity", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ appUserId, scope, forceRefresh }),
    });
    if (!response.ok) throw new Error("Identity verification unavailable");
    const payload = await response.json();
    return payload.token;
  },
});
GrowthCat.setAppUserId(currentUser.id);

Your identity endpoint must authenticate the current session and authorize the requested app user. Issue the signed token on the server; never trust an arbitrary appUserId sent by the browser.

tsx

import { GrowthCatReferralCodeForm, useReferralCode } from "@growthcat/web/react";

// Built-in combined input, suitable for onboarding or settings:
<GrowthCatReferralCodeForm
  mode="both"
  onSuccess={(result) => {
    console.log(result.kind); // "friend" or "influencer"
  }}
/>

// Or use useReferralCode({ mode: "friends" }) in your own component.

const client = GrowthCat.shared;
const programs = await client.referralPrograms();
const program = programs.find((item) => item.acceptingNewReferrals);
if (program) {
  const invite = await client.referralInvite(program.id);
  // Share invite.url or show invite.code; the user invite code stays stable.
}
const state = await client.referralState();
for (const progress of state.progress) {
  console.log(progress.qualifiedCount, progress.remainingCount);
  console.log(progress.milestones); // Configured thresholds and labels
}
console.log(state.rewards); // Review, delivery, and redemption state

// Clear account-specific identity and state when signing out:
GrowthCat.clearAppUserId();

tsx

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

// Settings UI follows single, repeat and tiered rules from the dashboard.
<GrowthCatFriendReferralPanel
  programId={programId}
  strings={{
    title: "Invite friends",
    remaining: (count) => `${count} friends until your next reward`,
  }}
  onSelectOffering={(offeringId) => presentPaywall(offeringId)}
  renderReward={(reward) => reward.featureKey === "vip_coaching"
    ? <a href="/account/coaching">View your coaching benefit</a> : null}
/>

Remote availability and new-user eligibility

Website arrival attribution

// Enable analytics only after obtaining the required consent.
GrowthCat.initialize({
  apiKey: process.env.NEXT_PUBLIC_GROWTHCAT_KEY!,
  measurementMode: "analytics",
  identityTokenProvider,
});
// Capture now; if sign-in is pending, the SDK can claim after identity is set.
await GrowthCat.captureWebArrival();
GrowthCat.setAppUserId(currentUser.id);

tsx

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

function AttributionStatus({ hasConsent }: { hasConsent: boolean }) {
  const arrival = useWebAttribution({ enabled: hasConsent });
  // Use the returned arrival state in your UI as needed.
  return null;
}

useReferralLinksAnalytics

Referrals & Attribution

Validate influencer or friend codes, show program progress and rewards, and capture app or website campaign attribution.

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