Vanilla HTML Configuration

Customize thresholds, feedback display, and event handling for your forms. For the full configuration reference covering all options, thresholds, proxy mode, and advanced settings, see the Configuration Reference.

Data Attributes Reference

The simplest way to configure Babel Shield -- add data attributes to the script tag:


<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN"
        data-feedback-mode="modal"
        data-blocked-message="Please revise your message."
        data-debug="true"></script>
Attribute Default Description
data-api-token (required) Your Babel Shield API token
data-feedback-mode inline Feedback display: inline, modal, or silent
data-feedback-container (auto) CSS selector for a custom feedback container
data-blocked-message (default) Custom message shown when content is blocked
data-debug false Enable console debug logging
data-fail-open true Allow form submission if the API is unavailable
data-api-url (production) Custom API endpoint URL

Security: data-api-url controls where form data is sent. Only use this on pages you fully control.

For more advanced configuration (custom thresholds, per-category messages, event handlers), use BabelShield.init() as shown in the sections below.

Thresholds

Thresholds control how sensitive each moderation category is. Set a value between 0 and 100 for any category -- content scoring at or above that threshold is flagged.

BabelShield.init({
  apiToken: 'YOUR_API_TOKEN',
  thresholds: { // Custom overrides
    spam: 80,
    profanity: 60,
    hate: 30,
    harassment: 75
  }
});

Categories you do not specify use the defaults. See the default thresholds in the Configuration Reference.

Note: Scores are 0-100 integers. A threshold of 50 means "flag content scoring 50 or above." Lower thresholds are more strict.

Feedback Modes

Three feedback modes control how blocked submissions are displayed.

Inline (Default)

A message appears near the form when content is blocked. This is the default -- no configuration needed.


<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN"
        data-feedback-mode="inline"></script>

Modal

A dialog overlay appears with the blocked message.


<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN"
        data-feedback-mode="modal"></script>

Silent

No visible feedback. The form submission is blocked, but no message is shown. Use this with custom event handlers or the onBlocked callback to build your own UI.


<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN"
        data-feedback-mode="silent"></script>

To handle blocked submissions yourself, use BabelShield.init() with a callback:

BabelShield.init({
  apiToken: 'YOUR_API_TOKEN',
  feedback: {
    mode: 'silent',
    onBlocked: (result, form) => {
      // Build your own UI here
      console.log('Blocked:', result.maxCategory);
    }
  }
});

Custom Messages

Override the default blocked message with per-category messages. The default message is used for any category without a specific message.

BabelShield.init({
  apiToken: 'YOUR_API_TOKEN',
  feedback: {
    mode: 'inline',
    messages: {
      spam: 'This looks like spam. Please revise your message.',
      profanity: 'Please remove inappropriate language.',
      hate: 'Hate speech is not allowed.',
      default: 'Your submission was blocked by our content filter.'
    }
  }
});

Category Selection

By default, all 13 moderation categories are checked. To limit moderation to specific categories, pass a categories array:

BabelShield.init({
  apiToken: 'YOUR_API_TOKEN',
  categories: ['spam', 'profanity', 'hate']
});

Only the listed categories are sent to the API, which scopes the server-side flagging decision to that set. The API still returns scores for all 13 categories -- the filter narrows flagging, not the returned scores.

Debug Mode

Enable debug logging to see every request, cache hit, and moderation result in the browser console.

Via data attribute:


<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN"
        data-debug="true"></script>

Or via BabelShield.init():

BabelShield.init({
  apiToken: 'YOUR_API_TOKEN',
  debug: true
});

Debug output appears in the browser console with the [BabelShield] prefix.

Fail-Open Behavior

By default, failOpen is true. If the Babel Shield API is unavailable or returns an error, forms submit normally so users are never blocked by a service outage.

To block form submissions when the API cannot be reached, set failOpen to false:


<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN"
        data-fail-open="false"></script>

Or via BabelShield.init():

BabelShield.init({
  apiToken: 'YOUR_API_TOKEN',
  failOpen: false
});

Event Listeners

Babel Shield fires events you can listen to for custom behavior. The three most common events:

ready -- Fires once when initialization is complete and forms are protected.

BabelShield.once('ready', () => {
  console.log('Babel Shield is active');
});

form:blocked -- Fires when a form submission is blocked by moderation.

BabelShield.on('form:blocked', ({form, result, category}) => {
  console.log('Form blocked:', form.id);
  console.log('Reason:', category, '(score:', result.maxScore + ')');
});

form:approved -- Fires when a form submission passes moderation and is allowed to proceed.

BabelShield.on('form:approved', ({form, result}) => {
  console.log('Form approved:', form.id);
});

For the complete event reference -- including form:detected, form:submit, form:validated, api:error, and api:response -- see Form Handler (Advanced).

Next Steps