Configuration
There are two ways you can configure the behavior of the widget.
- You can use HTML attributes (such as
data-start
). This is the method you usually use if you installed the widget to your website by adding a<script>
tag. - Alternatively, you can use the Javascript SDK and create widgets programmatically.
To respond to changes in the widget such as the captcha being completed, please see the events page.
HTML Attributes
data-sitekey
attribute
This field is how you specify the sitekey for a given widget.
Example:
<div class="frc-captcha" data-sitekey="<my sitekey>"></div>
data-start
attribute
You can specify when the widget should start solving a puzzle, you can specify the data-start
attribute with one of the following values:
auto
: the solver will start as soon as possible. This is recommended if the user will definitely be submitting the CAPTCHA solution (e.g. there is only one form on the page), this offers the best user experience.focus
: as soon as the form containing the widget fires thefocusin
event the solver starts, or when the user presses the start button in the widget. This is recommended for webpages where only few users will actually submit the form. This is the default.none
: the solver only starts when the user presses the button or it is programatically started by callingstart()
.
Example:
<div class="frc-captcha" data-sitekey="<my sitekey>" data-start="auto"></div>
One possible source of confusion lies in the distinction between a widget solving and completing. The data-start
attribute (or startMode
option for the JavaScript SDK) controls when the widget can start solving puzzles.
However, a widget will not reach its completed state until the user clicks it. At that point, the CAPTCHA response will be available. With a start mode of auto
or focus
, the challenges start solving in the background. By the time the user clicks, the CAPTCHA often completes instantly. There will never be tasks like clicking images of traffic lights. A single click is the only required interaction.
data-form-field-name
By default a hidden form field with name frc-captcha-response
is created. You can change the name of this field by setting this attribute, which can be useful for integrations with certain frameworks and content management systems.
Example:
<div class="frc-captcha" data-sitekey="<my sitekey>" data-form-field-name="my-captcha-solution-field"></div>
data-api-endpoint
Only relevant if you are using our dedicated EU endpoint service.
By default the widget fetches puzzles from https://global.frcapi.com/api/v2/captcha
, which serves puzzles globally. As a premium service we offer an alternative endpoint that serves requests from datacenters in Germany only. You can either specify a URL, "eu"
or "global"
.
Example:
<!-- Use the dedicated EU endpoint -->
<div class="frc-captcha" data-sitekey="<my sitekey>" data-api-endpoint="eu"></div>
data-theme
You can match the style of the widget to your website. By default the theme of the widget is light.
"light"
: A light theme (default)."dark"
: A dark "night mode" theme."auto"
: Match the user's operating system or browser preference settings.
Example:
<!-- Renders a dark widget -->
<div class="frc-captcha" data-sitekey="<my sitekey>" data-theme="dark"></div>
lang
attribute
You can use this to force a specific language.
We recommend you only use this if you have to. The widget automatically detects and matches the language of your website.
Example:
<!-- This will force a widget with German text -->
<div class="frc-captcha" data-sitekey="<my sitekey>" lang="de"></div>
Javascript SDK
See the CreateWidgetOptions for the settings you can pass when creating a widget using sdk.createWidget()
.