Das Paket ermöglicht Ihnen das Booten einer React-basierten Anwendung, die in das Zendesk App Framework (ZAF) integriert ist, und ermöglicht Ihnen einen schnellen Einstieg in die Entwicklung von Apps für Zendesk Sell.
Hinweis: Die Dokumente basieren auf dem Zendesk Developer Guide. Sie enthalten nur ausgewählte und hoffentlich die notwendigsten Informationen für die Erstellung einer in Zendesk Sell integrierten App. Wenn Sie Probleme haben oder die Informationen hier nicht ausreichen, schauen Sie sich bitte die aktuelle Dokumentation an.
Die folgende Ordnerstruktur und Dateien müssen in einer App enthalten sein, um die App erfolgreich in einem Zendesk-Produkt zu installieren:
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
Im Folgenden finden Sie kurze Beschreibungen der erforderlichen Dateien:
Beispiel für ein HubSpot for Sell-App-Manifest:
{
"name" : " Hubspot " ,
"author" : {
"name" : " Zendesk " ,
"email" : " [email protected] " ,
"url" : " https://www.zendesk.com "
},
"defaultLocale" : " en " ,
"private" : false ,
"singleInstall" : true ,
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
}
}
},
"version" : " 2.0.3 " ,
"frameworkVersion" : " 2.0 " ,
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
],
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}
} Sie müssen mit der location Eigenschaft in manifest.json angeben, wo Ihre App in jeder Produktschnittstelle angezeigt werden soll. An diesen Stellen können iFrames im Produkt erscheinen. Sie können einen oder mehrere Standorte in einem oder mehreren Zendesk-Produkten angeben. Standardmäßig ist Ihre App in Zendesk Sell auf allen Objektkarten (Lead, Kontakt, Deal) im Bereich auf der rechten Seite verfügbar.
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
},
"deal_card" : {
"url" : " assets/index.html "
}
}
}Informationen zu verfügbaren Standorten finden Sie unter Sell Apps API. Weitere Informationen zum Festlegen des App-Standorts finden Sie im Abschnitt „Festlegen des App-Standorts“ im Entwicklerhandbuch.
Wenn eine App AJAX-Anfragen stellt, können die Einstellungen für die Anfrage in der Browserkonsole angezeigt werden. Einige Einstellungen können vertrauliche Informationen wie einen API-Schlüssel oder ein Token enthalten. Eine empfohlene Möglichkeit, dieses Verhalten zu verhindern, ist die Verwendung OAuth Authentication . Die andere Option kann die Verwendung Secure Settings sein. Wählen Sie die Option, die am besten zu Ihnen passt.
Sie können OAuth2 verwenden, um alle Ihre API-Anfragen an externe Dienste zu authentifizieren. OAuth bietet Ihrer Anwendung eine sichere Möglichkeit, auf Ihre Kontodaten zuzugreifen, ohne dass vertrauliche Informationen wie Benutzernamen und Passwörter mit den Anfragen gesendet werden müssen. Um die OAuth-Authentifizierung verwenden zu können, müssen Sie Ihre Anwendung bei einem Drittanbieterdienst registrieren, um OAuth-Anmeldeinformationen für Ihre App zu generieren. Sie müssen Ihrer Anwendung außerdem einige Funktionen hinzufügen, um einen OAuth-Autorisierungsfluss zu implementieren.
Wenn Sie eine App registrieren, wird Ihnen ein Bildschirm mit den Einstellungen für Ihre neue App angezeigt, einschließlich des App-Namens, der Beschreibung und anderer App-Informationen, die Sie ausfüllen sollten. Darüber hinaus finden Sie auch die Authentifizierungseinstellungen für B. die Client-ID, das Client-Geheimnis, die Umleitungs-URL sowie die von Ihrer App verwendeten Bereiche. Sie benötigen diese Elemente, wenn Sie eine OAuth-Verbindung zwischen Ihrer App und einem Drittanbieterdienst initiieren.
Client ID – Diese ID ist für Ihre App eindeutig und wird zum Initiieren von OAuth verwendet.Client secret – Wird zum Einrichten und Aktualisieren der OAuth-Authentifizierung verwendet.Redirect URL – Benutzer werden an diesen Ort weitergeleitet, nachdem sie Zugriff auf Ihre App gewährt haben. Verwenden Sie eine der folgenden URLs:Scope – Optionale Sicherheitsmaßnahme. Der Bereich bestimmt, auf welche Daten Ihre App zugreifen darf.OAuth URL – Ein Benutzer benötigt diese URL, um Ihre App zu verbinden. Die URL wird basierend auf den Client-Anmeldeinformationen, der Umleitungs-URL und der Bereichskonfiguration Ihrer App erstellt. Verwenden Sie die Client ID und das Client secret in Ihrer Anwendung, wie im folgenden Abschnitt beschrieben.
Sobald Sie Ihre App registriert haben, müssen Sie OAuth-Einstellungen in der Datei manifest.json definieren. Aktualisieren Sie client_id und client_secret mit Ihrer eigenen.
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}Sie müssen der Parameterliste außerdem einen Parameter vom Typ „oauth“ hinzufügen:
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]Weitere Informationen finden Sie in den Dokumenten
Verwenden Sie in Ihrem App-Code den Platzhalter {{setting.access_token}} und eine secure: true -Eigenschaft, um eine OAuth-Anfrage zu stellen.
var settings = {
url : 'https://www.example.com/api/user' ,
headers : { "Authorization" : "Bearer {{setting.access_token}}" } ,
secure : true ,
type : 'GET'
} ;
var client = ZAFClient . init ( ) ;
client . request ( settings ) . then ( ... ) ; Dies ist eine reine JSON-API. Sie müssen einen Content-Type: application/json Header für PUT- und POST-Anfragen bereitstellen. Sie müssen für alle Anfragen einen Accept: application/json -Header festlegen.
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; Sichere Einstellungen sind eine weitere Möglichkeit, Einstellungen für Agenten unzugänglich zu machen, wenn sie AJAX-Anfragen stellen. Die Einstellungswerte werden nur in der ausgehenden Anfrage serverseitig auf der Proxy-Ebene eingefügt. Informationen zum Einrichten finden Sie unter Sichere Einstellungen verwenden.
Während Sie jedes benutzerdefinierte CSS oder Front-End-Framework für das Erscheinungsbild Ihrer App verwenden können, empfiehlt Zendesk die Verwendung von Zendesk Garden. Zendesk Garden ist als gemeinsame Basis für Stile und Komponenten aller Zendesk-Produkte konzipiert. Damit Ihre App dem Erscheinungsbild von Zendesk entspricht, wird in der App standardmäßig Zendesk Garden verwendet.
Beispiel:
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}Weitere Informationen zu den CSS-Klassen und React-Komponenten in Zendesk Garden finden Sie unter garden.zendesk.com.
Der ZAF-Client ermöglicht Ihrer App im Iframe die Kommunikation mit dem Host-Zendesk-Produkt. Sie können den Client in Ihren Apps verwenden, um an jedem Standort auf Ereignisse zu warten, Aktionen aufzurufen und auf Eigenschaften zuzugreifen. Siehe ZAF-Client-API-Leitfaden.
Beispiel:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )Das @zendesk/sell-zaf-app-toolbox-Paket bietet eine Reihe nützlicher Methoden, Hooks und Komponenten, mit denen Sie in Zendesk Sell integrierte React-Apps schneller und mit weniger Aufwand erstellen können. Unter der Haube nutzen sie den App Framework Client von Zendesk. Um mehr zu erfahren, besuchen Sie das Repository.
Navigieren Sie über Ihre Befehlszeilenschnittstelle zu dem Ordner, der die App enthält, die Sie testen möchten.
Installieren Sie bei Bedarf Abhängigkeiten:
npm installStarten Sie Ihre App mit dem folgenden Befehl:
npm startÖffnen Sie ein neues Fenster in Ihrem Terminal und starten Sie den Server:
npm run server
Navigieren Sie in einem Browser zu der Produktseite, auf der Sie die App angegeben haben, die angezeigt werden soll (z. B. Deal-/Lead-/Kontaktkarte) und hängen Sie ?zcli_apps=true an die URL an. Beispiel:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
Klicken Sie in der Adressleiste Ihres Browsers auf das Schildsymbol rechts (Chrome) oder das Schlosssymbol links (Firefox) und stimmen Sie zu, ein unsicheres Skript zu laden (Chrome) oder den Schutz zu deaktivieren (Firefox).
Hinweis: Safari bietet keine Option zum Deaktivieren des Schutzes.
Um Flusen zu beseitigen und einige Fehler automatisch zu beheben, führen Sie Folgendes aus:
npm run lintUm Ihren Code zu formatieren:
npm run prettierErstellen Sie ein Paket mit minimierten Quellen:
npm run build Der Befehl erstellt eine neue ZIP-Datei in dist/tmp . Jetzt kann Ihre App als private App in Ihrem Zendesk Sell installiert werden!
Integrations und wählen Sie dann die Registerkarte Apps aus.Upload private app .dist/tmp in Ihr lokales App-Projekt hoch.Wenn Ihre App OAuth oder sichere Einstellungen verwendet, können Sie sie nach der Remote-Installation weiterhin lokal testen.
zcli.apps.config.jsonplan und paramters ändern). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
} Um die App-Installations-ID zu finden, melden Sie sich als Administrator bei Ihrer Zendesk Sell-Instanz an, öffnen Sie die folgende Seite im selben Browser und ersetzen Sie your_subdomain durch Ihre eigene:
https://your_subdomain.zendesk.com/api/sell/apps/installations.json (in der Produktion)
Suchen Sie Ihre installierte App und notieren Sie ihren id -Wert, nicht ihren app_id -Wert.
