Native Ads

Implementation Methods

Native ads allow you to display ads with custom UI that matches your app’s design.

Method	Description	Recommended
Default Template	Use SDK-provided template	Quick implementation
Custom UI	Build your own UI	When design customization is needed

Use the test unit ID in development: PUBLIC_TEST_UNIT_ID_NATIVE

Default Template

You can use the default template in the same way as banner ads. Images and text are automatically rendered in the SDK-provided template.

<div data-adrop-unit="YOUR_NATIVE_UNIT_ID"></div>

The default template does not support advertiser profile sections. Use custom UI to display advertiser profiles.

Custom UI

Data Attributes Method

Add the data-adrop-render="custom" attribute and bind fields using data-adrop-native attributes on inner elements.

<div
  data-adrop-unit="YOUR_NATIVE_UNIT_ID"
  data-adrop-render="custom"
  data-adrop-entire-click="true"
  data-adrop-custom-click="true"
  class="native-ad">

  <!-- Advertiser Profile -->
  <div class="ad-profile">
    <img data-adrop-native="profile.displayLogo" alt="Advertiser">
    <span data-adrop-native="profile.displayName"></span>
  </div>

  <!-- Ad Content -->
  <h3 data-adrop-native="headline"></h3>
  <img data-adrop-native="asset" alt="Ad">
  <p data-adrop-native="body"></p>

  <!-- Extra text items -->
  <span data-adrop-native="extra.price"></span>

  <!-- CTA Button -->
  <button data-adrop-native="callToAction"></button>
</div>

Data Attributes

string

required

Unit ID created in Ad Control Console

string

required

Set to custom for custom UI

string

Context ID for contextual targeting

string

default:"light"

Theme setting (light or dark)

boolean

default:false

Enable entire area click

false: Only text/images are clickable, clicking advertiser profile goes to profile link
true: Entire container is clickable, all clicks go to ad destination

boolean

default:false

Enable custom click handling - When true, SDK will not automatically navigate to the destination URL on click, only emit adClicked event. Allows developers to implement custom click behavior.

string

Advertising identifier — required for the View on Device feature to preview a draft creative on a registered test device. Do not hard-code in production.

renderAd Method

Use this when you want direct control over ad loading timing.

<div id="native-ad-container" class="native-ad">
  <div class="ad-profile">
    <img data-adrop-native="profile.displayLogo" alt="Advertiser">
    <span data-adrop-native="profile.displayName"></span>
  </div>
  <h3 data-adrop-native="headline"></h3>
  <img data-adrop-native="asset" alt="Ad">
  <p data-adrop-native="body"></p>
  <button data-adrop-native="callToAction"></button>
</div>

<script>
  const container = document.getElementById('native-ad-container');
  const adrop = Adrop.instance();

  adrop.renderAd(container, {
    unit: 'YOUR_NATIVE_UNIT_ID',
    contextId: 'YOUR_CONTEXT_ID',
    theme: 'light',
    trackMode: 1,        // Required for custom UI
    isEntireClick: true, // Enable entire area click
    useCustomClick: true // Enable custom click handling
  });
</script>

renderAd Options

string

required

Unit ID created in Ad Control Console

string

User identifier (used to override SDK-level setting for individual placements)

string

Context ID for contextual targeting

number

required

Set to 1 for custom UI

boolean

default:false

Enable entire area click

string

default:"light"

Theme setting (light or dark)

boolean

default:false

Enable custom click handling - When true, SDK will not automatically navigate to the destination URL on click, only emit adClicked event with destination URL. Allows developers to implement custom click behavior.

string

Advertising identifier — required for the View on Device feature to preview a draft creative on a registered test device. Do not hard-code in production.

Field Binding

Bind ad data to UI elements using the data-adrop-native attribute.

