> ## 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. # Migration einer vorhandenen privaten App in das Projektframework (BETA) > Erfahren Sie, wie Sie eine vorhandene private App zum Projektframework migrieren (BETA). Wenn Sie zuvor eine [private App mit der vorherigen Version des Entwicklerframeworks](/guides/crm/understanding-the-crm) erstellt haben, können Sie die Konfiguration Ihrer App manuell in das neue Framework (`2025.2` migrieren). In dieser Anleitung erfahren Sie, wie das geht: * Sie klonen zunächst Ihr vorhandenes Projekt, damit die ursprünglichen Dateien als Backup dienen können. Anschließend können Sie alle zugeordneten Konfigurationsdateien überprüfen, um sicherzustellen, dass sie mit dem neuen Projektschema übereinstimmen. Dies erfordert geringfügige Aktualisierungen der Namen und der Struktur Ihrer Komponentenkonfigurationsdateien sowie ihrer jeweiligen Eigenschaften. * Anschließend aktualisieren Sie Ihre vorhandenen übergeordneten `hsproject.json`- und `app.json`-Konfigurationsdateien. * Sie können dann in den folgenden Abschnitten die Konfiguration für Ihre App-Komponenten aktualisieren, damit sie der Version `2025.2` der Entwicklerplattform entspricht, basierend auf den vorhandenen Funktionen, die Sie eingerichtet haben (z. B. eine App-Karte, die mit UI-Erweiterungen erstellt wurde). * Beachten Sie bitte, dass mit Ausnahme der `hsproject.json`-Datei alle anderen Konfigurationsdateien einem vorhersehbaren Benennungsschema folgen (`*-hsmeta.json`, wobei das `*` auf dem spezifischen Verzeichnis oder der Komponente basiert) und alle dieselben Top-Level-Eigenschaften haben: ```json theme={null} { "uid": "example-unique-identifier", "type": "example-component", "config": { ... } } ``` * Nachdem Sie alle Komponenten Ihres geklonten vorhandenen Projekts aktualisiert haben, laden Sie Ihr neues Projekt als Teil des letzten Schritts in diesem Handbuch in Ihren [HubSpot-Entwickler-Account](/getting-started/account-types#developer-accounts) hoch. Beachten Sie bitte die folgenden Beschränkungen, bevor Sie Ihre private App migrieren: * Die HubSpot-CLI-Migrationsbefehle werden für vorhandene private Apps nicht unterstützt, da die automatische Migration derzeit nicht unterstützt wird. * Die Unterstützung für die [GitHub-Integration](/developer-tooling/third-party-tools/set-up-github-actions), die automatische Uploads und Builds von GitHub auslöst, ist noch nicht verfügbar. Wenn Ihr vorhandenes 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](/developer-tooling/third-party-tools/set-up-github-actions). ## Klonen Ihrer vorhandenen Projektkonfigurationsdateien Bevor Sie Aktualisierungen vornehmen, klonen Sie bitte Ihr vorhandenes Projekt, damit Sie über ein Backup verfügen, auf das Sie zurückgreifen können oder auf das Sie ausweichen können, falls Probleme auftreten. Nachdem Sie Ihr Projekt geklont haben, öffnen Sie die geklonten Projektdateien in Ihrer bevorzugten IDE, z. B. VSCode. Wenn Sie nach einem minimalen Projekt suchen, das mit den neuen `2025.2`-Schemata konform ist, auf die Sie verweisen können, dann laden Sie eine Boilerplate-Vorlage herunter: * 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. * Führen Sie den folgenden Befehl in Ihrem Terminal aus, um ein Projekt mit der Boilerplate-Vorlage für eine App mit `private`-Verteilung und `static`-Authentifizierung zu erstellen. ```shell theme={null} hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta ``` * Befolgen Sie die Aufforderungen, um einen Namen und ein lokales Verzeichnis anzugeben, in das die Boilerplate-Vorlage heruntergeladen werden soll. * Wenn Sie aufgefordert werden, eine Vorlage auszuwählen, wählen Sie **Erste Schritte für ein Projekt mit einer privaten App mithilfe eines Zugriffstokens** aus. * Öffnen Sie das neu erstellte Projekt in Ihrem bevorzugten Editor. Sie können dann die Projektverzeichnisstruktur und die zugehörigen `*-hsmeta.json`-Schemadateien mit Ihrem bestehenden Projekt vergleichen, um sicherzustellen, dass die Spezifikationen gegebenenfalls übereinstimmen. Beachten Sie bitte, dass die Vorlage als Referenz verwendet, aber nicht direkt bearbeitet werden sollte, da empfohlen wird, wie oben beschrieben alle Änderungen in der geklonten Version Ihres Projekts vorzunehmen. Eine vollständige Referenz der neuen Projektstruktur für die Version `2025.2` der Entwicklerplattform finden Sie im [App-Konfigurationsleitfaden](/apps/developer-platform/build-apps/app-configuration#project-structure) . ## Aktualisieren Ihrer hsproject.json-Konfiguration Die Änderungen an der obersten Ebene `hsproject.json` beinhalten geringfügige Änderungen an den `name`- und `platformVersion`-Eigenschaften, wie in den folgenden Codeblöcken aufgeführt: **Vorher:** ```json theme={null} { "name": "My old private app", "srcDir": "src", "platformVersion": "2025.1" } ``` **Nachher:** ```json theme={null} { "name": "My new migrated app (Developer platform v2025.2)", "srcDir": "src", "platformVersion": "2025.2" } ``` Die Top-Level-`hsproject.json`-Datei in Ihrem Projekt befindet sich auf der neuen Entwicklerplattform am selben Speicherort, aber Sie müssen die `platformVersion` auf `"2025.2"`aktualisieren. Sie sollten das `name`-Feld auch mit einem eindeutigen Namen aktualisieren, damit Ihr vorhandenes Projekt beim Hochladen nicht überschrieben wird. Wenn der Name Ihrer vorhandenen privaten App beispielsweise `My private app` war, können Sie `(Developer Platform v2025.2)` oder etwas Ähnliches hinzufügen, um sie von der alten App zu unterscheiden. ## Das Top-Level-Schema Ihrer App überprüfen Die folgenden Codeblöcke enthalten Beispiele für die Konfiguration vor und nach den erforderlichen Änderungen: **Vorher (`src/app/app.json`):** ```json theme={null} { "name": "My old private app", "description": "This is an example of private app on the old developer platform.", "scopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"], "uid": "my-old-private-app", "public": false, "extensions": { "crm": { "cards": [ { "file": "extensions/example-card.json" } ] } }, "webhooks": { "files": "./webhooks/webhooks.json" } } ``` **Nachher (`src/app/app-hsmeta.json`):** ```json theme={null} { "uid": "new_developer_platform_app", "type": "app", "config": { "description": "Example of migrated app on the new developer platform.", "name": "My new migrated app (Developer platform v2025.2)", "distribution": "private", "auth": { "type": "static", "redirectUrls": ["http://localhost:3000/oauth-callback"], "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"], "optionalScopes": [], "conditionallyRequiredScopes": [] }, "permittedUrls": { "fetch": ["https://api.example.com"], "iframe": [], "img": [] }, "support": { "supportEmail": "support@example.com", "documentationUrl": "https://example.com/docs", "supportUrl": "https://example.com/support", "supportPhone": "+18005555555" } } } ``` In der älteren Version der Entwicklerplattform wurde die Konfiguration für Ihre private App in Ihrer `app.json`-Datei angegeben. Diese Konfigurationsdetails für Ihre App werden jetzt in Ihrer App-Schemadatei in der `/src/app/app-hsmeta.json`-Datei angegeben. Die wichtigsten Änderungen zwischen Ihrer alten `app.json`- und der neuen `app-hsmeta.json`-Konfiguration umfassen Folgendes: * Die Top-Level-Eigenschaft `public` wurde durch `distribution` ersetzt und sollte auf `private` festgelegt werden. Beachten Sie bitte, dass die `type`-Untereigenschaft des `auth`-Feldes auf `static` festgelegt werden sollte, wodurch die Installation Ihrer App auf einen einzigen Account beschränkt wird. Im [App-Konfigurationsleitfaden](/apps/developer-platform/build-apps/app-configuration#distribution) erfahren Sie mehr über App-Verteilung und -Authentifizierung. * Die Bereiche Ihrer App werden jetzt als Untereigenschaft des `auth`-Feldes angegeben und zwischen `requiredScopes`, `conditionallyRequiredScopes` und `optionalScopes`aufgeteilt. Weitere Informationen zum Angeben der einzelnen Bereichstypen finden Sie im [App-Konfigurationsleitfaden](/apps/developer-platform/build-apps/app-configuration#scopes). * Sie müssen die Top-Level-Eigenschaft `extensions` aus Ihrem vorherigen Projekt nicht definieren, da die Eigenschaft in der neuen `app-hsmeta.json`-Datei nicht vorhanden ist. Alle zuvor konfigurierten UI-Erweiterungen (z. B. Karten auf der CRM-Datensatzseite) werden mithilfe des `cards/`-Verzeichnisses Ihres Projekts verwaltet. Innerhalb dieses Verzeichnisses werden die Kartenkonfigurationsdetails in einer `*-hsmeta.json`-Datei angegeben, zusammen mit dem Komponentencode für Ihre Karte in einer `.jsx`-Datei, auf die mithilfe der `entrypoint`-Eigenschaft der `*-hsmeta.json`-Datei verwiesen wird. * Sie müssen auch nicht über die Top-Level-Eigenschaft `webhooks` aus Ihrem vorherigen Projekt in der neuen `app-hsmeta.json`-Datei definieren, da Webhooks mithilfe des `webhooks/`-Verzeichnisses Ihres Projekts konfiguriert und verwaltet werden. Weitere Informationen finden Sie weiter unten im Abschnitt [Webhook-Abonnements migrieren](#migrate-webhook-subscriptions). ## Konfiguration einzelner Komponenten aktualisieren In den folgenden Abschnitten wird beschrieben, wie Sie UI-Erweiterungen und Webhooks auf Ihre neue App portieren. Wenn Ihre alte App keine dieser Komponenten hatte, können Sie zum Abschnitt [Ihr Projekt hochladen](#upload-your-project) springen. ### CRM-Karten migrieren, die mit UI-Erweiterungen erstellt wurden Die folgenden Codeblöcke enthalten Beispiele für die Konfiguration vor und nach den erforderlichen Änderungen: **Vorher (`src/app/extensions/card.json`):** ```json theme={null} { "type": "crm-card", "data": { "title": "example app card", "uid": "example_app_card_private_static", "location": "crm.record.tab", "module": { "file": "example-app-card.jsx" }, "objectTypes": [ { "name": "contacts" } ] } } ``` **Nachher (`src/app/cards/example-app-card-hsmeta.json`):** ```json theme={null} { "uid": "example_app_card_private_static", "type": "card", "config": { "name": "example app card", "description": "Provides detailed information about a contact or company.", "previewImage": { "file": "./full-preview.png", "altText": "This describes the image" }, "entrypoint": "/app/cards/example-app-card.jsx", "location": "crm.record.tab", "objectTypes": ["CONTACT"] } } ``` CRM-Karten werden jetzt im `cards/`-Verzeichnis Ihres Projekts konfiguriert und ersetzen das vorherige `extensions/`-Verzeichnis Ihres alten Projekts. Innerhalb des neuen `cards/`-Verzeichnisses werden die Details der Kartenkonfiguration in einer `*-hsmeta.json`-Datei zusammen mit dem Komponentencode für Ihre Karte angegeben, der in einer `.jsx`-Datei bereitgestellt wird, auf die mithilfe der `entrypoint`-Eigenschaft der `*-hsmeta.json`-Datei verwiesen wird. Um den UI-Erweiterungscode Ihrer alten App zu portieren, kopieren Sie alle relevanten Werte aus Ihrer alten `app.json` -App in die zugehörigen Eigenschaften in der `*-hsmeta.json`-Datei im `cards/`-Verzeichnis, wobei Sie dabei die folgenden Änderungen beachten sollten: * Der Wert der `type`-Eigenschaft wurde von `"crm-card"` in `"card"` geändert. * Die `uid`-Eigenschaft wurde von einer Untereigenschaft des `data`-Feldes nach oben verschoben und wird nun auf der obersten Ebene Ihrer Konfiguration angegeben. * Die `data`-Eigenschaft wurde in `config` geändert und enthält die folgenden Untereigenschaften: * Die `title`-Eigenschaft wurde in `name` umbenannt. * Eine neue `description`-Eigenschaft ermöglicht es Ihnen, mehr Kontext zur Funktionalität Ihrer Karte bereitzustellen. Die Beschreibung wird in den Projekteinstellungen Ihrer App angezeigt. * Die `module`-Eigenschaft wurde in `entrypoint` umbenannt und der Wert sollte nun eine Zeichenfolge sein, die den Pfad zu Ihrer JSX-Komponente darstellt, relativ zum Stamm Ihres Projekts (z. B. `"/app/cards/example-app-card.jsx"`). * Die `objectTypes`-Eigenschaft wurde vereinfacht und besteht jetzt aus einem Array von Zeichenfolgen, die die Objekttypen darstellen, in denen Ihre Karte angezeigt werden soll (z. B. `["CONTACT", "COMPANY"]`). * Die `location`-Eigenschaft bleibt unverändert und kann auf `crm.record.tab`, `crm.record.sidebar`oder `helpdesk.sidebar` festgelegt werden. Wenn Sie [die Boilerplate-Projektvorlage heruntergeladen haben](#clone-your-existing-project-configuration-files), werden eine `example-app-card-hsmeta.json`-Beispielkonfigurationsdatei und eine `example-app-card.jsx`-JSX-Komponente im `src/app/cards`-Verzeichnis bereitgestellt. Eine vollständige Anleitung zum Erstellen von App-Karten auf der neuen Entwicklerplattform finden Sie [in diesem Artikel](/apps/developer-platform/add-features/ui-extensibility/app-cards/create-an-app-card). ### Webhook-Abonnements migrieren Die folgenden Codeblöcke enthalten Beispiele für die Konfiguration vor und nach den erforderlichen Änderungen: **Vorher (`src/app/webhooks/webhooks.json`):** ```json theme={null} { "settings": { "targetUrl": "https://example.com/webhook", "maxConcurrentRequests": 10 }, "subscriptions": { "crmObjects": [ { "subscriptionType": "object.creation", "objectType": "contact", "active": true } ], "legacyCrmObjects": [ { "subscriptionType": "contact.propertyChange", "propertyName": "lastname", "active": true } ], "hubEvents": [ { "subscriptionType": "contact.privacyDeletion", "active": true } ] } ``` **Nachher (`src/app/webhooks/webhooks-hsmeta.json`):** ```json theme={null} { "uid": "webhooks", "type": "webhooks", "config": { "settings": { "targetUrl": "https://example.com/webhook", "maxConcurrentRequests": 10 }, "subscriptions": { "crmObjects": [ { "subscriptionType": "object.creation", "objectType": "contact", "active": true } ], "legacyCrmObjects": [ { "subscriptionType": "contact.propertyChange", "propertyName": "lastname", "active": true } ], "hubEvents": [ { "subscriptionType": "contact.privacyDeletion", "active": true } ] } } } ``` Webhook-Abonnements werden weiterhin in einem `webhooks/`-Verzeichnis Ihres Projekts verwaltet. Innerhalb des Verzeichnisses werden die Abonnementdetails in einer `*-hsmeta.json`-Datei angegeben. Die Struktur der Datei ähnelt weitgehend dem vorherigen `webhooks.json`-Schema in Ihrer privaten App, mit den folgenden nennenswerten Änderungen: * Auf der obersten Ebene Ihrer `*-hsmeta.json`-Datei muss eine erforderliche `uid`-Eigenschaft definiert werden, die einen Namen erhalten sollte, um sie von anderen App-Funktionen zu unterscheiden (z. B. `"migrated_private_app_webhooks"`). * Eine erforderliche `type`-Eigenschaft muss ebenfalls auf der obersten Ebene Ihrer `*-hsmeta.json`-Konfiguration definiert und auf `"webhooks"` festgelegt werden. * Die `subscriptions`- und `settings`-Eigenschaften bleiben unverändert von `webhooks.json`, müssen jedoch in die `config`-Eigenschaft verschoben werden, die auf der obersten Ebene Ihrer `*-hsmeta.json`-Datei definiert ist. Eine vollständige Referenz zum Definieren von Webhook-Abonnements auf der neuen Entwicklerplattform finden Sie [in diesem Artikel](/apps/developer-platform/add-features/configure-webhooks). ## Ihr Projekt hochladen Nachdem Sie die Konfiguration von Ihrer vorhandenen privaten App in die entsprechenden Unterverzeichnisse Ihres Projekts migriert haben, können Sie Ihre neue App in Ihren HubSpot-Account hochladen. Dort finden Sie das Token für den Zugriff auf Ihre App, mit dem Sie API-Anfragen authentifizieren und die Funktionen auf der neuen Entwicklerplattform weiterentwickeln können. ### Hinweis: Wenn für Ihre vorhandene private App serverlose Funktionen definiert waren:
  1. Erstellen Sie ein Backup der `src/app/app.functions` aus Ihrem alten Projekt zusammen mit allen zugeordneten Verweisen auf Ihre serverlosen Funktionen an anderer Stelle in ihrem Projekt.
  2. Serverlose Funktionen sollten nicht im Projektverzeichnis enthalten sein, das Sie als Teil Ihrer neuen App hochladen. Wenn Sie Ihr Projekt hochgeladen haben, befolgen Sie einfach die Schritte im [Abschnitt weiter unten](#migrate-serverless-function-handling), um das gleiche Verhalten auf der neuen Entwicklerplattform auszulösen.
Um Ihr neues Projekt hochzuladen, führen Sie bitte den folgenden CLI-Befehl aus: ```shell theme={null} hs project upload ``` ## Verarbeiten von serverlosen Funktionen migrieren Wenn Ihre private App serverlose Funktionen enthält, müssen Sie Ihren eigenen REST-basierten Backend-Service erstellen und die `hubspot.fetch()`-API zum Abrufen von Daten verwenden. Hierfür müssen Sie jede vorhandene Dienstlogik, die zuvor in Ihrem von HubSpot gehosteten serverlose Funktionen definiert war, sowie den Zugriffstoken für Ihre private App zu einer Hosting-Plattform eines Drittanbieters wie Vercel, DigitalOcean, AWS usw. migrieren. So migrieren Sie Ihre serverlose Funktionslogik zu einer Hosting-Plattform eines Drittanbieters: * Suchen Sie Ihre serverlosen Funktionen im Projekt Ihrer vorhandenen privaten App im `src/app/app.functions`-Verzeichnis. * Kopieren Sie die gesamte relevante Logik aus Ihren Funktionen. In der folgenden beispielhaften serverlosen Funktion müsste nur Zeile 4 kopiert werden. ```js theme={null} exports.main = async (context = {}) => { const { text } = context.parameters; const response = `This is coming from a serverless function! You entered: ${text}`; return response; }; ``` * Fügen Sie auf der Hosting-Plattform des Drittanbieters die Logik aus Ihrer vorherigen Definition der serverlosen Funktionen ein und stellen Sie sicher, dass alle Parameternamen übereinstimmen. Sie müssen die Dokumentation zum Definieren der serverlosen Funktion auf der von Ihnen verwendeten Plattform zu Rate ziehen. * Kopieren Sie Ihre Zugriffstokens von der [Projektdetailseite](/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication-for-your-app) Ihrer App und fügen Sie sie als Umgebungsvariable mit der Hosting-Plattform Ihres Drittanbieters hinzu, damit Sie in Ihrem Code darauf verweisen können. * Als Nächstes müssen Sie die `permittedUrls`-Eigenschaft Ihrer Top-Level-`app-hsmeta.json`-[Schemadatei](#review-your-app-s-top-level-schema) aktualisieren, um das `fetch`-Feld aufzunehmen. Der Wert dieses Felds sollte auf ein Array festgelegt werden, das die URL des Endpunkts enthält, der auf der Hosting-Plattform eines Drittanbieters gehostet wird. * Aktualisieren Sie dann alle Verweise in Ihrem React-Code auf Ihren App-Karten, um die neue URL der serverlosen Funktion aufzurufen, die Sie eingerichtet haben. In [diesem Leitfaden](/apps/developer-platform/add-features/ui-extensibility/fetching-data) erfahren Sie mehr über die Verwendung von `hubspot.fetch()`. Wenn zum Beispiel der React-Code in Ihrer privaten App zuvor die serverlose Funktion wie folgt aufgerufen hat: ```js theme={null} const { response } = await runServerless({ name: "myFunc", parameters: { text: text }, }); ``` Dann sollten Sie den Code in Ihrem neuen Projekt in etwa folgendermaßen aktualisieren: ```js theme={null} const response = await hubspot.fetch("https://my-new-serverless-function.example.app/api/example-function.js", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text: "hello" }), }); ``` ## Bereinigen Nachdem Sie Ihr neues Projekt erfolgreich hochgeladen, alle serverlosen Funktionen migriert haben (falls zutreffend) und Ihre App vollständig getestet haben, um zu bestätigen, dass das Verhalten gleich ist, können Sie Ihr altes Projekt in Ihrem HubSpot-Entwickler-Account löschen. Denken Sie daran, dass Sie das ursprüngliche Backup Ihres Projekts immer noch lokal gespeichert haben, wie im [ersten Schritt](#clone-your-existing-project-configuration-files) dieses Leitfadens beschrieben, für den Fall, dass Sie es jemals als Referenz benötigen. So löschen Sie Ihr altes Projekt aus Ihrem Entwickler-Account: * Gehen Sie in Ihrem HubSpot-Account zu **Entwicklung**. * Klicken Sie auf der Seite **Projekte** auf den **Namen** Ihres alten Projekts. * Klicken Sie auf die Registerkarte **Einstellungen**. * Klicken Sie unter *Dieses Projekt löschen* auf **\[Projektnamen] löschen**. * Überprüfen Sie die Informationen im Dialogfeld, um zu bestätigen, dass Sie fortfahren möchten. Geben Sie dann den Namen Ihres Projekts ein und klicken Sie auf **Projekt löschen**. Löschen des alten Projekts bestätigen ## Nächste Schritte Nachdem Sie nun die Komponenten und die Konfiguration von Ihrer alten privaten App manuell migriert haben, können Sie mit diesen weiterführenden Anleitungen noch mehr Features auf der neuen Entwicklerplattform entwickeln: * [Eine Einstellungskomponente erstellen](/apps/developer-platform/add-features/ui-extensibility/create-a-settings-component) * [Eine benutzerdefinierte Workflow-Aktion definieren](/apps/developer-platform/add-features/custom-workflow-actions) * [Ihre App in HubSpot verwalten](/apps/developer-platform/build-apps/manage-apps-in-hubspot)