Attribution-Reporting-Register-Source

<json-string>

一个 JSON 字符串，提供浏览器在与归因来源交互时应存储的信息。可用的字段如下

"source_event_id" 可选

表示归因来源 ID 的字符串，可在与归因来源交互时将其映射到其他信息，或在报告端点聚合信息。该字符串必须仅由以基数 10 格式表示的 64 位无符号整数组成。

"destination"

单个字符串或 1-3 个字符串的数组。这些字符串必须包含与预期发生触发器的网站（方案 + eTLD+1）相对应的完整 URL。当与触发器交互时，这些用于将归因触发器与来源匹配。

"aggregation_keys" 可选

包含用户提供的键的对象，这些键表示要汇总报告值的不同数据点。

"aggregatable_report_window" 可选

表示时间的字符串（以秒为单位），在此时间之后，触发器数据将不再包含在生成的聚合报告中（这称为**报告窗口**）。如果未设置，则默认为"expiry"值。

"debug_key" 可选

表示调试密钥的以基数 10 格式表示的 64 位无符号整数。如果您想与关联的归因报告一起生成调试报告，请设置此值。

"debug_reporting" 可选

布尔值。如果设置了debug_key，则将其设置为true以指定生成的调试报告应为详细调试报告。

"event_level_epsilon" 可选

等于或大于0的数字，它控制添加到报告中的噪声量。epsilon 值越低，噪声越大，因此提供的隐私保护越好。最大值和默认值因实现而异；例如，Chrome 的最大值和默认值为14。

"event_report_window" 可选

表示时间的字符串（以秒为单位），在此时间之后，后续触发器将无法归因于此来源以生成事件级报告（这称为**报告窗口**）。如果未设置，则事件报告窗口将回退到"expiry"值。

注意：如果指定了"event_report_window"，则不能指定"event_report_windows"，否则来源注册将失败。

"event_report_windows" 可选

表示一系列报告窗口的对象，从"start_time"开始，在"end_times"中指定的每个结束时间之后交付此来源的报告。这可用于在多个报告中更改报告交付时间。如果未设置，则事件报告窗口将回退到"expiry"值。属性如下

• "start_time" 可选：指定报告窗口开始时间的非负数。如果未指定，则默认为0。
• "end_times"：指定后续报告窗口结束时间的正数数组。这些值必须递增，并且大于"start_time"。

  注意：如果指定了"event_report_windows"，则不能指定"event_report_window"，否则来源注册将失败。

"expiry" 可选

表示归因来源过期时间的字符串（以秒为单位），在此时间之后，它将不再处于活动状态（即，后续触发器将无法归因于此来源）。允许的最大过期时间为 2592000 秒（30 天），如果未显式设置"expiry"，则这也是默认值。

"filter_data" 可选

定义自定义数据的对象，该数据可用于筛选哪些转化生成报告。有关更多详细信息，请参阅筛选器。

"max_event_level_reports" 可选

介于0和20（含）之间的数字，指定此来源可以生成的事件级报告的总数。达到此最大值后，该来源将不再能够生成任何新数据。如果未指定，则对于基于导航的来源，"max_event_level_reports"默认为3，对于基于事件的（基于图像或脚本的）来源，默认为1。

"priority" 可选

表示归因来源优先级值的字符串。默认情况下，转化将归因于最近匹配的来源。对于事件级报告和汇总报告，您可以设置更高的优先级编号以优先考虑特定来源。例如，值2优先于默认值1。有关更多信息，请参阅报告优先级和限制。

"trigger_data" 可选

表示数据的 32 位无符号整数数组，这些数据描述了可能与该来源匹配的不同触发器事件。例如，“用户将商品添加到购物车”或“用户注册邮件列表”可能是触发器网站上发生的事件，这些事件可能与该来源匹配，并指示广告客户尝试衡量某种类型的转化。必须将其与触发器中指定的"trigger_data"匹配，才能进行事件级归因。如果省略，则对于基于导航的来源，"trigger_data"默认为[0, 1, 2, 3, 4, 5, 6, 7]，对于基于事件的（基于图像或脚本的）来源，默认为[0, 1]。

注意：用于表示每个事件的值以及数组中的元素数量完全是任意的，由您作为开发人员定义。数组可能包含未使用的值，但必须在数组中存在值，以便在注册触发器时由浏览器归因于来源。

"trigger_data_matching" 可选

指定如何将触发器的"trigger_data"与来源的"trigger_data"匹配的字符串。可能的值为

• "exact"：触发器的"trigger_data"必须与来源的"trigger_data"中包含的值完全匹配；如果没有这样的匹配，则不会发生任何事件级归因。
• "modulus"：在这种情况下，将执行以下计算 — d % allowedValues.size — 其中d是触发器的"trigger_data"，allowedValues是来源的"trigger_data"数组中的值序列。如果此计算的结果与来源的"trigger_data"数组中的值匹配，则匹配成功。在这种情况下，值将始终匹配，除非allowedValues为空。

"modulus"模式主要用于与引入"exact"之前的 API 行为向后兼容，因此您不太可能使用它。它在需要非常具体的压缩类型的特定情况下仍然有用，从而导致更小的注册标头。当使用需要根据来源类型根据来源"trigger_data"项的最大数量设置不同触发器数据的复杂筛选逻辑时，可能需要这样做。

注意：如果使用"modulus"，则来源的"trigger_data"必须形成从 0 开始的连续整数序列。如果触发器数据未形成此类序列，则会发生错误。

如果未指定，则"trigger_data_matching"默认为"modulus"。同样，这样做的原因是向后兼容：省略"trigger_data_matching"字段需要导致与引入此字段之前观察到的相同行为。

Node.js 服务器可能会如下设置Attribution-Reporting-Register-Source响应标头，以便在触发器与来源匹配时使浏览器生成事件级报告

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    source_event_id: "412444888111012",
    destination: "https://shop.example",
    trigger_data: [0, 1, 2, 3, 4],
    trigger_data_matching: "exact",
    expiry: "604800",
    priority: "100",
    debug_key: "122939999",
    event_report_window: "86400",
  }),
);

要使浏览器在触发器与来源匹配时生成汇总报告，您需要包含一些其他字段，除了事件级报告生成所需的字段之外。

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    source_event_id: "412444888111012",
    destination: "https://shop.example",
    trigger_data: [0, 1, 2, 3, 4],
    trigger_data_matching: "exact",
    expiry: "604800",
    priority: "100",
    debug_key: "122939999",
    event_report_window: "86400",

    aggregation_keys: {
      campaignCounts: "0x159",
      geoValue: "0x5",
    },
    aggregatable_report_window: "86400",
  }),
);

• Attribution-Reporting-Eligible
• Attribution-Reporting-Register-Trigger
• 归因报告 API