Astro

Name: Rybbit
Author: Rybbit

This guide explains how to integrate Rybbit with your Astro application for analytics tracking. Astro is a web framework for building content-rich websites, delivering minimal JavaScript by default.

How to Add Rybbit to Your Astro Site

The most common way to add a global script like Rybbit’s to an Astro site is by including it in a common layout component that is used across your pages, or directly within the <head> of your pages if you don’t use a shared layout.

1. Retrieve Your Tracking Script

Navigate to your Rybbit dashboard to obtain your code snippet. It will look like this:


<script
  src="https://app.rybbit.io/api/script.js"
  data-site-id="YOUR_SITE_ID"
  async
  defer
></script>

Remember to replace YOUR_SITE_ID with your actual Site ID.

2. Add the Snippet to a Common Layout or Page Head

Using a Common Layout (Recommended):

If you have a common layout component (e.g., src/layouts/Layout.astro or similar) that wraps your pages, this is the best place to add the script.

Open your layout file and add the Rybbit script tag within the <head> section.

src/layouts/Layout.astro


---
// src/layouts/Layout.astro
export interface Props {
	title: string;
}
 
const { title } = Astro.props;
const rybbitSiteId = "YOUR_SITE_ID"; // Replace with your actual Site ID
---
<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="description" content="Astro description" />
		<meta name="viewport" content="width=device-width" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<meta name="generator" content={Astro.generator} />
		<title>{title}</title>
 
    <!-- Rybbit Tracking Snippet -->
    <script
      src="https://app.rybbit.io/api/script.js"
      data-site-id={rybbitSiteId}
      async
      defer
    ></script>
	</head>
	<body>
		<slot /> <!-- Page content will be injected here -->
	</body>
</html>

Make sure to replace YOUR_SITE_ID with your actual Site ID.

Adding Directly to Individual Pages (If not using a common layout):

If you don’t have a common layout, you can add the script to the <head> of each .astro page file in your src/pages/ directory. However, using a layout is more maintainable.

3. Verify Installation

After building and deploying your Astro site, open your Rybbit dashboard to check if data is being received. You can also inspect your browser’s network tab to confirm that script.js is loaded on your pages.

Page View Tracking in Astro:

MPA (Multi-Page Application) Mode: By default, Astro builds multi-page applications. When a user navigates between different pages, a full page load occurs, and Rybbit’s script will naturally track this as a new page view.
View Transitions: If you are using Astro’s View Transitions API for client-side navigation effects, Rybbit’s script should generally still detect these as page views if the URL changes. However, if you notice issues, you might need to manually trigger page views. You can listen to Astro’s astro:after-swap event:
```
// In a client-side script, perhaps in your common layout or a global script file
document.addEventListener('astro:after-swap', () => {
  if (window.rybbit) {
    window.rybbit.trackPageview();
  }
});
```

Test the default behavior first.

Custom Event Tracking

You can track custom events from client-side JavaScript within your Astro site. This can be done in <script> tags within your .astro files or from JavaScript modules imported into Astro components (especially within UI framework components used as Astro islands).

Example in an Astro component’s client-side script:


---
// src/components/MyButton.astro
---
<button id="my-astro-button">Click Me in Astro</button>
 
<script>
  document.getElementById('my-astro-button')?.addEventListener('click', () => {
    if (window.rybbit) {
      window.rybbit.trackEvent('astro_button_click', { source: 'MyButton.astro' });
    }
  });
</script>

Example within a React/Vue/Svelte island component used in Astro:

If you’re using a UI framework component (e.g., React) as an island in Astro, you’d track events from within that component’s logic, similar to how you would in a standalone app of that framework:


// src/components/MyReactIsland.jsx (used in an .astro file)
import React from 'react';
 
export default function MyReactIsland() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.trackEvent('react_island_click', { island: 'MyReactIsland' });
    }
  };
  return <button onClick={handleClick}>Click Me (React Island)</button>;
}

Always ensure window.rybbit is available before calling its methods in client-side scripts.