使用Apps框架

使用Apps框架

使用ZAF SDK直接从iframe与Apps框架进行交互。SDK提供了ZAFClient全局对象，允许您的应用程序和主机Zendesk产品之间的跨帧通信。亚博详细信息请参见ZAF客户端API医生。

获取SDK

导入ZAF SDKhttps://static.zdassets.com/亚博zendesk_app_framework_sdk/2.0/zaf_sdk.min.js．例子:

             

              
<脚本类型=＂text / javascript＂src=＂https://static.zdassets.com/亚博zendesk_app_framework_sdk/2.0/zaf_sdk.min.js＂>脚本>
             

在应用中使用URL可确保SDK自动更新为最新的2.0补丁版本，包括任何错误修复。有关更多信息，请参见框架版本．

使用框架api

的得到，集和调用a的方法ZAFClient对象提供了iframe和框架api之间的接口。由于跨帧通信的本质，iframe和框架之间的每个交互都是异步发生的。得到，集和调用返回一个JavaScript承诺对象与调用的结果。

得到

             

              
var客户端=ZAFClient．初始化（）；客户端．得到（“ticket.requester.name”）．然后（函数（数据）｛控制台．日志（数据）；// {"ticket.request .name": "Mikkel Svane"}}）；
             

集

             

              
var客户端=ZAFClient．初始化（）；客户端．集（“ticket.type”，“任务”）；
             

调用

             

              
var客户端=ZAFClient．初始化（）；客户端．调用（“comment.appendText”，“我的打印机着火了”）；
             

大部分电话

的得到，集和调用的方法ZAFClient支持批量呼叫。

大部分得到

             

              
var客户端=ZAFClient．初始化（）；客户端．得到（［“ticket.subject”，“ticket.requester.name”]）．然后（函数（数据）｛控制台．日志（数据）；//{'票。子ject': 'Help, my printer is on fire', 'ticket.requester.name': 'Mikkel Svane' }}）；
             

批量设置

             

              
var客户端=ZAFClient．初始化（）；客户端．集（｛“ticket.subject”：“打印机过热事件”，“ticket.type”：“事件”}）．然后（函数（数据）｛控制台．日志（数据）；//{'票。子ject': 'Printer Overheating Incident', 'ticket.type': 'incident' }}）；
             

批量调用

             

              
var客户端=ZAFClient．初始化（）；客户端．调用（｛“ticket.comment.appendText”：［“我的打印机着火了”]，“ticketFields: priority.hide”：［]}）；
             

错误处理

调用时发生错误得到，集或调用如果有一条路径，则承诺被拒绝，并出现错误。如果路径无效或给出了无效参数，可能会发生错误。

例子:

             

              
//无效路径客户端．得到（“nonExistentPath”）．然后（函数（数据）｛控制台．日志（数据）；//永远不要运行}）．抓（函数（错误）｛控制台．日志（错误．toString（））；// "APIUnavailable: "nonExistentPath"无法找到"nonExistentPath"的处理程序}）；
             

             

              
//无效参数客户端．集（“ticket.form.id”，-1）．然后（函数（数据）｛控制台．日志（数据）；//永远不要运行}）．抓（函数（错误）｛控制台．日志（错误．toString（））；//错误:"ticket.form. "id“无效机票表格id”}）；
             

拨打批量电话时承诺总是解决的。但是，如果其中一个路径无效，或者调用给出了无效参数，则框架将包含一个错误属性，将失败的路径作为键，并将其错误对象作为值。

例子:

             

              
//无效路径客户端．得到（［“ticket.subject”，“nonExistentPath”]）．然后（函数（数据）｛控制台．日志（数据）；/ *｛“ticket.subject”：＇Help, my printer is on fire',“错误”:{'nonExistentPath':错误("无法找到'nonExistentPath'的处理程序")}}* /}）；
             

             

              
//无效参数客户端．集（｛“ticket.subject”：“打印机过热事件”，“ticket.form.id”：-1}）．然后（函数（数据）｛控制台．日志（数据）；/ *｛“ticket.subject”：＇Help, my printer is on fire',“错误”:{“ticket.form.id”：Error("Invalid Ticket Form ID")}}* /}）；
             

