Öffentliche Apps

In HubSpot ist eine öffentliche App eine Art von Integration, die Kunden in Ihren Accounts installieren können oder die im App Marketplace gelistet werden kann. Sie erfordert eine Authentifizierung über OAuth. Sobald ein Benutzer Ihre App in seinem HubSpot-Account installiert hat, können Sie API-Aufrufe mithilfe eines OAuth-Zugriffstokens an diesen Account vornehmen. Außerdem wird Ihre App in den Einstellungen von Verknüpfte Apps des Accounts angezeigt.

Verknüpfte Apps können außerdem davon profitieren, sich für Änderungen mithilfe von Webhooks anzumelden und benutzerdefinierte Chronik-Events zu erstellen. 

Nachfolgend erfahren Sie, wie Sie:

Eine öffentliche API erstellen

Wenn Sie eine App in HubSpot erstellen, verknüpfen Sie im Grunde eine von Ihnen erstellte App mit einem App-Entwickler-Account. So legen Sie mit dem Erstellen Ihrer HubSpot-App los:

  • Gehen Sie in Ihrem App-Entwickler-Account in der Hauptnavigationsleiste zu Apps
  • Klicken Sie oben rechts auf App erstellen.
  • Füllen Sie als Nächstes einige grundlegende Informationen und Einstellungen für Ihre App aus. Wenn Benutzer Ihre App mit ihrem HubSpot-Account authentifizieren, sehen sie den Namen, die Beschreibung, das Logo und alle Support-Kontaktinformationen, die Sie auf dieser Seite bereitstellen.

Bitte beachten: Der App-Name wird überall dort verwendet, wo Ihre App in HubSpot angezeigt wird. Dazu gehören die Installation der App sowie die Powered by-Footer für CRM-Karten und Chronik-Events.

  • Klicken Sie auf die Registerkarte Authentifizierung, um Ihre Client-ID und das Client-Geheimnis sowie die der App zugewiesenen Bereiche anzuzeigen. Sie benötigen diese Informationen beim Initiieren einer OAuth-Verknüpfung zwischen Ihrer App und HubSpot.

 

Bereiche konfigurieren

Bereiche bestimmen die Berechtigungen Ihrer App für den Zugriff auf Datenquellen oder Tools in einem Account, der Ihre App installiert hat. Die von Ihnen konfigurierten Bereiche werden als scope- und optional_scope-Abfrageparameter in einer Installations-URL angezeigt, die Sie dann den Benutzern zur Verfügung stellen können.

Bereichstypen

Auf der Registerkarte Authentifizierung stehen Ihnen drei verschiedene Bereichstypen zur Konfiguration zur Verfügung. Sie müssen die Bereiche angeben, die Ihre App für die Installation erfordert, aber Sie können auch zwei andere Bereichstypen angeben: bedingt erforderliche Bereiche und optionale Bereiche.

  • Erforderliche Bereiche: Bereiche, die vom Benutzer autorisiert werden müssen und im scope-Abfrageparameter in der Installations-URL Ihrer App für eine erfolgreiche Installation vorhanden sein müssen.
  • Bedingt erforderliche Bereiche: Bereiche, die nur dann vom Benutzer autorisiert werden müssen, wenn sie im scope-Abfrageparameter in der Installations-URL Ihrer App für eine erfolgreiche Installation vorhanden sind.
    • Mit diesem Bereichstyp können Sie flexibel sein und eine separate Installations-URL für mehrstufige Funktionen oder Bereiche bereitstellen, die nur erforderlich sind, wenn Benutzer bestimmte Funktionen in Ihrer App aktivieren. Beispielsweise könnten Sie Ihren Benutzern zwei Installations-URLs anbieten: Eine Installations-URL könnte den bedingt erforderlichen Bereich in den scope-Abfrageparameter für Benutzer mit Zugriff auf eine Funktion aufnehmen, während eine andere Installations-URL diesen Bereich im scope-Abfrageparameter für Benutzer ohne Zugriff auslässt.
    • Wenn in Ihrer App-Installations-URL ein bedingt erforderlicher Bereich vorhanden ist und ein Benutzer ohne Zugriff auf die zugehörige Funktion versucht, Ihre App über diese URL zu installieren, schlägt die Installation fehl.
  • Optionale Bereiche: Bereiche, die nicht erforderlich sind, um Ihre App erfolgreich zu installieren. Diese Bereiche werden im optional_scope-Abfrageparameter in der Installations-URL Ihrer App angegeben. Wenn Sie beispielsweise möchten, dass Ihre App Daten von benutzerdefinierten Objekten abrufen kann (die nur für Enterprise-Accounts von HubSpot verfügbar sind), können Sie den crm.objects.custom.read-Bereich als optionalen Bereich hinzufügen. Wenn dann ein Account Zugriff auf die benutzerdefinierten Objekte hat, wird der Bereich autorisiert. Andernfalls können sie die App weiterhin ohne den Bereiche „Benutzerdefinierten Objekte“ installieren.

 

