Framework guides
Web Analytics is coming soon
Every example uses the site id hfa_k7m2p4q9x3w5n8r6; copy yours from the site's Settings → Install. On a domain hosted on Hubfly space with automatic injection on, you need none of this: HubProxy already adds the script.
Script tag or package
Both load the same per-site script. The script tag is the simplest and works everywhere. The @hubfly/analytics package adds the tag from your app's code, gives you typed track(), pageview() and identify() functions, and does nothing during server rendering or when HubProxy has already injected the script.
npm install @hubfly/analyticsEvery package entry takes the same options:
| Option | Meaning |
|---|---|
site | The site id, hfa_…. |
host | Where the script and events go. Defaults to /.hubfly/a, the first-party path on domains hosted on Hubfly space. Sites hosted elsewhere set https://hfa.<region>.hubfly.app. |
src | A full script URL, overriding site and host. |
Any HTML site
Add the tag to the <head> of every page, or of your shared layout or template:
<!-- Hosted on Hubfly space, with automatic injection off -->
<script defer src="/.hubfly/a/s/hfa_k7m2p4q9x3w5n8r6.js"></script>
<!-- Hosted elsewhere -->
<script defer src="https://hfa.<region>.hubfly.app/s/hfa_k7m2p4q9x3w5n8r6.js"></script>Next.js
Render <Analytics /> once in the root layout (App Router) or in _app (Pages Router). It is a client component that renders nothing; route changes are counted automatically.
import { Analytics } from "@hubfly/analytics/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Analytics site="hfa_k7m2p4q9x3w5n8r6" host="https://hfa.<region>.hubfly.app" />
</body>
</html>
);
}Track events from client components:
"use client";
import { track } from "@hubfly/analytics";
export function UpgradeButton() {
return <button onClick={() => track("Upgrade", { props: { plan: "pro" } })}>Upgrade</button>;
}React
For Vite, Create React App and other React setups, render <Analytics /> once near the root:
import { createRoot } from "react-dom/client";
import { Analytics } from "@hubfly/analytics/react";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<>
<App />
<Analytics site="hfa_k7m2p4q9x3w5n8r6" host="https://hfa.<region>.hubfly.app" />
</>,
);Vue and Nuxt
import { createApp } from "vue";
import { analytics } from "@hubfly/analytics/vue";
import App from "./App.vue";
createApp(App)
.use(analytics({ site: "hfa_k7m2p4q9x3w5n8r6", host: "https://hfa.<region>.hubfly.app" }))
.mount("#app");In Nuxt, install the plugin from a client-only plugin file:
import { analytics } from "@hubfly/analytics/vue";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(analytics({ site: "hfa_k7m2p4q9x3w5n8r6", host: "https://hfa.<region>.hubfly.app" }));
});SvelteKit
Call injectAnalytics once from the root layout. It does nothing during server rendering.
<script>
import { injectAnalytics } from "@hubfly/analytics/svelte";
injectAnalytics({ site: "hfa_k7m2p4q9x3w5n8r6", host: "https://hfa.<region>.hubfly.app" });
</script>
<slot />Astro
Add the tag to your base layout. is:inline keeps Astro from bundling it:
<head>
<script is:inline defer src="https://hfa.<region>.hubfly.app/s/hfa_k7m2p4q9x3w5n8r6.js"></script>
</head>Sites using view transitions are counted on each navigation, like any single-page app.
WordPress
Add the script tag to your theme's header with a plugin that inserts code into <head>, or in a child theme's functions.php:
add_action('wp_head', function () {
echo '<script defer src="https://hfa.<region>.hubfly.app/s/hfa_k7m2p4q9x3w5n8r6.js"></script>';
});Add /wp-admin/** to Exclude pages in the site's Settings → Tracking so editors' visits are not counted.
Single-page apps
The script counts a pageview on load and on every pushState, replaceState and back/forward navigation, so routers in React, Vue, Svelte and Angular need no extra code. If your app routes with the URL hash (/#/settings), turn on Hash-based routing in the site's Settings → Tracking. For screens that do not change the URL, send a manual pageview.
Testing locally
localhost and private addresses are ignored unless you turn on Count localhost. Use a separate site for development so test traffic stays out of your production reports.Node.js and other servers
@hubfly/analytics/server sends events through the server-side events API. It runs on Node.js 18 or later, Bun, Deno and Cloudflare Workers. Set HUBFLY_ANALYTICS_INGEST_KEY to an ingest key and HUBFLY_ANALYTICS_HOST to https://hfa.<region>.hubfly.app (or https://<your domain>/.hubfly/a on a domain hosted on Hubfly space).
import { AnalyticsServer } from "@hubfly/analytics/server";
const analytics = AnalyticsServer.fromEnv();
// In a payment webhook handler:
await analytics.track("Purchase", {
url: "https://example.com/checkout",
revenue: { amount: "29.99", currency: "USD" },
userId: order.customerId,
});
// Forward the visitor's IP and user agent when you have the request:
await analytics.pageview({
url: request.url,
ip: request.headers.get("x-forwarded-for")?.split(",")[0]?.trim(),
userAgent: request.headers.get("user-agent") ?? undefined,
referrer: request.headers.get("referer") ?? undefined,
});Events the collector refuses (wrong domain, malformed, filtered) are counted in the result's rejected number; the call itself only fails for an invalid body, a bad key or a request that is too large.