Field	Description	Element Type
`profile.displayLogo`	Advertiser logo URL	`<img>`
`profile.displayName`	Advertiser name	Text
`headline`	Ad title	Text
`body`	Ad description	Text
`asset`	Main image URL	`<img>`
`callToAction`	CTA button text	Text
`extra.{key}`	Extra text items	Text
`extraAssets.{id}.asset`	Image URL of a media item	`<img>`

extra.{key} is the ID of extra text items set in Ad Control Console. It may be empty if not set as required.

extraAssets.{id} is the media ID of a multi-media unit (e.g., m2). This binding only shows images. If the unit accepts videos, display media items as described in Multi-Media Creatives. (SDK 1.4.0+)

To display advertiser profile (profile.displayLogo, profile.displayName), you must enable Show Advertiser Profile for that ad unit in Ad Control Console.

Ad Size

Custom UI size can be set freely.

Type	Size Setting	Alignment
Direct Ads	Responsive support	Horizontal/Vertical center
Backfill Ads	Initial width matching, height required	Horizontal center

Backfill ads request creatives matching the container size. Specify an appropriate size.

Fetching Data Only with requestAd

If you want complete control over the UI, you can fetch only the ad data using requestAd.

<div id="native-ad-container"></div>

<script>
  async function loadNativeAd() {
    const adrop = Adrop.instance();

    const response = await adrop.requestAd({
      unit: 'YOUR_NATIVE_UNIT_ID',
      trackMode: 1
    });

    if (response.code === 0 && response.result) {
      const ad = response.result;
      const container = document.getElementById('native-ad-container');

      container.innerHTML =
        '<div class="native-ad">' +
          '<div class="ad-header">' +
            '<img src="' + (ad.profile?.displayLogo || '') + '" alt="Logo">' +
            '<span>' + (ad.profile?.displayName || '') + '</span>' +
          '</div>' +
          '<h3>' + (ad.headline || '') + '</h3>' +
          '<img src="' + (ad.asset || '') + '" alt="Ad">' +
          '<p>' + (ad.body || '') + '</p>' +
          '<a href="' + ad.destinationURL + '" target="_blank">' + ad.callToAction + '</a>' +
        '</div>';
    }
  }

  loadNativeAd();
</script>

When using requestAd, you must implement impression/click tracking yourself. Also, backfill ads are not supported with this method. We recommend using renderAd unless there’s a special case.

AdropAdResponse

Return value of requestAd().

Field	Type	Description
`code`	`number`	Response code (0: success, 4000-4003: error)
`msg`	`string`	Response message
`result`	`AdData`	Ad data (only present on success)

AdData

Ad data object. Event handlers also receive the same structure. See Reference > AdData for the complete interface definition.

Field	Type	Description
`format`	`string`	Ad format (`banner`, `nativeAd`, `backfill`)
`unit`	`string`	Unit ID
`headline`	`string`	Ad title
`body`	`string`	Ad description
`callToAction`	`string`	CTA button text
`asset`	`string`	Main image URL
`destinationURL`	`string`	Click destination URL
`profile.displayLogo`	`string`	Advertiser logo URL
`profile.displayName`	`string`	Advertiser name
`profile.link`	`string`	Advertiser profile link
`extra`	`Record<string, string>`	Extra text items
`extraAssets`	`Record<string, AdropNativeAsset>`	Media items keyed by media ID. See Multi-Media Creatives

Event Handling

<script>
  const adrop = Adrop.instance();
  const filter = { unit: 'YOUR_NATIVE_UNIT_ID' };

  function handleReceived(unit, adData) {
    console.log('Ad received:', adData);
  }

  function handleNoFill(unit) {
    console.warn('No ad available:', unit);
  }

  function handleFailed(unit) {
    console.error('Ad failed:', unit);
  }

  function handleImpression(unit, adData) {
    console.log('Ad impression:', unit);
  }

  function handleClicked(unit, adData) {
    console.log('Ad clicked:', unit);
  }

  // Video playback started
  function handleVideoStart(unit, adData) {
    console.log('Video started:', unit);
  }

  // Video playback ended
  function handleVideoEnd(unit, adData) {
    console.log('Video ended:', unit);
  }

  adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
  adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
  adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
  adrop.on(Adrop.Events.AD_IMPRESSION, handleImpression, filter);
  adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);
  adrop.on(Adrop.Events.AD_VIDEO_START, handleVideoStart, filter);
  adrop.on(Adrop.Events.AD_VIDEO_END, handleVideoEnd, filter);
