Предыдущий Google Maps Mobile SDK for Work: Android

Для пользователей с лицензией на ранее выпускавшийся продукт Google Maps APIs for Workили лицензией Google Maps API for Business право использовать Google Maps Android API приобретается в составе Google Maps Mobile SDK for Work. В этом разделе документации описывается процедура настройки для этого SDK.

Эта страница предназначена только для пользователей, которые владеют лицензией на ранее выпускавшиеся продукты Maps APIs for Work или Maps API for Business. Эта страница не предназначена для пользователей нового продукта Google Maps APIs Premium Plan, который стал доступен в январе 2016 года.

Обзор

Следуйте указаниям, приведенным на этой странице, чтобы загрузить пакет SDK, настроить проект и добавить карту. Ниже приводится краткое описание необходимых шагов.

  1. Загрузите пакет SDK.
  2. Добавьте пакет SDK в новый или уже созданный проект Android.
  3. Добавьте свой ключ API в манифест приложения.
  4. Укажите необходимые разрешения для Android и настройки для OpenGL ES версии 2.
  5. Добавьте карту.

Загрузка пакета разработчика

Пакет разработчика можно загрузить в виде статической библиотеки или использовать Android SDK Manager.

Вариант 1: загрузка пакета разработчика в виде статической библиотеки

Загрузите последнюю версию в виде статической библиотеки.

Вариант 2: загрузка пакета разработчика с использованием Android SDK Manager

в Android Studio:

  1. Выберите Tools > Android > SDK Manager.
  2. Выберите Appearance & Behavior > System Settings > Android SDK.
  3. Перейдите на вкладку SDK Update Sites.
  4. Щелкните значок плюс (+), чтобы добавить новый сайт.
  5. Введите имя, например 'Google Maps APIs', и URL-адрес: https://dl.google.com/geosdk/android-m4b-addon.xml
  6. Нажмите OK.
  7. Перейдите на вкладку SDK Tools.
  8. Выберите Google Maps Mobile SDK for Work и нажмите OK, чтобы завершить загрузку.

Android Studio установит библиотеку в папку <android-sdk-folder>/extras/google/maps_for_business_sdk/.

См. руководство по работе с Android SDK Manager, чтобы получить инструкции по использованию Android SDK Manager как отдельного инструмента.

Добавление пакета разработчика в проект

Ниже приведены инструкции для Android Studio. Если вы используете другой инструмент, см. инструкции в документации Android относительно использования командной строки.

Google Maps Android API для Google Maps Mobile SDK for Work доступен в двух форматах: пакет aar (google-maps-sdk-m4b.aar) и библиотечный модуль (google-maps-sdk-m4b_lib). Выберите наиболее подходящий для вас формат.

Вариант 1: импорт пакета разработчика из пакета aar

