SpamBlock Integration Guide for WordPress Themes

Overview

You can deliver the SpamBlock pixel to any WordPress theme without changing your form plugins. The script runs in the browser, intercepts submissions, and relays only legitimate requests to your existing handlers.

This guide covers:

• Installing the pixel globally (recommended)
• Protecting Contact Form 7, Gravity Forms, WPForms, and native comment forms
• Optional configuration flags and debugging tips

1. Install the pixel

Option A – functions.php (themes & child themes)

Add the following snippet to your theme’s functions.php file or a site-specific plugin:

function spamblock_enqueue_pixel() {
  wp_enqueue_script(
    'spamblock-pixel',
    'https://api.spamblock.io/sdk/pixel/v1.js',
    array(),
    null,
    true
  );
  // Optional: Add configuration attributes
  // See /docs/ for all available options
  wp_script_add_data(
    'spamblock-pixel',
    'data',
    array(
      // 'data-max-score' => '60',
      // 'data-debug' => 'false',
      // Add other configuration options as needed
    )
  );
}
add_action('wp_enqueue_scripts', 'spamblock_enqueue_pixel');

Many themes do not support wp_script_add_data. If your theme is one of them, fall back to Option B.

Option B – header injection plugin

1. Install “Code Snippets” or “Insert Headers and Footers.”
2. Paste the script into the header area:

<script
  src="https://api.spamblock.io/sdk/pixel/v1.js" defer>
</script>

Optional: Add data-* attributes for configuration. See the configuration reference for all available options.

Save changes—the script will load on every page.

2. Protect your forms

Contact Form 7

Add data-block-spam to each [contact-form-7] shortcode:

[contact-form-7 id="123" html_class="spam-form" data-block-spam]

Alternatively, wrap the generated HTML form with a custom hook and add the attribute manually.

Gravity Forms

Edit the form settings and add data-block-spam inside the “Form CSS Class” field:

spamblock-protect

Then use a snippet to translate that class into the attribute:

add_filter('gform_form_tag', function($form_tag, $form) {
  if (strpos($form_tag, 'spamblock-protect') !== false) {
    $form_tag = str_replace('spamblock-protect', 'spamblock-protect" data-block-spam="true', $form_tag);
  }
  return $form_tag;
}, 10, 2);

WPForms

Go to Settings → General → Advanced and add data-block-spam to the “Form markup” field using the provided filter hook:

add_filter('wpforms_frontend_form_atts', function($atts) {
  $atts['data-block-spam'] = 'true';
  return $atts;
});

Native WordPress comments

Hook into comment_form_defaults:

add_filter('comment_form_defaults', function($defaults) {
  $defaults['form'] = str_replace('<form', '<form data-block-spam="true"', $defaults['form']);
  return $defaults;
});

3. Domain Verification

When you add a domain in your SpamBlock account, you'll receive a verification token. Include this token in your script tag using the data-verify-token attribute:

function spamblock_enqueue_pixel() {
  wp_enqueue_script(
    'spamblock-pixel',
    'https://api.spamblock.io/sdk/pixel/v1.js',
    array(),
    null,
    true
  );
  // Add verification token for domain verification
  wp_script_add_data(
    'spamblock-pixel',
    'data',
    array(
      'data-verify-token' => 'your-verification-token',
      // Add other configuration options as needed
    )
  );
}
add_action('wp_enqueue_scripts', 'spamblock_enqueue_pixel');

Or if using a header injection plugin:

<script
  src="https://api.spamblock.io/sdk/pixel/v1.js"
  data-verify-token="your-verification-token"
  defer>
</script>

Automatic Verification: Domains are automatically verified on the first form submission that includes the matching verification token. You don't need to manually verify domains - just add the script with your token and submit a form. The domain will be verified automatically, and you'll be able to access analytics and webhooks for that domain.

4. Configuration

All configuration options are set via data-* attributes on the script tag (or in the array passed to wp_script_add_data). See the complete configuration reference for all available options, defaults, and detailed explanations.

5. Testing

1. In the browser console, ensure the script is present (document.currentScript.src contains spamblock).
2. Submit a test with a disposable email (e.g., qa@mailinator.com).
3. Enable debug mode by temporarily adding data-debug="true" and watch the console output.
4. See the documentation for more testing tips.

Troubleshooting

Symptom	Fix
Form not protected	Verify the <form> element either has data-block-spam or there are no competing scripts removing it.
Legitimate submissions blocked	Adjust data-max-score or inspect console logs (with data-debug="true") for the reasons array. See configuration options.
Conflict with caching/CDN	Ensure the pixel is not being stripped by optimization plugins; whitelist the script URL if needed.

For more troubleshooting tips and configuration options, see the documentation.