Set Up Analytics

​

Create/enable analytics site

​

Required tracking ID and domain

​

Canonical browser tag

<script defer
  src="https://cdn.aiola.app/analytics.js"
  data-site-id="YOUR_TRACKING_ID"
  data-domain="yourdomain.com"></script>

// next.config.ts
async rewrites() {
  return [
    {
      source: "/js/analytics.js",
      destination: "https://cdn.aiola.app/analytics.js",
    },
  ];
}

<script defer
  src="/js/analytics.js"
  data-site-id="YOUR_TRACKING_ID"
  data-domain="yourdomain.com"></script>

// middleware.ts (Next.js) — records AI/LLM crawler hits server-side
import { NextResponse } from "next/server"
import type { NextFetchEvent, NextRequest } from "next/server"

const BOT_RE = /GPTBot|ChatGPT-User|OAI-SearchBot|OAI-AdsBot|Claude-User|Claude-SearchBot|ClaudeBot|anthropic-ai|Perplexity|MistralAI-|xAI-|Grok|Google-Extended|Google-NotebookLM|Google-Read-Aloud|Google-Agent|GoogleAgent|Google-InspectionTool|Google-CloudVertexBot|GoogleOther|Googlebot|Applebot|Copilot|bingbot|msnbot|Amzn-|Amazonbot|TikTokSpider|Bytespider|Doubaobot|Meta-ExternalFetcher|meta-externalfetcher|meta-webindexer|meta-externalads|facebookexternalhit|Meta-ExternalAgent|FacebookBot|meta-externalagent|CCBot|cohere-ai|cohere-training-data-crawler|DuckAssistBot|DuckDuckBot|YouBot|Kimi|Qwen|Qwantbot|TongyiBot|AliyunBot|Baiduspider|ERNIEBot|YiyanBot|ChatGLM-Spider|DeepSeekBot|AI2Bot|Diffbot|Timpibot|ImagesiftBot|LinerBot|QualifiedBot|YandexBot|SeznamBot|PetalBot/i
// Asset extensions we skip. robots.txt / llms.txt / sitemap.xml are intentionally
// NOT here (no .txt / .xml) so bot hits to those discovery files are tracked too.
const ASSET_RE = /\.(png|jpe?g|gif|webp|avif|svg|ico|css|js|mjs|map|woff2?|ttf|otf|eot|json|webmanifest|mp4|webm|pdf)$/i

export function middleware(req: NextRequest, ev: NextFetchEvent) {
  const ua = req.headers.get("user-agent") || ""
  if (BOT_RE.test(ua) && !ASSET_RE.test(req.nextUrl.pathname)) {
    // Country belongs in the JSON body. Do not forward this as a geo header.
    const country = req.headers.get("x-vercel-ip-country") || req.headers.get("cf-ipcountry")
    ev.waitUntil(fetch("https://aiola.app/api/bot-crawl-ingest", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ tracking_id: "YOUR_TRACKING_ID", url_path: req.nextUrl.pathname, url_host: req.nextUrl.hostname, ua, ...(country ? { country } : {}) }),
      keepalive: true,
    }).catch(() => {}))
  }
  // Forward the path so not-found.tsx (which Next doesn't hand a pathname) can
  // report which URL 404'd. Harmless on normal requests.
  const headers = new Headers(req.headers)
  headers.set("x-aiola-path", req.nextUrl.pathname)
  return NextResponse.next({ request: { headers } })
}

export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] }


// app/not-found.tsx — logs 404s crawlers hit (send status:404; middleware fires
// pre-response so it can't know the status). Same BOT_RE as middleware.ts.
import { headers } from "next/headers"
import { after } from "next/server"

