一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps SDK for iOS

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps SDK for iOS
  3. 创建相应密钥
继续

Google Maps URL 架构

您可以使用 Google Maps URL 架构启动 iOS 版 Google Maps 应用,并进行搜索,获取路线请求,并显示地图视图。 启动 Google Maps 时,系统会将您的捆绑包标识符作为请求的一部分自动发送。

概览

URL 架构允许您从另一个 iOS 应用或某个 Web 应用启动原生 iOS 应用。 您可以在将要传递给所启动应用的 URL 中设置选项。 iOS 版 Google Maps 应用支持以下 URL 架构:

  • comgooglemaps://comgooglemaps-x-callback:// – 这些架构允许您启动 iOS 版 Google Maps 应用,并执行下列几项操作之一:

    • 以指定的缩放级别显示指定位置的地图。
    • 搜索位置或地点,并将它们显示在地图上。
    • 请求从一个位置前往另一个位置的路线。 可以返回以下四种交通方式的路线:驾车、步行、骑自行车和乘坐公共交通工具。
    • 向您的应用添加导航。
    • 当应用完成后,使用 comgooglemaps-x-callback:// 发出一个回调。 回调经常用来使用户返回到最初打开 iOS 版 Google Maps 的应用。
  • comgooglemapsurl:// – 此架构允许您使用从桌面 Google Maps 网站得到的 URL 启动 iOS 版 Google Maps 应用。 这意味着您可以为用户提供原生移动体验,而不是简单地加载 Google Maps 网站。

    • 原始 URL 可以是 maps.google.com,或者 google.com/maps,也可以使用任何有效的国家代码顶级域名来代替 com。您还可以传递 goo.gl/maps 重定向 URL。
    • 您可以将 x-sourcex-success 参数与 comgooglemapsurl:// URL 架构结合使用来发出回调。

启动 iOS 版 Google Maps 应用,并执行一项特定功能

要启动 iOS 版 Google Maps 应用以及选择执行受支持的功能之一,请使用具有如下格式的 URL 架构:

comgooglemaps://?parameters

或者:

comgooglemaps-x-callback://?parameters

本文档中稍后将详细描述相关参数。

检查设备上是否已安装 Google Maps 应用

在将其中一个 URL 提供给您的应用中的某个用户之前,您应当先验证是否已安装该应用。 您的应用可以通过以下代码检查 URL 架构是否可用:

Swift

[[UIApplication sharedApplication] canOpenURL:
    [NSURL URLWithString:@"comgooglemaps://"]];

Objective-C

UIApplication.sharedApplication().canOpenURL(
    NSURL(string: "comgooglemaps://")!)

例如,如需显示纽约中央公园的地图,您可以使用以下代码:

Swift

