Skip to content

t1k:unity:mobile:native-overlay-ads

FieldValue
Modulemobile
Version3.65.6
Effortmedium
Tools—

Keywords: addContentView, admob native, AdmobNativeOverlayService, close chrome, collapse ad, end card, full-bleed, gnt_medium_template_view, gnt_small_template_view, IPostGenerateGradleAndroidProject, mrec overlay, mrec reload, native ad, native full-screen, native mrec, native overlay, native_overlay_mrec_reload_on_click, native-overlay, NativeFullScreenCloseChrome, NativeMrecAdController, nativeoverlay, NativeOverlayAdFormat, reload on click, ReloadNativeMrec, unityLibrary

/t1k:unity:mobile:native-overlay-ads
[setup|debug|format <aoa|inter|endcard|collapse>]

T1K — Native Overlay Ads (Unity / Android)

Section titled “T1K — Native Overlay Ads (Unity / Android)”

An AdMob native ad rendered at full-screen or half-screen size and used as a substitute for a conventional format. Five uses: app-open substitute, interstitial substitute, end card after an interstitial or rewarded ad, a resident half-screen band at the bottom of the screen, and a resident MREC stacked on the banner slot.

Android only, in a built player. Never in the editor, never on iOS — see § “It is skipped, not broken”.

  • In scope: enabling the format, the com.theone.nativeoverlay package and its Gradle-time injection, the platform close chrome, per-format lifecycles and gating, sizing, analytics signals, and diagnosing a format that silently never appears.
  • Out of scope: writing AdMob adapter code (com.gdk.3rd is a submodule — PR upstream, never patch in place, per reproducible-on-every-machine-unity.md); ad unit IDs / secrets; the conventional interstitial, banner, MREC and rewarded paths (see t1k:unity:mobile:3rd-integrate).
  • “enable / set up native overlay”, “turn on the collapse ad”, “native full-screen ad”
  • “the native overlay never shows”, “no close button on the ad”, “the ad can’t be dismissed”
  • “the ad is letterboxed / the Open button is huge / the media is the wrong size”
  • touching AdmobNativeOverlayService, either controller, or the Java close chrome

A native overlay is attached with Android’s Activity.addContentView, so it sits above the Unity view in the same window and eats every touch inside its bounds. That single fact drives the whole design: a Unity-canvas close button under it is invisible and untappable, so the countdown and close button must be Android views added after the ad; the game’s own uGUI input must be turned off for the ad’s duration; and a format with no platform chrome available is not degraded, it is skipped, because an undismissable full-screen ad is worse than no ad.

PiecePath
Android sources + Gradle injectorPackages/com.theone.nativeoverlay/ (own repo: The1Studio/TheOne.NativeOverlay)
Service contract + close-chrome seamPackages/com.gdk.3rd/Ads/Base/NativeOverlay/
AdMob implementationPackages/com.gdk.3rd/Ads/Admob/AdmobNativeOverlayService.cs
Format enumPackages/com.gdk.3rd/Contracts/AdsServices/NativeOverlayAdFormat.cs
Style / sizing configPackages/com.gdk.3rd/Configs/Ads/NativeOverlayStyleConfig.cs
Enable toggle + ad unit IDsPackages/com.gdk.3rd/Configs/Ads/AdMobSettings.cs
Runtime flags (remote config)Packages/com.gdk.3rd/Configs/Ads/AdServicesConfig.cs
Full-screen driverAssets/UITemplate/.../NativeAds/NativeFullScreenAdController.cs
Collapse driverAssets/UITemplate/.../NativeAds/NativeCollapseAdController.cs
MREC driverAssets/UITemplate/.../NativeAds/NativeMrecAdController.cs
Routing / gating / warm-upAssets/UITemplate/.../Ads/UITemplateAdServiceWrapper.cs
DIPackages/com.gdk.3rd/DI/Ads/Core/AdServiceVContainer.cs, DI/Ads/Admob/AdmobVContainer.cs, Assets/UITemplate/.../UITemplateThirdPartyVContainer.cs

