开始使用Google Maps Android API v2（Getting Started）

最新推荐文章于 2024-07-01 15:36:24 发布

琴弦第七

最新推荐文章于 2024-07-01 15:36:24 发布

阅读量2.3k

点赞数

分类专栏： Android 文章标签： Android google maps Google Play services Google APIs Console

Android 专栏收录该内容

21 篇文章 0 订阅

订阅专栏

----------------------------------------------------------------------------------------------------------------------------------------------------------

原文作者：Google

原文地址：https://developers.google.com/maps/documentation/android/start

原文版权：Creative Commons 3.0 Attribution License

译文作者：Jianan - qinxiandiqi@foxmail.com

版本信息：本文基于2014-06-12版本翻译

译文版权：CC BY-NC-ND 4.0，允许复制转载，但必须保留译文作者署名及译文链接，不得演绎和用于商业用途

----------------------------------------------------------------------------------------------------------------------------------------------------------

前言

在你使用Google API进行开发之前，你需要下载API并确保你拥有一个Google Maps Android API v2 key。API和可以都是免费的。

1、Overview（概述）

创建一个可以使用google Maps Android API v2的android应用程序需要几个步骤。本章节中大部分步骤都只需要执行一次，但是有一部分步骤需要你在未来开发的程序中进行配置。整个安装map到Android应用程序的过程大致如下：

安装Android SDK。
下载并且配置好google Play services SDK，它包含了Google Maps Android API。如果你使用Google Maps Mobile SDK for Business，你需要下载并且配置google Maps Mobile SDK作为静态的商业库。
生成一个API Key。完成这个步骤需要你在Google APIs Console上注册一个project，并且为你的应用程序签署数字证书。
添加需要的权限请求到你应用程序的Manifest文件中。
添加一个map到你的应用程序。
发布你的程序。

你可能希望参考一些实例项目，它们包含在Google Play service SDK中。

2、Install the Android SDK（安装Android SDK）

作为一个前提条件，你需要安装Android SDK，安装方法请参考Get the Android SDK。

3、Install and configure the Google Play services SDK（安装并配置Google Play services SDK)

在本章节中，你需要为你的App创建一个android项目以完整的进行所有步骤。如果你从来没有创建过Android应用程序，你可以根据以下指南创建一个“Hello World”的应用程序。参考：Creating an Android Project.

Google Maps Android API v2已经集成为Google Play services SDK中的一部分，你可以通过Android SDK Manager去下载Google Play services SDK。

获取更多详细内容，请参考Google Play services文档。以下是你需要执行的步骤简单概括：

安装Google Play services SDK
添加Google Play services作为一个android库项目
链接Google Play services到你自己的应用作为依赖库。

Add the Google Play services version to your app's manifest（在你的manifest文件中添加Google Play services的版本号）

编辑你应用程序中的AndroidManifest.xml文件，并且添加以下声明到<application>标签中。嵌入的Google Play services版本号就是app将要编译进去的版本。

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

4、Get an Android certificate and the Google Maps API key（获取一个Android签名证书和Google Maps API key)

注意：Google Maps Android API v2使用了新的key生成系统。已经存在的用于MapView的Google Maps Android v1 Key，不能在API v2上正常使用。

使用Maps API去访问Google Maps服务器，你必须添加一个Maps API Key到你的应用程序中。这个Key是免费的，你可以在你若干个应用程序中使用它去调用Maps API，并且它支持不限量的用户。你可以从Google APIs Console上生成一个Maps API key，只要你提供你应用程序的指纹证书和它的包名。添加key到你的应用程序方法是在你应用程序的AndroidManifest.xml文件中添加一个标签。

考虑到注册你的应用程序并且生成一个key的过程需要你掌握一些Android推送进程和请求的知识。总的来说，所有的Android应用程序都必须使用一个你的私有数字证书进行签名。因为每一个数字证书都是唯一的，它们能够保证你的应用程序唯一性。这使得你能够在系统同中追踪你的应用程序，比如google paly store商店中。并且你也可以追踪你的应用程序使用的资源，比如google maps服务器。

注意：请参考Android Guide(Singing Your Application)以获取更多关于数字证书的信息。

决定一个Maps API Key的是一个具体的证书/包名键值对，而不是用户或者应用程序。你只需要为每一个证书申请一个Key，不无靠考虑你的应用程序有多少用户。使用相同数字证书的应用程序可以使用同一个API Key。但是，推荐的做法是为你的每一个应用程序使用不同的数字证书签名，并且使用对应不同证书的Key。

为你的应用程序生成一个Key需要若干步骤。这些步骤大致如下，后续章节中将会具体描述。

获取你应用程序的数字签名信息。
在Google APIs Console(Google APIs控制台)上注册你的项目，并且为你的项目添加Maps API服务。
申请一个或多个Key。
添加你的Key到你的应用程序中，然后开始开发。

