Letzte Änderung: 11. September 2025
Die aktuelle Version (2025.2) der Entwicklerplattform bietet ein neues dateibasiertes Framework zum Build- und Bereitstellungsprozess. Dieses Framework enthält die Konfiguration, Ressourcen und anderen Quellcode einer App. Wenn Sie eine bestehende öffentliche App haben, die Sie vor Ihrer Anmeldung für die neue Beta-Version der Entwicklerplattform erstellt haben, erfahren Sie in diesem Leitfaden, wie Sie diese auf die neueste Version des Projektframeworks migrieren. Bevor Sie mit der Migration fortfahren, lesen Sie sich bitte die beiden folgenden Abschnitte zu den unterstützten Funktionen und allen Einschränkungen durch.

​
Unterstützte App-Funktionen und -Erweiterungen

Alle Funktionen, die von Projekten unterstützt werden, werden in die Migration einbezogen, einschließlich:
  • App-Konfiguration
  • Webhooks
  • Benutzerdefinierte Workflow-Aktionen

​
Bevor Sie loslegen

Wenn Ihr vorhandenes Projekt über eine Karte mit verknüpften benutzerdefinierten Objekten verfügt, überprüfen Sie vor der Migration, ob Sie über den crm.objects.custom.read-Bereich für Ihre App verfügen. Bei Projekten, die vor der neuesten Version (2025.2) erstellt wurden, konnten benutzerdefinierte Objektkarten nur mit dem erforderlichen crm.schemas.custom.read-Bereich erstellt werden. In der neuesten Version (2025.2) der Entwicklerplattform ist für Ihre Karte crm.objects.custom.read erforderlich, um auf benutzerdefinierte Objektdaten zuzugreifen.

​
Beschränkungen

Die folgenden Funktionen werden während der aktuellen privaten Beta-Phase noch nicht unterstützt:
  • Die Unterstützung für die GitHub-Integration, die automatische Uploads und Builds von GitHub auslöst, ist noch nicht verfügbar. Wenn Ihr Projekt derzeit mit GitHub verknüpft ist, stellen Sie bitte sicher, dass Sie die Integration deaktivieren, bevor Sie mit der Migration beginnen. Wie Sie die GitHub-Integration deaktivieren und GitHub-Aktionen zur Automatisierung von CI/CD einrichten, erfahren Sie in diesem Artikel.
  • Wenn Sie eine Einstellungsseite für Ihre App erstellt haben, müssen Sie Ihre Einstellungen mithilfe des neuen Features für UI-Erweiterungen umgestalten. Es wird empfohlen, dass Sie sich alle UI-Elemente in der aktuellen Produktionsversion Ihrer App notieren, bevor Sie sie auf die neueste Version migrieren. Nachdem der Migrationsprozess abgeschlossen ist, können Sie die neuen Funktionen der UI-Erweiterung verwenden, um Ihre Einstellungsseite neu zu erstellen.
  • Die klassische CRM-Kartenfunktion wird nicht für Apps unterstützt, die die neueste Version von Entwicklerprojekten verwenden. Sie müssen alle vorhandenen CRM-Karten umgestalten, um stattdessen das App-Kartenschema zu verwenden.
  • Die Ihrer App zugrunde liegende Berechtigungsstruktur wird aktualisiert, um detailliertere benutzerspezifische Berechtigungen zu unterstützen. Im Rahmen dieser Umstellung wird für neue Kundeninstallationen nun ein zugewiesener Service-Account-Benutzer in seinem Account erstellt, der an Ihre App gebunden ist.
    • Jeder Account erhält jetzt nur noch ein Aktualisierungstoken, unabhängig davon, wie viele einzelne Benutzer die App erneut autorisieren.
    • Vorhandene OAuth-Endpunkte, die Metadaten aus Tokens abrufen, aktualisieren und darauf zugreifen, geben weiterhin den Benutzer zurück, der sie als userId installiert hat, und geben jetzt nach der Migration Ihrer App eine serviceAccountId zurück.

​
Ihre App migrieren

Sobald Sie die Punkte im obigen Abschnitt durchgegangen sind, können Sie mit der Migration Ihrer App fortfahren. Bei diesem Vorgang bleiben die ursprünglichen Authentifizierungsdaten, App-Funktionen und Installationen für die App erhalten. Im Backend Ihrer App sind keine Änderungen erforderlich.
  • Stellen Sie sicher, dass Sie die neueste Beta-Version des HubSpot-CLI installiert haben, indem Sie den Befehl npm i -g @hubspot/cli@next ausführen, und es mit hs auth- und hs accounts use-Befehlen mit Ihrem Account verknüpfen.