Tick Enable Native Overlay on the AdMob settings asset. That checkbox is not a flag — its OnValueChanged handler writes com.theone.nativeoverlay into Packages/manifest.json and calls Client.Resolve() itself. Unticking removes it.

Do not force a Unity refresh afterwards. Client.Resolve() is the package resolve, and the manifest write triggers its own domain reload; t1k unity refresh is asset-import + compile, a different mechanism, and issuing one on top of an in-flight resolve is the editor-crash case in ai-velocity-batch-compile-unity.md.

The version it writes is a constant that trails the published package, and it never upgrades an entry that already exists — correct the pin by hand afterwards (references/setup.md § 2).

Then: ad unit IDs on the same asset, remote-config flags for the formats you want, and an Android build to test on. Set DefaultNativeOverlayAdId (Inspector: Native Overlay) unconditionally, even when every format you ship today has its own unit: a format enabled later from remote config falls back to it instead of loading an empty unit (references/setup.md § 3). A game integrating the formats for the first time should work the new-game checklist in references/setup.md § 0, which is the whole sequence in nine rows.

The single most common report is “native overlay does nothing”, and the ordinary cause is that it was correctly skipped. AndroidNativeOverlayCloseChrome.IsSupported is false whenever com.x.nativeoverlay.NativeFullScreenCloseChrome is not on the classpath — which is always true in the editor, on iOS, and in any build whose Gradle project was generated without the injector. Both controllers gate on it and log an Info line rather than failing.

There is no compile error and no crash for a missing package. Diagnose from references/hard-rules.md § “Nothing appears” before assuming a bug.

FormatEnumCountdownClose glyphLifetime
App-open substituteAppOpennative_overlay_aoa_countdown (3s)crossone impression, destroyed on dismiss
Interstitial substituteInterstitialnative_overlay_inter_countdown (5s)crossone impression, destroyed on dismiss
End cardEndCard0 (immediate)crossone impression, destroyed on dismiss
Collapse bandCollapsenative_overlay_collapse_close_timechevron downresident, destroyed after N shows
Bottom MRECMrecnonenoneresident; fresh creative every native_overlay_mrec_refresh_seconds, after a click (on return), or on ReloadNativeMrec()

Format selects the ad unit; placement stays an analytics label. Neither derives from the other, so both are passed on every call. Per-format lifecycles, gating and signals: references/formats.md.

  1. Ad first, chrome second. Z-order in the activity’s content view is insertion order. Chrome added before the ad ends up underneath it and untappable. The collapse arms its chrome from ShowAd’s onDisplayed callback for exactly this reason — showing awaits the load, so arming early would float a countdown over a screen with no ad on it.
  2. One chrome surface, globally. A second Show replaces the first’s views and any Hide takes down whatever is up. A collapse left standing while a full-screen ad shows would lose its close button. The wrapper suspends the collapse for the full-screen ad’s duration and restores it after.
  • Patch com.gdk.3rd or com.theone.nativeoverlay in place — both are separately-versioned packages. Fix upstream and bump the pointer (reproducible-on-every-machine-unity.md).
  • Add a second close affordance. The chrome is one shared surface by design.
  • Reach for Screen.width/height or Screen.dpi in sizing code — both are wrong here, for different reasons. See references/architecture.md § Sizing.
  • Trust an editor test. The Java helper only exists in a generated Gradle project.
FileContents
references/setup.mdNew-game checklist, enablement, package resolution and the stale-version trap, ad unit IDs, the full remote-config key table, verification checklist
references/architecture.mdThe Mono/Java seam, Gradle injection, the template override, sizing and dp-vs-px, close-chrome protocol
references/formats.mdPer-format lifecycle, gating, warm-up, analytics signals, call sites
references/hard-rules.mdSilent-failure catalogue, diagnosis order, the traps and why each exists