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
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
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.
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
The following attestations will be available to the SDK to get stronger guarantees about ad presentation:
- Device integrity attestation: Use platform APIs like Key Attestation to determine device integrity.
- APK identity: Use SdkSandbox APIs like
SdkSandboxController.getClientPackageNameand PackageManager APIs like
requestChecksumto verify APK identity.
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.
MotionEventscan be converted to
VerifiedMotionEventsusing system APIs. The SDK can show their own UI in response to user interaction if they choose.
We invite feedback on the following points:
- Is it preferable for the SDK to generate
VerifiedMotionEventsthemselves, or for the provider UI library to do so for the SDK?
- Is it preferable for the SDK to let the publisher own views containing video, or to own these views themselves?
- What properties would you like to see included in the
- How many SDK-owned ads or ad components do you expect to show at the same time on the screen?