---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
alternate:
  - https://boost.yandex.com/doc/en/ad-monetization/dev/ios/native.md
  - https://boost.yandex.com/doc/ru/ad-monetization/dev/ios/native.md
  - href: en/ad-monetization/dev/ios/native.md
    type: text/markdown
    title: Markdown version
  - href: llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://boost.yandex.com/doc/en/llms.txt

# Native ads

<!-- source: en/ad-monetization/dev/_includes/native-ads.md -->
Native advertising is a type of ad whose layout can be defined at the app level. This feature allows you to change the visual style of ads and their placement, in the context of the app design specifics.
<!-- endsource: en/ad-monetization/dev/_includes/native-ads.md -->

<!-- source: en/ad-monetization/dev/_includes/native-ads.md -->
Native ads enhance the overall ad experience, so you can show more ads while keeping users engaged. In the long run, this allows you to maximize your advertising revenue.
<!-- endsource: en/ad-monetization/dev/_includes/native-ads.md -->

<!-- source: en/ad-monetization/dev/_includes/native-ads.md -->
Ad rendering is performed with native platform tools, which enhances ad performance and quality.
<!-- endsource: en/ad-monetization/dev/_includes/native-ads.md -->

{% cut "Appearance" %}

<img src="https://yastatic.net/s3/doc-binary/src/docs/support/mobile-ads/en/monetization/_images/native-en-ex.png" width="200">

{% endcut %}

This guide will show how to integrate native ads into iOS apps. Besides code samples and instructions, it contains format-specific recommendations and links to additional resources.


## Prerequisite {#pre}

