Proxy/VPN Detection Integration Instructions

The documentation on this page demonstrates how the Proxy/VPN Detection Tests can be integrated in your website or app. Essentially, all you have to do is to include a JavaScript in your website and setup an API Callback to receive the Proxy/VPN detection results.

  • This service is free of charge. By integrating your website, you can help me make the detection tests better. All gathered detection data will be deleted after a couple of days.
  • By default, only positive sessions will be POSTed to the callback. This helps to reduce bandwidth. You can change this behavior in the configuration.
  • Your website should not have more than ~50,000 requests per day. This API is for demonstration purposes only and should not be used in mission critical scenarios.

Step 1: Configuration and Callback

You can configure the behavior of the Proxy and VPN Detection API. Below, you can see the default configuration: 

{
  "callbackPostUrl": "https://example.org/callback",
  "activatedTests": "all",
  "onlySendPositive": true,
  "onlySendTestResult": true,
  "enableActiveCallback": true,
  "enablePassiveCallback": false,
}

The explanation for the various configuration keys is as follows:

  • callbackPostUrl - This is the full URL of the HTTPS POST endpoint to which the Proxy/VPN detection results will be sent. This must be a HTTPS URL.
  • activatedTests - This is either an array of all activated tests or the string "all". It is suggested to leave this option set to "all".
  • onlySendPositive - If this option is set to true, only sessions with detected Proxy or VPN usage will be sent via callback.
  • onlySendTestResult - If true, then you will not receive test details for each of the Proxy and VPN detection tests. If this option is set to false, you will receive full details for each detection test.
  • enableActiveCallback - Active detection tests require the execution of JavaScript. If this option is set to true, you will receive a callback as soon as all tests (active and passive) are finished.
  • enablePassiveCallback - Passive tests do not require the execution of JavaScript. If true, you will receive a callback as soon as all passive detection tests are finished (Without waiting for the active tests). However, the passive callback CAN include tests that require JavaScript. The passive callback won't wait for them, but if they are available, they are included.

Step 2: Add the JavaScript to your Website

Add the following JavaScript to your website. Make sure that you use your own API Key (pdKey) and that your provide a custom value for pdVal.

  • pdKey: This is your API Key. This value is necessary in order for the detection server to know from where the request came from and in order to sent the results to the correct callbackPostUrl.
  • pdVal: This is your custom value. It can help you to identify a certain session or a certain user in your web application. The detection server just passes this value directly to the callback and does not use this value internally.
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Proxy/VPN Detection Tests - Integration Example</title>

  <script>
    // First, specify your API key.
    const pdKey = 'bee2cf3b70e32e981b7b';
    // Optionally, you can specify any custom value. This value could for example identify 
    // the session of your user. The same value is provided in the API callback.
    // With this value, you can make any kind of action depending on whether a Proxy or VPN was detected.
    const pdVal = '12345';
    // Now the JavaScript integration URL is created and the JS is loaded dynamically
    const fullUrl = 'https://pd-us-east.incolumitas.com/pd-lib.js?pdKey=' + pdKey + '&pdVal=' + pdVal;
    let pdsScript = document.createElement("script");
    pdsScript.setAttribute("src", fullUrl);
    document.head.appendChild(pdsScript);
  </script>
</head>
<body>
</body>
</html>

Step 3: Receiving Callbacks

After successfully placing the JavaScript and configuring your callback, your are ready to receive callbacks. There are two different kinds of callbacks:

  • Passive Callbacks: Some of the detection test do not require data obtained with JavaScript. Therefore, passive tests can be sent as soon as a client has made the first request to the server (After the JavaScript was requested). Passive callbacks can also include active test results.
  • Active Callbacks: Active callbacks need to wait for the arrival of information obtained with JavaScript. Active Callbacks also include passive test results.

Callback Format

Each callback payload (regardless whether it is active or passive) has the following basic callback structure.

Example Passive Callback

Example Active Callback

Step 4: Ban or Rate Limit Proxy/VPN Usage

It is up to you to decide what action to take when a user was detected using a Proxy or VPN. For example, most web services don't want to serve users that are using Anonymizing Proxies. In order to ban a user that is using a proxy, your custom action could look like the example below. Node.js and Express is used for the example below:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));

app.post('/callback', (req, res) => {
  let payload = req.body;

  if (payload.pdKey && payload.pdVal) {
    // how this is implemented depends on your backend logic
    const user = getUserByPdVal(payload.pdVal);

    if (user) {
      // user is using a Proxy
      // The threshold depends on your requirements
      // In this example, we take a score of 4 in order to label the connection as "proxied"
      if (payload.proxy.score >= 4) {
        user.displayCaptcha();
      }
    }
    // In this example, we don't care if users are using VPN's
  }

  res.header('Content-Type', 'application/json');
  return res.send({ 'msg': 'ok' });
});


app.listen(3000, () => {
  console.log('Example app listening on port 3000!');
});