Native Ads - Ad Control Help Center

Overview

Native ads are customizable ads that blend naturally with your app’s content. You can configure the ad to match your app’s UI using AdropNativeAd and AdropNativeAdView.

Key Features

Customizable layout to match app design
Provides various elements like headline, body, CTA button, profile, etc.
Supports image and HTML creative
Custom click handling support
Backfill ad support

Use the test unit ID in development: PUBLIC_TEST_UNIT_ID_NATIVE

AdropNativeAd

Constructor

AdropNativeAd({
  required String unitId,
  String? contextId,
  bool useCustomClick = false,
  AdropAdChoicesPosition preferredAdChoicesPosition = AdropAdChoicesPosition.topRight,
  AdropNativeListener? listener,
})

Parameters

Parameter	Type	Required	Description
`unitId`	`String`	Y	Unit ID created in Ad Control Console
`contextId`	`String`	N	Context ID for contextual targeting (1.17.0+)
`useCustomClick`	`bool`	N	Whether to use custom click handling (default: `false`)
`preferredAdChoicesPosition`	`AdropAdChoicesPosition`	N	AdChoices badge position for backfill native ads (default: `AdropAdChoicesPosition.topRight`)
`listener`	`AdropNativeListener`	N	Ad event listener

Properties

Property	Type	Description
`isLoaded`	`bool`	Whether the ad has finished loading
`unitId`	`String`	Ad unit ID
`contextId`	`String?`	Context ID passed to the constructor
`creativeId`	`String`	Creative ID
`txId`	`String`	Transaction ID
`campaignId`	`String`	Campaign ID
`destinationURL`	`String`	Destination URL
`properties`	`AdropNativeProperties`	Native ad properties
`creativeSize`	`CreativeSize`	Creative size
`isBackfilled`	`bool`	Whether it’s a backfill ad
`browserTarget`	`BrowserTarget?`	Browser target (external or internal)

Methods

Method	Return Type	Description
`load()`	`Future<void>`	Loads the ad
`dispose()`	`Future<void>`	Releases the underlying native WebView and, for backfill ads, the AdMob native ad

Call dispose() when the native ad is no longer displayed. Failing to dispose leaks the native WebView and can lead to OOM in feed-style screens.

A disposed AdropNativeAd cannot be reused. To request another ad, create a new AdropNativeAd instance.

@override
void dispose() {
  _nativeAd?.dispose();
  super.dispose();
}

AdropNativeAdView

A widget that displays native ads on screen.

Constructor

AdropNativeAdView({
  required AdropNativeAd? ad,
  required Widget child,
})

Parameters

Parameter	Type	Required	Description
`ad`	`AdropNativeAd?`	Y	Loaded native ad object
`child`	`Widget`	Y	Child widget to display ad content

AdropNativeProperties

Content properties of the native ad.

Properties

Property	Type	Description
`headline`	`String?`	Ad headline
`body`	`String?`	Ad body text
`creative`	`String?`	HTML creative content
`asset`	`String?`	Image asset URL
`destinationURL`	`String?`	URL to navigate on click
`callToAction`	`String?`	CTA button text
`profile`	`AdropNativeProfile?`	Advertiser profile information
`extra`	`Map<String, String>`	Additional custom fields
`extraAssets`	`Map<String, AdropNativeAsset>`	Media items keyed by media ID. See Multi-Media Creatives
`isBackfilled`	`bool`	Whether it’s a backfill ad

AdropNativeProfile

Property	Type	Description
`displayName`	`String?`	Advertiser name
`displayLogo`	`String?`	Advertiser logo image URL

Basic Usage

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class NativeAdExample extends StatefulWidget {
  const NativeAdExample({super.key});

  @override
  State<NativeAdExample> createState() => _NativeAdExampleState();
}

class _NativeAdExampleState extends State<NativeAdExample> {
  bool isLoaded = false;
  AdropNativeAd? nativeAd;

  @override
  void initState() {
    super.initState();
    _createNativeAd();
  }

  @override
  void dispose() {
    nativeAd?.dispose();
    nativeAd = null;
    super.dispose();
  }

