GuidesRecipesAPI ReferenceChangelog
Guides

BOT Detection

how to configure Trustfull's Bot Detection JS SDK

The Bot Detection feature helps identify anomalous patterns that may indicate bot activity or suspicious connections. By leveraging device and network fingerprinting techniques, the system collects detailed session information to provide accurate insights into the nature of the traffic on your website.

Bots can be used for various malicious purposes, such as scraping content, performing credential stuffing attacks, or simulating user interactions to defraud online services. Detecting these activities in real time is critical for maintaining the integrity of your platform, safeguarding user data, and ensuring a frictionless experience for legitimate users.

This feature uses advanced techniques to collect and analyze device and network signals without impacting user experience. The analysis helps distinguish between human users and automated bots, even in sophisticated scenarios where bots mimic human behavior.

Possible Use Cases

  • Account Farming / Multi-Account: Detect suspicious patterns where the same device or network is used to create or operate multiple accounts, often to exploit promotions, bypass restrictions, or conduct abusive behaviors.
  • Fraud Prevention: Detect automated scripts performing fraudulent actions such as fake registrations, coupon abuse, or payment fraud.
  • Content Protection: Prevent scraping of proprietary data, intellectual property, and pricing information.
  • Account Security: Identify bots attempting credential stuffing and brute force attacks.
  • Ad Integrity: Detect and block invalid traffic to protect ad campaigns and prevent click fraud.
  • User Experience Optimization: Avoid polluting analytics and recommendation engines with non-human traffic.

How It Works

Data Collection

The Bot Detection process begins when a small JavaScript snippet is embedded into the website. As soon as a user loads the page, this script activates and enters a passive listening mode. During this phase, the script gathers extensive information about the device and network, including characteristics like browser type, screen resolution, IP address, and connection attributes. These details contribute to creating a robust fingerprint of the session. To ensure that each session can be uniquely identified and tracked, the customer must provide a Session ID before loading the script. Additionally, the script requires an API Key to authorize its operations, ensuring secure communication with the backend.

Data Submission and Analysis

Once data collection is underway, the customer can determine the right moment to transmit this information to the backend for analysis. This typically happens after a significant user action, such as a button click or form submission. By calling a simple JavaScript function, all the collected session data is sent to the backend system. There, the data undergoes in-depth processing, where algorithms analyze the patterns and indicators to detect potential bot-like behavior. This phase is designed to be fast and efficient, allowing near real-time evaluation while the session is still active.

Result Retrieval

After processing is complete, the analysis results are made available through a server-to-server API call. The customer can retrieve these results using the same Session ID that was assigned earlier. The response provides a score representing the likelihood that the session involved a bot. Along with the score, the API also returns all raw data collected during the session, offering complete transparency into the evaluation process. These results can then be integrated into the customer’s backend systems to make informed decisions, such as blocking the session, flagging it for review, or allowing it to continue seamlessly.

Integration Guide

1. Install the JavaScript Snippet

To get started with Trustfull, paste the following JavaScript code before your website's closing tag. When using this JS, remember to replace YOUR-JS-KEY with the ID of the environment to which you want to send data. You can find this ID on your dashboard.

<script>
  (function(f, i, d, o, c, od, e) {
    f["FidoObject"] = c;
    f[c] = f[c] || function() {
      (f[c].q = f[c].q || []).push(arguments);
    }, f[c].l = 1 * new Date();
    od = i.createElement(d),
      e = i.getElementsByTagName(d)[0];
    od.async = 1;
    od.src = o;
    e.parentNode.insertBefore(od, e);
  })(window, document, "script", "https://det.trustfull.com/det.js", "det");

  det("create", "YOUR_APP_KEY");
</script>

📘

Note that the JS SDK is always loaded over SSL.

❗️

If you're installing Trustfull on both production and staging versions of your site, be sure to use the JS-KEY that corresponds to the environment in Trustfull you want to send data to. If you send data to the wrong environment, it will pollute the data in that environment.

2. Trigger Data submission

When ready (e.g., after a user action), call the following function to submit the collected data:

det.sendRecord(YOUR_SESSION_ID)

This function can be invoked at any time during the user session. You may choose to trigger it after meaningful user actions, such as form submissions, login attempts, or critical workflow steps. Alternatively, it can be executed immediately after the page loads or in the background when specific conditions are met. This flexibility allows you to align bot detection with your application's business logic and user journey.

3. Retrieve Results (Server-To-Server API)

Once the data is processed, a server-to-server API call will be performed using the session ID to obtain the detection results. Example request:

curl -X GET "https://api.trustfull.com/bot-detection/result?session_id=YOUR_SESSION_ID" \
     -H "X-api-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json"

The API response will provide a score reflecting the bot activity's likelihood. This score can be used directly in your risk assessment logic. For example, sessions with a score below a certain threshold might be blocked or flagged for manual review, while higher-scoring sessions can be seamlessly allowed. In addition to the score, the response includes the raw data collected, enabling deeper analysis or logging for auditing purposes.

Example response:

{
  "browser_battery_charging": true,
  "browser_battery_level": 85,
  "browser_color_depth": "24",
  "browser_cookies_enabled": true,
  "browser_cpu_class": "x86",
  "browser_cpu_cores": "12",
  "browser_device_brand": "Samsung",
  "browser_device_model": "Galaxy S7 Edge",
  "browser_device_operating_system": "Android",
  "browser_device_type": "desktop",
  "browser_do_not_track": true,
  "browser_has_privacy_related_plugins": true,
  "browser_incognito_mode": true,
  "browser_language": "it-IT",
  "browser_media_devices_count": "3",
  "browser_media_devices_list": "audioinput,videoinput,audiooutput",
  "browser_name": "Chrome",
  "browser_screen_resolution": "1920x1080",
  "browser_timezone": "Europe/Rome",
  "browser_version": "114.0.1",
  "browser_video_card_renderer": "angle (intel, mesa intel(r) graphics (rpl-u), opengl 4.6)",
  "browser_video_card_vendor": "google inc. (intel)",
  "browser_viewport": "1193x1327",
  "click_count": 2,
  "connection_type": "Reserved",
  "device_request_time": "2025-05-07 12:39:53",
  "has_headless_app_version": false,
  "has_headless_user_agent": false,
  "has_mime_prototype_anomaly": true,
  "has_permissions_anomaly": true,
  "has_plugins_prototype_anomaly": true,
  "has_puppeteer_extra_stealth": true,
  "has_webrtc_leak": true,
  "has_window_outer_dimension_anomaly": false,
  "header_language": "it;q=0.9",
  "header_mime_types": "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
  "header_referer": "https://bot-detection-staging.trustfull.com/",
  "header_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
  "ip": "188.216.85.224",
  "ip_black_list_count": 0,
  "ip_city": "Milan",
  "ip_company_domain": "google.com",
  "ip_connection_speed": "broadband/cable/fiber",
  "ip_connection_type": "Fixed Line",
  "ip_connection_type_src": "isp",
  "ip_country": "Italy",
  "ip_country_code": "IT",
  "ip_country_language_list": "ca,fur,de,it",
  "ip_css_count": 0,
  "ip_css_in_days": 7,
  "ip_is_hosting": false,
  "ip_is_mobile": false,
  "ip_is_proxy": false,
  "ip_is_relay": false,
  "ip_is_tor": false,
  "ip_is_valid_format": true,
  "ip_is_vpn": false,
  "ip_isp": "Vodafone Italia S.p.A.",
  "ip_lat": "45.4643",
  "ip_lon": "9.1895",
  "ip_proxy_name": "ProxyXYZ",
  "ip_proxy_type": "datacenter",
  "ip_remote_desktop_enabled": true,
  "ip_timezone": "Europe/Rome",
  "ip_timezone_relative_utc": "UTC+02:00",
  "ip_timezone_request_time": "morning",
  "ip_timezone_request_time_src": "2025-05-06T09:04:25.182CEST",
  "ip_vpn_name": "NordVPN",
  "ip_xbl_count": 0,
  "ip_xbl_in_days": 2,
  "ip_zip": "20121",
  "language_match": false,
  "mime_types_match": false,
  "mouse_movement": 153,
  "navigator_app_version": "5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
  "navigator_connection_rtt": 0,
  "navigator_language": "it",
  "navigator_mime_types": "application/pdf,application/x-google-chrome-pdf",
  "navigator_platform": "Linux x86_64",
  "navigator_plugins": "UpzZzCB,Browser com.adobe.pdf Viewer,Chromium PDF and PS Renderer,k5kxBIr8",
  "navigator_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
  "navigator_web_driver": true,
  "private_ip_addresses": "null",
  "proxy_name": "oxylabs",
  "proxy_type":"datacenter",
  "reason_codes": "RB001,TB002",
  "resolution_id": "ac126dcb-3eea-4273-85a2-d6414823489c",
  "score": 500,
  "score_cluster": "review",
  "score_confidence": 50,
  "score_model_used": "bot_detection_score",
  "session_id": "GOW7flnf3g",
  "time_elapsed_ms": 1835763,
  "total_movements": 153,
  "transaction_id": "ac126dcb-3eea-4273-85a2-d6414823489c",
  "user_agent_match": true,
  "wheel_count": 0,
  "window_outer_height": 362,
  "window_outer_width": 1923,
  "zero_movement_count": 3
}

Best Practices

To ensure optimal performance and reliable results from the Bot Detection feature, the following best practices should be followed:

  • Generate a Unique Session ID: Always create a unique Session ID for every user session. This ensures that data remains isolated, traceable, and easy to manage when retrieving and analyzing results.
  • Trigger Submission at Meaningful Moments: Call tfbd.sendRecord(sessionId) when it provides the most contextually rich data, such as after a user has completed a form, performed a login attempt, or initiated a transaction. However, since submission can be triggered at any time, consider submitting data also for background monitoring or upon page load when needed.
  • Interpret Scores Carefully: Define internal thresholds for interpreting bot scores (e.g. low, medium, high risk) and align them with your fraud prevention strategy. Use these thresholds to automate responses such as blocking, adding friction (like CAPTCHA), or flagging for review.
  • Leverage Raw Data: Make use of the raw data returned with the score for advanced use cases. This can include audit trails, enriching machine learning models, or correlating session details during fraud investigations.
  • Monitor and Iterate: Regularly review how the Bot Detection feature performs. Use collected metrics and incident analysis to tune thresholds, improve submission timing, and refine business rules for handling risky sessions.

Throubleshootinng

Typos in the JS SDK

If you received the JavaScript copy/pasted it into an email or another document, it's easy for typographical elements in the JS SDK to get reformatted. For example, you may end up with curly double quotes instead of straight quotes, or + signs may have been stripped. When in doubt, copy/paste the JavaScript directly from the developer documentation into your app.

Other

If you've double-checked all of the reasons above and are still having trouble, reach out to [email protected] with full-screen screenshots of the developer console on both tabs or a video of what you are experiencing.

Missing JS-KEY

When copying/pasting the JS SDK, be sure you have code that includes your JS-KEY in the Trustfull init call.
If you get the JavaScript from the install page after you sign up, or from our developer docs while logged in, this won't be a problem. However, if you copy a version while logged out, you might end up with a code that won't work.

Example:

det("create", "YOUR-JS-KEY");

Updated 2 days ago