Wie fügt man eine Full-Page UI-Extension zu Shopify Customer Accounts hinzu?

Um eine Full-Page-UI-Extension zu Shopify Customer Accounts hinzuzufügen, erstellen Sie eine eigene Extension mit dem Target customer-account.page.render und veröffentlichen sie mit shopify app deploy. Das reicht nicht: Bis Sie die Seite im Editor unter Einstellungen > Kundenkonten > Anpassen hinzufügen und veröffentlichen, erscheint der Fehler „There's a problem loading this page“. Ein Full-Page-Target braucht eine eigene Extension.

In diesem Leitfaden teilen wir, was wir bei Nodus Works beim Bau einer Full-Page-UI-Extension für die neuen Shopify-Kundenkonten aus erster Hand gelernt haben. Wir beschreiben den Weg von der Einrichtung bis zum Go-live, gehen auf die Fehler ein, auf die wir tatsächlich gestoßen sind, und zeigen mit Codebeispielen, wie wir sie gelöst haben. Grundlage ist unsere eigene Implementierung einer Full-Page-Extension für Kundenkonten im Produktivbetrieb.

Warum ist eine vollflächige UI-Extension erforderlich?

Shopifys neue Kundenkonten bieten vorgefertigte Seiten wie Bestellungen, Profil und Adressen. Für Szenarien wie Treueprogramme, Wunschlisten, Abonnementverwaltungen oder ein eigenständiges „Impact-Dashboard“ reichen diese Standardblöcke jedoch nicht aus. Dafür sieht Shopify Full-Page-UI-Extensions mit dem Target customer-account.page.render vor.

Was sind UI-Extensions und Targets?

Eine UI-Extension ist ein Modul, das Code an bestimmten Stellen der Kundenkonto-Oberfläche einbindet; das Target legt fest, wo dieser Code erscheint. Block-Targets werden in bestehende Seiten eingefügt, ein Full-Page-Target erstellt dagegen eine komplett neue Route. Die folgende Tabelle fasst die Unterschiede zwischen den beiden Target-Typen zusammen.

Wichtiger Hinweis: Ein Full-Page-Target kann nicht zusammen mit anderen Targets in derselben Extension stehen. Legen Sie für Ihre ganzseitige Ansicht eine eigene Extension an; wenn Sie ein Full-Page-Target in eine bestehende Block-Extension einbauen, erhalten Sie einen Konfigurationsfehler.

Schritt-für-Schritt-Einrichtung: Wie erstellt man eine Extension?

Für die Erstellung einer Extension sind zwei Dateien erforderlich: die Konfigurationsdatei und die Seitenkomponente. Ein Full-Page-Target muss in einer eigenen Extension definiert werden.

api_version = "2026-04"

[[extensions]]

name = "Impact Page"

handle = "impact-page"

type = "ui_extension"

  [[extensions.targeting]]

  module = "./src/FullPage.jsx"

  target = "customer-account.page.render"
Anschließend wird eine minimale Seitenkomponente definiert. Der kritische Punkt ist: Es ist zwingend erforderlich, die von Shopify bereitgestellten Webkomponenten (wie s-page, s-section, s-grid) zu verwenden und kein Standard-HTML. Der Host lehnt die gesamte Seite ab, wenn er einen unzulässigen Knoten erkennt.
import "@shopify/ui-extensions/preact";

import { render } from "preact";

export default () => {

  render(<MyPage />, document.body);

};

function MyPage() {

  return (

    <s-page heading="Impact">

      <s-section>

        <s-text>Loading…</s-text>

      </s-section>

    </s-page>

  );

}

Wie wird die Extension bereitgestellt (Deploy)?

Der Extension-Code wird nicht auf Ihrem eigenen Server gehostet; wenn Sie den Befehl shopify app deploy ausführen, kompiliert Shopify den Code und stellt ihn auf seiner eigenen Infrastruktur bereit.

shopify app deploy

Der Befehl fragt, ob eine neue Version veröffentlicht werden soll; sobald Sie dies bestätigen, geht die Extension live. Bis hierhin läuft alles wie in der Dokumentation beschrieben; die eigentlichen Lektionen kommen erst nach dem Deployment.

Wie erstellt man eine neue Seite unter „Mein Konto“? (Aktivierungsschritte)

