Zum Hauptinhalt springen
Eine produktionsbereite Integration ist in diesem Repository verfuegbar: https://github.com/Kameleoon/setup-engine-nextjs Achten Sie darauf, den Sitecode durch Ihren eigenen zu ersetzen in src/integrations/Kameleoon/sitecode.ts.
Die Domain Ihres Kameleoon-Skripts kann sich zwischen Projekten unterscheiden. Je nach Erstellungsdatum koennen Ihre Projekte unter kameleoon.eu oder kameleoon.io gehostet werden. Verwenden Sie immer die fuer Ihr Projekt in der Kameleoon App angezeigte Domain.

​
Ueberblick​

  1. Laden Sie die Kameleoon-Engine vorab, damit der Browser sie frueh herunterlaedt und im Cache speichert.
  2. Wenden Sie Anti-Flicker-CSS an, um Inhalte auszublenden, bis die Engine bereit ist, und Layout-Verschiebungen zu verhindern.
  3. Fuehren Sie die Engine nach der Hydratation aus, um React-Hydratationswarnungen oder Inkonsistenzen zu vermeiden.

​
Komponenten​

Diese Integration verwendet zwei Komponenten, die zusammenarbeiten, um reibungsloses Laden zu gewaehrleisten und Flackern waehrend der Hydratation zu verhindern.

​
1. Server Component​

Platzieren Sie diese Komponente innerhalb des <head> Ihres Hauptlayouts. Ihre Aufgaben sind:
  • Einfuegen von Anti-Flicker-CSS waehrend des SSR, um UI-Flashes zu verhindern
  • Vorladen der Datei engine.js, damit das Herunterladen so schnell wie moeglich beginnt
// ⛔ No "use client" here - must stay server-side
import { SITECODE_SRC } from "./sitecode";

const ANTIFLICKER_CSS = `
html::after {
    content: '';
    position: fixed;
    inset: 0;
    background: #fff;
    z-index: 2147483647;
}`;

export function KameleoonHead() {
    return (
        <>
            {/* Preload the engine so browser begins downloading ASAP */}
            <link rel="preload" href={SITECODE_SRC} as="script" fetchPriority="high" />
            {/* Anti-flicker stylesheet injected during SSR */}
            <style
                id="kameleoonLoadingStyleSheet"
                suppressHydrationWarning
                dangerouslySetInnerHTML={{ __html: ANTIFLICKER_CSS }}
            />
        </>
    );
}
Siehe KameleoonHead.tsx

​
2. Client Component​

Platzieren Sie diese Komponente ganz oben im <body>, um den Ausfuehrungszeitpunkt praezise zu steuern. Diese Komponente:
  • Entfernt die Anti-Flicker-Stile nach der Hydratation
  • Laedt Kameleoons engine.js dynamisch
  • Stellt sicher, dass das Skript ohne Rendering-Blockierung geladen wird
"use client";

import { useCallback, useEffect } from "react";
import { SITECODE_SRC } from "./sitecode";

export function KameleoonHydrationReady() {
    const removeAntiflickerStyles = useCallback(() => {
        const kameleoonLoadingTimeout = 500;
        window.kameleoonQueue = window.kameleoonQueue || [];
        window.kameleoonStartLoadTime = Date.now();

        window.kameleoonDisplayPage = function (fromEngine) {
            if (!fromEngine) {
                window.kameleoonTimeout = true;
            }
            document.getElementById("kameleoonLoadingStyleSheet")?.remove();
        };

        window.kameleoonDisplayPageTimeOut = setTimeout(
            window.kameleoonDisplayPage,
            kameleoonLoadingTimeout
        );
    }, []);

    const loadEngine = useCallback(() => {
        if (document.getElementById("kameleoon-engine")) return;

        const script = document.createElement("script");
        script.src = SITECODE_SRC;
        script.async = true;
        script.id = "kameleoon-engine";
        document.head.appendChild(script);
    }, []);

    // Execute Kameleoon after hydration
    useEffect(() => {
        removeAntiflickerStyles();
        loadEngine();
    }, [loadEngine, removeAntiflickerStyles]);

    return null;
}
Siehe KameleoonHydrationReady.tsx
Hinweis: Der standardmaessige Anti-Flicker-Timeout betraegt 500 ms. Passen Sie kameleoonLoadingTimeout bei Bedarf an.

​
Verwendung in RootLayout​

Beispiel fuer die Kombination beider Komponenten: 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <head>
                <KameleoonHead />
            </head>
            <body className={inter.className}>
                <KameleoonHydrationReady />
                {children}
            </body>
        </html>
    );
}
Siehe layout.tsx

​
Wichtige Erkenntnisse​

  • Anti-Flicker-Schutz beim SSR
  • Hydratationsbewusste Skriptausfuehrung
  • Asynchrones Laden der Engine
  • Fallback-Timeout fuer Zuverlaessigkeit
  • Keine blockierenden Skripte
  • Funktioniert mit Next.js-Layouts, Streaming und React Server Components
Mit dieser Einrichtung laedt Ihre Next.js-Anwendung Kameleoon effizient und vermeidet hydratationsbezogene Probleme.