Install a widget

Installing a widget has two parts. A page shows the widget, and the widget puts a token in the form. Your server then sends the token to Wicket with your secret key before it accepts the form. The Install tab of the widget has the code for both, with your site key already in it.

• Add a widget first. Open it from Security, then Open Wicket, and select its Install tab.
• The hostname of the page that shows the widget must be one of the widget's hostnames (Change a widget's settings). A page on another hostname gets no challenge.
• Have the widget's secret key ready. The tab never shows it, because we show it once, when you add the widget and when you rotate it. If you do not have it, rotate the secret key.

1. Under Add the widget to your page, select the copy button on the HTML block.
2. Paste the <script> line once in the page. It loads the widget with async defer, so it does not hold the page up.
3. Paste the <div> with the class wicket-widget inside the form, where the check should appear. Its data-sitekey is the widget's site key.

For a Managed or Non-interactive widget the <div> carries style="min-height: 65px", or 140px when the widget's size is Compact. It keeps room for the widget so the page does not jump when it loads. For an Invisible widget the <div> carries data-appearance="interaction-only" and no min-height, so it takes no room on the page (Invisible widgets).

When your Content-Security-Policy forbids inline styles, move the min-height into a stylesheet and leave the style attribute off (Reserve the widget's height).

The widget fills a hidden field named wicket-response with a token when the visitor passes, and the browser sends it with the form like any other field.

Never trust the form on the strength of the widget alone, because a script can send a form without loading the widget. Your server asks Wicket whether the token is real.

1. Under Check the token on your server, choose your language: curl, Node, Python, PHP or Go.
2. Copy the code into the handler that receives the form. It reads the wicket-response field, sends it to the verify address with your secret key, and reads the answer.
3. Keep the secret key in an environment variable named WICKET_SECRET_KEY on your server, never in a page or a repository.
4. Refuse the form when the answer's success is false.

The answer is JSON. success is true or false, and when it is false the error-codes list says why (Error codes). A token works once and for 300 seconds. When a visitor takes longer, the widget gets a new one by itself.

Until your server makes this call, the widget's Analytics tab says Your server is not verifying tokens, and the list marks the widget as needing attention once at least 20 checks passed in 24 hours without one (Read a widget's analytics).

To draw the widget from your own script, use Or draw it with JavaScript instead of the HTML block. The script address ends in ?render=explicit&onload=onWicketLoad, and the callback you pass to wicket.render receives the token, for a page that builds its forms in JavaScript. The <div> carries the same min-height as the HTML block.

Add Wicket to your site covers explicit rendering, several widgets on one page and single-page apps, and Widget options lists every option the widget takes.

The Test keys card lists site keys and secret keys that work on any hostname, are never counted and never touch a widget of yours. Use them in development, and in automated tests that submit a form. Test keys says what each one does.

If your site sets a Content Security Policy, add the two lines under Content Security Policy to it. They allow the widget's script and the frame it draws. The tab shows the addresses your widget uses, so copy them from there (Allow Wicket in a Content Security Policy).

The Preview card draws the widget as a visitor sees it, with the test site key that passes, so you can look at it before your page has one. It loads the same script your page will. When a browser extension or a policy of your own blocks the script, the card says The preview could not load.

The page shows the widget, a visitor passes it, and your server's check answers success: true. The widget's Analytics tab then counts the challenge and the verified token.

The widget shows an error about the site key or the hostname

The browser's console names the cause. Either the site key is not a widget's, or the page's hostname is not one of the widget's hostnames. Add it on the Settings tab.

The verify call answers invalid-input-secret

The server sends a secret key that no widget has, or that you rotated with Stop the old key now. Put the current secret key in WICKET_SECRET_KEY.

The verify call answers invalid-input-response

The token is another widget's, or it is WICKET.DUMMY.TOKEN from a test site key. Use the widget's own site key on the page.

The verify call answers timeout-or-duplicate

The server verified the same token twice, or took more than 300 seconds. Verify once for each submission.

Troubleshoot Wicket lists what each message in the widget means.

• Add a widget
• Change a widget's settings
• Verify a token on your server
• Manage widgets with the API

• Read a widget's analytics to see that challenges and verified tokens arrive.
• Test keys to test a failing check and a spent token.
• Move from Cloudflare Turnstile to Wicket if the page uses Turnstile now.