本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用网络数据跟踪器捕获网站访客活动
<a name="chat-widget-data-tracker"></a>

网络数据跟踪器可捕获访问者如何与您的网站进行交互——点击的项目、进行的搜索、表单的提交。它将该活动与其在 “客户资料” 中的个人资料相关联。跟踪器是 “通信” 控件的一部分，在小组件级别进行控制。有关网络数据跟踪器和网络通知如何协同工作的概述，请参阅[网络数据跟踪器和网络通知](customer-profiles-web-tracker-and-notification.md)。

## 先决条件
<a name="chat-widget-data-tracker-prereqs"></a>
+ 配置了通信小组件的 Connect Customer 实例。有关更多信息，请参阅 [向由 Connect 客户托管的网站添加聊天用户界面](add-chat-to-website.md)。
+ 在实例上启用了客户档案。有关更多信息，请参阅 [为您的 Connect 客户实例启用客户档案](enable-customer-profiles.md)。

## 步骤 1：在 “通信” 微件上启用数据收集
<a name="chat-widget-enable-data-collection"></a>

1. 登录到 Connect Customer 管理员网站。

1. 在导航菜单中，选择 “**频道**”，然后选择 “**通信” 微件**。

1. 创建新控件或编辑现有控件。有关更多信息，请参阅 [向由 Connect 客户托管的网站添加聊天用户界面](add-chat-to-website.md)。

1. 启用**数据收集**以开启点击流跟踪。

1. （可选）**数据收集**设置包括 “**高级数据收集**” 选项。开启此功能后，该服务就会自动收集访客与 HTML 内容的互动，从而生成更丰富、更准确的预测见解。

1. （可选）如果您计划通过此小组件发送主动通知，请启用 **Web** 通知。有关更多信息，请参阅 [通过 Connect 客户出站广告系列发送网络通知](outbound-campaigns-web-notification.md)。

1. 将要嵌入微件的网站域名添加到允许的域名列表中。

1. 保存控件并复制控件代码片段代码。下一步将此片段嵌入到您的网站上。

## 第 2 步：嵌入控件并初始化跟踪
<a name="chat-widget-embed-and-init-tracking"></a>

将控件片段嵌入到您网站的 HTML 中。片段加载后，在获得访客同意后初始化跟踪器。

```
// Start tracking visitor behavior (after obtaining consent)
await window.amazon_connect.Web.ClickStream.init();

// (Optional) Enable web notifications for this visitor
await window.amazon_connect.Web.Notification.init();
```

**重要**  
只有在根据您的隐私政策和适用法规获得相应的访客同意后，才能初始化跟踪。

**注意**  
对于单页应用程序，只需在顶级页面中嵌入代码片段一次。对于多页应用程序，请将代码片段嵌入到要捕获活动的每个页面上。

## 第 3 步：（可选）跟踪特定于业务的事件
<a name="chat-widget-track-business-events"></a>

要捕获自定义业务事件（例如购买完成、添加到购物车操作或产品视图），请在事件发生 JavaScript 时`recordBusinessMetric`从您的网站致电。

**重要**  
如果您计划将数据跟踪器与需要项目上下文（如`Find Similar Items`和）的推荐人一起使用`Frequently Paired Items`，则必须使用特定于业务的事件并包含该`item_id`字段。

### 方法签名
<a name="chat-widget-track-business-events-method"></a>

```
await amazon_connect.Web.ClickStream.recordBusinessMetric(eventType, eventPayload)
```


| **参数** | **Type** | **描述** | 
| --- | --- | --- | 
| `eventType` | 字符串 | 业务事件名称-保留类型或任何自定义字符串。 | 
| `eventPayload` | object | 使用以下对象架构构造的事件数据。 | 

### 对象架构
<a name="chat-widget-track-business-events-schemas"></a>

`eventPayload`支持以下对象。使用任意字段组合以适应您的用例。


| **Object** | **关键字段** | **描述** | 
| --- | --- | --- | 
| **项目** | `item_id`\*, `item_name`\*, `quantity`\*, `category`, `price`, `currency`, `impression_type`, `impression_id` | 单一产品或一件商品 | 
| **物品清单** | 名单 <item> | 物品对象数组（最少 1 个） | 
| **手推车** | `cart_id`\*, `item_list`\*, `total_value`, `currency` | 购物车 | 
| **订购** | `order_id`\*, `item_list`\*, `total_value`, `currency`, `payment_method`, `shipping_address`, `discount` | 已完成的订单 | 
| **search** | `search_query`\*, `total_matching_results`, `results_per_page`, `filter_expression`, `sort_criteria` | 搜索动作 | 
| **表单** | `form_id`\*, `form_name`, `form_length`, `validation_errors`, `fields_completed` | 表单互动 | 
| **滚动** | `depth_percentage`, `position_x`, `position_y` | 滚动位置（至少需要一个字段） | 
| **事件值** | 数字 | 代表事件重要性的数值 | 

\* 必填字段

