在 Google Cloud 上使用 ARCore API

请选择平台： Android Unity (AR Foundation) iOS

Geospatial API 和云锚点等 ARCore 功能会使用托管在 Google Cloud 上的 ARCore API。使用这些功能时，您的应用会使用凭据来访问 ARCore API 服务。

本快速入门介绍如何设置应用，使其能够与 Google Cloud 上托管的 ARCore API 服务进行通信。

创建新的 Google Cloud 项目或使用现有项目

如果您已有项目，请选择该项目。

转到“项目选择器”

如果您还没有 Google Cloud 项目，请创建一个。

创建新项目

启用 ARCore API

如需使用 ARCore API，您必须在项目中启用它。

启用 ARCore API

设置授权方法

Unity 应用可以使用两种不同的授权方法与 ARCore API 通信：推荐方法为无密钥授权和 API 密钥授权：

• 在 Android 上，无密钥授权会结合使用应用的软件包名称和签名密钥的指纹来对您的应用进行授权。

  在 iOS 上，无密钥授权使用已签名的令牌来控制对 API 的访问。此方法要求您拥有的服务器签署令牌并控制对 API 的访问权限。

• API 密钥是用于标识 Google Cloud 项目的字符串。由于 API 密钥通常可供客户端访问，因此通常会被视为不安全。考虑使用无密钥授权与 ARCore API 通信。

无钥匙

如需使用无密钥身份验证为您的应用授权，请创建 OAuth 2.0 客户端 ID。

确定签名密钥指纹

OAuth 2.0 客户端 ID 使用应用的签名密钥指纹来识别您的应用。

重要提示 ：通常使用不同的签名密钥为应用签名。您必须为计划使用的每个签名密钥创建一个客户端 ID。通常，该密钥包括调试签名密钥和版本签名密钥。

如何获取调试签名指纹

在运行或调试项目时，Android SDK 工具会自动使用生成的调试证书为您的应用签名。

使用以下命令获取调试证书指纹。

Mac/Linux

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

Windows

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

keytool 实用程序会提示您输入密钥库的密码。调试密钥库的默认密码为 android。然后，keytool 实用程序会将指纹输出到终端。例如：

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

如何从密钥库获取签名指纹

如果您有密钥库文件，请使用 keytool 实用程序确定指纹。

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

然后，keytool 实用程序会将指纹输出到终端。例如：

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

如何从 Play 应用签名功能获取应用签名密钥

使用 Play 应用签名时，Google 会管理应用的签名密钥，并使用该密钥为您的 APK 签名。 此密钥应该用于签名指纹。

1. 在 Google Play 管理中心的“应用签名”页面中，滚动到“应用签名密钥证书”。
2. 使用 SHA-1 证书指纹。

创建 OAuth 2.0 客户端 ID

对于上述步骤中每个适用的签名密钥，在您的 Google Cloud 项目的凭据中创建一个 OAuth 2.0 客户端 ID。

• 在 Google Cloud 中，打开“凭据”页面。

  凭据

• 点击创建凭据，然后从菜单中选择 OAuth 客户端 ID。

• 填写必填字段，如下所示：

  • Application type：选择 Android。
  • Package name：使用 AndroidManifest.xml 中声明的软件包名称。
  • SHA-1 证书指纹：使用在前面步骤中获得的指纹。

• 按创建。

包含必需的库

1. 在应用的依赖项中添加 com.google.android.gms:play-services-auth:16+。

2. 如果您使用代码缩减功能，请将其添加到应用的 build.gradle 文件中：

   buildTypes {
     release {
       ...
       proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
     }
   }
   

3. 将以下内容添加到应用的 proguard-rules.pro 文件中：

   -keep class com.google.android.gms.common.** { *; }
   -keep class com.google.android.gms.location.** { *; }
   -keep class com.google.android.gms.auth.** { *; }
   -keep class com.google.android.gms.tasks.** { *; }
   

您的应用现已配置为使用无密钥身份验证。

无钥匙

ARCore 支持使用（JSON Web 令牌）在 iOS 中授权 API 调用。令牌必须由 Google 服务帐号签名。

如需生成 iOS 令牌，您的服务器上必须具有满足以下要求的端点：

• 您自己的授权机制必须保护端点。