</script>

Supported Events

Event	Constant	Description
Ad Received	`AD_RECEIVED`	Ad request successful
No Ad	`AD_NO_FILL`	No direct ads available
Request Failed	`AD_FAILED`	Ad request failed
Impression	`AD_IMPRESSION`	Ad impression recorded
Click	`AD_CLICKED`	User clicked the ad
No Backfill	`AD_BACKFILL_NO_FILL`	No backfill ad available
Video Start	`AD_VIDEO_START`	Video ad playback started
Video End	`AD_VIDEO_END`	Video ad playback ended

Custom Click Handling

When useCustomClick is enabled, the SDK will not automatically navigate to the destination URL. Instead, you can handle the click event and implement custom behavior.

<script>
  const adrop = Adrop.instance();
  
  // Handle ad click with custom behavior
  function handleCustomClick(unit, adData) {
    console.log('Ad clicked:', unit);
    console.log('Destination URL:', adData.destinationURL);
    
    // Implement custom click behavior
    // For example: navigate within SPA, show modal, track analytics, etc.
    if (adData.destinationURL) {
      // Custom navigation logic
      window.location.href = adData.destinationURL;
    }
  }
  
  // Register click handler
  const filter = { unit: 'YOUR_NATIVE_UNIT_ID' };
  adrop.on(Adrop.Events.AD_CLICKED, handleCustomClick, filter);
  
  // Render ad with custom click enabled
  const container = document.getElementById('native-ad-container');
  adrop.renderAd(container, {
    unit: 'YOUR_NATIVE_UNIT_ID',
    trackMode: 1,
    isEntireClick: true,
    useCustomClick: true
  });
</script>

With custom click handling enabled, you have full control over what happens when users click the ad. The destinationURL is provided in the adClicked event data.

Multi-Media Creatives

Requires @adrop/ads-web-sdk 1.4.0 or later.

If a native unit has two or more media items, its creatives contain a file for each media item. 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. It’s included in the ad data of SDK events such as AD_RECEIVED, and in requestAd() and requestAds() results.

const media2 = adData.extraAssets && adData.extraAssets.m2;

Media 1 (m1) is the ad’s main media (asset or ad). Keep displaying it as before, and draw only the other media items yourself.
extraAssets isn’t included for creatives of units with a single media item or for backfill ads.
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

Field	Type	Description
`id`	`string`	Media ID set in the console (e.g., `m1`, `m2`)
`asset`	`string`	Image or video file URL
`ad`	`string`	HTML that plays a video media item, including its tracking
`cover`	`string`	Poster image URL of a video. Absent for images
`type`	`string`	`'display'` (image) or `'video'`. May be absent
`isVideo`	`boolean`	Whether the media item is a video

Displaying Media Items

This section uses custom UI (trackMode: 1).

Media	Display	Placement
Image	`<img>` with `asset`	Inside the ad container
Video	Write `ad` into an `<iframe>`	Inside the ad container

