Overview
This guide walks you through setting up yCAPTCHA to embed custom image-based challenges on your site.
This guide will get you started on embedding the yCAPTCHA widget and verifying its tokens server-side. yCAPTCHA is a community-puzzle widget, not a bot-detection service — see the FAQ if you haven't already.
Prerequisites
Before you begin, you must have:
- A yCAPTCHA account
- A website or web application where you want to add the widget
- Basic knowledge of HTML and your preferred server-side language
Process
yCAPTCHA widgets are the user-facing challenge that runs on your page. Each site gets its own unique key pair and puzzle configuration.
| Component | Description |
|---|---|
| Site Key | Public key (pk_...) used to invoke the widget on your site. |
| Secret Key | Private key (sk_...) used for server-side token validation. |
| Puzzle | Image challenge with configurable correct answers and difficulty. |
Regardless of how you create your site and puzzles, you will still need to embed the widget on your webpage and validate the token on your server.
Implementing yCAPTCHA involves two essential components:
- Client-side: Embed the widget — Add the yCAPTCHA iframe to your webpage to challenge visitors and generate verification tokens.
- Server-side: Validate the token — Verify the tokens on your server using the Siteverify API to ensure they are authentic.
Implementation
Follow the steps below to implement yCAPTCHA.
1. Create your site and puzzle
First, create a site and configure at least one puzzle to get your keys.
Refer to Create a Site for step-by-step instructions on creating sites, uploading images, and configuring puzzles.
2. Embed the widget
Add the yCAPTCHA widget iframe to your webpage and listen for verification tokens via postMessage.
Refer to Embed the Widget to learn about embedding, resize handling, and event listening.
3. Validate tokens
Implement server-side validation to verify the tokens generated by the widget.
Refer to Server-side Validation to secure your implementation with proper token verification.
Security requirements
- Server-side validation is mandatory. You must call the Siteverify API to verify every token. Not verifying leaves your implementation vulnerable.
- Tokens expire after 5 minutes. Each token can only be validated once. Expired or used tokens must be replaced with fresh challenges.
- Protect your Secret Key. Never expose your
sk_...key in client-side code.