### 集成步骤和用法示例
<a name="chat-widget-track-business-events-examples"></a>

调用后`amazon_connect.Web.ClickStream.init()`，在网站的事件处理程序中添加`recordBusinessMetric()`调用（例如 onclick）。

**示例-加入购物车**

```
await amazon_connect.Web.ClickStream.recordBusinessMetric('add_to_cart', {
    item: {
        item_id: 'prod-123',
        item_name: 'Wireless Headphones',
        price: 49.99,
        quantity: 1,
        currency: 'USD'
    }
});
```

**示例-查看商品**

```
await amazon_connect.Web.ClickStream.recordBusinessMetric('view_items', {
    item_list: [
        {
            item_id: 'item_10',
            quantity: 1,
            item_name: 'Premium Wireless Headphones',
            category: 'Electronics',
            price: 89.99,
            currency: 'USD'
        }
    ]
});
```

### 预留事件类型
<a name="chat-widget-track-business-events-reserved"></a>

以下事件类型使用预定义架构保留：


| **事件类型** | **必填对象** | **描述** | 
| --- | --- | --- | 
| `add_to_cart` | item | 追踪访客何时将商品添加到购物车 | 
| `purchase` | 顺序 | 追踪已完成的购买 | 
| `view_items` | 物品清单 | 跟踪访客何时查看一个或多个项目 | 

### 自定义事件
<a name="chat-widget-track-business-events-custom"></a>

除了保留的事件类型之外，您还可以定义任何自定义事件类型字符串（例如，`clear_cart`或`wishlist_add`）。对于自定义事件：
+ 该服务不对事件结构进行严格验证。
+ 您可以使用上述对象架构中的任意字段组合来适应您的用例。
+ 请完全按照所示使用字段名称（例如`cart_id`，不是`cartId`）。

```
await amazon_connect.Web.ClickStream.recordBusinessMetric('clear_cart', {
    cart_id: 'cart-123',
    item_list: [
        { item_id: 'p1', item_name: 'Widget', quantity: 1 }
    ]
});
```

## 将点击流与经过身份验证的用户相关联
<a name="chat-widget-data-tracker-authenticated-users"></a>

网络数据跟踪器捕获的点击流数据会持续流式传输到客户资料中，并与访客的个人资料相关联。下表描述了该关联对匿名和经过身份验证的访客的行为方式。


| **访客类型** | **个人资料关联行为** | 
| --- | --- | 
| 匿名访客 | 仅按会话标识符进行跟踪。行为数据会被捕获，但不与已知的客户身份相关联。不会收集任何个人身份信息。 | 
| 经过认证的访客 | 当您在小组件初始化期间传递经过身份验证的用户 ID 时，该服务会将所有点击流活动关联到客户资料中该用户的已知个人资料。这可以实现更丰富的个性化和更准确的触发条件。 | 

要将跟踪与经过身份验证的用户相关联，请使用以下方法之一：
+ **（推荐）使用 CustomerId JWT 声明 — 如果您在 “**通信” 小组件上启用了安全保护，请在 JSON Web Token (JWT) 声明`CustomerId`字段中包含经过身份验证的用户 ID。这会将点击流活动链接到用户的个人资料，而不会在客户端代码中暴露ID。有关设置的详细信息，请参阅[第 3 步：确认并复制通信小部件代码和安全密钥](add-chat-to-website.md#confirm-and-copy-chat-widget-script)。
+ **在初始化期间传递用户 ID** — 如果您的小组件未启用安全保护，请在初始化跟踪器时将经过身份验证的用户 ID 作为参数传递：

  ```
  await window.amazon_connect.Web.ClickStream.init('<authenticated-user-id>');
  ```

**重要**  
如果传递了经过身份验证的用户 ID，则它会通过账号密钥链接到现有的个人资料。由于数据跟踪器事件会随着时间的推移而累积，因此请为`WebAnalytics-Clickstream`和设置对象限制，`_webAnalytics`以防止新事件在达到配置文件对象限制后覆盖其他对象类型。有关配置指导，请参阅[客户资料数据限制](https://docs.aws.amazon.com/connect/latest/adminguide/customer-profiles-data-limits.html)。

## 捕获了什么
<a name="chat-widget-data-tracker-what-is-captured"></a>

有关跟踪器默认捕获的活动的完整列表，请参阅[网络数据跟踪器捕获的内容](customer-profiles-web-tracker-and-notification.md#web-tracker-what-is-captured)。

## 隐私和同意
<a name="chat-widget-data-tracker-privacy"></a>

网络数据跟踪器在设计上是可选的。如果您未在 “通信” 小组件上启用**数据收集**，则不会捕获任何点击流数据。即使跟踪了表单提交事件，也不会自动收集表单字段值、密码和付款信息。

**重要**  
根据您的隐私政策和《通用数据保护条例》(GDPR) 和《加州消费者隐私法》(CCPA) 等适用法规，在初始化数据跟踪之前，您有责任获得适当的访客同意。