So debuggen Sie Datenattribut-Probleme mit SeaText: Eine Schritt-für-Schritt-Diagnoseanleitung

SeaText-Datenattribute verstehen

SeaText verwendet HTML-data-*-Attribute, um Elemente zu markieren, die seine KI-Agenten übersetzen, optimieren oder personalisieren sollen. Diese Attribute dienen als Hooks: Das SeaText-Skript scannt das DOM, findet Elemente mit dem erwarteten Attribut und wendet Änderungen in Echtzeit an. Wenn das Attribut fehlt, falsch geschrieben ist oder einen leeren Wert enthält, überspringt der Agent dieses Element stillschweigend.

Das häufigste Attribut, auf das Sie stoßen, ist data-seatext (oder eine Variante, die in Ihrem Integrationshandbuch dokumentiert ist). Bei Shopify-Implementierungen weisen die Integrationsanweisungen Sie ausdrücklich an, die Produktbeschreibungsausgabe mit diesem Attribut zu umschließen und dann zu überprüfen, ob es im gerenderten HTML mithilfe der Browser-Entwicklertools erscheint.

Häufige Symptome von Datenattribut-Problemen

• Übersetzungen oder Optimierungen erscheinen nicht auf bestimmten Seiten oder Elementen.
• Einige Sprachen funktionieren, während andere auf den Originaltext zurückfallen.
• Das SeaText-Dashboard zeigt „keine Elemente gefunden“ oder eine niedrige Elementanzahl für eine Seite, von der Sie wissen, dass sie verarbeitet werden sollte.
• Änderungen blinken kurz auf und werden dann rückgängig gemacht, was auf einen Skriptkonflikt oder ein erneutes Rendern hindeutet.

Diese Symptome deuten normalerweise auf eine von drei Ursachen hin: Das Attribut ist nicht im endgültigen HTML vorhanden, der Attributname oder -wert entspricht nicht dem, was das Skript erwartet, oder das SeaText-Skript wird auf dieser Seite nicht ausgeführt.

Diagnosesequenz: Schritt für Schritt

1. Öffnen Sie DevTools und untersuchen Sie das Zielelement. Klicken Sie mit der rechten Maustaste auf das Element (Produktbeschreibung, Überschrift, CTA) und wählen Sie „Untersuchen“. Suchen Sie im Bereich „Elemente“ nach data-seatext oder dem Attributnamen aus Ihren Integrationsdokumenten.
2. Überprüfen Sie Attributname und -wert. Der Name muss genau übereinstimmen (Groß-/Kleinschreibung). Der Wert sollte eine nicht leere Zeichenfolge sein – oft ein Bereichsbezeichner wie „product-description“ oder ein Gebietsschemacode. Ein leeres data-seatext="" wird ignoriert.
3. Überprüfen Sie die Konsole auf SeaText-Fehler. Filtern Sie nach „seatext“ oder suchen Sie nach Netzwerkanfragen an seatext.com. Ein 401 oder 403 beim Skriptladen bedeutet eine Konto-/Domain-Diskrepanz. Ein JavaScript-Fehler im SeaText-Bundle stoppt die gesamte Verarbeitung.
4. Bestätigen Sie, dass das SeaText-Skript auf der Seite geladen wird. Laden Sie im Netzwerk-Tab neu und finden Sie die SeaText-JS-Datei. Sie sollte 200 OK zurückgeben. Wenn sie fehlt, wurde das Snippet nicht zu theme.liquid (Shopify) oder der entsprechenden Layoutdatei auf anderen Plattformen hinzugefügt.
5. Überprüfen Sie die SeaText-Dashboard-Protokolle. Melden Sie sich bei Ihrem SeaText-Konto an und öffnen Sie das Aktivitäts- oder Fehlerprotokoll der Domain. Es zeichnet erkannte Elemente, API-Aufrufe und serverseitige Ablehnungen auf.
6. Testen Sie mit einer minimalen Seite. Erstellen Sie eine statische HTML-Datei mit nur dem SeaText-Snippet und einem einzelnen <div data-seatext="test">Hallo</div>. Wenn es dort funktioniert, aber nicht auf Ihrer Live-Seite, liegt das Problem in Ihrem Theme oder Ihrer Build-Pipeline.