if ([[UIApplication sharedApplication] canOpenURL:
     [NSURL URLWithString:@"comgooglemaps://"]]) {
  [[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic"]];
} else {
  NSLog(@"Can't use comgooglemaps://");
}

Objective-C

if (UIApplication.sharedApplication().canOpenURL(NSURL(string:"comgooglemaps://")!)) {
  UIApplication.sharedApplication().openURL(NSURL(string:
      "comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic")!)
} else {
  print("Can't use comgooglemaps://");
}

显示地图

使用 URL 架构可按指定的缩放级别显示指定位置的地图。 您也可以将其他视图叠放在您的地图之上,或显示 Street View 图像。

参数

下面所有的参数都是可选的。 如果没有设置任何参数,URL 架构将直接启动 iOS 版 Google Maps 应用。

  • center:这是地图视口中心点。 其格式为用逗号分隔的字符串 latitude,longitude
  • mapmode:设置所显示地图的种类。 可以设置为:standardstreetview。 如果未指定,则将使用当前的应用设置。
  • views:开启/关闭特定视图。 可以设置为:satellitetraffictransit。 可以使用逗号分隔符来设置多个值。 如果指定了不带任何值的参数,那么将清除所有的视图。
  • zoom:指定地图的缩放级别。

下面是一个示例 URL,它以纽约为中心、采用 14 级缩放级别来显示地图,且开启了交通视图:

comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic

纽约交通地图

一些其他的示例如下:

comgooglemaps://?center=37.788463,-122.392545&zoom=12
comgooglemaps://?center=46.414382,10.013988&mapmode=streetview

搜索

使用此架构在指定的视口位置显示搜索查询。

参数

除了用于显示地图的参数外,搜索还支持 q 参数。

  • q:用于搜索的查询字符串。

下面的示例 URL 用来在指定位置附近搜索“Pizza”:

comgooglemaps://?q=Pizza&center=37.759748,-122.427135

附近的 Pizza

一些其他的示例如下:

comgooglemaps://?q=Steamers+Lane+Santa+Cruz,+CA&center=37.782652,-122.410126&views=satellite,traffic&zoom=15
comgooglemaps://?q=Google+Japan,+Minato,+Tokyo,+Japan&center=35.660888,139.73073&zoom=15&views=transit

显示路线

使用此架构来请求并显示两个位置之间的路线。 您还可以指定交通方式。

参数

  • saddr:设置路线搜索的起点。 它可以是一个纬度、经度或查询格式的地址。 如果它是返回多个结果的查询字符串, 将选择第一个结果。 如果该值留空,那么将使用该用户的当前位置。
  • daddr:设置路线搜索的终点。 具有与 saddr 相同的格式和行为。
  • directionsmode:交通方式。 可以设置为:drivingtransitbicyclingwalking

以下示例 URL 用来显示 Google 纽约办事处与肯尼迪国际机场之间的交通路线:

comgooglemaps://?saddr=Google+Inc,+8th+Avenue,+New+York,+NY&daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York&directionsmode=transit

公共交通路线

一些其他的示例如下:

comgooglemaps://?saddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA+94043&daddr=Google+Inc,+345+Spear+Street,+San+Francisco,+CA&center=37.422185,-122.083898&zoom=10
comgooglemaps://?saddr=2025+Garcia+Ave,+Mountain+View,+CA,+USA&daddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA,+United+States&center=37.423725,-122.0877&directionsmode=walking&zoom=17

指定回调 URL

如果您想指定一个回调 URL,需要使用 comgooglemaps-x-callback:// URL 架构。 此架构遵循 [x-callback-url 规范]。 当您通过此架构调用 iOS 版 Google Maps 应用时,该应用将在屏幕顶部显示一个按钮。

点按此按钮会发出对您已指定的 URL 的回调。

comgooglemaps-x-callback:// 的请求必须采用以下格式:

comgooglemaps-x-callback://?parameters

参数

x-callback URL 架构接受与 comgooglemaps:// URL 架构相同的参数,此外还具有以下附加参数。 这两个参数都是必填的。

  • x-source – 发送 x-callback 请求的应用的名称。 最好使用短名称。
  • x-success – 完成时调用的 URL。 通常,这是您自己的应用的 URL 架构,可以让用户返回到原来的应用。

请注意,您的应用必须注册自己的 URL 架构,以便能够响应此回调 URL。

  1. 确保您的应用已注册了可以响应回调请求的 URL 架构。
  2. 将回调按钮的标签传入 x-source 参数。
  3. 将回调 URL 传入 x-success 参数。

以下示例将启动 iOS 版 Google Maps 应用,并以纽约为中心显示地图。 该应用还会显示标有“SourceApp”的按钮。 当点击“SourceApp”按钮时,iOS 版 Google Maps 应用将发出一个指向虚拟的 URL 架构的回调, sourceapp://?resume=true.

comgooglemaps-x-callback://?center=40.765819,-73.975866&zoom=14
   &x-success=sourceapp://?resume=true
   &x-source=SourceApp

comgooglemaps:// URL 架构一样,您应该首先验证设备上是否安装了 iOS 版 Google Maps 应用,以及该应用是否支持 x-callback URL 架构。您的应用可以通过以下代码检查 URL 架构是否可用:

Swift

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemaps-x-callback://"]];

Objective-C

UIApplication.sharedApplication().canOpenURL(
    NSURL(string: "comgooglemaps-x-callback://")!)

以下 URL 示例可让用户在搜索 dessert 后返回到某个应用。

comgooglemaps-x-callback://?q=dessert&center=37.759748,-122.427135
   &x-success=sourceapp://?resume=true
   &x-source=Nom+Nom

向您的应用添加导航

通过路线请求启动 iOS 版 Google Maps 应用是让用户从您的应用访问转弯提示导航的一种简便方法。 您可以使用 comgooglemaps://comgooglemaps-x-callback:// URL 架构。

注:通过 x-source 参数添加的按钮不会显示在转弯提示导航 UI 中。

下面这段代码展示了如何使用 comgooglemaps-x-callback:// 架构来请求路线,然后在您的用户准备就绪后返回到您的应用。 该代码将执行以下操作:

  1. 验证 comgooglemaps-x-callback:// URL 架构是否可用。
  2. 启动 iOS 版 Google Maps 应用,并请求前往纽约市肯尼迪国际机场的路线。 将起始地址留空即可请求从用户的当前位置出发的路线。
  3. 将标记为“AirApp”的按钮添加到 iOS 版 Google Maps 应用中。 该按钮标签由 x-source 参数定义。
  4. 当用户点击返回按钮时,调用虚拟 URL 架构 sourceapp://,。

相关代码如下所示。

NSURL *testURL = [NSURL URLWithString:@"comgooglemaps-x-callback://"];
if ([[UIApplication sharedApplication] canOpenURL:testURL]) {
  NSString *directionsRequest = @"comgooglemaps-x-callback://" +
      @"?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
      @"&x-success=sourceapp://?resume=true&x-source=AirApp";
  NSURL *directionsURL = [NSURL URLWithString:directionsRequest];
  [[UIApplication sharedApplication] openURL:directionsURL];
} else {
  NSLog(@"Can't use comgooglemaps-x-callback:// on this device.");
}

从 Google Maps 桌面 URL 启动 iOS 版 Google Maps 应用

如果您的应用可以访问预先存在的 Google Maps URL,例如在网页上或数据库中,您可以使用以下架构在 iOS 版 Google Maps 应用中打开该 URL,从而给您的用户提供最佳的原生体验。

  1. http://https:// 架构替换为 comgooglemapsurl://.。
  2. 如果您想使用回调,请加入 x-sourcex-success 参数。 此架构遵循 [x-callback-url 规范]。

支持的 Google Maps URL 格式

comgooglemapsurl:// 架构支持符合以下正则表达式的 URL,其中 {TLD} 指的是任何有效的国家代码顶级域名。 添加了换行符以使结构更加清晰:

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

检查是否已安装 Google Maps 应用

首先验证设备上是否安装了 iOS 版 Google Maps 应用,以及该应用是否支持 URL 架构:

Swift

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemapsurl://"]];

Objective-C

UIApplication.sharedApplication().canOpenURL(
    NSURL(string: "comgooglemapsurl://")!)

示例

通用 Google Maps URL 示例:

原来的 Google Maps URL:

https://www.google.com/maps/preview/@42.585444,13.007813,6z

使用 URL 架构:

comgooglemapsurl://www.google.com/maps/preview/@42.585444,13.007813,6z

通用 Google Maps URL 示例:

原来的 Google Maps URL:

https://maps.google.com/?q=@37.3161,-122.1836

使用 URL 架构:

comgooglemapsurl://maps.google.com/?q=@37.3161,-122.1836

通过 x-callback 请求前往东京铁塔的路线示例:

原来的 Google Maps URL:

http://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1

以下示例将根据原来的 Google Maps URL(见上面)中所指定的内容,启动 iOS 版 Google Maps 应用,并显示带有前往东京铁塔的路线的地图。 该应用还会显示标有“SourceApp”的按钮。 当点击“SourceApp”按钮时,iOS 版 Google Maps 应用将发出一个指向虚拟的 URL 架构的回调, sourceapp://?resume=true.

comgooglemapsurl://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1
    &x-source=SourceApp
    &x-success=sourceapp://?resume=true

发送以下问题的反馈:

此网页
Google Maps SDK for iOS
Google Maps SDK for iOS
需要帮助?请访问我们的支持页面