Zum Hauptinhalt springen
Letzte Änderung: 8. Oktober 2025
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 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

​
Eine App-Karte erstellen

1

Fügen Sie Ihrem Projekt eine Kartenkomponente hinzu

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:
hs project add
Sobald Sie aufgefordert werden, eine hinzuzufügende Komponente auszuwählen, klicken Sie auf Karte.Screenshot der Terminal-Aufforderung zur Auswahl des Typs der hinzuzufügenden KomponenteFalls 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).
myProject
└── src/
    └── app/
        └── cards/
            ├── NewCard-hsmeta.json
            ├── NewCard.jsx
            └── package.json
Erfahren Sie in der Referenzdokumentation für App-Karten mehr über diese Dateien.
2

Zu HubSpot hochladen

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 openausführen. Es öffnet sich eine Browser-Registerkarte zur Projektdetailseite, auf der Sie Ihr Projekt, Ihre App und ihre neue Kartenkomponente sehen können.
Screenshot der Projektdetailseite in HubSpot, auf der eine App mit einer Kartenkomponente zu sehen ist
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.
Screenshot der App auf der Projektdetailseite in HubSpot
  • Klicken Sie auf die Registerkarte Verteilung.
  • Dann klicken Sie auf Jetzt installieren.
Screenshot der Schaltfläche „Jetzt installieren“ auf der Registerkarte „App-Verteilung“
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.
Screenshot der Schaltfläche „Anpassen“ in der Chronik eines Kontakts
  • 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.
Screenshot mit dem Plus-Button zum Hinzufügen einer Karte zur Ansicht des Kontaktdatensatzes
  • 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.
Screenshot mit Apps-Filtern der Kartenbibliothek
  • 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.
Screenshot der App-Karte, die in der Kontakt-Chronik mit dem „Developing Local“-Tag gerendert wird
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.

​
Hinzufügen von hubspot.fetch()-Unterstützung

Um Aufrufe an Ihr Backend oder einen Drittanbieterdienst vorzunehmen, aktualisieren Sie bitte die *-hsmeta.json-Konfigurationsdatei der App so, dass sie das permittedUrls-Feld enthält: 
"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.

​
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:
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.