Getting Started

Requirements

HTTPS: OverpoweredJS requires that your web page is served over HTTPS.
Supported Browsers: OverpoweredJS supports all modern browsers, including Chromium-based browsers (Google Chrome, Microsoft Edge, Opera, Brave), as well as Firefox and Safari.

Understanding Signals

clusterUUID is a probabilistic, pseudonymous identifier we compute to group events that likely come from the same user/device. Choose a request type based on how much stability and uniqueness you need.

Additional signals included with every request are:

botScore — probabilistic signal indicating likelihood of automation/bot behavior.
Anti‑detect browser detection — heuristics to detect malicious agents trying to bypass tracking.
possibleCountryCodes — fingerprint-inferred country candidates, independent of IP.
Additional diagnostics and risk fields — consistency checks and anomaly flags you can pipe into your own rules.

Request Types

For most use cases, use the Standard or Advanced request types. The Basic request type is best suited when your only concern is blocking bots, detecting anti-detect browsers, or fingerprinting short-term device characteristics rather than tracking real users over the long term.

Need help choosing?

Different request types are better suited to different use cases, and it’s not always obvious which one to pick. If you’re unsure, reach out to support and we’ll help you decide.

Basic — Fingerprint‑only clustering

What it uses: on‑device/browser signals only (e.g., UA/Client Hints, GPU/WebGL, canvas, storage quota, fonts, media queries).

What it does not use: third‑party IP intelligence; no OPJS cookie.

Generates a clusterUUID solely from the browser fingerprint.
Users with identical fingerprints will share the same clusterUUID (broader grouping → more collisions).
Less durable across browser/OS updates—IDs may change when the environment changes.
Great for lightweight bot filtering and privacy‑sensitive use cases where you don’t want network data involved.

Best for: teams that want simple risk signals or prefer to handle long‑term tracking themselves.

Standard — Full-context clustering

What it uses: browser fingerprint + Synthient IP intelligence (ASN/ISP, hosting/VPN/relay classification, residential vs. data-center, geosignals) + OPJS first-party cookie.

Yields a stable, more unique clusterUUID by combining device and network context when compared to Basic.
Understands privacy relays (e.g., iCloud Private Relay), VPNs, and network context, reducing collisions and resolution errors.
First-party cookie persists identity across sessions and routine browser/OS updates to further assist in tracking.
IP intel source: Synthient. In practice, this can be more prone to ISP/geolocation mislabels than MaxMind (used by Advanced), which may cause more mistakes in identity resolution.

Best for: most production sites that want durable identity with low collision rates and strong fraud/abuse controls.

Advanced — Full-context clustering (+ MaxMind)

What it uses: browser fingerprint + MaxMind IP intelligence (ASN/ISP, hosting/VPN/relay classification, residential vs. data-center, geosignals) + OPJS first-party cookie.

Delivers our highest stability and uniqueness; better differentiation on noisy networks, NATs, and privacy relays.
Static-IP pinning: when an address is confidently non-anonymous and stable, the clusterUUID can be anchored to it to further reduce collisions. This can significantly increase the uniqueness of the identifier.
IP intel source: MaxMind. Its geolocation and ISP/hosting labeling are typically more accurate than Synthient’s, yielding fewer resolution mistakes and tighter clustering.

Best for: high-stakes production environments needing maximum persistence and minimal collisions.

Quick comparison

Dimension	Basic	Standard	Advanced
Inputs	Browser fingerprint	Fingerprint + Synthient IP intel + first-party cookie	Fingerprint + MaxMind IP intel + first-party cookie
Uniqueness	Moderate (look-alike devices can collide)	High	Highest (adds static-IP pinning when possible)
Persistence across updates	Low	High	Highest
Network awareness	None	Classifies IPs (residential, hosting, VPN/relay), geolocation	Everything in Standard + static-IP pinning
IP intel accuracy	—	Good, but more mistakes vs Advanced (Synthient)	Higher accuracy → fewer resolution mistakes (MaxMind)
Ideal use	Bot screening, minimal data collection	Fraud prevention, account integrity, analytics dedupe	High-risk fraud prevention, precise user resolution

TL;DR

Basic = fingerprint‑only, broader grouping, minimal data. Great for lightweight bot defense.
Standard = fingerprint + Synthient IP intelligence + first-party cookie → stable IDs for most production needs, but more ISP/geo mislabels than Advanced.
Advanced = fingerprint + MaxMind IP intelligence + first-party cookie (+ static-IP pinning) → higher labeling/geo accuracy and fewer resolution mistakes.

Rate Details

Basic: 10 credits
Standard: 10 credits
Advanced: 30 credits

Overages are billed at $0.0002 per credit.

Generate an API Key

Each API key is pegged to a request type when generated via the Dashboard. The request type determines how the unique identifier (clusterUUID) is computed and how many credits are consumed per call.

Create an API key under the Config section in your project.

Installation

page.html
<script src="https://cdn.overpoweredjs.com/loader/opjs"></script>

terminal
npm install overpoweredjs

Basic Usage

Call opjs with your API key:

opjs({ API_KEY: 'my-api-key' }).then(fp => {
  console.log(fp);
});

The API key you pass determines the request type (Basic, Standard, or Advanced) and how the clusterUUID is computed.

Example

This function retrieves the response object, which you can send to your server or use directly in your client code.

note

Running opjs() on page load can degrade bot detection results. For more effective detection, load the script on page load and execute opjs() only after the user performs an action (e.g., button click, form submit).

Here is a minimal example of integrating OverpoweredJS into your web page:

<!DOCTYPE html>
<html>
  <head>
    <title>OverpoweredJS Integration Example</title>
    <script src="https://cdn.overpoweredjs.com/loader/opjs"></script>
  </head>
  <body>
    <button id="detectBot">Check Bot Status</button>

    <script>
      document.getElementById('detectBot').addEventListener('click', function () {
        opjs({ API_KEY: 'my-api-key' }).then(fp => {
          console.log('Fingerprint:', fp);
          // Send fingerprint data to your server
          fetch('/your-endpoint', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
            },
            body: JSON.stringify(fp),
          })
            .then(response => response.json())
            .then(data => {
              console.log('Server Response:', data);
            })
            .catch(error => {
              console.error('Error:', error);
            });
        });
      });
    </script>
  </body>
</html>

Requirements​

Understanding Signals​

Request Types​

Basic — Fingerprint‑only clustering​

Standard — Full-context clustering​

Advanced — Full-context clustering (+ MaxMind)​

Quick comparison​

Rate Details​

Generate an API Key​

Installation​

Basic Usage​

Example​