Next.js
Install
1
npm i @botbye/nextjs
1
yarn add @botbye/nextjs
Requires next >= 13 and react >= 18 as peer dependencies.
Configuration
Call phishing.init once at server startup — instrumentation.ts is the recommended place. Anti-phishing is identified by its own clientKey (available in your Phishing Project in the Dashboard), not the server key used by evaluate.
1
2
3
4
5
6
7
8
9
// instrumentation.ts
import { phishing } from "@botbye/nextjs/server";
export function register() {
phishing.init({
// clientKey from your Phishing Project on the Admin Dashboard
clientKey: "00000000-0000-0000-0000-000000000000",
});
}
phishing.init options
| Option | Type | Required | Description |
|---|---|---|---|
| clientKey | string | Yes | clientKey from your Phishing Project on the Admin Dashboard |
| url | string | No | Override BotBye API endpoint (default: https://verify.botbye.com) |
| logger.level | string | No | Log level: error, warn, info, debug, log (default: info) |
| logger.logger | TLogger | No | Custom logger implementing { error, warn, info, debug, log } |
| timeouts.fetchCatcher | number | No | Timeout in milliseconds for each fetchCatcher call |
Usage
Anti-phishing needs two route handlers on your own origin, each proxied through fetchCatcher:
SVG route — serves the SVG catcher. This is the URL your client code passes to getCatcher({ url }).
PNG route — serves the PNG that the SVG references (via innerPngUrl).
The paths are arbitrary — name the routes however you like. Pass the NextRequest as request and the format. For the SVG, innerPngUrl must be the absolute URL of your PNG route — the browser loads that PNG directly from your origin.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// app/botbye-catcher.svg/route.js
import { phishing } from "@botbye/nextjs/server";
import { NextResponse } from "next/server";
// Absolute URL of your PNG endpoint — the SVG catcher references it through innerPngUrl.
const PNG_CATCHER_URL = "https://your-site.example/botbye-catcher.png";
export async function GET(request) {
const catcher = await phishing.fetchCatcher({
request,
format: "svg",
innerPngUrl: PNG_CATCHER_URL,
});
return new NextResponse(catcher.body, { status: catcher.status, headers: catcher.headers });
}
1
2
3
4
5
6
7
8
9
// app/botbye-catcher.png/route.js
import { phishing } from "@botbye/nextjs/server";
import { NextResponse } from "next/server";
export async function GET(request) {
const catcher = await phishing.fetchCatcher({ request, format: "png" });
return new NextResponse(catcher.body, { status: catcher.status, headers: catcher.headers });
}
We recommend embedding the SVG catcher: it is designed to keep tracking even when a phishing site copies all of your assets to its own infrastructure (the PNG route exists because the SVG catcher relies on it).
Multiple instances
Use phishingFactory to create independent SDK instances, the same way factory works for evaluate.
1
2
3
4
5
6
7
8
9
10
import { phishingFactory } from "@botbye/nextjs/server";
const sdk = phishingFactory();
sdk.init({
// clientKey from your Phishing Project on the Admin Dashboard
clientKey: "00000000-0000-0000-0000-000000000000",
});
const catcher = await sdk.fetchCatcher({ request, format: "svg", innerPngUrl: PNG_CATCHER_URL });