AppMetrica Gradle 插件

AppMetrica 让您收集本地和 Java 崩溃的信息。 您可以在崩溃报告中分析它们。 另请参见崩溃/错误。

为了减小应用大小，优化代码在发布构建时。

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

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

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

限制

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

• 如果使用 ProGuard 或 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 上启用。 一种便捷的做法是通过环境变量来控制 启用 标志：

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

连接插件

要启用插件：

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

   plugins {
       id("io.appmetrica.analytics") version "2.1.0" apply false
   }
   
   启用插件使用buildscript

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

   buildscript {
      repositories {
          mavenCentral()
      }
      dependencies {
          classpath("io.appmetrica.analytics:gradle:2.1.0")
      }
   }
   

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

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

   其他参数及其默认值在插件参数中有描述。

常见任务

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

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")
}

Plugin parameters → 插件参数

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

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

Hierarchical configuration

插件支持四个配置级别：

appmetrica {
    // Global configuration
    variants {
        create("<variantName>") {
            // Variant configuration
        }
    }
}

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

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

Logic: “禁用总是优先”。

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

Example:

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

// 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"))
        }
    }
}

手动加载

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

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

   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

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

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

./gradlew uploadReleaseAppMetricaMapping
./gradlew uploadReleaseAppMetricaNdkSymbols

构建错误和警告

阻止构建的错误

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

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

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

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

如果遇到其他错误，请联系技术支持。

了解更多

• 崩溃和错误报告
• Android 文档

如果您没有找到所需答案，可以通过反馈表单提交您的问题。 请尽可能详细地描述问题。 如果可能，请附上截图。