Nach dem Deployment einer Full-Page-Extension ist die Seite im Menü „Mein Konto“ (Customer Accounts) noch weder sichtbar noch funktionsfähig; damit sie aktiv wird, müssen Sie sie separat über den Editor für Kundenkonten hinzufügen. Dieser Schritt ist völlig unabhängig vom Deployment.

1. Gehen Sie im Shopify-Admin zu Einstellungen → Kundenkonten.
2. Klicken Sie oben rechts auf Anpassen; es öffnet sich ein Editor, der dem Theme-Editor ähnelt.
3. Fügen Sie im Editor über den Bereich für Apps/Extensions die betreffende Full-Page-Extension hinzu.
4. Der Editor bietet automatisch an, die Seite ins Kopfzeilenmenü aufzunehmen; bestätigen Sie das.
5. Klicken Sie abschließend auf Speichern / Veröffentlichen.

Typische Falle: Es reicht nicht, die Extension nur bereitzustellen (deploy) und von Hand einen Link ins Navigationsmenü zu setzen. Die Seite wird weiterhin den Fehler "There's a problem loading this page" anzeigen, solange sie nicht über den Kundenkonto-Editor hinzugefügt und aktiviert wurde; diese beiden Schritte (Deployment und Aktivierung) sind voneinander unabhängig.

Warum tritt der Fehler "There's a Problem Loading This Page" auf?

Dieser Fehler tritt auf, wenn der oben genannte Aktivierungsschritt übersprungen wird, selbst wenn die Extension erfolgreich bereitgestellt und der Link im Navigationsmenü hinzugefügt wurde; dies ist die zeitaufwendigste Fehlerquelle. In der Browser-Konsole finden sich keine JavaScript-Fehler der Extension, sondern lediglich irrelevante Warnungen zu Analytics und CSP. Dies deutet darauf hin, dass das Problem nicht in der Rendering-Phase liegt, sondern bei der Auflösung (Resolution) der Seite.

Weitere häufige Fehler und Fehldiagnosen

Neben Deployment und Aktivierung gibt es vier weitere Situationen, die bei der Diagnose Zeit kosten. Die folgende Tabelle fasst die tatsächliche Ursache und den korrekten Diagnoseansatz für jeden Fall zusammen.

Am schnellsten kommen Sie zur richtigen Diagnose, wenn Sie die Seite auf ein minimales "Hello World" reduzieren und so nachweisen, dass das Problem nicht im Code, sondern in der Aktivierung liegt.

Self-Service-Content-Management für Shop-Betreiber

Nachdem die Seite funktioniert, ist der nächste logische Schritt, die Texte in die Extension-Einstellungen zu verschieben, damit der Shop-Betreiber sie ohne Entwickler bearbeiten kann. Die Felder werden in der Konfigurationsdatei definiert.

[extensions.settings]

    [[extensions.settings.fields]]

    key = "heading"

    type = "single_line_text_field"

    name = "Seitentitel"

    [[extensions.settings.fields]]

    key = "intro"

    type = "multi_line_text_field"

    name = "Einleitungstext"

Im Code werden diese Werte über ein Signal ausgelesen und in Echtzeit aktualisiert; ist ein Feld leer, greift der im Code definierte Standardwert.

const settings = globalThis.shopify?.settings?.current ?? {};

const heading = settings.heading?.trim() || "Standardüberschrift";

So kann der Shop-Betreiber alltägliche Textänderungen selbst im Editor vornehmen; nur strukturelle Änderungen erfordern ein neues Deployment.

Architektur: Ist ein separater Backend-Server erforderlich?

Nein, für Full-Page-UI-Extensions sind kein separates Backend und kein Hosting erforderlich. Sobald Sie das Deployment durchführen, kompiliert Shopify den Code und stellt ihn über das eigene CDN bereit; die Seite läuft innerhalb der Kundenkonten und übernimmt das Branding des Shops. Die Wartungskosten sind im Vergleich zu einem herkömmlichen Anwendungsserver deutlich geringer, da keine Serverkapazitäten geplant, aktualisiert oder überwacht werden müssen.

Schnell-Checkliste

