文档 API参考

使用聊天SDK启用身份验证用户

聊天SDK v2.8.0 iOS或更高版本和v3.0.0 Android或更高版本支持用户身份验证，以便您可以对聊天用户进行身份验证，以便进行更熟悉和安全的交互。详细信息请参见开发者文档:iOS|安卓．

本文概述了如何通过Swift和Kotlin/Java使用API。主题:

概述

您可以配置您的聊天SDK，在初始化时使用新的setIdentity API和JWT服务对用户进行身份验证。

当你配置Chat SDK来认证用户时，你会得到以下好处:

  • 更高的信心和安全性，您或您的代理正在与之交谈的用户或客户是真实的。
  • 支持跨域通信:如果您将SDK嵌入多个域或链接到外部托管服务(如Shopify)，验证访问者将跨域将访问者的身份持久化到Chat平台，这允许您的代理获得更多上下文。
  • 支持跨设备或浏览器识别:在身份验证调用中指定自定义ID时，如果访问者选择使用不同的设备或浏览器，则可以将其视为同一个人。

与Zendesk聊天W亚博eb小部件不同的是，在SDK中验证你的用户不会让他们看到他们的聊天历史。这是SDK的一个技术限制。

先决条件

在深入研究本文之前，您需要执行几个步骤。完成这些步骤将确保您能够轻松地阅读本文。前提条件很可能由处理用户身份验证的服务器端团队来完成，但这是需要注意的重要信息。

处理已认证用户需要以下步骤:

生成一个聊天共享秘密

要为最终用户身份验证配置SDK，您需要一个共享密钥。共享秘密是一种安全设置，旨在一次性生成、复制并粘贴到与工程团队的通信中，或直接粘贴到代码库中。它不应该被输入到浏览器或应用程序的源代码中。

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

为经过身份验证的访问者生成所需的共享秘密

  1. 打开“聊天”仪表板并转到设置>小部件．
  2. 单击Widget Security选项卡。
  3. 向下滚动到访问者身份验证部分并单击Generate按钮。

注意:共享秘密的目的是保持安全。因此，它只会完整地出现一次。如果您没有访问共享密钥的权限，并且需要完整的密钥来创建令牌，则可以通过单击“再生”按钮重置密钥。

重新生成一个新的共享密钥将撤销先前的令牌。如果您担心共享秘密已被泄露，则应该重新生成一个新的秘密。如果您需要旋转密钥，您应该将其安排在聊天脱机时，因为重新生成密钥可能会导致访问者与SDK断开连接5分钟。

确保您与其他可能处理身份验证的团队(如处理web小部件的团队)沟通对秘密的任何更改。

生成共享密钥之后，就可以使用它来创建JWT令牌了。了解更多关于JWT的信息．这个令牌最终将被传递到Chat SDK的实例中。

创建JWT令牌

JWT令牌需要从服务器端动态生成。服务器端开发人员可能会为您提供检索令牌的端点。您需要准备您的应用程序以达到这个端点。

为JWT令牌构造一个服务器端数据有效负载。这需要有以下信息:

  • 的名字:客户名称
  • 电子邮件:客户邮箱
  • external_id:字母数字字符串，唯一用于识别客户。一旦为客户设置了这个值，就不能更改。我们建议您对此字段使用系统的唯一用户ID。例如，user-123456。最大长度为200个字符
  • iat:当前时间戳的整数值，单位为秒。在特定语言Iat中，用于聊天身份验证的某些函数允许最多两分钟的时钟倾斜。
  • 经验值:(可选)到期时间戳的整数值，单位为秒。此值指示JWT令牌何时到期。该值允许与iat值的最大距离为7分钟。

如果端点没有准备好，并且为了便于测试，您可以通过实现其中之一来设置本地服务代码样本。

如何验证您的用户

一旦您的JWT服务设置为发出有效的JWT令牌，并且您的应用程序准备了该服务的访问点，您就可以在应用程序中启用经过身份验证的Chat用户了。

在Chat实例中设置应用程序对用户进行身份验证是很容易的。您需要遵循两个步骤。完成后，您的用户将在Chat仪表板中进行身份验证。本文后面将介绍这种情况。

启用已认证的聊天用户。

  1. 遵循JWTAuthenticator协议
  2. 调用setIdentity在聊天实例上

符合JWTAuthenticator协议(接口)

JWTAuthenticator协议(接口)包含一个函数(getToken)。
您的身份验证提供程序很可能包含一个从JWT服务发出响应的函数。

在iOS上，getToken函数有一个完成块，该块接受可选String和可选Error类型的元组。

在Android上，getToken方法接受一个回调函数，该函数有两个方法，onTokenLoaded(字符串)而且onError ()

将身份验证提供程序回调的结果传入完成块，Chat SDK将适当地处理完成处理程序的成功和失败。

如果对JWT服务的请求发出错误，Chat SDK将回退到匿名(未经身份验证)用户。

下面是一个符合JWTAuthenticator协议的Swift类的实现。

             

              
最后类JWTAuth：NSObject，JWTAuthenticator｛函数retrieveToken（_完成：@逃离（结果<字符串，错误\>）->无效）｛//请求后端服务返回一个JWT令牌或一个错误｝函数getToken（_完成：@逃离（字符串?，错误?）->无效）｛retrieveToken｛（结果）在完成（结果．元组．0，结果．元组．1）｝｝｝扩展结果｛//帮助转换Swift结果的元组为Objective-C风格的结果var元组：（成功?，失败?）｛开关自我｛情况下．成功（让成功）：返回（成功，零）情况下．失败（让错误）：返回（零，错误）｝｝｝

