Schnellstart

Das Prinzip

1. Der Browser lädt das Script von Antisy, ausgeliefert von api.antisy.com. Es zeigt dem Besucher nichts an.
2. Beim Absenden eines POST-Formulars an Ihre Website hält das Script die Übermittlung zurück, bis es ein Token hat, legt es in ein verstecktes Feld, antisy-token, und setzt die Übermittlung fort. Für diesen Fall schreiben Sie kein JavaScript.
3. Ihr Server empfängt das Formular mit dem Token. Er sendet es an POST /v1/siteverify, mit Ihrem Secret.
4. Die Antwort lautet allow oder deny: Der Besucher kommt durch oder nicht. Was danach geschieht, entscheiden Sie.

Der Browser spricht nie mit /v1/siteverify: Das ist eine Route für Ihren Server, die keinen CORS-Header sendet. Das Secret kommt nie in eine Seite.

Was Sie brauchen

• Eine Website, im Dashboard (auf Französisch) angelegt, mit den Hostnamen Ihrer Seiten (siehe Hostnamen).
• Ihren Site-Key (32 Zeichen): Er kommt in die Seite, er ist kein Geheimnis.
• Ein Verifizierungs-Secret (64 Zeichen): Es bleibt auf Ihrem Server, in einer Umgebungsvariable. Es wird nur einmal angezeigt, bei seiner Erstellung (Seite zu den Schlüsseln).
• Seiten, die über HTTPS ausgeliefert werden.

Ein vollständiges Beispiel

1. Die Seite

Das Script-Tag im <head> und ein gewöhnliches Formular: weder ein verstecktes Feld noch ein Script auf Ihrer Seite. Ersetzen Sie VOTRE_CLE_DE_SITE.

<script src="https://api.antisy.com/v1/i/l.js"
        data-site="VOTRE_CLE_DE_SITE" defer></script>

<form method="post" action="/contact">
  <input name="name" autocomplete="name">
  <input name="email" type="email" autocomplete="email">
  <textarea name="message"></textarea>
  <button>Envoyer</button>
</form>

Beim Absenden hält das Script von Antisy die Übermittlung zurück, bis es das Token hat (höchstens 6 Sekunden), legt das Feld antisy-token an, füllt es aus und sendet erneut. Ist das Script blockiert oder antwortet es nicht, wird das Formular trotzdem gesendet, ohne das Feld antisy-token: Ihr Server liest es mit einem leeren Standardwert, wie das Node-Beispiel unten. Die Seite zum Script sagt, was dann geschieht. Dieses Beispiel deckt die POST-Formulare an Ihre eigene Website ab. Für eine Übermittlung per fetch, ein Formular an eine Subdomain oder ein Ziel in einem anderen Fenster siehe welche Formulare abgedeckt sind.

2. Der Server, mit curl

Secret und Token stehen im Body der Anfrage, nie in einem Header; das Secret läuft über die Standardeingabe, nicht als Argument. Das Token wird vor dem Aufruf geprüft. Zeitlimit 3 Sekunden; antwortet Antisy nicht, geht die Übermittlung durch.

#!/bin/sh
# ANTISY_SECRET: Ihr Verifizierungs-Secret, aus der Umgebung, nie fest im Code.
# ANTISY_TOKEN:  das Feld antisy-token, mit dem Formular erhalten.
# Exit-Code 0: angenommen. Exit-Code 2: abgelehnt, oder Übermittlung nicht geprüft.
LC_ALL=C

# 1. Ein vorhandenes Token muss die Form eines Tokens haben: 1 bis 2048 druckbare ASCII-Zeichen.
#    Sonst wird Antisy nicht aufgerufen und nichts durchgelassen.
if [ -n "$ANTISY_TOKEN" ]; then
  case "$ANTISY_TOKEN" in
    *[!\ -~]*) echo "Jeton mal formé, envoi non vérifié" >&2; exit 2 ;;
  esac
  if [ "$(( $(printf '%s' "$ANTISY_TOKEN" | wc -c) ))" -gt 2048 ]; then
    echo "Jeton trop long, envoi non vérifié" >&2; exit 2
  fi
fi

# 2. Der Aufruf. Das Secret läuft über die Standardeingabe: Es erscheint nicht in der Prozessliste.
body=$(printf 'secret=%s' "$ANTISY_SECRET" | curl -sS --max-time 3 -w '\n%{http_code}' \
  https://api.antisy.com/v1/siteverify \
  -d @- \
  --data-urlencode response="$ANTISY_TOKEN")
curl_status=$?
http_code=$(printf '%s' "$body" | tail -n1)

