Install through GitHub or the snippet

Both routes put a small piece of code on your server. On every request it checks the user agent. For a person it does nothing. For an AI bot it sends one short message to Knownwise in the background, without waiting for an answer, so your page is never slowed down or changed. It adds no dependency.

Both live in Settings → Integrations → AI bot visits for your brand → AI bot tracking. The card lists each Tracking routes row with its status: Waiting for first visit, Installing, Receiving since a date, Problem: and a reason, or Turned off.

If your site is static, with no server of its own, neither route can run. That covers a Next.js site built with output: "export" and an Astro site without server output. Connect Cloudflare instead.

The GitHub route

This route is for a Next.js app in a GitHub repository. Knownwise offers it only when your last site check found Next.js or could not tell; a site it recognised as Astro, WordPress, Webflow or Shopify is offered the snippet or Cloudflare instead. It works on every paid plan, Starter included. The pull request is not a fix: it doesn't need a plan with fixes, and it never uses one of the month's fixes.

1. Connect GitHub and link the brand's repository. See GitHub.
2. On the brand's Opportunities page, the finding AI bot visits are not tracked yet appears under Fix on your site, in the AI bot tracking area.
3. Open that finding and choose Prepare pull request. The dialog lists this finding alone, because tracking is its own pull request, and its cost line reads Doesn't use a fix job: AI bot tracking is included in every paid plan. See Opportunities.
4. Review the pull request on GitHub, merge it and deploy.
5. When Knownwise sees the merge, the GitHub row shows Installing and Knownwise sends a test visit to your home page. When it arrives, the row reads Receiving since and a date.

What the pull request contains

One file, chosen from your repository:

• Next.js 16 and later get proxy.ts. Next.js 12.2 to 15 get middleware.ts.
• The file goes in src/ when your app lives there.
• A project without tsconfig.json gets the JavaScript version.

If you already have a proxy or middleware file, the pull request wraps it. Your file is renamed, unchanged, to knownwise-proxy-original or knownwise-middleware-original (same extension). A new file at the old path runs the tracking first, then your code, and returns your response. Tracking runs on every page, because AI bots mostly read the pages a login proxy never covers. Your code still runs only on the paths its own matcher covered, so it behaves exactly as before. Any other config keys are copied over unchanged. The pull request says which paths your code still runs on.

The pull request never adds a dependency and never edits package.json, a lockfile or an .env file.

Knownwise opens no pull request, and says why, when the repository is not a Next.js app, the Next.js version is older than 12.2 or can't be read, the site is a static export, the repository holds more than one Next.js app, or both a proxy and a middleware file exist. Use the snippet or Cloudflare then.

When the pull request does not happen, or is closed without merging, the GitHub pull request row shows Problem: and why, and Knownwise suggests the next route instead of waiting:

• the repository isn't a Next.js app, so the pull request can't add tracking. Use the snippet, or connect Cloudflare if it's in front of the site. Knownwise stops offering the pull request for this brand.
• the pull request was closed without merging. Add tracking again from Opportunities, or use the snippet.
• the pull request couldn't be made. Opportunities says why. You can try again there, or use the snippet.

Private and public repositories

The site key decides which Knownwise brand a visit belongs to. It can only send visits. It cannot read any of your data.

