Set Up Analytics

Open Settings → Analytics in the project you want to track. If analytics is not enabled, enter the production hostname and select Enable Analytics. Use a hostname such as yourdomain.com; do not include https://, a path, or a port. Enabling analytics creates the project’s Tracking ID. The Domain is required both when enabling analytics and afterward: the collector rejects every event until a valid domain is saved.

Only 1. Embed Script is required. 2. Ad-block Bypass and 3. Bot / AI Crawler Tracking are independent, optional additions.

1. Embed Script (required)

Add the following tag to the <head> shared by every page. Replace YOUR_TRACKING_ID with the Tracking ID shown in Settings → Analytics and replace yourdomain.com with the saved domain.

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

The direct script posts to Aiola’s collector and preserves accurate visitor IP exclusions, country/city data, and map data.

2. Ad-block Bypass (optional)

For a Next.js site, add these rewrites to next.config.ts:

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

Then use this tag instead of the tag from step 1:

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

Never install both tags. The first-party proxy can improve collection when ad blockers target the CDN or collector, but the collector sees the proxy rather than the visitor. Accurate IP exclusions, country/city attribution, and map data are therefore lost. Forwarded geo headers do not restore that accuracy.

3. Bot / AI Crawler Tracking (optional — pick ONE)

AI crawlers never execute JavaScript, so the browser tag cannot see them. Choose exactly one server-side or edge implementation for the stack that receives every page request. These calls post directly to https://aiola.app/api/bot-crawl-ingest; ad blockers do not apply.

Next.js / Vercel
Cloudflare Pages Function
Express / Node.js

Add both sections below. Middleware records normal crawler requests and forwards the requested path; app/not-found.tsx records crawler 404s because middleware runs before the response status is known.

// 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()
})

The snippets test the User-Agent before sending anything, skip static assets, keep robots.txt, llms.txt, and sitemap requests, send country in the JSON body when the platform provides it, and report status codes where the stack can observe them.

Use Add to App

The Add to App button in the analytics settings header opens an AI thread with the current Tracking ID, Domain, and endpoints. Its prompt first inspects the project to detect the real framework and runtime, then:

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

The Stripe section has its own Add to App action. It searches for the production Checkout Session creation path, detects the server framework, and adds the two Aiola cookie values without duplicating existing metadata.

Tracker attributes

Add these attributes to the single installed script tag when needed:

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" overrides the default https://aiola.app/api/collect-analytics endpoint. The ad-block bypass tag uses this.
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.

For example, opt into query-string pageviews by adding the attribute to the standard tag:

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

Custom events, identity, and manual revenue

After the script loads, use the global API:

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' })

The signatures are window.aiola.track(name, props) and window.aiola.identify(id, props). Event names are limited to 100 characters, and oversized event properties are discarded if their serialized data exceeds 6,000 characters. You can also track a click declaratively:

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

The tracker creates aiola_visitor_id with a 365-day cookie expiry and aiola_session_id with a sliding 30-minute expiry. Both use SameSite=Lax, path=/, and Secure on HTTPS. The visitor ID also uses local storage as a fallback.

Exclude unwanted traffic

Configure exclusions in Settings → Analytics:

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.

The settings page shows Desktop public IP: … — click to exclude. This is the desktop app’s current public IP; a visitor on another network or IP family can still appear under a different address. IP exclusions match the address seen by the direct Aiola worker request, so they are not reliable through the optional proxy.

Connect search keywords

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

The dashboard can then display search queries and pages, and the Indexing panel can report Google indexing reasons and Bing crawl issues. Search Console data has an approximately 48-hour delay.

Connect Stripe revenue

Connect Stripe from Settings → Integrations. Once the analytics setting shows Connected, pass the tracker cookies as Checkout Session metadata so the webhook can attribute revenue to the correct visitor and marketing channel.

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

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

  const session = await stripe.checkout.sessions.create({
    line_items: [...],
    mode: 'payment',
    metadata: {
      aiola_visitor_id: cookieStore.get('aiola_visitor_id')?.value,
      aiola_session_id: cookieStore.get('aiola_session_id')?.value,
    },
  });
}

// checkout.js
const session = await stripe.checkout.sessions.create({
  line_items: [...],
  mode: 'payment',
  metadata: {
    aiola_visitor_id: req.cookies.aiola_visitor_id,
    aiola_session_id: req.cookies.aiola_session_id,
  },
});

// checkout.py
session = stripe.checkout.Session.create(
    line_items=[...],
    mode='payment',
    metadata={
        'aiola_visitor_id': request.cookies.get('aiola_visitor_id'),
        'aiola_session_id': request.cookies.get('aiola_session_id'),
    },
)

Choose Display Currency in Settings → Analytics to control how the dashboard converts and presents revenue totals.

Security and data management

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

Aiola stores timestamps in UTC and displays them in the workspace timezone configured in Central settings. Imported local timestamps must be converted to UTC.

Verify collection

After deployment:

Visit the production domain and navigate between a few pages.
Open the project’s Analytics dashboard and verify visitors, sessions, and Views.
Open the realtime globe to confirm the active visitor and event stream.
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.
If Stripe or search providers are connected, verify the selected property/site and the Checkout Session metadata before expecting attribution.
Use the project dashboard’s Analyze with AI action to open a reporting thread for a preset or custom date range.

Retention is not a dashboard section. Request it through the Aiola MCP by calling get_analytics with the analytics_retention pipe and the workspace timezone.

Monthly plan usage is based on billable events: pageviews and custom events, excluding _leave, _identify, and _scroll. If the monthly limit is exceeded, the dashboard is locked until upgrade or reset, but collection continues and no data is lost.

Getting Started

Core Features

Setup Guides

Set Up Analytics

Use Add to App

Tracker attributes

Custom events, identity, and manual revenue

Exclude unwanted traffic

Connect search keywords

Connect Stripe revenue

Security and data management

Verify collection

​Use Add to App

​Tracker attributes

​Custom events, identity, and manual revenue

​Exclude unwanted traffic

​Connect search keywords

​Connect Stripe revenue

​Security and data management

​Verify collection

Use Add to App

Tracker attributes

Custom events, identity, and manual revenue

Exclude unwanted traffic

Connect search keywords

Connect Stripe revenue

Security and data management

Verify collection