Cómo usar claves de API

En este tema, se describe cómo crear una clave de API para el SDK de Maps para Android, agregarla a tu app y protegerla mediante la restricción de la clave. Debes agregar una clave de API a toda app que use el SDK.

Antes de comenzar

A fin de comenzar a utilizar el SDK de Maps para Android, debes habilitarlo y tener un proyecto con una cuenta de facturación. Si deseas obtener más información, consulta Set up in Cloud Console.

Cómo crear claves de API

La clave de API es un identificador único que se utiliza para autenticar solicitudes asociadas a tu proyecto con fines de uso y facturación. Debes tener, al menos, una clave de API asociada a tu proyecto.

Para crear una clave de API, sigue estos pasos:

  1. Ve a la página API y servicios > Credenciales.

    Ir a la página Credenciales

  2. En la página Credenciales, haz clic en Crear credenciales > Clave de API.
    El diálogo Se creó la clave de API mostrará la clave de API que acabas de crear.
  3. Haz clic en Cerrar.
    La nueva clave de API aparecerá en la página Credenciales debajo de Claves de API.
    (Recuerda restringir la clave de API antes de utilizarla en producción).

Cómo agregar la clave de API a tu app

En esta sección, se describe cómo almacenar tu clave de API para que tu app pueda hacer referencia a ella de manera más segura. No debes verificar la clave de API en el sistema de control de versión, por lo que te recomendamos almacenarla en el archivo local.properties, que se encuentra en el directorio raíz de tu proyecto. Para obtener más información sobre el archivo local.properties, consulta los archivos de propiedades de Gradle.

Para optimizar esta tarea, puedes usar el complemento Secrets Gradle para Android.

Para instalar el complemento y almacenar tu clave de API, haz lo siguiente:

  1. En Android Studio, abre el archivo build.gradle a nivel de tu app y agrega el siguiente código al elemento plugins.
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. Guarda el archivo y sincroniza tu proyecto con Gradle.
  3. Abre el archivo local.properties en el directorio de nivel de proyecto y, luego, agrega el siguiente código. Reemplaza YOUR_API_KEY por la clave de API.
    MAPS_API_KEY=YOUR_API_KEY
        
  4. Guarda el archivo y sincroniza tu proyecto con Gradle.
  5. En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY y actualiza el android:value attribute de la siguiente manera:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Nota: Como se mostró anteriormente, com.google.android.geo.API_KEY es el nombre de metadatos recomendado para la clave de API. Se puede utilizar una clave con este nombre a fin de autenticar varias API basadas en Google Maps en la plataforma de Android, incluido Maps SDK for Android. Respecto de la retrocompatibilidad, la API también admite el nombre com.google.android.maps.v2.API_KEY. Este nombre heredado solo permite la autenticación de la versión 2 de la API de Google Maps para Android. Una aplicación puede especificar solo uno de los nombres de metadatos de la clave de API. Si se especifican ambos, la API arrojará una excepción.

Cómo restringir las claves de API

La restricción de las claves de API agrega seguridad a tu aplicación, ya que garantiza que solo se realicen solicitudes autorizadas con tu clave de API. Te recomendamos enfáticamente que sigas las instrucciones si deseas configurar restricciones para tus claves de API. Para obtener más información, consulta Prácticas recomendadas sobre las claves de API.

Para restringir una clave de API, sigue estos pasos:

  1. Ve a la página API y servicios > Credenciales.

    Ir a la página Credenciales

  2. Selecciona la clave de API para la que deseas establecer una restricción. Aparecerá la página de propiedades de la clave de API.
  3. En Restricciones de clave, establece las siguientes restricciones:
    • Restricciones de aplicaciones:
      1. Selecciona Apps de Android.
      2. Haz clic en + Agregar nombre del paquete y huella digital.
      3. Ingresa el nombre del paquete y la huella digital del certificado SHA-1. Por ejemplo:
        com.example.android.mapexample
        BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
        Para obtener más información, consulta Cómo obtener una huella digital SHA-1.
    • Restricciones de API:
      1. Haz clic en Restringir clave.
      2. Selecciona SDK de Maps para Android en el menú desplegable Seleccionar API.
        Si el SDK de Maps para Android no aparece en la lista, debes habilitarlo.
  4. Para finalizar los cambios, haz clic en Guardar.

Cómo obtener una huella digital SHA-1

