REST Resource: projects.locations.dataStores.userEvents

资源：UserEvent

UserEvent 会捕获 Discovery Engine API 需要了解的有关最终用户如何与您的网站互动的所有元数据信息。

JSON 表示法 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ]
}
字段
eventType

string

必需。用户事件类型。允许的值为：

通用值：

  • search：搜索文档。
  • view-item：文档的详细页面视图。
  • view-item-list：面板或有序文档列表的视图。
  • view-home-page：首页视图。
  • view-category-page：类别页面的视图，例如“首页 > 男装 > 牛仔裤”

与零售相关的值：

  • add-to-cart：将商品添加到购物车，例如在零售在线购物中
  • purchase：购买商品

媒体相关值：

  • media-play：开始/继续观看视频、播放歌曲等。
  • media-complete：已完成或在播放视频、歌曲等内容的过程中停止。

自定义转化价值：

  • conversion：客户定义的转化事件。
conversionType

string

可选。转化类型。

如果 UserEvent.event_type 为 conversion，则必须提供此值。这是客户定义的转化名称，采用小写字母或数字，以“-”分隔，例如“watch”“good-visit”等。

如果 UserEvent.event_type 不是 conversion，请勿设置该字段。这会将自定义转化事件与 search、view-item 等预定义事件混合在一起。
userPseudoId

string

必需。用于跟踪访问者的唯一标识符。

例如，可以使用 HTTP Cookie 实现此目的，该 Cookie 应能够唯一标识单个设备上的访问者。如果访问者登录/退出网站，此唯一标识符不应发生变化。

请勿为不同用户将该字段设置为相同的固定 ID。这会将这些用户的事件历史记录混杂在一起，从而导致模型质量下降。

该字段必须是 UTF-8 编码的字符串，长度限制为 128 个字符。否则，系统将返回 INVALID_ARGUMENT 错误。

该字段不应包含 PII 或用户数据。建议您为此字段使用 Google Analytics 客户端 ID。
engine

string

Engine 资源名称，格式为 projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}。

可选。仅对于 Engine 生成的用户事件是必需的。例如，混合搜索中的用户事件。
dataStore

string

DataStore 资源的完整名称，格式为 projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}。

可选。仅当无法通过 UserEvent.engine 或 UserEvent.documents 确定用户事件的数据存储区时才需要。如果在写入/导入/收集用户事件请求的父级中设置了数据存储区，则可以省略此字段。
eventTime

string (Timestamp format)

仅 UserEventService.ImportUserEvents 方法需要此参数。用户事件发生时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
userInfo

object (UserInfo)

有关最终用户的信息。
directUserRequest

boolean

如果请求直接由最终用户发出，则应设置为 true，在这种情况下，可以从 HTTP 请求中填充 UserEvent.user_info.user_agent。

只有在 API 请求直接由最终用户（例如移动应用）发出时，才应设置此标志；如果网关或服务器正在处理和推送用户事件，则不应设置此标志。

在 UserEventService.CollectUserEvent 中使用 JavaScript 代码时，不应设置此属性。
sessionId

string

用于跟踪访问者会话的唯一标识符，长度限制为 128 字节。会话是指最终用户在一段时间内的行为汇总。

填充 sessionId 的一般准则：

  1. 如果用户在 30 分钟内没有任何活动，则应分配新的 sessionId。
  2. sessionId 在用户之间应该是唯一的，建议使用 uuid 或添加 UserEvent.user_pseudo_id 作为前缀。
pageInfo

object (PageInfo)

网页元数据，例如类别以及某些事件类型（例如 view-category-page）的其他关键信息。
attributionToken

string

用于将 API 响应归因于触发事件的用户操作的令牌。

强烈建议将此值用于因 RecommendationService.Recommend 而产生的用户事件。此字段可实现对推荐模型效果的准确归因。

该值必须是以下项之一：

