设置新应用
在这篇文章中,你将学习如何设置一个新的Zendesk应用程序。亚博
- 创建应用程序启动文件
- 为应用程序设置产品和位置
- 使用Zendesk Garden设计一亚博个应用程序
- 定义和配置应用程序的安装设置
创建应用程序文件
我们建议使用Zendesk命令行界面(ZCLI亚博)为新的Zendesk应用程序创建启动文件。我们还建议使用Zendesk Garden来设计亚博您的应用程序。
使用ZCLI
您可以使用ZCLI创建Zendesk应用程序的启动文件亚博zcli应用:新
命令。当运行该命令时,你可以选择以下Zendesk应用程序支架之一:亚博
基本的应用程序支架的默认支架
zcli应用:新
命令。如果你是Zendesk应用程序开发亚博的新手,我们建议你使用这个脚手架。脚手架包含了Zendesk应用程序所需的文件亚博。要查看scaffold的内容,请参见脚手架包在GitHub上。React应用脚手架这个脚手架是为熟悉Node.js、Webpack和Zendesk Apps框架(ZAF)的有经验的web开发人员设计的。亚博要查看脚手架的内容和设置说明,请参见脚手架包在GitHub上。要了解更多信息,请参见关于Zendesk 亚博React应用脚手架。
的使用说明zcli应用:新
命令,请参见使用Zendesk命亚博令行接口(ZCLI)。
ZCLI取代了处于维护模式的Zend亚博esk Apps Tools (ZAT)。要使用ZAT创建应用程序文件,请参考安装和使用ZAT。
使用Zend亚博esk Garden
虽然你可以使用任何自定义CSS或前端框架的外观和感觉你的应用程序,Zendesk建议使用Zendesk花园。亚博亚博Zendesk花园的设计是所有Zendesk产品之间风格和组件的共同基线。如果你想让你的应用匹配Zendesk的外观和感觉,在你的应用中使用Z亚博endesk Garden的CSS类和React组件。
你可以将Zendesk Gar亚博den的CSS类和React组件从jsdeliver CDN导入到应用的HTML模板中。看到https://www.jsdelivr.com/?query=亚博zendeskgarden。jsdeliver文件是npm包,也可以从npm。看到https://www.npmjs.com/search?q=亚博zendeskgarden。
有关Zendesk Garden中的CSS类和React组件的更多信息,请参见亚博garden.亚博zendesk.com或者是演示应用程序。
文件的要求
要在Zendesk产品中成功安装应用程序,必须包含以下文件夹结构和文件:亚博
资产/
标志。png
标志-小。png
翻译/
在。json
清单。json
其他的都是可选的。例如,您可以将应用程序的其余部分托管在远程应用程序服务器上,包括要框架到Zendesk产品中的HTML文件。亚博
以下是所需文件的简要说明:
manifest.json-描述和配置应用。参见清单参考。
翻译/ en.json-标准的英文翻译文件。看到应用程序国际化。
资产/ logo-small.png-小图标显示在应用程序的标题。你仍然可以上传和安装应用程序没有它,但一个默认的图像将出现在界面上。看到营销资产对于图像规格。
资产/ logo.png-在Zendesk管理页面显示大图标,用于管理应用程序。亚博你仍然可以上传和安装没有它的应用程序,但一个破碎的图像图标将出现在界面上。看到营销资产对于图像规格。
资产/ icon_ * .-应用程序在
nav_bar
,ticket_editor
,或top_bar
位置需要各自的icon_nav_bar.svg
,icon_ticket_editor.svg
或icon_top_bar.svg
文件。看到SVG应用图标和顶部栏,导航栏和票务编辑器图标对于图像规格。
如果你打算在亚博Zendesk市场(与创建一个只在Zendesk账户中运行的私人应用相反),可能需要额外的品牌资产。亚博看到创建应用品牌资产。
设置应用位置
你必须声明你的应用在每个产品界面中的位置位置
财产manifest.json。
例如,在Zendesk支持中,您亚博可以将应用程序放在代理界面票证右侧的面板中。框架将此位置称为ticket_sidebar
(或new_ticket_sidebar
在新票页的情况下)。
“位置”:{
“支持”:{
“ticket_sidebar”:“资产/ iframe.html”
}
},
有关可用位置,请参阅:
一些框架api只对特定位置的应用可用。例如,只有出现在票证页面上的应用程序才能获取和设置票证属性,并侦听票证的变化。
如果你想让应用出现在产品的多个位置,把这些位置添加到产品对象中:
“位置”:{
“支持”:{
“ticket_sidebar”:“资产/ iframe.html”,
“new_ticket_sidebar”:“资产/ iframe.html吗?位置=new_ticket_sidebar",
“nav_bar”:“https://dashboard.myapp.com/nav_bar”,
“top_bar”:“https://dashboard.myapp.com/top_bar”
}
},
一个应用程序可以存在于多个Zendesk产品中。亚博下面的例子显示了一个可能出现在Zendesk支持中的应用程序亚博ticket_sidebar
和Zendesk亚博聊天chat_sidebar
。
“位置”:{
“支持”:{
“ticket_sidebar”:“资产/ iframe.html”,
},
“聊天”:{
“chat_sidebar”:“资产/ chat_iframe.html”
}
},
您必须指定一个对象,而不是一个字符串,以使用在每个位置上启用的某些高级功能。设置对象中的位置属性。
例子:
“位置”:{
“支持”:{
“背景”:{
“url”:“资产/ iframe.html”
},
“ticket_sidebar”:{
“自动”:假
}
}
},
有关可用的位置属性,请参见舱单位置参考。
URL路径可以是绝对的(如果指向外部页面),也可以是相对的(如果指向资产文件夹中的html文件)。
请注意:使用https
用于所有远程的、生产就绪的URL路径。你可以用http
在开发过程中。
定义安装设置
你可以定义你希望产品管理员在安装应用程序期间或之后为应用程序设置的设置。虽然设置是完全可选的,但它们设置和使用都很简单。这个框架甚至会自动为你生成一个设置页面。
注意:如果你正在构建一个多产品的应用程序,你目前不能指定特定于产品的设置。
属性定义设置参数
的财产清单文件。该属性由一个JSON对象列表组成,这些对象表示您希望管理员设置的设置。
例子:
“参数”:[
{
“名称”:“子域名”,
“类型”:“文本”,
“要求”:真正的,
“安全”:假,
“默认”:“yoursubdomain”
},
{
“名称”:“令牌”,
“类型”:“文本”,
“要求”:真正的,
“安全”:真正的
},
{
“名称”:“useSSL”,
“类型”:“复选框”
}
]
你可以在应用中检索设置值client.metadata ()
:
var客户端=ZAFClient。初始化();
客户端。元数据()。然后(函数(元数据){
控制台。日志(元数据。设置);
});
您还可以使用设置自定义manifest.json文件在每个安装的基础上。若要在清单中指定设定值,请使用双花括号。例子:
...
“domainWhitelist”:[“www.example.com”,“.example.com {{setting.subdomain}}”],
欲了解更多有关domainWhitelist
,请参阅使用安全设置。
设置属性
中的每个对象参数
List代表一个设置,可以有以下属性:
名字
设置的名称。
“名称”:“子域名”,
因为你要在应用代码中使用这个值,所以要确保你给它起了合适的名字。
要求
一个布尔值,用于确定用户是否必须定义设置来安装应用程序。
“要求”:真正的,
默认的
如果用户未指定设置,则指定要输入的默认值。可选的。
“默认”:“yoursubdomain”,
的默认的
value用于在管理员安装或更新应用程序时填充参数表单字段。然而,对于已经设置值的现有参数,它将不生效。不要使用默认值作为回退值。如果你的应用需要一个回退值,在应用中实现它。
本地运行的应用程序web服务器不要使用默认的
从manifest.json。看到定义测试设置。
安全
使用可选的“安全”
属性,如果您不希望用户在发出HTTP请求时看到参数中的敏感信息。由于许多应用程序通过HTTP请求来获取或设置信息,如果设置不安全,任何代理都可以在浏览器中查看这些数据。
“安全”:真正的,
的安全
财产对…没有影响默认的
属性。的价值默认的
将保持公开,不应包含任何敏感信息。
有关详情,请参阅使用安全设置。
类型
指定要在该用户的自动生成设置页上使用的控件。
“类型”:“文本”,
框架为安装应用程序的用户生成一个HTML设置页面。以下控件可用:
类型 | 控制 |
---|---|
文本 | 单行输入字段 |
密码 | 一个被屏蔽的单行输入字段 |
复选框 | 单个复选框 |
url | 单行输入字段,验证了正确的URL语法 |
数量 | 单行输入字段,经过验证仅包含数字 |
多行 | 多行文本区。用户输入限制为64Kb |
隐藏的 | 在设置页面上从未显示给用户的参数 |
oauth | 如果你的应用使用OAuth,这是必需的。看到oauth在舱单参考中。该参数永远不会显示给用户 |
用户需要某种用户界面来在安装应用程序时输入设置或在安装应用程序后编辑设置。框架根据manifest文件中定义的设置生成HTML设置页面。控件中的设置顺序呈现页面上的设置类型控件清单文件。例子:
星号表示必填字段。
任何设置的最大长度为64kB。超过此限制将导致错误。
您可以自定义在生成的设置页面中显示的设置标签。中提取的标签和帮助文本翻译文件。要翻译参数和添加帮助文本,请添加参数
属性赋给应用程序
对象在翻译文件中如下所示:
{
“应用程序”:{
“参数”:{
“子域名”:{“标签”:“子域名”},
“令牌”:{“标签”:“令牌”},
“useSSL”:{“标签”:“使用SSL ?”,“helpText”:“使用SSL进行安全连接。”}
}
}
}
更新设置
有时你想在应用程序中更改和保存设置。你可以通过以下REST API端点来实现:
把/ api / v2 /应用程序/安装/ {id} . json
有关更多信息,请参见更新应用安装在REST API文档中。
注意,只有管理员可以更新设置,代理不能。
定义测试设置
在本地测试应用程序时,您需要为任何安装设置指定值。当你为应用程序启动一个ZCLI服务器时,ZCLI会交互式地向你询问这些值。属性中指定设置值zcli.apps.config.json文件代替。
如果你以前用过ZAT,zcli.apps.config.json取代了settings.yml文件。ZCLI服务器不从settings.yml或默认的值从manifest.json。
如果还不存在,创建一个zcli.apps.config.json文件在你的应用程序的根目录。
在zcli.apps.config.json的属性添加您的设置值
参数
对象。例如,如果manifest.json定义了以下安装设置:
“参数”:[
{
“名称”:“mySetting”
},
...
],
...
中指定设置值zcli.apps.config.json为:
{
...
“参数”:{
“mySetting”:“测试价值”
}
}
为应用程序启动一个ZCLI服务器在本地测试Zendesk应亚博用程序。