Android 版高级计划使用入门

您的 Google Maps APIs Premium Plan许可可以为 Google Maps Android API 提供增强支持。 本文介绍如何通过Premium Plan 创建使用 Google Maps Android API 的 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 文档中有关命令行使用的说明。

Premium Plan的 Google Maps Android API 采用两种格式: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 APIs Premium Plan:

    <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:将 SDK 作为库模块导入

您可以按照下面的步骤操作,将 SDK 库模块 (google-maps-sdk-m4b_lib) 添加到 Android Studio 中的现有项目,而无需使用 aar 文件:

  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 方法。

在应用清单中指定设置

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

API 密钥

按照身份验证指南中所述,为您的项目生成一个 API 密钥并将密钥添加到 AndroidManifest.xml 中。

权限

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

位置权限

如果您的应用通过启用 My Location 层访问用户的当前位置,您必须按位置数据指南中所述请求位置权限

外部存储权限

如果您以 Google Play 服务 SDK 8.3 版或更高版本为目标,使用 Google Maps Android API 时不再需要 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),则以 Google Play 服务 SDK 8.3 或更高版本为目标。

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

以下权限在 Google Play 服务清单文件中定义,它们会在编译时自动合并到您的应用的清单文件中。您需要显式地将它们添加到清单文件中:

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 APIs Premium Plan 服务。

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

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

    如需了解有关原因和解决方法的信息,请参阅 Android 开发者指南配置方法数超过 65K 的应用

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

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

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

更多信息

如何迁移现有应用

Premium Plan中的 Android API 在设计上与标准的 Google Maps Android API 非常相似。

因此,迁移过程非常简单。

  1. 下载 Premium Plan 中的 Google Maps Android API,并按上文所述将 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 与使用Premium Plan中的 API 之间的关键区别。

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

Google Play 服务

标准 Google Maps Android API 同时需要 Google Play 服务 APK 和 Google Play 服务客户端内容库。 不过,如果与 Google Maps APIs Premium Plan搭配使用,SDK 仅需要在目标设备上安装 Google Play 服务 APK - 不需要客户端内容库。

将应用迁移到 Premium Plan时,您不需要从项目中移除 Google Play 服务 SDK。

不过,您应移除对 com.google.android.gms.maps 软件包的任何引用。 Google Play 服务包含一个版本的 Google Maps Android API 和其他 Google 服务。 如果您在应用中通过 Play 服务来使用其他 Google API,请确保您仅使用Premium Plan SDK(com.google.android.m4b.maps 软件包)访问地图。

尽管不需要 Google Play 服务客户端内容库,您仍可能发现添加该库非常有用,添加之后,您可以充分利用其他 Google API,例如 Google+ 或 Location API。

示例代码

GitHub 上的 Google 地图存储区包含的许多示例说明了如何在您的 Android 应用中使用 Google Maps Android API。

请注意,示例应用使用 com.google.android.gms.maps 软件包,而不是与 Premium Plan搭配使用的 com.google.android.m4b.maps

示例应用还需要 Google Play 服务 SDK,因为它们在部分演示中使用 Location API。

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

文档

有关 Google Maps APIs Premium Plan的主要信息来源为我们网站其他地方提供的开发者指南和参考文档。