  void _createNativeAd() {
    nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          debugPrint('Native ad received successfully: ${ad.creativeId}');
          setState(() {
            isLoaded = true;
          });
        },
        onAdClicked: (ad) {
          debugPrint('Native ad clicked: ${ad.creativeId}');
        },
        onAdImpression: (ad) {
          debugPrint('Native ad impression: ${ad.creativeId}');
        },
        onAdFailedToReceive: (ad, errorCode) {
          debugPrint('Native ad failed to receive: $errorCode');
          setState(() {
            isLoaded = false;
          });
        },
      ),
    );

    // Load ad
    nativeAd?.load();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Native Ad Example')),
      body: SingleChildScrollView(
        child: Column(
          children: [
            // Main content
            const Padding(
              padding: EdgeInsets.all(16),
              child: Text('Main Content'),
            ),
            // Native ad
            if (isLoaded) _buildNativeAdView(),
          ],
        ),
      ),
    );
  }

  Widget _buildNativeAdView() {
    return AdropNativeAdView(
      ad: nativeAd,
      child: Container(
        padding: const EdgeInsets.all(16),
        margin: const EdgeInsets.all(16),
        decoration: BoxDecoration(
          border: Border.all(color: Colors.grey),
          borderRadius: BorderRadius.circular(8),
        ),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // Advertiser profile
            if (nativeAd?.properties.profile != null)
              Row(
                children: [
                  if (nativeAd?.properties.profile?.displayLogo != null)
                    Image.network(
                      nativeAd!.properties.profile!.displayLogo!,
                      width: 24,
                      height: 24,
                    ),
                  const SizedBox(width: 8),
                  Text(nativeAd?.properties.profile?.displayName ?? ''),
                ],
              ),
            const SizedBox(height: 8),
            // Headline
            if (nativeAd?.properties.headline != null)
              Text(
                nativeAd!.properties.headline!,
                style: const TextStyle(
                  fontSize: 18,
                  fontWeight: FontWeight.bold,
                ),
              ),
            const SizedBox(height: 4),
            // Body
            if (nativeAd?.properties.body != null)
              Text(nativeAd!.properties.body!),
            const SizedBox(height: 8),
            // Image asset
            if (nativeAd?.properties.asset != null)
              Image.network(
                nativeAd!.properties.asset!,
                width: double.infinity,
                fit: BoxFit.cover,
              ),
            const SizedBox(height: 8),
            // CTA button
            if (nativeAd?.properties.callToAction != null)
              ElevatedButton(
                onPressed: () {},
                child: Text(nativeAd!.properties.callToAction!),
              ),
          ],
        ),
      ),
    );
  }
}

AdropNativeListener

Listener to handle native ad events.

Callbacks

AdropNativeListener(
  onAdReceived: (AdropNativeAd ad) {
    // Ad received successfully
  },
  onAdClicked: (AdropNativeAd ad) {
    // Ad clicked
  },
  onAdImpression: (AdropNativeAd ad) {
    // Ad impression
  },
  onAdFailedToReceive: (AdropNativeAd ad, AdropErrorCode errorCode) {
    // Ad failed to receive
  },
  onAdVideoStart: (AdropNativeAd ad) {
    // Video ad started playing
  },
  onAdVideoEnd: (AdropNativeAd ad) {
    // Video ad finished playing
  },
)

Callback Descriptions

Callback	Description
`onAdReceived`	Called when ad is received successfully
`onAdClicked`	Called when ad is clicked
`onAdImpression`	Called when ad impression occurs
`onAdFailedToReceive`	Called when ad fails to receive
`onAdVideoStart`	Called when video ad starts playing
`onAdVideoEnd`	Called when video ad finishes playing

Custom Click Handling

Use useCustomClick when video creative or custom click behavior is needed.

nativeAd = AdropNativeAd(
  unitId: 'YOUR_UNIT_ID',
  useCustomClick: true, // Enable custom click
  listener: AdropNativeListener(
    onAdReceived: (ad) {
      setState(() {
        isLoaded = true;
      });
    },
    onAdClicked: (ad) {
      // Handle custom click action
      debugPrint('Ad clicked: ${ad.destinationURL}');
    },
  ),
);