const BOT_RE = /GPTBot|ChatGPT-User|OAI-SearchBot|OAI-AdsBot|Claude-User|Claude-SearchBot|ClaudeBot|anthropic-ai|Perplexity|MistralAI-|xAI-|Grok|Google-Extended|Google-NotebookLM|Google-Read-Aloud|Google-Agent|GoogleAgent|Google-InspectionTool|Google-CloudVertexBot|GoogleOther|Googlebot|Applebot|Copilot|bingbot|msnbot|Amzn-|Amazonbot|TikTokSpider|Bytespider|Doubaobot|Meta-ExternalFetcher|meta-externalfetcher|meta-webindexer|meta-externalads|facebookexternalhit|Meta-ExternalAgent|FacebookBot|meta-externalagent|CCBot|cohere-ai|cohere-training-data-crawler|DuckAssistBot|DuckDuckBot|YouBot|Kimi|Qwen|Qwantbot|TongyiBot|AliyunBot|Baiduspider|ERNIEBot|YiyanBot|ChatGLM-Spider|DeepSeekBot|AI2Bot|Diffbot|Timpibot|ImagesiftBot|LinerBot|QualifiedBot|YandexBot|SeznamBot|PetalBot/i

export default async function NotFound() {
  const h = await headers()
  const ua = h.get("user-agent") || ""
  if (BOT_RE.test(ua)) {
    // Country belongs in the JSON body. Do not forward this as a geo header.
    const country = h.get("x-vercel-ip-country") || h.get("cf-ipcountry")
    after(fetch("https://aiola.app/api/bot-crawl-ingest", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ tracking_id: "YOUR_TRACKING_ID", url_path: h.get("x-aiola-path") || "", url_host: (h.get("host") || "").split(":")[0], ua, ...(country ? { country } : {}), status: 404 }),
    }).catch(() => {}))
  }
  return <h1>404 — Page not found</h1>
}

// functions/[[path]].ts — Cloudflare Pages
const BOT_RE = /GPTBot|ChatGPT-User|OAI-SearchBot|OAI-AdsBot|Claude-User|Claude-SearchBot|ClaudeBot|anthropic-ai|Perplexity|MistralAI-|xAI-|Grok|Google-Extended|Google-NotebookLM|Google-Read-Aloud|Google-Agent|GoogleAgent|Google-InspectionTool|Google-CloudVertexBot|GoogleOther|Googlebot|Applebot|Copilot|bingbot|msnbot|Amzn-|Amazonbot|TikTokSpider|Bytespider|Doubaobot|Meta-ExternalFetcher|meta-externalfetcher|meta-webindexer|meta-externalads|facebookexternalhit|Meta-ExternalAgent|FacebookBot|meta-externalagent|CCBot|cohere-ai|cohere-training-data-crawler|DuckAssistBot|DuckDuckBot|YouBot|Kimi|Qwen|Qwantbot|TongyiBot|AliyunBot|Baiduspider|ERNIEBot|YiyanBot|ChatGLM-Spider|DeepSeekBot|AI2Bot|Diffbot|Timpibot|ImagesiftBot|LinerBot|QualifiedBot|YandexBot|SeznamBot|PetalBot/i
const ASSET_RE = /\.(png|jpe?g|gif|webp|avif|svg|ico|css|js|mjs|map|woff2?|ttf|otf|eot|json|webmanifest|mp4|webm|pdf)$/i

export async function onRequest(context) {
  const response = await context.next()
  const url = new URL(context.request.url)
  const ua = context.request.headers.get("user-agent") || ""
  if (BOT_RE.test(ua) && !ASSET_RE.test(url.pathname)) {
    const country = context.request.cf?.country
    context.waitUntil(fetch("https://aiola.app/api/bot-crawl-ingest", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ tracking_id: "YOUR_TRACKING_ID", url_path: url.pathname, url_host: url.hostname, ua, ...(country ? { country } : {}), status: response.status }),
    }).catch(() => {}))
  }
  return response
}

