該軟體包可讓您引導基於 React 的應用程序，該應用程式與 Zendesk App Framework(ZAF) 集成，並使您能夠快速開始為 Zendesk Sell 開發應用程式。
注意：這些文件基於 Zendesk 開發人員指南。它們僅包含創建與 Zendesk Sell 整合的應用程式時選定的且最必要的資訊。如果您遇到困難或此處沒有足夠的信息，請訪問實際文件。
應用程式中必須包含以下資料夾結構和檔案才能在 Zendesk 產品中成功安裝應用程式：
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
以下是所需文件的簡要說明：
用於銷售應用程式清單的 HubSpot 範例：
{
"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 "
}
}您必須使用manifest.json 中的location屬性聲明您希望應用程式出現在每個產品介面中的位置。這些位置是 iframe 可以在產品中出現的位置。您可以在一種或多種 Zendesk 產品中指定一個或多個位置。預設情況下，您的應用程式將在 Zendesk Sell 右側面板中的所有物件卡（潛在客戶、聯絡人、交易）上可用。
"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 "
}
}
}有關可用位置，請參閱銷售應用程式 API。要了解有關設定應用程式位置的更多信息，請訪問開發人員指南中的設定應用程式位置部分。
當應用程式發出 AJAX 請求時，可以在瀏覽器控制台中查看請求的設定。某些設定可能包含敏感訊息，例如 API 金鑰或令牌。防止此行為的建議方法是使用OAuth Authentication 。另一個選項可以使用Secure Settings 。選擇最適合您的選項。
您可以使用 OAuth2 來驗證對外部服務的所有 API 請求。 OAuth 為您的應用程式提供了一種安全的方式來存取您的帳戶數據，而無需隨請求發送使用者名稱和密碼等敏感資訊。要使用 OAuth 身份驗證，您需要向第 3 方服務註冊您的應用程序，以便為您的應用程式產生 OAuth 憑證。您還需要在應用程式中添加一些功能以實現 OAuth 授權流程。
註冊應用程式時，您將看到一個螢幕，其中顯示新應用程式的設置，包括應用程式名稱、描述以及您應填寫的其他應用程式資訊。您的應用程序，例如客戶端ID、客戶端金鑰、重定向URL 以及您的應用程式所使用的範圍。在您的應用程式和第 3 方服務之間啟動 OAuth 連線時，您將需要這些項目。
Client ID - 此 ID 對於您的應用程式來說是唯一的，用於啟動 OAuth。Client secret - 用於建立和刷新 OAuth 身份驗證。Redirect URL - 使用者在授予應用程式存取權限後將被重定向到此位置。使用以下網址之一：Scope - 可選的安全措施。範圍決定您的應用程式有權存取哪些資料。OAuth URL - 使用者將需要此 URL 來連接您的應用程式。 URL 是根據應用程式的用戶端憑證、重新導向 URL 和範圍配置建構的。請按照以下部分所述在您的應用程式中使用Client ID和Client secret 。
註冊應用程式後，您必須在manifest.json檔案中定義 OAuth 設定。使用您的更新client_id和client_secret 。
"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 "
}您還需要將“oauth”類型的參數新增至參數清單：
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]有關更多信息，請訪問文檔
在您的應用程式碼中，使用佔位符{{setting.access_token}}和secure: true屬性發出 OAuth 請求。
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 ( ... ) ;這是一個純 JSON API。您必須在 PUT 和 POST 請求上提供Content-Type: application/json標頭。您必須對所有請求設定Accept: application/json標頭。
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; 安全性設定是在發出 AJAX 請求時讓代理無法存取設定的另一種方法。設定值僅在代理層的出站請求伺服器端插入。請參閱使用安全設定進行設定。
雖然您可以使用任何自訂 CSS 或前端框架來實現應用程式的外觀和風格，但 Zendesk 建議使用 Zendesk Garden。 Zendesk Garden 旨在成為所有 Zendesk 產品之間風格和組件的共同基準。為了讓您的應用程式與 Zendesk 外觀和風格相匹配，應用程式中預設使用 Zendesk Garden。
例子：
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}有關 Zendesk Garden 中 CSS 類和 React 組件的更多信息，請參閱 Garden.zendesk.com。
ZAF 用戶端允許 iframe 中的應用程式與主機 Zendesk 產品進行通訊。您可以在應用程式中使用用戶端來偵聽事件、呼叫操作以及存取每個位置的屬性。請參閱 ZAF 用戶端 API 指南。
例子：
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )@zendesk/sell-zaf-app-toolbox 套件提供了一系列有用的方法、掛鉤和元件，可幫助您更快、更輕鬆地建立與 Zendesk Sell 整合的 React 應用程式。他們在底層使用 Zendesk 的應用程式框架用戶端。要了解更多信息，請訪問存儲庫。
使用命令列介面導航到包含要測試的應用程式的資料夾。
如果需要，安裝依賴項：
npm install使用以下命令啟動您的應用程式：
npm start在終端機中開啟一個新視窗並啟動伺服器：
npm run server
在瀏覽器中，導覽至您指定要顯示的應用程式的產品頁面（例如交易/潛在客戶/聯絡人卡）並將?zcli_apps=true附加到 URL。例子：
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
在瀏覽器的網址列中，按一下右側的盾牌圖示 (Chrome) 或左側的鎖定圖示 (Firefox)，並同意載入不安全的腳本 (Chrome) 或停用保護 (Firefox)。
注意：Safari 沒有停用保護的選項。
為了檢查並自動修復一些錯誤，請執行：
npm run lint為了格式化您的程式碼：
npm run prettier使用精簡的來源建立一個套件：
npm run build該指令在dist/tmp中建立一個新的 .zip 檔案。現在您的應用程式已準備好作為私人應用程式安裝在您的 Zendesk Sell 中！
Integrations部分，然後選擇Apps標籤。Upload private app按鈕。dist/tmp上傳最新的 .zip 檔案。如果您的應用程式使用 OAuth 或安全性設置，您可以在遠端安裝後繼續在本地測試它。
zcli.apps.config.json的文件plan和paramters鍵）。 {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
}若要尋找應用程式安裝 ID，請以管理員身分登入 Zendesk Sell 實例，然後在同一瀏覽器中開啟以下頁面，將your_subdomain替換為您自己的：
https://your_subdomain.zendesk.com/api/sell/apps/installations.json（在生產中）
找到您安裝的應用程式並記下其id值，而不是其app_id值。