Cuando restringes tu clave de API, debes proporcionar la huella digital del certificado SHA-1 de la clave de firma que se usó para firmar la aplicación. La huella digital es una secuencia de 20 números hexadecimales de dos dígitos separados por dos puntos. Existen dos tipos de certificados:

  • Certificado de depuración: Las herramientas del SDK de Android generan este certificado automáticamente cuando realizas una compilación de depuración. Utiliza este certificado solo con apps que estés probando. No intentes publicar una app firmada con un certificado de depuración.
  • Certificado de lanzamiento: Las herramientas del SDK de Android generan este certificado cuando ejecutas una compilación de lanzamiento. También puedes generar este certificado con el programa keytool. Usa este certificado cuando estés listo para publicar tu app en una tienda de aplicaciones.
  • Sigue los pasos que se indican a continuación para mostrar una huella digital SHA-1 con la app de línea de comandos Keytool.

    Certificado de depuración

    Cómo visualizar la huella digital del certificado de depuración

    1. Busca el archivo de almacén de claves correspondiente a tu depuración. El nombre del archivo es debug.keystore y se crea la primera vez que compilas el proyecto. De forma predeterminada, se almacena en el mismo directorio que los archivos de tu dispositivo virtual de Android (AVD):

      • macOS y Linux: ~/.android/
      • Windows Vista y Windows 7: C:\Users\your_user_name\.android\
    2. Indica la huella digital SHA-1:

      • En el caso de macOS o Linux, abre una ventana de la terminal y escribe lo siguiente:

        keytool -list -v -keystore ~/.android/debug.keystore
         -alias androiddebugkey -storepass android -keypass android
      • En el caso de Windows Vista y Windows 7, ejecuta lo siguiente:

        keytool -list -v -keystore
         "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey
         -storepass android -keypass android

    El resultado debería ser similar al ejemplo siguiente: En la línea que comienza con SHA1, se incluye la huella digital SHA-1 del certificado.

    Alias name: androiddebugkey
    Creation date: Jan 01, 2013
    Entry type: PrivateKeyEntry
    Certificate chain length: 1
    Certificate[1]:
    Owner: CN=Android Debug, O=Android, C=US
    Issuer: CN=Android Debug, O=Android, C=US
    Serial number: 4aa9b300
    Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
    Certificate fingerprints:
         MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
         SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
         Signature algorithm name: SHA1withRSA
         Version: 3
    
    Certificado de lanzamiento

    Cómo visualizar la huella digital del certificado de lanzamiento

    1. Busca el archivo de almacén de claves correspondiente a tu certificado de lanzamiento. No existe una ubicación ni un nombre predeterminados para este archivo. Si no especificas estos datos al compilar tu app para su lanzamiento, el archivo .apk quedará sin firmar, y deberás firmarlo antes de publicarlo. Para el certificado de lanzamiento, también necesitas el alias del certificado y las contraseñas del almacén de claves y del certificado. Puedes indicar los alias de todas las claves en un almacén de claves. Para ello, ingresa lo siguiente:

      keytool -list -keystore your_keystore_name

      Reemplaza your_keystore_name por la ruta de acceso completamente calificada y el nombre del almacén de claves, incluida la extensión .keystore. Se te pedirá que ingreses la contraseña del almacén de claves. Luego, keytool mostrará todos los alias en el almacén de claves.

    2. En una terminal o un símbolo del sistema, ingresa lo siguiente:

      keytool -list -v -keystore your_keystore_name -alias your_alias_name

      Reemplaza your_keystore_name por la ruta de acceso completamente calificada y el nombre del almacén de claves, incluida la extensión .keystore. Reemplaza your_alias_name por el alias que le asignaste al certificado cuando lo creaste.

    El resultado debería ser similar al ejemplo siguiente: En la línea que comienza con SHA1, se incluye la huella digital SHA-1 del certificado.

    Alias name: <alias_name>
    Creation date: Feb 02, 2013
    Entry type: PrivateKeyEntry
    Certificate chain length: 1
    Certificate[1]:
    Owner: CN=Android Debug, O=Android, C=US
    Issuer: CN=Android Debug, O=Android, C=US
    Serial number: 4cc9b300
    Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
    Certificate fingerprints:
        MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
        SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
        Signature algorithm name: SHA1withRSA
        Version: 3
    

    Para obtener más información sobre los certificados digitales, consulta la guía Firma tu app.