Zum Hauptinhalt springen
Letzte Änderung: 7. Oktober 2025
Für diese Funktion ist allerdings die Genehmigung von HubSpot erforderlich. Wenn Sie gerne Zugriff auf App-Objekte beantragen oder mehr über die Funktionalität erfahren möchten, senden Sie bitte dieses Formular ein.
Erfahren Sie, wie Sie eine Proof-of-Concept-App erstellen, bei der Sie ein App-Objekt konfigurieren, das Sie testen und in einem Entwickler-Test-Account verwenden können.
1

Die neueste Version des HubSpot CLI installieren

Sie benötigen die neueste Betaversion des HubSpot CLI, um eine einheitliche App zu erstellen. Führen Sie in einem Terminalfenster den folgenden Befehl aus:
npm install -g @hubspot/cli@next
Das CLI muss mindestens die Version 7.4.4-beta.0 sein. Sie können überprüfen, welche Version des CLI Sie haben, indem Sie hs --version ausführen.
2

Entwickler-Account authentifizieren

Dann müssen Sie Ihren Entwickler-Account anhand des folgenden Befehls authentifizieren:
hs auth
  • Befolgen Sie die Prompts, um einen persönlichen Zugriffsschlüssel in Ihrem Account zu generieren, kopieren Sie ihn und fügen Sie ihn dann in das Terminal ein, um Ihre Konfiguration zu speichern.
  • Während dieser Beta-Phase wird empfohlen, diesen Account zu Ihrem Standard-Account im CLI zu machen. Dadurch werden mögliche Fehler beim Zugriff auf den Account, den Sie für die Beta-Version angemeldet haben, verhindert.
3

Ein neues Boilerplate-Projekt erstellen

Führen Sie den folgenden Befehl in Ihrem Terminal aus, um eine neue Projekt- und Marketplace-App entweder mit den derzeit kompatiblen Funktionen oder einem App-Objektreferenzschema zu erstellen.
hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
4

Konfigurieren Sie das neu erstellte Projekt und laden Sie es in Ihren Entwickler-Account hoch

Das Projektframework verschiebt App-Features, die zuvor in der Benutzeroberfläche oder über die API konfiguriert wurden, in Quellcodedateien, die in der Regel als <file-name>-hsmeta.json-Konfigurationsdateien definiert sind.App-Funktionen werden dann mit einer Kombination aus Unterordnern aus dem /src/app-Hauptverzeichnis und anderen Konfigurationsdateien nach Bedarf erstellt. So konfigurieren Sie Ihr Projekt:
  • Fügen Sie eine oder mehrere gültige Weiterleitungs-URLs zur app-hsmeta.json-Datei hinzu, die auf Ihrer lokalen (oder einer anderen nicht produktionsbezogenen) OAuth-Serverkonfiguration basieren.

​
Hinweis:

Für den Anfang können Sie das OAuth Node.js-Beispiel verwenden und lokal ausführen. Alles ist bereits so eingerichtet, dass https://localhost:3000/oauth-callback als Weiterleitungs-URL benutzt wird. Diese wurde bereits im Boilerplate-Beispielcode des hs project create-Befehls konfiguriert, den Sie im vorherigen Schritt verwendet haben.
  • Ändern Sie die uid-Eigenschaften der App in der app-hsmeta.json-Datei und den anderen *-hsmeta.json-Konfigurationsdateien in Ihrem Projekt.
UIDs werden als eindeutige ID für alle Komponenten und Funktionen Ihres Projekts verwendet. Sobald eine Funktion und eine UID erstellt sind, führt das Ändern oder Modifizieren der UID in nachfolgenden Bereitstellungen zwangsläufig dazu, dass die Plattform sie als von früheren Funktionen abweichend erkennt, was möglicherweise nicht beabsichtigt ist.
  • Wenn Sie App-Objekte für Ihre einheitliche App verwenden, sind nur die autorisierten „Namen“-Eigenschaftsdefinitonen basierend auf Ihrer Objektanfrage zulässig. Im Rahmen dieser privaten Beta sollten Sie separat eine Bestätigung des genehmigten „Namens“ Ihrer App erhalten haben, der in der *-object-hsmeta.json-Konfiguration verwendet werden muss. Als Referenz lautet der vollständig qualifizierte Name (Fully Qualified Name, FQN) für Ihr App-Objekt a<appId>_<name>. Wenn zum Beispiel Ihre appId 16858319 lautet und Ihre name-Eigenschaft CARS war, dann wäre a16858319_cars Ihr FQN.
  • Sobald Sie Ihre Änderungen gespeichert haben, führen Sie den hs project upload-CLI-Befehl aus, um Ihr Projekt auf die HubSpot-Entwicklerplattform hochzuladen und automatisch einen neuen Build auszulösen.
  • Gehen Sie in einem Browserfenster zu https://app.hubspot.com/developer_projects/<accountId>, um die Projekt-Benutzeroberfläche aufzurufen und zu bestätigen, dass die App und das Projekt ordnungsgemäß erstellt, aufgebaut und bereitgestellt wurden.