When useCustomClick is true, child widget click events are handled as ad clicks.

Displaying HTML Creative

If the native ad includes HTML creative, you can display it using WebView.

For video native creatives, you must render properties.creative (the HTML payload) through a WebView. Passing properties.asset directly into video_player or any other custom player bypasses the SDK’s video tracking pipeline, so VTR is not measured and onAdVideoStart / onAdVideoEnd never fire. See Video Tracking and VTR.

import 'package:webview_flutter/webview_flutter.dart';

class NativeWithWebView extends StatefulWidget {
  const NativeWithWebView({super.key});

  @override
  State<NativeWithWebView> createState() => _NativeWithWebViewState();
}

class _NativeWithWebViewState extends State<NativeWithWebView> {
  bool isLoaded = false;
  AdropNativeAd? nativeAd;
  late final WebViewController webViewController;

  @override
  void initState() {
    super.initState();

    // Initialize WebView controller
    webViewController = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted);

    _createNativeAd();
  }

  void _createNativeAd() {
    nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      useCustomClick: true,
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          // Load HTML creative
          if (ad.properties.creative != null) {
            webViewController.loadHtmlString(ad.properties.creative!);
          }
          setState(() {
            isLoaded = true;
          });
        },
      ),
    );

    nativeAd?.load();
  }

  @override
  Widget build(BuildContext context) {
    if (!isLoaded) return const SizedBox.shrink();

    return AdropNativeAdView(
      ad: nativeAd,
      child: Container(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // Profile
            Row(
              children: [
                if (nativeAd?.properties.profile?.displayLogo != null)
                  Image.network(
                    nativeAd!.properties.profile!.displayLogo!,
                    width: 24,
                    height: 24,
                  ),
                const SizedBox(width: 8),
                Text(nativeAd?.properties.profile?.displayName ?? ''),
              ],
            ),
            const SizedBox(height: 8),
            // Headline
            if (nativeAd?.properties.headline != null)
              Text(
                nativeAd!.properties.headline!,
                style: const TextStyle(
                  fontSize: 18,
                  fontWeight: FontWeight.bold,
                ),
              ),
            const SizedBox(height: 8),
            // HTML creative
            SizedBox(
              width: MediaQuery.of(context).size.width,
              height: 300,
              child: WebViewWidget(controller: webViewController),
            ),
            // CTA button
            if (nativeAd?.properties.callToAction != null)
              Padding(
                padding: const EdgeInsets.only(top: 8),
                child: ElevatedButton(
                  onPressed: () {},
                  child: Text(nativeAd!.properties.callToAction!),
                ),
              ),
          ],
        ),
      ),
    );
  }
}

To use HTML creative, you need to add the webview_flutter package.

flutter pub add webview_flutter

Handling Backfill Ads

You can check and handle backfill ads using the isBackfilled property.

Widget _buildCreativeView() {
  if (nativeAd?.isBackfilled == true) {
    // Backfill ad: Use image asset
    return Image.network(
      nativeAd?.properties.asset ?? '',
      width: double.infinity,
      fit: BoxFit.cover,
      loadingBuilder: (context, child, loadingProgress) {
        if (loadingProgress == null) return child;
        return const Center(child: CircularProgressIndicator());
      },
      errorBuilder: (context, error, stackTrace) {
        return const Icon(Icons.error);
      },
    );
  } else if (nativeAd?.properties.creative != null) {
    // Regular ad: Use HTML creative
    return SizedBox(
      width: double.infinity,
      height: 300,
      child: WebViewWidget(controller: webViewController),
    );
  } else {
    return const SizedBox.shrink();
  }
}

AdChoices Position

For backfill native ads, you can choose which corner displays the AdChoices badge. Set preferredAdChoicesPosition in the AdropNativeAd constructor.

