Embedding Forms
You can embed a TrolleyShield custom form on any website using a script snippet or an iframe. The embed includes full behavioral tracking, AI analysis, and attribution capture.
Script Embed (Recommended)
The script embed renders the form directly in your page with behavioral tracking built in.
Setup
- Go to Forms in your TrolleyShield dashboard
- Click on the form you want to embed
- Copy the embed snippet
The snippet looks like this:
<div id="trolley-form-abc123"></div>
<script src="https://app.trolleyshield.com/custom-form.js"
data-form-id="abc123"
data-api-key="tsk_your_api_key"
async>
</script>
- Paste it into your website's HTML where you want the form to appear
How It Works
When the page loads, the script:
- Fetches the form configuration from TrolleyShield
- Renders the form inside the
<div>container - Attaches behavioral tracking (keystrokes, mouse movement, timing)
- On submit, sends form data + behavioral score + attribution to the API
- Displays a success message, redirects, or shows a block notice
Styling the Embed
The embed uses the styling settings you configured in the form builder. If you need full control over the form's appearance:
- Enable No Style Mode in the form builder's styling settings
- The form will render with only CSS class names (no inline styles)
- Target these classes in your stylesheet:
/* Form wrapper */
.ts-form { }
/* Form title */
.ts-form-title { }
/* Field wrapper */
.ts-form-field { }
/* Labels */
.ts-form-label { }
/* All inputs */
.ts-form-input { }
/* Specific input types */
.ts-form-textarea { }
.ts-form-select { }
.ts-form-checkbox { }
.ts-form-checkbox-label { }
/* Submit button wrapper and button */
.ts-form-submit-wrapper { }
.ts-form-submit { }
/* Success and error states */
.ts-form-success { }
.ts-form-error { }
Iframe Embed
If you prefer to embed the hosted page directly:
<iframe
src="https://app.trolleyshield.com/f/your-form-slug"
width="100%"
height="600"
frameborder="0"
style="border: none;">
</iframe>
The script embed is preferred over iframe because it integrates more naturally with your page layout, supports full CSS customization, and doesn't have cross-origin restrictions on redirect success actions.
Attribution Tracking
Both embed methods automatically capture attribution data from the URL where the form is displayed:
| Parameter | Source | Example |
|---|---|---|
page_url | Current page URL | https://yoursite.com/landing?utm_source=google |
referrer | HTTP referrer | https://google.com |
utm_source | URL parameter | google |
utm_medium | URL parameter | cpc |
utm_campaign | URL parameter | spring-sale |
utm_term | URL parameter | roof repair |
utm_content | URL parameter | ad-variant-a |
gclid | URL parameter | Google Ads click ID |
gbraid | URL parameter | Google Ads app click ID |
wbraid | URL parameter | Google Ads web-to-app click ID |
This data appears in the Source Attribution card when you expand a submission in the Submissions table.
Google Ads Integration
If your landing page URL contains a gclid parameter (auto-appended by Google Ads), the form will automatically capture it. This enables:
- Seeing which Google Ads campaigns and keywords drive form leads
- Matching form submissions back to specific ad clicks
- Attribution data visible in the Submissions dashboard
No additional configuration is required — attribution capture is always on.
Behavioral Tracking
The embed script automatically tracks visitor behavior to detect bots and spam:
- Typing patterns — keystroke timing, backspace frequency, paste detection
- Mouse activity — movement count and patterns within the form
- Time on page — how long the visitor spends before submitting
- Field interaction — focus/blur events, field navigation order
- Tab-away detection — whether the visitor switches browser tabs
This generates a behavioral score (0-100) that's combined with AI analysis for more accurate classification. No configuration needed — it runs automatically.
Failsafe Behavior
If the TrolleyShield API is unreachable when the form is submitted, the form fails open — it shows the success message or redirects as if the submission was accepted. This prevents legitimate users from being blocked by an API outage.