Das CLI muss Version 7.5.4 oder höher sein. Sie können überprüfen, welche Version des CLI Sie haben, indem Sie hs --version ausführen.
  • Um den Migrationsprozess zu starten, verwenden Sie einen der folgenden Befehle basierend auf der vorhandenen App, die Sie migrieren:
  • Wenn Sie eine Legacy-App migrieren, die nicht Teil eines Projekts ist, führen Sie bitte den folgenden Befehl aus:
hs app migrate
Wenn Sie eine projektbasierte App migrieren, führen Sie bitte den Befehl hs project migrate aus.
  • Sie werden aufgefordert, die App auszuwählen, die Sie migrieren möchten. Dadurch wird ein neues Projekt in Ihrem lokalen Dateisystem erstellt, das eine App mit den Funktionen enthält, die den aktuell konfigurierten Zustand darstellen.
  • Nachdem Sie die App ausgewählt haben, werden Sie zur Bestätigung der zu migrierenden Komponenten aufgefordert. Vergewissern Sie sich, dass Sie den Migrationsprozess vollständig verstanden haben, bevor Sie mit dem nächsten Schritt fortfahren.
  • Als Nächstes werden Sie gebeten, einen Projektnamen, einen lokalen Pfad zum neuen Projekt und alle erforderlichen UIDs anzugeben.
UIDs sollten als eindeutige ID für alle Funktionen Ihrer App verwendet werden. Sobald eine UID für ein bestimmtes Feature definiert ist, zwingt das Ändern oder Modifizieren in nachfolgenden Builds die Plattform, diese als „neu“ oder unterschiedlich von früheren Builds einzuordnen, was möglicherweise nicht beabsichtigt ist.
Aufforderungen zum Migrieren einer vorhandenen App
  • Sobald Sie die Details für Ihr Projekt bestätigt haben, führt der Migrationsprozess automatisch die folgenden Aktionen in einem einzigen Vorgang durch:
    • Erstellen Sie auf der Projektseite Ihres Accounts ein Projekt für Ihre App, das eine App-Komponente und alle kompatiblen Funktionen enthält.
    • Konvertieren Sie alle vorhandenen Funktionen der App in Quellcodedateien, die Sie aktualisieren können, um ihre Konfiguration in der Zukunft zu überarbeiten.
    • Erstellen und stellen Sie das neue Projekt bereit (das als Build #1 bezeichnet wird), welches die Zuordnung zwischen der App und ihrem Projekt vervollständigt. Dabei bleiben die ursprünglichen Anmeldeinformationen, App-Funktionen und Installationen erhalten.
    • Laden Sie die neuen Projektquelldateien in das lokale Verzeichnis herunter, das Sie zuvor angegeben haben, als Sie im Terminal dazu aufgefordert wurden.
    • Wenn ein vorhandenes Projekt migriert wurde, verschieben Sie die Dateien aus dem ursprünglichen src/-Verzeichnis in das archive/ und fügen Sie den neuen Projektquellcode in /src/ ein.
Detailseite für die migrierte App in der Projektansicht
Build #1 des neuen Projekts erfasst den Konfigurationsstatus der App für alle unterstützten Funktionen als Basis, zu der Sie zurückkehren können. Bei Bedarf können Sie alle zukünftigen Änderungen an diesem Projekt (z. B. Hinzufügen von React-basierten App-Karten) auf sichere Weise rückgängig machen, indem Sie Build #1 erneut bereitstellen.
Nach der Migration können die im Quellcode des Projekts definierten Funktionen nicht mehr über die App-Management-Benutzeroberfläche in HubSpot oder die vorherigen Entwickler-APIs bearbeitet werden. Andere Funktionen (z. B. benutzerdefinierte Workflow-Aktionen oder Chronik-Events) werden weiterhin über ihre jeweiligen APIs gepflegt.
  • Wenn die Migration abgeschlossen ist (wie im "platformVersion": "2025.2"-Feld in Ihrer hsproject.json-Datei angegeben), können Sie nun mit der Entwicklung neuer oder bestehender Funktionen beginnen. Verwenden Sie das HubSpot-CLI und die Quellcodedateien Ihres Projekts.