|
| 1 | +--- |
| 2 | +title: "How to add analytics to Astro" |
| 3 | +description: "Add privacy-first analytics to your Astro site with OpenPanel. Track page views, custom events, and user behavior without cookies." |
| 4 | +difficulty: beginner |
| 5 | +timeToComplete: 5 |
| 6 | +date: 2025-12-14 |
| 7 | +cover: /content/cover-default.jpg |
| 8 | +team: OpenPanel Team |
| 9 | +steps: |
| 10 | + - name: "Install the SDK" |
| 11 | + anchor: "install" |
| 12 | + - name: "Add the component to your layout" |
| 13 | + anchor: "setup" |
| 14 | + - name: "Track custom events" |
| 15 | + anchor: "events" |
| 16 | + - name: "Identify users" |
| 17 | + anchor: "identify" |
| 18 | + - name: "Verify your setup" |
| 19 | + anchor: "verify" |
| 20 | +--- |
| 21 | + |
| 22 | +# How to add analytics to Astro |
| 23 | + |
| 24 | +Adding analytics to your Astro site helps you understand how visitors interact with your content. This guide walks you through setting up OpenPanel to track page views, custom events, and user behavior in about five minutes. |
| 25 | + |
| 26 | +OpenPanel 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. |
| 27 | + |
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +- An Astro project |
| 31 | +- An OpenPanel account ([sign up free](https://dashboard.openpanel.dev/onboarding)) |
| 32 | +- Your Client ID from the OpenPanel dashboard |
| 33 | + |
| 34 | +## Install the SDK [#install] |
| 35 | + |
| 36 | +Start by adding the OpenPanel Astro package to your project. This package provides Astro components that handle initialization and tracking. |
| 37 | + |
| 38 | +```bash |
| 39 | +npm install @openpanel/astro |
| 40 | +``` |
| 41 | + |
| 42 | +You can also use pnpm or yarn if that's your preference. |
| 43 | + |
| 44 | +## Add the component to your layout [#setup] |
| 45 | + |
| 46 | +The `OpenPanelComponent` 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. |
| 47 | + |
| 48 | +```astro |
| 49 | +--- |
| 50 | +import { OpenPanelComponent } from '@openpanel/astro'; |
| 51 | +--- |
| 52 | +
|
| 53 | +<html> |
| 54 | + <head> |
| 55 | + <OpenPanelComponent |
| 56 | + clientId="your-client-id" |
| 57 | + trackScreenViews={true} |
| 58 | + trackOutgoingLinks={true} |
| 59 | + /> |
| 60 | + </head> |
| 61 | + <body> |
| 62 | + <slot /> |
| 63 | + </body> |
| 64 | +</html> |
| 65 | +``` |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +## Track custom events [#events] |
| 72 | + |
| 73 | +Beyond automatic page views, you'll want to track specific interactions that matter to your business. OpenPanel exposes a global `op` function that you can call from any event handler. |
| 74 | + |
| 75 | +```astro |
| 76 | +<button onclick="window.op('track', 'button_clicked', {button_name: 'signup'})"> |
| 77 | + Sign up |
| 78 | +</button> |
| 79 | +``` |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | +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. |
| 84 | + |
| 85 | +```astro |
| 86 | +<button data-track="button_clicked" data-button-name="signup"> |
| 87 | + Sign up |
| 88 | +</button> |
| 89 | +``` |
| 90 | + |
| 91 | +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. |
| 92 | + |
| 93 | +### Tracking form submissions |
| 94 | + |
| 95 | +Forms are a common tracking target. You can fire an event in the `onsubmit` handler while still allowing the form to submit normally. |
| 96 | + |
| 97 | +```astro |
| 98 | +<form onsubmit="window.op('track', 'form_submitted', {form_name: 'contact'}); return true;"> |
| 99 | + <input type="email" name="email" placeholder="Your email" required /> |
| 100 | + <button type="submit">Submit</button> |
| 101 | +</form> |
| 102 | +``` |
| 103 | + |
| 104 | +The `return true` ensures the form submission continues after the tracking call. |
| 105 | + |
| 106 | +## Identify users [#identify] |
| 107 | + |
| 108 | +When a user logs in or you otherwise learn their identity, you can associate their activity with a profile. The `IdentifyComponent` handles this declaratively. |
| 109 | + |
| 110 | +```astro |
| 111 | +--- |
| 112 | +import { IdentifyComponent } from '@openpanel/astro'; |
| 113 | +
|
| 114 | +const user = await getCurrentUser(); |
| 115 | +--- |
| 116 | +
|
| 117 | +<IdentifyComponent |
| 118 | + profileId={user.id} |
| 119 | + firstName={user.firstName} |
| 120 | + lastName={user.lastName} |
| 121 | + email={user.email} |
| 122 | + properties={{ |
| 123 | + plan: user.plan, |
| 124 | + }} |
| 125 | +/> |
| 126 | +``` |
| 127 | + |
| 128 | +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. |
| 129 | + |
| 130 | +### Setting global properties |
| 131 | + |
| 132 | +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. |
| 133 | + |
| 134 | +```astro |
| 135 | +--- |
| 136 | +import { SetGlobalPropertiesComponent } from '@openpanel/astro'; |
| 137 | +--- |
| 138 | +
|
| 139 | +<SetGlobalPropertiesComponent |
| 140 | + properties={{ |
| 141 | + app_version: '1.0.2', |
| 142 | + environment: import.meta.env.MODE, |
| 143 | + }} |
| 144 | +/> |
| 145 | +``` |
| 146 | + |
| 147 | +These properties merge with any event-specific properties you pass to individual tracking calls. |
| 148 | + |
| 149 | +## Verify your setup [#verify] |
| 150 | + |
| 151 | +Open your Astro site in the browser and navigate between a few pages. Then open your [OpenPanel dashboard](https://dashboard.openpanel.dev) and check the Real-time view. You should see page view events appearing within seconds. |
| 152 | + |
| 153 | +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 OpenPanel's servers. |
| 154 | + |
| 155 | +## Next steps |
| 156 | + |
| 157 | +The [Astro SDK reference](/docs/sdks/astro) covers additional configuration options like filtering events and customizing the CDN URL. If you're interested in running OpenPanel on your own infrastructure, the [self-hosting guide](/articles/how-to-self-host-openpanel) walks through the setup process. |
| 158 | + |
| 159 | +<Faqs> |
| 160 | +<FaqItem question="Does OpenPanel work with Astro Islands?"> |
| 161 | +Yes. The OpenPanelComponent is a client-side script that hydrates independently of your island components. It will track interactions across your entire page regardless of which parts are hydrated. |
| 162 | +</FaqItem> |
| 163 | + |
| 164 | +<FaqItem question="Can I use OpenPanel with Astro's SSR mode?"> |
| 165 | +Yes. OpenPanel works with both static and server-rendered Astro sites. The tracking script runs in the browser regardless of how the page was rendered. |
| 166 | +</FaqItem> |
| 167 | + |
| 168 | +<FaqItem question="Does OpenPanel use cookies?"> |
| 169 | +No. OpenPanel uses cookieless tracking by default, which means you don't need cookie consent banners for basic analytics under most privacy regulations including GDPR. Read more about [cookieless analytics](/articles/cookieless-analytics). |
| 170 | +</FaqItem> |
| 171 | +</Faqs> |
0 commit comments