final nativeAd = AdropNativeAd(
  unitId: 'YOUR_UNIT_ID',
  preferredAdChoicesPosition: AdropAdChoicesPosition.bottomRight,
  listener: AdropNativeListener(
    onAdReceived: (ad) => debugPrint('Received'),
    onAdFailedToReceive: (ad, errorCode) => debugPrint('Failed: $errorCode'),
  ),
);

await nativeAd.load();

Value	Description
`AdropAdChoicesPosition.topLeft`	Top-left corner
`AdropAdChoicesPosition.topRight`	Top-right corner (default)
`AdropAdChoicesPosition.bottomLeft`	Bottom-left corner
`AdropAdChoicesPosition.bottomRight`	Bottom-right corner

This setting is a preferred hint for the backfill network and applies only to backfill native ads — direct ads are not affected. The backfill network may override the position depending on its policy.

Video Tracking and VTR

Adrop measures video metrics for native creatives — including impression-to-completion (VTR), onAdVideoStart, and onAdVideoEnd — only when the video is rendered through the SDK’s media surface. On Flutter, that means rendering the HTML creative (properties.creative) inside a WebView, as shown in Displaying HTML Creative. This applies to the ad’s main media (Media 1). For the other media items of a multi-media creative, see Multi-Media Creatives. The properties.asset field returns a URL pointing to the underlying image or video file. It is exposed as supplementary metadata (for example, for thumbnails or your own analytics); it is not intended to drive playback.

Do not feed the properties.asset URL into a custom video player (video_player, chewie, or any third-party player) for a video native ad. When the SDK’s media surface is bypassed:

VTR (Video Through Rate) is not collected for that placement.
onAdVideoStart / onAdVideoEnd callbacks never fire.
Aggregate video performance for the unit will under-report or report zero.

Click (onAdClicked) and impression (onAdImpression) tracking still work because they are wired to AdropNativeAdView, but the video-specific signals are lost.

Recommended pattern

For video creatives, follow the WebView + HTML creative pattern:

if (ad.properties.creative != null) {
  webViewController.loadHtmlString(ad.properties.creative!);
}

Bind the WebView inside AdropNativeAdView so that click and impression tracking stay attached to the ad container.

If a placement absolutely requires a custom player and you accept that VTR will not be measured, you can still surface click and impression attribution by keeping the ad bound to AdropNativeAdView. In that case, treat the placement as non-VTR inventory in your internal reporting and avoid mixing it with SDK-measured video performance.

Using Extra Fields

Additional fields defined by publishers can be accessed from the extra map.

onAdReceived: (ad) {
  // Access extra fields
  final customField = ad.properties.extra['customFieldKey'];
  if (customField != null) {
    debugPrint('Custom field: $customField');
  }

  setState(() {
    isLoaded = true;
  });
}

Multi-Media Creatives

Requires adrop_ads_flutter 1.16.0 or later. If you use backfill, update the backfill module to 1.16.0 as well.

If a native unit has two or more media items, its creatives contain a file for each media item. properties.extraAssets holds every media item of the ad, keyed by the media ID set in the console. Media 1 is always m1, and the other media items use the IDs shown in Media Size on the Ad Unit detail screen, such as m2 and m3.

final media2 = ad.properties.extraAssets['m2']; // AdropNativeAsset?

Media 1 (m1) is the same media as properties.asset and properties.creative. Keep displaying it as before, and draw only the other media items yourself.
extraAssets is empty for creatives of units with a single media item and for backfill ads. Display those ads as usual.
Look up media items by ID instead of relying on their order.
If the ad is served in dark mode, image media items are dark mode images too.
To check your layout with a multi-media creative, preview the creative on a test device.

AdropNativeAsset

Property	Type	Description
`id`	`String`	Media ID set in the console (e.g., `m1`, `m2`)
`asset`	`String`	Image or video file URL
`creative`	`String`	HTML that plays a video media item, including its tracking
`cover`	`String?`	Poster image URL of a video. `null` for images
`type`	`String?`	`'display'` (image) or `'video'`
`isVideo`	`bool`	Whether the media item is a video

Displaying Media Items

