Whitelabel Technische Spezifikationen

Dieses Dokument definiert die Konfigurationsstandards für die NoPaperManuals™ Infrastruktur im Whitelabel-Modus.

[!NOTE] Wir bieten 3 progressive Integrationsstufen je nach Ihren technischen Anforderungen:

Stufe 1: DNS-Delegation (Einfache Anpassung über Farben und Logos).

Stufe 2: Smart Embedded (Reibungslose Integration via Iframe auf Ihrer bestehenden Website).

Stufe 3: Reverse Proxy (Remote Fetching zur Injektion Ihres kompletten nativen HTML).

🔗 Integrationsstufen und Anpassung

Je nach Ihren Branding-Anforderungen und technischen Ressourcen stehen drei Integrationsstufen zur Verfügung.

🎨 STUFE 1: DNS-Delegation (Branding-Anpassung)

Für die DNS-Delegation ist die Anpassung so konzipiert, dass sie einfach und schnell ist und von unserem technischen Team konfiguriert wird.

1. Konfiguration des Domainnamens (CNAME)

Sie müssen zunächst eine dedizierte Subdomain für Ihre Handbücher auswählen (z.B. handbuecher.ihre-marke.com). Anschließend müssen Sie in der DNS-Verwaltungsoberfläche Ihrer Domain einen CNAME-Eintrag erstellen, der auf unsere Infrastruktur verweist: fallback.nopapermanuals.com.

2. Was wir für Sie anpassen können:

• Visuelle Identität: Upload Ihres hochauflösenden Logos und eines benutzerdefinierten Favicons.

• Farbpalette: Definition Ihrer "Akzentfarbe", die auf Schaltflächen und aktive Elemente angewendet wird.

• Navigation (Header): Konfiguration einfacher Menüs (Linkname, URL), um den Zugriff auf Ihre Hauptseiten wiederherzustellen.

• Fußzeile (Footer): Integration von Links zu Ihren sozialen Netzwerken und Impressum-Seiten.

🧩 STUFE 2: Smart Embedded (Iframe-Integration)

Der Ansatz „Smart Embedded“ ist ideal, um Handbücher direkt in Ihre E-Commerce-Website (Shopify, PrestaShop) oder Ihr bestehendes Support-CMS zu integrieren.

Diese Methode ermöglicht es, auf das Design des NoPaperManuals-Headers oder -Footers zu verzichten, und garantiert gleichzeitig, dass physische QR-Code-Scans Ihre Kunden in Ihre Umgebung umleiten.

1. Host URL-Konfiguration

