Android 版高级计划使用入门

注意:Google Maps Platform 高级计划不再适用于注册客户或新客户。

您的 Google Maps Platform 高级计划许可能够为 Maps SDK for Android 提供增强型支持。本文档介绍了如何使用高级计划中包含的 Maps SDK for Android 创建 Android 应用。

概览

按照本页面上的说明下载 SDK、设置项目并添加地图。下面概要列出了所需步骤:

  1. 下载 SDK。
  2. 将 SDK 添加到新的或现有的 Android 项目。
  3. 将您的 API 密钥添加到应用清单。
  4. 指定所需的 Android 权限和 OpenGL ES 第 2 版。
  5. 添加地图。

下载 SDK

您可以将 SDK 作为静态库下载,也可以使用 Android SDK 管理器下载。

方法 1:将 SDK 作为静态库下载

将最新版本作为静态库下载。

方法 2:使用 Android SDK 管理器下载 SDK

在 Android Studio 中:

  1. 依次选择 Tools > Android > SDK Manager
  2. 然后依次选择 Appearance & Behavior > System Settings > Android SDK
  3. 点击 SDK Update Sites 标签页。
  4. 点击加号 (+) 图标,添加新网站。
  5. 输入名称(例如“Google Maps for Work”)和网址: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 管理器作为独立工具使用,请参阅有关 Android SDK 管理器的指南。

将 SDK 添加到您的项目

下面的说明适用于 Android Studio。如果您使用的是其他工具,请参阅 Android 文档中有关命令行用法的说明。

高级计划中包含的 Maps SDK for Android 有两种格式:aar 软件包 (google-maps-sdk-m4b.aar) 和库模块 (google-maps-sdk-m4b_lib)。您可以选择最适合自己的格式。

方法 1:从 aar 软件包导入 SDK