借助此令牌，我们可以准确地将网页浏览或转化完成归因于相应事件以及包含此点击/购买产品的特定预测响应。如果用户点击建议结果中的商品 K，则将 RecommendResponse.attribution_token 作为网址参数传递给商品 K 的页面。在记录商品 K 的页面上的事件时，请将 RecommendResponse.attribution_token 记录到此字段。
filter

string

过滤器语法使用一种表达式语言，可根据要过滤文档的一个或多个字段构建过滤条件。

例如，对于 search 事件，关联的 SearchRequest 可能包含 SearchRequest.filter 中的过滤表达式，该表达式符合 https://google.aip.dev/160#filtering。

同样，对于从 RecommendRequest 生成的 view-item-list 事件，此字段可以直接从 RecommendRequest.filter 填充，并遵循 https://google.aip.dev/160#filtering。

该值必须是采用 UTF-8 编码的字符串，长度上限为 1,000 个字符。否则，系统将返回 INVALID_ARGUMENT 错误。
documents[]

object (DocumentInfo)

与此用户事件相关联的 Document 的列表。

此字段为选填字段，但以下事件类型除外：

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

在 search 事件中，此字段表示当前网页上返回给最终用户的文档（最终用户可能尚未完成整个网页的浏览）。当最终用户在分页/过滤/排序后（即使是针对同一查询）获得新网页时，我们希望获得具有不同 UserEvent.documents 的新 search 事件。
panel

object (PanelInfo)

与相应用户事件相关联的面板元数据。
searchInfo

object (SearchInfo)

与活动相关的SearchService.Search详细信息。

应为 search 事件设置此字段。
completionInfo

object (CompletionInfo)

与活动相关的CompletionService.CompleteQuery详细信息。

如果启用了自动补全功能，并且用户点击了搜索建议，则应为 search 事件设置此字段。
transactionInfo

object (TransactionInfo)

与相应用户事件关联的交易元数据（如有）。
tagIds[]

string

相应用户事件所属的独立实验组的标识符列表。用于区分与不同实验设置关联的用户事件。
promotionIds[]

string

如果相应事件与促销活动相关联，则为促销活动 ID。目前，此字段最多只能包含一个 ID。
attributes

map (key: string, value: object)

要纳入推荐模型中的额外用户事件特征。这些属性不得包含需要进一步解析或处理的数据，例如 JSON 或其他编码。

如果您为注入的用户事件提供自定义特性，则务必也在与预测请求关联的用户事件中添加这些特性。自定义特性的格式设置必须在导入事件和随预测请求提供的事件之间保持一致。这样，Discovery Engine API 便可在训练模型和提供预测时使用这些自定义特性，从而帮助提高推荐质量。

此字段需要满足以下所有条件，否则系统会返回 INVALID_ARGUMENT 错误：

  • 键必须是 UTF-8 编码的字符串，长度限制为 5,000 个字符。
  • 对于文本属性，最多允许 400 个值。不允许使用空值。每个值都必须是 UTF-8 编码的字符串，长度限制为 256 个字符。
  • 对于数字属性，最多允许 400 个值。

对于商品推荐，额外的用户信息的一个示例是 traffic_channel，即用户到达网站的方式。用户可以直接访问网站，也可以通过 Google 搜索或其他方式访问网站。
attributes.text[]

string

相应自定义属性的文本值。例如，当键为“color”时，值为 ["yellow", "green"]。

不允许使用空字符串。否则，系统将返回 INVALID_ARGUMENT 错误。

应仅设置 CustomAttribute.text 和 CustomAttribute.numbers 中的一项。否则，系统将返回 INVALID_ARGUMENT 错误。
attributes.numbers[]

number

相应自定义属性的数值。例如，当键为“lengths_cm”时，值为 [2.3, 15.4]。

应仅设置 CustomAttribute.text 和 CustomAttribute.numbers 中的一项。否则，系统将返回 INVALID_ARGUMENT 错误。
mediaInfo

object (MediaInfo)

媒体专属信息。
panels[]

object (PanelInfo)