Bei der Einrichtung Ihres Whitelabel-Kontos mit unserem Team müssen Sie die genaue URL angeben, unter der das Iframe gehostet wird (z.B. https://support.ihre-marke.com/handbuecher).

2. JS Snippet-Integration

Unser technisches Team stellt Ihnen ein vorkonfiguriertes Javascript-Snippet für Ihre Marke zur Verfügung. Dieser Code liest die URL, wenn ein Benutzer einen QR-Code scannt (?npm_shortcode=XYZ), und erstellt dynamisch die URL unseres Iframes (https://nopapermanuals.com/s/XYZ?embedded=true).

<!-- Ziel des Iframes auf Ihrer Seite -->
<iframe id="npm-iframe" style="width:100%; height:100vh; border:none;"></iframe>

<script>
  // 1. Lesen des Parameters 'npm_shortcode' aus der URL
  const params = new URLSearchParams(window.location.search);
  const shortcode = params.get('npm_shortcode');
  
  // 2. Definieren der finalen Iframe-URL (Minimalistischer Modus ohne anfängliche Menüs)
  const iframeUrl = shortcode 
    ? `https://nopapermanuals.com/s/${shortcode}?embedded=true` 
    : `https://nopapermanuals.com/tenant/ihr-identifikator?embedded=true`;

  // 3. Transparentes Laden des Inhalts
  document.getElementById('npm-iframe').src = iframeUrl;
</script>

3. Benutzererfahrung (Journey) beim Scannen

• Schritt 1: Der Benutzer scannt den QR-Code auf Ihrem Produkt (qrmanual.app/ABC).
• Schritt 2: Unser Server erkennt den Smart Embedded-Modus für dieses Produkt.
• Schritt 3: Der Benutzer wird sofort auf Ihre Seite weitergeleitet: https://support.ihre-marke.com/handbuecher?npm_shortcode=ABC.
• Schritt 4: Das Snippet liest „ABC“, lädt das Handbuch von NoPaperManuals und fügt es in die Seite ein. Ihre Benutzer bleiben auf Ihrem Domainnamen.

🚀 STUFE 3: Reverse Proxy (Shell-Modus)

Der Proxy-Modus (Reverse Proxy) ist die fortschrittlichste Integration. Er ermöglicht es, NoPaperManuals in das Zentrum Ihrer eigenen Web-Infrastruktur zu verschmelzen.

Der Inhalt wird direkt von Ihrem Domainnamen bereitgestellt, was die Suchmaschinenoptimierung (SEO) optimiert und die transparenteste Erfahrung bietet.

Anpassung durch "Remote Fetching" (Dynamisch)

Anstatt Ihre Menüs manuell neu zu erstellen, ruft NoPaperManuals Fragmente Ihres Headers und Footers in Echtzeit über spezifische URLs ab.

• Hauptvorteil: 100% automatische Synchronisation. Jede Änderung auf Ihrer Hauptwebsite wird sofort auf den Abschnitt „Handbücher“ übertragen.
• Technische Voraussetzung: Sie müssen HTML-Endpunkte bereitstellen, die nur die Struktur Ihres Headers und Footers zurückgeben (ohne die globalen Tags <body> oder <html>).

🔒 Absicherung der Kommunikation

Die „Server-to-Server“-Kommunikation zwischen Ihrer Infrastruktur und NoPaperManuals muss zwingend über spezifische Header authentifiziert werden, um jegliche Identitätstäuschung zu verhindern:

| HTTP-Header | Erwarteter Wert | | :--- | :--- | | X-NPM-Custom-Host | Ihr offizieller Domainname (z.B. handbuecher.ihre-marke.com) | | X-NPM-Proxy-Secret | Ihr kryptografischer Sicherheitsschlüssel (mit unserem Team geteilt) |

[!WARNING] Kritischer Schutz Aktiv Wenn der Header X-NPM-Proxy-Secret fehlt, falsch oder kompromittiert ist, weigert sich die NoPaperManuals-Firewall, Ihre Inhalte bereitzustellen, um die Integrität Ihrer Marke zu schützen.

⚙️ Erforderliche Architektur: Dedizierte Subdomain

Bei Single-Page-Anwendungen (SPA) muss der Reverse Proxy zwingend auf eine dedizierte Subdomain abzielen (z.B. handbuecher.ihre-marke.com) und den Datenverkehr im Stammverzeichnis / abfangen.

[!WARNING] Die Konfiguration in einem Unterordner (z.B. ihre-marke.com/handbuecher/) wird dringend abgeraten. Sie erfordert eine technische Validierung, um Konflikte mit unseren Assets (/_next/, /api/, usw.) zu vermeiden. In 95% der Fälle ist die Subdomain die empfohlene Lösung.

🛠️ Nginx Konfigurationsbeispiel

Standardvorlage eines Nginx server-Blocks:

server {
    listen 443 ssl http2;
    server_name handbuecher.ihre-marke.com;
    
    # 1. Gültige SSL-Zertifikate (Von Ihnen bereitzustellen)
    ssl_certificate /path/to/cert/fullchain.pem;
    ssl_certificate_key /path/to/cert/privkey.pem;
    
    location / {
        # 2. Proxy auf das NoPaperManuals-Stammverzeichnis
        proxy_pass https://nopapermanuals.com/;
        
        # 3. Obligatorische Sicherheits-Header
        proxy_set_header X-NPM-Custom-Host "ihre-marke.com";
        proxy_set_header X-NPM-Proxy-Secret "IHR_KRYPTOGRAFISCHES_GEHEIMNIS";
        
        # 4. Standard-Transfer-Header
        proxy_ssl_server_name on;
        proxy_set_header Host nopapermanuals.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🛠️ Validierung & Bereitstellung

• Visuelle Überprüfung: Um die Darstellung Ihrer Farben, Logos und Branding-Optionen vor der Produktivsetzung zu validieren, kann eine dedizierte Testumgebung eingerichtet werden. Bitte kontaktieren Sie uns, um die Aktivierung vorzunehmen.

• Sicherheitstests: (Nur Stufe 3) Stellen Sie sicher, dass Ihre Sicherheits-Header korrekt konfiguriert und übertragen werden.

[!NOTE] Jede von unserem technischen Support vorgenommene Aktualisierung Ihres Brandings wird in Echtzeit auf Ihre Whitelabel-Domain angewendet.