额外的资源亚博电脑端

有关可用api的完整列表，请参阅以下文档:

• 核心应用程序API
• 支持应用程序API
• 聊天应用程序API
• 销售应用程序API

使用框架事件

使用在a方法ZAFClient对象侦听事件。有关可用的事件，请参见以下文档中按位置列出的列表:

• 核心应用程序API
• 支持应用程序API
• 聊天应用程序API
• 销售应用程序API

例子:

             

              
var客户端=ZAFClient．初始化（）；客户端．在（“ticket.updated”，函数（）｛handleTicketUpdated（）；}）；
             

钩的事件

钩子事件允许你的应用程序钩到产品事件，并阻止事件的完成，直到你的应用程序响应。

如果您的事件处理程序返回一个承诺，UI将等待直到承诺解决。或者，事件处理程序可以通过返回来中止用户请求假或作为错误消息显示的字符串。的处理程序ticket.save钩子事件阻止用户保存票据:

             

              
var客户端=ZAFClient．初始化（）；客户端．在（“ticket.save”，函数（）｛返回假；}）；
             

你可以注册多个钩子事件。但是，为了继续处理事件(例如，为了提交票据保存)，事件处理程序返回的所有承诺都必须成功解析。如果任何事件处理程序返回被拒绝的承诺、抛出异常或返回假或字符串，则终止事件。如果直接返回字符串或与承诺拒绝一起传递，则该字符串将在UI中显示为错误消息。

例子:

             

              
var客户端=ZAFClient．初始化（）；客户端．在（“ticket.save”，函数（）｛返回客户端．得到（“ticket.comment.text”）．然后（函数（数据）｛返回获取（“https://myapi.example.org/is_polite?comment=”+数据［“ticket.comment.text”]）．抓（函数（）｛扔“你必须更有礼貌些。”；}）；}）；}）；
             

钩子事件有一个30秒的超时时间，在此期间你的应用程序必须做出响应。否则事件将在默认情况下中止。

发送HTTP请求

您可以使用ZAF客户端的请求()方法安全地从客户端Zendesk应用程序发出HTTP请求，例如REST API调用亚博从Zendesk应用程序发出API请求亚博．

在服务器端应用程序中验证Zen亚博desk

Ze亚博ndesk应用程序可以由运行在远程服务器上的web应用程序组成，远程服务器生成并提供装载在Zendesk产品iframe中的所有HTML。没有应用程序逻辑或内容存储在Zendesk基础结构中。亚博当应用程序在产品中打开时，Zendesk必须从服务器端应用程序请求初始亚博页面。随后的页面请求通常来自框架应用程序本身。

如果您正在构建服务器端应用程序，需要考虑的一个安全特性是验证初始页面的HTTP请求是否来自合法的Zendesk产品实例。亚博

为了帮助您，Zendesk亚博可以在初始页面的请求中包含JSON Web令牌(JWT)。接收到请求后，服务器端应用程序可以检查签名令牌，以验证请求来自合法的Zendesk产品实例。亚博这有助于预防降级攻击．

带签名的令牌还包含许多属性(称为索赔)，您的服务器端应用程序可以使用它来查找与您的Zendesk支持帐户相关的外部存储值。亚博

亚博Zendesk仅在对应用程序初始页面的请求中包含JWT令牌位置对象中的manifest.json文件。例子:

             

              
“位置”：｛“支持”：｛“ticket_sidebar”：｛“签署”：真正的，“url”：“https://myapp.example.org/”}}}
             

请注意:此功能仅适用于在远程服务器上指定页面的应用程序位置对象。它不适用于指定托管在Zendesk基础架构上的页面的应用程序，例如“assets/iframe.html”。亚博

在Zendesk中启用JWT令牌亚博

要让Zende亚博sk在初始应用页面的请求中包含JWT令牌，请在应用的属性中包含以下属性之一manifest.json文件:

• 要在所有位置包含应用程序的JWT令牌，请添加“signedUrls”:真的到顶级清单对象。例子:

                 
  
                  
  ｛“名称”：“我的应用”，“signedUrls”：真正的，“位置”：｛…}，…}
                 

