So testen Sie die SeaText SPA-Integration vor dem Live-Gang

Bevor SeaText live geht, testen Sie es in einer Staging-Umgebung. Das Ziel ist einfach: Beweisen Sie, dass das Snippet geladen wird, der lokale Speicher funktioniert, Sprachumschaltungen funktionieren und sich jede Route korrekt verhält. Dieser Leitfaden bietet Ihnen eine praktische Checkliste, eine Routenübersicht und ein Beispiel-Cypress-Skript.

Warum Staging-Tests wichtig sind

SeaText schreibt Seitentexte um und erstellt Varianten. Wenn das Snippet fehlschlägt, sehen Besucher möglicherweise den Originaltext, den übersetzten Text oder eine fehlerhafte Benutzeroberfläche. Das ist in der Produktion schwer zu diagnostizieren.

Staging ermöglicht es Ihnen, diese Probleme zu erkennen, bevor echter Traffic eintrifft. Sie können asynchrones Laden, lokalen Speicher und Cross-Origin-Verhalten sicher testen.

Die SeaText-Dokumentation weist auf drei SPA-spezifische Risiken hin: asynchrones Laden, Berechtigungen für den lokalen Speicher und Cross-Origin-Probleme. Ein Staging-Test sollte alle drei abdecken.

Ohne Staging kann ein Fehler jeden Besucher betreffen. Mit Staging können Sie ihn vor dem Start beheben.

Wie das SeaText-Snippet innerhalb einer SPA funktioniert

SeaText ist ein JavaScript-Snippet. Die Dokumentation verwendet den Platzhalter SEATEXTCODEINTEGRATION. Sie fügen ihn in den Body der index.html oder in den entsprechenden Initialisierungsbereich Ihres SPA-Frameworks ein.

Das Skript-Tag enthält das Attribut async. Das verhindert, dass das Snippet das Rendern der Seite blockiert. Es ist eine Leistungsentscheidung, bedeutet aber auch, dass das Skript nach dem ersten Paint ausgeführt wird.

Das Skript speichert eine ID im lokalen Speicher. SeaText verwendet diese ID, um Besuche zu erkennen und die richtige Variante anzuwenden. Wenn der lokale Speicher blockiert ist, schlägt diese Erkennung fehl.

SPA-Frameworks wie React, Vue und Angular mounten die App von verschiedenen Einstiegspunkten aus. Sie müssen die richtige Datei finden. Die Dokumentation besagt, dass dies normalerweise index.html oder eine Haupt-JavaScript/TypeScript-Datei ist, in der das Framework mountet.

In einer SPA lädt ein Klick auf einen Link die Seite nicht neu. Der Browser tauscht Komponenten aus. SeaText muss über diese Wechsel hinweg funktionieren. Deshalb können Sie nicht nur eine Route testen.

Schritt-für-Schritt-Checkliste für Staging-Tests

Verwenden Sie diese Reihenfolge. Sie führt vom Build-Setup zu Laufzeitprüfungen.

1. Definieren Sie Ihre Routenkarte. Notieren Sie jede Produktions-URL, die die SPA verwendet.
2. Erstellen Sie die App auf die gleiche Weise wie für die Produktion. Verwenden Sie nach Möglichkeit dieselben Umgebungsvariablen.
3. Fügen Sie SEATEXTCODEINTEGRATION am korrekten Einstiegspunkt ein.
4. Stellen Sie den Staging-Build nach Möglichkeit über HTTPS bereit. SeaText verhält sich auf localhost möglicherweise anders.
5. Aktivieren Sie das SeaText-Debug- oder ausführliche Logging, falls das Dashboard dies anbietet.
6. Öffnen Sie die DevTools und überprüfen Sie den Netzwerk-Tab. Bestätigen Sie, dass das SeaText-Skript 200 zurückgibt.
7. Untersuchen Sie das Skript-Tag. Es sollte das Attribut async enthalten.
8. Öffnen Sie die Konsole. Suchen Sie nach CSP-, CORS- oder JavaScript-Fehlern.
9. Öffnen Sie den Anwendungs-Tab. Bestätigen Sie, dass der lokale Speicher eine SeaText-ID enthält.
10. Navigieren Sie durch jede Route in der Routenkarte. Verwenden Sie nicht nur typische Routen.
11. Simulieren Sie eine Sprachumschaltung auf mindestens einer tiefen Route. Der Text sollte sich ohne vollständiges Neuladen ändern.
12. Überprüfen Sie das SeaText-Dashboard. Bestätigen Sie, dass Varianten und Ereignisse aufgezeichnet wurden.

