谷歌 Play服务SDK 之谷歌地图 API v2

最新推荐文章于 2024-10-07 14:42:11 发布

Tonyfield

最新推荐文章于 2024-10-07 14:42:11 发布

阅读量5.6k

点赞数

分类专栏： Android 官网翻译 Android

Android 同时被 2 个专栏收录

49 篇文章 1 订阅

订阅专栏

Android 官网翻译

6 篇文章 1 订阅

订阅专栏

概述

建立一个有关谷歌地图 Android API v2的应用需要很多步骤。对于每个项目而言，其中很多步骤只需要做一遍，而再建立类似项目的话你将轻车熟路。同时有些步骤对于使用Google Play服务SDK的情况同样适用。步骤如下：

下载及配置谷歌 Play 服务 SDK。Google 地图 Android API 是其中一部分，具体可以参考 http://blog.csdn.net/tonyfield/article/details/8576988。
获得一个 API 密钥。为此你将需要在 Google APIs 平台注册一个项目，并为你的应用取得一个签名证书。
在应用AndroidManifest.xml 中指定设置。
在你的Android项目中加入地图。
完成，可以发布你的应用了!

要是你想先看看例程代码作为起步，你可以在谷歌Play服务SDK中找到。

获取谷歌地图 Android API v2

要使用谷歌 Play 服务，首先你要安装Google Play 服务 SDK，打开Android SDK Manager，选择“Google Play services”后点击“install packages...”。具体可以参考 http://blog.csdn.net/tonyfield/article/details/8576988。

谷歌地图 API 密钥

注意: 谷歌地图 Android API v2 使用新的密钥管理系统。MapView作为以前的 Google Maps Android v1 的应用密钥，在API v2中将不再有效。

为了用谷歌地图API 访问谷歌地图服务器，你必须在你的应用中加入地图 API 密钥。这个密钥是免费的，你能在自己的任何调用谷歌地图API的应用程序中使用它，并且它不限使用用户数量。为了获得API密钥，你要向谷歌 APIs Console 提供你的应用的签名证书和它的包（package）名称，一旦你有了密钥，你就可以将它以 meta-data元素的形式加入你应用的manifest 文件（AndroidManifest.xml）。

这需要你有一些Android应用发布的知识。简而言之，所有Android应用在发布前都必须用一个数字证书签名，而你作为发布者（不一定是开发者）拥有这个数字证书的私钥。由于数字证书是唯一的，所以它可以作为唯一识别你的应用的简单途径。这也是用于跟踪你的应用（如果谷歌Play Store）或是用于跟踪你应用正在使用的谷歌资源（如果谷歌地图服务器）。

注意: 更多数字签名知识请参考给你的应用签名。

地图 API 密钥keys are linked to specific certificate/package pairs, rather than tousers or applications. You only need one key for each certificate, no matter how many users youhave for an application. Applications that usethe same certificate can use the same API key. However, the recommendedpractice is to sign each of your applications with a different certificate andget a different key for each one.

Obtaining a key for your application requires several steps. These steps areoutlined here, and described in detail in the following sections.

Retrieve information about your application's certificate.
Register a project in the Google APIs Console and add the Maps API as a service for the project.
Once you have a project set up, you can request one or more keys.
Finally, you can add your key to your application and begin development.

显示证书信息

Maps API密钥是基于你的应用数字证书的一个缩写形式，被称为其SHA-1 指纹。这个指纹是由SHA-1哈希算法生成的唯一字符串。由于指纹本身（在统计意义上而言）是独一无二的，google Maps 用它作为识别你的应用的途径。

在显示你的证书的 SHA-1 指纹之前，你要确信你已经有了一个证书。证书有两种，Debug证书和 Release 证书。