• Erstellen Sie für das Full-Page-Target eine eigene Extension.
• Verwenden Sie ausschließlich offizielle Web-Komponenten; nutzen Sie kein Standard-HTML.
• Veröffentlichen Sie die neue Version mit shopify app deploy.
• Die Seite muss zwingend über den Editor für Kundenkonten hinzugefügt und aktiviert werden; ein bloßer Link im Menü reicht nicht aus.
• Schreiben Sie den Menü-Link nicht manuell, sondern wählen Sie ihn über den Editor bzw. die Auswahlfunktion als App-Seite aus.
• Unterscheiden Sie in der Konsole zwischen Analytics-/CSP-Rauschen und tatsächlichen Fehlern.
• Verlagern Sie Texte in Einstellungsfelder, damit der Shop-Betreiber die Inhalte selbst pflegen kann.

Individuelle UI-Extensions wie diese gehen über die übliche Theme-Anpassung hinaus und sind eine Integration auf Code-Ebene. Unser Service für Shopify-Integrationslösungen übernimmt plattformweite Anpassungen wie Kundenkonten komplett, einschließlich aller Deployment- und Aktivierungsschritte. Für die schnelle Diagnose von Fehlern wie "problem loading page" nach der Veröffentlichung steht unser technischer Support- und Wartungsservice für Shopify mit umfassender Praxiserfahrung bereit.

Häufig gestellte Fragen

Was bedeutet die Fehlermeldung "There's a problem loading this page"?

Dieser Fehler tritt auf, wenn die Seite zwar erfolgreich bereitgestellt (deployed), aber nicht über den Editor für Kundenkonten hinzugefügt und aktiviert wurde. Deployment und Aktivierung sind zwei unabhängige Schritte; der erste allein reicht nicht aus.

Was ist der Unterschied zwischen einer Vollseiten-Extension und einer Block-Extension?

Eine Block-Extension ist eine kleine Komponente, die in eine bestehende Seite (Bestellungen, Profil usw.) eingefügt wird und in derselben Extension mit anderen Targets kombiniert werden kann. Eine Full-Page-Extension erstellt dagegen mit dem Target customer-account.page.render eine eigene neue Route und braucht eine separate Extension.

Muss ich für eine Vollseiten-Extension einen separaten Backend-Server einrichten?

Nein. Shopify kompiliert und hostet den bereitgestellten Code über sein eigenes CDN. Sie brauchen weder separates Hosting noch eine Serververwaltung; der Wartungsaufwand ist daher deutlich geringer als bei einem herkömmlichen Anwendungsserver.

Wie füge ich den Menü-Link hinzu?

Geben Sie Links nicht manuell ein; eine manuell zum Navigationsmenü hinzugefügte /pages/<id>-Adresse führt zu einem ungültigen Link. Die korrekte Adresse wird automatisch vom App-Seitenauswähler im Editor für Kundenkonten generiert.

Kann ich Seitentexte ändern, ohne ein Deployment durchzuführen?

Ja, wenn die Texte in Einstellungsfelder wie single_line_text_field oder multi_line_text_field verschoben wurden, kann der Shop-Betreiber sie direkt im Editor anpassen. Nur strukturelle Änderungen (Komponenten, Logik) erfordern ein neues Deployment.

Fazit

Eine ganze eigene Seite in den neuen Shopify-Kundenkonten wirkt technisch einfach; in der Praxis kostet aber das Problem „Ich habe es deployed, aber es lädt nicht“ die meiste Zeit. Die wichtigste Lektion lautet: Das Veröffentlichen einer Full-Page-Extension und deren Aktivierung im Editor für Kundenkonten sind zwei separate Schritte. Sobald Sie das verinnerlicht haben, werden die übrigen Punkte (Auswahl der Komponenten, Deployment und editierbare Texte) zu einem klaren, wiederholbaren Ablauf. Shopify aktualisiert gelegentlich die Benutzeroberfläche und Versionsdetails; daher empfehlen wir, diesen Leitfaden stets in Verbindung mit der offiziellen Dokumentation zu verwenden.

Wenn Sie eine benutzerdefinierte Seite für Kundenkonten in Ihrem eigenen Shopify-Shop entwickeln oder ein ähnliches Aktivierungsproblem bei einer bestehenden Extension lösen möchten, können Sie sich bezüglich unserer Integrationslösungen mit unserem Team in Verbindung setzen.