Attribution reporting: cross app and web measurement

Recent updates

As described in the Attribution Reporting API design proposal, the API enables attribution of the following trigger paths on a single Android-powered device:

  • App-to-app: The user sees an ad in an app, then converts in either that app or another installed app.
  • App-to-web: The user sees an ad in an app, then converts in a mobile or app browser.
  • Web-to-app: The user sees an ad in a mobile or app browser, then converts in an app.
  • Web-to-web: The user sees an ad in a mobile or app browser, then converts in either the same browser or another browser on the same device.

Web here is defined as web content shown in an app. Web content can be shown in the context of a mobile browser app or as embedded websites shown in non-browser apps.

The preceding trigger paths translate to the following requirements:

  • For ad techs: updates to API calls and reporting to enable app-to-web paths
  • For apps and browsers: ability to pass registration of web attribution sources and web triggers to Android

This document explains how the Attribution Reporting API is extended to support app-to-web, web-to-app, and web-to-web trigger paths. It also describes the changes that ad techs and apps need to make to satisfy the requirements for supporting these trigger paths.

Get access to Attribution Reporting APIs

Ad tech platforms need to enroll to access the Attribution Reporting APIs, see Enroll for a Privacy Sandbox account for more information.

Once the enrollment process is finalized, the API will discard the registration if an unenrolled registration call is received.

When enrolling, ad tech platforms should ensure they are enrolling with all the server URLs that they might use across app and web to register attribution sources and triggers. Multiple server registration URLs are supported, but only one reporting origin is supported. This reporting origin is derived from the domain of one of the server registration URLs.

Changes for ad techs

Changes to registration & attribution

When registering an attribution source, ad techs specify a destination field which is the app package name where the trigger event occurs. To enable app-to-web measurement, we plan to support one app destination field (app package name) and one web destination field (eTLD+1).

When registering web attribution sources or triggers, the API does not support redirects because each app hosting web content could have its own permissions model. Each app is responsible for following redirects (if supported) and calling the web context APIs for each redirect hop.

Additionally, this integration enables ad techs to use app-specific attribution logic on web attribution sources. For example, you can now specify post-install attribution windows on a web attribution source.

Receive app and web reports

The Android Attribution Reporting API can send reports for both app and web conversions. If ad techs don't want to align trigger data and aggregation key-values across web and app surfaces, they can differentiate between a web and an app conversion:

  • For event-level reports, we will support a destination field that specifies whether the trigger happened on web (destination is a eTLD+1) or app (destination is an app package name)
  • For aggregatable reports, the destination is sent in cleartext.

Web-to-web measurement implications

Apps choose when to pass registration to the Attribution Reporting API. There are several considerations here:

  • Is the Attribution Reporting API available on that device? We will expose a new signal to apps which returns whether the Attribution Reporting API is available on that device. See the app changes section for more details on how apps can pass registration to the Attribution Reporting API.
  • What portion of attribution sources and triggers should be passed to the API? This will be a decision made by each app, or the ad tech if the app permits a choice. If the app has their own measurement solution, they may want to consider using that instead. Ultimately, passing all source and trigger registrations to the Android Attribution Reporting API, when available, enables the most accurate attribution across app and web.

The following example shows how browser apps can work with the Attribution Reporting API to provide accurate measurement when the user clicks on an ad in both a browser app and a non-browser app:

Examples of user clicks and conversions over a 3-day period
Example of source and trigger registration across a browser and an app
  • On day 1, the user clicks on an ad in the browser app.
    • The browser app can choose to use their own measurement solution or pass registration of the web ad click to the Attribution Reporting API.
  • On day 2, the user clicks on an ad in a non-browser app.
    • The click is registered as an attribution source with the API. The browser app has no visibility into this click because the event occurred within a different app.
  • On day 3, the user converts in the browser app.
    • If the browser app both registers the click and conversion using their own measurement solution and passes that information to the Attribution Reporting API, it's unlikely that an ad tech can deduplicate conversion reports across measurement solutions. Additionally, an ad tech could consume both the browser app rate limits and the Attribution Reporting API rate limits. Therefore, we recommend that apps pass all ad events and conversions to be registered on the API, when the API is available.

Register attribution source and trigger from WebView

In the case where the app is using WebView to show web content rather than a native Android ad, the app can apply to join the allowlist for registerWebSource() and provide the top-level origin of the website to be associated with the attribution source rather than the app package name.

Similar to browsers, WebView supports registerWebTrigger() for trigger registrations, which associates the trigger with the top-level origin. There is no support for WebView to register an app trigger; reach out if you have a use case for this. For the full list of combinations supported by WebView, refer to Attribution source and trigger registration from WebView.

Unlike browsers, WebView only supports registration with the OS within the Attribution-Reporting-Eligible header if Android's Attribution Reporting API is available. If Android's Attribution Reporting API is unavailable, WebView doesn't set an Attribution-Reporting-Eligible header and no registrations are made.

