---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.0
alternate:
  - https://appmetrica.yandex.com/docs/en/sdk/android/analytics/android-gradle-plugin.md
  - https://appmetrica.yandex.com/docs/ru/sdk/android/analytics/android-gradle-plugin.md
  - https://appmetrica.yandex.com/docs/zh/sdk/android/analytics/android-gradle-plugin.md
  - href: https://appmetrica.yandex.com/docs/zh/sdk/android/analytics/android-gradle-plugin.md
    type: text/markdown
    title: Markdown version
  - href: https://appmetrica.yandex.com/docs/zh/llms.txt?revision=r21975373
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://appmetrica.yandex.com/docs/zh/llms.txt?revision=r21975373

# AppMetrica Gradle 插件

AppMetrica 让您收集本地和 Java 崩溃的信息。 您可以在[崩溃](https://appmetrica.yandex.com/docs/zh/mobile-reports/crashes-and-errors.md)报告中分析它们。 另请参见[崩溃/错误](https://appmetrica.yandex.com/docs/zh/data-collection/about-crashes-and-errors.md)。

为了减小应用大小，[优化](https://developer.android.com/studio/build/shrink-code)代码在发布构建时。

如果在构建 Android 应用时代码被压缩和混淆，关于崩溃的信息会以混淆形式传输。 要从这样的崩溃日志中提取分析数据，AppMetrica 会在服务器端执行反混淆处理。

要完成这一步，请将SO文件的映射文件或调试符号上传到AppMetrica，可以在构建应用时自动上传，也可以通过网页界面手动上传。

要发送文件，请启用 AppMetrica Gradle 插件。

## 限制 {#restrictions}

- 插件仅应用于模块 `com.android.application`。 它不应用于 `com.android.library` 模块。

- 如果使用 [ProGuard](https://www.guardsquare.com/en/products/proguard/manual) 或 [R8](https://r8.googlesource.com/r8/)，请上传映射文件。 如果代码没有压缩或混淆，不要启用插件。

- 插件的运行取决于 `com.android.tools.build:gradle`（AGP）和gradle的版本。 插件与以下版本兼容：

    - `com.android.tools.build:gradle` 从 `7.2.0` 升级到 `8.13.+`（除 `8.0.+` 外）；
    - gradle 从 `7.4` 升级到 `9.2.1`. 我们不能保证插件与其他版本兼容。

    插件功能在同时使用 Gradle `8.0` 和 AGP `7.4.*` 时不保证正常。

- 对于本地构建，建议禁用插件——这可以加快构建速度。 只在 CI 上启用。 一种便捷的做法是通过环境变量来控制 `启用` 标志：

   ```kotlin translate=no
   appmetrica {
       enable.set(providers.environmentVariable("CI").map { it == "true" }.orElse(false))
   }
   ```

## 连接插件 {#connecting}

要启用插件：

1. 将以下依赖项添加到 Gradle 根文件中：

   ```kotlin translate=no
   plugins {
       id("io.appmetrica.analytics") version "2.1.0" apply false
   }
   ```

   {% cut "启用插件使用`buildscript`" %}

   将以下依赖项添加到 Gradle 根文件：

   ```kotlin translate=no
   buildscript {
      repositories {
          mavenCentral()
      }
      dependencies {
          classpath("io.appmetrica.analytics:gradle:2.1.0")
      }
   }
   ```

   {% endcut %}

2. 将插件和最小配置添加到应用的 Gradle 文件中：

   ```kotlin translate=no
   plugins {
       id("com.android.application")
       id("io.appmetrica.analytics")
   }

   appmetrica {
       postApiKey.set("Post Api key")
       ndk {
           enable.set(true) // Optional. Enable if your project has native code and you need native crashes
       }
   }
   ```

   其他参数及其默认值在[插件参数](#parameters)中有描述。

## 常见任务 {#recipes}

通常情况下，不需要修改任何设置：`enable` 默认为 `true`，仅用于 `buildType = 'release'`；`ndk.enable` 默认为 `false`（仅在项目包含本地代码且需要本地崩溃时才启用）。 因此，对于没有对外`发布`的项目（且没有NDK符号），插件已经能够开箱即用，性能优化良好。

{% cut "为单独的非发布 buildType 收集映射和 NDK 符号，不占用上传配额" %}

例如，如果单独的非发布 `buildType`（比如 `snapshot`）也需要映射和 NDK 符号，但你不想为这个构建耗费每日上传配额。 由于 `enable`、`offline` 和 `ndk.enable` 对每个构建变体分别解析，请通过分层配置（参见 [分层配置](#hierarchical-config)）为特定的 `buildType` 覆盖它们：

```kotlin translate=no
android {
    buildTypes {
        // Besides release, mapping and NDK symbols are also needed for the snapshot build
        named("snapshot") {
            appmetrica {
                // By default enable=true only for release — enable it explicitly for snapshot,
                // otherwise mapping will neither be collected nor uploaded
                enable.set(true)

                ndk {
                    // By default ndk.enable=false — enable it explicitly for snapshot,
                    // otherwise NDK symbols won't be collected
                    enable.set(true)
                }

                // To avoid spending the daily upload quota on snapshot, don't upload mapping
                // and symbols automatically. They will still be collected locally in
                // build/appmetrica/<variant>/result, and you can upload them manually later,
                // see "Manual loading"
                offline.set(true)
            }
        }
    }
}

appmetrica {
    // postApiKey is set once in the global block and applies to all variants,
    // including snapshot above — no need to set it again in a per-buildType block
    // (otherwise, with different values, you'll get "Conflicting values for postApiKey")
    postApiKey.set("Post Api key")
}
```

{% endcut %}

## Plugin parameters → 插件参数 {#parameters}

示例配置，包含所有可用的参数：

```kotlin translate=no
appmetrica {
    postApiKey.set("Post Api key")
    enable.set(true)                                    // Optional
    offline.set(false)                                  // Optional
    mappingFile.set(file("path/to/mapping.txt"))        // Optional
    enableAnalytics.set(true)                           // Optional
    allowTwoAppMetricas.set(false)                      // Optional
    ndk {                                               // Optional
        enable.set(false)
        soFiles.from(file("path/to/so"))                // Optional
        additionalSoFiles.from(file("path/to/extra"))   // Optional
        addNdkCrashesDependency.set(true)               // Optional
    }
}
```

#|
|| **参数** | **描述** ||
|| `postApiKey*` | Post API key. `字符串`.
您可以在 **设置** 部分的 AppMetrica 中获取 Post API 密钥。 它用于识别您的应用。

如果`offline = true`，该参数是可选的。

关于层级配置的说明：该值在所有设置了它的源中必须相同。 如果不同的源指定不同的值，插件会记录错误并将键视为未设置（请参见[分层配置](#hierarchical-config)）。 ||
|| `启用` | 启用或禁用给定构建变体的插件。`布尔值`。
如果插件被禁用，APK不会被修改，映射数据既不会被收集也不会被上传，资源生成也不会执行。

不影响收集或上传 NDK 符号——这由独立的 `ndk.enable` 参数控制（请参见下文）。

默认情况下，`true`仅当`buildType = 'release'`，否则`false`.

支持分层配置（请参见[分层配置](#hierarchical-config)）。 ||
|| `离线` | 启用`离线`模式。 `布尔`.

同时影响映射符号和NDK符号的上传（无论`enable`或`ndk.enable`是否启用——离线模式共享于两者之间）。

可接受的值：

* `true` — 也不会上传映射或符号到 AppMetrica. 归档文件放在 `build/appmetrica/<variant>/result/`，路径记录在日志中。 您可以通过网页界面手动上传归档文件。
* `false` — 自动上传映射和符号。

默认值是`false`.

支持分层配置（请参见[分层配置](#hierarchical-config)）。 ||
|| `mappingFile` | 映射文件的路径。`RegularFileProperty`（在 Kotlin DSL 中通过 `file("...")`）。

默认值是构建中的映射文件（`OBFUSCATION_MAPPING_FILE` AGP 工件）。 只有在想从非标准位置上传映射时才覆盖它。

支持分层配置（请参见[分层配置](#hierarchical-config)）。 ||
|| `启用分析` | 允许将插件使用统计发送到 AppMetrica `布尔值`

可接受的值：

* `true` — 已启用发送统计数据。
* `false` — 统计发送已禁用。

默认值是`true`。 ||
|| `allowTwoAppMetricas` | 当项目中同时存在两个不同的AppMetrica库（`io.appmetrica.analytics:analytics` 和 `com.yandex.android:mobmetricalib`）时的行为。`布尔值`.

可接受的值：

* `false` — 如果找到了两个库，构建会**失败**，并显示错误。
* `true` — 允许同时存在两个库，日志中会写入警告。

默认值是`false`.

支持分层配置（请参见[分层配置](#hierarchical-config)）。 ||
|| `ndk` | 此参数用于从 SO 文件加载符号，以追踪本地崩溃。 ||
|| `ndk.enable` | 启用或禁用从 SO 文件处理和上传符号。`布尔值`。

如果已启用，构建后符号处理和上传任务将自动运行。

默认值是`false`.

支持分层配置（请参见[分层配置](#hierarchical-config)）。 ||
|| `ndk.soFiles` | SO 文件需要处理。`可配置文件集合`. 使用 `from(...)` 添加文件。

默认情况下，插件从 `MERGED_NATIVE_LIBS` AGP 构件获取 SO 文件——这已包含 `src/main/jniLibs/**` 和 CMake/ndk-build 的输出。

如果你的 SO 文件位于非标准位置，或者插件无法找到它们，请覆盖它。

层级配置行为：来自所有源的集合被**合并**（参见[层级配置](#hierarchical-config)）。 ||
|| `ndk.additionalSoFiles` | Additional SO files. `可配置文件集合`. 使用 `from(...)` 添加文件。

与 `soFiles` 不同，它不是替换默认设置，而是对其进行扩展。

层次化配置行为：所有来源的集合已**合并**。 ||
|| `ndk.addNdkCrashesDependency` | 自动将 `io.appmetrica.analytics:analytics-ndk-crashes` 依赖项添加到 `<variant>Implementation` 配置中。`布尔值`.

默认值是`true`.

支持分级配置（请参见[分级配置](#hierarchical-config)）。 ||
|#

{% note info %}

如果启用了`ndk.enable` 参数，构建后符号处理和上传任务会自动运行。 不需要额外的手动配置。

{% endnote %}

### Hierarchical configuration {#hierarchical-config}

插件支持四个配置级别：

```kotlin translate=no
appmetrica {
    // Global configuration
    variants {
        create("<variantName>") {
            // Variant configuration
        }
    }
}

android {
    buildTypes {
        named("<buildTypeName>") {
            appmetrica {
                // buildType configuration
            }
        }
    }
    productFlavors {
        named("<flavorName>") {
            appmetrica {
                // flavor configuration
            }
        }
    }
}
```

{% note info %}

对于每个构建变体，插件会从所有级别收集值，并为每个参数应用相应的解析策略。 **这不是“通常”的优先级，即“最高级别获胜”——行为取决于参数类型。**

{% endnote %}

#### `启用`, `离线`, `ndk.启用`, `允许两个AppMetrica`, `启用分析`, `ndk.添加Ndk崩溃依赖`

Logic: “禁用总是优先”。

- 如果至少有一个源的值是`false`，结果就是`false`.
- 否则，如果至少有一个源具有值`true` —— 结果是`true`.
- 否则会使用默认值。

Example:

```kotlin translate=no
appmetrica {
    enable.set(true)
}

android {
    buildTypes {
       debug {
           appmetrica {
               enable.set(false)
           }
       }
    }
}
```

因此，`enable` 对于调试为 `false`，对于所有其他情况为 `true`。

#### `postApiKey`

Logic: “值必须唯一”。

- 如果参数只在一个源中设置，则使用该值。
- 如果在多个源中设置了相同的值，则使用该值。
- 如果不同的源指定不同的值——会记录错误`postApiKey的值冲突`，并使用默认值（空字符串）。 上传不会执行 — 插件额外发出警告 `postApiKey 未设置`.

因此，请将 `postApiKey` **仅设置在一个位置** —— 通常是在全局块或相关 flavor 中。

#### `mappingFile`

逻辑: "优先查找".

Source priority: 全局块 > 每个变体 > 每个构建类型 > 第一个配置的版本 > 默认值（从构建映射） 使用第一个设置了参数的源中的值。

#### `ndk.so文件`, `ndk.附加so文件`

Logic: “collection merging”.

所有非空的 `.from(...)` 来自所有层级的都 **合并** 为单个集合。 如果集合在任何级别都未配置 — `soFiles` 会回退到 AGP 的默认设置，而 `additionalSoFiles` 则会回退到空集合。 要替换默认的文件集，在其中一个源中设置 `soFiles.from(...)` — 这样默认设置就不会被使用。

#### Example

```kotlin translate=no
// Global settings for all variants
appmetrica {
    enableAnalytics.set(true)
}

android {
    buildTypes {
        release {
            // NDK symbol upload is needed only for release builds
            appmetrica {
                ndk {
                    enable.set(true)
                }
            }
        }
    }

    productFlavors {
        // Each flavor has its own key — for example, different apps for prod and dev
        create("prod") {
            appmetrica {
                postApiKey.set("prod-post-api-key")
            }
        }
        create("dev") {
            appmetrica {
                postApiKey.set("dev-post-api-key")
            }
        }
    }
}

// Per-variant: targeted override for a specific variant
appmetrica {
    variants.create("prodRelease") {
        ndk {
            additionalSoFiles.from(file("extra-symbols"))
        }
    }
}
```

{% note tip %}

要了解插件实际对某个变体应用了哪些值，请查看构建日志：对于每个参数，都会以以下形式写入一行 `使用来自<source>的值‘X’用于<parameter>` 或 `使用默认值‘...’用于...`。

{% endnote %}

## 手动加载 {#manual-loading}

要手动上传，请设置`offline = true`模式。 这是为了让插件生成 `info.txt`，其中包含元数据，服务器将通过这些数据将归档与构建关联。

1. 在 app/build.gradle 文件中，启用`离线`模式：

   ```kotlin translate=no
   appmetrica {
       offline.set(true)
   }
   ```

   在`离线`模式下，`postApiKey`参数是可选的。

2. 构建所需的应用版本（例如，`./gradlew assembleRelease`）。 归档将出现在 `<appModule>/build/appmetrica/<variant>/result/`:

   - `mapping.zip` — 用于 Java 崩溃；
   - `symbols.zip` — 用于本地崩溃，如果 `ndk.enable` 已启用。

3. 在AppMetrica界面中，从左侧菜单进入应用设置。
4. 转到 **崩溃** → **Android** 标签。
5. 点击 **选择文件**，上传需要的归档。

## Plugin tasks {#tasks}

对于每个构建变体 `<variant>`（`Release`、`ProdRelease`等），插件会注册以下任务：

#|
|| **任务名称** | **目的** ||
|| `检查<variant>AppMetricaDependencies` | 检查项目中仅使用了一个AppMetrica库（参见`allowTwoAppMetricas`）。 ||
|| `创建<variant>AppMetricaRes` | 生成资源在 `build/appmetrica/<variant>/res/`；结果会合并到应用资源中。 ||
|| `zip<variant>AppMetricaFiles` | 构建 `mapping.zip` (`info.txt` + mapping). ||
|| `上传<variant>AppMetricaMapping` | 上传 `mapping.zip` 到 AppMetrica（在 `离线` 模式下 — 跳过，归档文件保留在 `result/`）。 ||
|| `生成<variant>AppMetricaNdkSymbols` | 将SO文件转换为`.ysym`。 ||
|| `zip<variant>AppMetricaNdkFiles` | 构建 `symbols.zip` (`info.txt` + `.ysym`). ||
|| `上传<variant>AppMetricaNdkSymbols` | 上传 `symbols.zip` 到 AppMetrica. ||
|#

上传任务被连接为`finalizedBy`在`assemble<variant>`和`bundle<variant>`. 因此，普通构建（`./gradlew assembleRelease` 或 `./gradlew bundleRelease`）会自动触发上传。 你可以这样手动执行上传：

```bash
./gradlew uploadReleaseAppMetricaMapping
./gradlew uploadReleaseAppMetricaNdkSymbols
```

## 构建错误和警告 {#errors}

#### 阻止构建的错误 {#build-blocking-errors}

- `IllegalStateException` — 代码混淆未启用。 启用 ProGuard 或 R8。
- `HttpResponseException` — 无法上传归档。 检查您的网络连接和`postApiKey`的正确性。
- 依赖检查错误 — 项目中同时发现两个库 (AppMetrica `io.appmetrica.analytics:analytics` 和 `com.yandex.android:mobmetricalib`)。 删除其中一个，或者临时设置 `allowTwoAppMetricas = true`.

#### 警告（构建不会失败，但可能无法上传） {#warnings}

这些消息很重要，需要特别注意（尤其在 CI 中）——它们表示出现了问题，但 Gradle 不会报错。

- `AppMetrica 插件已为变体 '<variant>' 启用，但未设置 postApiKey。上传将失败。请设置 postApiKey 或启用离线模式。` — 对于该变体已启用上传，但密钥为空。 设置 `postApiKey` 或启用 `offline`.
- `postApiKey 的值冲突：...` — `postApiKey` 在不同的源中被设置为不同的值。 插件使用空键 — 上传会失败。 只在一个地方设置密钥，或者同步值。
- `使用默认值 '...' 用于 <parameter>` — 参数在任何源中都未设置，使用默认值。 有助于调试，如果看起来设置“没有生效”。

如果遇到其他错误，请联系[技术支持](https://appmetrica.yandex.com/docs/zh/troubleshooting/feedback-new.md)。

## 了解更多 {#learn-more}

- [崩溃和错误报告](https://appmetrica.yandex.com/docs/zh/mobile-reports/crashes-and-errors.md)
- [Android 文档](https://developer.android.com/topic/performance/vitals/crash)

<!-- source: zh/_includes/feedback-button-3.md -->
如果您没有找到所需答案，可以通过反馈表单提交您的问题。 请尽可能详细地描述问题。 如果可能，请附上截图。

<a href="../troubleshooting/feedback-new">
  <span class="button">联系支持</span>
</a>

<a href="../troubleshooting/feedback-docs">
  <span class="button">为文档提出改进建议</span>
</a>
<!-- endsource: zh/_includes/feedback-button-3.md -->