@ventiveiq/react
v0.1.0-rc6
Published
React hooks and provider for VentiveIQ analytics SDK
Keywords
Readme
@ventiveiq/react
React 18+ provider and hooks for the VentiveIQ analytics SDK. The provider is fail-safe: if the analytics service is unavailable, application rendering and event handlers continue normally.
Installation
npm install @ventiveiq/reactreact and react-dom must already be installed in the application.
Add the provider
Wrap the application, or the subtree that uses analytics hooks, with
AnalyticsProvider:
import { AnalyticsProvider } from "@ventiveiq/react";
export function App() {
return (
<AnalyticsProvider
config={{
host: "https://api.ventiveiq.com",
writeKey: "key:secret",
siteKey: "my-site",
}}
>
<ApplicationRoutes />
</AnalyticsProvider>
);
}The host setting is required when the provider is enabled. Supported config
options include:
<AnalyticsProvider
config={{
host: "https://api.ventiveiq.com",
writeKey: "key:secret",
siteKey: "my-site",
debug: false,
cookieDomain: ".example.com",
privacy: {
respectDnt: true,
respectGpc: true,
consent: {
analytics: true,
marketing: true,
advertising: true,
},
},
}}
>
<App />
</AnalyticsProvider>Next.js App Router
@ventiveiq/react is a client-side package. It can be rendered from a Next.js
layout while keeping the layout itself as a Server Component:
// app/layout.tsx
import { AnalyticsProvider } from "@ventiveiq/react";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<AnalyticsProvider
config={{ host: "https://api.ventiveiq.com", siteKey: "my-site" }}
>
{children}
</AnalyticsProvider>
</body>
</html>
);
}Components that call the hooks below must be Client Components.
Track events
"use client";
import { useTrack } from "@ventiveiq/react";
export function SignupButton() {
const track = useTrack();
return (
<button onClick={() => track("signup_clicked", { plan: "pro" })}>
Sign up
</button>
);
}Track page views
usePage sends a page event when the component mounts. Supply dependencies to
send another page event when route state changes:
"use client";
import { usePage } from "@ventiveiq/react";
export function ProductPage({ productId }: { productId: string }) {
usePage({ productId, section: "catalog" }, [productId]);
return <main>...</main>;
}Identify and reset users
"use client";
import { useIdentify, useReset } from "@ventiveiq/react";
export function AccountActions() {
const identify = useIdentify();
const reset = useReset();
async function signedIn() {
await identify("user-123", { email: "[email protected]", plan: "pro" });
}
function signedOut() {
reset();
}
return null;
}Call reset() when a user signs out so the next user does not inherit the
previous identity.
Privacy and consent
"use client";
import { useConsent, useIsBlocked, useOptOut } from "@ventiveiq/react";
export function PrivacyControls() {
const { consent, setConsent } = useConsent();
const { optOut, optIn } = useOptOut();
const blocked = useIsBlocked();
return (
<section>
<p>Analytics status: {blocked ? "blocked" : "enabled"}</p>
<button onClick={() => setConsent({ analytics: true })}>
Allow analytics
</button>
<button onClick={() => setConsent({ marketing: false })}>
Deny marketing
</button>
<button onClick={optOut}>Opt out</button>
<button onClick={optIn}>Opt in</button>
<pre>{JSON.stringify(consent, null, 2)}</pre>
</section>
);
}Service failures
The provider catches SDK initialization errors, synchronous SDK errors, and rejected analytics operations. If the configured host is unreachable or down, events are dropped without stopping the React application.
Use onError when the application needs its own logging for errors that reach
the provider:
function reportAnalyticsError(error: unknown) {
console.warn("VentiveIQ is temporarily unavailable", error);
}
<AnalyticsProvider
config={{ host: "https://api.ventiveiq.com" }}
onError={reportAnalyticsError}
>
<App />
</AnalyticsProvider>Keep onError stable—for example, define it outside the component or wrap it in
useCallback—to avoid recreating the analytics instance unnecessarily. When
onError is omitted, failures are written to console.warn. Low-level network
failures are already caught and logged by the core SDK, so they may not invoke
the provider's onError callback.
Disable analytics
Use disabled mode in tests, previews, or environments where analytics must not run. All hooks remain safe and become no-ops:
<AnalyticsProvider disabled>
<App />
</AnalyticsProvider>No config is required in disabled mode.
Access the SDK directly
For operations not covered by a convenience hook, use useAnalytics:
"use client";
import { useAnalytics } from "@ventiveiq/react";
export function AnalyticsStatus() {
const analytics = useAnalytics();
return <span>Anonymous ID: {analytics.getAnonymousId()}</span>;
}useAnalytics must be called below AnalyticsProvider. Calling it outside the
provider throws an error because no analytics context exists.
API summary
| Export | Purpose |
| --- | --- |
| AnalyticsProvider | Creates and provides a fail-safe analytics instance. |
| useAnalytics | Returns the full VentiveIQInstance. |
| useTrack | Returns a stable custom-event callback. |
| usePage | Sends page events from an effect. |
| useIdentify | Identifies the current user and stores traits. |
| useReset | Clears the stored identity. |
| useOptOut | Returns persistent opt-out and opt-in callbacks. |
| useConsent | Reads and updates consent preferences. |
| useIsBlocked | Reports whether privacy rules suppress tracking. |