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.

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