注意：Google Maps Mobile SDK for Businesse的用户必须另外为他们的API项目enable the SDK。

4.1 Display your app's certificate information（查看你的应用程序的证书信息）

Maps API key是基于你应用程序数字证书的缩写生成的，被称为SHA-1指纹。这个指纹是一个通过广泛使用的SHA-1散列算法生成的字符串。因为这个指纹是唯一的，所以Google Maps使用它作为确认你应用程序的一种途径。

查看你的证书SHA-1指纹，首先你要确认使用了正确的数字证书。一般你会拥有两个数字证书：

Debug数字证书：当你从命令行终端“debug”编译项目，或者是使用Eclipse编译项目但没有指明作为发布版本输出时，Android SDK工具将会自动为你创建一个debug数字证书。只有使用这个证书签名的应用才能进行测试。不要尝试使用debug证书来签名一个发布版本的应用程序。在Android开发文档中的Singing in Debug Mode章节可以查看更详细的Debug证书内容。
Release数字证书。当你使用ant构建工具或者Eclipse以“release”编译项目的时候，Android SDK工具将会创建这个证书。你可以使用keytool程序来生成这个证书。当你要对外发布你的应用程序时，你需要使用这个证书来签名。

你可以使用keytool程序加上-v参数来查看一个证书的SHA-1指纹。更多关于Keytool的信息，可以查看文档http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html.

下面章节将描述详细查看debug或者release数字证书指纹方法：

4.1.1 Display the debug certificate fingerprint（查看debug数字证书指纹）

1、找出你的debug keystory文件位置。这个文件名为debug.keystore，它在你第一次编译你的项目时候被创建。默认情况下，它保存在你的Android虚拟机（AVD）文件所在的文件夹下：

* OS X或者Linux系统：~/.android/

* Window Vista或者Window 7：C:\Users\your_user_name\.android\

如果你使用Eclipse和ADT插件并且你不确定的debug keystore位置，你可以选择Window > Prefs > Android > Build来查看完整的路径，然后你可以复制出这个路径到文件管理器中找到包含keystore的文件夹。

2、列出SHA-1指纹：

* 在Linux或者OS X系统上，打开终端创建，输入以下命令：

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

* 在Windows Vista或者Window 7系统上，可以运行：

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

3、你将会看到类似的输出：

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

以SHA1开头的那一行就是成熟的SHA-1指纹，它由20个两位十六进制数组成。

4.1.2 Displaying the release certificate fingerprint（查看release证书指纹）

1、找出你的release证书keystore文件位置。release的keystore文件没有默认的位置或者名字。当你编译一个发布版本的应用时没有指定一个release证书，那么生成的.apk文件将没有签名。但是，你要发布应用的时候你必须要对它签名。对于release证书，你还需要证书的别名、keystore的密码和证书。你可以通过以下命令列出一个keystore中所有key的别名：

keytool -list -keystore your_keystore_name

使用包含完整路径和名字的keystore替换your_keystore_name，包括文件的.keystore后缀名。你会被要求输入keystore的密码，只要输入密码，keytool就会列出keystore中所有的别名（alias）。

2、在命令行终端中输入以下命令：

keytool -list -v -keystore your_keystore_name -alias your_alias_name

使用包含完整路径和名字的keystore替换your_keystore_name，包括文件的.keystore后缀名。将your_alias_name替换为你创建keystore时候提供给证书的alias.

警告：为了保护你的keystore和key，除非你确定你的计算机是安全的，否则不要在命令行上添加storepass或者keypass参数。例如，在一个公共计算机上，有些人可以查看你的终端历史或者列出正在运行的程序获得密码，还能访问你的签名证书。这将可能导致其他人能够修改或者替换你的应用程序。

3、你将会看到类似的输出：

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个两位十六进制数组成。

4.2 Create an API project in the Google APIs Console（在Google APIs控制台上创建一个API项目）

根据以下步骤到Google APIs控制台上为你的应用创建或者修改一个项目，并注册Maps API服务。

1、打开浏览器，导航到Google APIs Console

* 如果你从来没有使用过Google APIs Console，你将会被提示创建一个项目来跟踪控制你对Google Maps Android API的使用。点击Create Project，控制台将会创建一个新的API项目。进入下一页，这个名字将会出现在左上角。想要重命名或者更改设置，可以点击这个名字。

* 如果你已经使用过Google APIs Console，那么你将会立刻看到所有已存在项目的列表以及可使用的服务。仍然推荐是创建一个新的项目来使用Google Maps Android API，因此，选择左上角的项目名称，然后点击Create按钮。

2、你将会在主窗口上看到APIs的列表。如果没有，在左边导航栏上选择Services。

3、在中间services列表中，往下滑动直到你看见Google Maps Android API v2.在这个条目的右边，打开开关按钮让它处于on状态。