// Register before routes. Node 18+ provides global fetch.
const BOT_RE = /GPTBot|ChatGPT-User|OAI-SearchBot|OAI-AdsBot|Claude-User|Claude-SearchBot|ClaudeBot|anthropic-ai|Perplexity|MistralAI-|xAI-|Grok|Google-Extended|Google-NotebookLM|Google-Read-Aloud|Google-Agent|GoogleAgent|Google-InspectionTool|Google-CloudVertexBot|GoogleOther|Googlebot|Applebot|Copilot|bingbot|msnbot|Amzn-|Amazonbot|TikTokSpider|Bytespider|Doubaobot|Meta-ExternalFetcher|meta-externalfetcher|meta-webindexer|meta-externalads|facebookexternalhit|Meta-ExternalAgent|FacebookBot|meta-externalagent|CCBot|cohere-ai|cohere-training-data-crawler|DuckAssistBot|DuckDuckBot|YouBot|Kimi|Qwen|Qwantbot|TongyiBot|AliyunBot|Baiduspider|ERNIEBot|YiyanBot|ChatGLM-Spider|DeepSeekBot|AI2Bot|Diffbot|Timpibot|ImagesiftBot|LinerBot|QualifiedBot|YandexBot|SeznamBot|PetalBot/i
const ASSET_RE = /\.(png|jpe?g|gif|webp|avif|svg|ico|css|js|mjs|map|woff2?|ttf|otf|eot|json|webmanifest|mp4|webm|pdf)$/i

app.use((req, res, next) => {
  const ua = req.get("user-agent") || ""
  const path = req.path || "/"
  if (BOT_RE.test(ua) && !ASSET_RE.test(path)) {
    const country = req.get("x-vercel-ip-country") || req.get("cf-ipcountry")
    res.once("finish", () => {
      void fetch("https://aiola.app/api/bot-crawl-ingest", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ tracking_id: "YOUR_TRACKING_ID", url_path: path, url_host: req.hostname, ua, ...(country ? { country } : {}), status: res.statusCode }),
      }).catch(() => {})
    })
  }
  next()
})

​

Setup Health implications of proxying

​

Bot tracking architecture

​

Current supported bot UAs and classification

​

Bot endpoint payload/validation/limits

​

Optional script-only ad-block bypass

​

Add to App

• installs the browser tag at the correct global layout, template, or entry point
• avoids duplicating an existing Aiola integration
• can add the optional same-domain proxy using the stack’s native rewrite mechanism
• can add optional server-side or edge bot tracking at the request interception point, including 404 handling where supported
• adds Stripe cookie metadata when Stripe is connected, or shows the manual revenue option otherwise

​

Complete tracker-attribute reference

• data-site-id="YOUR_TRACKING_ID" selects the project and is required.
• data-domain="yourdomain.com" allows that exact hostname and its subdomains. If the current hostname is not allowed, the tracker exits without sending.
• data-domains="one.example.com,two.example.com" adds a comma-separated list of allowed hostnames; each entry also allows its subdomains.
• data-host-url="/api/collect" is a legacy fallback collector URL, used only when the direct request to https://aiola.app/api/collect is blocked. Leave it unset.
• data-track-query="true" counts a query-string-only URL change as a new pageview. It is off by default; url_query is still sent with events either way.
• data-track-hash="true" includes the hash in the tracked path and counts hash-router navigation.
• data-do-not-track="true" makes the tracker honor the browser’s Do Not Track setting.
• data-auto-track="false" disables automatic page tracking.
• data-track-scroll="true" is parsed but no collection pipe reads scroll data; treat it as unsupported/diagnostic.

<script defer
  src="https://cdn.aiola.app/analytics.js"
  data-site-id="YOUR_TRACKING_ID"
  data-domain="yourdomain.com"
  data-track-query="true"></script>

​

Browser payload and public APIs

​

Browser/collector limits

​

Custom events and identity

window.aiola.track('signup_click', { plan: 'pro' })
window.aiola.identify('user_123', { email: 'user@example.com' })
window.aiola.track('__revenue', { revenue: 29.99, plan: 'pro' })

<button
  data-aiola-event="signup_click"
  data-aiola-event-plan="pro">
  Start trial
</button>

​

Exclude unwanted traffic

