该软件包允许您引导基于 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值。
