Native Ads

Native ads are ads that match the look, feel, and function of the media format in which they appear. Unlike banner or interstitial ads, native ads are rendered by the platform's native UI layer and positioned by binding them to a Godot Control node. The plugin keeps the native ad view in sync with the control's position, size, and visibility every frame.

Loading and Displaying

Load a native ad with load_native_ad(), wait for the native_ad_loaded signal, then call show_native_ad() and attach the ad to a Control node so the plugin knows where to render it.

func _ready() -> void:
    $Admob.native_ad_loaded.connect(_on_native_ad_loaded)
    $Admob.native_ad_failed_to_load.connect(_on_native_ad_failed_to_load)
    $Admob.load_native_ad()

func _on_native_ad_loaded(ad_info: AdInfo, _response_info: ResponseInfo) -> void:
    $Admob.show_native_ad(ad_info.get_ad_id())
    $Admob.attach_native_ad_to_control(ad_info.get_ad_id(), $NativeAdContainer)

func _on_native_ad_failed_to_load(ad_info: AdInfo, error_data: LoadAdError) -> void:
    print("Native ad failed to load: ", error_data)

Control Binding

Native ads are positioned by attaching them to a Control node. The plugin maps the control's canvas rect to window coordinates each frame, accounting for viewport scaling, and calls the platform's update_native_ad_layout accordingly.

• attach_native_ad_to_control(ad_id: String, control: Control) — Binds the native ad view to a control. If the ad was already attached to another control, it is re-attached.
• detach_native_ad(ad_id: String) — Removes the binding. The ad view will stop updating its position. Called automatically by remove_native_ad().

Showing and Hiding

Use show_native_ad() and hide_native_ad() to toggle the visibility of a loaded native ad without unloading it. Both methods accept an optional ad_id; if omitted, the most recently loaded ad is used.

# Show the most recently loaded native ad
$Admob.show_native_ad()

# Hide a specific native ad
$Admob.hide_native_ad(ad_info.get_ad_id())

Removing

Call remove_native_ad() to unload a native ad and free its resources. This also automatically detaches the ad from its bound control.

$Admob.remove_native_ad(ad_info.get_ad_id())

The max_native_ad_cache property (default 10) controls how many native ads can be held in the cache before older ones are evicted.

Native Ad Options

Native ad behaviour can be customised via LoadAdRequest before calling load_native_ad(). These options are ignored for other ad types.

var request: LoadAdRequest = $Admob.create_native_ad_request()
request.set_native_media_aspect_ratio(LoadAdRequest.NativeMediaAspectRatio.LANDSCAPE)
request.set_native_ad_choices_placement(LoadAdRequest.NativeAdChoicesPlacement.TOP_RIGHT)
request.set_native_image_scale_type(LoadAdRequest.NativeImageScaleType.CENTER_CROP)
$Admob.load_native_ad(request)

Media Aspect Ratio

Controls which aspect ratios the SDK should prefer when requesting native ad media (NativeMediaAspectRatio enum):

AdChoices Placement

Controls where the AdChoices icon appears within the native ad view (NativeAdChoicesPlacement enum):

Image Scale Type

Controls how icon and image assets are scaled inside their native ImageView (NativeImageScaleType enum). Only applies on Android.

Other Options

• set_native_return_urls_for_image_assets(true) — The SDK returns image asset URLs instead of pre-fetched drawables, letting you download and manage images yourself.
• set_native_request_multiple_images(true) — The SDK may return multiple images for a single asset slot. By default only one image per slot is returned.
• set_native_disable_validator(true) — Suppresses SDK validator warnings about missing view bindings. Useful in test or custom-layout scenarios.

Signals

Demo Ad Unit IDs

Use the following demo IDs during development. They are set as defaults on the Admob node when is_real is false.