Astro

Install EngageTrack in your Astro website.

Astro

Add EngageTrack analytics to your Astro site. Astro's partial hydration and multi-page architecture make it a great fit for lightweight analytics.

1. Add to Your Base Layout

Open your base layout file (typically src/layouts/Layout.astro) and add the script inside the <head> tag:

---
// src/layouts/Layout.astro
interface Props {
	title: string;
}
const { title } = Astro.props;
---
 
<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>{title}</title>
		<script
			is:inline
			defer
			data-site-id="YOUR_SITE_ID"
			src="https://cdn.engagetrack.net/sdk.js"></script>
	</head>
	<body>
		<slot />
	</body>
</html>

The is:inline directive is required. Without it, Astro will try to bundle the script, which breaks the external SDK loading. is:inline tells Astro to leave the script tag as-is in the HTML output.

2. Environment Variables

Use Astro's built-in environment variable support to avoid hardcoding the Site ID. Add to your .env file:

PUBLIC_ENGAGETRACK_SITE_ID=your-site-id-here

Then reference it in your layout:

<script
	is:inline
	defer
	data-site-id={import.meta.env.PUBLIC_ENGAGETRACK_SITE_ID}
	src="https://cdn.engagetrack.net/sdk.js"></script>

Astro environment variables must be prefixed with PUBLIC_ to be available in client-side code and templates.

3. View Transitions Support

If you use Astro's View Transitions (<ViewTransitions />), the EngageTrack SDK handles this automatically. It listens to the History API, so view transition navigations are tracked as pageviews without any extra configuration.

---
import { ViewTransitions } from "astro:transitions";
---
 
<head>
	<ViewTransitions />
	<script
		is:inline
		defer
		data-site-id="YOUR_SITE_ID"
		src="https://cdn.engagetrack.net/sdk.js"></script>
</head>

4. Track Goals

For static pages, use the data-goal HTML attribute:

<button data-goal="cta-click">Get Started</button>
<a href="/pricing" data-goal="pricing-viewed">View Pricing</a>

For interactive components (React, Vue, Svelte islands), use the JavaScript API:

// src/components/SignupForm.tsx (React island)
export default function SignupForm() {
	const handleSubmit = () => {
		window.engagetrack("signup-completed");
	};
 
	return (
		<form onSubmit={handleSubmit}>
			<input type="email" placeholder="Email" />
			<button type="submit">Sign Up</button>
		</form>
	);
}

5. Astro with SSR

If you're running Astro in SSR mode (with an adapter like @astrojs/node or @astrojs/vercel), the script tag in your layout works the same way. The is:inline directive ensures it renders as plain HTML regardless of rendering mode.

For server-side event tracking, you can read the visitor cookies in your API routes:

// src/pages/api/convert.ts
import type { APIRoute } from "astro";
 
export const POST: APIRoute = async ({ cookies }) => {
	const visitorId = cookies.get("engagetrack_visitor_id")?.value;
	const sessionId = cookies.get("engagetrack_session_id")?.value;
 
	await fetch("https://api.engagetrack.net/api/v1/event", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({
			site_id: import.meta.env.PUBLIC_ENGAGETRACK_SITE_ID,
			name: "server-conversion",
			visitor_id: visitorId,
			session_id: sessionId,
		}),
	});
 
	return new Response(JSON.stringify({ ok: true }), { status: 200 });
};

Verify Installation

Run npm run dev to start the Astro dev server.
Open your site and navigate between a few pages.
In the EngageTrack dashboard, go to the Realtime tab — your visits should appear within seconds.

If you see your pageviews in Realtime, you're all set. If not, add data-debug="true" to the script tag and check the browser console for diagnostic messages.