Media	Display	Placement
Image	Show `asset` with `Image.network`	Inside `AdropNativeAdView`
Video	Load `creative` into a `WebViewWidget`	Outside `AdropNativeAdView`, e.g., right below it

Image: With either useCustomClick setting, a tap on a widget inside AdropNativeAdView is an ad click, so a tap on an image you place there is counted like the rest of the ad. Don’t load the creative HTML of an image: it doesn’t report clicks to Adrop.
Video: Play the creative HTML, not the asset URL. The HTML contains the video player and its tracking, so video metrics are measured only through it. Place the WebViewWidget outside AdropNativeAdView: inside, every tap, including taps on the player’s controls, becomes an ad click. Load the HTML when the ad is about to appear on screen, not in advance.
Landing page: When a user taps the video, its HTML reports the click and asks to open the landing page in a new window or in the same window. Both requests arrive in onNavigationRequest, so open the requested URL there.

Impressions and Clicks

Impressions, clicks, and video metrics are counted once per ad, not per media item, even when both the SDK and a media item report them.

Event	How it’s counted
Impression	When `AdropNativeAdView` stays at least 50% visible for 0.5 seconds. A video media item also reports the ad’s impression when its video starts playing.
Click inside `AdropNativeAdView`	Counted by the SDK, and `onAdClicked` is called.
Tap on a video media item	Reported by the media item’s HTML. `onAdClicked` isn’t called.
Video playback (Valid Views, Completed Views)	Reported by the media item’s HTML. `onAdVideoStart` and `onAdVideoEnd` aren’t called.

Which taps on a video count as clicks depends on the unit’s video controller setting. With the controller off, every tap on the video is a click. With it on, taps on the play and mute controls aren’t clicks.

Example

This example shows Media 2 (m2) as an image inside AdropNativeAdView, or as a video right below it. Replace m2 with the ID of your unit’s media item. Add the WebView and URL launcher packages first.

flutter pub add webview_flutter webview_flutter_android webview_flutter_wkwebview url_launcher

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
import 'package:flutter/material.dart';
import 'package:url_launcher/url_launcher.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_android/webview_flutter_android.dart';
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';

class MultiMediaNativeAd extends StatefulWidget {
  const MultiMediaNativeAd({super.key});

  @override
  State<MultiMediaNativeAd> createState() => _MultiMediaNativeAdState();
}

class _MultiMediaNativeAdState extends State<MultiMediaNativeAd> {
  AdropNativeAd? _nativeAd;
  WebViewController? _creativeController;
  AdropNativeAsset? _media2;
  WebViewController? _media2VideoController;

  @override
  void initState() {
    super.initState();
    _nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          final properties = ad.properties;
          // Media 2 (m2). Not in the map for single-media creatives and backfill ads
          final media2 = properties.extraAssets['m2'];
          setState(() {
            // Media 1 (m1) is the existing creative
            _creativeController = _webViewController(properties.creative ?? '');
            _media2 = media2;
            _media2VideoController = media2 != null && media2.isVideo
                ? _webViewController(media2.creative, opensLanding: true)
                : null;
          });
        },
      ),
    );
    _nativeAd?.load();
  }

  WebViewController _webViewController(String html, {bool opensLanding = false}) {
    final PlatformWebViewControllerCreationParams params =
        WebViewPlatform.instance is WebKitWebViewPlatform
            ? WebKitWebViewControllerCreationParams(
                allowsInlineMediaPlayback: true,
                mediaTypesRequiringUserAction: const <PlaybackMediaTypes>{},
              )
            : const PlatformWebViewControllerCreationParams();
    final controller = WebViewController.fromPlatformCreationParams(params)
      ..setJavaScriptMode(JavaScriptMode.unrestricted);
    if (opensLanding) {
      controller.setNavigationDelegate(NavigationDelegate(
        onNavigationRequest: (request) {
          // The HTML itself (about:blank) loads as usual
          if (!request.isMainFrame || request.url == 'about:blank') {
            return NavigationDecision.navigate;
          }
          // A tap on the video: the HTML has reported the click and asks to open the landing page
          launchUrl(Uri.parse(request.url), mode: LaunchMode.externalApplication);
          return NavigationDecision.prevent;
        },
      ));
    }
    final platform = controller.platform;
    if (platform is AndroidWebViewController) {
      platform.setMediaPlaybackRequiresUserGesture(false);
    }
    controller.loadHtmlString(html);
    return controller;
  }

  @override
  void dispose() {
    _nativeAd?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final ad = _nativeAd;
    final creativeController = _creativeController;
    if (ad == null || creativeController == null) return const SizedBox.shrink();

    final properties = ad.properties;
    final media2 = _media2;
    final media2VideoController = _media2VideoController;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        AdropNativeAdView(
          ad: ad,
          child: Padding(
            padding: const EdgeInsets.all(16),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(properties.headline ?? ''),
                SizedBox(
                  height: 200,
                  child: WebViewWidget(controller: creativeController),
                ),
                // Media 2 (m2) when it's an image: inside AdropNativeAdView
                if (media2 != null && !media2.isVideo)
                  Image.network(media2.asset, width: 120, height: 120),
                ElevatedButton(
                  onPressed: () {},
                  child: Text(properties.callToAction ?? ''),
                ),
              ],
            ),
          ),
        ),
        // Media 2 (m2) when it's a video: outside AdropNativeAdView
        if (media2VideoController != null)
          SizedBox(
            height: 200,
            child: WebViewWidget(controller: media2VideoController),
          ),
      ],
    );
  }
}

