在 Chat 小组件中启用已通过身份验证的访问者

我的服务模式是什么？

Support 以及

实时在线交谈和消息传送，任意服务模式

您可以配置小组件，以便使用新的 JavaScript API 和 JWT 密钥对每次页面加载的访问者进行身份验证。

本文章适用于使用以下 Chat 版本的客户：

• Zendesk Chat 第 3 阶段（仅限 Chat）

如果您使用的是以下任意版本，请参阅在 Web Widget（经典）中启用已通过身份验证的访问者：

• Zendesk Chat 第 4 阶段（仅限 Chat 或有 Support）
• Zendesk Chat 第 3 阶段（Web Widget (Classic) 中有实时在线交谈功能）

如需帮助识别您正在使用的 Chat 版本，请参阅确定您的 Zendesk Chat 帐户版本。

本文章涵盖以下主题：

• 概览
• 生成 Chat 共享密钥
• 创建 JWT 密钥
• 代码范例
• 关于已通过身份验证的访问者的专员体验
• 关于已通过身份验证的访问者的小组件体验

概览

当您将 Chat 小组件配置为使用已通过身份验证的访问者时，您将获得以下好处：

• 更有信心确认与您或您的专员交谈的访问者/客户的真实性。

• 支持跨域名流量。如果您要将小组件嵌入多个域名或链接到外部托管服务（例如：Shopify），对访问者进行身份验证后，将使其跨多个域名访问 Chat 平台，这使您的专员可以获得更多上下文信息。

• 支持跨设备/浏览器识别。如果访问者选择使用不同的设备或浏览器（在身份验证调用中指定了自定义 ID），则可以将其视为同一个人。

生成 Chat 共享密钥

要配置小组件以进行访问者身份验证，您需要一个共享密钥。共享密钥是一种安全设置，旨在一次性生成、复制并粘贴到与您的工程团队的通讯中，或直接粘贴到您的代码库中。不应将其输入浏览器。

只有 Chat 管理员可以配置访问者身份验证设置。

生成已通过身份验证的访问者所需的共享密钥

1. 打开 Chat 面板并前往设置 > 小组件。
2. 单击小组件安全标签。
3. 向下滚动到“访问者身份验证”部分，然后单击生成按钮。

注意：共享密钥旨在保持安全。因此，它只会完整显示一次。如果您无权访问共享密钥，但需要完整的密钥来创建密钥，您可以单击“重新生成”按钮重置密钥。

重新生成新的共享密钥将撤销之前的密钥。如果您担心共享密钥已泄露，则应重新生成一个新密钥。如果您需要轮换密钥，则应计划在 Chat 离线时进行，因为重新生成密钥可能会导致访问者与小组件断开连接 5 分钟。

当您生成了共享密钥后，用它来创建一个 JWT 密钥（了解更多关于 JWT 的信息），您将把它添加到您的 Web Widget 代码段中。

创建 JWT 密钥

创建 JWT 密钥并将代码添加到 Chat 独立代码段

1. 构造 JWT 密钥的服务器端数据负载。这需要有以下信息：
   • 名称：客户的名称
   • 电邮：客户的电邮
   • external_id：字母数字字符串，用于识别客户的唯一性。此值一旦为客户设置，就无法更改。我们建议您对此字段使用系统的唯一用户 ID。例如，user-123456。
   • iat：当前时间戳的整数值，以秒为单位。特定语言中的一些函数，即 JavaScript 的 Date.now() 返回毫秒，因此请确保您转换为秒。用于 Chat 的身份验证允许最多两分钟的时钟偏差。
   • exp：当前时间戳的整数值，以秒为单位。此值指示此 JWT 密钥何时过期。该值与 iat 值之间的最大相差 7 分钟
2. 在 JWT 有效载荷的页首中指定 HS256 为 JWT 算法：

   {
     "typ":"JWT",
     "alg":"HS256"
   }

   HS256 即 HMAC SHA 256，是美国国家安全局设计的一种 256 位加密算法。

   注意：Zendesk 不支持 RS256 和 ES256 JWT 算法。
3. 使用下面的代码示例查找适合您语言需求的模板。
4. 使用 $zopim.livechat.authenticate Javascript API 提供一个函数，该函数每次被调用时都会提供一个全新的 JWT。下面是代码示例：

   $zopim(function() {
     $zopim.livechat.authenticate({
       jwtFn: function(callback) {
         fetch('JWT_TOKEN_ENDPOINT').then(function(res) {
           res.text().then(function(jwt) {
             callback(jwt);
           });
         });
       }
     });
   });

   在上面的例子中，JWT_TOKEN_ENDPOINT 是一个端点，可以在您自己的服务器上实现，以获取全新的 JWT。

   注意：可以在整个在线交谈会话中多次调用 jwtFn，以获取新的 JWT，以便在会话的整个生命周期中验证访问者的身份。
