Wie Domains bei Alpheris funktionieren
Alpheris merkt sich pro Shop eine Liste verifizierter Domains. Beim Onboarding wird deine Shop-Domain automatisch als primäre Domain angelegt. Für genau diese Domain wird dann ein Install-Key erzeugt — der Schlüssel, der in deinem Widget-Snippet steht.
Bei jeder Anfrage aus dem Browser prüft der Server zwei Dinge: ob der Origin der Seite (also der Host, auf dem das Widget eingebettet ist) zu einer erlaubten Domain gehört, und ob der mitgesendete Install-Key zu diesem Shop passt. Stimmt etwas nicht, antwortet der Server mit 403 blocked und das Widget bleibt stumm.
Origin bzw. Referer. Kopiert jemand dein Snippet auf eine fremde Seite, wird die Anfrage abgelehnt — der Schlüssel ist außerhalb deiner Domain wertlos.Domain hinterlegen & verifizieren
Wie eine Domain verifiziert wird, hängt davon ab, wie du Alpheris installierst. In allen Fällen entsteht eine verifizierte Domain plus passender Install-Key — du musst keine DNS-Einträge setzen oder Dateien hochladen.
Bei Shopify und WordPress läuft die Verifizierung implizit über die bestätigte Verbindung: Die Domains werden direkt mit Verifizierungs-Methode shopify bzw. wordpress als verifiziert gespeichert. Bei Shopify wird zusätzlich die www.-Variante automatisch ergänzt.
Bei der Code-Methode (Snippet manuell einbauen) trägst du die Domain im Dashboard ein. Sie wird mit Methode manual als verifiziert hinterlegt und ein Install-Key dafür erzeugt. Einen separaten DNS-TXT- oder Datei-Token-Schritt gibt es bei der Code-Methode nicht.
Domain im Dashboard eintragen
shop.de oder www.shop.de. Eine vollständige URL wie https://shop.de/ wird ebenfalls akzeptiert — Schema, Pfad und Port werden automatisch entfernt.Erlaubte Domains & Matching
Eine Anfrage gilt als erlaubt, wenn ihr Host zu einer hinterlegten Domain passt. Das Matching kennt drei Fälle:
| Eintrag | Erlaubt |
|---|---|
shop.de | Exakt shop.de — und zusätzlich www.shop.de |
www.shop.de | Exakt www.shop.de |
*.shop.de | shop.de sowie alle Subdomains, z. B. de.shop.de, checkout.shop.de |
Eine bare Domain (ohne www.) deckt die www.-Variante automatisch mit ab. Soll das Widget auf beliebigen Subdomains laufen, nimm einen Wildcard-Eintrag *.shop.de auf. Für lokale Tests trägst du localhost als eigene Domain ein — eine implizite Whitelist dafür gibt es nicht.
Origin sendet, nicht die IP des Proxys.Mehrere Domains & Plan-Grenzen
Wie viele Domains du hinterlegen darfst und ob du sie selbst verwalten kannst, hängt vom Plan ab:
| Plan | Domains | Verwaltung |
|---|---|---|
| Free | 1 | Nur über Support |
| Basic | 1 | Nur über Support |
| Business | bis zu 5 | Selbst, inkl. bis zu 3 Wechsel der primären Domain |
| Enterprise | unbegrenzt | Selbst, ohne Limit |
Eure eigene Alpheris-Adresse (deinshop.alpheris.com) zählt nicht gegen dein Domain-Limit. Es gibt sie mit Enterprise, und sie entsteht nicht automatisch: Du legst sie im Dashboard unter Domains an. Mehr unter Pläne & Abrechnung.
Install-Key pro Domain
Der Install-Key (Attribut data-alpheris-key) verknüpft dein Snippet eindeutig mit deinem Shop und der Domain, für die er ausgestellt wurde. So sieht das fertige Snippet aus:
<!-- Alpheris Chat Widget -->
<script src="https://alpheris.com/widget.js" data-alpheris-key="INSTALL_ID" crossorigin="anonymous" async></script>
<!-- End Alpheris Chat Widget -->Ersetze INSTALL_ID durch den Wert aus deinem Dashboard — dort bekommst du das komplette Snippet bereits mit deinem echten Key fertig zum Kopieren. Das vollständige Einbau-Verfahren steht unter Widget-Code.
Eigenschaften des Install-Keys
- Pro Domain ausgestellt: Beim Verifizieren der (primären) Domain wird der zugehörige Install-Key erzeugt und intern an genau diese Domain gekoppelt.
- Widerrufbar: Ein Key kann als
revokedmarkiert werden; danach werden Anfragen mit diesem Key nicht mehr akzeptiert. - Mehrere Keys möglich: Pro Domain kann mehr als ein Key existieren — relevant z. B. nach einem Wechsel der primären Domain. Verwende immer das aktuelle Snippet aus dem Dashboard.
invalid_install_id blockiert werden. Hol dir dann den passenden Key für die neue Domain aus dem Dashboard.Strict-Domain-Modus (Widget-Domain-Bindung)
Alpheris betreibt das Widget standardmäßig im Strict-Domain-Modus (intern WIDGET_STRICT_DOMAIN, plattformseitig aktiv). In diesem Modus gilt für jede Widget- und Chat-Anfrage:
- Der
Origin/Referer-Host muss zu einer erlaubten Domain deines Shops passen — sonst403 domain_not_allowed. - Fehlt der Origin komplett (z. B. roher Direktaufruf ohne Browser-Kontext), wird die Anfrage abgelehnt (
no_origin), außer sie kommt nachweislich aus einer eingeloggten Console-/Vorschau-Sitzung deines Shops. - Ist ein Install-Key angegeben, muss er gültig und zum Shop gehörig sein.
Ein optionaler Host-Fallback über einen Query-Parameter ist im Strict-Modus bewusst deaktiviert — der Host wird nur aus den echten Browser-Headern abgeleitet, nicht aus frei wählbaren Parametern.
403 blocked mit domain_not_allowed oder invalid_install_id meldet: Domain ist nicht (richtig) hinterlegt oder der Key passt nicht zur Domain. Siehe Fehlerbehebung.Häufige Fragen
Ich habe meine Domain gewechselt — was tun?
Trage die neue Domain im Dashboard ein und setze sie als primäre Domain. Dabei wird ein neuer Install-Key erzeugt. Tausche anschließend das Snippet auf deiner Website gegen die aktuelle Version aus dem Dashboard. Im Business-Plan sind bis zu 3 solcher Primär-Wechsel möglich, im Enterprise-Plan unbegrenzt.
Funktioniert das Widget auf Staging- oder Test-Domains?
Ja — nimm die Staging-Domain als zusätzliche erlaubte Domain auf (im Business-/Enterprise-Plan). Für lokale Tests trage localhost ein.
Brauche ich für jede Subdomain einen eigenen Eintrag?
Nein. Ein Wildcard-Eintrag *.shop.de deckt die Domain und alle ihre Subdomains ab. Für www. reicht zudem die bare Domain.