Client-Mastered

对话API允许您以编程方式检索和提交Bazaarvoice对话数据以在应用程序中使用。要了解更多信息，请参阅对话API文档主页．

本页解释了开发人员如何通过提交用户ID和消费者生成的内容来验证Bazaarvoice的作者身份。

概述

在这种身份验证类型中，用户id来自您的身份验证系统，该系统被认为是用户身份验证的权威(主)源。这也被称为“客户端站点身份验证”，因为它依赖于您的站点身份验证系统。

组件

下表总结了实现由客户端掌握的身份验证需要了解的组件。这些组件将在本文档的其余部分中引用。熟悉它们将使您更容易理解客户端掌握的身份验证。

身份验证场景

在使用客户端托管身份验证时，有两种身份验证场景:1)在提交之前没有创建编码的UAS或2)在提交之前已经创建了编码的UAS。您的实现应该支持这两种场景。

未预先创建已编码的UAS令牌

在这种情况下，当作者试图访问您的提交表单时，您将无法访问预先创建的编码UAS令牌。相反，您将基于以下条件之一创建一个编码的UAS令牌:

• 如果作者已经登录到您的网站，您应该创建编码的UAS令牌，加载提交表单并将其内容提交到Bazaarvoice。
• 如果作者没有登录到你的网站，你应该重定向他们通过你的登录过程，然后回到你的提交表单来完成他们的提交。

预先创建的已编码的UAS令牌

在此场景中，使用预先创建的编码UAS令牌的用户尝试访问您的提交表单。当发生这种情况时，您不应该将用户重定向到您的站点登录或创建新的编码UAS令牌，原因如下:

• 预先创建的编码UAS令牌可能包含标准令牌不包含的其他参数(请参阅数据注入下图)
• 强迫作者不必要地登录将导致提交量减少40%

这个场景的一个例子是Bazaarvoice所说的购买后电子邮件(PPE)。PPE向经过验证的购买者(已知购买过产品的用户)征求评论，并包含一个链接，其中包含一个编码的UAS令牌，直接指向您的提交表单。经过验证的购买者的身份已经已知，因此可以预先创建编码的UAS令牌，并包括表明用户是产品所有者的其他数据。因为已经创建了编码的UAS令牌，所以不需要在用户中登录。

身份验证场景逻辑

前面的场景由以下伪代码表示，这是决定何时允许用户访问您的提交表单的推荐逻辑:

if (Pre_Created_Encoded_UAS_Token){呈现提交表单}elseif (user_is_logged_in){创建编码的UAS令牌呈现提交表单}否则{重定向到登录页面，用户登录后发送回提交表单重复此逻辑}

继续购买后的电子邮件示例，考虑在发送给消费者的电子邮件中嵌入以下URL。消费者的身份已经知道，因为他们最近购买了，所以可以提前创建编码的UAS令牌:

https://yourdomain.com/path/to/your/submissionform.html?usertoken=c34c38c8c308852a49e7607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653d323030372d30352d3237267573657269643d49443132333435

不需要通过身份验证过程路由该用户。此请求已经包含预先创建的编码UAS令牌。相反，您应该立即呈现表单，收集他们的输入，并将其与编码的UAS令牌一起提交给Bazaarvoice。

创建并编码UAS

当已编码的UAS令牌不存在时，您将需要创建用户身份验证字符串并对其进行编码。

用户认证字符串由“&”分隔的“键=值”对组成。在提交之前，使用共享密钥对UAS进行签名和编码。结果被称为一个编码的UAS令牌。这个过程允许Bazaarvoice验证提交的内容来自可信来源，从而防止不良行为者编造内容或冒充用户。

对UAS进行签名和编码是消息身份验证的一种方法，而不是隐私。如下面的伪代码所示，用户ID将以一种带有共享密钥签名的编码格式进行通信，这是相当安全的，但也可以作为纯文本十六进制字符串进行通信，这是有意可逆的。如果需要隐私保护，提交应使用HTTPS。

为了验证已编码的UAS令牌的来源，Bazaarvoice将反转已hexhex的部分，然后使用我们的共享密钥副本对UAS进行编码，并将结果与您创建的字符串的已编码部分进行比较。如果它们匹配，那么我们可以确信提交的内容来自可信的来源。

如何创建一个基本的无人机系统

以下参数应用于所有用户身份验证字符串。看到数据注入其他可用参数:

下面的代码示例显示了UAS所需的参数:

日期= 2015 - 10 - 23 -用户id = ID12345

上述字符串将在创建当天(2015-10-23)和第二天(2015-10-24)有效，此后Bazaarvoice将不再接受该字符串。使用maxage参数来延长UAS的寿命:

日期= 2015 - 10 - 23 -用户id = ID12345&maxage = 30

此字符串将在2015-10-23之后的30天内有效。

看到数据注入以下是更多信息

UAS编码

要对UAS进行编码，您将使用共享密钥执行以下步骤:

