### Install astro-analytics with npm, pnpm, or yarn

Source: https://github.com/destiner/astro-analytics/blob/main/README.md

Install the astro-analytics package using npm, pnpm, or yarn. Choose one of the three commands.

```bash
npm install astro-analytics
# or
pnpm install astro-analytics
# or
yarn add astro-analytics
```

--------------------------------

### GoogleAnalytics Usage Examples

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/google-analytics.md

Two usage examples: the first hard-codes the tracking ID, the second passes the ID from the site's frontmatter configuration, choosing between production and development IDs based on `Astro.site`. Both import `GoogleAnalytics` from the package root.

```astro
---
import { GoogleAnalytics } from 'astro-analytics';
---
<html>
  <head>
    <GoogleAnalytics id="UA-156492295-1" />
  </head>
</html>
```

```astro
---
import { GoogleAnalytics } from 'astro-analytics';
const GA_ID = Astro.site?.includes('example.com') ? 'UA-156492295-1' : 'UA-DEV-1';
---
<head>
  <GoogleAnalytics id={GA_ID} />
</head>
```

--------------------------------

### Matomo emitted markup example

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/matomo.md

Example emitted markup when `url = "https://yourdomain.com"` and `id = "1"`. Shows the resolved tracker and endpoint URLs.

```html
<script async src="https://yourdomain.com/matomo.js"></script>
<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['disableCookies']);
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    _paq.push(['setTrackerUrl', 'https://yourdomain.com/matomo.php']);
    _paq.push(['setSiteId', '1']);
  })();
</script>
```

--------------------------------

### Plausible emitted markup with default src

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/plausible.md

Example of the emitted markup with the default `src` and `domain = "yourdomain.com"`.

```html
<script src="https://plausible.io/js/script.js" data-domain="yourdomain.com" defer></script>
```

--------------------------------

### Usage example with Fathom component

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/index.md

Shows how to use the package in an Astro project. Imports the Fathom component and places it in the head with a site prop. All nine components emit script and inline define:vars markup where placed.

```astro
---
import { Fathom } from 'astro-analytics';
---
<html>
  <head>
    <Fathom site="ABCDEF" />
  </head>
  <body>…</body>
</html>
```

--------------------------------

### Rendered script tag and example output

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/umami.md

The component renders a single script tag with defer, src as concatenation of site and host, and data-website-id attribute. The second block shows the emitted markup with example values; no URL normalization is performed, so a trailing slash in site would produce a double slash.

```html
<script defer src={site}{host} data-website-id={dataId}></script>
```

```html
<script defer src="https://your-umami-app.com/umami.js" data-website-id="4fb7fa4c-5b46-438d-94b3-3a8fb9bc2e8b"></script>
```

--------------------------------

### Emitted script with example ID

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/minimal-analytics.md

The full rendered script when `id = "UA-156492295-1"`. It includes the tracking logic and the fixed options object. The script is deferred and inline.

```HTML
<script defer>
(function(a,b,c){var d=a.history,e=document,f=navigator||{},g=localStorage,
h=encodeURIComponent,i=d.pushState,k=function(){return Math.random().toString(36)},
l=function(){return g.cid||(g.cid=k()),g.cid},m=function(r){var s=[];for(var t in r)
r.hasOwnProperty(t)&&void 0!==r[t]&&s.push(h(t)+"="+h(r[t]));return s.join("&")},
n=function(r,s,t,u,v,w,x){var z="https://www.google-analytics.com/collect", …};
…
})(window,'UA-156492295-1',{anonymizeIp:true,colorDepth:true,characterSet:true,screenSize:true,language:true});
</script>
```

--------------------------------

### Fathom component rendered markup with defaults

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/fathom.md

Example of the rendered markup with the default `src` and a sample `site` ID.

```html
<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEF" defer></script>
```

--------------------------------

### Metrical Emitted Markup with app='j5gZ1K26a'

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

Example output when `app` is set to 'j5gZ1K26a', showing the literal app ID in the `window.metrical` object.

```html
<script async src="https://cdn.metrical.xyz/script.js" type="text/javascript"></script>
<script>
window.metrical = {
  app: 'j5gZ1K26a',
};
</script>
```

--------------------------------

### Plausible Component

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/plausible.md

