---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/flutter/quick-start.md
  - https://ads.yandex.com/helpcenter/ru/dev/flutter/quick-start.md
  - https://ads.yandex.com/helpcenter/zh/dev/flutter/quick-start.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt

# 集成 Mobile Ads Flutter 插件

> _系统：Yandex Advertising Network_



Flutter 是一种流行的移动应用开发跨平台技术。 它专为软件开发人员编写，可应用于不同操作系统（Android 和 iOS）的通用代码而设计。

将 Yandex Mobile Ads Flutter SDK 集成到您的应用中是渲染广告和创收的第一步。 集成 SDK 后，您可以为应用变现选择一种广告格式（例如横幅广告或激励广告）进行设置。

## 应用要求 {#requirements}

{% list tabs %}

- Android

   - 使用 Android Studio 2021 或更高版本。
   - 确保您应用的构建文件使用以下值：
      - minSdkVersion 21 或更高版本。
      - compileSdkVersion 31 或更高版本。
   - 要加载任何类型的广告，您需要使用 Android 4.1 或更高版本。
   - 仅针对 Android 5 或更高版本的设备选择视频广告。

- iOS

   - 使用 iOS 13 或更高版本。
   - 使用 Xcode 16.4 或更高版本。

{% endlist %}

### 在您的 Yandex Advertising Network 账户中设置应用程序 {#yan}

<!-- source: zh/dev/_includes/reg.md -->
以下是在 Yandex Advertising Network 中注册您的应用的方法：

