Migration einer vorhandenen privaten App in das Projektframework (BETA)

• 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:

{
  "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 hoch.

​

Klonen Ihrer vorhandenen Projektkonfigurationsdateien

• 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.

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.

​

Aktualisieren Ihrer hsproject.json-Konfiguration

{
  "name": "My old private app",
  "srcDir": "src",
  "platformVersion": "2025.1"
}

{
  "name": "My new migrated app (Developer platform v2025.2)",
  "srcDir": "src",
  "platformVersion": "2025.2"
}

​

Das Top-Level-Schema Ihrer App überprüfen

{
  "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"
  }
}

{
  "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"
    }
  }
}

• 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 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 optionalScopesaufgeteilt. Weitere Informationen zum Angeben der einzelnen Bereichstypen finden Sie im App-Konfigurationsleitfaden.
• 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.

​

Konfiguration einzelner Komponenten aktualisieren

​

CRM-Karten migrieren, die mit UI-Erweiterungen erstellt wurden

{
  "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" }]
  }
}

{
  "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"]
  }
}

• 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.sidebaroder helpdesk.sidebar festgelegt werden.

​

Webhook-Abonnements migrieren

{
"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
        }
      ]
}

{
  "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
        }
      ]
    }
  }
}

• 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.

​

Ihr Projekt hochladen

hs project upload

​

Verarbeiten von serverlosen Funktionen migrieren

• 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.

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 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 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 erfahren Sie mehr über die Verwendung von hubspot.fetch().

const { response } = await runServerless({
  name: 'myFunc',
  parameters: { text: text },
});

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

• 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.

​

Nächste Schritte

• Eine Einstellungskomponente erstellen
• Eine benutzerdefinierte Workflow-Aktion definieren
• Ihre App in HubSpot verwalten