或

• 若要仅在特定位置为应用程序包含JWT令牌，请添加“签署”:真的的命名位置位置对象。例子:

                 
  
                  
  “名称”：“我的应用”，“位置”：｛“支持”：｛“ticket_sidebar”：｛“签署”：真正的，“url”：“https://myapp.example.org/”}}}，
                 

在服务器端应用程序中处理JWT令牌

启用JWT令牌后，Zendesk执行以下操作:亚博

• 将初始页面的请求方法从GET更改为POST
• 字段中包含JWT令牌令牌在POST请求的表单数据

因此，请确保您的服务器端应用程序执行以下任务:

• 处理应用程序初始页面的POST请求
• 从请求的表单数据中获取令牌
• 验证JWT令牌

亚博Zendesk使用SHA-256哈希算法(“RS256”)与RSA签署JWT令牌RFC7519）.您的服务器端应用程序应该使用支持此签名算法的JWT客户端库。验证用于编码令牌的JWT算法是RS256有助于防止降级攻击．一个流行的JWT库列表可在jwt.io．

您的JWT库将需要一个公钥来解码令牌。你可以用。获取应用的公钥获取应用程序公钥Zendesk REST API亚博中的端点:

             

              
https：//｛子域名}．亚博．com/api/v2/应用程序/｛app_id}/public_key．pem
             

在哪里{子域名}是您的Zendesk Support实例的子域，以亚博及{app_id}是应用的ID，你可以用列出所有应用程序端点:

             

              
https：//｛子域名}．亚博．com/api/v2/应用程序．json
             

密钥是在Zendesk支持中创建应用程序时生成的，并且如果稍后更新应用程序也不会更改。亚博

请注意:如果应用程序已经在Zendesk支持帐户中创建，则只能获得应用程序的公钥。亚博因此，在修改服务器端应用程序以验证JWT令牌之前，您必须上传应用程序包(仅包括清单文件和任何产品内的品牌资产)到Zendesk Support实例。亚博上传应用程序还不能在用户界面中启用它。

下面的示例展示了服务器端应用程序处理Zendesk JWT令牌的一种方式。亚博Ruby应用程序使用JWT宝石,亚博Zendesk Ruby API客户端，和Sinatra web框架．代码将在示例之后进行解释。

             

              
需要“jwt”需要“辛纳特拉”需要“zendes亚博k_api”client = 亚博ZendeskAPI:: client。New do |config|##使用您的凭据更改这些值配置。url=＇https：//mysubdomain.zendesk.com/api/v2'配置。Username = '(电子邮件保护)＇配置。Password = ' Password '结束app_id = 101 #设置为你的App IDRsa_public_pem = client.connection.get("apps/#{app_id}/public_key.pem").body使用公钥验证应用ID #{app_id}把rsa_public_pemrsa_public = OpenSSL::PKey::RSA.new(rsa_public_pem)设置:protection，除了::frame_optionsPost '/' dodecoded_token = JWT.decode params[:token]， rsa_public, true，算法:'RS256'Jwt_claims = decoded_token.firstUser_info = client.connection.get(jwt_claims["sub"]).bodyUser_name = user_info["user"]["name"]Account_url = jwt_claims["iss"]“欢迎#{user_name}来自#{account_url}!”结束
             

