Skip to content

Latest commit

 

History

History
182 lines (136 loc) · 11.3 KB

app_to_web.md

File metadata and controls

182 lines (136 loc) · 11.3 KB
Raw

Cross App and Web Attribution Measurement

Authors:

  • Charlie Harrison
  • Michael Thiessen
  • John Delaney

Participate

See Participate. Please file GitHub issues with the app-to-web label.

Introduction

Currently, the Attribution Reporting API supports attributing events within a single browser instance. This proposal expands the scope of attribution to allow attributing conversions that happen on the web to events that happen off the browser, within other applications.

This proposal was inspired by Safari's App-to-web support in Private Click Measurement and the Android Privacy Sandbox proposal.

The proposal here takes advantage of OS-level support for attribution. In particular, it gives the developer an option to allow events on the mobile web to be joinable with events in Android’s Privacy Sandbox, although support for other platforms could also be implemented.

Goals

  • Support measurement of ads that show up within apps that later convert on the web
  • Support measurement of ads that show up within the browser that later convert on the web or in an app / app install
  • Support both clicks and views
  • Proposal is generic enough to be implemented by any browser
  • While focusing initially on Android support, the proposal should be generic enough to be supported on other platforms

API changes

sequenceDiagram
  participant B as Browser
  participant O as OS platform
  participant R as Reporting endpoint
  Note over B,R: For either source or trigger registration
  B->>R: Registration request advertising OS support
  R->>B: Response headers chooses how registration is handled
  alt header opts into OS handling
  B->>O: Passes relevant information to the OS
  O->>R: OS re-pings to attain full registration config
  else header opts out and provides browser registration
  B->>B: Applies standard registration
  end
Loading

See Android's Attribution reporting: cross app and web measurement proposal for one example of an OS API that a browser can integrate with to do cross app and web measurement.

The existing API involves sending requests to the reporting origin to register events. These requests will have a new request header Attribution-Reporting-Eligible. On requests with this header, the browser will additionally broadcast possible web or OS-level support for attribution to the reporting origin's server via a new dictionary structured request header:

Attribution-Reporting-Support: os, web

Note that if there is neither web nor OS-level support for attribution, no background requests will be made and the browser will not set Attribution-Reporting-Eligible header on <a>, window.open, <img>, or <script> requests.

If the Attribution-Reporting-Support header indicates OS support, the reporting origin can optionally respond to the request with a list structured header containing one or more URLs that indicates a desire to use the OS's attribution API instead of the browser's. Note that the API also allows browsers to only support OS-level attribution if they choose.

Note: the Attribution-Reporting-Support header is subject to the browser adding "GREASE" parameters, to ensure that servers use a spec-compliant structured header parser. See here for an example. For this header, only the structured-dictionary keys should be interpreted: the values and parameters are currently unused, but may have meaning in the future.

// Registers a source against a native OS attribution API
Attribution-Reporting-Register-OS-Source: "https://adtech.example/register", "https://other-adtech.example/register"

Trigger registrations will accept a new response header as well:

// Registers a trigger against a native OS attribution API
Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register", "https://other-adtech.example/register"

The reporting origin can also optionally respond with a dictionary structured header Attribution-Reporting-Info to specify the preferred platform. The key is preferred-platform and the value is a structured header token with allowed values os and web.

Attribution-Reporting-Info: preferred-platform=os

The browser will make the platform decision based on the availability of the platform support on the user's device.

After receiving these headers, the browser will pass these URLs into the underlying OS API with any additional information including: the context on which the event occurs (source / destination site) the InputEvent in the event of a click/navigation source, for platform verification

Normal attribution logic in the browser will be halted.

For a site to enable App<->Web attribution after integrating with the Web API, they will only need to make server side changes.

A reporting origin responding with the Attribution-Reporting-Register-OS-Source or Attribution-Reporting-Register-OS-Trigger headers while there is no OS-level support will cause the OS registration to fail. If both OS registration and web registration are provided in the response while there is no OS-level support, the browser will fallback to the web registration only if a preferred platform is specified. If a preferred platform is not specified, then the web registration will fail as well.

Optional: debugging reports

The Cross App and Web Attribution Measurement is new and fairly complex. A successful attribution requires both the browser and OS-level support. As such, we are open to introducing a mechanism to learn more debug information about OS registrations. This ensures that the API can be better understood and help flush out any bugs (either in browser or OS or caller code).

The reporting origins may opt in to receiving debugging reports by adding a new boolean parameter debug-reporting to the items in the Attribution-Reporting-Register-OS-Source and Attribution-Reporting-Register-OS-Trigger headers:

Attribution-Reporting-Register-OS-Source: "https://adtech.example/register"; debug-reporting, "https://other-adtech.example/register"
Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register", "https://other-adtech.example/register"; debug-reporting

The debug-reporting parameter is set for each registration URL independently. When the OS registration is successfully delegated to the OS, regardless of the native OS attribution API result, the browser will send a non-credentialed HTTP POST request to the registration URL's origin at the path /.well-known/attribution-reporting/debug/verbose, e.g.

https://adtech.example/.well-known/attribution-reporting/debug/verbose

The report data is included in the request body as a JSON list of objects, e.g.:

[{
  "type": "os-source-delegated", // or "os-trigger-delegated"
  "body": {
    "context_site": "https://source.example",
    "registration_url": "https://adtech.example/register"
  }
}]

Note: The report body is a JSON list to align with the verbose debugging reports for the web-based Attribution Reporting API.

The reporting origins may also opt in to receiving header-error debugging reports (details).

Privacy considerations

This proposal explicitly links data from the web with data from apps. It enables apps to learn coarse user behavior patterns in the browser in the same way that the existing Attribution Reporting API allows websites to learn coarse user behavior patterns in the browser. In other words, we can safely think of an app as a particular "kind of website", and we can share data to apps that we’d be comfortable sharing to a (cross-site) website.

However, there are some “privacy budget” / rate-limit consequences to expanding support to the OS. In particular, if the OS maintains a separate budget than the browser, an adversary could in theory consume both the browser-local budget and the OS system budget, leaking more than if only the browser-local budget were used. Mitigations for this issue include stricter budgets overall, or being more restrictive about entities that can register both OS-level events and browser-local events.

Additionally, this proposal sends user information from the browser to the operating system. The OS will be responsible for integrating with browser user controls such as those for clearing browsing history.

New fingerprint vector

The new request header we would add to the API, Attribution-Reporting-Support adds an additional fingerprinting vector letting an adversary know if the underlying platform supports attribution reporting.

User Control

Attribution between two websites within the browser doesn't require specific OS support. However, attribution of web to app or app to web will require (1) that a user's device supports both a valid version of the browser and a valid version of the operating system and (2) that the user has not disabled the Attribution Reporting API for either the browser or the platform. If the user has opted out of the API in either the browser or at the OS level, app to web or web to app attribution will not be enabled.

Security considerations

This design places trust in the OS to process potentially sensitive user data. Additionally, it requires the OS to place trust in the browser.

Further discussion on the Android-specific measurement API's security considerations can be found here.

Appendix

Alternative design considered: Sending app events directly to browsers

A previous iteration of this design involved sending app events to “the browser” using Android Intents. This design was not ideal due to scalability issues when there were multiple browsers on a user’s device, since it put the singular browser in the center of attribution, in control of everything. If there were multiple browsers, an app would be forced to send things like view Intents to all the registered browsers on the device at once.

With platform-level support, this kind of architecture is not necessary.

References & acknowledgements

Apple has announced a similar feature to support conversions within Safari to be attributed to app clicks on iOS.