API Integration Guide

Complete documentation for integrating SharkEyes protection into your web applications. Secure your forms, pages, and user interactions with advanced bot detection.

Quick Start Troubleshooting Other Docs GitHub →

Overview

SharkEyes provides three distinct integration methods to protect your web applications from bots and automated attacks. Each method is designed for specific use cases and offers different levels of user interaction.

Visible Widget

Interactive CAPTCHA challenge for form protection with full customization options.

PoW Protection

Computational challenge-based verification without any user interaction required.

Invisible Widget

Seamless background protection that works silently without visible interface elements.

Prerequisites

Before integrating SharkEyes, ensure you have:

  • A SharkEyes account (if required)
  • Access to modify your website's HTML
  • Basic understanding of HTML and JavaScript
  • HTTPS enabled on your domain (recommended)

Visible CAPTCHA Widget

The visible widget provides an interactive challenge that users must complete before submitting forms. This is the most secure option for protecting sensitive actions like user registration, login, or payment forms.

Installation Steps

Add Required Scripts to <head>

First, add the preconnect link and widget script to your page's head section. The preconnect link improves loading performance by establishing an early connection to the SharkEyes CDN.

HTML 
<head>
  <!-- Preconnect to SharkEyes CDN for faster loading -->
  <link rel="preconnect" href="https://edge.sharkeyes.dev">
  
  <!-- SharkEyes Visible Widget Script -->
  <script src="https://edge.sharkeyes.dev/api/v1/widget_v.js" 
          async defer></script>
</head>

Add Widget Container to Your Form

Place the widget container div inside your form element where you want the CAPTCHA to appear. Typically, this is placed just before the submit button.

HTML 
<body>
  <form action="/submit" method="POST">
    <!-- Your form fields -->
    <input type="email" name="email" required>
    
    <!-- SharkEyes CAPTCHA Widget -->
    <div data-sharkeyes-captcha></div>
    
    <button type="submit">Submit</button>
  </form>
</body>

Customize Widget (Optional)

Add data attributes to customize the widget's appearance and behavior according to your needs.

HTML 
<div data-sharkeyes-captcha
     data-theme="dark"
     data-size="compact"
     data-lang="en"
     data-auto="true">
</div>

Configuration Attributes

Customize the visible widget using the following data attributes:

Attribute Available Values Default Description
data-theme light, dark, auto light Controls the color scheme of the widget. Auto adapts to user's system preference.
data-size normal, compact normal Determines the widget size. Use compact for space-constrained layouts.
data-lang en, ru, he, de en Sets the interface language for instructions and messages.
data-auto true, false true When true, automatically verifies on page load. Set to false for manual triggering.

Proof of Work (PoW) Protection

Proof of Work protection provides bot detection through computational challenges that run in the background. This method requires no user interaction and is ideal for protecting pages without forms or when you want completely invisible protection.

Best Use Cases

  • Content pages and articles
  • API endpoints that need rate limiting
  • Pages where user interaction is undesirable
  • Protecting against scraping and automated access

Installation Steps

Add PoW Script to <head>

Include the PoW script in your page head. This script will automatically start the computational challenge when the page loads.

HTML 
<head>
  <!-- Preconnect to SharkEyes CDN -->
  <link rel="preconnect" href="https://edge.sharkeyes.dev">
  
  <!-- SharkEyes PoW Protection Script -->
  <script src="https://edge.sharkeyes.dev/api/v1/pow.js" 
          async defer></script>
</head>

Add Protection Container to <body>

Place the PoW container div anywhere in your body. The position doesn't matter as this protection works invisibly in the background.

HTML 
<body>
  <!-- SharkEyes PoW Protection Container -->
  <div data-pow-protected></div>
  
  <!-- Your page content -->
  <h1>Your Protected Content</h1>
  <p>This page is protected by SharkEyes PoW.</p>
</body>

How PoW Protection Works

When a user visits your protected page, the SharkEyes script automatically:

  1. Generates a unique computational challenge
  2. Solves the challenge using the visitor's browser resources
  3. Submits the solution to SharkEyes servers for verification
  4. Allows legitimate access while blocking bots that can't complete the challenge