Debug 证书: 当你调试程序时，Android SDK 工具自动生成这个证书。这个证书仅限用于你在测试的程序，你不能用它来发布版本。更多细节可参考在调试模式中的签名。你可以由这个证书生成API密钥，但仅能用于测试，不能用于产品发布。
Release证书: 当你用 Ant 或 Eclipse 编译一个release版本时，Android SDK 工具生成这个证书，生成时，Ant 或 Eclipse会引导你输入必要信息。你也能用keytool 程序在命令行生成release证书，它能被用来发布你的应用。一旦你有了完整的release 证书你就能用 keytool 显示其 SHA-1 指纹。
关于Keytool工具更多信息，参考 http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html.

显示 debug 证书指纹

找到你的 debug keystore 文件。文件名是 debug.keystore。其默认路径和 Android Virtual Device (AVD) 文件一致：
- OS X and Linux: ~/.android/
- Windows Vista and Windows 7: C:\Users\your_user_name\.android\
如果你用的是 Eclipse 的ADT，并且你不能确定你的 debug keystore 是不是还在默认路径下，你可以选择 Windows >Prefs > Android > Build 来获得全路径。

列出 SHA-1指纹

对于 Linux 或OS X，打开终端窗口，输入下列命令：

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

对于Windows Vista 和 Windows 7，运行：

keytool -list -v -keystore "C:\Users\your_user_name\.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

以 SHA1开始的行含有证书的 SHA-1 指纹。指纹是 20 个以冒号隔开的2位16进制数字。

显示 release证书指纹

Locate your release certificate keystore file. There is no default location or name for the release keystore. If you don't specify one when you build your application for release, the build will leave your.apk unsigned, and you'll have to sign it before you can publish it. For the release certificate, you also need the certificate's alias and the passwords for the keystore and the certificate. You can list the aliases for all the keys in a keystore by entering:
```
keytool -list -keystore your_keystore_name
```
Replace your_keystore_name with the fully-qualified path and name ofthe keystore, including the.keystore extension. You'll be prompted forthe keystore's password. Once you enter it,keytool displays all thealiases in the keystore.
在命令行窗口输入下列命令：
```
keytool -list -v -keystore your_keystore_name -alias your_alias_name
```
Replace your_keystore_name with the fully-qualified path and name ofthe keystore, including the.keystore extension. Replaceyour_alias_name with the alias that you assigned to the certificatewhen you created it.

Caution: To protect your keystore and key, don't enter thestorepass or keypass arguments on the command line unless you're confident of your computer's security. For example, on a public computer, someone could look at your terminal window history or list of running processes, get the password, and then have write access to your signing certificate. This would allow that person to modify or replace your application with their own.

你应该看到类似下列输出：

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 个以冒号隔开的2位16进制数字。

创建一个 API 项目

一旦你有了自己的签名证书指纹，就可以在谷歌APIs Console上为你的应用创建或修改一个项目，并为地图API注册。为此你需要执行以下步骤。

登录谷歌 APIs Console页面。
- 如果你之前从没用过谷歌 APIs Console ，你将被提示创建一个项目，你可以用它来跟踪你对谷歌地图Android API 的使用情况。点击 Create Project，Console 会创建一个称为 API Project 的新项目。下一步这个名字出现在左上角。要重命名及管理该项目，可点击它的名字。
- 如果你使用过谷歌 APIs Console ，你将马上看到一个存在项目的列表以及有效的服务。为谷歌地图 Android API使用一个新的项目始终是个好主意，所以选择左上角的项目名并点击Create。
你应该会在主窗口看到一个 APIs 及 services 的列表，如果没有，从左侧导航栏选择 Services。
在页面中央位置显示的services列表中向下滚动，直到你看到 Google Maps Android API v2。在偏右侧位置点击开关按钮，使之处于开启（on）状态。
这里有谷歌地图 Android API 服务条款。要是你同意该条款，点击服务条款下方的复选框，点击接受（Accept）。然后页面会返回到 APIs和services 列表。

你现在已经准备好获取一个地图API 密钥。

获得一个 API 密钥

