Skip to main content
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

1

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

Add the snippet to your site

Paste the following code before the closing </head> tag on every page you want to track:
<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.
3

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

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.
Make sure you replace YOUR_API_KEY with your actual API key. The snippet will not collect data without a valid key.

​
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.
The snippet only collects data on the domains you have authorized in your workspace settings. See Allowed Domains below.

​
Platform-Specific Installation

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.
Using a plugin is recommended because it preserves the snippet when you update or change your WordPress theme.
  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.
<!-- PromptAlpha Tracking Snippet -->
<script defer src="https://app.promptalpha.ai/pa.js" data-key="YOUR_API_KEY"></script>
</head>
Add the snippet to your root layout file so it loads on every page.App Router (app/layout.tsx)
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)
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>
  );
}
Open your HTML file and paste the snippet directly inside the <head> section:
<!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.

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

​
Troubleshooting

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