Dokumentation

Warpkit anbinden und steuern

Warpkit sitzt als Cloudflare Worker vor deinem Shop. Diese Seite beschreibt den Ablauf einer Anfrage, die Einstellungen eines Mandanten und die Schnittstellen.

Ablauf einer Anfrage

Einordnen. Aus Tag, Netzbereich und User-Agent entsteht ein Hash, der den Besucher der beschleunigten oder der Kontrollgruppe und den Varianten laufender Experimente zuordnet. Der Hash existiert nur im Arbeitsspeicher.
Gerüst suchen. Liegt für die URL ein Gerüst im Edge-Cache und steht die URL nicht als geändert im Bloom-Filter, wird es sofort gesendet.
Server fragen. Gleichzeitig geht die Anfrage mit den Cookies des Besuchers an deinen Server. Aus dessen Antwort schneidet Warpkit die persönlichen Bereiche heraus und hängt sie an den laufenden Datenstrom an.
Vergleichen. Weicht das Gerüst der Live-Antwort vom gespeicherten ab, ruft Warpkit die Seite erneut ohne Cookies ab, ersetzt das Gerüst und trägt die URL in den Bloom-Filter ein.

Ist kein Gerüst vorhanden, erhält der Besucher die normale Antwort deines Servers. Im Hintergrund wird die Seite ohne Cookies abgerufen und für den nächsten Aufruf vorbereitet.

Antwort-Header `x-warpkit`

Wert	Bedeutung
`hit`	Gerüst aus dem Edge-Cache, persönliche Bereiche im selben Datenstrom
`miss`	Kein Gerüst vorhanden, Antwort kommt vom Server, Cache wird aufgewärmt
`spec`	Vorab-Ladung (Prefetch oder Prerender), ohne Kontakt zu deinem Server
`sw`	Gerüst für den Gerätecache des Service Workers
`control`	Kontrollgruppe, bewusst ohne Beschleunigung
`pass`	Ausgeschlossener Pfad oder nicht cachebare Seite
`fail-open`	Fehler in Warpkit, Anfrage ging unverändert an deinen Server

Anbindung

Full-Edge (Early Access)

Die Shop-Domain wird als Custom Hostname bei Warpkit hinterlegt und per CNAME auf Warpkit gerichtet. Das TLS-Zertifikat stellt Cloudflare aus. Dein Server bleibt unverändert und muss nur weiterhin unter einer eigenen Adresse erreichbar sein, die als origin eingetragen wird.

Seite über den Selbsttest analysieren. Das Ergebnis enthält eine Startkonfiguration.
Mandant anlegen (siehe API) und Bereiche ergänzen, die nur eingeloggt oder mit gefülltem Warenkorb sichtbar sind.
CNAME setzen. Mit controlShare: 0.5 starten und im Dashboard prüfen, dass „Abweichungen außerhalb der Bereiche“ bei 0 bleibt.

Connector (in Vorbereitung)

Für Shops hinter einem fremden CDN ist eine Anbindung über ein Skript-Tag und eine Service-Worker-Datei vorgesehen. Sie wirkt ab dem zweiten Seitenaufruf und ist noch nicht verfügbar.

Einstellungen eines Mandanten

