t1k:unity:mobile:native-overlay-ads
| Field | Value |
|---|---|
| Module | mobile |
| Version | 3.65.6 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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.nativeoverlaypackage 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.3rdis a submodule — PR upstream, never patch in place, perreproducible-on-every-machine-unity.md); ad unit IDs / secrets; the conventional interstitial, banner, MREC and rewarded paths (seet1k:unity:mobile:3rd-integrate).
When to Use
Section titled “When to Use”- “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
The one-paragraph model
Section titled “The one-paragraph model”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.
Ownership map
Section titled “Ownership map”| Piece | Path |
|---|---|
| Android sources + Gradle injector | Packages/com.theone.nativeoverlay/ (own repo: The1Studio/TheOne.NativeOverlay) |
| Service contract + close-chrome seam | Packages/com.gdk.3rd/Ads/Base/NativeOverlay/ |
| AdMob implementation | Packages/com.gdk.3rd/Ads/Admob/AdmobNativeOverlayService.cs |
| Format enum | Packages/com.gdk.3rd/Contracts/AdsServices/NativeOverlayAdFormat.cs |
| Style / sizing config | Packages/com.gdk.3rd/Configs/Ads/NativeOverlayStyleConfig.cs |
| Enable toggle + ad unit IDs | Packages/com.gdk.3rd/Configs/Ads/AdMobSettings.cs |
| Runtime flags (remote config) | Packages/com.gdk.3rd/Configs/Ads/AdServicesConfig.cs |
| Full-screen driver | Assets/UITemplate/.../NativeAds/NativeFullScreenAdController.cs |
| Collapse driver | Assets/UITemplate/.../NativeAds/NativeCollapseAdController.cs |
| MREC driver | Assets/UITemplate/.../NativeAds/NativeMrecAdController.cs |
| Routing / gating / warm-up | Assets/UITemplate/.../Ads/UITemplateAdServiceWrapper.cs |
| DI | Packages/com.gdk.3rd/DI/Ads/Core/AdServiceVContainer.cs, DI/Ads/Admob/AdmobVContainer.cs, Assets/UITemplate/.../UITemplateThirdPartyVContainer.cs |
Enable it
Section titled “Enable it”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.
It is skipped, not broken
Section titled “It is skipped, not broken”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.
The five formats
Section titled “The five formats”| Format | Enum | Countdown | Close glyph | Lifetime |
|---|---|---|---|---|
| App-open substitute | AppOpen | native_overlay_aoa_countdown (3s) | cross | one impression, destroyed on dismiss |
| Interstitial substitute | Interstitial | native_overlay_inter_countdown (5s) | cross | one impression, destroyed on dismiss |
| End card | EndCard | 0 (immediate) | cross | one impression, destroyed on dismiss |
| Collapse band | Collapse | native_overlay_collapse_close_time | chevron down | resident, destroyed after N shows |
| Bottom MREC | Mrec | none | none | resident; 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.
Two hard invariants
Section titled “Two hard invariants”- 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’sonDisplayedcallback for exactly this reason — showing awaits the load, so arming early would float a countdown over a screen with no ad on it. - One chrome surface, globally. A second
Showreplaces the first’s views and anyHidetakes 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.
Do not
Section titled “Do not”- Patch
com.gdk.3rdorcom.theone.nativeoverlayin 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/heightorScreen.dpiin sizing code — both are wrong here, for different reasons. Seereferences/architecture.md§ Sizing. - Trust an editor test. The Java helper only exists in a generated Gradle project.
References
Section titled “References”| File | Contents |
|---|---|
references/setup.md | New-game checklist, enablement, package resolution and the stale-version trap, ad unit IDs, the full remote-config key table, verification checklist |
references/architecture.md | The Mono/Java seam, Gradle injection, the template override, sizing and dp-vs-px, close-chrome protocol |
references/formats.md | Per-format lifecycle, gating, warm-up, analytics signals, call sites |
references/hard-rules.md | Silent-failure catalogue, diagnosis order, the traps and why each exists |