billdogeng-react

The BillDog engagement suite for React — a thin, idiomatic, SSR-safe wrapper over the existing browser SDKs (@billdog.io/web, @billdog.io/analytics, @billdog.io/survey-core).

It surfaces, framework-idiomatically:

• Analytics — capture / identify / group via useBilldog()
• Surveys — fetch + submit + a drop-in <Survey/> component (useSurvey)
• In-app messaging — trigger via useBilldog().showInAppMessages()
• Feature flags — remote / server-authoritative via useFeatureFlag()

Feature flags are evaluated on the BillDog backend. This package performs no local bucketing and contains no murmurhash — server-authoritative targeting only, by design.

Install

npm install billdogeng-react @billdog.io/web @billdog.io/analytics @billdog.io/survey-core

react / react-dom (>=18) and the three @billdog.io/* packages are peer dependencies. The @billdog.io/* peers are optional — features degrade to no-ops if a peer is absent.

Quick start

import { BilldogProvider } from 'billdogeng-react';

export function App() {
  return (
    <BilldogProvider config={{ apiKey: 'bd_live_…', projectId: 'proj_123' }}>
      <YourApp />
    </BilldogProvider>
  );
}

Analytics

import { useBilldog } from 'billdogeng-react';

function Checkout() {
  const { capture, identify, group } = useBilldog();

  function onLogin(user) {
    identify(user.id, { plan: user.plan });
    group('company', user.companyId, { seats: user.seats });
  }

  return <button onClick={() => capture('checkout_started')}>Buy</button>;
}

Feature flags (remote)

import { useFeatureFlag } from 'billdogeng-react';

function Banner() {
  const newUI = useFeatureFlag('new-banner', false);   // boolean flag
  const theme = useFeatureFlag('theme', 'classic');     // multivariate flag
  return newUI ? <NewBanner theme={theme} /> : <OldBanner />;
}

The value updates automatically whenever the SDK re-evaluates flags remotely.

Surveys

Drop-in component:

import { Survey } from 'billdogeng-react';

<Survey surveyId="svy_nps" onSubmit={(res) => console.log(res)} />;

Or drive the form yourself with the hook / render-prop:

import { useSurvey } from 'billdogeng-react';

function CustomSurvey() {
  const { survey, loading, submit } = useSurvey('svy_nps');
  if (loading || !survey) return null;
  // render your own UI, then call submit([...answers])
}

In-app messaging

const { showInAppMessages } = useBilldog();
showInAppMessages('home_banner');

SSR

The package is safe to import and server-render under SSR frameworks (Remix, Vite SSR, Astro islands, etc.):

• The public entry never touches window/document at import time.
• BilldogProvider only instantiates the engagement client inside useEffect, so nothing runs during server render. Children render immediately; engagement features activate once the provider becomes ready in the browser.
• The underlying browser SDKs are loaded with dynamic import(), deferred to the client.

During SSR, useBilldog().ready is false and useFeatureFlag returns its default value.

API

| Export | Kind | Purpose | | --- | --- | --- | | BilldogProvider | component | Initialises the SDK; provides context. | | useBilldog() | hook | { client, ready, capture, identify, group, showInAppMessages, reset } | | useFeatureFlag(key, default?) | hook | Remote flag value (boolean or string variant). | | useSurvey(surveyId) | hook | { survey, loading, error, submit, refetch } | | Survey | component | Renders + submits a survey (or render-prop). | | createBilldogClient(config, deps?) | fn | Low-level client factory (client-side only). |

Development

npm install
npm run build      # tsup → dist/ (esm + cjs + d.ts)
npm test           # vitest (jsdom + node SSR suites)
npm run typecheck  # tsc --noEmit

License

MIT