Error Handling

When backfill ads are configured, the backfillNoFill error code is returned when both direct ads and backfill ads are unavailable.

onAdFailedToReceive: (ad, errorCode) {
  if (errorCode == AdropErrorCode.backfillNoFill) {
    debugPrint('No backfill ads available');
  }
}

General Error Handling

class _NativeAdState extends State<NativeAdWidget> {
  bool isLoaded = false;
  AdropErrorCode? errorCode;
  AdropNativeAd? nativeAd;

  @override
  void initState() {
    super.initState();

    nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          setState(() {
            isLoaded = true;
            errorCode = null;
          });
        },
        onAdFailedToReceive: (ad, error) {
          // Handle backfill-related errors
          if (error == AdropErrorCode.backfillNoFill) {
            debugPrint('No backfill ads available');
          }

          setState(() {
            isLoaded = false;
            errorCode = error;
          });
        },
      ),
    );

    nativeAd?.load();
  }

  @override
  Widget build(BuildContext context) {
    if (isLoaded) {
      return _buildNativeAdView();
    } else if (errorCode != null) {
      return Text('Ad load failed: ${errorCode?.code}');
    } else {
      return const SizedBox.shrink();
    }
  }

  Widget _buildNativeAdView() {
    // Native ad UI composition
    return AdropNativeAdView(
      ad: nativeAd,
      child: Container(
        // ...
      ),
    );
  }
}

Best Practices

1. Recreating Ads

To load a new ad, create a new AdropNativeAd instance.

void resetAd() {
  setState(() {
    isLoaded = false;
  });

  nativeAd = AdropNativeAd(
    unitId: 'YOUR_UNIT_ID',
    listener: AdropNativeListener(
      onAdReceived: (ad) {
        setState(() {
          isLoaded = true;
        });
      },
    ),
  );

  nativeAd?.load();
}

2. Conditional Rendering

Display an appropriate placeholder until the ad loads.

Widget buildNativeAd() {
  if (isLoaded && nativeAd != null) {
    return _buildNativeAdView();
  } else if (isLoading) {
    return const SizedBox(
      height: 200,
      child: Center(child: CircularProgressIndicator()),
    );
  } else {
    return const SizedBox.shrink();
  }
}

3. Responsive Layout

Configure layout to adapt to various screen sizes.

Widget _buildNativeAdView() {
  return AdropNativeAdView(
    ad: nativeAd,
    child: LayoutBuilder(
      builder: (context, constraints) {
        return Container(
          width: constraints.maxWidth,
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              // Ad content
            ],
          ),
        );
      },
    ),
  );
}

