Custom Domains

Custom Domains verbinden dynamische QR-Codes mit einer eigenen Marken-Domain, zum Beispiel go.example.com/summer statt einer neutralen Plattform-Domain. Die Verwaltung ist im QR-Dashboard unter /qr/domains live.

Wann du Custom Domains nutzt

Nutze Custom Domains, wenn der sichtbare Scan-Link zur Marke, Kampagne oder Organisation passen soll. Das ist besonders wichtig fuer Print, Retail, Verpackungen, Events, Franchise-Strukturen und Agenturen mit mehreren Kunden.

Eine Custom Domain aendert nicht den QR-Code-Typ. Sie steuert die Redirect- Domain fuer dynamische Codes. Statische Codes enthalten ihren Payload weiterhin direkt im QR-Bild.

Setup-Ablauf

1. Oeffne /qr/domains.
2. Gib eine Subdomain ein, zum Beispiel go.example.com.
3. QR Vello validiert den Hostname ohne Cloudflare-Mutation.
4. Lege die angezeigten DNS-Records beim DNS-Provider an.
5. Starte Verify now im Dashboard oder warte auf den Hintergrund-Check.
6. Warte, bis DNS und TLS aktiv sind.
7. Markiere die Domain optional als Primary.
8. Weise neue oder bestehende dynamische QR-Codes dieser Domain zu.

Hostname-Regeln

DNS-Records

Die konkrete DNS-Anweisung kommt immer aus dem Wizard und aus dem Domain-Detail. Diese Records koennen erscheinen:

Unterstuetzte DNS-Typen sind TXT und CNAME. Kopiere name und value immer exakt. Bei Cloudflare muss der CNAME fuer diese Subdomain auf DNS only stehen, nicht auf Proxied.

Statusmodell

Archivierte Domains haben zusaetzlich archivedAt. Sie bleiben fuer die Restore-Frist sichtbar, damit bestehende Referenzen und Audit-Historie sauber bleiben.

DNS-Status

Typische Loesungen:

• missing: Record fehlt oder DNS-Propagation laeuft noch.
• wrong_target: CNAME zeigt nicht auf das angezeigte Edge-Target.
• wrong_value: TXT- oder CNAME-Wert weicht ab.
• proxied: Cloudflare-Proxy deaktivieren und auf DNS only stellen.
• a_record_conflict: A/AAAA-Record fuer denselben Host entfernen.
• unknown: Resolver liefern noch kein stabiles Ergebnis.

Recommended Actions

Das Backend liefert pro Domain konkrete naechste Schritte:

Primary Domain

Eine aktive Domain kann als Primary markiert werden. Primary bedeutet: neue dynamische QR-Codes koennen diese Domain als Default bekommen. Bestehende Codes werden nicht stillschweigend umgezogen. Aendere sie gezielt im Code-Detail oder ueber die API, damit gedruckte Kampagnen kontrolliert bleiben.

QR-Code-Zuweisung

Custom Domains greifen bei dynamischen Codes. Beim Erstellen oder Bearbeiten eines Codes wird customDomainId gesetzt. Die Domain muss zum aktiven Workspace gehoeren und fuer Live-Redirects aktiv sein.

{
  "type": "dynamic",
  "kind": "url",
  "title": "Store Mainz",
  "targetUrl": "https://example.com/mainz",
  "customDomainId": 42
}

Im Dashboard findest du die Auswahl beim Erstellen eines Codes und im Code-Detail unter Organisation. Wenn eine Domain nicht aktiv ist, faellt das Rendering auf die verfuegbare Default-Domain zurueck oder blockiert die Aktion mit einem konkreten Hinweis.

Dashboard-Funktionen

Die Domains-Oberflaeche unter /qr/domains deckt ab:

• Liste mit status, primaryOnly und includeArchived.
• Detailansicht mit DNS-Anweisungen, codesUsing, nextPollAt und nextManualVerifyAllowedAt.
• Diagnostics mit lastErrorPublic, Cloudflare-Validierungsfehlern, TLS-Zeitpunkten und kvSyncedAt.
• Events und Audit-Historie pro Domain.
• Metadata-Update fuer displayName und notes.
• Deaktivieren, Reaktivieren, Archivieren, Restore und Bulk-Delete.
• Realtime-Updates ueber den qr_custom_domain Channel.

Dashboard API

Diese Routen sind die interne Dashboard-API fuer authentifizierte Workspace- Sessions. Sie sind dokumentiert, aber nicht als Public-v1-Vertrag fuer fremde Server-zu-Server-Integrationen gemeint.

Create Payload

{
  "hostname": "go.example.com",
  "displayName": "Retail Links",
  "notes": "DNS liegt bei Cloudflare Marketing"
}

Detail Response

Wichtige Felder im Domain-Detail:

• id, workspaceId, hostname, displayName, notes
• status, isPrimary, codesUsing
• dnsInstructions.cname und dnsInstructions.records[]
• cfHostnameStatus, cfSslStatus, cfValidationErrors
• lastErrorPublic, failureCount, lastCheckAt
• activatedAt, tlsIssuedAt, tlsExpiresAt, disabledAt
• verificationExpiresAt, kvSyncedAt
• nextPollAt, nextManualVerifyAllowedAt
• recommendedActions

Webhooks und Realtime

Custom-Domain-Lifecycle-Events werden im Dashboard und in Webhooks verwendet:

• custom_domain.created
• custom_domain.activated
• custom_domain.error
• custom_domain.enabled
• custom_domain.disabled
• custom_domain.primary_changed
• custom_domain.tls_renewed
• custom_domain.archived
• custom_domain.restored
• custom_domain.deleted
• custom_domain.metadata_updated

Der Realtime-Channel heisst qr_custom_domain. Clients koennen den aktiven Workspace abonnieren oder eine workspaceId uebergeben, wenn die Membership das erlaubt.

Public API Status

Die stabile Public API v1 dokumentiert aktuell QR-Codes unter /docs/qr/api-reference-v1. Custom-Domain- Automation ist im Produkt vorhanden, aber noch nicht als eigenstaendige Public-v1-Ressource freigegeben. Fuer externe Provisionierung oder Agentur- Workflows sollte der Use Case ueber Support oder Enterprise abgestimmt werden, bis eine stabile /v1/custom-domains-Flaeche veroeffentlicht ist.

Troubleshooting