如果你的应用是用 Google Maps Android API v2 服务注册的，那你能请求一个 API 密钥。它可以用于注册不止一个keyper项目。

为了获得该密钥:

在左侧导航栏点击 API Access。
在结果页面点击 Create New Android Key....

在对话框中输入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

Google APIs 控制台将会显示 Key for Android apps (with certificates) 跟随一个40字符的 API 密钥，如:
```
AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
```
复制这个值，你后面就要用到它。

在你的程序中添加 API 密钥

第一步就是要把这个 API 密钥添加到你程序的 manifest.xml。之后，Maps API 读取密钥值并将它传送到 Google Maps 服务器，服务器会确认是你在访问 Google Maps 数据，别忘了，你先前用于生成这个密钥而提交给Google的SHA-1指纹和应用包名，就是验证这一切的信息。

添加密钥到你的程序:

在 AndroidManifest.xml中添加如下元素作为 <application> 元素的子节点，插入点需要刚好在标识</application>之前:
```
<meta-data
    android:name="com.google.android.maps.v2.API_KEY"
    android:value="your_api_key"/>
```
your_api_key代表你的 API 密钥。这个元素设置键值 com.google.android.maps.v2.API_KEY 为your_api_key 并使 API 密钥对你程序中任意的MapFragment 可见。in your application.

在你的 manifest 中添加如下元素，用你的包名代替 com.example.mapdemo 。

        <permission
          android:name="com.example.mapdemo.permission.MAPS_RECEIVE"
          android:protectionLevel="signature"/>
        <uses-permission android:name="com.example.mapdemo.permission.MAPS_RECEIVE"/>

保存 AndroidManifest.xml 并重新编译程序。

设定程序的Manifest设置

一个使用 Google Maps Android API 的 Android 程序需要在其 manifest（AndroidManifest.xml）中设定以下设置:

地图应用中需要的访问权限。
程序需要 OpenGL ES version 2 支持的通知（notification）。外部服务能检测这个通知并进行相应动作。例如，Google Play Store 不会在不支持 OpenGL ES version 2 的设备上显示应用。
Maps API 密钥。密钥保证你已经在Google APIs 控制台注册了 Google Maps 服务。

设定权限

通过在<manifest>添加子节点<uses-permission>添加权限:

例如，为了请求互联网访问权限，添加：

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

为使用Google Maps Android API，以下权限必须添加:

android.permission.INTERNET 被API用来从Google Maps服务器下载地图块。
com.google.android.providers.gsf.permission.READ_GSERVICES 允许 API访问 Google 基于Web的服务。
android.permission.WRITE_EXTERNAL_STORAGE 允许 API 将地图块数据缓存在设备的外部存储区。

以下权限用于用户当前位置的定位，推荐使用，但如果你的程序不涉及这些应用，或是你希望通过My Location layer打开，可以不加。.

android.permission.ACCESS_COARSE_LOCATION 允许API 使用 WiFi 或电信cell 数据 (或都用)来定位设备位置。

android.permission.ACCESS_FINE_LOCATION 允许API 使用全球定位系统 (GPS) 来精确定位设备位置.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

需要 OpenGL ES version 2

因为 Google Maps Android API v2 需要 OpenGL ES version 2 的支持，你必须加入一个 <uses-feature> 元素作为 <manifest> 的子节点:

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

它通知外部服务需求，特别它有防止 Google Play Store 在不支持 OpenGL ES version 2 的设备上打开你应用的效果。

添加地图

完成上述步骤，你可以在你的应用程序里加入地图。

测试程序是否已正确配置最简易的方法是加入一个简单的地图。你要修改两个文件 main.xml 和 MainActivity.java。请注意以下测试代码仅对目标Android API 12及以上的应用程序有效果，该代码不应使用在产品应用中。如何加入更为健壮的代码请参考例程。

在 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"
  class="com.google.android.gms.maps.MapFragment"/>

在 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.main);
    }
}