How to add analytics to Astro
Adding analytics to your Astro site helps you understand how visitors interact with your content. This guide walks you through setting up Helion to track page views, custom events, and user behavior in about five minutes.
Helion works well with Astro because it's a lightweight script that loads asynchronously and doesn't block your site's rendering. It tracks page views automatically across both static and server-rendered pages, and the component-based API fits naturally into Astro's architecture.
Prerequisites
- An Astro project
- An Helion account (sign up free)
- Your Client ID from the Helion dashboard
Install the SDK
Start by adding the Helion Astro package to your project. This package provides Astro components that handle initialization and tracking.
npm install @helionlabs/astroYou can also use pnpm or yarn if that's your preference.
Add the component to your layout
The HelionComponent initializes tracking and should be placed in your root layout so it loads on every page. Add it inside the <head> tag to ensure it initializes before any user interactions.
---
import { HelionComponent } from '@helionlabs/astro';
---
<html>
<head>
<HelionComponent
clientId="your-client-id"
trackScreenViews={true}
trackOutgoingLinks={true}
/>
</head>
<body>
<slot />
</body>
</html>The trackScreenViews option automatically records a page view event whenever someone navigates to a new page. The trackOutgoingLinks option tracks when visitors click links that take them to external sites. Both are optional but recommended for most sites.
You can also pass a profileId prop if you already know the user's identity at render time, and globalProperties to attach metadata to every event.
Track custom events
Beyond automatic page views, you'll want to track specific interactions that matter to your business. Helion exposes a global op function that you can call from any event handler.
<button onclick="window.op('track', 'button_clicked', {button_name: 'signup'})">
Sign up
</button>The first argument is always 'track', the second is your event name, and the third is an optional object of properties you want to attach to the event. Keep event names consistent across your codebase, using snake_case is a good convention.
For elements where you'd rather not write JavaScript, you can use data attributes instead. Any element with a data-track attribute will automatically fire an event when clicked.
<button data-track="button_clicked" data-button-name="signup">
Sign up
</button>Properties are pulled from any data-* attributes on the element. The data-track value becomes the event name, and other data attributes become event properties.
Tracking form submissions
Forms are a common tracking target. You can fire an event in the onsubmit handler while still allowing the form to submit normally.
<form onsubmit="window.op('track', 'form_submitted', {form_name: 'contact'}); return true;">
<input type="email" name="email" placeholder="Your email" required />
<button type="submit">Submit</button>
</form>The return true ensures the form submission continues after the tracking call.
Identify users
When a user logs in or you otherwise learn their identity, you can associate their activity with a profile. The IdentifyComponent handles this declaratively.
---
import { IdentifyComponent } from '@helionlabs/astro';
const user = await getCurrentUser();
---
<IdentifyComponent
profileId={user.id}
firstName={user.firstName}
lastName={user.lastName}
email={user.email}
properties={{
plan: user.plan,
}}
/>Place this component on pages where the user is authenticated. Once identified, all subsequent events from that browser session will be linked to this profile until they clear their browser data or you explicitly clear the identity.
Setting global properties
Sometimes you want to attach the same properties to every event, like an app version or environment. The SetGlobalPropertiesComponent lets you do this once rather than repeating it in every tracking call.
---
import { SetGlobalPropertiesComponent } from '@helionlabs/astro';
---
<SetGlobalPropertiesComponent
properties={{
app_version: '1.0.2',
environment: import.meta.env.MODE,
}}
/>These properties merge with any event-specific properties you pass to individual tracking calls.
Verify your setup
Open your Astro site in the browser and navigate between a few pages. Then open your Helion dashboard and check the Real-time view. You should see page view events appearing within seconds.
If events aren't showing up, open your browser's developer console and look for errors. The most common issues are an incorrect Client ID or an ad blocker preventing the tracking script from loading. You can also check the Network tab to confirm requests are being sent to Helion's servers.
Next steps
The Astro SDK reference covers additional configuration options like filtering events and customizing the CDN URL. If you're interested in running Helion on your own infrastructure, the self-hosting guide walks through the setup process.