Behandeln Sie jede Prüfung als bestanden oder nicht bestanden. Wenn eine fehlschlägt, fahren Sie nicht mit dem nächsten Schritt fort, bis Sie den Grund verstehen.

Checkliste für die Routenabdeckung und Beispiel-Cypress-Skript

Eine Routenkarte ist die Liste der URLs, die Ihre SPA anzeigen kann. Sie ist die Quelle der Wahrheit für Tests. Beginnen Sie mit den Links in Ihrer Navigation und fügen Sie dann Routen aus Kampagnen und E-Mails hinzu.

Hören Sie nicht bei Startseite, Produkt und Kasse auf. Tiefe Routen verbergen oft Probleme. Zum Beispiel kann eine Kontoseite zusätzliche Header senden, die CORS auslösen.

Ersetzen Sie die Beispielrouten durch Ihre eigenen. Wichtig ist, dass jede Produktionsroute im Test erscheint.

Führen Sie nach der Tabelle das unten stehende Cypress-Skript aus. Es besucht jede Route und prüft auf die SeaText-Netzwerkanfrage.

describe('SeaText SPA Routenabdeckung', () => {
  const routes = ['/', '/products/sample', '/pricing', '/checkout', '/account', '/blog/sample', '/missing-route'];

  it('lädt das SeaText-Skript auf jeder Route', () => {
    cy.intercept('**/*seatext*').as('seatextScript');
    routes.forEach(route => {
      cy.visit(Cypress.env('STAGING_URL') + route);
      cy.wait('@seatextScript').its('response.statusCode').should('eq', 200);
    });
  });

  it('speichert eine SeaText-ID im lokalen Speicher', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.window().then(win => {
      const keys = Object.keys(win.localStorage).filter(k => k.toLowerCase().includes('seatext'));
      expect(keys.length).to.be.greaterThan(0);
    });
  });

  it('aktualisiert Text bei Sprachumschaltung', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.get('[data-seatext-lang=es]').click();
    cy.contains('¡Bienvenido!').should('be.visible');
  });
});

Hypothetisches Szenario: ein React-Staging-Lauf

Stellen Sie sich Lena vor, eine Frontend-Entwicklerin. Sie muss einen React-Store mit SeaText starten. Sie beginnt mit einem produktionsähnlichen Staging-Build.

Sie öffnet public/index.html und fügt SEATEXTCODEINTEGRATION vor dem schließenden Body-Tag ein. Dann führt sie npm run build aus und stellt die Ausgabe unter https://staging.example.com bereit.

In den DevTools filtert sie den Netzwerk-Tab nach seatext. Das Skript gibt 200 zurück. Das Skript-Tag im Elements-Panel hat das Attribut async.

Sie öffnet den Anwendungs-Tab und findet einen lokalen Speicher-Schlüssel, der eine SeaText-ID enthält. Sie navigiert durch die Routenkarte. Die ID bleibt auf jeder Route im lokalen Speicher.

Als nächstes klickt sie auf einer Produktseite auf den spanischen Sprachbutton. Die Überschrift ändert sich zu „¡Bienvenido!“ ohne Neuladen. Die URL ändert sich nicht.

Sie führt dann die Cypress-Suite gegen alle Routen aus. Eine Route schlägt fehl, weil der Staging-Server einen 404 für eine clientseitige Route zurückgibt. Sie korrigiert das Server-Fallback, um index.html bereitzustellen, und führt den Test erneut aus.

Die Suite besteht. Das SeaText-Dashboard zeigt aufgezeichnete Varianten. Lena veröffentlicht das Snippet.

Kompromisse und Einschränkungen

Asynchrones Laden verbessert die Leistung, kann aber zu einer kurzen Verzögerung führen. Benutzer sehen möglicherweise kurz den Originaltext, bevor SeaText Änderungen anwendet. Das ist ein Kompromiss, kein Fehler.