Die Bereiche Ihrer öffentlichen App konfigurieren

So passen Sie Ihre Bereichseinstellungen an und fügen neue Bereiche hinzu:

  • Um bedingt erforderliche oder optionale Bereiche zu konfigurieren, klicken Sie auf den Schalter Erweiterte Bereichseinstellungen aktivieren, um ihn zu aktivieren.

turn-on-advanced-scope-settings-toggle-in-public-app-auth-tab

Hinweis: Ab dem 21. Oktober 2024 sind für alle Apps erweiterte Bereichseinstellungen erforderlich. Erfahren Sie mehr über das Änderungsprotokoll für Entwickler von HubSpot.
  • Klicken Sie im Abschnitt Bereiche auf Neuen Bereich hinzufügen.
  • Verwenden Sie im rechten Bereich die Suchleiste, um nach einem Bereich zu suchen, und aktivieren Sie dann das Kontrollkästchen neben dem Bereich, den der Benutzer autorisieren soll. Wenn Sie die erweiterten Bereichseinstellungen aktiviert haben, klicken Sie auf das Dropdown-Menü neben dem Bereich und wählen Sie einen Bereichstyp aus.
  • Klicken Sie auf Aktualisieren.
add-new-scope-panel-in-public-app-setup
  • Überprüfen Sie Ihre konfigurierten Bereiche. Wenn Sie die erweiterten Bereichseinstellungen aktiviert haben, können Sie den Bereichstyp eines beliebigen Bereichs ändern, indem Sie auf das Dropdown-Menü neben dem Bereich klicken. Sie können auch auf Löschen klicken, um einen der Bereiche Ihrer App zu entfernen.
review-new-scope-settings-in-public-app-setup
  • Sobald Sie Ihre App-Einstellungen eingerichtet haben, klicke unten links auf App erstellen.

Mit der erstellten App können Sie nun den Installationsprozess durchlaufen.

Bitte beachten: Es wird empfohlen, der App eine verifizierte Domain hinzuzufügen, um den Benutzern, die Ihre App installieren, eine weitere Vertrauensebene zu verleihen. Andernfalls zeigt die App ein Banner an, das besagt, dass die App nicht verifiziert ist.

Eine App installieren

Bitte beachten: Bevor Sie Ihre App installieren, sollten Sie Folgendes bedenken:

  • Eine App wird erst auf der Seite Verknüpfte Apps eines Accounts angezeigt, wenn die Token für den erstmaligen Zugriff und die Aktualisierung erstellt wurden.
  • Nur Benutzer mit Zugriff auf die erforderlichen oder bedingt erforderlichen Bereiche einer App können eine App installieren.
  • Apps können nicht in Entwickler-Accounts installiert werden. Um Ihre App zu testen, müssen Sie in Ihrem Entwickler-Account einen Test-Account erstellen und sie dort installieren.

Die Installation einer App kann in zwei Schritte unterteilt werden: Autorisierung und Token-Generierung.

Ihre App mit einem Kunden-Account autorisieren 

  • Um Ihre App mit einem HubSpot-Account zu autorisieren, müssen Sie eine Autorisierungs-URL erstellen. Rufen Sie dazu die Client-ID für Ihre App ab und initiieren Sie den OAuth-Prozess.
  • Wenn Ihre URL bereit ist, öffnen Sie sie in Ihrem BVrowser, um eine Liste aller Ihrer HubSpot-Accounts anzuzeigen. Dies ist auch, was Benutzer sehen, sobald Sie sie zu dieser URL weiterleiten.
  • Wählen Sie den Account aus, in dem Sie Ihre App installieren möchten.

select_account-1

  • Nachdem Sie einen Account ausgewählt haben, wird Ihnen eine Liste von Bereichen basierend auf den Parametern &scope= und &optional_scope=, die Sie für die Autorisierungs-URL festgelegt haben, angezeigt.

Bitte beachten: Wenn Sie einen optional_scope berücksichtigen und der ausgewählte Account keinen Zugriff darauf hat (z. B. der Content-Bereich für einen reinen CRM-Account), wird er nicht aufgeführt.

  • Klicken Sie auf Zugriff gewähren, um die Verknüpfung zu autorisieren.

approve_scopes-1

  • Nachdem Sie Zugriff gewährt haben, werden Sie basierend auf dem &redirect_uri=-Parameter in der ursprünglichen Autorisierungs-URL weitergleitet und ein ?code=-Parameter wird an die URL angehängt. Verwenden Sie diesen Code im nächsten Schritt, um ein Zugriffstoken zu generieren.

