DOCSEARCHbyAlgolia
Submit Docs

powCAPTCHA Documentation

website·Indexed 31 days ago

https://docs.powcaptcha.com

Documentation for integrating and configuring the powCAPTCHA widget, including installation, server-side response verification, widget attributes, event listening, and invisible mode. Includes details on the machine learning-based spam filter available for Pro subscriptions.

Tokens
2.9K
Snippets
11
Records
17
Agent score
51%

What's inside powCAPTCHA

  1. Overview of powCAPTCHA

    powCAPTCHA is a privacy-first CAPTCHA solution that uses Proof-of-Work (PoW) to prevent bot activity and filter spam. It is designed for easy integration into websites to stop automated abuse while remaining user-friendly.

  2. Implement manual execution strategies for Invisible Mode

    Since the invisible widget does not have a visible trigger, you must decide when to obtain and solve the challenge. Common strategies include:

    • Triggering upon form submission.
    • Triggering when a form field receives focus.
    • Triggering after a keyup event (or a specific number of keyups).
    • Triggering after a set amount of time has elapsed.
    • Combining multiple triggers (e.g., triggering on focus/keyup only if 5 seconds have passed since page load, otherwise triggering on submit).
    <form method="POST" id="form-docs-example">
  <input type="text" name="name" placeholder="Full name" required />
  <input type="email" name="email" placeholder="Email" required />
  <textarea name="message" placeholder="Message" required></textarea>
  <powcaptcha-widget data-app-id="YOUR_APP_ID" data-invisible></powcaptcha-widget>
  <input type="submit" value="Submit" />
</form>

  3. Listen to powCAPTCHA widget events

    The powCAPTCHA widget emits custom JavaScript events that allow developers to handle user interactions and state changes. You can attach standard event listeners to the powcaptcha-widget element to respond to these events. The event data (such as tokens, error messages, or progress percentages) is contained within the event.detail object.
    const widget = document.querySelector('powcaptcha-widget');

// Handle successful completion
widget.addEventListener('@powcaptcha/widget/solved', (event) => {
    console.log('Challenge solved:', event.detail.token);
});

// Handle errors
widget.addEventListener('@powcaptcha/widget/error', (event) => {
    console.error('Error occurred:', event.detail.error);
});

// Handle start of solving process
widget.addEventListener('@powcaptcha/widget/solving', () => {
    console.log('Solving challenge...');
});

// Handle solving progress updates
widget.addEventListener('@powcaptcha/widget/solving/progress', (event) => {
    console.log('Solving progress:', event.detail.progress);
});

  4. Load the powCAPTCHA widget script

    To make the powCAPTCHA widget available on your website, include the widget JavaScript file. The script should be placed in the <head> section of your HTML or immediately before the closing </body> tag. Use the async and defer attributes to ensure the script does not block page rendering.
    <script src="https://js.powcaptcha.com/widget.js" async defer></script>

  6. Implement powCAPTCHA Spam Filter in verification requests

    To use the spam filter (available for Pro subscriptions and higher), include the spamFilter object in the verification request sent to the /challenges/verify endpoint. The spamFilter object accepts optional email and text fields containing the user's form input for analysis.
    const response = await fetch('https://api.powcaptcha.com/challenges/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    secret: 'your_private_key',
    solution: 'your_solution_token',
    spamFilter: {
      email: requestUser.email,
      text: requestUser.text,
    },
  }),
});

  7. Enable powCAPTCHA Invisible Mode

    To render the powCAPTCHA widget as invisible, add the data-invisible attribute to the <powcaptcha-widget> element. When using invisible mode, it is recommended to delay obtaining the challenge until after the page has loaded to ensure user signals are collected, which improves the accuracy of the challenge rating.
    <powcaptcha-widget data-app-id="YOUR_APP_ID" data-invisible="true"></powcaptcha-widget>

  8. Customize the powCAPTCHA widget using HTML attributes

    The powCAPTCHA widget can be customized by adding specific data- attributes and the name attribute to the widget element. These control localization, themes, visibility, and server-side communication.
    <div 
  data-app-id="YOUR_APP_ID"
  data-locale="en"
  data-theme="dark"
  data-invisible="true"
  name="custom-captcha-response"
></div>

  9. powCAPTCHA widget event reference

    The following events are emitted by the powCAPTCHA widget:

    • @powcaptcha/widget/solved: Fired when the challenge is successfully solved. The event.detail contains the solution token.
    • @powcaptcha/widget/error: Fired when an error occurs during the challenge process. The event.detail contains error details.
    • @powcaptcha/widget/solving: Fired when the challenge solving process starts. No additional detail is provided.
    • @powcaptcha/widget/solving/progress: Fired to indicate progress while solving the challenge. The event.detail contains a progress value.

  10. Embed the powCAPTCHA widget in HTML

    Display the powCAPTCHA widget on a page by inserting the <powcaptcha-widget> custom element. You must provide your unique application ID via the data-app-id attribute, which is available in the powCAPTCHA dashboard.
    <powcaptcha-widget data-app-id="YOUR_APP_ID"></powcaptcha-widget>

  11. Verify powCAPTCHA response via REST API

    To verify a powCAPTCHA solution token on your server, send a POST request to the verification endpoint. This process ensures the token is valid and allows for optional spam filtering for paid plan users.
    POST /challenges/verify HTTP/1.1
Host: api.powcaptcha.com
Content-Type: application/json

{
  "solution": "your_solution_token",
  "secret": "your_private_key",
  "spamFilter": {
    "text": "optional_text_to_check_for_spam",
    "email": "optional_email_to_check_for_spam"
  }
}

  12. Configure powCAPTCHA verification parameters

    The powCAPTCHA verification request body accepts the following parameters:

    • solution (string, Required): The solution token received from the powCAPTCHA widget on the frontend.
    • secret (string, Required): Your application’s private key. This must be kept secret and never exposed on the frontend.
    • spamFilter (object, Optional): Used for advanced filtering (requires a paid plan). Contains:
      • text (string, Optional): Text content to check for spam.
      • email (string, Optional): Email address to check for spam.