files/en-us/web/http/reference/headers/attribution-reporting-register-source/index.md
{{deprecated_header}}
The HTTP Attribution-Reporting-Register-Source {{Glossary("response header")}} registers a page feature as an attribution source.
This header is included as part of a response to a request that contains the {{HTTPHeader("Attribution-Reporting-Eligible")}} header. It provides the information that the browser should store when a user interacts with the attribution source. The information you include in this header also determines the types of reports the browser can generate.
See the Attribution Reporting API for more details.
<table class="properties"> <tbody> <tr> <th scope="row">Header type</th> <td>{{Glossary("Response header")}}</td> </tr> <tr> <th scope="row"> {{Glossary("CORS-safelisted response header")}} </th> <td>No</td> </tr> </tbody> </table>[!NOTE] If the calling site does not have the Attribution Reporting API included in a successful privacy sandbox enrollment process, the
Attribution-Reporting-Register-Sourceheader is ignored and attribution sources are not registered.
Attribution-Reporting-Register-Source: <json-string>
<json-string>
"source_event_id" {{optional_inline}}
"destination"
"aggregation_keys" {{optional_inline}}
"aggregatable_report_window" {{optional_inline}}
"expiry" value."debug_key" {{optional_inline}}
"debug_reporting" {{optional_inline}}
debug_key is set, set this to true to specify that the generated debug report should be a verbose debug report."event_level_epsilon" {{optional_inline}}
0, which controls the amount of noise added to reports. Lower values of epsilon result in more noise and therefore provide greater privacy protection. The maximum and default values will vary across implementations; Chrome for example has a maximum and default value of 14."event_report_window" {{optional_inline}}
"expiry" value.
[!NOTE] If
"event_report_window"is specified,"event_report_windows"cannot be specified, otherwise the source registration will fail.
"event_report_windows" {{optional_inline}}
"start_time", with reports for this source being delivered after each specified end time in "end_times". This can be used to vary the time of report delivery across multiple reports. If not set, the event report window falls back to the "expiry" value. Properties are as follows:
"start_time" {{optional_inline}}: A non-negative number specifying the start time for the reporting windows. If not specified, it defaults to 0."end_times": An array of positive numbers specifying end times for subsequent report windows. The values must be increasing, and greater than "start_time".
[!NOTE] If
"event_report_windows"is specified,"event_report_window"cannot be specified, otherwise the source registration will fail.
"expiry" {{optional_inline}}
"expiry" is not explicitly set."filter_data" {{optional_inline}}
"max_event_level_reports" {{optional_inline}}
0 and 20, inclusive, which specifies the total number of event-level reports this source can generate. After this maximum is reached, the source is no longer capable of producing any new data. If not specified, "max_event_level_reports" defaults to 3 for navigation-based sources and 1 for event-based (image- or script-based) sources."priority" {{optional_inline}}
2 takes priority over the default value of 1. See Report priorities and limits for more information."trigger_data" {{optional_inline}}
: An array of 32-bit unsigned integers representing data that describes the different trigger events that could match this source. For example, "user added item to shopping cart" or "user signed up to mailing list" could be actions happening at the trigger site that could match this source and indicate a conversion of some kind that the advertiser is trying to measure. These must be matched against "trigger_data" specified in triggers for event-level attribution to take place. If omitted, "trigger_data" defaults to [0, 1, 2, 3, 4, 5, 6, 7] for navigation-based sources and [0, 1] for event-based (image- or script-based) sources.
[!NOTE] The values used to represent each event, and the number of elements in the array, are completely arbitrary and defined by you as the developer. The array may contain values that are not used, but values must be present in the array to be attributed to the source by the browser when a trigger is registered.
"trigger_data_matching" {{optional_inline}}
: A string that specifies how the "trigger_data" from the trigger is matched against the source's "trigger_data". Possible values are:
"exact": The "trigger_data" from the trigger must exactly match a value contained in the source's "trigger_data"; if there is no such match, no event-level attribution takes place."modulus": In this case, the following calculation is performed — d % allowedValues.size — where d is the "trigger_data" from the trigger, and allowedValues is the sequence of values in the source's "trigger_data" array. If the result of this calculation matches a value in the source's "trigger_data" array, the match is a success. In such a case, the value will always match, unless allowedValues is empty."modulus" mode exists primarily for backwards compatibility with the API's behavior before "exact" was introduced, and as such, you'd be unlikely to use it. It is still useful in particular cases that require a very specific kind of compression resulting in smaller registration headers. This can be required when using complex filtering logic that needs to set different trigger data based on the source type according to the maximum number of source "trigger_data" items.
[!NOTE] If
"modulus"is used, the source's"trigger_data"must form a contiguous sequence of integers starting at 0. If the trigger data does not form such a sequence, an error occurs.
If not specified, "trigger_data_matching" defaults to "modulus". Again, the reason for this is backwards compatibility: omitting the "trigger_data_matching" field needs to result in the same behavior observed before this field was introduced.
A Node.js server might set the Attribution-Reporting-Register-Source response header as follows to make a browser generate an event-level report when a trigger is matched to a 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",
}),
);
To make the browser generate a summary report when a trigger is matched to a source, you need to include some extra fields, in addition to those required for event-level report generation.
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",
}),
);
{{Specifications}}
{{Compat}}