4、将会显示Google Maps Android API服务条款。如果你接收服务条款，勾选条款底部的选择框，然后点击Accept按钮。你将返回到APIs和服务列表。

4.2.1 Obtail a Google Maps API key（生成一个Google Maps API key）

如果你的应用已经注册了Google Maps Android API v2服务，你就可以申请API key。它允许你为一个项目申请多个key。

1、在Google APIs Console上导航到你的项目中。

2、在Services页面，确认“Google Maps Android API v2"条目是否打开。

3、在左边导航栏上，点击API Access。

4、在出来的界面上，点击Create New Android Key

5、在出来的对话框上，输入SHA-1指纹，添加分号”;“，然后添加应用程序的包名。例如：

BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75;com.example.android.mapexample

6、Google APIs Console将会发回一个40个字符的API key。例如：

AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0

4.2.2 Add the API key to your application

按照以下步骤添加API key到你应用程序的AndroidManifest.xml文件中。在这里，Maps API将会读取这个key值传递到Google Maps服务器上，服务器将会确认你是否有权限接受Google Maps数据。

1、在AndroidManifest.xml文件中，将下面标签作为子标签添加到<application>标签中：

<meta-data
    android:name="com.google.android.maps.v2.API_KEY"
    android:value="API_KEY"/>

将其中value属性值API_KEY替换为你的API key。这个标签将com.google.android.maps.v2.API_KEY的键值设置为你的API key，以便你程序中的一些MapFragment能够访问到你的API key。

2、保存AndroidManifest.xml并重新构建你的应用。

5、Specify app settings in the application manifest（在manifest文件中声明应用设置）

使用Google Maps Android API的应用需要在AndroidManifest.xml文件中声明以下设置：

一个Google Play services版本的引用。如果你按照本页面的步骤操作到这里，那么你已经在你的manifest文件中添加了这个声明。
这个应用的Maps API key。这个key表明你已经通过Google APIs Console注册了Google Maps服务。如果按照本页面的步骤操作到这里，那么你已经将API key添加到你的manifest文件中。
添加使用Android系统功能和访问Google Maps服务器的权限。具体查看下面关于权限设置的说明。
（推荐）声明应用要求使用OpenGL ES version 2.外部服务能够根据这个声明来采取相应的操作。例如，Google Play Store将不会在一些不支持OpenGL ES version 2的设备上显示这个应用。具体查看下面说明如果添加这个设置。

5.1 Specify permissions（指定权限）

通过在<manifest>标签下添加<uses-permission>子标签来指定你的引用需要的权限。语法如下：

<uses-permission android:name="permission_name"/>

例如，请求访问网络权限需要添加：

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

除了你的应用其它部分需要使用到的权限，你需要添加以下权限才能够使用Google Maps Android API：

* android.permission.INTERNET 用于API从Google Maps服务器上下载图块。

* android.permission.ACCESS_NETWORK_STATE 允许API去检查网络连接状态来判断是否能够下载数据。

* android.permission.WRITE_EXTERNAL_STORAGE 允许API在设备的外部存储卡上缓存地图图块数据。

以下权限是推荐添加的，但是如果你不需要通过编程或者允许我的位置层等方式访问用于当前的位置则可以忽略：

* android.permission.ACCESS_COARSE_LOCATION 允许API通过Wifi或者移动蜂窝数据（或者两者都有）来判断设备的位置。

* android.permission.ACCESS_FINE_LOCATION 允许API通过使用全球定位系统（GPS）来获取一个精确的设备位置。

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- The following two permissions are not required to use
     Google Maps Android API v2, but are recommended. -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

5.2 Specify requiremenet for OpenGL ES version 2（指定OpenGL ES version 2需求）

Google Maps Android API使用OpenGL ES version 2来渲染地图。如果设备不支持OpenGL ES version 2，你的地图将不会出现。我们推荐你在AndroidManifest.xml文件的<manifest>标签下添加以下<uses-feature>子标签：

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

这将会通知外部服务你的应用程序需求。特别的，这能够防止Google Play Store在不支持OpenGL ES version 2的设备上显示你的应用。

6、Add a map（添加地图）

一个简单的方法来测试你的应用已经正确配置好的方法就是添加一个简单的地图。你将会修改两个文件：定义应用布局的xml文件和main activity的java源文件。

注意一下代码只能够在应用程序的target系统版本在Android API 12或者更高的版本上测试。这段代码不能用于最终发布的产品应用。如何添加更加健壮的代码可以参考范例项目中的代码。

1、在应用的布局文件中添加以下Fragment。如果你使用Eclipse的ADT插件创建了”Hello World“项目，这个文件在res/layout/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.gms.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);
    }
}

3、编译运行你的应用。你将会看到一个地图。如果你没有看到地图，请确认你是否已经完成本页面描述的所有步骤。