5

Fügen Sie die Client-ID und das Client-Geheimnis Ihrer App zu Ihrer App hinzu

  • Nach dem Hochladen Ihres Projekts müssen Sie die Authentifizierungsdetails für Ihre App abrufen, um sie in Ihre OAuth-Konfiguration zu kopieren:
    • Klicken Sie im Navigationsmenü Entwicklung auf Projekte.
    • Dann klicken Sie auf den Namen Ihres neuen Projekts.
    • Anschließend klicken Sie auf die UID Ihrer App und danach auf die Registerkarte Authentifizierung.
    • Kopieren Sie die Client-ID und das Client-Geheimnis aus Ihrer neuen App, fügen Sie die Angaben an den entsprechenden Stellen in der Konfiguration Ihres lokalen OAuth-Servers ein und starten Sie dann Ihren OAuth-Server neu.
6

Konfiguration des App-Objektschemas einrichten

Als Nächstes konfigurieren Sie das Schema Ihres App-Objekts:
  • Fügen Sie ein neues App-Objekt hinzu, indem Sie ein Verzeichnis innerhalb des Verzeichnisses /src/app erstellen und es app-objects nennen. Der resultierende Pfad zum neuen Verzeichnis sollte /src/app/app-objects sein .
  • Erstellen Sie eine neue Konfigurationsdatei, um das Schema Ihres Objekts darzustellen. Sie sollten den Objektnamen, der Ihrer App während des Vorschauprozesses gegeben wurde, als Präfix für den Dateinamen verwenden, gefolgt von -object-hsmeta.json. In der Vorlage des Referenzprojekts lautet der App-Objektname beispielsweise „CAR“, daher heißt die resultierende Konfigurationsdatei car-object-hsmeta.json.
  • Konsultieren Sie die Referenzdatei für App-Objektkomponentendefinitionen und passen Sie die Felder an die entsprechenden Werte für Ihr App-Objekt an.
    • Innerhalb des config-Objekts Ihrer Definition muss das name-Feld mit dem Namen übereinstimmen, der Ihrer App während des Überprüfungsprozesses im UPPER_SNAKE_CASE-Format zugewiesen wurde.
    • Beachten Sie, dass die Eigenschaften und Felder, sobald sie zu Ihrem App-Objektschema hinzugefügt und im nächsten Schritt in Ihr Projekt hochgeladen wurden, nicht mehr entfernt werden können.

​
Hinweis:

Zur Vereinfachung der Tests kann derselbe App-Objektname für mehrere Apps verwendet werden, um Ihren Entwicklungs-Lifecycle zu unterstützen. Beginnen Sie mit dieser Proof-of-Concept-App, und sobald Migrationen verfügbar sind, können Sie denselben Namen und dieselben Schemadefinitionen für Ihre Entwicklungs-, Staging- und Produktions-Apps verwenden. Die UIDs für jede dieser Instanzen müssen eindeutig sein.
  • Wenn Sie mit der Bearbeitung Ihrer App-Objektschemadefinition fertig und bereit sind, diese Änderungen zu übernehmen, führen Sie die folgenden Befehle aus, um Ihre Änderungen zu speichern:
hs project upload
hs project deploy
  • Gehen Sie in einem Browserfenster zu https://app.hubspot.com/developer_projects/<hubId>, um die Projekt-Benutzeroberfläche aufzurufen und zu bestätigen, dass die App und das Projekt ordnungsgemäß erstellt, aufgebaut und bereitgestellt wurden.
7

App aktualisieren

Nachdem Ihr App-Objektschema hochgeladen wurde, müssen Sie die in Ihrer app-hsmeta.json-Datei definierten Bereiche aktualisieren, um die im vorherigen Schritt erstellten Bereiche widerzuspiegeln. Diese Bereiche sollten in den CLI-Protokollen sichtbar sein, nachdem Sie hs project upload ausgeführt haben.
  • Bearbeiten Sie die app-hsmeta.json-Datei und fügen Sie die neuen Bereiche dem Array von requiredScopes innerhalb der auth-Definition hinzu. Wenn zum Beispiel Ihre appId a12345 lautete, dann würden Sie die auth-Definition wie folgt bearbeiten:
"auth": {
  "type" : "oauth",
  "redirectUrls": ["http://localhost:3000/oauth-callback"],
  "requiredScopes": [
    "crm.objects.contacts.read",
    "crm.objects.contacts.write",
    "crm.app.objects.a12345_my_app_object.view",
    "crm.app.objects.a12345_my_app_object.create",
    "crm.app.objects.a12345_my_app_object.edit",
    "crm.app.schemas.a12345_my_app_object.read",
    "crm.app.objects.a12345_my_app_object.merge",
    "crm.app.objects.a12345_my_app_object.delete",
    "crm.app.schemas.a12345_my_app_object.properties.write"
  ],
  "optionalScopes": [],
  "conditionallyRequiredScopes": []
},