Die OAuth-Token für den erstmaligen Zugriff generieren 

Um Ihre Token für den erstmaligen Zugriff und die Aktualisierung zu generieren, benötigen Sie den Code vom ?code=-Parameter der Autorisierungs-URL, redirect_url, die Client-ID und das Client-Geheimnis. Detaillierte Anweisungen finden Sie hier

Nachdem Sie Ihre App autorisiert haben und die Token für den erstmaligen Zugriff generiert haben, ist die Installation abgeschlossen. Sie wird auf Ihrer Seite Verknüpfte Apps gelistet und Sie erhalten jetzt Anfragen zum Abrufen von Webhooks und CRM-Karten.

connected_apps-1

 

Öffentliche Apps in HubSpot verwalten

Find an app's ID

Sie können die ID einer öffentlichen App in Ihrem App-Entwickler-Account auf eine der folgenden Arten finden:

  • Gehen Sie in Ihrem Entwickler-Account in der Hauptnavigationsleiste zu Apps und zeigen Sie dann die App-ID an, die unter dem Namen Ihrer App aufgeführt ist.
find-app-id
  • Gehen Sie in Ihrem Entwickler-Account in der Hauptnavigationsleiste zu Apps und klicken Sie dann auf den Namen der App. Klicken Sie auf der Seite Grundlegende Informationen auf die Registerkarte Authentifizierung und zeigen Sie dann die App-ID an.

find-app-id-auth-settings

App-Verhalten überwachen

HubSpot protokolliert alle Anfragen, die an oder von einer verknüpften App vorgenommen werden, einschließlich eingehender Anfragen mithilfe eines OAuth-Zugriffstokens oder ausgehender Anfragen für Webhooks oder CRM-Karten. 

So zeigen Sie dieses Anfrageprotokoll an:

  • Gehen Sie in Ihrem Entwickler-Account in der Hauptnavigationsleiste zu Apps.
  • Klicken Sie auf den Namen der App.
  • Gehen Sie in der linken Seitenleiste zu Monitoring
  • Verwenden Sie die Registerkarten, um verschiedene Typen von Anfragen anzuzeigen, die an die oder von der App vorgenommen werden. Beim Anzeigen dieser Protokolle können Sie auf eine einzelne Anfrage klicken, um weitere Informationen zu dieser anzuzeigen, einschließlich:
    • bei erfolgreichen Anfragen die Anfragemethode, der Pfad und die Uhrzeit der Anfrage.
    • bei nicht erfolgreichen Anfragen zusätzliche Fehlerinformationen wie Antwort-Header und -Text.

request_details

Im Folgenden erfahren Sie mehr über die einzelnen Registerkarten der Seite Monitoring.

  • API-Aufrufe: Die Registerkarte API-Aufrufe zeigt alle Anfragen an, die mithilfe eines OAuth-Zugriffstokens an Ihre App durchgeführt wurden. Es kann nach HTTP-Methode, Antwortcode, Zeitrahmen oder Anfrage-URL gefiltert werden.
  • Webhooks: Die Registerkarte Webhooks zeigt HubSpot-Anfragen für alle Webhook-Abonnements Ihrer App an. Filtern Sie nach Antwort (einschließlich Timeouts und Verknüpfungsfehler), Status (Erfolg, erneuter Versuch wird vorgenommen oder Fehler), Abonnementtyp, Zeitrahmen, Versuch, Batch, Event oder Account-ID.

Bitte beachten: Die Versuch-ID wäre eine Kombination von subscriptionId, eventId und attemptNumber von einer spezifischen Anfrage.

  • CRM-Erweiterungen: Auf der Registerkarte CRM-Erweiterungen werden Anfragen für die CRM-Karten Ihrer App angezeigt. Filtern Sie nach Erweiterungsobjekttyp, CRM-Objekttyp (Kontakt, Unternehmen, Ticket oder Deal), Fehler- oder Warnungstyp, Zeitrahmen, Anfrage-ID oder CRM-Datensatz-ID (d. h., eine bestimmte Kontakt-ID).
  • App-Einstellungen: Die Registerkarte App-Einstellungen ermöglicht es Ihnen, die Einstellungsseite Ihrer App zu konfigurieren.

Auf jeder Registerkarte können Sie, wenn in den letzten 30 Tagen zugehörige Ereignisse aufgetreten sind (z. B. ein Webhook-Trigger aufgetreten ist oder ein API-Aufruf durchgeführt wurde), auf Protokolle exportieren klicken, um die zugehörigen Event-Daten in eine CSV-Datei zu exportieren:

  • Konfigurieren Sie im Dialogfeld, Daten von wie vielen Tagen der Export umfassen soll (bis zu 30 Tage).
  • Klicken Sie auf Exportieren. Es wird eine E-Mail-Benachrichtigung an die E-Mail-Adresse gesendet, die Ihrem Benutzer in Ihren HubSpot-Einstellungen zugeordnet ist.