Выполните следующие шаги, чтобы добавить пакет aar (google-maps-sdk-m4b.aar) в проект Android Studio.

  1. Перейдите в Google Maps Mobile SDK for Work, используя следующий путь:

    <android-sdk>/extras/google/maps_for_business_sdk

  2. Скопируйте файл google-maps-sdk-m4b.aar в каталог libs своего проекта. (Если этот каталог отсутствует, создайте его).

  3. В файл build.gradle добавьте следующий код:

    dependencies {
        compile(name:'google-maps-sdk-m4b', ext:'aar')
    
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. Выполните шаги для настройки конфигурации, как это описано ниже.

Вариант 2: импорт пакета разработчика в виде библиотечного модуля

Вместо использования файла aar вы можете выполнить следующие шаги, чтобы добавить библиотечный модуль пакета разработчика (google-maps-sdk-m4b_lib) к существующему проекту в Android Studio.

  1. В Android Studio выберите вариант для импорта нового модуля (File -> New -> Import Module).
  2. Перейдите к пакету SDK, используя следующий путь:

    <android-sdk>/extras/google/maps_for_business_sdk

  3. Выберите каталог google-maps-sdk-m4b_lib и нажмите Choose.

  4. Согласитесь с использованием значений по умолчанию в мастере импорта.
  5. Нажмите Finish. Вы увидите текстовый файл с описанием результатов процесса импорта.
  6. Убедитесь, что библиотека включена в файл settings.gradle:

    include ':googlemapssdkm4b_lib'

  7. Добавьте зависимость модуля в файл build.gradle вашего приложения:

    compile project(':googlemapssdkm4b_lib')

Преобразование готовых конфигураций, в которых используются службы Google Play

  1. Если у вас есть приложение, в котором используются службы Google Play, замените все ссылки на пакет com.google.android.gms.maps на com.google.android.m4b.maps.
  2. Добавьте ко всем ссылкам на атрибуты макетов XML префикс m4b_. Например: m4b_mapType и m4b_cameraZoom.

Получите ключ API и добавьте его в свое приложение

Создайте ключ API для своего проекта и добавьте его в AndroidManifest.xml, как это описывается ниже. Вам нужно настроить ключ API с ограничением для Android.

Ваш ключ API идентифицирует вас как пользователяGoogle Maps Mobile SDK for Work, позволяет получать поддержку и использовать приобретенную квоту для вашего приложения. Вы можете сгенерировать ключ API для учетной записи с включенной службой Google Maps Mobile SDK, используя сочетание названия своего пакета приложения и его цифрового сертификата.

Ключ API основан на сокращенной форме цифрового сертификата вашего приложения. Все приложения Android подписываются с использованием цифровых сертификатов, для которых имеются закрытые ключи. (Подробные сведения о цифровых сертификатах изложены в руководстве Android по добавлению подписи в приложениях).

Отображение информации о сертификате приложения

Ограничение ключа API для Android представляет собой цифровой сертификат вашего приложения, только в сокращенной форме, которая называется контрольной суммой SHA-1.

Получение информации о сертификации из Android Studio

Если вы следовали руководству по началу работы для Google Maps Android API, Android Studio создаст полезный файл google_maps_api.xml, содержащий учетные данные вашего приложения.

Выберите один из следующих способов получить свой ключ API из Android Studio.

  • Самый быстрый и простой способ: Используйте ссылку в файле google_maps_api.xml, созданном Android Studio.
    1. Скопируйте ссылку из файла google_maps_api.xml и вставьте ее в адресную строку своего браузера. Эта ссылка перенаправит вас в Google API Console и предоставит в Google API Console необходимую информацию через параметры URL, тем самым сократив объем данных, которые требуется вводить вручную.
    2. Выполните инструкции, чтобы создать новый проект в Google API Console, или выберите существующий проект.
    3. Создайте ключ API, ограниченный для Android, для своего проекта.
    4. Скопируйте созданный ключ API, вернитесь в Android Studio и вставьте ключ API в элемент <string> в файле google_maps_api.xml.
  • Несколько менее быстрый способ: Используйте учетные данные в файле google_maps_api.xml, созданном Android Studio.
    1. Скопируйте учетные данные из файла google_maps_api.xml.
    2. Откройте Google API Console в браузере.
    3. Используйте скопированные учетные данные, чтобы добавить приложение в существующий ключ API или создать новый ключ API.

Самостоятельное получение информации о сертификации

Если при создании приложения вы не следовали руководству по началу работы, тогда вам необходимо будет самостоятельно получить контрольную сумму SHA-1 для своего сертификата. Прежде всего, убедитесь, что вы действительно используете соответствующий сертификат. У вас может быть два сертификата.

  • Сертификат для отладки: Этот сертификат создается автоматически при выполнении отладочной сборки приложения с помощью инструментов Android SDK. Его следует использовать исключительно при тестировании приложений. Не пытайтесь опубликовать приложение, подписанное с помощью сертификата для отладки. Подробные сведения о таких сертификатах см. на странице Добавление подписи в режиме отладки в документации для разработчиков Android.
  • Сертификат для выпуска: Этот сертификат создается с помощью инструментов Android SDK при выполнении сборки в процессе подготовки к выпуску. Его также можно создать с помощью программы keytool. Этот сертификат используется для добавления подписи в приложение, готовое к публикации.

Ниже показан порядок действий, которые необходимо выполнить, чтобы отобразить контрольную сумму SHA-1 сертификата в программе keytool с помощью параметра -v. Подробные сведения о программе Keytool см. в документации Oracle.

Сертификат для отладки

Отображение контрольной суммы сертификата для отладки

  1. Найдите ваш файл хранилища ключей для отладки. Этот файл, который называется debug.keystore, создается при выполнении первой сборки проекта. По умолчанию он хранится в том же каталоге, где и файлы Android Virtual Device (AVD):

    • macOS и Linux: ~/.android/
    • Windows Vista и Windows 7: C:\Users\your_user_name\.android\
  2. Откройте контрольную сумму SHA-1.

    • В Linux или macOS перейдите в окно терминала и введите следующую команду:

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • В Windows Vista и Windows 7 выполните следующую команду:

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

Результат должен быть аналогичен следующему:

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
Сертификат для выпуска

Отображение контрольной суммы сертификата для выпуска

  1. Найдите ваш файл хранилища ключей сертификата для выпуска. Этот файл может называться по-разному, и для него нет стандартного местоположения. Если не указать этот файл при создании сборки приложения для выпуска, ваш пакет .apk останется без подписи и его необходимо будет подписать, чтобы обеспечить возможность публикации. Кроме того, в случае с сертификатом для выпуска вам потребуется его псевдоним, а также пароли для хранилища ключей и самого сертификата. Чтобы получить список псевдонимов для всех ключей, имеющихся в хранилище, введите следующую команду:

    keytool -list -keystore your_keystore_name

    Замените your_keystore_name на полный путь и имя файла хранилища ключей, включая расширение .keystore. Потребуется ввести пароль для хранилища ключей. После этого в окне программы keytool появится список всех псевдонимов, имеющихся в хранилище.

  2. В окне терминала или в командной строке введите следующую команду:

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    Замените your_keystore_name на полный путь и имя файла хранилища ключей, включая расширение .keystore. Замените your_alias_name на псевдоним, присвоенный сертификату при его создании.

Результат должен быть аналогичен следующему:

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

В строке, которая начинается с элемента SHA1, указана контрольная сумма SHA-1 сертификата. Контрольная сумма представляет собой последовательность из 20 двузначных чисел в шестнадцатеричном формате, которые разделены двоеточиями.

Дополнительные сведения о цифровых сертификатах изложены в руководстве Android по добавлению подписи в приложениях.

Убедитесь, что ваша учетная запись активирована для службы

Google Maps Mobile SDKПосле подписки

на Google Maps Mobile SDK for Work группа Google Maps Mobile SDK активирует службу Google Maps Mobile SDK. Эта служба включена в новый проект. После этого вы можете получить ключ API в Google API Console.

Примечание. Служба Google Maps Mobile SDK будет отображаться только в консоли исходного владельца проекта. Чтобы запросить разрешениена просмотр службы для других владельцев проекта, нужно отправить заявку по нетехнической проблеме в Google Cloud Support Portal.

Убедитесь, что ваша учетная запись активирована:

  1. Перейдите в Google API Console и войдите в свою учетную запись Google.
  2. Выберите проект Google Maps Mobile SDK for Work, который был создан для вас при заказе Google Maps Mobile SDK for Work. Название проекта начинается с Google Maps APIs for Business or Google Maps for Work or Google Maps. Если вы еще не приобрели доступ к SDK, [свяжитесь с отделом продаж].
  3. Откройте панель Dashboard и в списке API проверьте активацию Google Maps Mobile SDK*.

Получение ключа API из Google API Console

После активации службы Google Maps Mobile SDK for Work для вашего проекта необходимо сгенерировать новый ключ.

  1. Откройте страницу учетных данных в Google API Console и войдите в свою учетную запись Google.
  2. Выберите проект Google Maps Mobile SDK for Work, который был создан для вас при заказе Google Maps Mobile SDK for Work. Название проекта начинается с Google Maps APIs for Business or Google Maps for Work or Google Maps. Если вы еще не приобрели доступ к SDK, [свяжитесь с отделом продаж].
  3. Найдите в списке *API keys ключ c ограничением для Android.
  4. Если в вашем проекте еще нет ключа API, ограниченного для Android, создайте его, выбрав Create credentials > API key.
  5. В открывшемся диалоговом окне выберите Restrict key.
  6. В разделе Restrictions выберите Android apps, затем укажите контрольную сумму SHA-1 своего приложения и название пакета. Например:

    BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    com.example.android.mapexample
    
  7. Нажмите Save.

    Ваш новый ключ API, ограниченный для Android, отобразится в списке ключей API для вашего проекта. Ключ API представляет собой строку символов, которая выглядит примерно так:

    AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
    

Добавление ключа API в приложение

Выполните приведенные ниже действия, чтобы включить ключ API в манифест приложения, содержащийся в файле AndroidManifest.xml.

  1. В файле AndroidManifest.xml добавьте следующий дочерний элемент к элементу <application>, вставив его перед закрывающим тегом </application>:
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="YOUR_API_KEY"/>
        

    Укажите свой ключ API для YOUR_API_KEY в атрибуте value. Данный элемент устанавливает для ключа com.google.android.geo.API_KEY значение ключа API.

  2. Сохраните AndroidManifest.xml и повторно выполните сборку приложения.

Примечание. Как показано выше, com.google.android.geo.API_KEY является рекомендуемым именем метаданных для ключа API. Ключ с таким именем может использоваться для аутентификации нескольких API-интерфейсов, созданных на основе Google Maps для платформы Android, включая Google Maps Android API. Для обеспечения обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY. Это устаревшее имя обеспечивает аутентификацию только для Android Maps API v2. Приложение позволяет указать только одно из имен в метаданных ключа API. Если указаны оба имени, API вызывает исключение.

Указание разрешений приложения

Укажите разрешения, которые необходимы для вашего приложения, добавив дочерние элементы <uses-permission> для элемента <manifest> в файле AndroidManifest.xml.

Разрешения на использование данных о местоположении

Если ваше приложение обращается к данным о текущем местоположении пользователя путем использования слоя My Location, вам необходимо запросить разрешения на использование данных о местоположении, как это описано в руководстве по работе с данными о местоположении.

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

Если ваше приложение предназначено для Google Play Services SDK версии 8.3 или более поздней, вам более не понадобится разрешение WRITE_EXTERNAL_STORAGE для использования Google Maps Android API.

Если же вы разрабатываете приложение для предыдущих версий Google Play Services SDK, вам следует запросить разрешение android.permission.WRITE_EXTERNAL_STORAGE.

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

Примечание. Если ваше приложение предназначено для API уровня 23 (Android 6.0), который требует использования разрешений для выполнения, ваше приложение должно быть предназначено для Google Play Services SDK версии 8.3 или более поздней.

Разрешения, автоматически добавляемые в манифест

Следующие разрешения определяются в манифесте служб Google Play и автоматически добавляются в манифест вашего приложения при сборке. Вам не нужно указывать их в манифесте явным образом.

  • android.permission.INTERNET – используется API-интерфейсом для загрузки листов карты с серверов Google Maps.
  • android.permission.ACCESS_NETWORK_STATE – позволяет API-интерфейсу проверять состояние подключения для определения возможности загрузки данных.

Указание OpenGL ES версии 2

Для обработки карты Google Maps Android API использует интерфейс OpenGL ES версии 2. Следующий параметр определяется в манифесте служб Google Play и автоматически добавляется в манифест вашего приложения при сборке. Вам не нужно указывать его в манифесте явным образом.

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

Это уведомит внешние службы о наличии данного требования. В частности, из-за этого магазин Google Play не будет отображать ваше приложение для устройств, которые не поддерживают OpenGL ES версии 2.

Добавление карты

Самым простым способом проверить, правильно ли выполнена конфигурация вашего приложения, является добавление простой карты.

Примечание. Этот код не должен использоваться в рабочем приложении.

  1. В activity_main.xml добавьте следующий фрагмент.

    <?xml version="1.0" encoding="utf-8"?>
    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
              android:id="@+id/map"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:name="com.google.android.m4b.maps.MapFragment"/>
    
  2. В MainActivity.java добавьте следующий код.

    package com.example.mapdemo;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    public class MainActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    }
    