Documentation for the Plausible Astro component, including its props, rendered markup, and usage examples.

```APIDOC
## [COMPONENT] Plausible

### Description
Astro component that embeds the Plausible analytics tracker script into a page. It renders a single script tag with the provided domain and optional source URL.

### Import
```ts
import { Plausible } from 'astro-analytics';
```

### Props
- **domain** (string) - Required - Plausible site domain, emitted as the `data-domain` attribute of the tracker script tag.
- **src** (string) - Optional - URL of the Plausible tracker script. Defaults to `'https://plausible.io/js/script.js'`. Omit to use the Plausible-hosted script, or pass a custom URL for self-hosted Plausible.

### Rendered Markup
With default `src` and `domain = "yourdomain.com"`:
```html
<script src="https://plausible.io/js/script.js" data-domain="yourdomain.com" defer></script>
```
The tag is marked `defer`, so the script executes after the HTML is parsed. The component returns no value; it renders only this fragment — no comments, no `<noscript>` fallback, and no inline bootstrap script are emitted.

### Throws / Rejects
- **Throw:** none. The component performs no validation or error handling; a missing `domain` renders `data-domain=""`.
- **Unspecified behavior:** `src` is substituted verbatim; an empty string `src=""` would render `<script src="" …>` because the destructuring default only applies to `undefined`.

### Examples
Basic usage — the default Plausible-hosted script:
```astro
---
import { Plausible } from 'astro-analytics';
---
<html>
  <head>
    <Plausible domain="yourdomain.com" />
  </head>
</html>
```

Self-hosted Plausible — point `src` at your own tracker script:
```astro
<Plausible domain="yourdomain.com" src="https://yourdomain.com/js/script.js" />
```
```

--------------------------------

### GoogleAnalytics Rendered Markup and Example Output

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/google-analytics.md

The rendered markup of the component and the emitted HTML when `id` is `UA-156492295-1`. The inline script uses Astro's `define:vars` to create a global `window.dataLayer` array, define a `window.gtag()` function that pushes arguments, and issue the initial calls `gtag('js', new Date())` and `gtag('config', id)`. The script tag is `async` with no `defer`.

```html
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src={gtagUrl}></script>
<script define:vars={{id}}>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', id);
</script>
```

```html
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-156492295-1"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'UA-156492295-1');
</script>
```

--------------------------------

### GoogleAnalytics Component

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/google-analytics.md

Documentation for the GoogleAnalytics Astro component, including its props, rendered markup, behavior, and usage examples.

```APIDOC
## GoogleAnalytics Component

### Description
Astro component that embeds the Google Analytics gtag.js tag (the "Global site tag") into a page. It renders a loader script, an HTML comment, and an inline bootstrap script that initializes the dataLayer and gtag function.

### Import
```ts
import { GoogleAnalytics } from 'astro-analytics';
```

### Props
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | `string` | — (required) | Google Analytics tracking ID (e.g. `UA-156492295-1`). It is URL-embedded into the gtag.js loader URL and passed to `gtag('config', id)`. |

### Rendered Markup
With `id = "UA-156492295-1"` the emitted markup is:

```html
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-156492295-1"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'UA-156492295-1');
</script>
```

### Behavior
The inline script (using Astro's `define:vars`) creates/keeps a global `window.dataLayer` array, defines a global `window.gtag()` function that pushes its arguments onto that array, then issues the standard initial calls `gtag('js', new Date())` and `gtag('config', id)`.

### Throws / Rejects
- **Throw:** none. The component performs no validation; an empty `id` merely produces `gtag/js?id=` in the URL.
- **Unspecified behavior:** the script tag is `async`; no `defer` is set (unlike `Fathom`, `Plausible`, and `Umami`). Whether dataLayer hits reach Google before the loader finishes loading is outside this component's control.

### Examples
Basic usage:

```astro
---
import { GoogleAnalytics } from 'astro-analytics';
---
<html>
  <head>
    <GoogleAnalytics id="UA-156492295-1" />
  </head>
</html>
```

Pass the ID from the site's frontmatter configuration rather than hard-coding it:

```astro
---
import { GoogleAnalytics } from 'astro-analytics';
const GA_ID = Astro.site?.includes('example.com') ? 'UA-156492295-1' : 'UA-DEV-1';
---
<head>
  <GoogleAnalytics id={GA_ID} />
