> ## 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.

# Nuxt Integration

> Install AgentRef in Nuxt with a global script definition that covers every route.

Nuxt is a strong fit for AgentRef because you can register the tracking script globally and let it stay active across route changes.

## Before you start

* Set the program website in AgentRef to the same root domain your Nuxt app uses.
* Copy the exact script snippet from `Settings -> Integration`.
* If checkout starts on another subdomain, install AgentRef there too.

## Recommended installation

<Tabs>
  <Tab title="nuxt.config.ts">
    The cleanest Nuxt installation is a global head script in `nuxt.config.ts`.

    ```ts theme={null}
    export default defineNuxtConfig({
      app: {
        head: {
          script: [
            {
              src: 'https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID',
              defer: true,
            },
          ],
        },
      },
    });
    ```
  </Tab>

  <Tab title="useHead fallback">
    If you need to scope installation through a shared layout, use `useHead()` in `app.vue` or a global layout.

    ```vue theme={null}
    <script setup lang="ts">
    useHead({
      script: [
        {
          src: 'https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID',
          defer: true,
        },
      ],
    });
    </script>
    ```
  </Tab>
</Tabs>

## Checkout compatibility in Nuxt

| Checkout pattern                                       | Recommendation                                                                               |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Hosted Stripe surfaces on Nuxt pages                   | Supported directly.                                                                          |
| Nuxt server routes or backend create Checkout Sessions | Supported, but you must bridge `window.AgentRef.getCheckoutMetadata()` into Stripe metadata. |
| Cross-root-domain checkout                             | Not automatic. First-party cookies stay on one root domain.                                  |

## Nuxt-specific notes

* Install once globally instead of per page.
* AgentRef works well with route changes because the script remains loaded after hydration.
* If you enable consent mode, call `window.AgentRef.setConsent('granted')` from your banner integration after opt-in.

## Verify the installation

1. Visit the Nuxt app through a live affiliate link.
2. Confirm `agentref_cid` and `agentref_pid` in browser cookies.
3. Add `?agentref_debug=1` and inspect the console.
4. Complete one supported Stripe test checkout and confirm AgentRef records the conversion.

## Troubleshooting

* The script only loads on one route: move it into `nuxt.config.ts` or a shared app-level layout.
* Clicks appear but no conversion does: your custom session path still needs the [Stripe guide](/docs/integration/stripe).
* Consent is required but cookies never appear: your banner integration probably never calls `window.AgentRef.setConsent('granted')`.

## Related docs

<CardGroup cols={3}>
  <Card title="Stripe Checkout" icon="credit-card" href="/docs/integration/stripe">
    Required for custom session creation on the server.
  </Card>

  <Card title="Consent and GDPR" icon="shield" href="/docs/tracking/consent-gdpr">
    Gate tracking until the user accepts.
  </Card>

  <Card title="Debug Mode" icon="bug" href="/docs/tracking/debug-mode">
    Inspect runtime state and warnings.
  </Card>
</CardGroup>