1. 在 Yandex Advertising Network 中 [登录](https://partner.yandex.ru/)  或 [登录](https://passport.yandex.com/auth/list?origin=rsy_ligth_out&retpath=https%3A%2F%2Fpartner.yandex.com%2Fform%2F?roles%5B%5D=27) 您的账户。
2. 在 Yandex Advertising Network 中 [注册](https://passport.yandex.com/auth/list?origin=rsy_ligth_out&retpath=https%3A%2F%2Fpartner.yandex.com%2Fform%2F?roles%5B%5D=27) 您的应用。
<!-- endsource: zh/dev/_includes/reg.md -->

## 集成 {#inegration}

集成 Yandex Mobile Ads SDK 的方式如下：

1. 集成 Yandex Mobile Ads Flutter 插件。
2. 特定于平台的设置。
3. 初始化库。
4. 测试集成。

### 集成 Yandex Mobile Ads Flutter 插件

<!-- source: zh/dev/_includes/add-flutter.md -->
要将 Yandex Mobile Ads SDK 与您的 Flutter 应用集成，请使用 [Yandex Mobile Ads Flutter 插件](https://pub.dev/packages/yandex_mobileads)。

为您的项目安装 Yandex Mobile Ads Flutter 插件。从项目根目录执行命令：

```
flutter pub add yandex_mobileads
```

添加插件后，包含依赖项的行将添加到 `pubspec.yaml`：

```
dependencies:
    yandex_mobileads: ^8.2.0
```
<!-- endsource: zh/dev/_includes/add-flutter.md -->

### 特定于平台的设置 {#config}

{% list tabs %}

- Android

   **使用广告 ID 的权限**

   广告 ID 是 Google Play 服务提供的唯一标识符，用于向选择个性化广告的用户展示广告。 用户可以选择退出广告个性化设置或在设置中重置其 ID。 在这种情况下，广告网络将无法使用该 ID 为用户选择相关广告。

   如果需要，您可以删除该权限。 例如，如果政策不允许使用 ID 来选择广告，例如家庭政策。

   要防止将该权限添加到应用程序的主清单中，请将以下代码添加到 AndroidManifest.xml 中：
   ```xml
   <manifest>
       <application>
           <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>
       </application>
   </manifest>
   ```

   {% note warning %}

   缺乏此权限和对 ID 的访问权限可能会降低广告的相关性，从而降低您的收入。

   {% endnote %}

   **COPPA 设置**

   您可以在初始化 SDK 之前手动或使用 `AndroidManifest.file` 设置个人数据隐私策略。

   自动初始化时，在 `AndroidManifest.xml` 中添加以下代码，以通知 Yandex Mobile Ads SDK 该应用被儿童使用：
   ```xml
   <manifest>
       <application>
           <!-- Disable the use of child's personal data for app monetization.  -->
           <meta-data
             android:name="@string/yandex_mobileads_age_restricted_user"
             android:value="true" />
       </application>
   </manifest>
   ```

- iOS

   **SKAdNetwork 支持**

   在应用的 `Info.plist` 文件中添加广告网络标识符。 有关说明，请参阅 [SKAdNetwork](https://ads.yandex.com/helpcenter/zh/dev/ios/skadnetwork.md)。

   {% note warning %}

   默认情况下，Flutter 应用通过在项目中应用动态库的 `use_frameworks!` 选项进行创建。

   Yandex Mobile Ads SDK 使用静态库，因此在集成过程中需要注释掉 `# use_frameworks!` 行。

   {% endnote %}

{% endlist %}

### 初始化 Yandex Mobile Ads SDK 库 {#init}

<!-- source: zh/dev/_includes/init-sdk-flutter.md -->
成功初始化 Yandex Mobile Ads SDK 是正确集成库的重要条件。

默认情况下，对于 Android 系统，SDK 会**在您的应用启动时自动**初始化。这会加速广告加载，从而增加您的变现收入。

默认情况下，对于 iOS 系统，SDK 初始化**在广告加载之前自动**进行，但手动初始化将加快第一个广告加载的速度，从而增加变现收入。

将 `YandexAds.initialize();`调用添加到应用小部件的 `initState`：

```dart
@override
void initState() {
  super.initState();
  // 在 init sdk 之前配置用户隐私数据策略
  YandexAds.initialize();
}
```
<!-- endsource: zh/dev/_includes/init-sdk-flutter.md -->

如果您的应用需要设置 [数据使用隐私政策](https://ads.yandex.com/helpcenter/zh/dev/flutter/gdpr.md)，请在初始化 Yandex Mobile Ads SDK 之前执行此操作。

您可以在初始化 SDK 之前手动或使用 `AndroidManifest.file` 设置个人数据隐私策略。

### 测试 SDK 集成

{% list tabs %}

- Android

   <!-- source: zh/dev/_includes/test-android.md -->
   您可以使用 SDK 的内置集成测试工具验证库集成是否成功。

   为此，在添加依赖项并初始化 SDK 后，请重新构建项目。

   打开 Logcat 并搜索“Yandex Ads”关键词。

   该命令将输出集成状态日志。您将会看到一条消息，显示集成是否成功。如果存在问题，您将会看到详细描述以及解决步骤。示例命令输出：

   ```bash
   mobileads$ adb logcat | grep 'Yandex Ads' -i
   [Yandex Ads]  I  Yandex Mobile Ads 8.2.0 integrated successfully
   [Yandex Ads]  I  Yandex Mobile Ads 8.2.0 initialized successfully
   ```

   日志显示两个单独的事件：
   - “集成成功”：集成检查（SDK 尚未初始化）。
   - “初始化成功”：SDK 初始化成功。
   <!-- endsource: zh/dev/_includes/test-android.md -->

- iOS

   <!-- source: zh/dev/_includes/test-ios.md -->
   您可以检查日志以确保 SDK 集成正确。

   要查看日志，请前往控制台工具并设置 `Subsystem = com.mobile.ads.ads.sdk`。您可以按类别过滤日志，仅保留与广告 SDK 集成相关的日志。设置 `Category = Integration`。保存查询，并在需要调试时从过滤行中选择它。

   您将看到有关成功集成的消息：启用 `YandexMobileAdsBundle.bundle`、初始化 SDK 以及连接 SKAdNetwork 和移动聚合适配器（如果您在项目中使用了它们）。

   如果 SDK 集成过程中出现任何问题，您将看到详细的问题报告。

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

{% endlist %}

## 后续步骤 {#next}

成功集成 Yandex Mobile Ads SDK 后，您就可以实施广告格式了。

选择最适合您的应用的广告类型：



#|
|| **广告格式** | **Yandex Advertising Network** | **Adfox** | **描述** ||
|| [自适应内联横幅](https://ads.yandex.com/helpcenter/zh/dev/flutter/adaptive-inline-banner.md) | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/yes-new.png"> | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/no-new.png"> | 自适应内嵌横幅广告是一种灵活的横幅广告格式，通过针对每台设备优化广告尺寸，确保投放效果达到最优。

横幅的高度会自动调整，可能会达到设备屏幕的高度。

通常，这种格式在基于内容来源的应用或允许主要关注广告的上下文环境中使用。 ||
|| [自适应粘性横幅](https://ads.yandex.com/helpcenter/zh/dev/flutter/adaptive-sticky-banner.md) | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/yes-new.png"> | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/no-new.png"> | 自适应固定横幅广告是一种小型广告，会自动更新，并显示在应用屏幕的顶部或底部。它不会遮挡主要内容，常用于游戏应用中。

粘性横幅的高度是自动确定的，可根据设备的屏幕尺寸调整，并且不占用超过屏幕高度的 15%。 ||
|| [插屏广告](https://ads.yandex.com/helpcenter/zh/dev/flutter/interstitial.md) | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/yes-new.png"> | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/no-new.png"> | 插屏广告是一种全屏广告格式，嵌入在应用内容中，在自然暂停时显示，例如在游戏关卡之间过渡或完成目标操作时。

渲染插屏广告时，用户注意力会完全集中在您的广告上，这就是每次展示成本较高的原因。

如果您过于频繁地使用此格式，您的用户交互可能会受到影响。 ||
|| [激励广告](https://ads.yandex.com/helpcenter/zh/dev/flutter/rewarded.md) | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/yes-new.png"> | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/no-new.png"> | 激励广告是一种受欢迎的全屏广告格式，用户观看广告后会获得奖励。

<!-- source: zh/dev/_includes/rewarded.md -->
广告展示采用主动选择机制：例如，用户可以主动触发广告以获取游戏奖励或额外生命值。
<!-- endsource: zh/dev/_includes/rewarded.md -->

强烈的用户动机使这种广告格式成为免费应用中最受欢迎且盈利能力最强的广告格式。
 ||
|| [开屏广告](https://ads.yandex.com/helpcenter/zh/dev/flutter/app-open-ad.md) | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/yes-new.png"> | <img src="https://yastatic.net/s3/doc-binary/src/dev/mobile-ads/ru/images/no-new.png"> | 应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示：
* 应用启动时。
* 应用被调至前台时。
* 从后台返回应用时。
 ||
|#