</head>
```
```

--------------------------------

### Use analytics components in Astro templates

Source: https://github.com/destiner/astro-analytics/blob/main/README.md

Use the analytics components in your Astro templates. Each component accepts service-specific props; for example, Fathom and Plausible fall back to default script URLs when no src is provided. Replace the placeholder values with your own site IDs, API keys, and domains.

```html
<Fathom site="ABCDEF" src="https://youdomain.com/script.js" /> (if no src is set it will fallback to https://cdn.usefathom.com/script.js)
<GoogleAnalytics id="UA-156492295-1" />
<Metrical app="j5gZ1K26a" />
<Plausible domain="yourdomain.com" src="https://youdomain.com/yoursript.js" /> (if no src is set it will fallback to https://plausible.io/js/script.js)
<SimpleAnalytics />
<Umami id="4fb7fa4c-5b46-438d-94b3-3a8fb9bc2e8b" src="https://your-umami-app.com/umami.js" />
<Amplitude apiKey="<YOUR API KEY>" />
<Matomo id="1" src="https://yourdomain.com" />
<MinimalAnalytics id="UA-156492295-1" />
```

--------------------------------

### Basic Umami usage with default host

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/umami.md

Basic usage with default host, serving the script from the app root. Place the component in the head of an Astro page.

```astro
---
import { Umami } from 'astro-analytics';
---
<html>
  <head>
    <Umami site="https://your-umami-app.com" dataId="4fb7fa4c-5b46-438d-94b3-3a8fb9bc2e8b" />
  </head>
</html>
```

--------------------------------

### Self-hosted Plausible usage with custom src

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/plausible.md

Self-hosted Plausible usage by passing a custom `src` URL to your own tracker script.

```astro
<Plausible domain="yourdomain.com" src="https://yourdomain.com/js/script.js" />
```

--------------------------------

### Amplitude rendered script

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/amplitude.md

Rendered markup of the Amplitude component. It loads the analytics-browser SDK async from the CDN and initializes it with amplitude.init(apiKey). If the SDK fails to load, it logs "[Amplitude] Error: could not load SDK". If included more than once, the second load logs "Amplitude snippet has been loaded." and skips re-initialization.

```html
<script>
!function(){"use strict";!function(e,t){var r=e.amplitude||{_q:[],_iq:[]};if(r.invoked)e.console&&console.error&&console.error("Amplitude snippet has been loaded.");else{r.invoked=!0;var n=t.createElement("script");n.type="text/javascript",n.integrity="sha384-…",n.crossOrigin="anonymous",n.async=!0,n.src="https://cdn.amplitude.com/libs/analytics-browser-1.5.1-min.js.gz",n.onload=function(){e.amplitude.runQueuedFunctions||console.log("[Amplitude] Error: could not load SDK")};…}(window,document)}();

amplitude.init(apiKey);
</script>
```

--------------------------------

### Basic Plausible usage in Astro

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/plausible.md

Basic usage with the default Plausible-hosted script. Place the component in the `<head>` of your Astro page.

```astro
---
import { Plausible } from 'astro-analytics';
---
<html>
  <head>
    <Plausible domain="yourdomain.com" />
  </head>
</html>
```

--------------------------------

### Basic usage of SimpleAnalytics in a page layout

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/simple-analytics.md

Place the component in the shared page layout to embed the tracker. No configuration is needed.

```astro
---
import { SimpleAnalytics } from 'astro-analytics';
---
<html>
  <head>
    <SimpleAnalytics />
  </head>
  <body>…</body>
</html>
```

--------------------------------

### SimpleAnalytics component frontmatter (empty)

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/simple-analytics.md

The component's frontmatter is empty, declaring no Props interface and accepting no attributes. This is the only component in the package without configuration surface.

```astro
---
---
```

--------------------------------

### Basic MinimalAnalytics usage

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/minimal-analytics.md

Basic usage of the MinimalAnalytics component. Import the component from 'astro-analytics' and place it in the <head> with an id prop (e.g., 'UA-156492295-1'). The component emits a deferred script that sends a pageview after a fixed 10 ms delay (c.delay || 10).

```astro
---
import { MinimalAnalytics } from 'astro-analytics';
---
<html>
  <head>
    <MinimalAnalytics id="UA-156492295-1" />
  </head>
</html>
```