Feld	Standard	Bedeutung
`origin`	–	Adresse deines Servers, nur `https`
`dynamic`	`[]`	CSS-Selektoren der persönlichen Bereiche. Ihr Inhalt wird nie gespeichert.
`exclude`	`/cart, /checkout, /account …`	Pfade, die immer unverändert durchgereicht werden
`ignoreParams`	`utm_*, gclid, fbclid …`	Query-Parameter, die den Cache-Schlüssel nicht verändern
`vary`	`[]`	Header, nach denen dein Server unterschiedliches HTML liefert, oder `device` für mobil/Desktop
`ttl`	`86400`	Maximale Lebenszeit eines Gerüsts in Sekunden
`controlShare`	`0.1`	Anteil der Besucher ohne Beschleunigung (Kontrollgruppe), 0 bis 1
`assignment`	`stateless`	`stateless`: Zuordnung per Hash, nichts wird auf dem Gerät gespeichert. `cookie`: zufällige Gruppennummer in einem First-Party-Cookie, 30 Tage stabil.
`experiments`	`[]`	Edge-A/B-Tests: `id`, `selector`, `variants` (`name`, optional `html`, `attrs`), `weights`
`speculation`	aktiv	`hover`: `prefetch` oder `prerender`; `minProbability`, `minSamples`, `maxPrerender` steuern das Vorab-Rendern vorhergesagter Seiten
`serviceWorker`	`false`	Gerätecache für Gerüste. Abschalten wirkt als Notschalter für alle Geräte.
`stripComments`	`true`	HTML-Kommentare aus dem Gerüst entfernen

Markierungen im HTML deines Shops

data-wk-conv an einem Formular, Link oder Button zählt Absenden bzw. Klick als Conversion.
warpkit.track("conversion") meldet eine Conversion aus eigenem Skript.
data-wk-nospec an einem Link schließt ihn vom Vorausladen aus.
Das Ereignis warpkit:merged am document signalisiert, dass die persönlichen Bereiche eingesetzt sind. Bis dahin trägt <html> die Klasse wk-loading, danach wk-loaded.

Schalter in der URL

?wk=off liefert die Seite unbeschleunigt, ?wk=on erzwingt die beschleunigte Gruppe.
?wkx-<experiment>=<variante> zeigt eine bestimmte Testvariante.

API

Alle Aufrufe gehen an https://warpkit.co und erwarten Authorization: Bearer <Schlüssel>. Der Mandantenschlüssel wird beim Anlegen einmalig ausgegeben.

Aufruf	Zweck
`GET /api/t/{id}/stats?days=7`	Messwerte, Trefferquote, Vorhersagen, Testergebnisse
`GET /api/t/{id}/config`	Aktuelle Einstellungen und Hostnamen
`POST /api/t/{id}/purge`	`{"paths": ["/produkt/x"]}` markiert URLs als geändert, `{"all": true}` verwirft alle Gerüste
`POST /api/admin/tenants`	Mandant anlegen oder ändern (nur Betreiber)
`GET`, `DELETE /api/admin/tenants/{id}`	Mandant lesen oder löschen (nur Betreiber)

curl -X POST https://warpkit.co/api/t/mein-shop/purge \
  -H "Authorization: Bearer wk_…" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/produkt/regenjacke"]}'

Bekannte Grenzen

Gespeichert werden nur HTML-Antworten mit Status 200 in UTF-8 bis 2 MB. Alles andere wird durchgereicht.
Setzt dein Server bei einem beschleunigten Aufruf Cookies, werden sie verschlüsselt mitgeschickt und über einen kurzen Folgeaufruf gesetzt. HttpOnly bleibt erhalten.
Eine Content-Security-Policy mit Nonces verlangt pro Antwort einen neuen Wert und muss vor der Aktivierung abgestimmt werden.
Skripte mit defer starten erst, wenn die Antwort vollständig ist, also nach der Antwort deines Servers. Sichtbar ist die Seite vorher.
Vorab-Rendern nutzt die Speculation Rules API und wirkt derzeit in Chromium-Browsern.
Ohne Cookie kann sich die Zuordnung zu Gruppe und Variante ändern, wenn der Besucher das Netz wechselt oder ein neuer Tag beginnt. Für strenge Tests gibt es assignment: "cookie".

Der Selbsttest

Der Selbsttest ruft die angegebene Seite zweimal mit dem User-Agent WarpkitAnalyzer/1.0 ab, einmal ohne und einmal mit den Cookies der ersten Antwort. Er führt keine Skripte aus, folgt keinen weiteren Links und speichert weder Adresse noch Inhalt.