Создание и запуск приложения

Соберите и запустите свое приложение. Должна отобразиться карта.

Устранение неполадок

  • Если карта не отображается, проверьте, выполнили ли вы все шаги, описанные ранее в этом документе. В частности, убедитесь, что вы используете правильный ключ API, а ваша учетная запись активирована для службы Google Maps Mobile SDK for Work.

  • Если количество методов, используемых в вашем проекте, превышает установленный лимит, появится следующая ошибка:

    Unable to execute dex: method ID not in [0, 0xffff]: 65536

    Информацию о причинах и решениях см. в руководстве для разработчиков приложений Android в разделе об использовании более 65 тысяч методов для сборки приложений.

  • Если в вашем проекте уже используется Guava, могут возникнуть ошибки конфликта классов, например, такие:

    com.android.dex.DexException: Multiple dex files define Lcom/google/common/annotations/Beta

    Чтобы устранить эту проблему, попробуйте удалить копию Guava из каталога google-maps-sdk-m4b_lib/libs.

Дополнительная информация

Миграция существующего приложения

Интерфейс Android API, который предлагается вместе с Google Maps Mobile SDK for Work, очень похож на стандартный Google Maps Android API. Следовательно, процесс миграции не должен вызвать затруднений.

  1. Загрузите Google Maps Android API для Google Maps Mobile SDK for Work и добавьте пакет SDK в проект, как описано выше.
  2. Замените все ссылки на пакет com.google.android.gms.maps, указав вместо них com.google.android.m4b.maps.
  3. Добавьте ко всем ссылкам на атрибуты макетов XML префикс m4b_. Например: m4b_mapType и m4b_cameraZoom.
  4. Создайте новый ключ API для своего проекта и добавьте его в AndroidManifest.xml, как это описано в руководстве по аутентификации.
  5. Скомпилируйте приложение.