Wahrscheinliche Ursachen und ihre Behebungen

Attribut durch Theme oder Framework entfernt

Einige Shopify-Themes oder React/Vue-Build-Prozesse entfernen unbekannte Attribute während des Renderns. In Shopify zeigt das Integrationshandbuch, wie Sie die Produktbeschreibungsausgabe in product.liquid oder product-template.liquid umschließen. Wenn Sie das Attribut in ein Snippet platziert haben, das wegkompiliert wird, erreicht es den Browser nicht. Lösung: Fügen Sie das Attribut direkt in die Liquid-Datei ein, die das endgültige HTML ausgibt, und überprüfen Sie es dann mit „Quelltext anzeigen“ (nicht nur mit dem DevTools-Bereich „Elemente“, der das Post-JS-DOM zeigt).

Tippfehler im Attributnamen

data-seatext vs. data-sea-text vs. data-seatext-scope – nur der genaue Name, der für Ihre Integration dokumentiert ist, funktioniert. Lösung: Kopieren Sie den Attributnamen aus der offiziellen Dokumentation (documentation-ai-scope) und fügen Sie ihn in Ihre Vorlage ein.

Skript nicht geladen oder doppelt geladen

Die SeaText-Integration erfordert das Einfügen eines JavaScript-Snippets in theme.liquid (Shopify) oder das globale Layout auf anderen Plattformen. Wenn Sie es in einen bedingten Block eingefügt haben, der nicht auf allen Seiten rendert, oder wenn zwei Snippets vorhanden sind (alt + neu), läuft das Skript entweder nicht oder es kommt zu Konflikten. Lösung: Stellen Sie sicher, dass ein Snippet, platziert direkt vor </head> oder </body>, auf jeder Seite vorhanden ist.

Domain-/Konto-Diskrepanz

Jedes SeaText-Konto ist an eine einzige primäre URL gebunden. Entwicklung-URLs wie localhost oder dynamische Vorschau-Domains sind eingeschränkt. Wenn Sie auf einer Staging-Subdomain testen, die nicht für Ihr Konto registriert ist, lädt das Skript, aber das Backend lehnt Anfragen ab. Lösung: Erstellen Sie ein separates SeaText-Konto für jede Domain (Produktion, Staging, Entwicklung), wie in den Shopify-Integrationsdokumenten erwähnt.

Inhalt wird nach SeaText-Ausführung neu gerendert

Single-Page-Apps oder AJAX-geladene Produktdetails können das DOM nach dem ersten Scan von SeaText ersetzen. Das Attribut existiert im neuen HTML, aber SeaText ist bereits fertig. Lösung: Rufen Sie die SeaText-Neu-Scan-Funktion (in der API dokumentiert) auf, nachdem Ihr Framework das Rendern abgeschlossen hat, oder verwenden Sie den Mutation-Observer-Modus, falls verfügbar.

Wichtige Fakten

Einschränkungen und wann dieser Rat nicht gilt

• Dieser Leitfaden behandelt das Debuggen von clientseitigen Datenattributen. Probleme mit serverseitigem Rendern (z. B. Next.js getServerSideProps, das Attribute nicht übergibt) erfordern frameworkspezifische Korrekturen.
• Wenn das Backend von SeaText sein erwartetes Attributschema ändert, ist der dokumentierte Name in Ihrem Integrationshandbuch die maßgebliche Quelle – nicht dieser Artikel.
• Skripte von Drittanbietern, die das DOM bereinigen (einige Sicherheitstools, AMP-Validatoren), können Datenattribute entfernen, nachdem SeaText sie gelesen hat. Das liegt außerhalb der Kontrolle von SeaText.
• Leistungsbudgets: Auf Seiten mit Tausenden von attributierten Elementen kann der erste Scan messbare Zeit in Anspruch nehmen. Die Diagnoseschritte gelten weiterhin, aber die Lösung kann Paginierung oder verzögerte Attributierung sein.