# 3. Durchgelassen wird nur, wenn Antisy nicht antwortet: Netzausfall, Zeitlimit überschritten, 5xx.
#    Standardmässig auch der 429: Lesen Sie die Seite zur Verifizierung, bevor Sie diese Wahl beibehalten.
if [ "$curl_status" -ne 0 ] || [ "$http_code" -ge 500 ] || [ "$http_code" = 429 ]; then
  echo "Antisy ne répond pas (curl $curl_status, HTTP $http_code), envoi laissé passer" >&2
  exit 0
fi
# Jeder andere Fehlerstatus ist ein Fehler Ihres Aufrufs: zu beheben, und nie ein Freipass.
if [ "$http_code" -ge 400 ]; then
  echo "Requête refusée par Antisy (HTTP $http_code), envoi non vérifié" >&2
  exit 2
fi

# 4. Kompakte JSON-Antwort: grep genügt hier, verwenden Sie in Ihrem Code einen echten JSON-Parser.
if printf '%s' "$body" | grep -q '"success":true'; then
  exit 0   # Besucher angenommen
else
  exit 2   # deny: allgemeine Ablehnung, ohne Begründung
fi

3. Der Server, mit Node

Dasselbe mit fetch, ohne Abhängigkeit. Die Funktion gibt allow oder deny zurück; die Seite zur Prüfung erklärt jeden Fall, auch den 429, dessen Behandlung standardmässig eine Wahl ist, die bei Ihnen liegt.

// antisy.mjs: Node 22 oder neuer, ohne Abhängigkeit.
// Gibt "allow" oder "deny" zurück.
// Antisy antwortet nicht (Netz, Zeitlimit, 5xx): "allow". Alles andere Ungewisse: "deny".

// Der 429 ist Ihre Entscheidung. Standardmässig "allow", wie bei einem Ausfall;
// für ein sensibles Formular setzen Sie "deny" (siehe die Seite zur Verifizierung).
const ON_RATE_LIMIT = "allow";

export async function antisyVerdict(token) {
  // 1. Ein vorhandenes Token muss die Form eines Tokens haben: 1 bis 2048 druckbare ASCII-Zeichen.
  //    Sonst wird Antisy nicht aufgerufen und nichts durchgelassen.
  //    Ein leeres oder fehlendes Feld (Script blockiert) geht als leere Zeichenkette: Antisy liest es als fehlendes Token.
  if (token && !/^[\x20-\x7e]{1,2048}$/.test(token)) {
    console.warn("Jeton mal formé, envoi non vérifié");
    return "deny";
  }

  let response;
  try {
    response = await fetch("https://api.antisy.com/v1/siteverify", {
      method: "POST",
      // fetch folgt Weiterleitungen standardmässig: Eine 3xx würde den Body samt Secret anderswohin wiederholen.
      // Hier ist sie ein Fehler Ihres Aufrufs (weiter unten abgelehnt).
      redirect: "manual",
      // Ein URLSearchParams-Body geht als application/x-www-form-urlencoded.
      body: new URLSearchParams({
        secret: process.env.ANTISY_SECRET, // Ihr Secret, nie in der Seite
        response: token ?? "",             // das Feld antisy-token, wie erhalten
      }),
      signal: AbortSignal.timeout(3000),   // nach 3 s antwortet Antisy nicht
    });
  } catch (error) {
    console.warn("Antisy injoignable, envoi laissé passer :", error.name);
    return "allow";
  }
  if (response.status >= 500) {
    console.warn("Antisy a répondu " + response.status + ", envoi laissé passer");
    return "allow";
  }
  if (response.status === 429) {
    console.warn("Antisy a répondu 429, décision : " + ON_RATE_LIMIT);
    return ON_RATE_LIMIT;
  }
  if (!response.ok) {
    // 400, 401, 413, 415 ...: Der Fehler liegt in Ihrem Aufruf. Zu beheben, nie ein Freipass.
    console.error("Antisy a refusé la requête (" + response.status + "), envoi non vérifié");
    return "deny";
  }
  const result = await response.json().catch(() => null);
  if (typeof result?.success !== "boolean") {
    console.error("Réponse d'Antisy illisible, envoi non vérifié");
    return "deny";
  }
  // Ein fehlendes oder abgelehntes Secret ist kein HTTP-Fehler: Die Antwort ist eine Ablehnung, mit 200.
  const codes = result["error-codes"] ?? [];
  if (codes.includes("missing-input-secret") || codes.includes("invalid-input-secret")) {
    console.error("Antisy refuse le secret : " + codes.join(", "));
  }
  // success ist die einzige Annahme: Es ist genau dann true, wenn verdict "allow" ist.
  return result.success ? "allow" : "deny";
}

