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 Advanced request type. 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 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 can 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.
• If you need persistence with Basic, you may implement your own first‑party cookie/session logic. Otherwise, consider using Advanced instead.

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

Advanced — Full‑context clustering

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

• Produces a more stable, more unique clusterUUID by combining device and network context.
• Distinguishes privacy networks (e.g., iCloud Private Relay) by classifying exit nodes, reducing crowding on shared egress IPs.
• Static‑IP pinning: when an IP is confidently non‑anonymous and stable, a clusterUUID can be anchored to it to further reduce collisions.
• First‑party cookie binding: OPJS writes/reads a first‑party cookie to persist identity across sessions and minor browser/OS updates.
• Designed for abuse prevention, account defense, and analytics deduplication where accurate user resolution matters.

Best for: most production sites that need durable identity, fewer collisions, and strong fraud/abuse controls.

Quick comparison

Dimension	Basic	Advanced
Inputs	Browser fingerprint	Fingerprint + MaxMind IP intel + first‑party cookie
Uniqueness	Moderate; collisions for look‑alike devices	High; fewer collisions (handles NATs, VPNs/relays better)
Persistence across updates	Lower	High (cookie binding + network intelligence)
Network awareness	None	Classifies IPs (residential, hosting, VPN/relay), geolocation, static‑IP pinning
Ideal use	Bot screening, minimal data collection	Fraud prevention, account integrity, analytics dedupe

TL;DR

• Basic = fingerprint‑only, broader grouping, minimal data. Great for lightweight bot defense.
• Advanced = fingerprint + IP intelligence + first‑party cookie for maximum stability and minimal collisions, including on privacy networks and shared NATs.

Rate Details

• Basic: 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

CDN

page.html

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

NPM

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