• 端点必须每次都生成新的令牌，以便：

  • 每个用户都会获得一个唯一的令牌。
  • 令牌不会立即过期。

创建服务账号和签名密钥

请按照以下步骤创建 Google 服务帐号和签名密钥：

1. 在 Google Cloud 中，打开“凭据”页面。
   凭据
2. 依次点击创建凭据 > 服务帐号。
3. 在服务帐号详情下，输入新帐号的名称，然后点击创建。
4. 在“服务帐号权限”页面上，转到选择角色下拉菜单。 选择服务帐号 > Service Account Token Creator，然后点击“继续”。
5. 在向用户授予访问此服务帐号的权限页面上，点击“完成”。
6. 在凭据页面上，找到“服务帐号”部分，然后点击您刚创建的帐号的名称。
7. 在服务帐号详情页面上，向下滚动到“密钥”部分，然后依次选择添加密钥 > 创建新密钥。

8. 选择 JSON 作为密钥类型，然后点击创建。

   这会将包含私钥的 JSON 文件下载到您的机器。请将下载的 JSON 密钥文件存储在安全的位置。

   注意 ：此文件包含不得向公众公开的私钥。请不要将其提交到 GitHub 等源代码库。

在服务器上创建令牌

如需在您的服务器上创建新令牌 (JWT)，请使用标准 JWT 库以及您从新服务帐号安全下载的 JSON 文件。

在开发机器上创建令牌

如需在开发机器上生成 JWT，请使用以下 oauth2l 命令：

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

必须使用 --cache 标志指定空缓存位置，以确保每次都生成不同的令牌。请务必修剪生成的字符串。多余的空格或换行符将会导致 API 拒绝令牌。

对令牌签名

您必须使用 RS256 算法和以下声明为 JWT 签名：

• iss - 服务帐号电子邮件地址。
• sub - 服务帐号电子邮件地址。
• iat - 生成令牌的 Unix 纪元时间（以秒为单位）。
• exp - iat + 3600（1 小时）。令牌到期的 Unix 纪元时间（以秒为单位）。
• aud - 受众群体。它必须设置为 https://arcore.googleapis.com/。

JWT 载荷中不需要非标准声明，但您可能会发现 uid 声明对于识别相应用户很有用。

如果您使用其他方法生成 JWT（例如在 Google 管理的环境中使用 Google API），请务必使用本部分中的声明对 JWT 进行签名。最重要的是，确保受众群体正确无误。

在 ARCore 会话中传递令牌

1. 确保将 iOS 身份验证策略设置为 AuthenticationToken。在 Unity 中，转到 Edit > Project Settings > XR plug-in Management > ARCore Extensions。在 iOS 身份验证策略下拉菜单中，选择身份验证令牌选项。

2. 获取令牌后，使用 ARAnchorManager.SetAuthToken() 将其传递到 ARCore 会话中：

   // Designate the token to authorize ARCore API calls
   // on the iOS platform. This should be called each time the application's token is refreshed.
   ARAnchorManager.SetAuthToken(authToken);
   

您的应用现已配置为使用无密钥身份验证。

将令牌传递到会话中时，请注意以下事项：

• 如果您使用 API 密钥创建会话，ARCore 将忽略该令牌并记录错误。

  如果您不再需要该 API 密钥，请在 Google Developers Console 中将其删除，并从您的应用中移除。

• ARCore 会忽略包含空格或特殊字符的词元。

• 令牌通常会在 1 小时后过期。如果您的令牌在使用时可能会过期，请获取一个新令牌并将其传递给 API。

API 密钥

1. 在 Google Cloud 中，打开“凭据”页面。
   凭据
2. 选择创建凭据，然后从菜单中选择 API 密钥。
   “已创建 API 密钥”对话框会显示新创建的密钥的字符串。

3. 在 Unity 中，转到 Edit > Project Settings > XR plug-in Management > ARCore Extensions。对于每个目标平台（Android、iOS），在其身份验证策略下拉菜单中，选择 API 密钥选项。然后，在 API 密钥字段中插入您的 API 密钥。

4. 请查看有关 API 密钥限制的文档，以保护您的 API 密钥。

您的应用现已配置为使用 API 密钥。

后续步骤

配置授权后，请查看以下使用授权的 ARCore 功能：

• Geospatial API
• Cloud Anchor API