4. Null Check for Ad Properties

Native ad properties can be null, so always check them.

Widget _buildHeadline() {
  final headline = nativeAd?.properties.headline;
  if (headline == null || headline.isEmpty) {
    return const SizedBox.shrink();
  }
  return Text(
    headline,
    style: const TextStyle(
      fontSize: 18,
      fontWeight: FontWeight.bold,
    ),
  );
}

Preloading Backfill Ads (preload)

Starting with SDK 1.17.0, you can use AdropNativeAd.preload() to preload a backfill native ad. When a native ad that you load() with the same unit ID and the same AdChoices position gets no direct ad and falls back to a backfill ad, it uses the preloaded ad right away instead of requesting a backfill ad again. load() still requests a direct ad first, regardless of preload. If a direct ad is received, the preloaded ad is kept as is. If you don’t call preload, the behavior is the same as before.

Requirements

You need adrop_ads_flutter 1.17.0 or later and, on the native platforms, the backfill dependency 1.17.0 or later. See Getting Started.
Preload fetches a backfill ad only when the server has told the app that there are no direct ads to show right now. Otherwise, it ends with ERROR_CODE_AD_PRELOAD_SKIPPED without requesting a backfill ad. This is a normal result in apps that have direct ad campaigns.
Right after the app is installed, right after you change the App Key, and right after you switch to a different user with setUID, preload ends with ERROR_CODE_AD_PRELOAD_SKIPPED until the server response arrives.
With test unit IDs, preload always ends with ERROR_CODE_AD_PRELOAD_SKIPPED.

Usage

Call preload right before you open the screen that contains the native ad. A preloaded ad is discarded after 30 minutes if it isn’t used, so call preload only for ads you’re about to display. You don’t need to wait for the result before calling load(). If the ad is still being fetched, load() waits for that result and uses it. preload() completes when preloading succeeds. Any other result (including ERROR_CODE_AD_PRELOAD_SKIPPED) is delivered as a PlatformException whose code is the error code string. If you don’t handle it, even SKIPPED, which is a normal result, is reported as an unhandled asynchronous error, so wrap the call in try/catch or attach .catchError.

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

// Call right before you open the screen that contains the native ad.
Future<void> preloadFeedNativeAd() async {
  try {
    await AdropNativeAd.preload(
      unitId: 'YOUR_UNIT_ID',
      preferredAdChoicesPosition: AdropAdChoicesPosition.topRight, // Default
    );
    debugPrint('Preload complete');
  } on PlatformException catch (e) {
    // ERROR_CODE_AD_PRELOAD_SKIPPED is a normal result.
    // Don't call preload again right away here.
    final errorCode = AdropErrorCode.getByCode(e.code);
    debugPrint('Not preloaded: ${errorCode.code}');
  }
}

If you don’t need the result, you can call it like this.

AdropNativeAd.preload(unitId: 'YOUR_UNIT_ID').catchError((_) {});

To use the preloaded ad, create the AdropNativeAd you load() with the same preferredAdChoicesPosition you passed to preload. Both default to AdropAdChoicesPosition.topRight.

final nativeAd = AdropNativeAd(
  unitId: 'YOUR_UNIT_ID',
  preferredAdChoicesPosition: AdropAdChoicesPosition.topRight, // Value passed to preload
  listener: AdropNativeListener(
    onAdReceived: (ad) => debugPrint('Received'),
    onAdFailedToReceive: (ad, errorCode) => debugPrint('Failed: $errorCode'),
  ),
);

await nativeAd.load();

When a Preloaded Ad Is Used

