Web setup

@invitebase/js is the browser SDK. It implements the shared surface with web-native attribution: referral codes arrive as URL parameters and persist in a first-party cookie until signup. Typed, tree-shakeable, no dependencies.

This page covers what's specific to the web platform — installation, how attribution works in a browser, and the TypeScript surface. The methods themselves are documented once for all platforms in the SDK reference. For a guided first integration, see the Web quickstart.

All five SDKs ship as version 1.0 on November 15, 2026. Prebuilt UI components and push notifications are coming soon and are outside the November 15 release. Build custom UI with the SDK methods and reactive reads.

Install

npm install @invitebase/js

pnpm add @invitebase/js

<script src="https://cdn.invitebase.com/js/v1/invitebase.min.js"></script>
<!-- exposes window.invitebase -->

The package exports a singleton client. Configure it once, as early as possible in your page lifecycle:

import invitebase from '@invitebase/js';

invitebase.configure(process.env.NEXT_PUBLIC_INVITEBASE_PUBLISHABLE_KEY);

export default invitebase;

configure generates (or restores) the anonymous ID from localStorage and, by default, immediately checks the current URL and stored cookie for an inbound referral code. Options and behavior: configure reference.

How inbound resolution works on web

When someone clicks https://mycompany.refr.link/a1b2c3 and continues to your site, the redirect appends the code to your destination URL as a ref query parameter. The SDK:

1. Reads ?ref= (also accepts ?invitebase_code=) from the URL.
2. Persists the code in a first-party cookie (_ib_ref) and localStorage, with expiry aligned to the campaign's qualification window.
3. Attaches the code as referral_code on the next tracked events — the signup event is what advances the referral from clicked to signed_up.
4. Clears the stored code after attribution succeeds (one-shot).

If the same browser clicks two different referral links before signing up, the last click wins. There is no fingerprinting — attribution on web is entirely URL parameter plus first-party storage. See Attribution for the full model.

Unlike mobile, there is no deferred-install gap on web, so resolveReferral resolves immediately from URL/cookie state and never reports needsManualEntry. For client-side routing or custom entry points, call handleInbound yourself.

TypeScript types

All types are exported from the package root:

import type {
  InvitebaseUser,
  ReferralLink,
  InboundReferral,
  ReferralResolution,
  CampaignInfo,
  ReferrerProgress,
  Reward,
  RewardStatus,
  InvitebaseEvent,
  InvitebaseError,
} from '@invitebase/js';

The package ships full .d.ts declarations and is tree-shakeable — unused methods are dropped from your bundle. The React Native SDK's types are generated from the same source, so shapes match exactly.

What's next