在 Google Cloud 中使用 ARCore API

選取平台： Android Unity (AR 基礎) iOS

ARCore 功能，例如地理空間 API 和 Cloud Anchors 使用 託管於 Google Cloud 的 ARCore API。使用這些功能時，您的應用程式 使用憑證存取 ARCore API 服務。

本快速入門導覽課程說明如何設定應用程式，以便 都能與託管於 Google Cloud 的 ARCore API 服務進行通訊。

建立新的 Google Cloud 專案或使用現有專案

如果您有現有專案，請選取該專案。

前往專案選取器

如果您目前沒有 Google Cloud 專案，請先建立專案。

建立新專案

啟用 ARCore API

如要使用 ARCore API，您必須在專案中啟用 ARCore API。

啟用 ARCore API

設定授權方法

Unity 應用程式可以使用兩種不同的方式，與 ARCore API 通訊 授權方法：無金鑰授權 和 API 金鑰授權：

• 在 Android 上，無金鑰授權會使用應用程式的套件名稱組合 和簽署金鑰的指紋，以便授權應用程式。

  在 iOS 上，無金鑰授權會使用簽署的權杖來控制 API 的存取權。這個 方法會要求您擁有的伺服器，以便簽署符記並控制 並嚴謹測試及提升 API 的公平性後 我們才能放心地推出 API

• API 金鑰是用來識別 Google Cloud 專案的字串。API 金鑰是 通常不會視為安全，因為用戶端通常可以使用這類軟體。 建議您使用無金鑰授權來與 ARCore API 通訊。

無鑰匙無鑰匙API 金鑰

如要使用無金鑰驗證來授權應用程式，請建立 OAuth 2.0 用戶端 而非客戶 ID

決定簽署金鑰指紋

OAuth 2.0 用戶端 ID 會使用應用程式的簽署金鑰指紋來識別 應用程式。

重要事項： 應用程式常見的簽署金鑰可能不同。 您必須為要使用的每個簽署金鑰建立用戶端 ID。通常， 屬於偵錯簽署 金鑰和 發布簽署金鑰。

如何取得偵錯簽署指紋

執行專案或偵錯時，Android SDK 工具會自動 使用產生的偵錯憑證來呼叫應用程式。

使用下列指令取得偵錯憑證指紋。

Mac/LinuxWindows

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

敬上

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

keytool 公用程式會提示您輸入 KeyStore 密碼。 android 的偵錯 KeyStore 預設密碼。接著，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

如何從 KeyStore 取得簽署指紋

如果你有 KeyStore 檔案，請使用 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 專案的憑證

• 在 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 支援在 iOS 中使用 (JSON Web) 授權的 API 呼叫 權杖)。權杖必須由 Google 。

你必須在伺服器上設定端點，才能產生 iOS 權杖 須符合下列條件：

• 您自己的授權機制必須保護端點。

• 端點每次都必須產生新的符記，以便：

  • 每位使用者都會取得專屬權杖。
  • 權杖不會立即失效。

建立服務帳戶與簽署金鑰

請按照下列步驟建立 Google 服務帳戶和簽署金鑰：

1. 在 Google Cloud 中開啟「憑證」頁面。
   憑證
2. 按一下「建立憑證」>服務帳戶。
3. 在「服務帳戶詳細資料」下方輸入新帳戶的名稱，然後按一下 建立。
4. 在「服務帳戶權限」頁面，前往「請選取角色」下拉式選單。 選取服務帳戶 >服務帳戶權杖建立者，然後按一下 繼續。
5. 在「將這個服務帳戶的存取權授予使用者」頁面上，按一下「完成」。
6. 在「Credentials」(憑證) 中 在頁面中找出「服務帳戶」專區，然後按一下帳戶名稱 每個 Cloud Storage 值區
7. 在「Service account details」(服務帳戶詳細資料) 頁面中，向下捲動至「Keys」(金鑰) 部分，然後 選取「新增鍵」>建立新的金鑰。

8. 選取「JSON」JSON做為金鑰類型，然後按一下「建立」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，例如使用 API (位於 Google 代管環境中)，請務必在使用憑證附加資訊時簽署您的 JWT 本節最重要的是，請確認目標對象正確無誤。

在 ARCore 工作階段中傳遞權杖

1. 確認「iOS 驗證策略」已設為 AuthenticationToken。在 Unity 中，前往「Edit」(編輯) >「Project Settings」> XR 外掛程式管理 > ARCore 擴充功能。點選「iOS Authentication Strategy」下拉式選單。 選取「Authentication Token」選項。

2. 取得權杖後，請使用以下指令將權杖傳遞至 ARCore 工作階段 ARAnchorManager.SetAuthToken():

   // 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 網站刪除 控制台，並將該指標從 應用程式。

• ARCore 會忽略含有空格或特殊字元的符記。

• 憑證通常會在一小時後失效。如果 權杖可能會在使用期間過期，請取得新權杖並傳遞至 API。

1. 在 Google Cloud 中開啟「憑證」頁面。
   憑證
2. 按一下「建立憑證」，然後從選單中選取「API 金鑰」。
   建立的 API 金鑰對話方塊會顯示新建金鑰的字串。

3. 在 Unity 中，前往「Edit」(編輯) >「Project Settings」>XR 外掛程式管理 > ARCore 擴充功能。每個目標平台 (Android、iOS) 「驗證策略」下拉式選單，選取「API 金鑰」選項。接著： 在 API 金鑰欄位中插入 API 金鑰

4. 參閱 API 金鑰限制說明文件 確保 API 金鑰安全

您的應用程式現已設為使用 API 金鑰。

後續步驟

設定授權後，請查看下列使用 它：

• Geospatial API
• Cloud Anchor API