5. 当用户退出主机应用/网站时，您可以使用 $zopim.livechat.clearAll() API 从小组件退出。

   对于单页应用，请注意在使用 $zopim.livechat.clearAll() API 后无法对访问者重新进行身份验证。您将需要重新加载页面，以便对访问者再次进行身份验证。

代码范例

您的密钥需要在页面加载时从服务器端动态生成。在下面找到适合您语言需求的模板。根据需要自定义示例，确保将 #{details} 替换为您自己的信息。

如果这些示例中没有一个符合您的需求，JWT 有一个更广泛的 JWT 库列表可供您探索。

• Ruby
• NodeJS
• Python
• PHP
• Elixir

Ruby

首先，安装 ruby-jwt。

如果您正在使用 Rubygems：

gem install jwt

如果您使用的是 Bundler，请将以下内容添加到您的 gem 文件中：

gem 'jwt'

接下来，使用共享密钥生成一个密钥：

require 'jwt'
payload = {
  :name => "#{customerName}",
  :email => "#{customerEmail}",
  :iat => timestamp,
  :external_id => "#{externalId}"
}
token = JWT.encode payload, "#{yourSecret}"

NodeJS

安装 jsonwebtoken：

npm install jsonwebtoken --save-dev

然后，使用共享密钥生成一个密钥：

var jwt = require('jsonwebtoken'); 
var payload = {
  name: '#{customerName}',
  email: '#{customerEmail}',
  iat: #{timestamp},
  external_id: '#{externalId}'
};
var token = jwt.sign(payload, '#{yourSecret}');

Python

安装 python-jose：

pip install python-jose

使用共享密钥生成一个密钥：

from jose import jwt
var payload = {
  'name': '#{customerName}',
  'email': '#{customerEmail}',
  'iat': #{timestamp}, 
  'external_id': '#{externalId}'
}
token = jwt.encode(payload, '#{yourSecret}'

PHP

下载 PHP-JWT：

composer require firebase/php-jwt

使用共享密钥生成一个密钥：

use \Firebase\JWT\JWT;
$payload = {
  'name' => '#{customerName}' ,
  'email' => '#{customerEmail}',
  'iat' => #{timestamp},
  'external_id' => '#{externalId}'
};
$token = JWT::encode($payload, '#{yourSecret}');

Elixir

将“json_web_token_ex”添加到您的“mix.exs”文件：

defp deps do
  [{:json_web_token, "~> 0.2"}]
end

使用共享密钥生成一个密钥：

data = %{
  name: "#{customerName}",
  email: "#{customerEmail}",
  iat: "#{timestamp}",
  external_id: "#{externalId}"
}
options = %{ key: "#{yourSecret}" }
jwt = JsonWebToken.sign data, options

关于已通过身份验证的访问者的专员体验

当专员开始与已通过身份验证的访问者在线交谈时，Chat 面板中会更新一些内容。

首先，专员可通过访问者头像上的绿色已验证勾选标记来识别访问者已通过身份验证：

专员还会注意到，他们无法编辑访问者的姓名或电邮，因为真实的来源来自通过 Javascript API 发送的信息。

最后，禁止已通过身份验证的访问者将意味着该访问者无法跨设备和浏览器访问 Chat 小组件。

关于已通过身份验证的访问者的小组件体验

已通过身份验证的访问者在 Chat 小组件中的体验也略有不同。首先，他们的信息是只读的，不能通过小组件或 Javascript API 进行修改。

其次，当访问者通过身份验证时，正在进行的在线交谈会话将在各个设备之间同步。例如，如果访问者在桌面网络浏览器和移动网络浏览器上的 Chat 小组件之间切换，则可以灵活地切换计算机/浏览器并继续其正在进行的在线交谈会话。

注意：由于当前的 Chat 移动 SDK 不支持访问者身份验证，当使用 Chat SDK 在桌面小组件和移动应用之间切换时，访问者无法继续在线交谈会话。

最后，对于已通过身份验证的访问者，在弹出窗口中进行在线交谈的功能已取消，因为无法通过弹出窗口验证其身份（因为该体验托管在我们的域名 zopim.com 上）。

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。