按照以下步骤将 aar 软件包 (google-maps-sdk-m4b.aar) 添加到 Android Studio 项目中:

  1. 在以下位置找到 Google Maps Platform 高级计划:

    <android-sdk>/extras/google/maps_for_business_sdk

  2. google-maps-sdk-m4b.aar 文件复制到项目的 libs 目录中(如果目录不存在,就创建一个)。

  3. 将以下代码添加到应用的 build.gradle 文件中:

    dependencies {
        implementation(name:'google-maps-sdk-m4b', ext:'aar')
        implementation 'com.android.support:support-v4:+'
        implementation 'com.android.support:appcompat-v7:+'
        implementation 'com.google.android.gms:play-services-basement:15.0.1'
        implementation 'com.google.android.gms:play-services-base:15.0.1'
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. 在应用的 build.gradle 文件中,将 compileSdkVersion 设置为最新版本。

  5. 按照下文所述,完成配置步骤。

方法 2:将 SDK 作为库模块导入

除了使用 aar 文件之外,您还可以按照以下步骤将 SDK 库模块 (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 文件中:

    dependencies {
        implementation project(':googlemapssdkm4b_lib')
        implementation 'com.android.support:support-v4:+'
        implementation 'com.android.support:appcompat-v7:+'
        implementation 'com.google.android.gms:play-services-basement:15.0.1'
        implementation 'com.google.android.gms:play-services-base:15.0.1'
    }
    
  8. 在应用的 build.gradle 文件中,将 compileSdkVersion 设置为最新版本。

转换使用 Google Play 服务的所有现有配置

  1. 如果您的现有应用使用 Google Play 服务,请将对 com.google.android.gms.maps 软件包的所有引用替换为 com.google.android.m4b.maps
  2. 为对 XML 布局属性的所有引用添加前缀 m4b_。例如:m4b_mapTypem4b_cameraZoom

在应用清单中指定设置

使用 Maps SDK for Android 的 Android 应用需要在其清单文件 AndroidManifest.xml 中指定以下设置:

API 密钥

按照身份验证指南中的步骤为您的项目生成 API 密钥并将密钥添加到 AndroidManifest.xml

权限

通过将 <uses-permission> 元素添加为 AndroidManifest.xml<manifest> 元素的子元素,指定应用所需的权限。

位置权限

如果您的应用通过启用“我的位置”图层来访问用户的当前位置,您必须按位置数据指南中所述的方式请求位置权限

外部存储权限

如果您定位到 8.3 版或更高版本的 Google Play 服务 SDK,则使用 Maps SDK for Android 时不再需要 WRITE_EXTERNAL_STORAGE 权限。

如果您定位到更低版本的 Google Play 服务 SDK,则必须请求 android.permission.WRITE_EXTERNAL_STORAGE 权限。

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

注意:如果您的应用以需要使用运行时权限的 API 级别 23 (Android 6.0) 为目标平台,则应定位到 8.3 版或更高版本的 Google Play 服务 SDK。

自动合并到清单文件中的权限

以下权限在 Google Play 服务清单中定义,它们会在构建时自动合并到您应用的清单中。您需要将它们明确添加到清单中:

OpenGL ES 第 2 版

Maps SDK for Android 使用 OpenGL ES 第 2 版来渲染地图。以下设置在 Google Play 服务清单中定义,并会在构建时自动合并到应用的清单中。您不需要将其明确添加到清单中:

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

此设置会将此要求告知外部服务。具体来说,它可防止 Google Play 商店在不支持 OpenGL ES 第 2 版的设备上显示您的应用。

添加地图

若要测试应用是否配置正确,最简单的方法就是添加简易地图。

  1. activity_main.xml 中,添加以下 Fragment。

    <?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 Platform 高级计划服务。

  • 如果项目中的方法数量超过限制,您可能会收到一条错误消息:

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

    如需了解相关原因和解决方案,请参阅有关构建方法数超过 65K 的应用的 Android 开发者指南。

  • 如果您的项目依赖于 Guava,您可能会收到如下所示的类冲突错误:

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

    为了解决此问题,您可以从 google-maps-sdk-m4b_lib/libs 目录中删除 Guava 副本。

更多信息

如何迁移现有应用

高级计划中包含的 Android API 在设计上与标准 Maps SDK for Android 非常相似。因此,迁移过程非常简单。

  1. 按照上述说明下载高级计划中包含的 Maps SDK for Android,然后将 SDK 添加到您的项目。
  2. 将对 com.google.android.gms.maps 软件包的所有引用替换为 com.google.android.m4b.maps
  3. 为对 XML 布局属性的所有引用添加前缀 m4b_。例如:m4b_mapTypem4b_cameraZoom
  4. 按照身份验证指南中的步骤为您的项目生成新的 API 密钥并将密钥添加到 AndroidManifest.xml
  5. 构建您的应用。

比较版本

下表说明了使用标准 Maps SDK for Android 和使用高级计划中所含 API 之间的主要区别。

  标准 Maps SDK for Android 高级计划
软件包名称 com.google.android.gms.maps com.google.android.m4b.maps
布局文件中的 XML 属性 使用不带前缀的属性名称。例如:mapType 为所有属性名称添加前缀 m4b_。例如:m4b_mapType。如需了解详情,请参阅有关 XML 属性的文档
下载位置 包含在 Google Play 服务中。 作为静态库提供。
支持渠道 基于社区的支持服务 获享高级支持服务
条款 遵守 Google Maps Platform 服务条款 遵守 Google Maps Platform 高级计划条款

Google Play 服务

使用标准 Maps SDK for Android 时,需要 Google Play 服务 APK 和 Google Play 服务 maps 客户端库 (com.google.android.gms:play-services-maps)。不过,使用 Google Maps Platform 高级计划中包含的 SDK 时,只需要在目标设备上安装 Google Play 服务 APK,不需要 maps 客户端库。

将应用迁移到高级计划时,您应该从项目中移除 maps 客户端库,以及对 com.google.android.gms.maps 软件包的所有引用。请确保您只使用高级计划中包含的 SDK(com.google.android.m4b.maps 软件包)来访问地图。

您可以随意添加其他 Google Play 服务客户端库,以便利用其他 Google API,例如 Google Analytics(分析)API 或 Google Location and Activity Recognition API。

示例代码

GitHub 上的 Google 地图代码库包含的许多示例说明了如何在 Android 应用中使用 Maps SDK for Android。请注意,示例应用使用的是 com.google.android.gms.maps 软件包,而不是用于高级计划的 com.google.android.m4b.maps 软件包。这些示例应用还需要 Google Play 服务 SDK,因为它们会在演示版应用的某些部分使用地理位置 API。

此外,您还可以在开发者指南的每个页面上找到代码段。

文档

关于 Google Maps Platform 高级计划的主要信息来源是我们网站其他地方提供的开发者指南和参考文档。