This process typically takes less than a second and is completely transparent to legitimate users.

Invisible Widget

The invisible widget provides silent, background protection without any visible interface elements. It analyzes user behavior patterns and browser fingerprints to detect bots without interrupting the user experience.

When to Use Invisible Widget

  • When you want maximum security with zero user friction
  • For applications where UI elements would disrupt the experience
  • As an additional layer on top of other security measures
  • For monitoring and analytics without visible indicators

Installation Steps

Add Invisible Widget Script

Include the invisible widget script in your page head. This script operates completely in the background.

HTML 
<head>
  <!-- Preconnect to SharkEyes CDN -->
  <link rel="preconnect" href="https://edge.sharkeyes.dev">
  
  <!-- SharkEyes Invisible Widget Script -->
  <script src="https://edge.sharkeyes.dev/api/v1/widget.js" 
          async defer></script>
</head>

Add Widget Container

Place the widget container div in your body. Despite being invisible, the container is required for the script to function properly.

HTML 
<body>
  <!-- SharkEyes Invisible Widget Container -->
  <div data-sharkeyes></div>
  
  <!-- Your page content -->
  <h1>Welcome</h1>
</body>

Benefits of Invisible Protection

  • Zero User Friction: No visible challenges or interactions required
  • Continuous Monitoring: Analyzes behavior throughout the session
  • Advanced Detection: Uses machine learning and behavioral analysis
  • Seamless Integration: Works alongside existing security measures

Advanced Configuration

Learn about advanced configuration options and best practices for optimizing SharkEyes integration.

Script Loading Optimization

The async and defer attributes ensure optimal page load performance:

Attribute Behavior Use Case
async Downloads script in parallel, executes immediately when ready When script doesn't depend on DOM elements
defer Downloads in parallel, executes after DOM is fully parsed When script needs DOM elements to be available
async defer Prefers async, falls back to defer if async not supported Recommended for maximum compatibility

Security Best Practices

Always Use HTTPS

Ensure your site uses HTTPS to protect the integrity of SharkEyes verification tokens.

Server-Side Validation

Always verify SharkEyes tokens on your server. Client-side checks alone are not sufficient.

Regular Updates

Keep your integration updated by using the latest script versions from the CDN.

Multiple Widgets on Same Page

You can use multiple SharkEyes widgets on the same page by giving each container a unique identifier:

HTML 
<!-- First form -->
<form id="login-form">
  <div data-sharkeyes-captcha data-form-id="login"></div>
</form>

<!-- Second form -->
<form id="signup-form">
  <div data-sharkeyes-captcha data-form-id="signup"></div>
</form>

Troubleshooting

Common issues and solutions for SharkEyes integration problems.

Slow Script Loading

If you experience slow loading times or timeouts when loading SharkEyes scripts, try these solutions:

Solution 1: Use Alternative CDN

Switch from edge.sharkeyes.dev to api.sharkeyes.dev for potentially better performance in your region:

HTML 
<head>
  <!-- Use alternative CDN -->
  <link rel="preconnect" href="https://api.sharkeyes.dev">
  <script src="https://api.sharkeyes.dev/api/v1/widget_v.js" 
          async defer></script>
</head>

Solution 2: Use Minified Scripts

Minified scripts are smaller and load faster. Add .min.js to any script URL:

Widget Type Standard Script Minified Script
Visible Widget /api/v1/widget_v.js /api/v1/widget_v.min.js
PoW Protection /api/v1/pow.js /api/v1/pow.min.js
Invisible Widget /api/v1/widget.js /api/v1/widget.min.js
HTML 
<!-- Example: Minified Visible Widget on Alternative CDN -->
<script src="https://api.sharkeyes.dev/api/v1/widget_v.min.js" 
        async defer></script>

CDN Endpoint Reference

Quick reference for all available CDN endpoints and script variations:

Widget Type Edge CDN API CDN
Visible Widget edge.sharkeyes.dev/api/v1/widget_v.js api.sharkeyes.dev/api/v1/widget_v.js
Visible Widget (min) edge.sharkeyes.dev/api/v1/widget_v.min.js api.sharkeyes.dev/api/v1/widget_v.min.js
PoW Protection edge.sharkeyes.dev/api/v1/pow.js api.sharkeyes.dev/api/v1/pow.js
PoW Protection (min) edge.sharkeyes.dev/api/v1/pow.min.js api.sharkeyes.dev/api/v1/pow.min.js
Invisible Widget edge.sharkeyes.dev/api/v1/widget.js api.sharkeyes.dev/api/v1/widget.js
Invisible Widget (min) edge.sharkeyes.dev/api/v1/widget.min.js api.sharkeyes.dev/api/v1/widget.min.js

Common Issues & Solutions

Widget Not Appearing

Check that the container div has the correct data attribute and the script loaded successfully in browser console.

CORS Errors

Ensure your domain is whitelisted in SharkEyes dashboard and using HTTPS protocol.

Slow Verification

Try the alternative CDN endpoint or check if your firewall is blocking SharkEyes domains.

Mobile Issues

Use compact size for better mobile experience: data-size="compact"

Complete Integration Examples

Real-world examples showing complete implementations of each SharkEyes protection method.

Example 1: Registration Form with Visible Widget

A complete user registration form protected by SharkEyes visible CAPTCHA widget:

HTML 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>User Registration</title>
  
  <!-- SharkEyes Integration -->
  <link rel="preconnect" href="https://edge.sharkeyes.dev">
  <script src="https://edge.sharkeyes.dev/api/v1/widget_v.js" 
          async defer></script>
  
  <style>
    body { font-family: sans-serif; max-width: 500px; margin: 50px auto; }
    input { width: 100%; padding: 10px; margin: 10px 0; }
    button { width: 100%; padding: 12px; background: #0066FF; color: white; border: none; }
  </style>
</head>
<body>
  <h1>Create Account</h1>
  
  <form action="/register" method="POST">
    <label for="username">Username:</label>
    <input type="text" id="username" name="username" required>
    
    <label for="email">Email:</label>
    <input type="email" id="email" name="email" required>
    
    <label for="password">Password:</label>
    <input type="password" id="password" name="password" required>
    
    <!-- SharkEyes CAPTCHA Widget -->
    <div data-sharkeyes-captcha
         data-theme="auto"
         data-size="normal"
         data-lang="en"
         data-auto="true">
    </div>
    
    <button type="submit">Create Account</button>
  </form>
</body>
</html>

Example 2: Protected Content Page with PoW

A content page protected by Proof of Work without any visible challenges:

HTML 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Protected Article</title>
  
  <!-- SharkEyes PoW Protection -->
  <link rel="preconnect" href="https://edge.sharkeyes.dev">
  <script src="https://edge.sharkeyes.dev/api/v1/pow.js" 
          async defer></script>
</head>
<body>
  <!-- PoW Protection Container -->
  <div data-pow-protected></div>
  
  <article>
    <h1>Premium Content</h1>
    <p>This article is protected from scraping and automated access.</p>
    <!-- Your content here -->
  </article>
</body>
</html>

Example 3: E-commerce Checkout with Invisible Widget

A checkout page with invisible protection for seamless user experience:

HTML 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Checkout</title>
  
  <!-- SharkEyes Invisible Widget -->
  <link rel="preconnect" href="https://api.sharkeyes.dev">
  <script src="https://api.sharkeyes.dev/api/v1/widget.min.js" 
          async defer></script>
</head>
<body>
  <!-- Invisible Widget Container -->
  <div data-sharkeyes></div>
  
  <h1>Complete Your Order</h1>
  
  <form action="/process-payment" method="POST">
    <!-- Payment form fields -->
    <input type="text" name="card_number" placeholder="Card Number" required>
    <button type="submit">Complete Purchase</button>
  </form>
</body>
</html>
You are offline - check your internet connection