旧版 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 Plan2016 年 1 月上市发售)的客户。

概览

按照此页说明下载 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 APIs”)和网址: 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 文档中有关命令行使用的说明。

Google Maps Mobile SDK for Work 的 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 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:将 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 方法。

获取 API 密钥并将其添加到您的应用 按照下面的说明,为您的项目生成一个 API 密钥并将密钥添加到 AndroidManifest.xml 中。

您需要设置一个 Android 特定的 API 密钥

您的 API 密钥确定您作为 Google Maps Mobile SDK for Work 客户的身份,并且使您能够获取支持和为您的应用购买配额。

您可以结合使用您应用的软件包名称及其数字证书,在已启用 Google Maps Mobile SDK 服务的帐号上生成 API 密钥。

API 密钥以应用数字证书的简要形式为基础。 所有 Android 应用均使用您持有私有密钥的数字证书签署。 (有关数字证书的详细信息,请参阅签署您的应用的 Android 指南。)

显示应用的证书信息

Android API 密钥限制以应用数字证书(即其 SHA-1 指纹)的简要形式为基础。

从 Android Studio 获取证书信息

如果您按照 Google Maps Android API 入门指南中的指示操作,Android Studio 会创建一个包含应用凭据的简单 google_maps_api.xml 文件。

请选择以下方法之一从 Android Studio 中获取您的 API 密钥:

  • 最简单、快捷的方法:使用 Android Studio 为您创建的 google_maps_api.xml 文件中提供的链接:
    1. 复制 google_maps_api.xml 文件中提供的连接,然后将其粘贴到您的浏览器中。该链接跳转至 Google API Console 并通过网址参数向 Google API Console 提供所需的信息,从而减少所需的手动输入。
    2. 按照说明在 Google API Console 上新建一个项目,或者选择某个现有项目。
    3. 为您的项目创建受 Android 限制的 API 密钥。
    4. 复制生成的 API 密钥,返回 Android Studio,并将该 API 密钥粘贴到 google_maps_api.xml 文件中的 <string> 元素中。
  • 速度稍慢的方法:使用 Android Studio 为您创建的 google_maps_api.xml 文件中提供的凭据:
    1. 复制 google_maps_api.xml 文件中提供的凭据。
    2. 转至浏览器中的 Google API Console
    3. 使用所复制的凭据将您的应用添加至某个现有的 API 密钥,或者新建一个 API 密钥。

自己获取证书信息

如果您未按照入门指南中的指示创建应用,则需要自己获取证书的 SHA-1 指纹。首先请确保使用的证书正确。您可能有两个证书:

  • 调试证书:Android SDK 工具会在您执行调试生成阶段时自动生成此证书。此证书只能用于要测试的应用。请勿尝试发布使用调试证书签署的应用。Android 开发者文档中的在调试模式下签署部分详细介绍了调试证书。
  • 发布证书:Android SDK 工具会在您执行版本生成阶段时自动生成此证书。您也可以使用 keytool 程序生成此证书。如果您已准备好向外界发布应用,请使用此证书。

按照下面的步骤,结合使用 keytool 程序与 -v 参数来显示证书的 SHA-1 指纹。如需了解有关 Keytool 的详细信息,请参阅 Oracle 文档

调试证书

显示调试证书指纹

  1. 找到您的调试密钥库文件。该文件的文件名为 debug.keystore,在您首次构建项目时创建。默认情况下,它与 Android Virtual Device (AVD) 文件存储在同一目录下:

    • macOS 和 Linux~/.android/
    • Windows Vista 和 Windows 7C:\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 和 Windows7,请运行:

      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 Cloud Support 团队在您注册 Google Maps Mobile SDK for Work 时会启用 Google Maps Mobile SDK 服务。

新项目会启用这一服务。 然后,您可以从 Google API Console 获取 API 密钥。

注:只有此项目的初始所有者才能看到 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 或 Google Maps for Work 或 Google Maps 开头。 如果您还没有购买该 SDK 的访问权限,请联系[销售]。

  3. Dashboard 上的 APIs 列表中,检查是否已启用 Google Maps Mobile SDK

从 Google API Console 中获取 API 密钥 为您的项目启用 Google Maps Mobile SDK for Work 服务后,您必须生成一个新的密钥。

  1. 转到 Google API Console 的 Credentials 页面并登录您的 Google 帐号。

  2. 选择在您订购 Google Maps Mobile SDK for Work 时为您创建的 Google Maps Mobile SDK for Work 项目。

该项目名称以 Google Maps APIs for Business 或 Google Maps for Work 或 Google Maps 开头。 如果您还没有购买该 SDK 的访问权限,请联系[销售]。

  1. API keys 列表中,查找具有 Android 限制的密钥。
  2. 如果您的项目没有 Android 特定的 API 密钥,请立即通过选择 Create credentials > API key 创建一个。

  3. 在结果对话框中,选择 Restrict key

  4. 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

  5. 点击 Save

    Android 特定的新 API 密钥会显示在项目的 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 密钥替代 value 属性中的 YOUR_API_KEY。该元素会将密钥 com.google.android.geo.API_KEY 设置为您的 API 密钥的值。

  2. 保存 AndroidManifest.xml 并重新编译您的应用。

:如上所示,com.google.android.geo.API_KEY 是建议使用的 API 密钥元数据名称。可使用具有该名称的密钥向 Android 平台上的多个基于 Google Maps 的 API(包括 Google Maps Android API)验证身份。出于向后兼容性上的考虑,该 API 还支持 com.google.android.maps.v2.API_KEY 名称。该旧有名称只允许向 Android Maps API v2 验证身份。应用只能指定其中一个 API 密钥元数据名称。如果两个都指定,API 会抛出异常。

指定应用权限

通过在 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 Mobile SDK for Work 服务。

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

    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 副本。

更多信息

如何迁移现有应用

Google Maps Mobile SDK for Work 中的 Android API 在设计上与标准的 Google Maps Android API 非常相似。

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

  1. 下载 Google Maps Mobile SDK for Work 中的 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 与使用Google Maps Mobile SDK for Work 中的 API 之间的关键区别。

  标准 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 属性的文档
下载位置 包含在 Google Play 服务中 作为静态内容库提供。
支持渠道 基于社区的支持 获取高级支持
条款 适用 Google Maps APIs 服务条款 适用 Google Maps Mobile SDK for Work 条款

Google Play 服务

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

将应用迁移到 Google Maps Mobile SDK for Work 时,您不需要从项目中移除 Google Play 服务 SDK。

不过,您应移除对 com.google.android.gms.maps 软件包的任何引用。 Google Play 服务包含一个版本的 Google Maps Android API 和其他 Google 服务。 如果您在应用中通过 Play 服务来使用其他 Google API,请确保您仅使用 Google Maps Mobile SDK for Work 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 软件包,而不是与 Google Maps Mobile SDK for Work 搭配使用的 com.google.android.m4b.maps

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

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

文档

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