---
metadata:
- name: generator
content: Diplodoc Platform v5.50.6
alternate:
- https://ads.yandex.com/helpcenter/en/dev/ios/native.md
- https://ads.yandex.com/helpcenter/pt/dev/ios/native.md
- https://ads.yandex.com/helpcenter/ru/dev/ios/native.md
- https://ads.yandex.com/helpcenter/zh/dev/ios/native.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt
# 原生广告
原生广告是一种布局可以在应用级别定义的广告类型。这一功能允许您根据应用设计的具体上下文更改广告的视觉风格以及投放位置。
原生广告可以增强广告体验。因此，您可以在不失去用户兴趣的情况下展示更多广告。从长远来看，这确保了广告收入的最大化。
广告呈现通过本地平台工具执行，从而提高广告效果和质量。
{% cut "外观" %}
{% endcut %}
本指南将展示如何将原生广告集成到 iOS 应用中。 除了代码示例和说明之外，它还包含特定格式的建议和其他资源的链接。
## 前提条件 {#pre}
1. 请按照 [快速入门](https://ads.yandex.com/helpcenter/zh/dev/ios/quick-start.md) 中描述的 SDK 集成步骤进行操作。
2. 提前 [初始化](https://ads.yandex.com/helpcenter/zh/dev/ios/quick-start.md#init) 您的广告 SDK。
3. 确保您运行的是最新的 [Yandex Mobile Ads SDK](https://ads.yandex.com/helpcenter/zh/dev/platforms.md) 版本。如果您使用聚合，请同时确保您运行的是最新版本的 [统一构建](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。
## 实施 {#implement}
集成原生广告的关键步骤：
- 创建并配置 `NativeAdLoader`。
- 加载广告。
- 如果您使用 Adfox，请传递[其他设置](https://ads.yandex.com/helpcenter/zh/dev/ios/target-adfox.md)。
- 展示加载的广告。
## 原生广告集成的特点 {#features}
1. 所有 Yandex Mobile Ads SDK 方法调用都必须在主线程中进行。
2. 我们强烈建议不要在出现加载错误时尝试加载新广告。 使用完成处理程序时，为 `.failure` 结果；使用 Swift Concurrency 时，在 `catch` 中进行处理。 如果需要从错误处理程序中重试，请限制广告加载的重试次数，以避免由于网络连接限制而重复出现失败的广告请求。
3. 我们建议您在与广告交互的屏幕的整个生命周期内保持对广告及其加载器的强引用。
4. 我们建议根据广告内容计算广告容器的大小。
加载广告后，您必须渲染其所有素材。 您可以从 `NativeAd` 广告对象获取可用于广告的组件列表。
5. 带有视频的广告通常具有更高的点击率，从而带来更高的广告收入。 要展示视频广告，广告容器和 MediaView 组件的大小应至少为 300x160 dp（密度无关像素）。
6. 我们建议您使用包含完整的可能素材集的布局。 根据我们的经验，包含整套素材的布局转换效果更好。
## 加载广告 {#load}
要加载原生广告，请创建一个 `NativeAdLoader` 对象。
广告请求参数通过 `AdRequest` 类进行设置。 传递广告版位 ID；您还可以配置定位数据和其他能够提升广告质量的数据。 图片加载选项通过 `NativeAdOptions` 进行传递。 详情请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/ios/target.md)部分。
使用带有完成处理程序的 `loadAd(with:options:completion:)`，或者使用 Swift Concurrency 重载 `loadAd(with:options:)`。
以下示例展示了如何从视图控制器加载原生广告。
{% 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)
// 通知原生广告已加载
} catch {
// 通知广告加载失败
}
}
}
```
- 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):
// 通知原生广告已加载
break
case .failure:
// 通知广告加载失败
break
}
}
}
}
```
{% endlist %}
## 渲染广告 {#ad-view}
{% note warning %}
从版本 8.0.0 开始，原生模板（`NativeBannerView`、`MutableNativeTemplateAppearance` 及相关类型）已从 SDK 中完全移除。 按如下所述将手动布局用于原生广告。
{% endnote %}
加载广告后，您必须渲染其所有素材。 您可以从 `NativeAd` 广告对象获取可用于广告的组件列表。
## 手动设置原生广告布局 {#config}
此方法使您能够构建原生广告布局，并将广告组件彼此相对放置。 广告可以包含必需和可选的组件。 您可以在[原生广告素材](https://ads.yandex.com/helpcenter/zh/dev/ios/components.md)中找到完整列表。
{% note tip %}
我们建议您使用包含完整的可能素材集的布局。 实际上，这通常会提高转化率。
{% endnote %}
要手动配置原生广告，请执行以下操作：
1. 为 `NativeAdView` 类创建自定义 `view`。
1. 配置自定义元素的版位，以显示组件。
1. 将这些自定义元素链接到相应的 `NativeAdView` 属性：
```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 %}
如果您没有将自定义元素链接到强制组件的 `NativeAdView` 属性，广告将不会展示。
{% endnote %}
1. 将自定义 `view` 链接到 `NativeAd` 对象，以在成功加载后展示广告。 针对 `NativeAd` 对象调用 `bind(with adView: NativeAdView)`：
```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() {
// ...
}
}
```
## 加载多个广告 {#load-more-ads}
Yandex Mobile Ads SDK 允许在单个请求中加载多个广告（最多九个广告）。
{% note info %}
将演示广告单元 `demo-native-bulk-yandex` 用于 `adUnitID`。 您可以在页面[演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/ios/demo-blocks.md)上查看支持的平台。
{% endnote %}
1. 创建 `NativeBulkAdLoader` 类的实例以获取原生广告。
2. 使用广告版位 ID 和用于获取附加选项（图片等）的 `NativeAdOptions` 创建 `AdRequest`。
3. 调用 `loadAds(with:adsCount:options:completion:)` 以加载广告。
{% 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)
// 单独处理每个 NativeAd
} catch {
// 加载错误
}
```
- 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):
// 单独处理每个 NativeAd
break
case .failure:
break
}
}
```
{% endlist %}
{% note info %}
批量广告请求允许您选择多个不同的广告。
批量请求返回的广告数组可能包含零到 `adsCount` 个 `NativeAd` 对象。 可以使用上述原生广告布局方法来彼此独立地渲染接收到的所有广告对象。
{% endnote %}
## 测试原生广告集成 {#test}
### 使用演示广告单元进行广告测试 {#demo-blocks}
我们建议使用测试广告来测试您的原生广告集成和应用本身。
为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 ID。 用它来检查您的广告集成。
文本与图片广告的演示 `adUnitId`：`demo-native-content-yandex`。
移动应用广告的演示 `adUnitId`：`demo-native-app-yandex`。
{% note warning %}
在商店中发布应用之前，请确保将演示广告单元 ID 替换为从 Yandex Advertising Network 界面获取的真实 ID。
{% endnote %}
### 测试广告集成 {#test-int}
您可以使用本机控制台工具测试广告集成。
要查看详细日志，请调用 `YMAMobileAds` 类的 `enableLogging` 方法。
```swift
YMAMobileAds.enableLogging()
```
要查看 SDK 日志，请前往控制台工具并设置 `Subsystem = com.mobile.ads.ads.sdk`。您还可以按类别和错误级别过滤日志。
如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。
## 原生广告集成指示器 {#native-ad-integration-indicator}
{% note info %}
默认情况下，该指示器仅在模拟器模式下显示（设备类型 `DeviceTypeSimulator`）。 您可以在 `DeviceType` 中查看设备类型。
{% endnote %}
如果集成原生广告时出现错误，模拟器模式下广告顶部会出现一个指示器。 单击该指示器可查看包含调试信息的消息，以帮助您了解错误的原因。 再次单击指示器可隐藏该消息。
要同时启用真实设备的指示器，请在 `enableVisibilityErrorIndicatorForDeviceType:` 方法中传递值 `DeviceTypeHardware | DeviceTypeSimulator`。
```swift
YandexAds.enableVisibilityErrorIndicator(for: [.hardware, .simulator])
```
要禁用该指示器，请在 `enableVisibilityErrorIndicatorForDeviceType:` 方法中传递值 `DeviceTypeNone`。
```swift
YandexAds.enableVisibilityErrorIndicator(for: [])
```
#|
|| 
| 
||
|#
## 其他资源 {#resources}
*
[GitHub](https://github.com/yandexmobile/yandex-ads-sdk-ios) 链接。