billdogeng-next
v1.0.0-beta.1
Published
BilldogEng SDK for Next.js — SSR-safe, idiomatic React/Next wrapper over the BillDog engagement suite (analytics, surveys, in-app messaging, remote feature flags).
Maintainers
billdogReadme
billdogeng-next
The BillDog engagement suite for Next.js / React — a thin, SSR-safe,
idiomatic wrapper over the existing browser SDKs (@billdog.io/web,
@billdog.io/analytics, @billdog.io/survey-core).
It surfaces everything the engagement suite offers the React way:
- Analytics —
capture,identify,group - Surveys — fetch, render (
<Survey/>), and submit (useSurvey) - In-app messaging — trigger placements
- Feature flags — remote / server-authoritative (
useFeatureFlag)
Feature flags are evaluated on the BillDog backend. This package does no local bucketing and contains no murmurhash — targeting is server-side only.
Install
npm install billdogeng-next @billdog.io/web @billdog.io/analytics @billdog.io/survey-corereact, react-dom and next are peer dependencies. The three BillDog
browser SDKs are optional peers — install the ones whose features you use.
Quickstart (App Router)
// app/providers.tsx
'use client';
import { BilldogProvider } from 'billdogeng-next';
export function Providers({ children }: { children: React.ReactNode }) {
return (
<BilldogProvider
config={{
apiKey: process.env.NEXT_PUBLIC_BILLDOG_API_KEY!,
projectId: process.env.NEXT_PUBLIC_BILLDOG_PROJECT_ID!,
customerId: 'user_42', // optional; or call identify() later
}}
>
{children}
</BilldogProvider>
);
}// app/layout.tsx
import { Providers } from './providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}BilldogProvider is a Client Component. It is SSR-safe: the engagement
client is created inside a useEffect, so it never runs during server render
and never touches window/document on the server. You can safely import this
package from Server Components — nothing initialises until the browser.
Analytics
'use client';
import { useBilldog } from 'billdogeng-next';
export function CheckoutButton() {
const { capture, identify, group } = useBilldog();
return (
<button
onClick={() => {
identify('user_42', { plan: 'pro' });
group('company', 'acme', { seats: 12 });
capture('checkout_started', { value: 49.0 });
}}
>
Buy
</button>
);
}Feature flags (remote)
'use client';
import { useFeatureFlag } from 'billdogeng-next';
export function Banner() {
const newBanner = useFeatureFlag('new-banner', false); // boolean
const theme = useFeatureFlag('home-theme', 'classic'); // string variant
if (!newBanner) return null;
return <div className={`banner banner--${theme}`}>Welcome!</div>;
}The hook returns the value cached from the backend's flag-evaluation response and re-renders automatically whenever the SDK re-evaluates flags.
Surveys
Drop-in component:
'use client';
import { Survey } from 'billdogeng-next';
export function FeedbackSurvey() {
return (
<Survey
surveyId="svy_nps"
onSubmit={(result) => console.log('submitted', result.responseId)}
/>
);
}Or build your own UI with the hook + render-prop:
'use client';
import { useSurvey } from 'billdogeng-next';
export function CustomSurvey() {
const { survey, loading, submit } = useSurvey('svy_nps');
if (loading || !survey) return null;
return (
<button onClick={() => submit([{ question_id: 'q1', answer_number: 9 }])}>
Rate 9 — {survey.name}
</button>
);
}In-app messaging
'use client';
import { useBilldog } from 'billdogeng-next';
export function HelpTrigger() {
const { showInAppMessages } = useBilldog();
return <button onClick={() => showInAppMessages('help-center')}>Help</button>;
}API
| Export | Kind | Purpose |
| --- | --- | --- |
| BilldogProvider | component | Init + context root (SSR-safe). |
| 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 surveyId /> | component | Fetch + render + submit a survey. |
| createBilldogClient(config, deps?) | fn | Low-level client builder (advanced). |
Pages Router
Wrap your tree in _app.tsx:
import { BilldogProvider } from 'billdogeng-next';
export default function App({ Component, pageProps }) {
return (
<BilldogProvider config={{ apiKey: '...', projectId: '...' }}>
<Component {...pageProps} />
</BilldogProvider>
);
}License
MIT