Skip to main content
Version: 1.0.0

Configuration

ARCaptcha Container Configuration

The only way to configure ARCaptcha is to set custom attributes on the ARCaptcha container <div>. You're already required to do this with data-site-key, but there are a handful of other optional attributes that enable more customization.

AttributeRender optionValueDescription
data-site-keysite_key<your site key>Required. Your public API site key.
data-sizesizenormal | inivisibleOptional. Set the size of the widget. Defaults to normal.
data-themethemelight | darkOptional. Set the theme of widget. Defualts to light
data-colorcolorcolor name or hex codeOptional. Set color of every colored element in widget.
data-error-printerror_print0 | 1Optional. Disable or enable error messages at the bottom of checkbox. Defaults to 0(enabled)
data-langlangen | faOptional. Set language of widget . Defaults to fa
data-callbackcallback<function name>Optional. Called when the user submits a successful response. The arcaptcha-token token is passed to your callback.
data-rendered-callbackrendered_callback<function name>Optional. This function would be called after rendering captcha
data-error-callbackerror_callback<function name>Optional. This function would be called after error
data-reset-callbackreset_callback<function name>Optional. This function would be called after reseting captcha
data-expired-callbackexpired_callback<function name>Optional. This function would be called after expiring
data-chlexpired-callbackchlexpired_callback<function name>Optional. This function would be called after challange expiration
data-blocked-callbackblocked_callback<function name>Optional. This function would be called after user is detected as bot and blocked by our system

Besides the required data-site-key, you can add as many or as few configuration attributes as you want.

<div
class="arcaptcha"
data-site-key="your_site_key"
data-callback="onSubmit"
></div>

All of the above attributes can also be used as param arguments when explicitly rendering with arcaptcha.render() (described in the next section). In that case, the param name is as shown above, but without the data prefix. For example, the param argument for data-site-key is just site_key

<script type="text/javascript">
arcaptcha.render("captcha-1", {
site_key: "your_site_key",
});
</script>

JavaScript API

The ARCaptcha API exposes the ARCaptcha object that has methods you may find useful in customizing ARCaptcha behavior.

arcaptcha.render(container, params)

Renders the ARCaptcha widget inside the container DOM element. Returns a unique widgetID for the widget.

  • container The string ID of the container or the container DOM element.
  • params An object containing config parameters as key=value pairs. Ex:
{
size: "invisible",
site_key: "your_site_key"
}

arcaptcha.reset(widgetID)

Resets the ARCaptcha widget with widgetID.

  • widgetID Optional unique ID for a widget. Defaults to first widget created.

arcaptcha.getArcToken(widgetID)

Gets the challenge ID for the ARCaptcha widget with widgetID.

  • widgetID Optional unique ID for a widget. Defaults to first widget created.

arcaptcha.execute(widgetID)

Triggers the ARCaptcha workflow programmatically. Generally used in invisible mode where the target container is a div rather than a button. Returns a promise that will be resolved after user solved the challenge and will be rejected after any error occuration or false solvation.

  • widgetID Optional unique ID for a widget. Defaults to first widget created.
arcaptcha
.execute()
.then(({ arcaptcha_token }) => {
console.log(arcaptcha_token);
})
.catch((err) => {
console.error(err);
});

Explicitly Render ARCaptcha

In the default implementation, ARCaptcha widgets will be automatically rendered and inserted into your webpage. However, you can also defer rendering by specifying a custom onload callback function in which you render the widget yourself.

To specify a custom onload callback function, you must pass the function name as an attribute into ARCaptcha container or as a parameter into render function.

You can then call arcaptcha.render with the container selector(id or class) or HTMLElement and your site key to explicitly render the widget.

<script type="text/javascript">
var yourFunction = function () {
console.log("ARCaptcha is ready.");
var widgetID = arcaptcha.render("captcha-1", {
site_key: "your_site_key",
});
};
</script>

Error handling(Client Side)

By setting data-error-callback on ARCaptcha widget you can access different types of errors may be happened on the client side.

<div
class="arcaptcha"
data-site-key="your_site_key"
data-error-callback="onError"
></div>

<script>
function onError({ code, message }) {
console.log(code, "-", message); // '201-answer-server-error:500-Server error'
}
</script>

We categorized errors by codes like HTTP protocol:

  • 1xx: Create phase errors
  • 2xx: Answer phase errors

In this table you can see all supported errors thrown by our widget:

CodeNameDescriptionMessage Example
101CREATE_SERVER_ERRORWhen there is an error in our server side in create phasecreate-server-error:404-Website not found
102CREATE_NETWORK_ERRORWhen client can't create connection to our servers in create phasecreate-network-error:Network is unreachable
201ANSWER_SERVER_ERRORWhen there is an error in our server side in answer phaseanswer-server-error:500-Server error
202ANSWER_NETWOR_ERRORWhen client can't create connection to our servers in answer phaseanswer-network-error:Network is unreachable
203ANSWER_WRONG_ERRORWhen client submits wrong answeranswer-wrong-error
401UNKNOWN_ERRORany unknown errorunknown-error

Integration Testing: Test Keys

If you intend to run automated integration tests that access a live server, the simplest approach is to use the following test ARCaptcha site keys that always generate a passcode without asking a question. Those passcodes can only be verified using the test secret.

caution

The test keys provide no anti-bot protection, so please double-check that you use them only in your test environment!

Test Key Set

Test parameterValue
site-key0000000000
secret-key00000000000000000000
arcaptcha-token000000000000000000000000000000