可选。与相应活动相关联的面板的列表。用于网页级展示数据。

UserInfo

最终用户的信息。

JSON 表示法 
{
  "userId": string,
  "userAgent": string,
  "timeZone": string
}
字段
userId

string

强烈建议已登录的用户使用。已登录用户的唯一标识符，例如用户名。不为匿名用户设置。

始终为此 ID 使用哈希值。

请勿为不同用户将该字段设置为相同的固定 ID。这会将这些用户的事件历史记录混杂在一起，从而导致模型质量下降。

该字段必须是 UTF-8 编码的字符串，长度限制为 128 个字符。否则，系统将返回 INVALID_ARGUMENT 错误。
userAgent

string

HTTP 标头中包含的用户代理。

该字段必须是 UTF-8 编码的字符串，长度上限为 1,000 个字符。否则，系统将返回 INVALID_ARGUMENT 错误。

如果使用 GTM 或 JavaScript 代码在 UserEventService.CollectUserEvent 中进行客户端事件报告，或者设置了 UserEvent.direct_user_request，则不应设置此属性。
timeZone

string

可选。IANA 时区，例如 Europe/Budapest。

PageInfo

详细的网页信息。

JSON 表示法 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
字段
pageviewId

string

网页浏览的唯一 ID。

对于从同一网页浏览触发的所有用户事件，此值应保持不变。例如，当用户浏览商品详情页面时，可能会触发多个事件。所有这些事件的 pageviewId 属性应保持一致，以便将它们正确地归为一组。

如果使用 JavaScript Pixel 和 Google 跟踪代码管理器进行客户端事件报告，系统会自动填充此值。
pageCategory

string

与类别页面关联的最具体类别。

如需表示类别的完整路径，请使用“>”符号分隔不同的层次结构。如果“>”是类别名称的一部分，请将其替换为其他字符。

类别页面包括销售页面或促销页面等特殊页面。例如，特惠促销页面的类别层次结构可能为："pageCategory" : "Sales > 2017 Black Friday Deals"。

对于 view-category-page 事件为必需参数。其他事件类型不应设置此字段。否则，系统将返回 INVALID_ARGUMENT 错误。
uri

string

用户当前网页的完整网址 (window.location.href)。

如果使用 JavaScript Pixel 和 Google 跟踪代码管理器进行客户端事件报告，系统会自动填充此值。长度上限为 5,000 个字符。
referrerUri

string

当前网页的引荐来源网址。

如果使用 JavaScript Pixel 和 Google 跟踪代码管理器进行客户端事件报告，系统会自动填充此值。不过，某些浏览器隐私权限制可能会导致此字段为空。

DocumentInfo

与用户事件关联的详细文档信息。

JSON 表示法 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
字段
promotionIds[]

string

与相应文档关联的促销活动 ID。目前，此字段最多只能包含一个 ID。
joined

boolean

仅限输出。所引用的文档是否可在数据存储区中找到。

联合字段 document_descriptor。关联的 Document 的必需描述符。

  • 如果指定了 id，则在通过存储的 Document 进行注释时，将使用 {location}、{collection_id}、{data_store_id} 和 {branch_id} 的默认值。

  • 如果指定了 name，则在对存储的 Document 进行注释时，将使用为 {location}、{collection_id}、{data_store_id} 和 {branch_id} 提供的（允许使用默认）值。document_descriptor 只能是下列其中一项：
id

string

Document 资源 ID。
name

string

Document 资源的完整名称，格式为：projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

Document URI - 仅允许用于网站数据存储区。
quantity

integer

与用户事件关联的文档数量。默认为 1。

例如，如果 add-to-cart 事件涉及同一文档的两个数量，则此字段为 2。

对于以下事件类型的事件，此参数为必需参数：

  • add-to-cart
  • purchase
conversionValue

number

可选。与相应文档关联的转化价值。如果 UserEvent.event_type 为“conversion”，则必须设置此参数。

例如，值 1000 表示用户在查看文档上花费了 1000 秒，而这属于 watch 转化类型。

