First-party analytics integration for Next.js, Laravel, React and static sites

MetricFold has two installation modes. Hosted mode is one deferred script and needs no Nginx configuration. Optional same-origin mode proxies only the tracker, tracking plan and event routes through your product domain. Both modes use the same privacy boundary and reports. Choose the mode that fits your Content Security Policy and infrastructure; a proxy is not required for maps, geography or live updates.

Start with the generated site manifest

Create the site through the dashboard, REST API, MCP server or MetricFold CLI. The response includes a public site key, exact collector URL, hosted snippet and platform recipes. Use the generated values rather than copying placeholders from a guide.

The tracker is deferred, framework-free and budgeted below 7 kB gzip. It does not set an analytics cookie or use browser storage for a permanent visitor id. It observes page navigation and bounded interactions after the document is ready, and a delivery failure never blocks the measured product action. The generated script element contains a deferred tracker source plus the site-specific event and plan endpoints.

Use the snippet shown for your site because route and integrity details may evolve. Set an exact allowed origin in MetricFold and verify from the real canonical hostname.

Next.js App Router

Place the tracker in the root layout with Next.js Script and an after-interactive or lazy strategy appropriate to your measurement needs. The current Next.js script guide describes next/script as the supported way to control script loading and recommends deferring analytics so it does not compete with primary content.

MetricFold listens to History API changes, so client-side routes produce page views without mounting a tracker component on every page. For explicit product outcomes, call window.metricfold.capture() after the server confirms the action, or add a semantic data-analytics-action attribute to the stable control.

For same-origin routes, Next.js rewrites can map exact paths such as /mf/tracker.js, /mf/plan and /mf/e to the generated MetricFold upstream. The official rewrite reference documents that rewrites proxy the destination while preserving the visible URL. Do not use a catch-all analytics proxy. Exact routes make method, cache and credential policies auditable.

React and other client routers

Load the tracker once in the document shell. It patches pushState and replaceState and observes popstate, so duplicate route-specific integrations are unnecessary. If a framework changes the route without History API semantics, dispatch the explicit page event once after the route is committed.

Use a stable semantic attribute such as data-analytics-cta on the important link, with a value such as pricing.start-trial.

The tracker records the stable identifier, not the visible link text. Copy changes and localization therefore do not fragment the report. For a confirmed product action, prefer an event such as project.exported over a generic button_clicked event. Include a small allowlisted property set—plan key, workflow stage or result class—not free-form text or field values.

Laravel and Inertia

Add the deferred snippet to the root Blade document so SSR pages contain their indexable content before analytics JavaScript runs. Inertia navigation is covered through the History API. Server-side outcomes should be recorded after the domain transition succeeds. Payment and entitlement events must originate from verified webhooks or the server-side lifecycle adapter.

If Laravel serves the optional proxy, define exact GET routes for the tracker and plan plus an exact POST route for events. Forward the original normalized product origin through a trusted server boundary, drop application cookies and authorization headers, cap request/response sizes and use short timeouts. Do not make a normal product request wait for analytics.

Use queued or after-response delivery only for events that are safe to retry with an idempotency key. An ambiguous timeout on a money-changing provider request cannot be labelled failed merely because the analytics delivery was uncertain.

Static HTML, Webflow and site builders

Add the hosted snippet before the closing body tag or through the platform's site-wide custom-code field. Hosted mode is the correct choice when the platform does not provide secure server rewrites. Configure the exact production origin and publish. Use semantic data attributes on important links and forms where the builder preserves custom attributes.

Do not install a broad tag manager merely to fire one analytics script. If advertising destinations are required, configure MetricFold's server-side destination rules with their own consent and field policy. Core first-party analytics and advertising delivery remain separate.

Protect page speed

Measure the host before and after installation on the same page and network profile. The important checks are:

• the script is deferred and outside the critical rendering path;
• no synchronous request delays Largest Contentful Paint;
• event listeners are delegated rather than attached to every control;
• Core Web Vitals collection uses browser observers without layout reads in a hot loop;
• delivery uses a bounded non-blocking request or beacon;
• the optional selector and map code load only inside authenticated product surfaces;
• an unavailable collector does not delay navigation.

The dashboard chart and MapLibre bundles are not part of the customer tracker. Lighthouse on a customer site should therefore measure the small standalone tracker, not MetricFold's authenticated application bundle.

Instrument the activation funnel

Page views alone cannot explain product value. Define a short funnel with trusted outcomes:

1. landing page viewed;
2. signup committed by the server;
3. onboarding completed;
4. first-value action confirmed;
5. checkout started;
6. payment verified by the provider.

MetricFold's tracking-plan manager and free generator create stable definitions. Reusable site funnels can then select sequential or strict mode, event names and optional page patterns. The same funnel is available to the dashboard, REST report and MCP analyst.

Verify the integration before release

Test initial page load, client navigation, back/forward navigation, outbound links, downloads, form abandonment, a semantic CTA and one server-trusted product action. Send the same event id twice and confirm it counts once. Send from a foreign origin and confirm it is rejected. Inspect response headers for Set-Cookie, verify no DOM text or form values appear, and run mobile/desktop Lighthouse.

For the same-origin mode, test tracker caching independently from event POST caching, redirects, request-size limits, upstream timeout and host failure. Keep hosted mode as a diagnostic fallback until production traffic is visible.

Release framework integrations safely

Prevent duplicate initialization

Hot reload, nested layouts and partial navigation can mount application code more than once. Install the tracker in one document-level location and ensure a second initialization is a no-op. Test strict development mode and production navigation separately. Duplicate listeners can inflate CTA events even when page views appear correct, so verify one interaction produces one event id.

When a product has both marketing and authenticated applications on separate origins, register them as explicit allowed origins or separate analytics sites according to the reporting boundary you want. Do not accept wildcard origins merely to make staging work. Keep staging data in its own site or exclusion policy so internal testing does not distort production conversion.

Separate public and trusted events

Client collection covers page views, campaign fields, interaction intent, performance and privacy-safe friction. The application server covers signup commitment, onboarding completion, first value and other domain outcomes. Verified provider webhooks cover money and subscription state. That separation prevents a person or bot from posting payment_completed through a public collector and corrupting revenue.

Use product analytics to define first value, funnel analytics to select sequential or strict steps and first-party proxy guidance when your deployment needs exact same-origin routes. The hosted route remains the shortest safe installation.

Frequently asked questions

Does a first-party route remove the need for consent?

No universal technical configuration decides the legal question. Same-origin delivery and cookie-free collection reduce the surface, but purpose, fields, retention, destinations and jurisdiction still matter. MetricFold keeps advertising destinations separate and avoids permanent anonymous profiles by default. Review the privacy architecture for the implemented boundary.

Will MetricFold lower a site's PageSpeed score?

The tracker is deferred and has a hard gzip budget, but every host must still be measured. Compare the same representative page before and after installation under mobile throttling. The authenticated dashboard's chart and map libraries are not downloaded by the measured customer site.

Do I need to fire an event for every button?

No. MetricFold automatically handles page navigation and bounded generic interaction evidence. Add semantic CTA attributes to the few acquisition controls you want to compare, and explicit product events to confirmed outcomes that answer an activation, retention, revenue or friction question. A giant stream of generic clicks increases storage while making decisions harder.