下面是一个符合JWTAuthenticator接口的Java类的实现:

             

              
类JwtAuth实现了JwtAuthenticator｛私人空间retrieveToken（JwtCallback回调）｛//请求后端服务返回一个JWT令牌或一个错误｝@Override公共空间getToken（final JwtCompletion JwtCompletion）｛retrieveToken（新JwtCallback（）｛@Override公共空间调用onSuccess（字符串标记）｛jwtCompletion．onTokenLoaded（令牌）；｝@Override公共空间onError（）｛jwtCompletion．onError（）；｝｝）；｝接口JwtCallback｛无效调用onSuccess（字符串标记）；无效onError（）；｝｝

在聊天实例上调用setIdentity

一旦有了符合协议(实现接口)的类，并从身份验证服务检索JWT，就可以将它应用到Chat实例了。

您需要在初始化Chat实例后执行此操作。如果您在一个包装器类中包含与zendes亚博k相关的代码，则setIdentity调用可以在init中完成。您需要传入实现JWTAuthenticator协议(接口)的类的实例。

简短的通话片段setIdentity．

             

              
最后类亚博ZendeskChat｛静态让实例＝亚博ZendeskChat（）函数初始化（）｛闲谈，聊天．初始化（accountKey：accountKey，appId：appId）让身份验证＝JWTAuth（）闲谈，聊天．实例？.setIdentity（身份验证：身份验证）｝｝

调用的Java代码段setIdentity**
**

             

              
公共枚举亚博ZendeskChat｛实例；亚博ZendeskChat（）｛闲谈，聊天．实例．初始化（上下文，accountKey）；JwtAuthenticatorjwtAuth＝新JwtAuth（）；闲谈，聊天．实例．setIdentity（jwtAuth）；｝｝

在你打电话之后setIdentity传入JWTAuthenticator协议的有效实现后，您就启用了Chat身份验证，并可以使用了。您所需要做的就是开始聊天，输入消息，然后您应该在代理仪表板中看到您的用户已经过身份验证。

关于代理与经过认证的访客的经验

当代理开始与经过身份验证的用户聊天时，Chat仪表板中会更新一些内容。

首先，代理将能够通过覆盖在用户头像上的绿色已认证复选标记来告诉用户已通过身份验证:

如果Zendesk实例具有代理工作区体验亚博，则应该在用户消息旁边看到一个标记。这允许代理知道用户已通过身份验证

代理还会注意到他们不能编辑访问者的姓名或电子邮件，因为真相的来源是通过JWT发送的信息。

最后，禁止一个经过身份验证的访问者将意味着访问者不能从Web Widget和sdk启动聊天。

关于已认证用户的Chat SDK体验

经过身份验证的用户的体验几乎与匿名用户相同。

由于用户的信息是只读的，所以用户不能使用聊天前表单或ChatAPIConfiguration修改这些信息

因此，预聊天和离线表单不会包含任何关于他们信息的查询(如姓名、电子邮件或电话)。

用户只会被问到他们的初始查询和他们想被导向哪个部门(可通过ChatConfiguration进行配置)。

故障排除

如果在对用户进行身份验证的过程中出现任何错误，Chat SDK将继续进行未经身份验证的会话。如果您在设置身份验证时遇到问题，您可以尝试以下几件事来确保正确地遵循步骤。

  1. 验证您的令牌与您的秘密jwt.io
  2. 监听身份验证错误通知(仅iOS)

身份验证错误通知(仅iOS)

如果您已经验证了正在检索的令牌，但仍然没有看到经过身份验证的用户，那么您可以在应用程序中侦听身份验证错误，并适当地处理这些错误。中的错误案例列表开发文档。

在Android上，我们目前不支持这种风格的通知，但如果发生任何错误，我们将记录错误。要查看SDK日志，需要通过调用开启日志功能Logger.setLoggable(真正的)．

下面的Swift代码片段监听AuthenticationErrors。

             

              
私人函数observeAuthNotification（）｛NotificationCenter．默认的．addObserver（自我，选择器：#选择器（authenticationHasFailed（＿：）），的名字：闲谈，聊天．NotificationAuthenticationFailed，对象：零）｝@objc函数authenticationHasFailed（_通知：通知）｛警卫让错误＝通知．用户信息?［NSUnderlyingErrorKey］作为?AuthenticationError其他的｛返回｝开关错误｛情况下．invalidAccessToken（让令牌）：//指定的JWT令牌无效@未知的默认的：打破｝｝

如何取消用户身份验证

您可能希望在某些时候取消用户的身份验证，无论他们是删除帐户还是只是注销。你可以通过resetIdentity函数。该函数接受一个可选的完成处理程序来执行标识完全重置后可能需要执行的任何操作。

下面的Swift代码片段调用resetIdentity．

             

              
扩展亚博ZendeskWrapper｛函数resetIdentity（）｛闲谈，聊天．实例？.resetIdentity｛//标识已清除，继续注销｝｝｝

调用的Java代码段resetIdentity．

             

              
公共枚举亚博ZendeskChat｛实例；无效resetIdentity（）｛闲谈，聊天．实例．resetIdentity（新CompletionCallback<无效>（）｛//标识已清除，继续登录｝）；｝｝

现在，您的代理可以通过您的应用程序与您的客户进行安全而熟悉的对话。

如果您在设置已验证的流时仍然遇到困难，请参阅使用本地JWT服务准备的示例应用程序(已提到)以上)：iOS样本| Android样本(TBA)。