---
metadata:
- name: generator
content: Diplodoc Platform v5.50.6
alternate:
- https://ads.yandex.com/helpcenter/en/dev/react-native/app-open-ad.md
- https://ads.yandex.com/helpcenter/ru/dev/react-native/app-open-ad.md
- https://ads.yandex.com/helpcenter/zh/dev/react-native/app-open-ad.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt
# 开屏广告
应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示：
* 应用启动时。
* 应用被调至前台时。
* 从后台返回应用时。
本指南介绍将开屏广告集成到 React Native 应用的过程。
除了代码示例和说明之外，它还包含特定格式的建议以及指向其他资源的链接。
{% note alert %}
应用开屏广告仅支持纵向布局的应用。对于横向布局的应用，此类广告将不会展示。
{% endnote %}
## 外观
开屏广告包含 **Go to the app** 按钮，该按钮向用户表明他们当前正在使用您的应用并可以关闭广告。以下是此广告格式的示例：
## 前提条件 {#pre}
1. 按照 [快速入门](https://ads.yandex.com/helpcenter/zh/dev/react-native/quick-start.md) 中描述的 Yandex Mobile Ads React Native 插件集成步骤进行操作。
2. 确保您拥有 [最新版本的 Yandex Mobile Ads React Native 插件](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。如果您正在使用聚合，请更新到最新的 [单一构建版本](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。
### 术语
* **冷启动**：启动不在 RAM 中的应用，创建一个新的应用会话。
* **热启动**：当应用在 RAM 中暂停时，将应用从后台模式切换到前台模式。
## 实施 {#implement}
集成开屏广告广告的关键步骤：
1. 创建 `AppOpenAdLoader`。
1. 使用 `AdRequestConfiguration` 对象设置加载广告的参数。
1. 加载 `AppOpenAd` 对象。
1. 设置广告的回调函数。
1. 使用 `AppState.addEventListener('change', handleAppStateChange)` 方法订阅应用状态更改事件，以便在应用开启时展示广告。
1. 展示 `AppOpenAd` 对象。
### 关键步骤
1. 创建 `AppOpenAdLoader`。
```ts
let loader = await AppOpenAdLoader.create()
.catch((error) => {
// 妥善处理错误
return;
});
```
2. 使用 `AdRequestConfiguration` 对象设置加载广告的参数。要创建 `AdRequestConfiguration` 类实例，您需要来自 Yandex Advertising Network 界面 (adUnitId) 的版位 ID。
您还可以在创建 `AdRequestConfiguration` 对象时，通过提供有关用户兴趣、页面上下文、位置和其他附加数据的信息来扩展广告请求参数。在广告请求中添加额外的上下文信息可以极大地提高广告质量。请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/react-native/target.md)版块了解更多信息。
```ts
let adRequestConfiguration = new AdRequestConfiguration({
adUnitId: 'R-M-XXXXXX-Y', // for debug you can use 'demo-appopenad-yandex'
age: '20',
contextQuery: 'context-query',
contextTags: ['context-tag'],
gender: Gender.Female,
location: new Location(55.734202, 37.588063),
});
```
3. 调用 `loadAd` 方法加载广告。
```ts
let ad = await loader.loadAd(adRequestConfiguration)
.then((ad) => {
// 广告加载成功
return ad;
})
.catch((error) => {
// 妥善处理错误
return;
});
```
4. 设置广告的回调函数。
```ts
ad.onAdShown = () => {
console.log('Did show');
};
ad.onAdFailedToShow = (error) => {
console.log(`Did fail to show with error: ${JSON.stringify(error)}`);
};
ad.onAdClicked = () => {
console.log('Did click');
};
ad.onAdDismissed = () => {
console.log('Did dismiss');
};
ad.onAdImpression = (impressionData) => {
console.log(`Did track impression: ${JSON.stringify(impressionData)}`);
};
```
5. 使用 `AppState.addEventListener('change', handleAppStateChange)` 方法订阅应用状态更改事件，以便在应用开启时展示广告。
6. 当应用变为活跃状态时，调用 `show()` 方法展示广告。
```ts
const handleAppStateChange = (nextAppState: string) => {
if (nextAppState === 'active') {
ad.show();
subscription.remove();
}
};
const subscription = AppState.addEventListener('change', handleAppStateChange);
```
{% note info %}
如果广告已经投放，调用 `show()` 方法将在 `onAdFailedToShow` 中返回显示错误。
{% endnote %}
## 开屏广告集成的特点 {#features}
1. 广告可能需要较长的加载时间，如果广告尚未加载，应避免增加冷启动时间。
2. 预加载广告，以便后续热启动展示使用。
3. 不建议在应用启动时同时加载开屏广告和其他广告格式，因为应用可能正在下载必要的操作数据。这样做可能会导致设备和网络连接负载过高，从而延长广告加载时间。
4. 如果 `loadAd` 方法返回错误，请勿再次尝试加载新广告。如果没有其他选项，请限制广告加载重试次数。如果有限制，这将有助于避免频繁出现失败的请求和连接问题。
## 测试开屏广告集成 {#test}
{% list tabs %}
- Android
### 使用演示广告单元进行广告测试 {#demo-blocks}
使用测试广告来检查您的广告集成和应用本身。为了确保每次广告请求都能返回测试广告，您可以使用一个特殊的演示广告版位 ID。
演示广告单元 ID：`demo-appopenad-yandex`。
{% note warning %}
在应用商店发布应用前，请务必将演示广告版位 ID 替换为您在 Yandex Advertising Network 接口中获取的真实 ID。
{% endnote %}
有关所有可用演示广告版位 ID 的列表，请参阅[用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/android/demo-blocks.md)。
### 测试广告集成 {#test-int}
您可以使用 SDK 的内置分析工具检查应用的开屏广告是否已正确集成。日志中将显示包含测试结果的详细报告。
要查看报告，请在 Android 应用调试工具 [Logcat](https://developer.android.com/studio/command-line/logcat) 中搜索关键词“YandexAds”。
```bash
adb logcat -v brief '*:S YandexAds'
```
如果集成成功，将返回以下消息：
```bash
adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type App Open Ad was integrated successfully
```
如果存在任何广告集成问题，您将收到详细的问题报告和故障排除建议。
- iOS
### 使用演示广告单元进行广告测试 {#demo-blocks}
我们建议使用测试广告来测试开屏广告集成和应用本身。
为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。
演示广告单元 ID：`demo-appopenad-yandex`。
{% note warning %}
在商店中发布您的应用程序之前，确保将演示版位 ID 替换为您在 Yandex Advertising Network 界面中获得的真实 ID。
{% endnote %}
您可以在 [用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/ios/demo-blocks.md) 版块找到可用的演示广告版位 ID 列表。
### 测试广告集成
您可以使用本机控制台工具测试广告集成。
要查看详细日志，请调用 `YMAMobileAds` 类的 `enableLogging` 方法。
```swift
YMAMobileAds.enableLogging()
```
要查看 SDK 日志，请前往控制台工具并设置 `Subsystem = com.mobile.ads.ads.sdk`。您还可以按类别和错误级别过滤日志。
如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。
{% endlist %}
## 建议
1. 不建议在应用到达启动画面之前展示开屏广告。
显示启动画面可增强用户体验，使其更加直观。这样，用户就会知道他们打开了正确的应用，不会因广告而感到意外或困惑。在此屏幕上，您还可以提醒用户即将展示的广告。为此，请使用加载指示器或简单的文本信息，告知用户他们可以在广告结束后继续查看应用内容。
2. 如果广告请求与展示之间存在延迟，用户可能会在短暂打开应用后看到与应用内容无关的意外广告。这会对用户体验产生负面影响，因此应避免此类情况。一种解决方案是在显示主应用内容之前展示启动画面，并从该屏幕开始广告展示。不建议在启动画面后的内容已打开时再展示广告。
3. 等待新用户打开应用并使用几次后，再开始投放开屏广告展示。仅向符合特定条件的用户展示广告（例如，如果完成特定关卡、打开应用达到一定次数或不参与奖励优惠）。不建议在用户安装应用后立即展示广告。
4. 根据用户行为调整广告展示频率。不建议在每次冷启动或热启动时都展示广告。
5. 仅当应用在后台运行了一定时间（例如 30 秒、2 分钟或 15 分钟）时才展示广告。
6. 务必进行测试，因为每款应用都是独特的，需采用适合自身的方法来最大限度地提高收入，同时确保不影响用户留存或应用使用时长。用户行为和参与度可能会随着时间的推移而发生变化，因此我们建议定期在应用内测试不同的开屏广告展示策略。
## 其他资源 {#resources}
*
[GitHub](https://github.com/yandexmobile/yandex-ads-react-native-plugin) 链接。