Add a game from the marketplace

BananaSeed's contact form already has a working widget from the previous lesson. In this last lesson we replace the plain checkbox with a real, playable game that every visitor has to clear.

Why bother, when the checkbox already works? The checkbox is the quiet minimum. A game turns the unavoidable "prove you are human" moment into something a visitor enjoys instead of endures, and it is the part that holds up against sophisticated attackers. Today's AI can tick a checkbox and solve image grids, but a real game is the one challenge it cannot cheat, because no machine plays the way a human does. 💪

This lesson is a little more involved than dropping in the widget was: you pick a game, install it on your site key, and turn on the gate that requires it. The payoff is that the game becomes the actual thing standing between a bot and your form, not decoration you can skip past. The token mechanics underneath are identical, so your backend does not change at all. Everything here works on the free plan.

What you will have at the end

• A game from the marketplace installed on your site key.
• That game required for verification, so a bare checkbox can no longer pass.
• The same contact form, now guarded by the game, with your backend check unchanged.

1. Pick a game from the marketplace

The marketplace is the public catalog you choose from. Open it and browse: filter by category, or by what a game supports (touch, keyboard, screen readers, sound), so you can match a game to your audience. Each game has its own page with a preview and an id like caputchin/games/leaf-memory.

Browsing is open, with no approval queue: every game in the catalog is available to use. Pick one and copy its id. We will use Leaf Memory (caputchin/games/leaf-memory) for the rest of this lesson.

2. Install the game on your site key

Before a game can guard a key, you install it on that key. Installing tells Caputchin to take a pinned, verified snapshot of the game, so the exact version your visitors play is the one Caputchin can re-run when it checks a result later.

In the dashboard, open your troop, open your site key, and go to its Games page. In the Add a game panel, search for the game in the Marketplace game box and select it from the list (or click Open).

Caputchin registers the game, takes its snapshot, and drops you on the game's settings page. The game now appears under Registered games back on the Games page, ready to guard the key. Almost every marketplace game is ready as soon as you register it, the first-party ones always; if a rare game shows a Not replayable badge here, it cannot gate until the author ships a replayable build.

You can add more than one game. Add them on a single site key, or add them once on the troop to share the same set across every key in it.

Your site key now has a game installed and verified. Next we make it required. 🎉

3. Require a game to verify

Installing a game makes it available; it does not yet force anyone to play it. The gate does that.

On your site key, open its Security page and turn on Require a game to verify. From now on, every visitor to this key must play one of its installed games to pass, and clearing a bare checkbox is no longer enough. (You cannot turn the gate on until at least one game is installed, which is why step 2 comes first.)

With the gate on, Caputchin chooses which installed game each visitor gets and hands it out through a one-time, signed ticket. A visitor, or a bot, cannot pick the game, skip it, or swap it for an easier one: the choice is made on Caputchin's side, fresh for every session. That is what turns the game from a nicety into real protection.

Managing a whole set of keys? A troop has its own Security page with Require a game on every site key, which turns the gate on across every key in the troop at once.

4. Swap the element

Now the page. Games render on a different element, <caputchin-game>. The import "@caputchin/widget" you already added registers it too, so there is nothing new to install. Because the key now requires a game, the checkbox-only <caputchin-widget> can no longer pass on it, so this swap is the last required step.

In your contact form, change the one line:

// before
<caputchin-widget sitekey="cpt_pub_..." />

// after
<caputchin-game sitekey="cpt_pub_..." />

You do not pass a game id. Because the key requires a game, Caputchin serves one of your installed games and picks it per visit. If you would rather pin a specific one, or limit the rotation to a subset, name them (each must be installed on the key):

// always Leaf Memory
<caputchin-game sitekey="cpt_pub_..." game="caputchin/games/leaf-memory" />

// a random one of these two per visit
<caputchin-game
  sitekey="cpt_pub_..."
  games="caputchin/games/leaf-memory,caputchin/games/dino-runner"
/>

Naming a game that is not installed on the key will not load it: the widget reports that the gate has no such game rather than letting the visitor through.

5. Try it

Reload your app. The checkbox is gone: the visitor now plays the game in a sandboxed iframe. When they win, the widget adds the same hidden caputchin-token field to the form, so your FormData read and your backend /siteverify check are both unchanged from the previous lesson.

Open your site key's statistics and you will see sessions flowing through the same funnel as before. You can filter the whole view to a single game to compare one against another.

BananaSeed's contact form is now guarded by a real, playable game that every visitor must clear, and every submission is still verified on your server. You shipped it. 🎉

You went from an empty account to a verified, game-guarded form.

What just happened

What is next

These are the areas you will most likely reach for from here:

• Customize the games: set the language, skin, and difficulty of your games.
• Security: the game gate, proof-of-work difficulty, origins, and the rest of a key's protection.
• Statistics and sessions: read the funnel and compare one game against another.
• Account management: sign-in, access tokens, billing, and seats.
• Troops: organize your site keys and, on a paid plan, invite your team.