1. URL转义这些值，以确保它们不会与其他具有特殊含义的字符冲突
2. 生成共享密钥和用户身份验证字符串的十六进制编码HMAC-SHA256散列(结果应该是64个字符长)
3. 十六进制编码用户身份验证字符串
4. 将步骤3的结果附加到步骤2的末尾

如果您不知道您的共享密钥，请联系Bazaarvoice的支持．

伪代码示例

userStr =" date=" + urlescape(YYYYMMDD) + "&userid=" + urlescape(123456) sharedKey =" SHARED_SECRET_KEY" encUserStr = hmac('sha256'， sharedKey, userStr) + hex(userStr)

结果如下所示:

c34c38c8c308852a49e7607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653 d323030372d30352d3237267573657269643d49443132333435

在上面的例子中，SHA-256散列部分(前64个字符)被突出显示

数据注入

数据注入指的是在用户身份验证字符串中向Bazaarvoice提交数据，而不是使用标准提交表单字段。

当您托管提交表单并通过对话API提交时，通常不需要数据注入。这项技术主要对使用我们的客户有用 基于JavaScript的集成．在这个集成中，Bazaarvoice控制表单，但是通过使用数据注入，我们的客户端可以代表用户提交数据。

但是，作为构建API应用程序的开发人员，在某些情况下可能需要使用数据注入。例如，您正在构建的API应用程序可能与基于JavaScript的集成共享Bazaarvoice客户端配置。在这种情况下，您的API应用程序将需要使用数据注入，因为Bazaarvoice客户端实例就是这样配置的。

下面是UAS中可能注入的参数和值的列表。

标准参数

这些参数对所有客户端都可用，如下所示，尽管在使用之前必须启用它们。

自定义参数

以下字段类型也可以被注入。这些字段必须为您的客户端实例配置，确切的参数键和值可能会有所不同。

• 标签
• 附加字段
• 背景数据问题

UAS中用于这些字段的参数是完全可定制的。下面的示例演示了注入这些字段的效果。实际的参数键和值取决于您的客户机配置。

向Bazaarvoice投稿

方法提交已编码的UAS令牌用户参数:

属性的提交示例如下用户参数:

POST /数据/ submitreview。json HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress]…ApiVersion = [latestApiVersion] &ProductId = [productId]行动= submit&Rating =(评级)&ReviewText = [reviewText]标题=[标题]&UserNickname =(昵称)万能钥匙= [yourKey] fp = [deviceFingerprint] &用户= c34c38c8c308852a49e7607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653d323030372d30352d3237267573657269643d49443132333435

附录

故障排除ERROR_PARAM_MISSING_USER_ID

错误代码ERROR_PARAM_MISSING_USER_ID意味着对话API无法识别有效的用户ID。造成这种错误的常见原因有:

缺少user或userid参数

请确保用户或用户标识参数包含在请求中，并且请求在语法上是正确的。例如，下面的请求似乎包括用户，但它不会被解析为预期的，因为URL是畸形的(前面没有&号用户)．

POST /数据/ submitreview。json HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress]…ApiVersion = [latestApiVersion] &ProductId = [productId]行动= submit&Rating =(评级)&ReviewText = [reviewText]标题=[标题]&UserNickname =(昵称)万能钥匙= [yourKey] fp = [deviceFingerprint]用户= c34c38c8c308852a49e7607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653d323030372d30352d3237267573657269643d49443132333435

上面例子中的省略号(…)表示你的应用程序可能会生成其他头文件。

共享密钥不正确

在创建已编码的UAS令牌时，请确保您使用的是正确且完整的共享密钥。您可以联系我们的支持团队，以验证您使用的值是否正确。

UAS已过期

正确制作的编码UAS令牌的一个常见问题是它已经过期。默认情况下，令牌在创建的当天和第二天都有效(相当于maxage = 1)．为了延长他们的寿命，你可以使用maxage参数。指如何创建一个基本的无人机系统以上是更多细节。

有一些必须注入的字段

如果您基于conversation API的应用程序正在使用我们基于JavaScript的解决方案与集成共享配置，则可能需要执行数据注入。我们的支持团队可以帮助您验证您的配置。如果是这种情况，重要的是不要改变配置，因为这样做的话，基于JavaScript的集成将停止正常工作。

使用userid提交

提交用户ID而不用在UAS令牌中进行编码是可能的。这是通过使用用户标识参数以纯文本形式提交用户ID，而不是使用编码的UAS令牌。您可能会发现这个方法在使用sessions API时很有用，但事实确实如此不推荐，因为Bazaarvoice无法验证提交的内容来自可信来源。

下面是一个使用userid参数提交的例子:

POST /数据/ submitreview。json HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress]…ApiVersion = [latestApiVersion] &ProductId = [productId]行动= submit&Rating =(评级)&ReviewText = [reviewText]标题=[标题]&UserNickname =(昵称)万能钥匙= [yourKey] fp = [deviceFingerprint] &用户id = 1234567890