---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/android/quick-start.md
  - https://ads.yandex.com/helpcenter/ru/dev/android/quick-start.md
  - https://ads.yandex.com/helpcenter/zh/dev/android/quick-start.md
  - href: zh/dev/android/quick-start.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://ads.yandex.com/helpcenter/zh/llms.txt

# 集成 Mobile Ads SDK

> _系统：Yandex Advertising Network，Adfox_

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


## 前提条件 {#prolog}

要准备您的应用，请按照接下来的章节中描述的步骤进行操作。

### 应用要求 {#requirements}

- 使用 Android Studio 2021 或更高版本。
- 使用 Android Gradle 插件版本 8.7.0 或更高版本。
- 检查您应用的构建文件是否使用以下值：
   - minSdkVersion 21 或更高版本。
   - compileSdkVersion 35 或更高版本。
- 如果在应用中使用 [AppMetrica SDK](https://appmetrica.yandex.com)，请确保您已安装 8.3.0 或更高版本（仅限于一个主要版本）。

### 在您的 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 -->

## 设置您的应用 {#app}

1. 将对 Google 和 Maven 中央存储库的支持添加到项目配置中。

   根据构建设置，这些存储库可以添加到项目的 build.gradle 文件或 settings.gradle 的存储库块中，如下所示：

   {% list tabs %}

   - build.gradle

      ```groovy
      // 项目级别的 build.gradle 文件
      buildscript {
          repositories {
              google()
              mavenCentral()
          }
      }

      allprojects {
          repositories {
              google()
              mavenCentral()
          }
      }
      ```

   - settings.gradle

      ```groovy
      // 项目级别的 settings.gradle 文件
      pluginManagement {
        repositories {
              google()
              mavenCentral()
              gradlePluginPortal()
          }
      }
      dependencyResolutionManagement {
          repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
          repositories {
              google()
              mavenCentral()
          }
      }
      ```
   {% endlist %}

2. 将 Yandex Mobile Ads SDK 的某个依赖项添加到应用模块级别的 Gradle 文件中（通常为 app/build.gradle）：
   ```groovy
   dependencies {
     implementation 'com.yandex.android:mobileads:8.2.0'
   }
   ```

3. 设置使用广告 ID 的权限（适用于使用 4.5.0 之前版本 SDK 的应用）。

   <!-- source: zh/dev/_includes/ad-id.md -->
   {% cut "如何设置使用广告 ID 的权限" %}

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

   如果您的应用运行低于 4.5 的 Yandex Mobile Ads SDK 版本，请将 com.google.android.gms.permission.AD_ID 添加到 AndroidManifest.xml 文件中：
   ```xml
   <manifest>
       <application>
       <!-- For apps targeting Android 13 or higher & Yandex Mobile Ads SDK versions lower than 4.5.0 -->
           <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
       </application>
   </manifest>
   ```

   从版本 4.5.0 开始，Yandex Mobile Ads SDK 默认添加 com.google.android.gms.permission.AD_ID。因此，您不必在应用程序的主清单中指定它。该权限允许您使用广告 ID 从广告网络中选择更相关的广告。

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

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

   {% note warning %}

   缺少 ID 使用权限和访问权限可能会影响您的收入，因为您的应用可能会投放相关性较低的广告。

   {% endnote %}

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

成功初始化 Yandex Mobile Ads SDK 是正确集成库的前提条件。 默认情况下，SDK 会在您的应用启动时自动初始化。 这会加快广告加载速度，从而增加您的变现收入。

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

您可以使用 AndroidManifest.file 或在手动初始化 SDK 之前设置这些政策。

{% cut "COPPA 设置" %}

如果选择了自动初始化，请将以下代码添加到 AndroidManifest.xml 文件中，以便在应用用户是儿童时通知 Yandex Mobile Ads SDK：
```xml
<manifest>
    <application>
        <!-- 禁止使用儿童的个人数据进行应用变现。  -->
        <meta-data
          android:name="@string/yandex_mobileads_age_restricted_user"
          android:value="true" />
    </application>
</manifest>
```
{% endcut %}

### 手动 SDK 初始化 {#init-manual}

如有必要，您可以禁用自动初始化，并使用 `initialize()` 方法对库手动进行初始化。

```xml
<manifest>
    <application>
        <!-- 禁用自动 sdk 初始化。  -->
        <meta-data
            android:name="com.yandex.mobile.ads.AUTOMATIC_SDK_INITIALIZATION"
            android:value="false" />
    </application>
</manifest>
```

{% note warning %}

即使您已禁用自动初始化，但如果您尚未手动调用 `YandexAds.initialize()`，SDK 也会在第一个广告请求之前进行初始化。 有关初始化日志的更多信息，请阅读下方的[测试 SDK 集成](#check)。

{% endnote %}

我们建议将初始化代码添加到 `Application` 类的 `onCreate` 方法中。 确保在初始化 SDK 之前设置[个人数据隐私政策](https://ads.yandex.com/helpcenter/zh/dev/android/gdpr.md)。

{% list tabs %}

- Kotlin

   ```kotlin
   class MyApplication : Application() {
       override fun onCreate() {
           super.onCreate()
           // 在 sdk 初始化之前配置用户数据隐私政策
           YandexAds.initialize(this) {
               // 现在您可以使用广告
           }
       }
   }
   ```

- Java

   ```java
   public class MyApplication extends Application {
       @Override
       public void onCreate() {
          super.onCreate();
           // 在 sdk 初始化之前配置用户数据隐私政策
           YandexAds.initialize(this, () -> {
               // 现在您可以使用广告
           });
       }
   }
   ```
{% endlist %}

## 测试 SDK 集成 {#check}

<!-- 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 -->

### 过时库版本的指示器

{% note info %}

该指示器在调试模式下可用。

{% endnote %}

如果 Yandex Mobile Ads SDK 版本已过时，则会在库初始化或加载广告时显示一个提示条形式的指示器。

问题详细信息也记录到应用日志中。

**示例日志：**

```
***************************************************************************************
* The integrated version of the Yandex Mobile Ads SDK is outdated.                    *
* Please update com.yandex.android:mobileads to the latest version.                   *
* Learn more about the latest version of the SDK here:                                *
* https://yandex.ru/dev/mobile-ads/doc/android/quick-start/android-ads-component.html *
* Changelog: https://yandex.ru/dev/mobile-ads/doc/intro/changelog-android.html        *
***************************************************************************************
```
要禁用指示器，请调用 `enableDebugErrorIndicator` 方法并将其设置为 `false`：

```java
YandexAds.enableDebugErrorIndicator(false)
```
{% note tip %}

我们不建议禁用对过时 SDK 版本指示器的验证。 确保使用最新的库版本以最大限度地提高您的广告收入。

{% endnote %}

### 面向最新 SDK 版本的 Lint 检查

构建应用的发布版本时，将运行 lint 检查，以验证您使用的是否为最新 SDK 版本。

Lint 检查是通过调用 `lintVitalRelease` gradle 任务触发的，如果广告 SDK 版本已过时，该任务会崩溃。

如果有更新的 SDK 版本可用，该检查将不会允许应用构建。

要禁用对最新 SDK 版本的检查，请使用通过 gradle 代码阻止 lint 检查这一标准方法（有关详细信息，请参阅 [Android 文档](https://developer.android.com/reference/tools/gradle-api/4.1/com/android/build/api/dsl/LintOptions)）。

```groovy
android {
    lintOptions {
        disable 'MobileAdsSdkOutdatedVersion'
    }
}
```

## 后续步骤 {#next}

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

选择以下最适合您的应用的广告类型之一：



#|
|| **广告格式** | **Yandex Advertising Network** | **Adfox** | **描述** ||
|| [自适应内联横幅](https://ads.yandex.com/helpcenter/zh/dev/android/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/yes-new.png"> | 自适应内嵌横幅广告是一种灵活的横幅广告格式，通过针对每台设备优化广告尺寸，确保投放效果达到最优。

横幅高度是自动选择的，并且可以达到设备屏幕的高度。

通常，这种格式用于基于信息流的应用或可以将用户注意力主要集中在广告上的上下文环境中。 ||
|| [自适应粘性横幅](https://ads.yandex.com/helpcenter/zh/dev/android/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/yes-new.png"> | 自适应固定横幅广告是一种小型广告，会自动更新，并显示在应用屏幕的顶部或底部。它不会遮挡主要内容，常用于游戏应用中。

粘性横幅的高度是自动确定的，可根据设备屏幕尺寸调整，并且不超过屏幕高度的 15％。 ||
|| [插屏广告](https://ads.yandex.com/helpcenter/zh/dev/android/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/yes-new.png"> | 插屏广告是一种全屏广告格式，嵌入在应用内容中，在自然暂停时显示，例如在游戏关卡之间过渡或完成目标操作时。

当用户看到插屏广告时，他们的注意力完全集中在广告上，这导致此类展示的成本更高。

过度使用这种格式可能会降低用户的互动体验。 ||
|| [激励广告](https://ads.yandex.com/helpcenter/zh/dev/android/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/android/native.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/yes-new.png"> | 原生广告是一种布局可以在应用级别定义的广告类型。这一功能允许您根据应用设计的具体上下文更改广告的视觉风格以及投放位置。

<!-- source: zh/dev/_includes/native-ads.md -->
广告呈现通过本地平台工具执行，从而提高广告效果和质量。
<!-- endsource: zh/dev/_includes/native-ads.md -->

您可以使用模板或手动设置原生广告的布局。 如果选择使用模板，广告布局将在SDK端设置。 ||
|| [开屏广告](https://ads.yandex.com/helpcenter/zh/dev/android/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"> | 应用开屏广告是一种用于通过应用加载界面实现变现的特殊广告格式。此类广告可随时关闭，并设计用于在以下场景中展示：
* 应用启动时。
* 应用被调至前台时。
* 从后台返回应用时。
 ||
|| [广告信息流](https://ads.yandex.com/helpcenter/zh/dev/android/feed-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"> | 广告信息流是由一系列广告组成的单元。信息流可以作为应用的主要内容添加，或者添加到现有内容之后。信息流可能包含数十条广告，而这些广告会按顺序加载（一次加载多个广告）。
 ||
|| [视频插播广告](https://ads.yandex.com/helpcenter/zh/dev/android/instream.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/yes-new.png"> | 视频插播广告 可让您通过在播放视频内容时投放广告来实现应用变现。

视频插播广告由具有多个视频块的场景组成。视频插播广告场景中视频单元的类型决定了视频广告相对于主视频内容的播放方式。
 ||
|#