Настройка проекта Android Studio

В этой статье рассказывается, как настроить проект Android Studio для использования Maps SDK для Android, не применяя шаблон Google Карт, описанный в кратком руководстве.

Шаблон Google Карт автоматически задает конфигурацию для проекта и добавляет базовую карту. Однако вы также можете добавить карту в проект Android, где используется другой шаблон Android Studio. Для этого необходимо вручную изменить настройки проекта, а затем добавить карту.

Шаг 1. Настройте Android Studio

В этом документе описывается среда разработки с Android Studio Hedgehog и плагином Android Gradle версии 8.2.

Шаг 2. Настройте SDK

Библиотека Maps SDK для Android доступна в репозитории Google Maven. Чтобы добавить SDK в приложение, выполните следующие действия:

  1. Добавьте портал плагина Gradle, репозиторий Google Maven и центральный репозиторий Maven в блок pluginManagement файла settings.gradle верхнего уровня. Блок pluginManagement должен находиться над всеми операторами скрипта. 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. Добавьте репозиторий Google Maven и центральный репозиторий Maven в блок dependencyResolutionManagement файла settings.gradle верхнего уровня: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. В файле build.gradle на уровне модуля добавьте сервисы Google Play в качестве зависимости Maps SDK для Android:

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:18.2.0")
}
  4. В файле build.gradle на уровне модуля присвойте compileSdk и minSdk указанные ниже значения.

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 19
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 19
        // ...
    }
}
  5. В разделе buildFeatures файла build.gradle уровня модуля добавьте класс BuildConfig. Он позволит получать значения метаданных, которые будут определены позже.

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}

    Kotlin

    android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}

Шаг 3. Добавьте ключ API в проект

В этом разделе рассказывается, как настроить безопасный вызов ключа API вашим приложением. Вводить ключ API в систему управления версиями нежелательно, поэтому мы рекомендуем хранить его в файле secrets.properties, который находится в корневом каталоге проекта. Подробные сведения о файле secrets.properties можно найти в описании файлов свойств Gradle.

Чтобы упростить работу, используйте плагин Secrets Gradle для Android.

Чтобы установить плагин Secrets Gradle для Android в проект Google Карт:

  1. В Android Studio откройте файл build.gradle или build.gradle.kts верхнего уровня и добавьте в элемент dependencies, принадлежащий элементу buildscript, приведенный ниже код.

    Groovy

    buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

    Kotlin

    buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
  2. Откройте файл build.gradle уровня модуля и добавьте в элемент plugins приведенный ниже код.

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. Убедитесь, что для targetSdk и compileSdk в файле build.gradle уровня модуля задано значение 34.
  4. Сохраните файл и синхронизируйте проект с Gradle.
  5. Откройте файл secrets.properties в каталоге верхнего уровня и добавьте приведенный ниже код. Укажите вместо YOUR_API_KEY свой ключ API. Храните свой ключ в этом файле, поскольку secrets.properties не добавляется в систему управления версиями. 
    MAPS_API_KEY=YOUR_API_KEY
  6. Сохраните файл.

  7. Создайте файл local.defaults.properties в директории верхнего уровня (там же, где хранится файл secrets.properties), а затем добавьте указанный ниже код.

    MAPS_API_KEY=DEFAULT_API_KEY

    Этот файл служит запасным хранилищем ключа API, чтобы обеспечить выполнение сборки, даже если система не обнаружит файл secrets.properties. Так может произойти, если вы скопируете приложение из системы управления версиями, игнорирующей файл secrets.properties, и не создадите secrets.properties с ключом API локально.

  8. Сохраните файл.
  9. В файле AndroidManifest.xml найдите раздел com.google.android.geo.API_KEY и обновите android:value attribute. Если тег <meta-data> не существует, создайте его как дочерний элемент для тега <application>. 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

    Kotlin

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

Шаг 4. Обновите манифест приложения

В этом разделе описаны настройки, которые необходимо добавить в файл AndroidManifest.xml.

Версия сервисов Google Play

Добавьте в элемент application приведенный ниже код, чтобы указать версию сервисов Google Play, которая использовалась при компиляции приложения.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Доступ к данным о местоположении

Если приложению требуется доступ к данным о местоположении пользователя, вы должны запросить разрешение в файле AndroidManifest.xml. Доступны следующие варианты: ACCESS_FINE_LOCATION (точное местоположение) и ACCESS_COARSE_LOCATION (менее точное). Дополнительную информацию вы можете найти в руководстве по работе с данными о местоположении.

Чтобы запросить разрешение ACCESS_FINE_LOCATION, добавьте в элемент manifest следующий код:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Разрешение на доступ к внешнему хранилищу

Если ваше приложение предназначено для SDK сервисов Google Play версии 8.3 или более поздней, вам не понадобится разрешение WRITE_EXTERNAL_STORAGE. А если для более ранних, то необходимо запросить разрешение WRITE_EXTERNAL_STORAGE в элементе manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Библиотека Apache HTTP Legacy

Если вы используете версию com.google.android.gms:play-services-maps:16.0.0 или более раннюю, но ваше приложение обращается к API 28-го уровня (Android 9.0) или более поздней версии, добавьте приведенный ниже код в элемент <application> файла AndroidManifest.xml. В остальных случаях делать это не нужно.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Шаг 5. Настройте устройство Android

Чтобы запустить приложение с Maps SDK для Android, разверните его на устройстве Android или в эмуляторе ОС Android 4.0 или более поздней версии, поддерживающем API Google.

  • Чтобы использовать устройство Android, следуйте инструкциям о том, как запускать приложения на физических устройствах.
  • Чтобы воспользоваться эмулятором Android, создайте виртуальное устройство и установите эмулятор с помощью Менеджера AVD, который доступен в Android Studio.

Шаг 6. Проверьте, поддерживаются ли сервисы Google Play (необязательно)

Для работы с Maps SDK для Android необходимо, чтобы на устройстве, где развертывается приложение, были установлены сервисы Google Play. Google предоставляет метод, с помощью вызова которого можно выполнить проверку. Подробнее о том, как проверить, установлены ли сервисы Google Play…

Дальнейшие действия

Завершив настройку проекта, вы сможете добавить в приложение карту.