Cómo agregar dependencias de compilación

El sistema de compilación de Gradle en Android Studio te permite incluir objetos binarios externos o otros módulos de biblioteca a tu compilación como dependencias. Las dependencias pueden ubicarse en tu máquina o en un repositorio remoto, y cualquier dependencia transitiva que estas declaren se incluirá automáticamente. En esta página, se describe cómo usar las dependencias con tu proyecto de Android, incluidos los detalles sobre los comportamientos y las opciones de configuración que son específicos del complemento de Android para Gradle (AGP). Para obtener una guía conceptual más detallada sobre las dependencias de Gradle, consulta la Guía de Gradle para la administración de dependencias. Sin embargo, recuerda que tu proyecto de Android solo debe usar las opciones de configuración de dependencias que se definen en esta página.

Cómo agregar una dependencia de biblioteca o complemento

La mejor manera de agregar y administrar dependencias de compilación es usar catálogos de versiones, que es el método que usan los proyectos nuevos de forma predeterminada. En esta sección, se describen los tipos de configuraciones más comunes que se usan para proyectos de Android. Consulta la documentación de Gradle para obtener más opciones. Para ver un ejemplo de una app que usa catálogos de versiones, consulta Ahora en Android. Si ya tienes dependencias de compilación configuradas sin catálogos de versiones y tienes un proyecto de varios módulos, te recomendamos migrar.

Si deseas obtener orientación para agregar y administrar dependencias nativas (no comunes), consulta Dependencias nativas.

En el siguiente ejemplo, agregamos una dependencia binaria remota (la biblioteca de Macrobenchmark de Jetpack), una dependencia de módulo de biblioteca local (myLibrary) y una dependencia de complemento (el complemento de Android para Gradle) a nuestro proyecto. Estos son los pasos generales para agregar estas dependencias a tu proyecto:

1. Agrega un alias para la versión de la dependencia que deseas en la sección [versions] del archivo del catálogo de versiones, llamada libs.versions.toml (en el directorio gradle de la vista Project o Gradle Scripts en la vista Android):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Los alias pueden incluir guiones o guiones bajos. Estos alias generan valores anidados a los que puedes hacer referencia en las secuencias de comandos de compilación. Las referencias comienzan con el nombre del catálogo, la parte libs de libs.versions.toml. Cuando uses un solo catálogo de versiones, te recomendamos que mantengas el valor predeterminado de "libs".

2. Agrega un alias para la dependencia en las secciones [libraries] (para objetos binarios remotos o módulos de bibliotecas locales) o [plugins] (para complementos) del archivo libs.versions.toml.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Algunas bibliotecas están disponibles en una lista de materiales (BoM) publicada que agrupa familias de bibliotecas y sus versiones. Puedes incluir una BoM en tu catálogo de versiones y archivos de compilación, y permitir que administre esas versiones por ti. Consulta Cómo usar la lista de materiales para obtener más detalles.

3. Agrega una referencia al alias de dependencia a la secuencia de comandos de compilación de los módulos que requieren la dependencia. Convierte los guiones bajos y los guiones del alias en puntos cuando hagas referencia a él desde una secuencia de comandos de compilación. Nuestra secuencia de comandos de compilación a nivel del módulo se vería de la siguiente manera:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }
   

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }
   

   Las referencias de complementos incluyen plugins después del nombre del catálogo, y las referencias de versión incluyen versions después del nombre del catálogo (las referencias de versión son poco comunes; consulta Dependencias con los mismos números de versión para ver ejemplos de referencias de versión). Las referencias de bibliotecas no incluyen un calificador libraries, por lo que no puedes usar versions ni plugins al comienzo de un alias de biblioteca.

Configurar dependencias

Dentro del bloque dependencies, puedes declarar una dependencia de biblioteca con una de las diferentes configuraciones de dependencias (como implementation, que se muestra antes). La configuración de cada dependencia le proporciona a Gradle diferentes instrucciones para usarla. En la siguiente tabla, se describe cada una de las configuraciones que puedes usar para una dependencia en tu proyecto de Android.

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

Cómo configurar dependencias para una variante de compilación específica

Todas las configuraciones anteriores aplican dependencias a todas las variantes de compilación. Sin embargo, si quieres declarar una dependencia solo para un conjunto de fuentes de una variante de compilación o un conjunto de fuentes de prueba específicos, usa mayúsculas para el nombre de la configuración y agrégale un prefijo con el nombre de la variante de compilación o el conjunto de fuentes de prueba.