--------------------------------

### Metrical Rendered Markup (src/Metrical.astro:9-13)

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

The rendered component output: a loader script for the Metrical SDK and an inline configuration script with `define:vars`. The `app` prop is assigned to `window.metrical`.

```html
<script async src="https://cdn.metrical.xyz/script.js" type="text/javascript"></script>
<script define:vars={{app}}>
window.metrical = {
  app,
};
</script>
```

--------------------------------

### Custom host for Umami script path

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/umami.md

Custom host to serve the script from a non-root path on the same origin. The host value is concatenated with site to form the script src.

```astro
<Umami site="https://your-umami-app.com" dataId="4fb7fa4c-5b46-438d-94b3-3a8fb9bc2e8b" host="/static/umami.js" />
```

--------------------------------

### Track custom events and exceptions with window.ma

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/minimal-analytics.md

Tracking custom events and exceptions in page scripts using the window.ma API defined by the emitted script. The script runs after the component's deferred script. Use window.ma.trackEvent for events and window.ma.trackException for exceptions. The component performs no error handling; network failures are ignored.

```astro
<MinimalAnalytics id="UA-156492295-1" />
<script>
  // called after the component's deferred script has run
  window.ma.trackEvent('engagement', 'video', 'watched', 0.75);
  try {
    riskyOperation();
  } catch (err) {
    window.ma.trackException('Risky operation failed', true);
  }
</script>
```

--------------------------------

### Amplitude with queued tracking calls

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/amplitude.md

Non-trivial usage: include the component in the layout and then call queued tracking functions from page scripts. Calls made immediately after the component remain safe because the loader queues them until the SDK is ready.

```astro
<Amplitude apiKey="YOUR_API_KEY" />
<script>
  window.amplitude.logEvent('PageViewed', { slug: 'docs/amplitude' });
  window.amplitude.setUserId('user-42');
</script>
```

--------------------------------

### Basic Matomo usage

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/matomo.md

Basic usage of the Matomo component with a server at `https://yourdomain.com` and site ID `1`.

```astro
---
import { Matomo } from 'astro-analytics';
---
<head>
  <Matomo url="https://yourdomain.com" id="1" />
</head>
```

--------------------------------

### Import Fathom component from astro-analytics

Source: https://github.com/destiner/astro-analytics/blob/main/README.md

Import the Fathom component from the astro-analytics package. This is the first step to using the analytics components in an Astro project.

```js
import { Fathom } from 'astro-analytics';
```

--------------------------------

### Metrical Conditional Rendering per Environment

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

Conditionally renders the component based on `import.meta.env.PROD`, disabling tracking for preview or blob builds.

```astro
---
import { Metrical } from 'astro-analytics';
const track = import.meta.env.PROD; // set false for preview/blob builds
---
<head>
  {track ? <Metrical app="j5gZ1K26a" /> : null}
</head>
```

--------------------------------

### Base layout usage with slot for head

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/simple-analytics.md

Drop the component into the base layout once to apply to every page rendered through it. The component cannot be conditionally configured per environment from its own attributes; wrap it in a frontmatter expression to enable/disable it.

```astro
---
// src/layouts/Base.astro
import { SimpleAnalytics } from 'astro-analytics';
---
<html>
  <head>
    <slot name="head" />
    <SimpleAnalytics />
  </head>
  <body>
    <slot />
  </body>
</html>
```

--------------------------------

### Matomo rendered markup

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/matomo.md

Rendered markup of the Matomo component: a loader script and an inline configuration script that initializes the `_paq` queue and issues five commands.

```html
<script async src={scriptUrl}></script>
<script define:vars={{id, trackerUrl}}>
  var _paq = window._paq = window._paq || [];
  _paq.push(['disableCookies']);
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    _paq.push(['setTrackerUrl', trackerUrl]);
    _paq.push(['setSiteId', id]);
  })();
</script>
```

--------------------------------

### Basic Fathom component usage

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/fathom.md

Basic usage of the Fathom component with the default CDN script and a site ID.

```astro
---
import { Fathom } from 'astro-analytics';
---
<html>
  <head>
    <Fathom site="ABCDEF" />
  </head>
</html>
```

--------------------------------

### window.ma trackEvent and trackException definitions

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/minimal-analytics.md

