> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.de/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Eine App-Karte (BETA) erstellen
> Erfahren Sie, wie Sie eine App-Karte auf der neuesten Version der Entwicklerplattform (BETA) erstellen.
Sie können eine React-basierte App-Karte für Projekte mit der neuesten Version (`2025.2`) der Entwicklerplattform erstellen. App-Karten funktionieren ähnlich wie vorhandene Karten, die Sie [möglicherweise für ältere Apps erstellt](/apps/developer-platform/add-features/ui-extensibility/app-cards/reference) haben, allerdings mit einigen geringfügigen Änderungen an Ihren Konfigurationsdateien.
In dieser Anleitung erfahren Sie, wie Sie eine Boilerplate-App-Karte in einer vorhandenen App erstellen und sie in HubSpot hochladen und in der Vorschau ansehen können. Anschließend laden Sie alle diese Dateien in Ihr Projekt hoch, wo Sie eine Vorschau der Karte in einem Entwickler-Test-Account, in dem Sie Ihre App installiert haben, angezeigt bekommen.
## Voraussetzungen
* Vergewissern Sie sich, dass Sie die neueste Beta-Version des [HubSpot CLI](/developer-tooling/local-development/hubspot-cli/install-the-cli) installiert haben.
* Wenn dies noch nicht geschehen ist, [erstellen Sie eine App](/getting-started/quickstart).
* Es wird empfohlen, [einen konfigurierbaren Test-Account einzurichten](/developer-tooling/local-development/configurable-test-accounts), damit Sie in einer isolierten Umgebung erstellen und testen können.
## Eine App-Karte erstellen
Um Ihrem Projekt eine neue App-Kartenkomponente hinzuzufügen, gehen Sie mit dem Terminal in Ihr lokales Projektverzeichnis, und führen dann den folgenden Befehl aus:
```shell theme={null}
hs project add
```
Sobald Sie aufgefordert werden, eine hinzuzufügende Komponente auszuwählen, klicken Sie auf **Karte**.
Falls Ihr Projekt noch keine App-Karten enthält, wird ein `cards/`-Verzeichnis für Sie in diesem `app/`-Verzeichnis erstellt. Das `cards/`-Verzeichnis enthält:
* Eine JSON-Kartenkonfigurationsdatei (`*-hsmeta.json`)
* Eine React-Komponentendatei (`.jsx`)
* Eine `package.json`-Datei
Wenn Ihr Projekt bereits App-Karten enthält, werden die oben genannten Dateien dem vorhandenen `cards/`-Verzeichnis hinzugefügt (es sei denn `package.json`, es existiert bereits).
```shell theme={null}
myProject
└── src/
└── app/
└── cards/
├── NewCard-hsmeta.json
├── NewCard.jsx
└── package.json
```
Erfahren Sie in der [Referenzdokumentation für App-Karten](/apps/developer-platform/add-features/ui-extensibility/app-cards/reference) mehr über diese Dateien.
So laden Sie die neue Karte in Ihren HubSpot-Account hoch:
* Führen Sie `hs project install-deps` aus, um die für die App-Karte erforderlichen Abhängigkeiten zu installieren. Dadurch wird das `cards/`-Verzeichnis mit den erforderlichen Node-Modulen und einer `package-lock.json`-Datei aktualisiert, wodurch der Build der hochgeladenen App-Kartenerweiterung beschleunigt und sichergestellt wird, dass alle Abhängigkeiten in Ihrer lokalen Entwicklungsumgebung und Ihrem Produktions-Account übereinstimmen.
* Führen Sie dann `hs project upload` aus, um das Projekt in Ihrem Standard-Account hochzuladen.
* Um einen anderen Account anzugeben (z. B. einen separaten Test-Account), fügen Sie den `--account`-Tag ein und geben Sie die HubID des Accounts an; zum Beispiel: `hs project upload --account 123456`.
* Wenn das Projekt noch nicht hochgeladen wurde, werden Sie aufgefordert zu bestätigen, dass Sie das Projekt in Ihrem Account erstellen möchten. Andernfalls zeigt das Terminal zuerst den Erstellungs- und Bereitstellungsstatus an und bestätigt erst dann, wenn das Projekt erfolgreich hochgeladen wurde.
## Die Karte in HubSpot anzeigen
Nachdem Sie das Projekt hochgeladen haben, können Sie es in HubSpot anzeigen, indem Sie `hs project open`ausführen. Es öffnet sich eine Browser-Registerkarte zur Projektdetailseite, auf der Sie Ihr Projekt, Ihre App und ihre neue Kartenkomponente sehen können.
Wenn Sie die App noch nicht im Account installiert haben, müssen Sie dies tun, bevor Sie die Karte anschauen können. Für die Installation der App:
* Klicken Sie in der Projektzusammenfassung auf der linken Seite oder unter *Projektkomponenten* auf den **Namen** der App.
* Klicken Sie auf die Registerkarte **Verteilung**.
* Dann klicken Sie auf **Jetzt installieren**.
Die von `hs project add` erstellte Boilerplate-App-Karte ist so konfiguriert, dass sie in der mittleren Spalte von Kontaktdatensätzen angezeigt wird. Um die Karte anzuzeigen, müssen Sie sie zunächst der Ansicht des Kontaktdatensatzes hinzufügen:
* Gehen Sie in Ihrem HubSpot-Account zu **CRM** > **Kontakte**.
* Klicken Sie auf den **Namen** eines Kontakts.
* Dann klicken Sie oben in der mittleren Spalte des Kontaktdatensatzes auf **Anpassen**.
* Klicken Sie auf **Standardansicht**.
* Wählen Sie die **Registerkarte** aus, der Sie die Karte hinzufügen möchten. Bewegen Sie dann den Mauszeiger über die Stelle, an der Sie die Karte platzieren wollen, und klicken Sie auf das **Pluszeichen**. Dies kann nach der Ersteinrichtung jederzeit angepasst werden.
* Klicken Sie im rechten Bereich auf die Registerkarte **Kartenbibliothek**. Klicken Sie dann auf das Dropdown-Menü für **Kartentypen** und wählen Sie **App** aus, um nach App-Karten zu filtern.
* Klicken Sie unter der von Ihnen erstellten App-Karte auf **Karte hinzufügen** und dann auf die Schaltfläche zum **Schließen** oben rechts in der Seitenleiste.
* Klicken Sie oben rechts auf **Speichern und beenden**.
Sie werden dann zurück zum Kontaktdatensatz weitergeleitet, in dem Ihre Karte jetzt angezeigt wird. Lassen Sie für den nächsten Schritt, wenn Sie den lokalen Entwicklungsserver starten, die Seite mit dem Kontaktdatensatz in Ihrem Browser geöffnet.
## Lokale Entwicklung einrichten
Nachdem Ihre App-Karte zu allen Kontaktdatensätzen hinzugefügt wurde, können Sie nun mit dem Erstellen der App-Karte fortfahren. Der einfachste Weg, schnell zu iterieren, besteht darin, den lokalen Entwicklungsserver mit dem `hs project dev`-Befehl zu starten:
* Führen Sie im Terminal `hs project dev` aus.
* Folgen Sie den Terminal-Anweisungen, um den **Account** auszuwählen, den Sie für die lokale Entwicklung verwenden möchten.
* Das Terminal startet den lokalen Entwicklungsserver und bestätigt dann, sobald alles funktioniert.
* Gehen Sie bei laufendem Server zurück zur Browser-Registerkarte mit dem Kontaktdatensatz und laden Sie die Seite neu.
Die App-Karte wird mit einem `Developing locally`-Tag angezeigt, was besagt, dass der lokale Entwicklungsserver bereit ist.
Der lokale Entwicklungsserver erkennt automatisch alle Änderungen, die in den Front-End-React-Dateien der App-Karte gespeichert sind (d. h. beliebige `.jsx`- oder `.tsx`-Dateien). Wenn Sie Änderungen an anderen Dateitypen vornehmen wollen, z. B. an einer `.json`-Konfigurationsdatei, müssen Sie das Projekt erneut hochladen und den lokalen Entwicklungsserver neu starten.
## Nächste Schritte
Schauen Sie sich die folgenden Ressourcen an, um das Erscheinungsbild und die Funktionalität der Karte zu erweitern.
* Lesen Sie die [Referenzdokumentation für UI-Erweiterungskomponenten](/apps/developer-platform/add-features/ui-extensibility/ui-components/overview), um der Karte weitere UI-Komponenten hinzuzufügen.
* Alle Konfigurationsoptionen für App-Karten sowie weitere Informationen finden Sie in der [Referenzdokumentation für App-Karten](/apps/developer-platform/add-features/ui-extensibility/app-cards/reference).
* Die [SDK-Referenz für UI-Erweiterungen](/apps/developer-platform/add-features/ui-extensibility/ui-extensions-sdk) enthält alles zu verfügbaren Dienstprogramme und Methoden für UI-Erweiterungen.
### Hinzufügen von hubspot.fetch()-Unterstützung
Um Aufrufe an Ihr Backend oder einen Drittanbieterdienst vorzunehmen, aktualisieren Sie bitte die `*-hsmeta.json`-[Konfigurationsdatei](/apps/developer-platform/build-apps/app-configuration) der App so, dass sie das `permittedUrls`-Feld enthält:
```json theme={null}
"permittedUrls": {
"fetch": ["https://api.example.com"],
"img": [],
"iframe": []
}
```
Das `permittedUrls`-Feld definiert eine Liste von URIs, auf die Ihre App zugreifen darf. Es fügt sowohl Ihrer App als auch HubSpot eine zusätzliche Sicherheitsebene hinzu, da Sie so explizit steuern können, mit welchen externen Ressourcen Ihre App zur Laufzeit interagieren kann.
Das `permittedUrls`-Feld ist ein Objekt mit einem bestimmten Satz unterstützter Eigenschaften, was bedeutet, dass Sie hier keine beliebigen Schlüssel übertragen können. Der wichtigste anzugebende Schlüssel ist `fetch`, der bestimmt, welche URLs über `hubspot.fetch` aufgerufen werden können. Dies entspricht dem `allowedUrls`-Feld, das beim Erstellen älterer öffentlicher Apps benutzt wurde.
Erfahren Sie hier mehr über die Verwendung von `hubspot.fetch` in der entsprechenden Dokumentation [hier](/apps/developer-platform/add-features/ui-extensibility/fetching-data#fetching-data-for-public-apps-beta).
## Eine zuvor erstellten App-Karte migrieren
Wenn Sie ein vorhandenes Projekt mit App-Karten auf die Entwicklerplattform migrieren müssen, lesen Sie bitte die folgenden Anleitungen:
* [Migration einer bestehenden öffentlichen App](/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-public-app)
* [Migration einer bestehenden privaten App](/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-private-app)
Wenn in Ihrem bestehenden Projekt eine Karte mit verbundenen benutzerdefinierten Objekten vorhanden ist, sollten Sie sich vergewissern, dass Sie vor der Migration über den `crm.objects.custom.read`-Bereich in Ihrer App verfügen. Bei Projekten, die vor der aktuellen Version `2025.2` erstellt wurden, war zur Erstellung von Karten mit benutzerdefinierten Objekten nur der `crm.schemas.custom.read`-Bereich nötig. In der neuesten Version (`2025.2`) der Entwicklerplattform, ist hingegen `crm.objects.custom.read` erforderlich. Wenn Sie diesen Bereich nicht einschließen, schlägt der Build während der Migration fehl und es wird der folgende Fehler angezeigt:
**\[FEHLER] Der Build ist fehlgeschlagen oder abgelaufen. Überprüfen Sie das beim Aktualisieren Ihrer App aufgetretene Problem und versuchen Sie die Migration erneut.**
Ihre kundenseitige App ist trotz des Status auf der Projektdetailseite nicht davon betroffen. Um das Problem zu beheben, fügen Sie den `crm.objects.custom.read`-Bereich zu den Bereichen Ihrer alten App hinzu, erstellen die App anhand der Version `2023.2` ein weiteres Mal und versuchen dann die Migration erneut.