Como usar chaves de API

Este tópico descreve como criar uma chave de API para o SDK do Maps para Android, adicioná-la ao seu app e proteger o aplicativo restringindo a chave. Você precisa adicionar uma chave de API a qualquer app que use o SDK.

Antes de começar

Para usar o SDK do Maps para Android, você precisa de um projeto com uma conta de faturamento, além de estar com esse SDK ativado. Para saber mais, consulte Configurar no Console do Cloud.

Criar chaves de API

A chave de API é um identificador exclusivo que autentica solicitações associadas ao seu projeto para fins de uso e faturamento. Você precisa ter pelo menos uma chave de API associada ao projeto.

Para criar uma chave de API, siga estas etapas:

  1. Acesse a página APIs e serviços > Credenciais.

    Acessar a página "Credenciais"

  2. Na página Credenciais, clique em Criar credenciais > Chave de API.
    A caixa de diálogo Chave de API criada exibirá sua chave recém-criada.
  3. Clique em Fechar.
    A nova chave aparecerá na página Credenciais, em Chaves de API.
    Lembre-se de restringir a chave de API antes de usá-la na produção.

Adicionar a chave de API ao seu app

Nesta seção, descrevemos como armazenar sua chave de API para que ela possa ser referenciada com mais segurança pelo seu app. Não verifique sua chave de API no sistema de controle de versões. Recomendamos armazená-la no arquivo local.properties, localizado no diretório raiz do projeto. Para saber mais sobre o arquivo local.properties, consulte Arquivos de propriedade do Gradle.

Para otimizar essa tarefa, use o Plug-in Secrets Gradle para Android.

Para instalar o plug-in e armazenar sua chave de API:

  1. No Android Studio, abra o arquivo build.gradle no nível do app e adicione o seguinte código ao elemento plugins.
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. Salve o arquivo e sincronize seu projeto com o Gradle.
  3. Abra o local.properties no diretório do nível do projeto e adicione o seguinte código. Substitua YOUR_API_KEY pela sua chave de API.
    MAPS_API_KEY=YOUR_API_KEY
        
  4. Salve o arquivo e sincronize seu projeto com o Gradle.
  5. No seu arquivo AndroidManifest.xml, acesse com.google.android.geo.API_KEY e atualize o android:value attribute da seguinte maneira:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Observação: conforme mostrado acima, com.google.android.geo.API_KEY é o nome de metadados recomendado para a chave de API. Uma chave com esse nome pode ser usada para autenticar várias APIs do Google Maps na Plataforma Android, incluindo o Maps SDK for Android. Para garantir a compatibilidade com versões anteriores, a API também aceita o nome com.google.android.maps.v2.API_KEY. Esse nome herdado permite autenticação apenas na API Android Maps v2. Um aplicativo pode especificar somente um dos nomes de metadados da chave de API. Se ambos forem especificados, a API irá gerar uma exceção.

Restringir chaves de API

Essa ação aumenta a segurança do aplicativo, garantindo que somente solicitações autorizadas sejam feitas com sua chave de API. Recomendamos que você siga as instruções para definir restrições nessas chaves. Para mais informações, consulte Práticas recomendadas da chave de API.

Para restringir uma chave de API, faça o seguinte:

  1. Acesse a página APIs e serviços > Credenciais.

    Acessar a página "Credenciais"

  2. Selecione a chave de API em que você quer definir uma restrição. A página de propriedades será exibida.
  3. Em Restrições de chave, defina as seguintes opções:
    • Restrições do aplicativo:
      1. Selecione Apps Android.
      2. Clique em + Adicionar nome do pacote e impressão digital.
      3. Insira o nome do pacote e a impressão digital do certificado SHA-1. Exemplo:
        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 ver mais informações, acesse Receber uma impressão digital SHA-1.
    • Restrições de API:
      1. Clique em Restringir chave.
      2. Selecione SDK do Maps para Android na lista suspensa Selecionar APIs.
        Se o SDK do Maps para Android não aparecer na lista, ative-o.
  4. Para concluir as mudanças, clique em Salvar.

Receber uma impressão digital SHA-1

Ao restringir a chave de API, é necessário fornecer a impressão digital do certificado SHA-1 da chave usada para assinar o aplicativo. A impressão digital é uma sequência de 20 números hexadecimais de dois dígitos separados por dois pontos. Há dois tipos de certificados:

  • Certificado de depuração: as Ferramentas do SDK do Android geram esse certificado automaticamente quando você faz um build de depuração. Use-o apenas com apps em teste. Não tente publicar um app assinado com um certificado de depuração.
  • Certificado de lançamento: as Ferramentas do SDK do Android geram esse certificado quando você executa uma versão de lançamento. Também é possível gerá-lo usando o programa keytool. Use esse certificado quando tudo estiver pronto para lançar seu aplicativo em uma app store.
  • Siga as etapas abaixo para exibir uma impressão digital SHA-1 usando o app de linha de comando Keytool.

    Certificado de depuração

    Exibir a impressão digital do certificado de depuração

    1. Localize o arquivo de keystore de depuração. O nome do arquivo é debug.keystore, e ele é gerado no momento em que você cria seu projeto. Por padrão, ele fica armazenado no mesmo diretório que os arquivos do Dispositivo virtual Android (AVD, na sigla em inglês):

      • macOS e Linux: ~/.android/
      • Windows Vista e Windows 7: C:\Users\your_user_name\.android\
    2. Liste a impressão digital SHA-1:

      • Para Linux ou macOS, abra uma janela do terminal e digite o seguinte:

        keytool -list -v -keystore ~/.android/debug.keystore
         -alias androiddebugkey -storepass android -keypass android
      • No Windows Vista e Windows 7, execute este código:

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

    A saída será semelhante a esta: A linha que começa com SHA1 inclui a impressão digital SHA-1 do 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 lançamento

    Exibir a impressão digital do certificado de lançamento

    1. Localize o arquivo de keystore do certificado de lançamento. Não há local nem nome padrão para o keystore de lançamento. Se você não especificar esses itens ao criar seu app, .apk ficará sem assinatura, e será preciso assiná-lo antes da publicação. Para o certificado de lançamento, você também precisa do alias do certificado e das senhas do keystore e do certificado. É possível listar os aliases de todas as chaves em um keystore digitando o seguinte:

      keytool -list -keystore your_keystore_name

      Substitua your_keystore_name pelo caminho e nome totalmente qualificados do keystore, incluindo a extensão .keystore. Você precisará inserir a senha do keystore. Em seguida, keytool exibirá todos os aliases relevantes.

    2. Digite o seguinte em um terminal ou no prompt de comando:

      keytool -list -v -keystore your_keystore_name -alias your_alias_name

      Substitua your_keystore_name pelo caminho e nome totalmente qualificados do keystore, incluindo a extensão .keystore. Troque your_alias_name pelo alias que você atribuiu ao certificado quando o criou.

    A saída será semelhante a esta: A linha que começa com SHA1 inclui a impressão digital SHA-1 do 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 ver mais informações sobre os certificados digitais, consulte o guia Assinar seu app.