The exact functions exposed on `window.ma`. `trackEvent` sends an event hit; `trackException` sends an exception hit. Both return undefined as the beacon is fired asynchronously.

```JavaScript
trackEvent:function o(r,s,t,u){return n("event",r,s,t,u)},
trackException:function q(r,s){return n("exception",null,null,null,null,r,s)}
```

--------------------------------

### Self-hosted Fathom tracker script

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/fathom.md

Self-hosted tracker script usage by passing an explicit `src` to point to your own script.js.

```astro
<Fathom site="ABCDEF" src="https://yourdomain.com/script.js" />
```

--------------------------------

### Amplitude Props

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/types.md

Defines the props interface for the Amplitude component. The apiKey field is required and is passed to amplitude.init(apiKey) once the SDK loader finishes.

```APIDOC
## Amplitude Props

### Description
Defines the props interface for the Amplitude component. The apiKey field is required and is passed to amplitude.init(apiKey) once the SDK loader finishes.

### Fields
- **apiKey** (string) - Required - Amplitude API key, passed to amplitude.init(apiKey) once the SDK loader finishes.

### TypeScript Interface
```ts
export interface Props {
  apiKey: string
}
```
```

--------------------------------

### Amplitude Props Interface

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/types.md

Defines the props for the Amplitude component. The `apiKey` field is passed to `amplitude.init(apiKey)` once the SDK loader finishes.

```ts
export interface Props {
  apiKey: string
}
```

--------------------------------

### Umami Props Interface

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/types.md

Defines the props for the Umami component. The `site` field is the app origin URL, `dataId` is the website ID, and `host` is the script path with a runtime default of '/umami.js'.

```ts
export interface Props {
  site: string;
  dataId: string;
  host: string;
}
```

--------------------------------

### Metrical Frontmatter (src/Metrical.astro:6)

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

Destructures the `app` prop from `Astro.props` in the component frontmatter.

```ts
const { app } = Astro.props;
```

--------------------------------

### index.ts re-export module

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/index.md

