CRM-Karten
Benutzerdefinierte CRM-Karten ermöglichen es, Informationen aus anderen Systemen in HubSpot-Kontakt-, Unternehmens-, Deal- oder Ticket-Datensätzen anzuzeigen. Mithilfe dieser Funktion können Apps benutzerdefinierte Karten erstellen, um diese Daten anzuzeigen. Wenn sich Ihre Daten direkt in HubSpot befinden sollen, jedoch keines der nativen Objekte Ihren Anforderungen entspricht, sollten Sie überlegen, ob vielleicht benutzerdefinierte Objekte Ihre Anforderungen erfüllen.
Beispiel für einen Anwendungsfall: Ihr Entwicklerteam verwendet einen Softwaredienst, um Bugs nachzuverfolgen, aber Ihre Kundendienstmitarbeiter nutzen HubSpot. Ihre Vertriebsmitarbeiter möchten Informationen zu den Bugs ihrer Kunden sehen, ohne HubSpot verlassen zu müssen. Ihre App kann eine benutzerdefinierte Karte definieren, auf der diese Informationen direkt im HubSpot-Kontaktdatensatz angezeigt werden.
So funktioniert es
Karten können als Teil der Funktionseinstellungen Ihrer App definiert werden. Sobald die App installiert ist und ein Benutzer die Ziel-CRM-Datensätze anzeigt, stellt HubSpot eine ausgehende Anfrage an die App, ruft die relevanten Daten ab und zeigt sie auf einer Karte auf der Datensatzseite an. Apps können ebenfalls benutzerdefinierte Aktionen angeben, die der Benutzer basierend auf diesen Informationen durchführen kann. Ein Beispiel für eine benutzerdefinierte Aktion ist das Öffnen eines modalen Dialogfeldes und die Anzeige der eigenen UI der App in HubSpot.
Hier ist ein Beispiel für eine CRM-Karte:
Und hier ist ein Beispiel für den Datenfluss, um Karteneigenschaften im CRM anzuzeigen:
Einrichten von CRM-Karten
CRM-Karten können in Ihrem Entwickler-Account erstellt und konfiguriert werden. Einzelne Details auf der Karte werden durch Karteneigenschaften dargestellt, und die Titel für diese Eigenschaften können (optional) zum System des Integrators verlinken. Bitte beachten Sie, dass der Text „Powered by“ auf der Karte den App-Namen von Ihren App-Einstellungen verwendet.
Wählen Sie im Apps-Dashboard die App aus, für die Sie eine Karte hinzufügen möchten, und gehen Sie dann zu „CRM-Karten“. Klicken Sie auf die Schaltfläche „CRM-Karte erstellen“, um loszulegen.
Anforderungen an den Bereich
Um benutzerdefinierte CRM-Karten zu erstellen, muss Ihre App die OAuth-Bereiche anfordern, die erforderlich sind, um die CRM-Datensätze zu ändern, in denen Ihre Karte angezeigt wird. Dies bedeutet, dass Sie den contacts
-Bereich anfordern, um eine Karte für Kontakte, Unternehmen oder Deals einzurichten, sowie den tickets
-Bereich für Tickets.
Weitere Informationen zu Bereichen und zum Einrichten der Autorisierungs-URL für Ihre App finden Sie in der OAuth-Dokumentation.
Entfernen von Bereichen
Wenn Ihre App bereits CRM-Karten verwendet, können Sie die contacts
- oder tickets
-Bereiche erst entfernen, wenn Sie alle vorhandenen Karten für die zugehörigen Objekttypen gelöscht haben.
Erstellen neuer Karten
Das Erstellen von Kartenvorlagen ist der erste Schritt bei der Verwendung von CRM-Karten. Dies ist, was ein Benutzer sieht:
Konfigurieren von Karten über die API
Erfahren Sie mehr über das Verwalten von Karten über die API auf der Registerkarte „Endpunkte”.
Konfigurieren von Karten über die Benutzeroberfläche mit den App-Einstellungen
Sie können CRM-Karten* auch in Ihrem Entwickler-Account unter den Funktionseinstellungen Ihrer App erstellen und verwalten. (Siehe vorherige Anweisungen.)
*Sie können bis zu 25 CRM-Karten pro App erstellen.
Verwandte Dokumente
Datenabrufanfragen
Wie auf der Registerkarte „Übersicht“ erläutert, stellt HubSpot jedes Mal eine Datenabrufanfrage an Ihre App, wenn ein Benutzer den zugehörigen CRM-Datensatz aufruft. Diese Anfragen werden an die festgelegte Abruf-/Ziel-URL der Karte gesendet. Eine Payload stellt dabei Details für den zugehörigen CRM-Datensatz bereit.
Antworten können bis zu fünf Karteneigenschaften enthalten. Wenn für ein bestimmtes CRM-Objekt weitere Karteneigenschaften verfügbar sind, kann Ihre App zu ihnen verlinken.
Beachten Sie, dass die Zeit für die Anfrage nach fünf Sekunden abläuft. Innerhalb dieser Zeit muss eine Verbindung mit 3 Sekunden hergestellt werden.
Beispiel für eine Datenabrufanfrage
GET: https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com
Mit einem Header:
X-HubSpot-Signatur: <some base64 string>
Der X-HubSpot-Signatur
-Header stellt eine Verifizierung dafür bereit, dass die Anfrage von HubSpot stammt. Weitere Informationen finden Sie unter Anfragesignaturen.
Abfrageparameter:
userId
: Die numerische Benutzer-ID des Kunden, der Daten anfordert.userEmail
: Die HubSpot-Adresse des Benutzers, der Daten anfordert.portalId
: Die HubSpot-Account-ID des Kunden, der Daten anfordert. Account und Portal werden synonym verwendet.associatedObjectId
: Die ID für das aktuelle Objekt, abhängig vomassociatedObjectType
. Dies ist dann diecompanyId
,dealId
,contact vID
oderobjectId
für Tickets.associatedObjectType
: Der Objekttyp, zu dem der Benutzer Daten anfordert (contact
,company
,deal
oderticket
). Dies ist einer der für diesen Datensatztyp bereitgestelltenassociatedHubSpotObjectTypes
.- Und Werte für die angeforderten
associatedHubSpotObjectTypeProperties
. Wenn eine der Anfrageeigenschaften nicht für das aktuelle Objekt definiert ist, wird sie nicht in der Abfragezeichenfolge aufgeführt. Im obigen Beispiel ist die Domain der Unternehmenseigenschaft enthalten. Anfrageeigenschaften können, wie im nachfolgenden Screenshot zu sehen, über die Benutzeroberfläche mit den App-Einstellungen definiert werden:
Beispielantwort:
Definitionen:
results
: Eine Liste mit bis zu fünf gültigen Karteneigenschaften.results[].objectId
: Eine eindeutige ID für dieses Objekt. Diese Eigenschaft ist erforderlich.results[].title
: Der Titel dieses Objekts. Diese Eigenschaft ist erforderlich.results[].link
: Der URI, dem der Benutzer folgen kann, um weitere Details zu diesem Objekt abzurufen. Diese Eigenschaft ist optional, wenn jedoch keines der Objekte über einen Link verfügt, sollten Sie den Wert Null angeben.results[].properties
: Eine Liste benutzerdefinierter Eigenschaften, die nicht in den Karteneinstellungen definiert sind. Sie können diese Liste verwenden, um eindeutige Eigenschaften eines bestimmten Objekts anzuzeigen. Diese Eigenschaften werden in der Reihenfolge angezeigt, in der sie angegeben werden, aber nach den in den Karteneinstellungen definierten Eigenschaften. Diese Eigenschaft ist optional.results[].actions
: Eine Liste mit verfügbaren Aktionen, die ein Benutzer für dieses Objekt durchführen kann. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.totalCount
: Die Gesamtanzahl der verfügbaren Karteneigenschaften, wenn es mehr als fünf gibt, die mit dem angeforderten CRM-Objekt zusammenhängen. Diese Eigenschaft ist optional.allItemsLink
: Ein URI, der alle Karteneigenschaften im Zusammenhang mit dem angeforderten CRM-Objekte anzeigt, wenn es mehr als fünf gibt. Diese Eigenschaft ist optional.itemLabel
: Das Label, das im Link „Mehr anzeigen“ verwendet werden soll, z. B. „Mehr Tickets anzeigen". Diese Eigenschaft ist optional. Wird sie nicht angegeben, wird standardmäßig der Kartentitel angezeigt.settingsAction
: Eine Iframe-Aktion, mit der Benutzer die Einstellungen der App aktualisieren können. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.primaryAction
: Die primäre Aktion für einen Datensatztyp, in der Regel eine erstellende Aktion. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.secondaryActions
: Eine Liste der auf Kartenebene angezeigten Aktionen. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.
Zusätzlich zu den oben genannten Eigenschaften kann der Integrator Werte für die in den Karteneinstellungen definierten Eigenschaften bereitstellen. Im obigen Beispiel ist dies die erstellte JSON-Eigenschaft:
"created":"2016-08-04"
Stellt einen Wert für dieses Objekt für die vordefinierte created
-Eigenschaft bereit.
Verarbeiten von Action-Hooks
Wenn ein Benutzer auf eine Aktion klickt, die als Action-Hook definiert ist, sendet HubSpot eine Anfrage mithilfe der in der Aktionsrichtlinie festgelegten URI und HTTP
-Methode.
Beispielanfrage:
DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com
Mit einem Header:
X-HubSpot-Signatur: <some base64 string>
Abfrageparameter:
userId
: Die numerische Benutzer-ID des Kunden, der Daten anfordert.userEmail
: Die HubSpot-Benutzeradresse des Kunden, der Daten anfordert.associatedObjectId
: Die ID für das aktuelle Objekt, abhängig vomassociatedObjectType
. Dies ist dann diecompanyId
,dealId
,contact vid
oderobjectId
für Tickets.associatedObjectType
: Der Objekttyp, zu dem der Benutzer Daten anfordert (contact
,company
,deal
oderticket
).portalId
: Die Account-ID (auch Hub-ID genannt) des Kunden, der Daten anfordert.- Und Werte für die angeforderten
associatedObjectProperties
. Wenn eine der angeforderten Eigenschaften nicht für das aktuelle Objekt definiert ist, wird sie nicht in der Abfragezeichenfolge aufgeführt. Im obigen Beispiel ist die Domain der Unternehmenseigenschaft enthalten.
Anhand des X-HubSpot-Signatur
-Headers kann der Integrator verifizieren, dass eine Anfrage von HubSpot kam. Weitere Informationen finden Sie unter Anfragesignaturen.
Beispielantwort:
{"message": "Objekt erfolgreich gelöscht"}
HubSpot versucht, Antworten auf Action-Hooks als JSON zu analysieren, und sucht nach einer Nachrichteneigenschaft. Der Benutzer erhält sowohl bei einem Erfolg als auch bei einem Fehlschlagen eine entsprechende Meldung.
Ein Antwortstatuscode von 2XX
bedeutet eine Erfolgsmeldung und ein Antwortstatuscode von 4XX
oder 5XX
bedeutet eine Fehlermeldung.
Aktionstypen
Die folgenden Abschnitte enthalten Details zu jeder Art von Aktion, die angegeben werden kann.
Iframe-Aktionen
Wenn ein Benutzer auf eine iframe-Aktion klickt, wird ein modales Dialogfeld mit einem iframe geöffnet, der auf die angegebene URL verweist.
Beispiel-iframe-Aktion:
Definitionen:
type
: Sollte IFRAME sein, um anzugeben, dass dies eine iframe-Aktion ist.width, height
: Die gewünschten iframe-Abmessungen.uri
: Der im iframe geöffnete URI.label
: Das im Aktions-Dropdown-Menü angezeigte Label.associatedObjectProperties
: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. Die Eigenschaftswerte für das aktuelle Objekt werden als Abfrageparameter an die URI angehängt, wenn Sie den iframe öffnen.
Anweisen des modalen Dialogfeldes zum Schließen
Wenn der Benutzer eine iframe-Aktion abgeschlossen hat, sollte das modale Dialogdialogfeld geschlossen werden und der Benutzer zum ursprünglichen CRM-Bildschirm zurückgeleitet werden. Um das modale Dialogfeld zu schließen, kann die App eine window.postMessage verwenden. Die folgenden Nachrichten werden akzeptiert:
{"Aktion": "FERTIG"}
– Der Benutzer hat die Aktion erfolgreich abgeschlossen.{"Aktion": "ABBRECHEN"}
– Der Benutzer hat die Aktion abgebrochen.
Beispiel: window.parent.postMessage(JSON.stringify({"Aktion": "FERTIG"}), "*");
Hinweis: Modale iframe-Dialogfelder, die über eine iframe-Aktion aufgerufen werden, haben eine responsive Breite.
Action-Hook-Aktionen
Action-Hook-Aktionen senden einen serverseitige Anfrage an eine App. Der einzige UI, die ein Benutzer für diese Aktion sieht, ist eine Erfolgsmeldung oder eine Fehlermeldung. Diese Art von Aktion ist hilfreich bei einfachen Operationen, die keine weitere Benutzereingabe erfordern.
Beispiel für eine Action-Hook-Aktion:
Definitionen:
type
: SollteACTION_HOOK
sein, um anzugeben, dass dies eine Action-Hook-Aktion ist.httpMethod
: DieHTTP
-Methode, die für die Anfrage verwendet werden soll. Dies kannGET
,POST
,PUT
,DELETE
oderPATCH
sein.uri
: Der URI der zu stellenden Anfrage.label
: Das Label, das im Aktions-Dropdown-Menü angezeigt wird.associatedObjectProperties
: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. WennhttpMethod
den WertGET
oderDELETE
hat, werden diese Eigenschaftswerte an den URI der Anfrage als Abfrageparameter angehängt. Andernfalls werden sie als ein JSON-Anfragetext gesendet.
Weitere Informationen zur Implementierung des Aktionspunkts finden Sie unter Verarbeiten von Action-Hooks.
Bestätigungsaktionen
Bestätigungsaktionen verhalten sich wie Action-Hooks, außer dass dem Benutzer ein Bestätigungsdialogfeld angezeigt wird, bevor die serverseitige Anfrage ausgeführt wird.
Definitionen:
type
: SollteACTION_HOOK
sein, um anzugeben, dass dies eine Action-Hook-Aktion ist.httpMethod
: DieHTTP
-Methode, die für die Anfrage verwendet werden soll. Dies kannGET
,POST
,PUT
,DELETE
oderPATCH
sein.uri
: Der URI der zu stellenden Anfrage.label
: Das Label, das im Aktions-Dropdown-Menü angezeigt wird.associatedObjectProperties
: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. WennhttpMethod
den WertGET
oderDELETE
hat, werden diese Eigenschaftswerte an den URI der Anfrage als Abfrageparameter angehängt. Andernfalls werden sie als ein JSON-Anfragetext gesendet.
Weitere Informationen zur Implementierung des Aktionspunkts finden Sie unter Verarbeiten von Action-Hooks.
Bestätigungsaktionen
Bestätigungsaktionen verhalten sich wie Action-Hooks, außer dass dem Benutzer ein Bestätigungsdialogfeld angezeigt wird, bevor die serverseitige Anfrage ausgeführt wird.
Definitionen:
type
: SollteCONFIRMATION_ACTION_HOOK
sein, um anzugeben, dass dies eine Bestätigungs-Action-Hook-Aktion ist.httpMethod
: DieHTTP
-Methode, die für die Anfrage verwendet werden soll. Dies kannGET
,POST
,PUT
,DELETE
oderPATCH
sein.uri
: Der URI der zu stellenden Anfrage.label
: Das Label, das im Aktions-Dropdown-Menü angezeigt wird.associatedObjectProperties
: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. WennhttpMethod
den WertGET
oderDELETE
hat, werden diese Eigenschaftswerte an den URI der Anfrage als Abfrageparameter angehängt. Andernfalls werden sie als ein JSON-Anfragetext gesendet.confirmationMessage
: Die Nachricht, die dem Benutzer im Bestätigungsdialogfeld angezeigt wird.confirmButtonText
: Der Text für die Schaltfläche „OK“. Dies ist optional, da der Schaltflächentext standardmäßig „OK“ ist.cancelButtonText
: Text für die Schaltfläche „Abbrechen“. Dies ist optional, da der Schaltflächentext standardmäßig „Abbrechen“ ist.
Weitere Informationen zur Implementierung des Aktionspunkts finden Sie unter Verarbeiten von Action-Hooks.
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.