Attribution Reporting API: integration guide

The Attribution Reporting API is designed to provide improved user privacy by removing reliance on cross-party user identifiers, and to support key use cases for attribution and conversion measurement across apps. This document includes guidelines to help you get prepared for Attribution Reporting API integration.

This guide attempts to provide a comprehensive view, which may include features that are not yet implemented at the current stage of the Privacy Sandbox on Android Developer Preview. In these cases, related details will be marked as not yet implemented.

Integration goals

In this stage of the Privacy Sandbox Developer Preview, the goals of integration planning include the following:

Current and upcoming support

Currently supported use cases and features in the latest Developer Preview release include the following:

  • Source-prioritized, last-touch attribution and post-install attribution.
  • Register app attribution sources and app triggers.
  • Receive event-level reports.
  • Receive unencrypted aggregatable reports.

Upcoming Developer Preview releases plan to add support for the following additional use cases and technical features. As these features become available, this guide will be updated to reflect relevant details.

  • Ad tech platform enrollment.
  • Debugging support, to help developers compare aggregate reports with those from existing mechanisms.
  • Register web attribution sources and web triggers, to support app-to-web attribution.
  • Receive encrypted aggregatable reports from the API and send batches to the aggregation service.
  • Receive summary reports from the aggregation service.
  • API usage will require a new normal permission.

Intended ad tech audiences

To receive a report from the Attribution Reporting API, an ad tech platform must register both the attribution source and the trigger. At a minimum, to enable a full end-to-end test, both serving ad tech and mobile measurement partners should work together to call the API for the same advertiser, and may need to utilize redirects in the registration calls. You may also need to work with the publisher or advertiser app.

For attribution source registration, the API call will typically be initiated by the ad tech SDK used to serve ads in the publisher app, though the API can also be called directly by the app.

For trigger registration, the API call will typically be initiated by the mobile measurement partner's SDK in the advertiser app, or from the advertiser app itself.

Prerequisites

Integration steps

To prepare for integrating the Attribution Reporting API into your solution, complete the steps described in the following sections.

Verify technical correctness in the test environment

  • Create a test application to familiarize yourself with the Privacy Sandbox on Android Attribution Reporting API. At this stage, you could also start with the sample app on GitHub.
  • Set up mocked server endpoints, or use our sample server, to familiarize with the REST API signatures used by the Attribution Reporting client APIs.
  • Register events, including view, click, and conversion (trigger) events.
  • For testing purposes, force-run reporting jobs, using the appropriate ADB commands, to reduce the time horizon to receive report data for both event-level and aggregate reports.
  • Evaluate the applicability of API signatures for your current technology stack. This includes input parameters and return values. Identify any gaps in data flow and mitigations.

Verify compatibility with existing technical infrastructure

  • Client-side development environment and codebase:
    • After the Developer Preview, Privacy Sandbox on Android will require a minimum target API level of 33. Identify a migration path for your existing codebase. Evaluate your app’s or SDK's compatibility with other changes introduced in Android 13.
  • Server-side:
    • Add API stub endpoints to existing technical infrastructure to find and verify any technical limitations.
    • Add callbacks to accept reports to existing technical infrastructure.

Define and verify integration requirements

  • Verify—in either logs or server data—that reports contain data from the views, clicks, and conversions.
  • Verify both event-level and aggregate-level reports.