Events, live activity and funnels
Track explicit product actions in apps and websites, confirm delivery, and measure an ordered journey using Macaron’s own collector.
Start in your product workspace
Add your app or website, then open its Analytics tab. In Product analytics → Setup, enable event collection. This permission is separate from website traffic totals and customer chat. No model key, payment connection or repository is required. Every product starts with collection off. Only the signed-in owner can read events, configure collection or save funnels.
Install on a website
Choose HTML / React / Vite or Next.js in Setup and copy the filled-in script. For Next.js, put next/script in your shared layout inside body with strategy afterInteractive. For HTML or Vite, install the script once before the closing body tag. Add each exact HTTPS website origin to Allowed website origins; localhost HTTP is supported for development. If customer chat is already installed, add data-analytics-key with this public project key to the current chat script instead of installing a second analytics client. The key only permits event submission; it does not grant access to analytics, accounts or conversations.
Connect consent before tracking
Loading the SDK captures nothing and does not read or write an analytics identifier. In your existing consent manager, call window.MacaronAnalytics.setConsent(true) after permission is granted and the script is ready. Await it before capturing. Call setConsent(false) when permission is withdrawn; this cancels queued delivery and removes the browser identifier. You can also dispatch macaron:analytics-consent with detail { granted: true or false }. The website client respects Global Privacy Control, Do Not Track and window.macaronAnalyticsConsent === false. Owner enablement does not establish visitor consent. Listen for macaron:analytics-ready or check window.MacaronAnalytics before initializing your consent handler.
Capture successful actions
Call await window.MacaronAnalytics.capture("signup_completed", { screen: "Signup" }) only after that action succeeds. Event names use 2–64 lowercase letters, numbers or underscores and begin with a letter. Capture is explicit: Macaron does not automatically record clicks, forms, screen contents or session replays. Approved properties are screen, path, release, plan, result, step, variant, feature and duration_ms. Use short non-personal labels, booleans or finite numbers. Paths are normalized and query strings, fragments and common identifiers are removed. Do not send names, email addresses, secrets, payment details or arbitrary customer text.
Install in Expo or React Native
Choose Expo / React Native, download MacaronAnalytics.ts into your project and copy the generated initialization. It is editable framework-independent source with no native package dependency. Initialize one client outside a component render, use platform expo, ios or android as appropriate, await analytics.setConsent(true) after permission, then await analytics.capture for a real action. The default anonymous ID lasts only for that client’s lifetime. To preserve anonymous journeys across launches, supply the optional storage adapter { getId, setId, removeId } backed by your app’s existing consent-controlled storage. It is accessed only after consent and cleared on withdrawal. Test builds should use environment test.
Install in SwiftUI
Choose iOS / SwiftUI, download MacaronAnalytics.swift into your Xcode target and copy the generated client initialization. The actor uses Foundation and URLSession, not a web form. Use the deployed HTTPS Macaron server on physical devices; localhost on a phone refers to that phone. Await setConsent(true) after permission and try await capture for successful actions. The default anonymous ID is in memory. For cross-launch anonymous funnels, pass anonymousID from your own consent-controlled storage and erase it when permission is withdrawn. You remain responsible for your app’s privacy disclosures and device acceptance testing.
Keep identity consistent
After consent, use identify with an opaque internal ID before the first funnel step. Never use an email address. The server stores an app-specific hash of the ID; the event feed does not expose it. Anonymous and identified histories are separate and are not stitched together. On sign-out or account switching, call reset before tracking the next account, then identify the new account if appropriate. Website anonymous IDs use local storage after consent; if storage is blocked, they last only in memory. Native identity persistence must be supplied by the host app. Analytics IDs are not verified unique people.
Verify a real event
Run the generated setup_test example in your installed website or test build after granting your own test consent. Choose Test data → Live events. Setup confirms an event received with the current project key and shows its platform and environment. Installing a file alone is not proof of delivery. The feed checks every three seconds while visible, supports an event-name filter and keeps up to 200 recent rows on screen. A reload shows the latest 50 retained events. Live and test data are separate in both the feed and funnel results.
Save a funnel
In Funnels, choose Create funnel, name the journey, and enter 2–6 exact event names in the order they must occur. Choose a 1-hour, 24-hour or 7-day conversion window. For example: signup_started → signup_completed → first_project_created. Saved definitions can be edited and are evaluated over retained events in the last 7 or 30 days. Each analytics ID counts once per step. Other events may occur in between; repeated steps require distinct events. All matched steps must be received within both the selected date range and conversion window. Without start events, the conversion rate is empty. Recent starters may still convert later; drop-off alone does not establish a bug or a reason for churn.
Delivery and limits
The clients deliver events serially in server receive order and retry one network or server failure with the same event ID. The collector deduplicates exact retries and rejects conflicting reuse of an ID. There is no durable offline queue, client-time backdating or guaranteed delivery after an app closes. Each product retains up to 100,000 events across live and test data for 30 days; requests exceeding the cap are rejected rather than silently truncating a funnel. Public ingestion is rate limited. The public project key and supplied analytics IDs do not establish trusted identity or completed revenue. Keep verified payments in Revenue.
Pause, rotate and troubleshoot
Pause collection in Setup to reject new events while keeping retained history. Pausing and resuming keeps your project key. Saving origins rotates it, so update installed clients afterward. Setup waits for a receipt using the current key. If delivery fails, check consent and privacy signals, collection state, exact allowed origin, key, supported properties and the returned error. A receipt with received false means no event was stored. Browser blockers may prevent delivery. Saving a new website URL disables collection until the owner confirms settings again.
Self-hosted storage
The collector stores events and saved funnels in product-analytics.db inside the private DATA_DIR, with retention independent of account records. Keep that directory on a persistent volume and use one collector instance with the local database. For shared deployments, configure MACARON_ANALYTICS_DATABASE_URL and, when required, MACARON_ANALYTICS_AUTH_TOKEN for a libSQL-compatible database. Never expose these server credentials in install code. This first release does not include session replay, identity merging, automatic churn claims or PostHog-scale reporting.