Same unit ID and same AdChoices position: The AdChoices position is fixed when the backfill ad is fetched, so the preferredAdChoicesPosition of the ad you load() must match the value you passed to preload. If it differs, the preloaded ad is kept as is, and load() requests a backfill ad as usual.
Used only once: A preloaded ad is gone once a single load() uses it. To preload again, call preload again.
Lifetime and count: An ad that isn’t used within 30 minutes is discarded. Only 1 ad is kept per unit and AdChoices position, and native ads keep up to 5 different combinations. When there are more than 5, ads are discarded starting with the one received first.
Calling again: Calling preload again with the same unit and AdChoices position doesn’t make a new request. If an ad has already been preloaded, the call completes without a new request; if one is still being fetched, the call gets that load’s result (success or failure). You can’t use preload to refresh an ad. However, if the user consent status has changed in the meantime, the existing ad is discarded and a new one is fetched.
Consent status changes: If the user consent status changes after an ad is preloaded, that ad isn’t used by load().
What completion means: When preload() completes, it means preloading has finished. A load() that was waiting for that result may have already used the ad.

Failure Codes

Error Code	Code String	Description
`preloadSkipped`	`ERROR_CODE_AD_PRELOAD_SKIPPED`	No backfill ad was requested because direct ads may be shown, or because that hasn’t been confirmed yet. This is a normal result, so call preload again right before you open the next screen.
`adNoFill`	`ERROR_CODE_AD_NO_FILL`	The backfill dependency (1.17.0 or later) is missing, backfill isn’t configured for the unit, or the SDK hasn’t received that configuration yet. Call preload again a little later. If the backfill dependency is missing, preload keeps ending with this code. On iOS, preload also ends with this code when the device isn’t in the target countries.
`backfillNoFill`	`ERROR_CODE_AD_BACKFILL_NO_FILL`	No backfill ad is available.
`internal`	`ERROR_CODE_INTERNAL`	The request was interrupted (for example, on Android, the Activity finished while the ad was being fetched) or an internal error occurred. Call preload again later.
`initialize`	`ERROR_CODE_INITIALIZE`	The SDK isn’t initialized. On Android, preload also ends with this code when the device isn’t in the target countries.
`invalidUnit`	`ERROR_CODE_INVALID_UNIT`	The unit ID is empty.

Don’t call preload again right away inside catch. If the result doesn’t change — for example, when the backfill dependency is missing — the calls repeat endlessly. Call it again later, such as before you open the next screen.

Next Steps

Interstitial Ads

Implement full-screen interstitial ads

Rewarded Ads

Implement rewarded ads that provide rewards

Popup Ads

Implement popup-style ads

Reference

Reference types, methods, and error codes

​Overview

​Key Features

​AdropNativeAd

​Constructor

​Properties

​Methods

​AdropNativeAdView

​Constructor

​AdropNativeProperties

​Properties

​AdropNativeProfile

​Basic Usage

​AdropNativeListener

​Callbacks

​Callback Descriptions

​Custom Click Handling

​Displaying HTML Creative

​Handling Backfill Ads

​AdChoices Position

​Video Tracking and VTR

​Recommended pattern

​Using Extra Fields

​Multi-Media Creatives

​AdropNativeAsset

​Displaying Media Items

​Impressions and Clicks

​Example

​Error Handling

​Backfill-Related Errors

​General Error Handling

​Best Practices

​1. Recreating Ads

​2. Conditional Rendering

​3. Responsive Layout

​4. Null Check for Ad Properties

​Preloading Backfill Ads (preload)

​Requirements

​Usage

​When a Preloaded Ad Is Used

​Failure Codes

​Next Steps

Interstitial Ads

Rewarded Ads

Popup Ads

Reference

Overview

Key Features

AdropNativeAd

Constructor

Properties

Methods

AdropNativeAdView

Constructor

AdropNativeProperties

Properties

AdropNativeProfile

Basic Usage

AdropNativeListener

Callbacks

Callback Descriptions

Custom Click Handling

Displaying HTML Creative

Handling Backfill Ads

AdChoices Position

Video Tracking and VTR

Recommended pattern

Using Extra Fields

Multi-Media Creatives

AdropNativeAsset

Displaying Media Items

Impressions and Clicks

Example

Error Handling

Backfill-Related Errors

General Error Handling

Best Practices

1. Recreating Ads

2. Conditional Rendering

3. Responsive Layout

4. Null Check for Ad Properties

Preloading Backfill Ads (preload)

Requirements

Usage

When a Preloaded Ad Is Used

Failure Codes

Next Steps