import { antisyVerdict } from "./antisy.mjs";

// Im Handler Ihres Formulars, nach dem Parsen des Bodys:
const verdict = await antisyVerdict(body["antisy-token"]);
if (verdict === "deny") return refuse(); // allgemeine Ablehnung, ohne Begründung
return accept();

PHP, Python und Go haben ihre Beispiele auf der Seite ein Token prüfen. Für den ganzen Weg, von der Website bis zur Produktion, folgen Sie der Schritt-für-Schritt-Anleitung.

Was mit dem Ergebnis tun

• allow: Der Besucher ist angenommen. Speichern oder veröffentlichen Sie die Nachricht.
• deny: Der Besucher kommt nicht durch. Lehnen Sie ab, ohne den Grund zu nennen.

Es gibt nur diese zwei Ausgänge, und die Antwort sagt nie warum: weder Grund noch Score noch Schwelle, in keinem Modus. Jeder genannte Grund würde dem, der den Schutz umgehen will, verraten, was ihn aufgehalten hat. Der Besucher sieht von alledem nichts.

Ein Token ist 60 Sekunden gültig und lässt sich nur einmal prüfen. Ein Ausfall von Antisy darf Ihre Besucher nie blockieren: Die beiden Beispiele oben lassen die Übermittlung nur dann durch, und protokollieren sie, wenn Antisy nicht antwortet (Netz, Zeitlimit, Fehler 5xx). Ein Fehler, den Ihre Anfrage verursacht, lässt nie durch.

Wie streng ablehnen

Jede Website hat einen Prüfmodus, der im Tab « Paramètres » (Einstellungen) des Dashboards eingestellt wird. Er ändert nur den Moment, ab dem ein zweifelhafter Besucher nicht mehr durchkommt; es gibt weder Schieberegler noch einen Wert einzugeben.

Streng

Lehnt früher ab, auf die Gefahr hin, einige echte Besucher zu behindern.

Ausgewogen

Die Standardeinstellung: ein Kompromiss zwischen den beiden anderen.

Nachsichtig

Lehnt nur eindeutige Fälle ab, auf die Gefahr hin, mehr Bots durchzulassen.

In allen Modi kommen bestimmte Fälle nie durch: die Liste steht auf der Seite zur Prüfung.

Was dieser Weg abdeckt

Der hier beschriebene Aufruf eignet sich für Formulare mit geringem Risiko: Kontakt, Newsletter. Er bindet das Token nicht an ein Konto; für ein Login oder eine Registrierung eignet er sich deshalb nicht. Dafür wird das Node-SDK (Express, Fastify, Next.js) mit seiner Dokumentation auf npm veröffentlicht werden; es ist noch nicht veröffentlicht.

Die Seiten Login und Registrierung sagen, was dieser andere Aufruf prüft und wie weit er ist; die häufigen Fragen fassen den Rest zusammen.

Anleitungen nach Plattform

Derselbe Weg, eingebunden in eine PHP-Website, eine Next.js-Anwendung oder eine WordPress-Website:

• PHP-Formular vor Bots schützen: Anleitung von AntisyEine Prüfdatei in PHP und cURL, ein Handler für das Kontaktformular und das Secret in der Umgebung des Servers.
• Next.js-Formular vor Bots schützen: Anleitung von AntisyDas Script-Tag im Layout, ein POST-Formular, eine Route, die die Node-Funktion der Dokumentation aufruft, und die CSP-Richtlinie mit Nonce.
• WordPress-Formular vor Spam-Bots schützen: Anleitung von AntisyKein Plugin: ein Script-Tag im Head, die PHP-Funktion der Dokumentation und zwei WordPress-Hooks, für die Kommentare und für ein selbst geschriebenes Formular.

Weiter

• Schritt-für-Schritt-AnleitungVon der Website bis zum geschützten Formular: acht Schritte, was Sie bei jedem sehen sollten, und was tun, wenn ein echter Besucher abgelehnt wird.
• Das Browser-ScriptDas Script-Tag, die abgedeckten Formulare, antisy.token(), die CSP-Richtlinie, die Hostnamen, die Browser, wenn das Script blockiert ist.
• Ein Token prüfenDie Anfrage, die Antwort, die Fristen, die Fehlercodes, wenn die API nicht antwortet, die Beispiele in PHP, Python und Go, der tatsächliche Ausgang.
• Schlüssel und TestumgebungenSite-Key, Secret, Erstellen und Widerrufen, Testschlüssel und ihre Schutzregel.
• Erhobene Daten und DatenschutzWas der Browser sendet, was Antisy aufbewahrt und wie lange.