Quickstart: plain HTML forms

Time needed: about 10 minutes. Use this for your own survey pages, or for any platform that lets you add a script and hidden form fields.

1. Load the collector

<script src="https://cdn.jsdelivr.net/npm/@lydite/collector@VERSION/dist/lydite.generic.min.js"
        integrity="sha384-HASH" crossorigin="anonymous"></script>

Replace VERSION and HASH with the values on the release page, or host the file yourself. With a bundler, run npm install @lydite/collector and import { init, generic } from '@lydite/collector'.

2. Add hidden fields and bind them

Add one hidden input per monitored answer, plus one for the session:

<form method="post" action="/submit">
  <label for="q1"><span id="q1-text">What did you do last weekend?</span></label>
  <textarea id="q1" name="q1"></textarea>
  <input type="hidden" id="lyd_q1" name="lyd_q1">
  <input type="hidden" id="lyd_s" name="lyd_s">
  <button>Submit</button>
</form>

<script>
  Lydite.init({ platform: 'generic', secret: 'replace-with-a-long-random-string' });
  Lydite.generic.bindHidden('#q1', '#lyd_q1', { fieldId: 'q1', canaryTarget: '#q1-text' }, '#lyd_s');
</script>

bindHidden(field, hidden, options, sessionHidden) fills the hidden inputs when the answer loses focus and again when the form is submitted.

Option	Purpose
fieldId	Name of the answer column in your data. The payload carries this name, and the analyzer uses it to find the answer text for the decoy-word check. The hidden column itself can be called anything.
canaryTarget	Element that receives the hidden copy-trap instruction, usually the question text. Leave it out to skip the trap for this field.

init option	Purpose
secret	Optional seed for choosing decoy words; random per session if omitted. It is visible in the page source, so it is not a password.
respondentKey	Optional per-respondent key, such as a panel ID. Defaults to a random session value.
canary	false turns traps off; an object configures them (see Methodology).
debug	true logs a summary to the browser console while piloting. It never changes behavior.

For forms submitted with JavaScript instead of a normal submit, call handle.flush() (the return value of bindHidden) and Lydite.flushSession() yourself and send the strings along with the answers.

3. Store and analyze

Save the hidden values next to the answers, one row per respondent, with an id column (for example ResponseId, participant_id or subject). A CSV with columns id, q1, lyd_q1 and lyd_s is enough. The analyzer finds payload columns by their content, so they can have any name. Then use the offline page, R, Python or the command line. If an answer is stored under a different column name than its fieldId, map it explicitly (for example --map q1=answer_text).

A working page is in examples/generic/index.html.