As described in the Attribution Reporting API design proposal, the API enables attribution of the following trigger paths on a single Android 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 above trigger paths translate to the following requirements:
- For adtechs: 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 adtechs and apps need to make to satisfy the requirements for supporting these trigger paths.
Changes for adtechs
Adtechs will need to enroll to use the Attribution Reporting API. The details of the enrollment process are still in development, and we welcome your feedback.
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 to registration & attribution
When registering an attribution source, adtechs currently 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 adtechs 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.
Receiving app and web reports
The Android Attribution Reporting API can send reports for both app and web conversions. If adtechs do not wish to align trigger data and aggregation keys/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 will be 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 adtech 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:
- 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 adtech can deduplicate conversion reports across measurement solutions. Additionally, an adtech 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.
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-Eligiblebroadcasts whether OS-level support for attribution is available. In this case, the header indicates whether Android's Attribution Reporting API is available.
- If available, adtechs can optionally respond using
Attribution-Reporting-Register-OS-Source, which initiates a secondary API call from the browser app to
- Adtechs can also respond to trigger registrations using the
Attribution-Reporting-Register-OS-Triggerheader, which initiates a secondary API call from the browser app to
Attribution source registration
When registering an attribution source, apps can call
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 adtechs should be included in the report or not.
Input event: Either an
InputEventobject (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 which was used for navigation on user click.
When the API makes a request to the Attribution Source URI, the adtech 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 destination(s) specified by the adtech with the destination(s) 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.
Trigger (conversion) registration
On trigger registration, apps can call
registerWebTrigger(), which expects the
- 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)
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.
Establishing 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.
We are considering mitigations for these situations. One option would be to
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. We are also looking into technical solutions to
validate web content. We
welcome your feedback
on use cases and which types of apps need to call
Any app could call
registerWebTrigger() because the privacy and security
considerations on the trigger side aren't applicable without source-side
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:
- 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?
- Are the proposed rate limits reasonable for app and web traffic?
- Are there any concerns with potentially receiving 2 pings for each attribution source and trigger, one from the browser/app and one from the Attribution Reporting API?
- Will you want to provide a different server endpoint for Android API registrations (versus browser/app API registrations)?
- How can we help make debugging across different APIs easier for you?
- The proposal currently 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?
- For browsers/apps, please reach out if you would be interested in registering web impressions, or any other integrations with the Android Privacy Sandbox Attribution Reporting API.
- 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 will you use to specify this app link?
- 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. Please 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.