Exact source of index.ts, the package entry point. It imports nine Astro components from src/*.astro and exports them under their own names. No types, constants, or functions are declared here.

```typescript
import Fathom from "./src/Fathom.astro";
import GoogleAnalytics from "./src/GoogleAnalytics.astro";
import Matomo from './src/Matomo.astro';
import Metrical from "./src/Metrical.astro";
import Plausible from "./src/Plausible.astro";
import SimpleAnalytics from "./src/SimpleAnalytics.astro";
import Umami from "./src/Umami.astro";
import Amplitude from "./src/Amplitude.astro";
import MinimalAnalytics from "./src/MinimalAnalytics.astro";

export {
  Fathom,
  GoogleAnalytics,
  Metrical,
  Plausible,
  SimpleAnalytics,
  Umami,
  Amplitude,
  Matomo,
  MinimalAnalytics,
};
```

--------------------------------

### Amplitude component frontmatter

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/amplitude.md

Frontmatter of the Amplitude component that extracts the apiKey prop and calls amplitude.init(apiKey) after the SDK loader finishes loading.

```ts
const { apiKey } = Astro.props;
…
amplitude.init(apiKey);
```

--------------------------------

### Umami Props

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/types.md

Defines the props interface for the Umami component. The site and dataId fields are required, while host has a runtime default of '/umami.js'.

```APIDOC
## Umami Props

### Description
Defines the props interface for the Umami component. The site and dataId fields are required, while host has a runtime default of '/umami.js'.

### Fields
- **site** (string) - Required - Umami app origin URL; concatenated with host to form the script src (src={site}{host}).
- **dataId** (string) - Required - Umami website ID, rendered as the data-website-id attribute.
- **host** (string) - Typed required, but has a runtime default - Path (or host/path) of the Umami script on the app origin; defaults to '/umami.js'.

### TypeScript Interface
```ts
export interface Props {
  site: string;
  dataId: string;
  host: string;
}
```
```

--------------------------------

### Umami component props and destructuring with default host

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/umami.md

The Props interface declares site, dataId, and host as required strings. The frontmatter destructuring applies a runtime default of '/umami.js' for host, so omitting host works at runtime despite the type declaring it required.

```ts
export interface Props {
  site: string;
  dataId: string;
  host: string;
}
```

```ts
const { dataId, site, host = '/umami.js' } = Astro.props;
```

--------------------------------

### SimpleAnalytics rendered markup (script and noscript)

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/simple-analytics.md

The component renders a script tag loaded async defer from the Simple Analytics CDN and a noscript fallback image that reports pageviews via a tracking pixel for visitors with JavaScript disabled. The referrerpolicy attribute suppresses the referrer header on secure-to-insecure downgrades.

```html
<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
<noscript><img src="https://queue.simpleanalyticscdn.com/noscript.gif" alt="" referrerpolicy="no-referrer-when-downgrade" /></noscript>
```

--------------------------------

### Metrical Usage with Environment Variable

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

Reads the app ID from `import.meta.env.METRICAL_APP_ID` and conditionally renders the component only if the variable is set.

```astro
---
import { Metrical } from 'astro-analytics';
const appId = import.meta.env.METRICAL_APP_ID;
---
<head>
  {appId ? <Metrical app={appId} /> : null}
</head>
```

--------------------------------

### Conditional Fathom component rendering

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/fathom.md

Conditional rendering of the Fathom component based on frontmatter variables, showing how to include it only on production sites.

```astro
---
import { Fathom } from 'astro-analytics';
const fathomSite = Astro.site?.startsWith('https://production') ? 'ABCDEF' : undefined;
---
<head>
  {fathomSite ? <Fathom site={fathomSite} /> : null}
</head>
```

--------------------------------

### Plausible frontmatter destructuring with default src

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/plausible.md

Frontmatter destructuring with the runtime default for `src`. The default applies only when `src` is `undefined`; an empty string would render an empty `src` attribute.

```ts
const { domain, src = 'https://plausible.io/js/script.js' } = Astro.props;
```

--------------------------------

### window.ma.trackException

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/minimal-analytics.md

Tracks an exception by sending an exception hit to Google Analytics. Maps positional arguments to exception description and fatal flag.

```APIDOC
## Function: trackException

### Description
Sends an exception hit to Google Analytics with the provided exception description and fatal flag. The beacon is fired asynchronously.

### Signature
```js
window.ma.trackException(r, s)
```

### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `r` | `string` | Exception description (`exd`). |
| `s` | `string` | Exception fatal flag (`exf`). |

### Return
Returns the sender's return value (undefined; the beacon is fired asynchronously).
```

--------------------------------

### Matomo usage with config variable

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/matomo.md

Builds the Matomo URL from a config variable, falling back to defaults. Uses `import.meta.env.MATOMO_URL` and `import.meta.env.MATOMO_SITE_ID`.

```astro
---
import { Matomo } from 'astro-analytics';
const analyticsUrl = import.meta.env.MATOMO_URL ?? 'https://analytics.example.com';
---
<head>
  <Matomo url={analyticsUrl} id={import.meta.env.MATOMO_SITE_ID ?? '1'} />
</head>
```

--------------------------------

### Basic Metrical Usage

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

Basic usage of the `Metrical` component in an Astro page, embedding the tracker in the `<head>` with a hardcoded app ID.

```astro
---
import { Metrical } from 'astro-analytics';
---
<html>
  <head>
    <Metrical app="j5gZ1K26a" />
  </head>
</html>
```

--------------------------------

### Metrical Props Interface (src/Metrical.astro:2-4)

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/metrical.md

The exact props declaration for the `Metrical` component. It defines a required `app` string property for the Metrical application ID.

```ts
export interface Props {
  app: string;
}
```

--------------------------------

### GoogleAnalytics Props and Frontmatter

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/google-analytics.md

The component's props interface and frontmatter. The Props interface requires a single `id` string. The frontmatter extracts `id` from `Astro.props` and constructs the gtag.js loader URL by embedding the ID.

```ts
export interface Props {
  id: string;
}
```

```ts
const { id } = Astro.props;

const gtagUrl = `https://www.googletagmanager.com/gtag/js?id=${id}`;
```

--------------------------------

### Plausible rendered script tag

Source: https://github.com/destiner/astro-analytics/blob/main/_autodocs/api-reference/plausible.md

The component renders a single script tag with `defer`. No comments, `<noscript>` fallback, or inline bootstrap script are emitted.

```html
<script src={src} data-domain={domain} defer></script>
```