Por ejemplo, si quieres agregar una dependencia binaria remota solo a tu variante de producto "gratuito" con la configuración implementation, usa lo siguiente:

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Sin embargo, si deseas agregar una dependencia para una variante que combina un tipo de producto y un tipo de compilación, deberás inicializar el nombre de la configuración:

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Las dependencias implementation que agregues en las pruebas instrumentadas y las locales tendrán el siguiente aspecto:

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

Sin embargo, algunas opciones de configuración no son útiles en esta situación. Por ejemplo, como otros módulos no pueden depender de androidTest, verás la siguiente advertencia si usas la configuración androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Orden de las dependencias

El orden en el que enumeras tus dependencias indica la prioridad de cada una: la primera biblioteca tendrá mayor prioridad que la segunda, la segunda tendrá mayor prioridad que la tercera, y así sucesivamente. Este orden es importante en el caso de que se combinen los recursos o se combinen los elementos del manifiesto en tu app desde las bibliotecas.

Por ejemplo, si en tu proyecto se declara lo siguiente:

• Hay una dependencia en LIB_A y LIB_B (en ese orden).
• Además, LIB_A depende de LIB_C y LIB_D (en ese orden).
• LIB_B también depende de LIB_C.

Luego, el orden de la dependencia única será el siguiente:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

De esta manera, se garantiza que tanto LIB_A como LIB_B puedan anular a LIB_C; además, LIB_D sigue teniendo mayor prioridad que LIB_B porque LIB_A (que depende de esta) tiene mayor prioridad que LIB_B.

Para descubrir cómo se fusionan los manifiestos de diferentes fuentes o dependencias de proyectos, consulta Cómo fusionar varios archivos de manifiestos.

Información de la dependencia de Play Console

Cuando compilas tu app, AGP incluye metadatos que describen las dependencias de la biblioteca que se compilan en la app. Cuando subes tu app, Play Console inspecciona estos metadatos para proporcionar alertas sobre problemas conocidos con los SDKs y las dependencias que usa tu app y, en algunos casos, proporcionar comentarios prácticos para resolver esos problemas.

Los datos se comprimen, se encriptan con una clave de firma de Google Play y se almacenan en el bloque de firmas de tu app de lanzamiento. Recomendamos conservar este archivo de dependencias para una experiencia del usuario segura y positiva. Para inhabilitar esta opción, incluye el siguiente bloque dependenciesInfo en el archivo build.gradle.kts de tu módulo.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Para obtener más información sobre nuestras políticas y posibles problemas con las dependencias, consulta nuestra página de asistencia para usar los SDK de terceros en tu app.

Estadísticas del SDK

Android Studio muestra advertencias de lint en el archivo del catálogo de versiones y en el diálogo Project Structure para los SDKs públicos en el Índice SDK de Google Play cuando se aplican los siguientes problemas:

• Los autores marcan los SDKs como desactualizados.
• Los SDKs incumplen las políticas de Play.

Las advertencias son indicadores de que debes actualizar esas dependencias, ya que usar versiones desactualizadas podría impedir que publiques contenido en Google Play Console en el futuro.

Cómo agregar dependencias de compilación sin catálogos de versiones

Recomendamos usar catálogos de versiones para agregar y administrar dependencias, pero es posible que los proyectos simples no los necesiten. A continuación, se muestra un ejemplo de un archivo de compilación que no usa catálogos de versiones:

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Este archivo de compilación declara una dependencia en la versión 12.3 de la biblioteca "app-magic", dentro del grupo de espacios de nombres "com.example.android". La declaración de dependencia binaria remota es un atajo para lo siguiente:

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

El archivo de compilación también declara una dependencia en un módulo de biblioteca de Android llamado "mylibrary". Este nombre debe coincidir con el nombre de la biblioteca definido con include: en tu archivo settings.gradle.kts. Cuando compilas tu app, el sistema de compilación compila el módulo de biblioteca y empaqueta el contenido compilado resultante en la app.

El archivo de compilación también declara una dependencia en el complemento de Android para Gradle (com.application.android). Si tienes varios módulos que usan el mismo complemento, solo puedes tener una versión del complemento en la ruta de acceso de compilación en todos los módulos. En lugar de especificar la versión en cada una de las secuencias de comandos de compilación del módulo, debes incluir la dependencia del complemento en la secuencia de comandos de compilación raíz con la versión y, luego, indicar que no se aplique. Agregar apply false le indica a Gradle que tome nota de la versión del complemento, pero que no la use en la compilación raíz. Por lo general, la secuencia de comandos de compilación raíz está vacía, excepto por este bloque plugins.

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Si tienes un proyecto de un solo módulo, puedes especificar la versión de forma explícita en la secuencia de comandos de compilación a nivel del módulo y dejar la secuencia de comandos de compilación a nivel del proyecto vacía:

plugins {
    id("com.android.application") version "8.3.0"
}

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}