Widget modes

A widget's mode decides how much of the check a visitor sees. You choose it when you add the widget, and you can change it later. The page does not set it, so one page can show widgets of all three modes by using three site keys. A second setting, the appearance, decides when the widget's frame is on the page at all, and works with every mode.

Every mode runs the same check. The visitor's browser does a small calculation, called the proof of work, and answers a few questions about itself, such as whether a script is driving it. Wicket scores the answer, and the score decides what happens next:

• A clear pass gives the token at once. Most visitors see nothing more than a moment of Checking your browser… and then Success.
• A score in the middle costs the visitor a little: a click, or more work. The modes differ in which.
• Only near-certain evidence fails a check. Wicket never refuses a visitor on a guess, and ticking the box with a keyboard or a screen reader never counts against a visitor.

Every token is bound to the widget and to your page's hostname, works once, and expires after 300 seconds.

A Managed widget starts the check at once and shows Checking your browser…. Then one of three things happens:

• The visitor passes, and the widget shows Success.
• Wicket is unsure, and the widget asks Confirm you are a person with a box. The visitor ticks it once. When the answer is still unclear, the widget does one more round of work at a harder level, and then fails the check.
• Wicket is nearly certain the visitor is a script, and the widget shows We could not check this browser with a Try again button.

The box is a real checkbox. A visitor can tick it with a pointer, a finger, Space or a screen reader. A box that waits for 120 seconds shows Time ran out, and the widget starts again by itself unless refresh-timeout says otherwise.

A Non-interactive widget shows the same short check and never a box. When Wicket is unsure, the widget gives the visitor's browser more to calculate instead of asking for a click: up to two more rounds, each harder than the one before. The visitor sees Checking your browser… for a little longer, and then Success.

A visitor Wicket stays nearly certain about gets We could not check this browser with a Try again button, as in Managed.

An Invisible widget draws nothing and takes no room on the page once its frame has loaded. It checks as a Non-interactive widget does: no box, and up to two harder rounds when Wicket is unsure.

Because the visitor sees nothing, your page decides what to show. The widget gives your code a token through callback, and a failed check through error-callback, with the code failed. Show your own message there, and let the visitor try again by calling wicket.reset().

An Invisible widget usually starts when your code asks it to: set data-execution="execute" and call wicket.execute() when the visitor submits. Add Wicket to your site shows how to mark an Invisible widget so the page does not move when it loads.

appearance decides when the frame is on the page, and execution decides when the check starts. Both are options of the widget's container or of wicket.render (Widget options), whatever the mode.

A frame that is not on the page is out of sight and out of the accessibility tree: it takes no room, and a screen reader does not announce it. An Invisible widget is never on the page, whatever its appearance.

A token works for 300 seconds. When they pass, the script empties the hidden field and calls expired-callback. Then refresh-expired decides what happens, and appearance decides whether the visitor sees it:

From the moment a token expires until the next check passes, wicket.getResponse() answers undefined and wicket.isExpired() answers true. With never, call wicket.reset() to start the next check yourself.

A box that nobody ticks is separate. The frame always comes onto the page for Time ran out, and refresh-timeout takes the same three words with the same effects.

• Choose Managed for most forms: sign-up, contact and comment forms. Most visitors never see a box, and the few who do tick it once.
• Choose Non-interactive where a box would be out of place, such as a checkout or a sign-in that must feel instant, and a visitor can wait a moment longer. It costs the visitor time, never a click.
• Choose Invisible when the check runs behind your own button or inside an app that shows its own messages. Your page handles a failed check, because the visitor sees nothing from Wicket.

All three modes run the same check and score it the same way. The mode decides only what Wicket asks of a visitor it is unsure about.

Your server can tell which visitors ticked a box: the verify answer's metadata.interactive is true for them (Verify a token on your server).

The test keys give a widget of each kind without a real widget: a visible one that passes, a visible one that fails, an invisible one that passes and one that fails, and one that shows the box and then passes.

• Add a widget and choose its mode.
• Change a widget's settings to switch the mode of a widget you have.
• Add Wicket to your site to mark an Invisible widget so the page does not move.
• Widget options for appearance, execution and the callbacks.