Native ads on Android

Note: The Privacy Sandbox on Android is an ongoing project, and this document reflects its current design. Your feedback is essential as we continue to develop and enhance its features.

The Native Ads format allows the publisher to customize an ad that's shown to a user. After fetching an ad from the SDK, publishers can then change the layout and look of the ad to align better with the application's user interface: adding a color filter, changing typography, and adding custom overlays. To optimize the performance or user experience of Native Ads, publishers often set display limits or offload video playback to the SDK. Finally, publishers can customize ad click listeners to monitor for additional events such as upward swipes.

The Native Ads format requires a higher level of trust on the publisher than needed for showing other ad formats. SDKs typically want to detect policy violations and to verify that the ad content given to the publisher was shown to the user.

Banner ad support in the SDK runtime is achieved through the SurfaceControlViewHost API. This allows the SDK to show user interface elements from the SDK Runtime process without it being tampered with by the client application. Use SurfaceView Z above or Z below modes to determine whether the surface where the SDK UI is rendered is above or below the client application's window. When an ad is rendered using Z above mode, the SDK receives MotionEvents from user interaction, but the client application views aren't visible over the ad. When an ad is rendered in Z below mode, the application shows its own views on top of the ad, but MotionEvents from user interaction on the ad go to the application, not to the SDK.

The privacysandbox.ui Jetpack libraries can be used by the SDK and publisher to establish and maintain a UI session.

App-owned ad container

We prototyped letting the SDK own all views comprising a native ad (including the application's overlays) and found that while feasible, it imposed some restrictions on the UI and increased integration complexity with the SDK. A more pragmatic approach is to let the application own most views. The SDK can still choose to show some UI themselves, such as the ad view, using SandboxedSdkView from privacysandbox.ui. This approach provides the most flexibility in how existing and future use cases for this ad format are supported: With this approach, the app developer gets to move ad components around and style them as needed, while the SDK retains ownership of the video player, if preferred, and maintains access to media controls.

Proposed Native Ads control flow.

Notifications about ad state

Different SDKs look at different properties of ad views for fraud detection and policy violations. We'd like to support this without prescribing which properties to use, or becoming the bottleneck for the SDK changing the set of properties queried. We propose creating a representation of the ad container, and its children views, using NativeAdContainerInfo. This will be a parcelable object with various getters exposing information limited to the ad container and its contents, where such information is privacy-preserving and not expensive to compute. The SDK will be able to opt in to categories of signals included in NativeAdContainerInfo. The SDK would receive this object whenever the ad state changes in ways relevant to the SDK, such as billable events like ad impression and user clicks.`

Additionally, the publisher will be able to add view-specific tags (Strings) to each child added to NativeAdContainer, which can be used to let the SDK know which ad asset each child corresponds to.

When the user clicks on SDK-owned views, the UI library will forward the MotionEvent with properties translated to the SDK's coordinate space to the SDK, along with the original MotionEvent. For future versions of Android, we're exploring adding ways to let the client application to transfer touch focus for all user gestures on the SDK-owned parts of this native ad to be handled by the SDK.

Attestations

The following attestations will be available to the SDK to get stronger assurances about ad presentation:

1. Device integrity attestation: Use platform APIs like Key Attestation to determine device integrity.
2. APK identity: Use SdkSandbox APIs like SdkSandboxController.getClientPackageName and PackageManager APIs like requestChecksum to verify APK identity.
3. VerifiedMotionEvents: On future versions of Android, we're exploring enabling the client application to transfer touch focus for all user gestures on the SDK owned parts of this native ad to be handled by the SDK. MotionEvents can be converted to VerifiedMotionEvents using system APIs. The SDK can show their own UI in response to user interaction if they choose.

Open questions

1. Is it preferable for the SDK to generate VerifiedMotionEvents themselves, or for the provider UI library to do so for the SDK?
2. Is it preferable for the SDK to let the publisher own views containing video, or to own these views themselves?
3. What properties would you like to see included in the AppOwnedAdContainerInfo object?
4. How many SDK-owned ads or ad components do you expect to show at the same time on the screen?