Eine verifizierte Domain hinzufügen

Wenn HubSpot-Benutzer eine App installieren, stimmen sie zu, dem Entwickler der App Zugriff auf seine Account-Daten zu gewähren. Die Identität und der Ruf des Entwicklers spielen jeweils eine wichtige Rolle bei der Entscheidung eines Benutzers, mit der Installation fortzufahren. Um die vollständige Zustimmung der Benutzer bei der Installation einer App zu gewährleisten, zeigt HubSpot auf dem App-Installationsbildschirm eine Meldung an, in der die Verifizierungsstufe der App und das Listing im App Marketplace angezeigt werden:

  • Wenn eine App nicht über eine verifizierte Domain verfügt, zeigt HubSpot auf dem Installationsbildschirm ein Banner an, das besagt, dass die App nicht verifiziert wurde.
    not-verified
  • Wenn die App über eine verifizierte Domain verfügt, aber nicht im App Marketplace gelistet ist, zeigt HubSpot die verifizierte Domain zusammen mit einem Banner auf dem Installationsbildschirm an, das besagt, dass die App nicht von HubSpot überprüft oder genehmigt wurde.verified-not-listed
  • Wenn eine App im App Marketplace gelistet wurde und den App-Überprüfungsprozess von HubSpot bestanden hat, zeigt HubSpot keines der oben genannten Banner an. Sie müssen die Domain nicht verifizieren, wenn Ihre App im App Marketplace gelistet ist.
    verified-and-listed

Eine verifizierte Domain hinzufügen

Um eine verifizierte Domain zur App hinzuzufügen, müssen Sie zuerst die Domain zu den Einstellungen der App hinzufügen und dann einen TXT-Eintrag zu den DNS-Einstellungen der Domain hinzufügen:

  • Gehen Sie in Ihrem App-Entwickler-Account zu Apps.
  • Klicken Sie auf den Namen der App.
  • Gehen Sie in der linken Seitenleiste zu Kontakt & Support.
  • Geben Sie im Feld Unternehmensdomain Ihre Domain ein und klicken Sie dann auf Speichern. Unterhalb der Unternehmensdomain wird eine Meldung angezeigt, dass die Domain noch nicht verifiziert wurde.
  • Klicken Sie auf Verifizieren, um den Verifizierungsvorgang zu starten.

domain-verification-for-app


  • Bestätigen Sie im rechten Bereich, dass die Domain korrekt eingegeben wurde, und klicken Sie dann auf Weiter.
  • Kopieren Sie den erforderlichen TXT-Eintragswert, indem Sie in der Spalte Wert auf Kopieren klicken.
    verify-app-domain-copy-value
  • Erstellen Sie bei Ihrem DNS-Anbieter einen TXT-Eintrag mit dem kopierten Wert. Nachfolgend finden Sie Anweisungen für einige gängige DNS-Anbieter:
  • Nachdem Sie Ihre DNS-Einstellungen aktualisiert haben, gehen Sie zurück zu HubSpot und klicken Sie im rechten Bereich auf Weiter. Die Aktualisierung von DNS-Einträgen kann bis zu 48 Stunden dauern, sodass HubSpot die Änderung möglicherweise nicht sofort erkennt. Sie können jederzeit zu diesem Bildschirm zurückkehren, indem Sie die Option Jetzt verifizieren auf der Seite mit den Einstellungen für Unternehmensdetails erneut auswählen.
  • Nach der Verifizierung sehen Sie im Feld Unternehmensdomain eine Erfolgsstatusanzeige.

Domain verified__export

Zusätzliche Anmerkungen

  • Um das weitere Eigentum an der Domain sicherzustellen, überprüft HubSpot weiterhin regelmäßig, ob der TXT-Eintrag vorhanden ist. Die Installationswarnung wird zurückgegeben, wenn der TXT-Eintrag entfernt oder geändert wird.
  • Derzeit können Sie nur eine verifizierte Domain pro Entwickler-Account haben. Alle Apps in einem Account teilen die verifizierte Domain. Die Domain auf der Installationsseite verlinkt zu Ihrer Root-Domain.
  • Wenn Sie Ihre verifizierte Domain löschen, erhalten alle Apps in Ihrem Entwickler-Account erneut die Installationswarnung. Sie können eine andere Domain verifizieren, der Vorgang dauert jedoch einige Stunden.

 


War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.