PanelInfo

与用户事件关联的详细面板信息。

JSON 表示法 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
字段
panelId

string

必需。面板 ID。
displayName

string

面板的显示名称。
documents[]

object (DocumentInfo)

可选。与相应面板关联的文档 ID。
panelPosition

integer

面板的有序位置（如果与其他面板一起向用户显示）。如果设置了此字段，则还必须设置 totalPanels。
totalPanels

integer

向用户展示的面板总数（包括当前面板）。如果设置了 panelPosition，则必须设置此参数。

SearchInfo

详细的搜索信息。

JSON 表示法 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
字段
searchQuery

string

用户的搜索查询。

如需查看定义，请参阅 SearchRequest.query。

该值必须是采用 UTF-8 编码的字符串，长度上限为 5,000 个字符。否则，系统将返回 INVALID_ARGUMENT 错误。

对于 search 事件，至少需要 searchQuery 和 PageInfo.page_category 其中之一。其他事件类型不应设置此字段。否则，系统将返回 INVALID_ARGUMENT 错误。
orderBy

string

返回商品的顺序（如果适用）。

如需了解定义和语法，请参阅 SearchRequest.order_by。

该值必须是采用 UTF-8 编码的字符串，长度上限为 1,000 个字符。否则，系统将返回 INVALID_ARGUMENT 错误。

只能为 search 事件设置此字段。其他事件类型不应设置此字段。否则，系统将返回 INVALID_ARGUMENT 错误。
offset

integer

一个整数，用于指定分页的当前偏移量（API 视为相关的商品的从 0 开始的起始位置）。

如需查看定义，请参阅 SearchRequest.offset。

如果此字段为负数，则返回 INVALID_ARGUMENT。

只能为 search 事件设置此字段。其他事件类型不应设置此字段。否则，系统将返回 INVALID_ARGUMENT 错误。

CompletionInfo

详细的完成信息，包括完成情况归因令牌和点击完成信息。

JSON 表示法 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
字段
selectedSuggestion

string

已选择最终用户 CompleteQueryResponse.QuerySuggestion.suggestion。
selectedPosition

integer

最终用户选择的 CompleteQueryResponse.QuerySuggestion.suggestion 位置，从 0 开始。

TransactionInfo

交易是指整个购买交易。

JSON 表示法 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
字段
currency

string

必需。币种代码。请使用三个字符的 ISO-4217 代码。
transactionId

string

交易 ID，长度限制为 128 个字符。
value

number

必需。与交易相关的非零总价值。此值可能包含运费、税费或其他要计入总价值的调整值。
tax

number

与交易相关的所有税费。
cost

number

与商品相关的所有费用。这些费用可以是制造成本、最终用户无需承担的运费或任何其他费用，因此：
discountValue

number

应用于相应交易的折扣总价值。此数字应从 TransactionInfo.value 中排除

例如，如果用户支付了 TransactionInfo.value 金额，则交易的名义（折扣前）价值为 TransactionInfo.value 和 TransactionInfo.discount_value 的总和

这意味着，无论折扣值是多少，利润的计算方式都相同，并且 TransactionInfo.discount_value 可以大于 TransactionInfo.value：

MediaInfo

媒体特有的用户事件信息。

JSON 表示法 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
字段
mediaProgressDuration

string (Duration format)

媒体进度时间（以秒为单位，如果适用）。例如，如果最终用户已播放 90 秒的视频，则 MediaInfo.media_progress_duration.seconds 应设置为 90。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
mediaProgressPercentage

number

媒体进度应仅使用相对于媒体总长度的 mediaProgressDuration 来计算。

此值必须介于 [0, 1.0] 之间（含）。

如果这不是播放，或者无法计算进度（例如，正在进行的直播），则应取消设置此字段。

方法

collect

 从浏览器写入单个用户事件。

import

 批量导入用户事件。

purge

 永久删除指定过滤条件所指定的所有用户事件。

write

 写入单个用户事件。