<!-- source: en/ad-monetization/dev/_includes/pre-ios.md -->
1. Follow the SDK integration steps described under [Quick start](https://boost.yandex.com/doc/en/ad-monetization/dev/ios/quick-start.md).
2. First, you need to [initialize](https://boost.yandex.com/doc/en/ad-monetization/dev/ios/quick-start.md#init) the advertising SDK.
3. Make sure you're using the [latest version of the Yandex Mobile Ads SDK](https://boost.yandex.com/doc/en/ad-monetization/dev/platforms.md), and if you're using mediation, the latest version of the [unified build](https://boost.yandex.com/doc/en/ad-monetization/dev/platforms.md).
<!-- endsource: en/ad-monetization/dev/_includes/pre-ios.md -->

## Implementation {#implement}

Key steps for integrating native ads:

- Create and configure a `NativeAdLoader`.
- Load the ad.
- Pass [additional settings](https://boost.yandex.com/doc/en/ad-monetization/dev/ios/target-adfox.md) if you're using Adfox.
- Render the loaded ad.

## Specifics of native ad integration {#features}

1. All calls to Yandex Mobile Ads SDK methods must be made from the main thread.

2. We strongly advise against attempting to load a new ad immediately after a loading error. With completion handlers, this corresponds to the `.failure` case. With Swift Concurrency, it's the `catch` block. If you need to retry, limit the number of attempts. This helps prevent endless failed requests during network issues.

3. We recommend maintaining a strong reference to the ad and its loader throughout the lifespan of the screen where the ad interaction is taking place.

4. The size of the ad container should be based on the ad content.

   After the ad has finished loading, you need to render all of its assets. You can get the list of available ad assets from the `NativeAd` advertising object.

5. Ads with a video typically have a higher CTR and, consequently, generate more revenue. To display video ads, the size of the ad container and the MediaView component must be at least 300 × 160 dp (density-independent pixels).

6. We recommend using a layout that includes all the possible components. In practical terms, such layouts result in higher conversion rates.

## Loading ads {#load}

To load your native ads, create a `NativeAdLoader` object.

The ad request parameters are configured via the `AdRequest` class object. To make a request, you'll need to pass your ad unit ID. You can also customize targeting and other parameters to help deliver higher-quality, more relevant ads. Image loading parameters can be passed using `NativeAdOptions`. To learn more, see [Ad targeting](https://boost.yandex.com/doc/en/ad-monetization/dev/ios/target.md).

To load an ad, use either the `loadAd(with:options:completion:)` method with a completion handler or the Swift Concurrency-powered `loadAd(with:options:)` method.

The following example shows how to load native ads from the View Controller:

{% list tabs %}

- Swift Concurrency

  ```swift
  final class CustomNativeViewController: UIViewController {
      private var adLoader: NativeAdLoader?

      override func viewDidLoad() {
          adLoader = NativeAdLoader()
      }

      private func loadNativeAd() async {
          let request = AdRequest(adUnitID: "R-M-XXXXX-YY")
          let options = NativeAdOptions()
          do {
              let ad = try await adLoader?.loadAd(with: request, options: options)
              // Notifies that a native ad is loaded
          } catch {
              // Notifies that the ad failed to load
          }
      }
  }
  ```

- Completion handler

  ```swift
  final class CustomNativeViewController: UIViewController {
      private var adLoader: NativeAdLoader?

      override func viewDidLoad() {
          adLoader = NativeAdLoader()
      }

      private func loadNativeAd() {
          let request = AdRequest(adUnitID: "R-M-XXXXX-YY")
          let options = NativeAdOptions()
          adLoader?.loadAd(with: request, options: options) { [weak self] result in
              switch result {
              case .success(let ad):
                  // Notifies that a native ad is loaded
                  break
              case .failure:
                  // Notifies that the ad failed to load
                  break
              }
          }
      }
  }
  ```

{% endlist %}

## Rendering ads {#ad-view}

{% note warning %}

Starting in version 8.0.0, we've completely removed native templates (`NativeBannerView`, `MutableNativeTemplateAppearance`, and related classes) from the SDK. To customize the look and feel of your native ads, you can manually configure their layout using the steps below.

{% endnote %}

After the ad has finished loading, you need to render all of its assets. You can get the list of available ad assets from the `NativeAd` advertising object.

## Manual configuration of the native ad layout {#config}

This method allows you to create a custom layout for your native ads and define their positioning relative to each other. The ad may include both required and optional assets for display. For the full list, see [Native ad assets](https://boost.yandex.com/doc/en/ad-monetization/dev/ios/components.md).

{% note tip %}

We recommend using a layout that includes all the possible components. In practical terms, such layouts result in a higher conversion rate.

{% endnote %}

To manually configure the layout of your native ads:

1. Create a custom `view` for the `NativeAdView` class.
1. Set up the positioning of custom elements responsible for asset rendering.
1. Link these custom elements to the corresponding `NativeAdView` properties:

    ```swift
    final class CustomNativeAdView: NativeAdView {
        // ...

        init() {
            super.init(frame: CGRect())
            setupUI()
            bindAssets()
        }

        private func bindAssets() {
            titleLabel = customTitleLabel
            domainLabel = customDomainLabel
            warningLabel = customWarningLabel
            sponsoredLabel = customSponsoredLabel
            feedbackButton = customFeedbackButton
            callToActionButton = customCallToActionButton
            mediaView = customMediaView
            priceLabel = customPriceLabel
            reviewCountLabel = customReviewCountLabel
            ratingView = customRatingView
            bodyLabel = customBodyLabel
            iconImageView = customIconImageView
        }

        private func setupUI() {
        // ...
        }
    }
    ```

    {% note info %}

    If you don't link a custom element to the `NativeAdView` property for the mandatory component, the ad won't be displayed.

    {% endnote %}

1. Once the ad loads successfully, bind your custom `view` to the `NativeAd` object to display it. To do this, call the `bind(with adView: YMANativeAdView)` method for the `NativeAd` object:

    ```swift
    final class NativeCustomViewController: UIViewController, NativeAdDelegate {
        private let adView = NativeCustomAdView()

        // ...

        private lazy var adLoader: NativeAdLoader = {
            let adLoader = NativeAdLoader()
            return adLoader
        }()

        override func viewDidLoad() {
            super.viewDidLoad()
            setupUI()
            loadNativeAd()
        }

        private func loadNativeAd() {
            let request = AdRequest(adUnitID: "demo-native-app-yandex")
            let options = NativeAdOptions()
            adLoader.loadAd(with: request, options: options) { [weak self] result in
                if case .success(let ad) = result {
                    self?.bindNativeAd(ad)
                }
            }
        }

        private func bindNativeAd(_ ad: NativeAd) {
            ad.delegate = self
            do {
                try ad.bind(with: adView)
            } catch {
                // ...
            }
        }

        private func setupUI() {
        // ...
        }
    }

    ```

## Loading multiple ads {#load-more-ads}

The Yandex Mobile Ads SDK provides the option to load multiple ads in a single request (up to nine ads).

{% note info %}

Use the `demo-native-bulk-yandex` demo ad unit for your `AdUnitID`. For supported platforms, see [Demo ad units for testing](https://boost.yandex.com/doc/en/ad-monetization/dev/ios/demo-blocks.md).

{% endnote %}

1. Create an instance of the `NativeBulkAdLoader` class to get native ads.

2. Create an `AdRequest` with your ad unit ID and use `NativeAdOptions` for extra settings like image parameters.

3. Call the `loadAds(with:adsCount:options:completion:)` method to load ads.

{% list tabs %}

- Swift Concurrency

  ```swift
  let request = AdRequest(adUnitID: AdUnitID)
  let options = NativeAdOptions()
  let adLoader = NativeBulkAdLoader()

  do {
      let ads = try await adLoader.loadAds(with: request, adsCount: adsCount, options: options)
      // Handling each NativeAd object separately
  } catch {
      // Load error
  }
  ```

- Completion handler

  ```swift
  let request = AdRequest(adUnitID: AdUnitID)
  let options = NativeAdOptions()
  let adLoader = NativeBulkAdLoader()

  adLoader.loadAds(with: request, adsCount: adsCount, options: options) { result in
      switch result {
      case .success(let ads):
          // Handling each NativeAd object separately
          break
      case .failure:
          break
      }
  }
  ```

{% endlist %}

{% note info %}

Using a bulk ad request, you can select multiple distinct ads.

The array of ads returned by a bulk request may contain between zero and `adsCount` `NativeAd` objects. All the received ad objects can be displayed independently, using the previously described methods for native ad layout.

{% endnote %}

## Testing native ad integration {#test}

### Using demo ad units for ad testing {#demo-blocks}

Use test ads to check your native ad integration and the app itself.

To make sure that test ads are returned for each ad request, we created a special demo ad placement ID designed to help you test your ad integration.

Demo adUnitId for Combinatorial ads: `demo-native-content-yandex`.

Demo adUnitId for ads for mobile apps: `demo-native-app-yandex`.

{% note warning %}

Before publishing your app in the store, make sure to replace the demo placement ID with the real ID you obtained in the interface Boost.

{% endnote %}

<!-- Список всех доступных демонстрационных идентификаторов рекламного места доступен в разделе [Тестовые объявления](ссылка). -->

### Testing ad integration {#test-int}

<!-- source: en/ad-monetization/dev/_includes/test-integration-ios.md -->
You can test your ad integration using the native Console tool.

To view detailed logs, call the `YandexAds` class's `enableLogging` method.

```swift
YandexAds.enableLogging()
```

To view SDK logs, go to the Console tool and set `Subsystem = com.mobile.ads.ads.sdk`. You can filter logs by category or error level.

If you're having problems integrating ads, you'll get a detailed report on the issues and recommendations for how to fix them.

<img src= "https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/common/integration-ios-2.png">
<!-- endsource: en/ad-monetization/dev/_includes/test-integration-ios.md -->

## Indicator of correct native ad integration {#native-ad-integration-indicator}

{% note info %}

By default, the indicator is only shown in simulator mode (device type `DeviceTypeSimulator`). You can view device types in `DeviceType`.

{% endnote %}

If there's an error in native ad integration, the indicator will appear over the ad in the simulator mode. Click the indicator to see the debug message, which should point you to the root cause of the problem. Clicking the indicator again hides the message.

To enable the indicator for real devices as well, pass the value `DeviceTypeHardware | DeviceTypeSimulator` in the `enableVisibilityErrorIndicatorForDeviceType:` method.

```swift
YandexAds.enableVisibilityErrorIndicator(for: [.hardware, .simulator])
```

To disable the indicator, pass the value `DeviceTypeNone` in the `enableVisibilityErrorIndicatorForDeviceType:` method.

```swift
YandexAds.enableVisibilityErrorIndicator(for: [])
```

#|
|| <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/weather_closed_1.png"> | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/weather_open_1.png"> ||
|#

## Additional resources {#resources}

* <!-- source: en/ad-monetization/dev/_includes/github-pubdev-links.md -->
  Link to [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-ios).
  <!-- endsource: en/ad-monetization/dev/_includes/github-pubdev-links.md -->