Filter sources before attribution using attribution scopes

Attribution scopes allows API callers to specify a list of strings during source and trigger registration that can be used for filtering before attribution takes place. This allows finer grain filtering to increase API efficiency and provide more flexibility. For example, it enables tracking separate advertisers on the same site distinctly. It also facilitates tracking multiple campaigns or products within a single ad banner.

Attribution scopes are optional fields that can be set during source and trigger registration. During attribution, only sources whose attribution scope values contain at least one of the trigger's attribution scope values will be considered for attribution. If no scope is specified in the trigger then all sources will be considered. Before you continue, you should be familiar with the Attribution reporting API and high-level filters.

During source registration

An optional parameter attribution_scopes is added to the header Attribution-Reporting-Register-Source which contains two required parameters: values, and limit; and one optional parameter: max_event_states.

  • limit: Represents the total number of distinct scopes allowed per destination for the source reporting origin. Any existing registered sources with the same reporting origin and destination, but a smaller limit, will be deleted.
  • values: Represents the list of attribution scopes for a particular source. These values must be strings with a maximum length of 50.
  • max_event_states (optional): Represents the maximum number of event states that an API caller plans to use across all subsequent event-source registrations. Note that any existing registered sources with the same reporting origin and destination but a different max_event_states value will be deleted. The default value for this optional field is 3.

Source registration sample

  Attribution-Reporting-Register-source: {
  //optional
  "attribution_scopes":{
  "limit": <int>,
  "values": <list of strings>,
  // optional
  "max_event_states": <int>
    },
  ...
  }

During trigger registration

An optional parameter attribution_scopes is added to the header Attribution-Reporting-Register-Trigger during trigger registration. Ensure the parameter value is a list of strings representing the scopes for the trigger. The trigger will only match sources whose attribution_scopes values parameter contains at least one of the trigger's attribution_scopes, if specified.

Trigger registration sample

Attribution-Reporting-Register-Trigger: {
//optional
"attribution_scopes": <list of strings>,
...
}

Attribution scopes example

The following example shows the case where a trigger is attributed to a source while using attribution scopes.

Source registration #1

  Attribution-Reporting-Register-source: {
  "destination": "https://trigger.example",
  "attribution_scopes": {
  "limit": 2,
  "values": ["advertiser1"],
  "max_event_states": 3
  },
  ...
  }

Source registration #2

  Attribution-Reporting-Register-source: {
  "destination": "https://trigger.example",
  "attribution_scopes": {
  "limit": 2,
  "values": ["advertiser2"],
  "max_event_states": 3
  },
  ...
  }

Trigger registration

  Attribution-Reporting-Register-Trigger: {
  "attribution_scopes": ["advertiser1"],
  ...
  }

When the trigger registration occurs, the API selects sources to be considered for attribution that have attribution_scopes values that intersect with the values in the trigger registration. The matching source registrations will continue with the rest of the attribution flow. In this example, the API caller will receive an attribution report attributing the trigger registration to the first source registration.

Attribution scopes versus filters

While the functionality of attribution scopes and filters may appear similar, the distinguishing factor is where they are applied in the trigger registration flow. Attribution scopes filtering happens before attribution. This means it reduces the pool of unexpired, candidate sources having the same destination site and reporting origin, based on which sources have scopes that intersect with the scopes found in the trigger. Top-level filters, however, are applied after a trigger has been attributed to a single source. If the source and trigger filters don't intersect then no reports are generated.

The following image shows a group of sources and a trigger that have the same destination site, reporting origin and are not expired. We'll briefly talk about how attribution scopes and filters are used and whether a report will be generated based on the available sources and triggers.

An image showing 4 boxes labelled sources numbered 1 through 4 and a single box labelled

Before attribution

  • Source #1 is filtered out as its attribution scope doesn't match the trigger's scope of casualwear. Having the highest priority among all available sources doesn't prevent it from being filtered out as pre-attribution filtering occurs before priorities are checked.
  • Source #2 is also filtered out due to not having the same scope as the trigger. This source also has the same filter as the trigger but high level filters aren't applied until after attribution.

During attribution

  • Source #3 is not selected for attribution as it has lower priority than Source #4.
  • Source #4 is selected as it has a matching attribution scope to the trigger and has the highest priority. High level filters are applied post attribution so they don't factor in during the attribution process.

Post attribution

  • No report is generated as the high level filters for the selected source (source #4) and the trigger don't intersect.

The previous example doesn't result in a report being generated. However, if the fourth source is removed completely:

The same image having 4 boxes labelled sources numbered 1 through 4 and a single box labelled

During attribution

  • Source #3 is selected as it has an intersecting attribution scope with the trigger.

Post attribution

  • Source #3 isn't rejected as its filter intersects with the filter in the trigger. The attribution will then go through the rest of the post attribution checks ending with a report being generated if it passes all the checks.

Attribution scopes reduce the number of sources considered for attribution. The remaining attribution steps are then applied to this smaller pool of sources, which may result in a report.

Attribution scopes' place in attribution flow

Attribution scopes are applied before a source is selected for attribution. This also precedes top-level-filters and custom report window filtering. The following diagram shows a simplified version of overall attribution flow with attribution scope happening before attribution and the rest of the attribution checks.

An image showing a simplified version of the attribution flow with each step represented as a square linked to the next step by an arrow. The steps in order are

Attribution flow operations

The following is a recap of the various operations performed during the attribution flow:

  • Source registration: When a user interacts with an ad on the advertiser's site, a source event is registered. The device then sends a request to the reporting origin's endpoint, which responds with a header containing source event data.
  • Trigger registration: When a conversion occurs on the advertiser's site, a trigger event is registered. Another request is sent by the device to the reporting origin, which responds with a header containing trigger event data.
  • Source matching: The device matches source and trigger events based on criteria such as destination site, reporting origin and expiry.
  • Attribution scopes check: Sources are filtered based on intersection between source and trigger attribution_scopes values.
  • Attribution: The device selects the highest priority source for attribution if multiple sources match. If priorities are equal, the most recent one is selected.
  • Filters check: The device compares the source and trigger filters to determine if they match. If the filters don't match then the attribution is dropped.
  • Deactivation of other sources: If the chosen source's filters match, the device deactivates sources matched during the Source matching stage. Sources deactivated will include sources whose attribution scopes don't match trigger scopes.
  • Post-attribution checks: The device performs more checks on the selected attribution such as checking if the source is noised with fake reports, checking duplicate attributions using deduplication keys, checking if the trigger falls within the source's report window, and checking rate limits.
  • Report generation: If all checks pass, the device generates and schedules an attribution report to be sent to the reporting origin's endpoint.

Next steps