Der lokale Speicher ist nicht garantiert. Einige Browser blockieren ihn im privaten Modus oder wenn Speicher von Drittanbietern eingeschränkt ist. Ihre App muss die Berechtigung haben, auf den lokalen Speicher zuzugreifen.

Cross-Origin-Anfragen können fehlschlagen. Wenn Ihre SPA mehrere Domains aufruft, überprüfen Sie die Konsole auf CORS-Fehler. Die SeaText-Dokumentation warnt davor.

Staging-Apps verwenden oft eine Content Security Policy (CSP). Eine strikte CSP kann das SeaText-Skript blockieren. Fügen Sie die benötigte Domain Ihrer Zulassungsliste hinzu und überprüfen Sie dies.

Framework-Einstiegspunkte sind nicht identisch. React, Vue und Angular haben jeweils eine andere Dateistruktur. Bestätigen Sie, wo Ihr Framework initialisiert wird, bevor Sie das Snippet einfügen.

Staging muss das Produktions-Routing widerspiegeln. Wenn der Staging-Server für clientseitige Routen nicht index.html zurückgibt, schlagen Routentests aus dem falschen Grund fehl.

KI-Ausgaben sind variabel. Schreiben Sie keine Tests, die für immer exakten Text erwarten. Stellen Sie sicher, dass Inhaltselemente existieren und Text enthalten.

Kriterien für das Bestehen: Alle Routen geben 200 für das Skript zurück, keine Konsolenfehler, lokale Speicher-ID erscheint, Sprachumschaltung funktioniert und das Dashboard zeichnet eine Variante auf. Wenn einer dieser Punkte fehlschlägt, blockieren Sie den Start, bis er behoben ist.

Fehlerbehebung bei häufigen Ausfällen

Nutzen Sie die DevTools als erste Anlaufstelle. Die Konsolen- und Netzwerk-Tabs geben normalerweise das genaue Problem an.

• Skript lädt nicht. Überprüfen Sie den Netzwerk-Tab auf einen 404 oder eine fehlgeschlagene Anfrage. Überprüfen Sie die Skript-URL, DNS- und Firewall-Regeln.
• Lokale Speicher-ID fehlt. Bestätigen Sie, dass das Skript ausgeführt wurde. Überprüfen Sie Speicherberechtigungen und blockierte Speichermodi.
• CORS-Fehler tritt auf. Lesen Sie die vollständige Konsolenmeldung. Überprüfen Sie die Antwort-Header auf Access-Control-Allow-Origin.
• CSP blockiert das Skript. Suchen Sie nach einer Refused to load-Meldung. Aktualisieren Sie die Sicherheitsrichtlinie und führen Sie sie erneut aus.
• Sprachumschaltung bewirkt nichts. Bestätigen Sie, dass der Button den erwarteten Selektor verwendet. Überprüfen Sie, ob die Übersetzung für diese Route aktiv ist.
• Tests bestehen im Staging, schlagen aber in der Produktion fehl. Vergleichen Sie Routenkarten, Umgebungsvariablen und Build-Einstellungen.
• Das Skript lädt, aber der Text ändert sich nie. Öffnen Sie das Dashboard, um zu sehen, ob eine Variante aufgezeichnet wurde. Wenn nicht, überprüfen Sie die Agentenkonfiguration.

FAQ

• Muss das SeaText-Snippet in jeder Seitendatei vorhanden sein? Nein. Fügen Sie es einmal zum HTML-Einstiegspunkt oder zur Framework-Initialisierungsdatei hinzu.
• Sollte ich einen Produktions-Build für Staging-Tests verwenden? Ja. Die Build-Befehle sollten mit der Produktion übereinstimmen.
• Woher weiß ich, dass das Skript asynchron ist? Untersuchen Sie das Skript-Tag in den DevTools. Es sollte das Attribut async enthalten.
• Warum gibt mein Routentest einen 404 zurück? Der Staging-Server hat wahrscheinlich kein SPA-Fallback. Konfigurieren Sie ihn so, dass er index.html für clientseitige Routen bereitstellt.
• Kann ich Playwright anstelle von Cypress verwenden? Ja. Die Routenabdeckung und die Prüfungen sind dieselben.
• Was ist, wenn ein Test lokal besteht, aber in der Staging-Pipeline fehlschlägt? Vergleichen Sie URL, Umgebungsvariablen und die exakte Build-Ausgabe.