Image: Set isEntireClick: true so that a click on an image you add counts as an ad click. Show images with asset: with trackMode: 1, the ad HTML of an image doesn’t report clicks to Adrop.
Video: Play the ad HTML in an <iframe>, not the asset URL. The HTML contains the video player and its tracking, so video metrics are measured only through it. Clicks inside an <iframe> don’t reach the ad container, so a tap on the video is handled only by its HTML. Don’t set the sandbox attribute on the <iframe>: the HTML needs to run scripts and open the landing page.
Landing page: When a user taps the video, its HTML reports the click and opens the landing page.

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 the ad container 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 in the ad container	Counted by the SDK, and `AD_CLICKED` fires.
Tap on a video media item	Reported by the media item’s HTML. `AD_CLICKED` doesn’t fire.
Video playback (Valid Views, Completed Views)	Reported by the media item’s HTML. `AD_VIDEO_START` and `AD_VIDEO_END` don’t fire.

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 or a video inside the ad container. Replace m2 with the ID of your unit’s media item.

<div id="native-ad-container" class="native-ad">
  <h3 data-adrop-native="headline"></h3>
  <img data-adrop-native="asset" alt="Ad">
  <!-- Media 2 (m2) -->
  <div id="ad-media-2"></div>
  <button data-adrop-native="callToAction"></button>
</div>

<script>
  const container = document.getElementById('native-ad-container');
  const adrop = Adrop.instance();

  function renderMediaItem(target, item) {
    if (!item.isVideo) {
      const image = document.createElement('img');
      image.src = item.asset;
      image.alt = 'Ad';
      target.replaceChildren(image);
      return;
    }

    // A video plays in its own HTML, which also reports the ad's taps and playback
    const iframe = document.createElement('iframe');
    iframe.title = 'Ad video';
    iframe.allow = 'autoplay';
    iframe.style.cssText = 'display: block; width: 100%; aspect-ratio: 16 / 9; border: 0;';
    target.replaceChildren(iframe);

    const doc = iframe.contentDocument;
    doc.open();
    doc.write(
      '<!DOCTYPE html><html><head><meta charset="UTF-8">' +
        '<style>html, body { margin: 0; height: 100%; overflow: hidden; }</style>' +
        '</head><body>' + item.ad + '</body></html>'
    );
    doc.close();
  }

  adrop.on(Adrop.Events.AD_RECEIVED, function (unit, adData) {
    // Media 2 (m2). Not included for single-media creatives and backfill ads
    const media2 = adData.extraAssets && adData.extraAssets.m2;
    if (media2) renderMediaItem(document.getElementById('ad-media-2'), media2);
  }, { unit: 'YOUR_NATIVE_UNIT_ID' });

  adrop.renderAd(container, {
    unit: 'YOUR_NATIVE_UNIT_ID',
    trackMode: 1,
    isEntireClick: true // Count clicks on the media items you add as ad clicks
  });
</script>

Size the <iframe> to the media item’s size set on the unit. The example uses a 16:9 media item.

SDK Guide

AI

Android

iOS

React Native

Flutter

Web

REST API

Implementation Methods

Default Template

Custom UI

Data Attributes Method

Data Attributes

renderAd Method

renderAd Options

Field Binding

Ad Size

Fetching Data Only with requestAd

AdropAdResponse

AdData

Event Handling

Supported Events

Custom Click Handling

Multi-Media Creatives

AdropNativeAsset

Displaying Media Items

Impressions and Clicks

Example

​Implementation Methods

​Default Template

​Custom UI

​Data Attributes Method

​Data Attributes

​renderAd Method

​renderAd Options

​Field Binding

​Ad Size

​Fetching Data Only with requestAd

​AdropAdResponse

​AdData

​Event Handling

​Supported Events

​Custom Click Handling

​Multi-Media Creatives

​AdropNativeAsset

​Displaying Media Items

​Impressions and Clicks

​Example

Implementation Methods

Default Template

Custom UI

Data Attributes Method

Data Attributes

renderAd Method

renderAd Options

Field Binding

Ad Size

Fetching Data Only with requestAd

AdropAdResponse

AdData

Event Handling

Supported Events

Custom Click Handling

Multi-Media Creatives

AdropNativeAsset

Displaying Media Items

Impressions and Clicks

Example