请注意:如果在本地运行此服务器端应用程序(例如，http ://localhost:4567)，通过单击右侧的屏蔽图标(Chrome)或左侧的锁定图标(Firefox)，允许在浏览器中混合内容。

该应用程序执行以下任务:

1. 类创建REST API客户端亚博Zendesk Ruby客户端：

                  
   
                   
   client = 亚博ZendeskAPI:: client。New do |config|…结束
                  

2. 使用客户端发出Zendesk REST API请求来亚博获取应用程序的公钥:

                  
   
                   
   Rsa_public_pem = client.connection.get("apps/#{app_id}/public_key.pem").body
                  

3. 使用Sinatra url路由来处理应用程序初始页面('/')的POST请求:

                  
   
                   
   Post '/' do…结束
                  

4. 从请求中获取令牌并验证它:

                  
   
                   
   Post '/' dodecoded_token = JWT.decode params[:token]， rsa_public, true，算法:'RS256'…
                  

有关Python示例，请参见保护应用程序在开发帮助中心的“构建服务器端应用”系列教程中。

JWT索赔

JWT令牌包含许多属性(称为索赔)，您的服务器端应用程序可以使用它来查找与您的Zendesk支持帐户相关的值。亚博

请注意:除了JWT声明中提供的数据外，JWT令牌不授予对Zendesk产品实例中的任何数据的访问权限。亚博需要外部身份验证方法(例如用户名和密码、API令牌或OAuth)才能从Zendesk产品帐户获取更多信息，这超出了本文的范围。亚博有关更多信息，请参见安全与认证在Zendes亚博k REST API文档中。

使用本地存储

Zendesk托管的应用资产有自己独特的u亚博rl。这意味着应用程序有它们自己的本地存储这是其他应用程序无法共享的。

但是，如果用户对同一应用程序有不同的安装，则不同安装的资产url将是相同的。因此，最好的做法是将本地存储密钥限定到每个安装，以防止在同一浏览器上运行的不同安装之间发生冲突。例子:

             

              
var客户端=ZAFClient．初始化（）；函数setKey（关键，瓦尔）｛返回客户端．元数据（）．然后（函数（元数据）｛返回localStorage．setItem（元数据．installationId+"："+关键，瓦尔）；}）；}函数getKey（关键）｛返回客户端．元数据（）．然后（函数（元数据）｛返回localStorage．getItem（元数据．installationId+"："+关键）；}）；}setKey（“用户名”，“agent_extraordinaire”）；getKey（“用户名”）．然后（函数（用户名）｛控制台．日志（用户名）；/ / agent_extraordinaire}）；
             

地点之间的消息传递

框架使你的应用程序可以与运行在不同应用程序位置的另一个自身实例进行交互实例API。有关更多信息，请参见实例．

例子

下面的示例演示了从一个实例触发事件并从另一个实例侦听事件。对于本例，我们将事件命名为incoming_call．在您自己的代码中，您可以选择任何合适的名称。

这个例子中的应用程序必须运行在nav_bar和top_bar的位置。清单将包含这样的代码片段:

             

              
｛“位置”：｛“支持”：｛“nav_bar”：“资产/ nav_bar.html”，“top_bar”：“资产/ top_bar.html”}}}
             

顶部栏应用程序运行以下代码:

             

              
var客户端=ZAFClient．初始化（）；客户端．在（“incoming_call”，函数（）｛客户端．调用（“窗”）；}）；
             

导航栏应用程序运行以下代码:

             

              
var客户端=ZAFClient．初始化（）；vartopBarClientPromise=客户端．得到（“实例”）．然后（函数（instancesData）｛var实例=instancesData．实例；为（varinstanceGuid在实例）｛如果（实例［instanceGuid]．位置＝＝＝“top_bar”）｛返回客户端．实例（instanceGuid）；}}}）；topBarClientPromise．然后（函数（topBarClient）｛//在顶部栏触发incoming_call事件topBarClient．触发（“incoming_call”）；}）；
             

使用情态对话框

控件中显示iframe模态使用instances.createAPI。情态动词目前只在Zendesk支持中可用。亚博

请注意:使用签署的url特性必须在清单中定义模态位置，并指定要使用的url。

例子

要打开显示当前维基百科主页的模式，使用:

             

              
var客户端=ZAFClient．初始化（）；客户端．调用（“instances.create”，｛位置：“模态”，url：“https://en.m.wikipedia.org/wiki/Main_Page”，大小：｛/ /可选宽度：“450 px”，高度：“300 px”}}）．然后（函数（modalContext）｛//模态现在显示在屏幕上!varmodalClient=客户端．实例（modalContext［“instances.create”]［0]．instanceGuid）；modalClient．在（“modal.close”，函数（）｛//模式已关闭。}）；}）；
             

注:最大推荐宽度80vw，高度80vh。如果内容大于模态的宽度或高度，则显示滚动条。

测试和调试

您可以使用ZCLI在本地运行和测试应用程序。指在本地测试Zendesk应亚博用程序．