> ## Documentation Index
> Fetch the complete documentation index at: https://promptalpha.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Snippet

> Install the PromptAlpha tracking snippet on your website

The PromptAlpha tracking snippet is a lightweight JavaScript tag that collects AI crawler visits, AI-referred traffic, and conversion events on your website. Installation takes about two minutes.

## Installation

<Steps>
  <Step title="Find your API key">
    Log in to PromptAlpha and navigate to **Settings** > **Workspace**. Your API key is displayed under the **Tracking** section. Copy it to your clipboard.
  </Step>

  <Step title="Add the snippet to your site">
    Paste the following code before the closing `</head>` tag on every page you want to track:

    ```html theme={null}
    <script defer src="https://app.promptalpha.ai/pa.js" data-key="YOUR_API_KEY"></script>
    ```

    Replace `YOUR_API_KEY` with the API key you copied in the previous step.
  </Step>

  <Step title="Deploy your changes">
    Publish or deploy your website with the snippet in place. The script loads asynchronously using the `defer` attribute, so it will not block page rendering.
  </Step>

  <Step title="Verify data is flowing">
    Wait up to 24 hours, then check your **Agent Analytics** dashboard. You should see crawler visits and traffic data beginning to populate. If you see data appearing, the installation is complete.
  </Step>
</Steps>

<Warning>
  Make sure you replace `YOUR_API_KEY` with your actual API key. The snippet will not collect data without a valid key.
</Warning>

## How It Works

The PromptAlpha snippet is designed to be lightweight and privacy-respecting:

* **Small footprint** — The script is under 5 KB gzipped and loads asynchronously via `defer`, so it does not impact your page load performance.
* **Privacy-respecting** — The snippet does not use cookies for tracking. It respects the browser's Do Not Track (DNT) setting when enabled.
* **AI source detection** — The snippet identifies traffic from AI search engines by analyzing the `document.referrer` value. It recognizes referrers from ChatGPT, Perplexity, Claude, Gemini, Grok, and Google AI Overviews.
* **Crawler detection** — AI crawler visits are detected server-side by matching known bot user-agent strings. The JavaScript snippet is not involved in crawler detection.

<Info>
  The snippet only collects data on the domains you have authorized in your workspace settings. See [Allowed Domains](#allowed-domains) below.
</Info>

## Platform-Specific Installation

<AccordionGroup>
  <Accordion title="WordPress">
    You have two options for adding the snippet to a WordPress site:

    **Option A: Edit your theme header**

    1. Go to **Appearance** > **Theme File Editor** in your WordPress admin.
    2. Open the `header.php` file.
    3. Paste the snippet before the closing `</head>` tag.
    4. Click **Update File**.

    **Option B: Use a header/footer plugin**

    1. Install a plugin such as "Insert Headers and Footers" or "WPCode."
    2. Navigate to the plugin's settings page.
    3. Paste the snippet into the **Header** section.
    4. Save your changes.

    <Tip>
      Using a plugin is recommended because it preserves the snippet when you update or change your WordPress theme.
    </Tip>
  </Accordion>

  <Accordion title="Shopify">
    1. In your Shopify admin, go to **Online Store** > **Themes**.
    2. Click **Actions** > **Edit code** on your active theme.
    3. Open the `theme.liquid` file under **Layout**.
    4. Paste the snippet before the closing `</head>` tag.
    5. Click **Save**.

    ```html theme={null}
    <!-- PromptAlpha Tracking Snippet -->
    <script defer src="https://app.promptalpha.ai/pa.js" data-key="YOUR_API_KEY"></script>
    </head>
    ```
  </Accordion>

  <Accordion title="Next.js">
    Add the snippet to your root layout file so it loads on every page.

    **App Router (`app/layout.tsx`)**

    ```tsx theme={null}
    import type { Metadata } from 'next';

    export const metadata: Metadata = {
      title: 'My App',
    };

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <head>
            <script
              defer
              src="https://app.promptalpha.ai/pa.js"
              data-key="YOUR_API_KEY"
            />
          </head>
          <body>{children}</body>
        </html>
      );
    }
    ```

    **Pages Router (`pages/_document.tsx`)**

    ```tsx theme={null}
    import { Html, Head, Main, NextScript } from 'next/document';

    export default function Document() {
      return (
        <Html>
          <Head>
            <script
              defer
              src="https://app.promptalpha.ai/pa.js"
              data-key="YOUR_API_KEY"
            />
          </Head>
          <body>
            <Main />
            <NextScript />
          </body>
        </Html>
      );
    }
    ```
  </Accordion>

  <Accordion title="Static HTML">
    Open your HTML file and paste the snippet directly inside the `<head>` section:

    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>My Page</title>

      <!-- PromptAlpha Tracking Snippet -->
      <script defer src="https://app.promptalpha.ai/pa.js" data-key="YOUR_API_KEY"></script>
    </head>
    <body>
      <!-- Your page content -->
    </body>
    </html>
    ```

    If your site has multiple HTML files, add the snippet to every page you want to track. If you use a templating system or server-side includes, add it to the shared header template.
  </Accordion>
</AccordionGroup>

## Allowed Domains

PromptAlpha only collects data from domains you have explicitly authorized. To configure your allowed domains:

1. Go to **Settings** > **Workspace** > **Allowed Domains**.
2. Add each domain where you have installed the tracking snippet (e.g., `example.com`, `www.example.com`).
3. Click **Save**.

<Note>
  Subdomains are treated separately. If your site runs on both `example.com` and `www.example.com`, add both. Requests from unauthorized domains are silently ignored.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No data appearing after 24 hours">
    * Confirm the snippet is present in your page's `<head>` section by viewing the page source in your browser.
    * Verify that `YOUR_API_KEY` has been replaced with your actual API key from **Settings** > **Workspace**.
    * Check that your domain is listed under **Allowed Domains** in your workspace settings.
    * Open your browser's developer console (**F12** > **Console**) and look for any errors related to `pa.js`.
  </Accordion>

  <Accordion title="Snippet is present but pa.js fails to load">
    * Check that your Content Security Policy (CSP) allows scripts from `app.promptalpha.ai`. You may need to add `https://app.promptalpha.ai` to your `script-src` directive.
    * Confirm that no ad blocker or browser extension is blocking the request.
    * Verify network connectivity to `https://app.promptalpha.ai/pa.js` by opening the URL directly in your browser.
  </Accordion>

  <Accordion title="AI traffic data is missing but crawler data shows">
    AI traffic detection depends on the JavaScript snippet running in the user's browser. If crawler data appears but AI-referred traffic does not:

    * Confirm the snippet is loading on the correct pages.
    * Check that the referrer is not being stripped by a `Referrer-Policy` header set to `no-referrer`. Use `no-referrer-when-downgrade` or `strict-origin-when-cross-origin` instead.
    * Allow up to 48 hours for traffic data to fully populate after initial installation.
  </Accordion>

  <Accordion title="Duplicate page views or inflated numbers">
    * Ensure the snippet is only included once per page. Check for duplicate inclusions in both your HTML template and any tag managers.
    * If you use a single-page application (SPA) framework, the snippet handles route changes automatically. You do not need to re-initialize it on navigation.
  </Accordion>
</AccordionGroup>