Start with one application action
A bot detection API becomes easier to evaluate when it assesses an action the application understands: submitting a contact form, creating an account or spending a credit. Page views alone cannot tell you whether that business action was legitimate. Choose one action, keep its normal validation and authentication, and decide which later evidence could establish its outcome.
Blokk's generic integration follows that model. A customer's backend requests an assessment and remains responsible for the business action. The browser can supply limited observations, but it never receives the site API key and cannot choose the server's integration mode or policy.
Choose the evidence binding deliberately
In bound mode, the backend prepares an attempt for its configured site, action, origin and session. Optional browser collection returns a receipt. On submission, the backend sends the attempt and receipt for assessment. This checks how the submission relates to a prepared attempt; it does not certify the visitor's identity or intentions.
Submit-only mode removes the preparation call for explicitly permitted actions. The backend can relay an optional browser snapshot, but it is unbound and could be fabricated or replayed. Use the mode because its trade-off fits the application, and keep the weaker binding visible when interpreting the result. Never let a submitted form field select it.
Make retries part of the design
Networks retry, users double-click and responses get lost. Give the business submission its own stable identity and use a server-generated idempotency key for the assessment. Blokk returns the stored result for an exact assessment retry; changed input under the same key is a conflict. This protects the assessment record, but it does not replace application-level prevention of duplicate business actions.
Test the retry path with the exact same input, then deliberately change the input under the same key in your local environment. Verify both responses and confirm that your application does not create a second form submission, account or charge merely because the assessment request was retried.
Keep missing evidence and outages distinct
A missing browser receipt, an invalid integration request and an unavailable detector are different conditions. A usable assessment can report limited evidence or an integrity problem. Those states do not establish automation. A credential or configuration error needs an integration fix. A timeout or service failure needs the application's explicitly chosen unavailable policy.
Start in shadow mode, where the application's action continues while the assessment is recorded. Exercise missing JavaScript, an expired attempt and a controlled API outage locally. Confirm that the application preserves the visitor's submitted work and records an unassessed action during downtime rather than inventing a detection result.
Close the loop with reviewed outcomes
After the team establishes what an action turned out to be, report the outcome separately. Blokk uses legitimate, confirmed_unwanted and unresolved. The report also records the basis of the judgement and any action taken. For example, restricting an account pending review can coexist with an unresolved outcome; the restriction itself does not prove abuse.
A later correction creates a new report with a new key and determination time. It preserves the earlier assessment instead of rewriting the original detection result. Report within the configured retention window and check which outcome is current, especially when an earlier determination arrives late. A useful review needs both the original evidence and the decision history.
Evaluate the whole loop before changing policy
Use local, labelled scenarios to verify the protocol and review workflow. Include an ordinary submission, authorised automation, missing browser evidence, exact retries, a controlled outage and an outcome correction. Scripted scenarios establish behaviour under those conditions; they do not measure performance on genuine customer traffic.
The generic API and SDK workflow is distinct from the guided Shopify adapter workflow. Shopify installation creates its own store-scoped setup, and browser observations do not automatically provide the same server context as a custom application. Blokk remains a research alpha: agree the action, available evidence and review decision before treating an assessment as a reason to enforce a rule.