To register an attribution source / trigger using the OS:

  • Ad techs should respond to source registrations using the Attribution-Reporting-Register-OS-Source header, which initiates a secondary API call from the WebView to registerSource() or registerWebSource().
  • Ad techs can also respond to trigger registrations using the Attribution-Reporting-Register-OS-Trigger header, which initiates a secondary API call from the WebView to registerWebTrigger() or registerTrigger().

Note that if the response does not include the previous headers, or it also includes the Attribution-Reporting-Register-Source / Attribution-Reporting-Register-Trigger headers even though web is not supported, then the entire registration will fail.

For details on whether WebView will use registerSource() / registerWebSource() and registerTrigger() / registerWebTrigger() (as well as how to change this behavior) refer to Attribution source and trigger registration from WebView.

Transitional debugging reports

The Attribution Reporting API supports an optional functionality called transitional debugging reports, which allows ad techs to learn more information about attribution reports when an advertising ID is available. There are two types of debugging reports: attribution-success and verbose. These reports are supported for cross app and web attribution, and both report types contain the same information; the only difference being around permissions that gate when debugging reports are sent out.

For web-to-web attribution that happens within a single app (for example, within the same browser app), attribution-success and verbose reports are available only when third-party cookies are available, and are not based on advertising ID availability.

For app-to-web, web-to-app, and web-to-web cross-app attribution, attribution-success and verbose reports are available if AdID is available on the app side and the ad tech can pass the same (correct) AdID on the web side. See below for an app-to-web example where the source happens in a publisher app, but the trigger happens on an advertiser site inside a browser app.

To enable an attribution-success debugging report for app-to-web, all three conditions below must be met:

  • The user must not have opted out of personalization using the advertising ID
  • The publisher app must have declared AdID permissions
  • The ad tech must pass the AdID value in trigger registration (from a web context)

To enable verbose debugging reports for app-to-web:

  • Source verbose reports depend on the publisher side permissions only. For source verbose reports to be sent, the user must not have opted out of AdID personalization, and the publisher app must have declared AdID permissions.
  • Trigger verbose reports depend on the trigger side (in this example, web) permissions only. Third-party cookies must be available in the browser for trigger verbose reports to be sent.
  • For trigger verbose reports that can optionally include a source_debug_key, the source_debug_key is included if the advertising ID is available to the publisher app.

Note that in all cases, the ad tech still needs to opt in to receiving verbose debugging reports using the debug_reporting dictionary field in source and trigger registration headers.

Changes for apps

We will support attribution across app and web surfaces by allowing apps to pass registration of web attribution sources and web triggers to the Attribution Reporting API on Android using a new set of web context API calls.

After completing the registration steps in the following sections, app and web attribution sources and triggers are stored on the device, and the Attribution Reporting API can perform source-prioritized, last-touch attribution across app and web surfaces.

See Privacy Sandbox for the Web's proposal for an example of how browsers can integrate with Android's Attribution Reporting API to enable cross app and web measurement. In the proposal, the browser will add the following request headers:

  • Attribution-Reporting-Eligible broadcasts whether OS-level support for attribution is available. In this case, the header indicates whether Android's Attribution Reporting API is available.
  • If available, ad techs can optionally respond using Attribution-Reporting-Register-OS-Source, which initiates a secondary API call from the browser app to registerWebSource().
  • Ad techs can also respond to trigger registrations using the Attribution-Reporting-Register-OS-Trigger header, which initiates a secondary API call from the browser app to registerWebTrigger().

Attribution source registration

When registering an attribution source, apps can call registerWebSource(), which expects the following parameters:

  • Attribution source URIs: The platform issues a request to each URI in this list in order to fetch metadata associated with the attribution source.

    Each URI should accompany a boolean Debug flag to indicate if the debug keys provided by the techs should be included in the report.
  • Input event: Either an InputEvent object (for a click event) or null (for a view event)
  • Source origin: Origin on which the source occurred (publisher website).
  • OS destination: An app package name where the trigger event happens.
  • Web destination: An eTLD+1 where the trigger event happens.
  • Verified destination: OS or web destination URI intent used for navigation on user click.

When the API makes a request to the Attribution Source URI, the ad tech should respond with the attribution source metadata in an HTTP header, Attribution-Reporting-Register-Source. This header uses the same fields as app-to-app attribution source registration, with a few changes:

  • The API validates the destinations specified by the ad tech with the destinations specified by the app. If destinations are different, the API discards the attribution source registration.

    Apps are expected to validate web destinations before calling the web context API. For clicks, apps should check that the destination specified matches the destination to which the user is navigating.
  • The API ignores any redirect URIs provided in Attribution-Reporting-Redirects. Apps should follow redirects on their own and call registerWebSource() for each redirect, so that they can apply their own permissions policies as needed.