​
Hinweis:

  • Kunden können Ihr App-Objekt nur dann sehen, wenn der schemas.read- Bereich in Ihren App-Einstellungen enthalten ist und wird während der Installation/erneuten Autorisierung des OAuth-Ablaufs benötigt. Dies wird dringend empfohlen, auch für alle App-Objektbereiche in Ihren Einstellungen. Auf jeden Fall ist schemas.read obligatorisch für Kunden, damit sie in der Lage sind, darauf zuzugreifen. Zum Beispiel für eine 12345 lautende appId, schließen Sie crm.app.schemas.a12345_MY_APP_OBJECT.read als erforderlichen Bereich ein.
  • Je nach App, mit der Sie testen (Prototyp, Entwicklung, Staging, Produktion), müssen Sie genau darauf achten, wo Sie Ihre bereichsspezifischen Definitionen hinzufügen. Obwohl die Bereitstellung einer Produktions-App noch nicht in dieser Phase der privaten Beta unterstützt wird, ist es im Allgemeinen am sichersten, diese Bereiche als conditionallyRequiredScopes einzuschließen, wenn Sie für die Produktion bereit sind. Erfahren Sie mehr über diese Bereichstypen in der Referenzdokumentation für öffentliche Apps.
  • Wenn Sie mit dem Hinzufügen dieser Bereiche fertig sind und Ihre Änderungen gespeichert haben, führen Sie die folgenden Befehle aus, um Ihre Änderungen auf der Plattform zu übernehmen:
hs project upload
hs project deploy
Nach Abschluss der Bereitstellung können Ihre App und das entsprechende App-Objekt nun mit einem installierten Account getestet werden.
8

Erstellen Sie einen Entwickler-Test-Account (optional) und installieren Sie Ihre App

Wenn Sie noch keinen Test-Account haben, können Sie einen in HubSpot erstellen:
  • Gehen Sie im Navigationsmenü Entwicklung zu Test-Accounts und klicken Sie dann auf Entwickler-Test-Account erstellen. Folgen Sie den Anweisungen, um Ihren neuen Test-Account zu einzurichten.
  • Gehen Sie im Menü der linken Seitenleiste zu Projekte, klicken Sie auf den Namen Ihres neuen Projekts und dann in der Komponentenliste auf die UID Ihrer App.
  • Kopieren Sie auf der Registerkarte Authentifizierung den Installationslink Ihrer App.
  • Verwenden Sie diesen Link, um die App in Ihrem Entwickler-Test-Account zu installieren.
  • Öffnen Sie den Test-Account und gehen Sie zur Seite Verknüpfte Apps, auf der Ihre installierte App aufgelistet sein sollte.
  • Gehen Sie in Ihrem Test-Account zu CRM > Kontakte, klicken Sie dann auf das Dropdown-Menü „CRM-Objekt“ und bestätigen Sie, dass Ihr App-Objekt verfügbar ist.
  • Sie können dann feststellen, ob Ihre Schemadefinition mit Ihrer Konfigurationsdatei übereinstimmt, indem Sie einen neuen Datensatz Ihres App-Objekts erstellen.
app-objekt-verfügbar-im-crm
9

Programmgesteuerter Datenzugriff über die HubSpot-Objekt-API

Nachdem Sie Ihr App-Objekt erfolgreich erstellt und in einem Entwickler-Test-Account getestet haben, können Sie das OAuth-Zugriff-Token der dem installierten Test-Account zugeordnet ist, verwenden, um Anfragen zur Aktualisierung von Daten im Account direkt über die Objekte-API zu stellen.Lesen Sie sich die Anleitung zur Objekte-API durch, um weitere Informationen über die API zu erhalten. Alle Anfragen, die sich auf Ihr App-Objekt beziehen, folgen aber den gleichen Konventionen wie andere Standardobjekte in HubSpot auch. Sie müssen die objectTypeId Ihres App-Objektes oder den fullyQualifiedName als objectType-Pfadparameter in Ihrer Anfrage verwenden.Der folgende Codeblock zeigt beispielsweise, wie Sie eine cURL-Anfrage zum Erstellen eines neuen Datensatzes Ihres App-Objekts durchführen:
curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/<fullyQualifiedName> \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'
Sie können die objectTypeId für Ihr App-Objekt über die Indexseite für Datensätze finden:
  • Gehen Sie zu CRM > Kontakte im Entwickler-Test-Account, in dem Sie Ihre App installiert haben.
  • Klicken Sie auf das Dropdown-Menü oben auf der Seite und wählen Sie Ihr App-Objekt aus.
  • Die objectTypeId wird in der URL zwischen den einzelnen Abschnitten /objects/<objectTypeId>/views angezeigt.

​
Nächste Schritte

In der Referenzdokumentation finden Sie Informationen zu den nächsten Schritten und dazu wie sich App-Objekten mit verschiedenen Funktionen der Entwicklerplattform verwenden lassen:
⌘I