Letzte Änderung: 11. September 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.
Projektstruktur
- Alle App-Funktionen und -Komponenten müssen innerhalb des in der
hsproject.json
-Konfigurationsdatei angegebenensrc
-Verzeichnisses gespeichert werden. - Alle App-Funktionen und -Komponenten müssen innerhalb des
app/
-Verzeichnisses gespeichert werden. - App-Objektzuordnungen werden innerhalb des
app-object-associations/
-Verzeichnisses definiert. - Webhook-Abonnements werden innerhalb des
webhooks/
-Verzeichnisses definiert. - Benutzerdefinierte Workflow-Aktionen werden innerhalb des
workflow-actions/
-Verzeichnisses definiert. - Alle Kartenfunktionen müssen im
cards/
-Verzeichnisses gespeichert werden. - Für alle alle Komponenten- und Feature-Instanzen ist anzugeben, dass sie
*-hsmeta.json
-Dateien verwenden. Stellen Sie dem Dateinamen etwas Aussagekräftiges voran (z. Bmy-app-hsmeta.json
). Diese Dateien müssen sich auf der Stammebene ihres jeweiligen Ordners befinden (z. B.app/my-app-hsmeta.json
,cards/my-card-hsmeta.json
).
Beispiel auf GitHub anzeigen
App-Objekte
Um ein App-Objekt zu erstellen, fügen Sie einapp-objects
-Komponentenverzeichnis zusammen mit einer Konfigurationsdatei in das Projekt ein.
*-object-hsmeta.json
.
Beispiel auf GitHub anzeigen
Mit * markierte Felder sind Pflichtfelder.
Feld | Typ | Beschreibung |
---|---|---|
uid * | Zeichenfolge | Eine eindeutige ID für das App-Objekt. Muss innerhalb des Projekts global eindeutig sein. |
type * | Zeichenfolge | Der Typ der Komponente. Muss mit dem Namen des übergeordneten Ordners (app-object ) übereinstimmen. |
name * | Zeichenfolge | Der Name Ihres App-Objekts. Verwenden Sie den genehmigten Namen, den Sie in Ihrer Bestätigung über die genehmigte App erhalten haben. Muss in Snake Case und Großbuchstaben (MY_OBJECT_NAME ) geschrieben werden. |
appPrefix | Zeichenfolge | Eine Zeichenfolge, die dem Singular- oder Pluralnamen des Objekts in der Benutzeroberfläche von HubSpot vorangestellt ist, um es von anderen Objekten zu unterscheiden. In diesem Beispiel würde das appPrefix von Vroom und die singularForm von Car dazu führen, dass „Vroom Car“ auf der Benutzeroberfläche angezeigt wird. |
description * | String | die Beschreibung des Objekts, das in HubSpot angezeigt wird. |
singularForm * | Zeichenfolge | Die Singularform des Objektnamens. |
pluralForm * | Zeichenfolge | Die Pluralform des Objektnamens. |
properties * | Array | Eine Liste der für das Objekt definierten CRM-Eigenschaften. Eigenschaften werden mit denselben Feldern wie die Eigenschaften-API definiert. Den resultierenden Eigenschaften wird bei der Erstellung automatisch a<appId>_ vorangestellt (z. B a12345_make ). Sie sollten das Präfix nicht in die Konfigurationsdatei aufnehmen. |
primaryDisplayLabelPropertyName * | Zeichenfolge | Der Name der Eigenschaft, die als primäre Anzeige-Eigenschaft verwendet werden soll. Der Wert muss mit dem in der properties -Liste angegebenen Namen übereinstimmen (d. h., er sollte nicht das generierte a<appId>_ -Präfix enthalten). |
secondaryDisplayLabelPropertyNames * | Array | Die Liste der Eigenschaften, die als sekundäre Anzeigeeigenschaften verwendet werden sollen. Der Wert muss mit dem in der properties -Liste angegebenen Namen übereinstimmen (d. h., er sollte nicht das generierte a<appId>_ -Präfix enthalten). |
settings * | Objekt | Ein Objekt, das Objekteinstellungen enthält. |
hasRecordPage * | BoolescherWert | Bestimmt, ob Datensatzseiten für Instanzen dieses App-Objekts vorhanden sind. Bei Festlegung auf false ist die Indexseite weiterhin vorhanden, enthält jedoch keine Links zu den einzelnen Datensatzseiten. |
allowsUserCreatedRecords * | BoolescherWert | Bestimmt, ob Endbenutzer Datensätze mit dem Objekt erstellen können. Wenn diese Option auf false festgelegt ist, können Benutzer keine Datensätze in HubSpot erstellen. |
hasEngagements * | BoolescherWert | Bestimmt, ob die App-Objektdatensätze Aktivitäten/Interaktionen unterstützen. Wenn diese Option auf false festgelegt ist, enthalten App-Datensatzseiten keine Interaktionfunktionen wie die Registerkarte „Aktivität“ oder aktivitätsbezogene Chronik-Filter. |
Der vollständig qualifizierte Name (Fully Qualified Name, FQN) für Ihr App-Objekt lautet
a<appId>_<objectName>
. Zum Beispiel: Wenn Ihr appId
16858319
und der Name des App-Objekts CARS
lautet , dann wäre a16858319_CARS
der FQN. Sie verwenden den FQN, wenn Sie Bereichswerte für Ihre App-Objekte festlegen.App-Design
Um ein App-Objekt zu erstellen, fügen Sie eineapp-hsmeta.json
-Konfigurationsdatei in das app
-Verzeichnis ein.
app-hsmeta.json
.
Änderungszusammenfassung
Änderungszusammenfassung
Beachten Sie die folgenden Änderungen für App-Kartenkonfigurationsdateien:
uid
-,type
- undconfig
-Felder der obersten Ebene wurden hinzugefügt.extensions
-Feld wurde entfernt.distribution
-Feld wurde hinzugefügt.
Beispiel auf GitHub anzeigen
*-hsmeta.json-Felder für das App-Schema
Mit * markierte Felder sind Pflichtfelder.
Feld | Typ | Beschreibung |
---|---|---|
uid * | Zeichenfolge | Eine interne eindeutige ID für die App. Sie muss innerhalb des Projekts global eindeutig sein und kann eine beliebige Zeichenfolge mit bis zu 64 Zeichen aufweisen. Zeichen können in Groß- oder Kleinbuchstaben geschrieben werden und Ziffern, Unterstriche (_ ), Bindestriche (- ) und Punkte (. ) enthalten. |
type * | Zeichenfolge | Der Typ der Komponente. Muss mit dem Namen des übergeordneten Ordners (app ) übereinstimmen. |
description * | Zeichenfolge | Eine Beschreibung, was die App für den installierenden Benutzer tut. Kann eine beliebige Zeichenfolge mit bis zu 8.192 Zeichen sein. |
name * | Zeichenfolge | Dies ist der Name der App, der in HubSpot angezeigt wird. Kann eine beliebige Zeichenfolge mit bis zu 200 Zeichen sein. Darf nicht mit einem Leerzeichen beginnen oder enden. |
distribution * | Zeichenfolge | Die Methode der App-Verteilung. Muss auf marketplace festgelegt sein, damit die App für ein App Marketplace-Listing berechtigt ist. |
auth * | Objekt | Ein Objekt, das die Details der Authentifizierungsmethode der App enthält. Weitere Informationen finden Sie in der Tabelle zur Authentifizierung. |
permittedUrls | Objekt | Ein Array, das die URLs enthält, die die App aufrufen darf. URLs müssen dem HTTPS-Schema folgen und eine Autorität enthalten, ggf. gefolgt von einem optionalen Pfadpräfix. |
supportEmail | Zeichenfolge | Eine gültige E-Mail-Adresse, an die sich Benutzer wenden können, wenn sie Support benötigen. |
documentationUrl | Zeichenfolge | Die externe URL, zu der Benutzer navigieren können, um die Begleitdokumentation zu erhalten. Muss HTTPS verwenden. |
supportUrl | Zeichenfolge | Die externe URL, zu der Benutzer navigieren können, um zusätzlichen Support zu erhalten. Muss HTTPS verwenden. |
supportPhone | Zeichenfolge | Die Telefonnummer, die Benutzer kontaktieren können, wenn sie Support benötigen. Muss mit einem Pluszeichen (+ ) beginnen. |
Authentifizierungsfelder
Mit * markierte Felder sind Pflichtfelder.
Feld | Typ | Beschreibung |
---|---|---|
type * | Zeichenfolge | Die Art der Authentifizierung. Muss auf oauth festgelegt sein, damit die App die OAuth-Authentifizierung verwenden kann. |
redirectUrls * | Array | Eine Liste von URLs, zu denen der OAuth-Prozess zurückleiten darf. Jede App muss über mindestens eine derartige URL verfügen und HTTPS verwenden. Die einzige Ausnahme ist, dass für http://localhost das Testen erlaubt ist. |
requiredScopes * | Array | Eine Liste der erforderlichen Bereiche Ihrer App. Jede App muss mindestens einen Bereich enthalten, wobei es erforderlich ist, dass der installierende Benutzer diese Bereiche zulässt, wenn die App erfolgreich installiert werden soll. Erfahren Sie im Folgenden mehr über Bereiche. |
optionalScopes | Array | Eine Liste der optionalen Bereiche Ihrer App. Diese Bereiche können bei der Installation von der Autorisierung ausgeschlossen werden, wenn der Account oder der Benutzer, der die App installiert, nicht über entsprechende Berechtigungen verfügt. In diesem Fall wird der Bereich nicht in das resultierende Aktualisierungs- oder Zugriffs-Token aufgenommen. Erfahren Sie im Folgenden mehr über Bereiche. |
conditionallyRequiredScopes | Array | Eine Liste von Bereichen, die nur erforderlich sind, wenn sie im scope -Abfrageparameter der Installations-URL enthalten sind. Erfahren Sie im Folgenden mehr über Bereiche. |
Bereiche
Imauth
-Feld einer App-Konfigurationsdatei können Sie drei Arten von Bereichen angeben: erforderliche Bereiche, bedingt erforderliche Bereiche und optionale Bereiche. Für diese Phase der Beta sollten Sie nur Ihre App-Objektbereiche als conditionallyRequiredScopes
einschließen. Auf diese Weise können Sie Ihre neuen Funktionen für bestimmte Kunden isolieren, indem Sie die App-Objektbereiche in die Installations-URL aufnehmen.
App-Objektbereiche haben das folgende Format:
crm.app.schemas.<appObjectFullyQualifiedName>.read
Für ein App-Objekt mit dem FQN a16858319_cars
wäre der read
-Bereich beispielsweise:
crm.app.schemas.a16858319_cars.read
.
Ihre App muss mindestens den oben genannten read
-Bereich enthalten, damit Kunden auf das Objekt zugreifen können. Es wird empfohlen, alle App-Objektbereiche in Ihrer App zu berücksichtigen, wie im Folgenden angegeben.
Definition von Webhooks-Komponenten
Um einen Satz von Webhook-Abonnements für Ihre App zu definieren, müssen Sie einwebhooks
-Verzeichnis zusammen mit einer *-hsmeta.json
-Konfigurationsdatei in das Projekt einschließen.
*-hsmeta.json
-Datei.
*-hsmeta.json-Felder für Webhooks
Mit * markierte Felder sind Pflichtfelder.
Feld | Typ | Beschreibung |
---|---|---|
uid * | Zeichenfolge | Eine interne eindeutige ID für die Webhook-Komponente. |
type * | Zeichenfolge | Der Typ der Komponente, die in diesem Fall webhooks sein sollte. |
settings * | Objekt | Ein Objekt, das zwei Felder angibt: targetUrl ist die öffentlich verfügbare URL für HubSpot-Aufrufe, an die Event-Payloads geliefert werden, und maxConcurrentRequests stellt den oberen Schwellenwert von HTTP-Anfragen dar, die HubSpot in einem bestimmten Zeitraum vornimmt. |
subscriptions * | Objekt | Ein Objekt, das die Abonnementtypen angibt, die Ihre App abonnieren wird. |
crmObjects | Array | Ein Array mit Definitionen für Event-Abonnements. Dies ist das aufzunehmende Standard-Array, das für alle Events im neuen Format (object.* ) zu verwenden ist. Klassische Webhook-Abonnementtypen sollten aber je nach Event in legacyCrmObjects - und hubEvents -Arrays enthalten sein. |
legacyCrmObjects | Array | Ein Arraymit klassischen Abonnementtypen wie contact.creation und deal.deletion . |
hubEvents | Array | Ein Array mit den klassischen Abonnementtypen contact.privacyDeletion und conversation.* |
subscription
Objekt können die folgenden Felder angegeben werden, je nachdem, welcher Abonnementdefinitionstyp abonniert wird (d. h. crmObjects
, legacyCrmObjects
bzw. hubEvents
) oder abhängig davon, ob Sie eine bestimmte Eigenschaftsänderung abonnieren (z B contact.propertyChange
).
Feld | Typ | Beschreibung |
---|---|---|
subscriptionType | Zeichenfolge | Der Typ des abonnierten Events. |
objectType | Zeichenfolge | Für Abonnements, die innerhalb des crmObjects -Arrays angegeben sind, gibt dies das CRM-Objekt an, das Ihre App abonniert. Um Änderungen an einem App-Objekt zu abonnieren, geben Sie den Namen Ihres App-Objekts in dieses Feld ein (z. B. car_app_object ). |
propertyName | Zeichenfolge | Bei Abonnements von Eigenschaftenänderungen gibt dies an, durch welche Eigenschaft das Webhook-Event ausgelöst wird. |
active | Boolescher Wert | Gibt an, ob Webhook-Events für dieses Abonnement ausgelöst werden. |
Schema der App-Karte
Um eine App-Karte zu erstellen, die auf einer App-Objekt-Datensatzseite angezeigt wird, schließen Sie eincards
-Komponentenverzeichnis zusammen mit einer Konfigurationsdatei in das Projekt ein.
- Stellen Sie sicher, dass Sie
hs project upload
ausgeführt haben, nachdem Sie Ihre App-Objektkomponente und die zugehörigen Konfigurationsdateien erstellt haben. - Fügen Sie in Ihrer
my-app-card-hsmeta.json
-Datei die UID Ihres App-Objekts zumobjectTypes
-Array hinzu (z. B . hier"app_object_uid"
). Jedes der verfügbaren Felder in der.json
-Datei ist in der folgenden Tabelle aufgeführt.
Änderungszusammenfassung
Änderungszusammenfassung
Beachten Sie die folgenden Änderungen für App-Kartenkonfigurationsdateien:
uid
-,type
- undconfig
-Felder der obersten Ebene wurden hinzugefügt.- Das
module
-Feld wurde inentrypoint
umbenannt. - Das
title
-Feld wurde inname
umbenannt. - Das
objectTypes
-Feld wurde vereinfacht, um ein Zeichenfolgen-Array zu akzeptieren.
- Nachdem Sie die Änderungen an Ihrer
example-card-hsmeta.json
-Datei gespeichert haben, führen Siehs project upload
aus.
Beispiel auf GitHub anzeigen
Felder für *-hsmeta.json-App-Karten
Mit * markierte Felder sind Pflichtfelder.
Feld | Typ | Beschreibung |
---|---|---|
uid * | Zeichenfolge | Die eindeutige ID der Karte. Sie kann eine beliebige Zeichenfolge sein, sollte aber die Karte sinnvoll identifizieren. HubSpot identifiziert die Karte anhand dieser ID, sodass Sie den Titel der Karte ändern können, ohne historische oder zustandsbehaftete Daten, wie z. B. die Position im CRM-Datensatz, zu entfernen. |
type | Zeichenfolge | Der Typ der Komponente, die in diesem Fall card sein sollte. |
config | Objekt | Ein Objekt, das Konfigurationsdetails enthält. |
name * | Zeichenfolge | Der Titel der Karte, wie auf der Benutzeroberfläche von HubSpot angezeigt. |
description | Zeichenfolge | Eine Beschreibung der Karte. |
previewImage | Objekt: | Ein Objekt, das die file - und altText -Felder enthält. Das file -Feld ist der relative Pfad zum Vorschaubild. Gültige Dateierweiterungen sind png, jpeg, jpg oder gif. Die maximale Dateigröße beträgt 5.0 MB. Das altText -Feld ist eine Kurzbeschreibung des Bildes. |
entrypoint * | Zeichenfolge | Der Dateipfad des Front-End-React-Codes der Karte. |
location * | crm.record.tab | crm.record.sidebar | helpdesk.sidebar | Wo die Karte auf der Benutzeroberfläche von HubSpot angezeigt wird. Erfahren Sie mehr über den Speicherort der Erweiterung. |
objectTypes * | Array | Die Typen von CRM-Datensätzen, in denen die Karte angezeigt wird. |
App-Objektzuordnungen
Um Verknüpfungen zwischen Ihrem App-Objekt und anderen CRM-Objekten zu ermöglichen, fügen Sie einapp-object-associations
-Komponentenverzeichnis zusammen mit einer Konfigurationsdatei in das Projekt ein.
*-association-hsmeta.json
) aufgeführt.
*-Zuordnungs-hsmeta.json-Felder zur Zuordnung
Mit * markierte Felder sind Pflichtfelder.
Feld | Typ | Beschreibung |
---|---|---|
uid * | Zeichenfolge | Eine interne eindeutige ID für die App. Muss innerhalb des Projekts global eindeutig sein. |
type * | Zeichenfolge | Der Typ der Komponente. Muss mit dem Namen des übergeordneten Ordners (app-object-association ) übereinstimmen. |
config * | Objekt | Ein Objekt, das die Konfiguration der Objekt-Zuordnung enthält. |
firstObjectType * | Zeichenfolge | Das erste Objekt in der Zuordnung. Kann entweder ein App-Objekt oder ein HubSpot-CRM-Objekt sein. App-Objekte werden mit der in ihrer Quelldatei angegebenen uid referenziert. Standardobjekte werden mit ihrem jeweiligen fullyQualifiedName referenziert. Die resultierende Zuordnung ist bidirektional, sodass die Reihenfolge der Feldwerte willkürlich ist. |
secondObjectType * | Zeichenfolge | Das zweite Objekt in der Zuordnung. Siehe firstObjectType für Details. |