• IP addresses: one IPv4 or IPv6 address, or an IPv4 CIDR range such as 203.0.113.0/24.
• Paths: an exact path such as /admin, or a prefix ending in *, such as /admin/*. Query strings are not used for path matching.
• Countries: visitors whose signed worker geo resolves to the selected two-letter country code.
• Hostnames: an exact hostname and all its subdomains, such as preview.yourdomain.com.

​

Search-provider mapping

1. Open Settings → Integrations and connect Google Search Console and/or Bing Webmaster Tools.
2. Return to Settings → Analytics → Search Keywords.
3. Select the Google Search Console property and Bing Webmaster site for this project. If multiple connected accounts exist, the selector groups properties by account.

​

Stripe/manual revenue

npm install stripe

// app/api/create-checkout/route.js
import { cookies } from 'next/headers';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export async function POST() {
  const cookieStore = await cookies();

  const session = await stripe.checkout.sessions.create({
    line_items: [{ price: process.env.STRIPE_PRICE_ID, quantity: 1 }],
    mode: 'payment',
    success_url: `${process.env.APP_URL}/success`,
    cancel_url: `${process.env.APP_URL}/checkout`,
    metadata: {
      aiola_visitor_id: cookieStore.get('aiola_visitor_id')?.value || '',
      aiola_session_id: cookieStore.get('aiola_session_id')?.value || '',
    },
  });
  return Response.json({ url: session.url });
}

npm install express cookie-parser stripe

// server.js
import cookieParser from 'cookie-parser';
import express from 'express';
import Stripe from 'stripe';

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
app.use(cookieParser());

app.post('/create-checkout', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [{ price: process.env.STRIPE_PRICE_ID, quantity: 1 }],
    mode: 'payment',
    success_url: `${process.env.APP_URL}/success`,
    cancel_url: `${process.env.APP_URL}/checkout`,
    metadata: {
      aiola_visitor_id: req.cookies.aiola_visitor_id || '',
      aiola_session_id: req.cookies.aiola_session_id || '',
    },
  });
  res.json({ url: session.url });
});

app.listen(3000);

pip install Flask stripe

# app.py
import os

import stripe
from flask import Flask, jsonify, request

app = Flask(__name__)
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

@app.post("/create-checkout")
def create_checkout():
    session = stripe.checkout.Session.create(
        line_items=[{"price": os.environ["STRIPE_PRICE_ID"], "quantity": 1}],
        mode="payment",
        success_url=f'{os.environ["APP_URL"]}/success',
        cancel_url=f'{os.environ["APP_URL"]}/checkout',
        metadata={
            "aiola_visitor_id": request.cookies.get("aiola_visitor_id", ""),
            "aiola_session_id": request.cookies.get("aiola_session_id", ""),
        },
    )
    return jsonify(url=session.url)

​

Exclusions and Attack Mode

​

Import/export/clear/disable limits

• Attack Mode: enables stricter bot and headless-browser detection, per-IP limits, and per-site limits. Use it when analytics is receiving spam or the site is under attack.
• Export: downloads CSV for this month, last month, the current or previous year, or a custom month range. An export is truncated at 100,000 rows; narrow the range if that happens.
• Import: accepts at most 10 MiB, 100,000 source rows, and 500,000 expanded events.
• Import: Fix CSV with AI converts a CSV from another provider into Aiola’s UTC schema and saves the fixed file to Downloads for re-upload. Direct Import (auto-detect) imports CSV or TSV directly.
• Clear Data: permanently deletes all pageviews, events, sessions, charts, breakdowns, and historical analytics for the project. Export first if the data may be needed.
• Disable Analytics: pauses collection while preserving existing data. Re-enable it later to resume collection.

​

Verification

1. Visit the production domain and navigate between a few pages.
2. Open the project’s Analytics dashboard and verify visitors, sessions, and Views.
3. Open the realtime globe to confirm the active visitor and event stream.
4. If crawler tracking is installed, test the server route with a matching crawler User-Agent and verify the AI view. The browser tag alone cannot perform this test.
5. If Stripe or search providers are connected, verify the selected property/site and the Checkout Session metadata before expecting attribution.
6. Use the project dashboard’s Analyze with AI action to open a reporting thread for a preset or custom date range.

​

Confirmed quota behavior only