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,
  bool useCustomClick = false,
  AdropAdChoicesPosition preferredAdChoicesPosition = AdropAdChoicesPosition.topRight,
  AdropNativeListener? listener,
})

Parameters

Parameter	Type	Required	Description
`unitId`	`String`	Y	Unit ID created in Ad Control Console
`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
`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
`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();
  }

  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. 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;
  });
}

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,
    ),
  );
}

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

​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

​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

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

Next Steps