> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Astro Integration
> Install AgentRef in a shared Astro layout so affiliate tracking works across your marketing site or app shell.
Astro is a good fit for AgentRef because the tracking script can live in one shared layout and still cover static pages, islands, and Stripe embeds.
## Before you start
* Set the program website in AgentRef to the same root domain your Astro site uses.
* Copy the exact script snippet from `Settings -> Integration`.
* If checkout starts on a sibling subdomain, install the script there too.
## Recommended installation
Put the script in the shared layout you use across public pages.
```astro theme={null}
---
export interface Props {
title: string;
}
const { title } = Astro.props;
---
{title}
```
You do not need a separate Framer-style helper script in Astro. AgentRef already watches the DOM for late-rendered Stripe links, Buy Buttons, and Pricing Tables.
## Checkout compatibility in Astro
| Checkout pattern | Recommendation |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Stripe Payment Links, Buy Buttons, or Pricing Tables embedded in Astro pages | Supported directly. |
| Custom server-created Stripe Checkout Session | Supported, but you must pass AgentRef metadata into Stripe on the server. |
| External checkout on another root domain | Not automatic. Keep checkout on the same root or build an intentional server-side handoff. |
## Multi-domain and consent notes
* Shared subdomains on one root can work well if AgentRef is installed everywhere the journey can begin.
* If you use a consent banner script, call `window.AgentRef.setConsent('granted')` after opt-in.
* If you run a strict CSP, allow `https://www.agentref.co` for `script-src` and `connect-src`.
## Verify the installation
Make sure the layout change is on the deployed site, not just in local preview.
Use a real affiliate link and confirm the AgentRef cookies appear.
Add `?agentref_debug=1` and inspect the console output.
Use the tracking health panel or `verify_tracking`.
## Troubleshooting
* The script exists in the layout but cookies never appear: check whether the program website in AgentRef matches the live domain.
* Clicks arrive but Stripe conversions do not: your checkout backend still needs the [Stripe guide](/docs/integration/stripe).
* The script works locally but not in production: verify the deployed layout actually includes the script and that no CSP blocks it.
## Related docs
Metadata bridge for custom Stripe sessions.
Full tracking-script reference.
Inspect hosted Stripe instrumentation and warnings.