• Private repository. The key is written into the file. There is nothing else to set.
• Public repository (or one whose visibility Knownwise can't read). The key is not in the code. The file reads it from the KNOWNWISE_SITE_KEY environment variable. Until that variable is set, the file does nothing. The pull request description says which: "This repository is public", or "We couldn't confirm this repository is private".

For a public repository, the pull request description has the steps, and the GitHub pull request row in the card says This repository is public, so the tracking code reads the site key from KNOWNWISE_SITE_KEY. To get the key:

1. In Knownwise, open Settings → Integrations → AI bot tracking and, on the GitHub pull request row, choose Show a new key for this.
2. Knownwise keeps only a fingerprint of the key, so showing one means making a new one. Confirm with Make and show the key. Any key set before stops working at once.
3. Copy your site key now. Knownwise shows it once.
4. Add it to your hosting provider's environment variables as KNOWNWISE_SITE_KEY, redeploy, then choose Test it on the same row.

Visits from this setup are counted on the GitHub pull request row.

If a private repository becomes public, its key is public too. On the GitHub pull request row, choose Retire the key in the code, then Retire it and show a new key. The key in your code stops working at once, and the site stops reporting until you finish:

1. Copy your site key now. Knownwise shows it once.
2. In the Knownwise file, change the KNOWNWISE_SITE_KEY line to the one the card shows, which reads the KNOWNWISE_SITE_KEY environment variable.
3. Add the key to your hosting provider's environment variables as KNOWNWISE_SITE_KEY, redeploy, then choose Test it.

From then on the row works like a public repository's.

On Vercel

With this file in place, every page request runs the proxy or middleware. On Vercel that counts as a function or middleware invocation on your Vercel plan. When your last site check found Vercel, the pull request description says so too.

Remove it

Delete the Knownwise file and redeploy. If the pull request wrapped your own file, delete the new file and rename knownwise-…-original back to its old name.

The snippet route

Use the snippet for any site with a server: Next.js, Astro with server output, Express or plain Node, or anything that can send an HTTP request.

1. In the AI bot tracking card, under Set up with a snippet, choose Create a site key.
2. Copy your site key now. Knownwise shows it once. Afterwards the card shows only its first characters.
3. Pick your Framework, and for Next.js and Astro the Language. On the Astro tab, also pick the Astro output: Server or Static.
4. Pick Where your site runs (see below).
5. Choose Copy code, add the file to your site and deploy.
6. Choose Test it.

While the key is on screen, the code has the key in it. Once you leave the page, the code reads the key from KNOWNWISE_SITE_KEY instead, and you set that variable where your site runs.

Framework tabs

Tab	File	Notes
Next.js 16+	proxy.ts	In src/ if your app is there.
Next.js 12.2–15	middleware.ts	In src/ if your app is there.
Astro	src/middleware.ts	Server output only. Static shows A static Astro site has no server to run this. Connect Cloudflare instead.
Express	knownwise-ai-bots.js	Needs Node 18 or later. Name it .cjs in an ES module project.
Other / HTTP	knownwise-ai-bots.sh	A curl example of the message to send.

The notes under the code are in your language. If an option can't be built, the card says We couldn't build the framework code with these options. Pick other options, or use Other / HTTP.

For Express, add app.use(knownwiseAiBots) before your routes. The file also exports knownwiseAiBotsWithStatus, which waits for your response and sends its status code. Use it if you want the Refused column on the AI bots page to work, since the other code runs before your page answers and has no status code to send.

If your Next.js site already has a proxy or middleware file, don't add a second one. Copy the Knownwise constants and the knownwiseTrack function into your file, and call knownwiseTrack(request, event) at the top of your function. Your matcher then decides which paths are counted. The GitHub route does this wrapping for you.

Where your site runs

This setting decides whether visits can be verified as the real bot. The code reads the visitor's IP only from a header that your platform sets itself, because anyone who reaches your server directly can forge the others.

• Vercel. Reads the visitor IP that Vercel sets, so visits can be verified.
• Behind Cloudflare. Reads the visitor IP that Cloudflare sets, so visits can be verified.
• Directly, no proxy. Reads the connection's own IP. Use it only with no proxy in front. Not offered for Next.js.
• Somewhere else. Sends no IP. Visits are counted but can't be verified as the real crawler.

Knownwise picks a default from your last site check. See Verified visits.

Test it

Test it asks your home page for a special test address, with a user agent the tracking code recognises. Your code passes it on to Knownwise, which marks the route as receiving and does not count it as a visit.

• Test sent. We'll look for the visit over the next few minutes. The test is running. When it arrives the row reads Tracking works. Waiting for the first AI bot visit, and Receiving since a date once a real AI bot visits.
• A test is already running. Try again in two minutes.
• Too many tests this hour. Try again later. You can test 10 times an hour.
• This route can't be tested right now. A Cloudflare row has nothing to test, and a turned-off route can't be tested.

If the test visit never arrives, Knownwise keeps trying for about a day. Then the row shows Problem: and what to check:

• the site didn't answer. Check that the change is deployed. Your home page gave no answer, or a server error.
• the site refused our check (401 or 403), so a firewall or bot protection is blocking it. A firewall or bot protection stopped the request before your code ran. Allow Knownwise and AI bots there. See The firewall warnings.
• no visits arrived. Check that KNOWNWISE_SITE_KEY is set where the site runs. Seen on the GitHub route for a public repository. Your site answered but nothing reached Knownwise. Check the variable holds the key from Show a new key for this, and that you redeployed after setting it.
• we reached your site, but no visit came back. Check the snippet is deployed and the key in it is the current one. Seen on the snippet route. Your site answered but nothing reached Knownwise. Check the file is deployed in the right folder, and that its key (or KNOWNWISE_SITE_KEY) is the one you were shown last.
• the site answered, but the tracking code didn't run. Check the file's name and folder. Seen on the GitHub route with the key in the code. The file is likely in the wrong folder or has the wrong name.

Running Test it again clears the problem and starts over. On a route that already receives visits, a test that never comes back adds The last test didn't come back: and the reason, and the route keeps counting.

A snippet key that was created but never sent anything stops counting as "being set up" after 7 days: the AI bots page and the suggestions then offer the route that fits your site again.

Make a new key

Make a new key replaces the site key. The confirmation reads The current key stops working at once. The site stops reporting until you deploy the new key. The route goes back to Waiting for first visit until visits with the new key arrive.

Remove it

Delete the Knownwise file (or the lines you added to your own file) and redeploy.

Related pages

• AI bot visits
• Connect Cloudflare
• The AI bots page