Integrate hCaptcha drag-and-drop recognition
Preserve movable entity identities, source geometry, and image keys in drag-and-drop jobs, then interpret placement results without losing their mapping.
Preserve entities as well as images
Drag-and-drop recognition needs more than a screenshot. The challenge structure identifies the background image and the movable entities. Each entity includes an identifier, image input, size, and coordinates. Both the background datapoint_uri and each entity_uri must contain base64 image/video data URIs; remote URLs are rejected. Download and encode the original media in your integration before submitting it. The request family is image_drag_drop inside an outer hcaptcha_recognition task.
Flattening the whole challenge into one image loses the relationship between movable pieces and their identities. Preserve that relationship when constructing your application’s request and when applying the returned placements.
Keep a clear mapping record
| Input information | Why the application needs it |
|---|---|
Image task_key |
Associates an answer with its background |
Entity entity_id |
Identifies the movable object |
| Entity image input | Provides the object being placed |
| Size and coordinates | Preserve source geometry |
| Original question | States the requested relationship |
Use the full schema in the API reference rather than a hand-built object that only includes the fields shown in this table. Validate required arrays and supported image inputs before paid submission.
Interpret placement results explicitly
Completed drag results contain placement data keyed by image task. entity_name and entity_coords must remain associated with the original movable object. Do not select an entity by whichever array position happens to match a returned result.
The application also needs a consistent coordinate mapping into the displayed challenge. Different image scaling or browser offsets can move every placement. Test geometry with local fixtures before drawing conclusions about model performance from a live rejection.
Separate transport, recognition, and interaction failures
Record whether creation was accepted, whether the job completed, whether placements were applied correctly, and whether the integration accepted the result. A drag event that did not reach the intended target is different from a transport failure or an incorrect recognized placement.
Each drag/background image is a recognition group for billing. Retain the job ID and send feedback after the observed outcome is known. The area-selection guide discusses coordinate mapping, while coordinate-transform debugging helps isolate repeated UI application errors.