Apps must join an allowlist to call registerWebSource(). Complete this form to join the allowlist. The intent of the allowlist is to mitigate privacy considerations around establishing trust for web context.

Trigger (conversion) registration

On trigger registration, apps can call registerWebTrigger(), which expects the following parameters:

  • Trigger URIs: The platform issues a request to each URI in this list in order to fetch metadata associated with the trigger
  • Destination origin: Origin on which the trigger occurred (advertiser website)

Attribution source and trigger registration from WebView

By default, WebView will use registerSource() and registerWebTrigger(). This associates sources with the app and triggers with the top-level origin of the WebView when the trigger occurs.

If an app requires different behavior (such as those that host web content in a WebView) they need to use the setAttributionRegistrationBehavior method on the androidx.webkit.WebViewSettingsCompat class. This method will specify whether WebView should call registerWebSource() or registerSource() and registerWebTrigger() or registerTrigger().

The available options for setAttributionRegistrationBehavior are the following:

Value Description Example use case
APP_SOURCE_AND_WEB_TRIGGER (default) Allows apps to register app sources (sources associated with the app package name) and web triggers (triggers associated with the eTLD+1) from WebView. Apps that use WebView to serve ads rather than enable web browsing
WEB_SOURCE_AND_WEB_TRIGGER Allows apps to register web sources and web triggers from WebView.
Note: Apps using this option will need to apply to join the allowlist to use registerWebSource().		 WebView-based browser apps, where ad impressions and conversions could both happen on websites in WebView.
APP_SOURCE_AND_APP_TRIGGER Allows apps to register app sources and app triggers from WebView. WebView-based apps where ad impressions and conversions should always be associated with the app rather than the eTLD+1 of the WebView.
DISABLED Disables source and trigger registration from WebView.
Note that the initial network call to the Attribution Source or Trigger URIs may still happen, but any response is discarded and nothing will be stored on the device.

Privacy and security considerations

Impact on privacy-preserving mechanisms applied to reports

As described in the main design proposal, the API applies privacy-preserving rate limits to reports. Some limits are partitioned across source and destination apps. When a web attribution source or trigger is registered, the rate limit is partitioned by the source or destination site instead of the app.

If the app maintains separate rate limits, it would be possible for an adversary to consume app-specific rate limits in addition to the API's rate limits. To mitigate this, apps should ensure that a given attribution source isn't registered on both the app's measurement solution and the Android Attribution Reporting API.

Establish trust for web context

In the web context API calls, the API places trust in the app to detect and specify the source and destination origins. This can open up potential privacy and security considerations:

  • An adversary can claim to be hosting websites it owns in an attempt to bypass rate limits around the amount of information any source can transfer.
  • Multiple adversaries can collude to register separate attribution sources, claiming the same source site. This could cause the source site to hit ad tech platform rate limits and prevent the actual source site from registering legitimate attribution sources.

To mitigate this, we will limit which browsers or apps can call registerWebSource() to browsers or apps that attest that the source site used in registration represents the actual site being shown to the user. Fill out this form to join the allowlist to call registerWebSource().

Any app could call registerWebTrigger() because the privacy and security considerations on the trigger side aren't applicable without source-side collusion.

User controls

Apps can continue to support user controls or permissions policies as long as they can be defined at registration time. For example, if apps allow any site-level or user-level permissions, the app should evaluate those and determine whether to call the web context APIs.

Additionally, we will support a new API call from apps to delete any attribution sources, triggers, and pending reports stored for that app on the device. For example, if apps allow the user to clear their browsing history, they may want to call the API to delete attribution sources, triggers, and pending reports stored for that app on the user's device.

Future considerations & open questions

The app-to-web interoperability for the Attribution Reporting API is a work in progress. We'd like to seek feedback from the community on a few ideas:

  1. On an Android Privacy Sandbox supported device, how will you use browser measurement solutions with the Android Attribution Reporting API? Will you prefer to pass everything to Android?
  2. Are there any concerns with potentially receiving 2 pings for each attribution source and trigger, one from the browser or app and one from the Attribution Reporting API?
  3. How can we help make debugging across different APIs easier for you?
  4. The proposal does not include validation that app and web destinations are affiliated. In the future, we may be able to validate these destinations by checking associations using Digital Asset Links. Would that block any of your use cases? Does it make sense to use Digital Asset Links to do this validation?
  5. When registering an attribution source, you must specify a destination. In the web-to-app case, you may want to specify an app link. What formats do you use to specify this app link?
  6. When registering an app-to-web attribution source, that source event would need to be registered from the app with the Android Attribution Reporting API. For example, if the user clicks on an ad and the click is opened in a browser or a browser's custom tab, that click (source event) should be registered from the app rather than in the browser context. Reach out if you have concerns about this, or if there are other use cases that don't fall into the categories covered in this issue describing supported flows.