Install the JavaScript SDK, track your first action, and verify it in reports.
Collect pageviews and product actions from your website with @embrasure/analytics. Use the same project for browser and backend events.
Open Analytics in Embrasure and select Set up analytics. Your workspace must be enrolled in the analytics pilot, and an administrator must create the project. If setup is unavailable, ask your Embrasure contact to enable your workspace.
Choose your environment and copy its public project key. Add your site's exact origin to Allowed websites, for example https://app.example.com or http://localhost:3000. Origins include the scheme and port, with no page path. Development and production have separate keys and allowed websites.
npm install @embrasure/analyticsInitialize once in your browser entry point:
import { createAnalytics } from "@embrasure/analytics";
export const analytics = createAnalytics({
projectKey: "pk_your_project_key",
});The SDK sends to https://api.embrasure.ai/collect by default. It captures the initial page and pathname changes, including browser back/forward navigation. Page data includes pathname and host; it excludes query strings, fragments, page text, and form values.
For Next.js 15.3 or later, put this initialization in instrumentation-client.ts at the project root, or inside src if your app uses it. Import the instance only from browser code. Use capturePageview: false if you prefer to call analytics.page() yourself.
If your app requires consent before analytics, initialize with enabled: false and call analytics.setEnabled(true) after consent. Your app owns consent persistence.
Call track from the relevant click handler or completed action:
analytics.track("signup_started", { source: "pricing" });
analytics.identify("user_123", { plan: "pro" });
analytics.group("company", "company_456", { seats: 5 });
analytics.track("report_created", { report_id: "report_789" });Use a stable application user ID when identifying someone. Call analytics.reset() on logout or account change to clear identity, groups, and session. Keep secrets and sensitive form values out of event properties.
Clicks require explicit track calls. Automatic click capture, session replay, and feature flags are not included.
Trigger an action, then flush the queue while testing:
const result = await analytics.flush();
console.log(result); // { accepted, discarded, dropped, pending }In project setup, check Event received, then run the separate Ready in reports check. Collection acceptance means the event was acknowledged for delivery; reports become available after warehouse processing. A discarded result is not stored analytics.
The SDK normally flushes every five seconds or at 50 events. Its queue is memory-only, so browser shutdown is best effort. For troubleshooting, configure onDiagnostic: ({ type, count, reason }) => console.info(type, count, reason) when creating the client.
Create a server key in the project's environment settings. Keep it in a server environment variable, never browser code or a NEXT_PUBLIC_ variable. Node.js 20 or later is required.
import { createServerAnalytics } from "@embrasure/analytics/server";
const analytics = createServerAnalytics({
projectKey: "pk_your_project_key",
serverKey: process.env.EMBRASURE_ANALYTICS_SERVER_KEY!,
});
analytics.track({
id: "invoice_paid:invoice_123", // Reuse this ID when retrying this action.
event: "invoice_paid",
user_id: "user_123",
properties: { amount: 42, currency: "USD" },
});
const result = await analytics.flush();Pass identity with each backend event. Await flush() before a short-lived process exits; pending means work remains for retry. This SDK is best-effort analytics, not a transactional outbox.
401: check the selected environment's project key and any server credential.403: add the browser's exact origin to Allowed websites.422: check required fields, custom event names, and payload limits in the reference.