Сравнение версий

В следующей таблице приводится описание основных различий между использованием стандартного Google Maps Android API и использованием API, который доступен с Google Maps Mobile SDK for Work.

  Стандартный Google Maps Android API Google Maps Mobile SDK for Work
Название пакета com.google.android.gms.maps com.google.android.m4b.maps
Атрибуты XML в файле макета Используйте имя атрибута без префикса. Например: mapType. Добавьте ко всем именам атрибутов префикс m4b_. Например: m4b_mapType. Более подробную информацию см. в документации с описанием атрибутов XML.
Каталог загрузки Входит в состав служб GooglePlay. Доступен в виде статической библиотеки.
Каналы поддержки Поддержка сообщества Доступ к поддержке премиум-уровня
Условия использования Регулируется условиями использования Google Maps APIs. Регулируется условиямиGoogle Maps Mobile SDK for Work использования .

Службы Google Play

Для стандартного Google Maps Android API требуется наличие как APK служб Google Play, так и клиентской библиотеки служб Google Play. Однако при использовании с Google Maps Mobile SDK for Work пакет SDK требует лишь установки APK служб Google Play на целевом устройстве – клиентская библиотека не требуется.

При миграции вашего приложения на Google Maps Mobile SDK for Work не требуется удалять пакет SDK служб Google Play из проекта. Однако вам следует удалить все ссылки на пакет com.google.android.gms.maps. Службы Google Play включают в себя версию Google Maps Android API, а также другие службы Google. Если вы настроите службы Google Play в своем приложении для использования других API-интерфейсов Google, убедитесь, что вы используете только Google Maps Mobile SDK for Work SDK (пакет com.google.android.m4b.maps) для доступа к Google Maps.

Хотя клиентская библиотека служб Google Play не требуется, может быть полезно добавить ее, чтобы иметь возможность использовать другие Google API, например, Google+ или Location API.

Пример кода

Репозиторий Google Maps на GitHub содержит ряд примеров, иллюстрирующих использование Google Maps Android API в приложении для Android. Обратите внимание, что примеры приложений используют пакет com.google.android.gms.maps, а не com.google.android.m4b.maps, который используется с Google Maps Mobile SDK for Work. Для примеров приложений также требуется SDK служб Google Play, так как они используют Location API для отдельных частей демонстрации.

Кроме того, на каждой странице этого руководства для разработчиков приведены фрагменты кода.

Документация

Основным источником информации о Google Maps Mobile SDK for Workявляется документация для разработчиков и справочная документация, доступная на нашем веб-сайте.