Install the browser, Node.js, or Python SDK and send your first product event.
Send pageviews and product actions, including clickstream events, to an Embrasure Analytics project. Your browser and backend can use the same project.
What gets captured
The browser SDK captures pageviews by default. Add track calls for clicks and other actions you choose. It does not automatically capture clicks, form contents, session replay, or feature flags.
Open Analytics in Embrasure. The first time, choose Copy setup prompt and paste it into a coding agent, or install by hand under Or install it yourself and choose Create project. Either one creates a project with production and development keys, turning on Analytics if it is off. Copying the prompt keeps you on the page and lists the new project under Projects, which updates when its first event arrives; Create project opens its Production Setup tab with your key filled in. To add another app later, choose New project on the Analytics page; it offers the same two paths and asks for the app's name. Only a workspace admin can do this.
Choose an environment and copy its public project key. For browser events, open Settings on the Setup tab and add your site's exact origin to Allowed websites, such as https://app.example.com or http://localhost:3000. Include the scheme and port, but no page path. Development and production use separate keys and allowed websites.
For backend events, also create a server key under Settings on the Setup tab. Keep it in a server environment variable. Never put it in browser code or a NEXT_PUBLIC_ variable.
npm install @embrasure/analyticsAll three clients send to https://api.embrasure.ai/collect by default. Use the project key from the same environment in each integration.
Initialize once in browser code, then call track from a click handler or completed action:
import { createAnalytics } from "@embrasure/analytics";
export const analytics = createAnalytics({
projectKey: "pk_your_project_key",
});
analytics.track("signup_started", { source: "pricing" });The client records the initial page and pathname changes, including back/forward navigation. For Next.js 15.3 or later, initialize in instrumentation-client.ts at the project root, or inside src if your app uses it. Import the instance only from browser code.
Trigger the action. In project setup, check Event received, then run the separate Ready in reports check. Collection acceptance means the collector acknowledged the event; reports become available after warehouse processing.
While testing the browser client, call await analytics.flush() and inspect accepted, discarded, dropped, and pending. Node.js flush() and Python flush(timeout=...) or shutdown(timeout=...) return the same counts. discarded means the event was not stored; pending means delivery has not finished.
| Purpose | Browser | Node.js server | Python server |
|---|---|---|---|
| Record an action | track(name, properties) | track(message) | track(name, **fields) |
| Update user traits | identify(userId, traits) | identify(message) | identify(user_id, **fields) |
| Update group traits | group(type, key, traits) | group(message) | group(type, key, **fields) |
| Record a pageview | page(); automatic by default | Send a page message through the collection API | Send a page message through the collection API |
| Send queued events now | flush() | flush() | flush(timeout=...) |
| End a client | destroy() | destroy() | shutdown(timeout=...) |
In the browser, call identify after sign-in and reset() on logout or account change. group associates the current browser identity with a company or other group:
analytics.identify("user_123", { plan: "pro" });
analytics.group("company", "company_456", { seats: 5 });
analytics.track("report_created", { report_id: "report_789" });
// On logout: analytics.reset();Server SDKs do not retain a current user, group, or session. Include identity on every message. Python's track, identify, and group return True when a message is queued, not delivered.
For consent-controlled browser collection, initialize with enabled: false and call analytics.setEnabled(true) after consent. Your app owns consent persistence. Set capturePageview: false and call analytics.page() if you want to control pageviews yourself.
Browser page data includes pathname and host, but excludes query strings, fragments, page text, and form values. Keep secrets and sensitive values out of event properties. The browser saves pending events locally for retry when storage is available; shutdown remains best effort. Server clients buffer events in memory. Use a transactional outbox when an event must survive an application crash.
| Symptom | Check |
|---|---|
401 | Confirm the environment's project key and server credential. |
403 | Add the browser's exact origin to Allowed websites. |
422 | Check required fields, event names, and payload limits. |
| Accepted but absent from reports | Confirm the project and environment, then check Ready in reports. |
For browser diagnostics without logging event bodies or credentials, pass onDiagnostic: ({ type, count, reason }) => console.info(type, count, reason) to createAnalytics.
See the collection API for fields, limits, receipts, and errors, or the OpenAPI schema for native request and response models.