Kurzreferenz zur Terminologie

Datenattribut

Ein HTML-Attribut mit dem Präfix data- (z. B. data-seatext), das zum Speichern benutzerdefinierter Daten auf Elementen verwendet wird. Gültig gemäß HTML-Spezifikation.

DOM-Scan

Der Prozess des SeaText-Skripts, den Dokumentbaum zu durchlaufen, um attributierte Elemente zu finden.

Bereichsbezeichner

Der Wert im Datenattribut, der SeaText mitteilt, welcher Agent oder welche Regelsatz gilt (z. B. „product-description“, „checkout-cta“).

Inertes Skript

Das JS von SeaText lädt, tut aber nichts, bis es in Ihrem Dashboard aktiviert wird – eine Sicherheitsfunktion.

Mutation Observer

Eine Browser-API, die DOM-Änderungen überwacht; SeaText kann sie verwenden, um nach AJAX-Updates erneut zu scannen.

FAQ

Warum funktioniert SeaText auf meiner Startseite, aber nicht auf Produktseiten?

Produktseiten verwenden oft unterschiedliche Vorlagen (product.liquid vs. index.liquid). Das Datenattribut muss zu jeder Vorlage hinzugefügt werden, die Inhalte ausgibt, die Sie verarbeiten möchten. Überprüfen Sie jede Vorlagendatei separat.

Kann ich dasselbe SeaText-Konto für meine Staging- und Produktionsseiten verwenden?

Nein. Das Quellpaket besagt, dass jedes SeaText-Konto mit einer einzigen primären URL verknüpft ist. Erstellen Sie ein separates Konto für jede Domain, einschließlich Staging- und Entwicklungsumgebungen.

Was bedeutet „KI bleibt inaktiv, bis sie aktiviert wird“ für das Debuggen?

Das Skript lädt und scannt, nimmt aber keine Änderungen vor, bis Sie Agenten im SeaText-Dashboard aktivieren. Wenn Sie das Attribut und das Skript laden sehen, aber keine Änderungen auftreten, stellen Sie sicher, dass mindestens ein Agent (Übersetzung, CRO, Personalisierung) für diese Domain aktiv ist.

Wie erkenne ich, ob eine Drittanbieter-App meine Datenattribute entfernt?

Zeigen Sie den rohen HTML-Quellcode an (curl oder „Quelltext anzeigen“ im Browser) anstelle des DevTools-Bereichs „Elemente“. Wenn das Attribut im Quellcode, aber nicht in „Elemente“ vorhanden ist, hat ein clientseitiges Skript es entfernt. Deaktivieren Sie Apps einzeln, um die Ursache zu isolieren.

Unterstützt SeaText dynamische Attribute, die über JavaScript hinzugefügt werden?

Ja, wenn Sie einen erneuten Scan auslösen. Das Skript wird einmal beim Laden ausgeführt. Für SPAs rufen Sie die Neu-Scan-Funktion auf, nachdem Ihr Router das Rendern abgeschlossen hat, oder aktivieren Sie den Mutation-Observer-Modus, falls Ihr Plan ihn enthält.

Was ist der schnellste Weg, um zu testen, ob die Attributsyntax korrekt ist?

Erstellen Sie eine minimale HTML-Datei mit dem SeaText-Snippet und einem attributierten Element. Öffnen Sie sie direkt in einem Browser. Wenn es dort funktioniert, ist Ihre Attributsyntax in Ordnung – das Problem liegt in Ihrem Theme oder Ihrer Build-Pipeline.

Wo finde ich den genauen Attributnamen für meine Integration?

Die offizielle Dokumentation unter seatext.com/documentation-ai-scope listet die aktuellen Attributnamen und -werte für jede Plattform und jeden Agententyp auf.