在 Google Cloud 中使用 ARCore API

無金鑰

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

決定簽署金鑰指紋

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

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

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

   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 -list -v -alias your-key-name -keystore path-to-production-keystore

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

建立 OAuth 2.0 用戶端 ID

針對上述步驟中的每個適用的簽署金鑰，在 Google Cloud 專案的憑證中建立 OAuth 2.0 用戶端 ID。

• 在 Google Cloud 中開啟「憑證」頁面。

  憑證

• 按一下「建立憑證」，然後從選單中選取「OAuth 用戶端 ID」。

• 按照下列方式填寫必填欄位：

  • 應用程式類型：選擇「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. 在「Service account details」(服務帳戶詳細資料) 下方輸入新帳戶的名稱，然後按一下「Create」(建立)。
4. 在「服務帳戶權限」頁面，前往「請選擇角色」下拉式選單。依序選取「Service Accounts」(服務帳戶) >「Service Account Token Creator」(服務帳戶憑證建立者)，然後按一下「Continue」(繼續)。
5. 在「將這個服務帳戶的存取權授予使用者」頁面中，按一下「完成」。
6. 在「Credentials」(憑證) 頁面上找到「Service Account」(服務帳戶) 部分，然後按一下您剛建立的帳戶名稱。
7. 在「Service account details」(服務帳戶詳細資料) 頁面中，向下捲動至「Keys」(金鑰) 部分，然後選取「Add Key」(新增金鑰) >「Create new key」(建立新的金鑰)。

8. 選取「JSON」做為金鑰類型，然後按一下「建立」。

   即可將包含私密金鑰的 JSON 檔案下載至您的電腦。將下載的 JSON 金鑰檔案儲存在安全的位置。

在伺服器上建立權杖

如要在伺服器上建立新權杖 (JWT)，請使用標準 JWT 程式庫，以及您透過新服務帳戶安全下載的 JSON 檔案。

在開發機器上建立權杖

如要在開發機器上產生 JWT，請使用下列 oauth2l 指令：

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

必須使用 --cache 旗標指定空白的快取位置，才能確保每次都會產生不同的憑證。請務必修剪產生的字串。多餘的空格或換行字元會導致 API 拒絕權杖。

簽署權杖

您必須使用 RS256 演算法和下列憑證附加資訊來簽署 JWT：

• iss：服務帳戶電子郵件地址。
• sub：服務帳戶電子郵件地址。
• iat：產生權杖的 Unix Epoch 紀元時間 (以秒為單位)。
• exp - iat + 3600 (1 小時)。權杖的 Unix Epoch 紀元時間，以秒為單位。
• 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 Authentication Strategy」下拉式選單中，選取「Authentication Token」選項。

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 會忽略含有空格或特殊字元的權杖。

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

API 金鑰

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

3. 在 Unity 中，依序前往「Edit」 >「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」。針對每個目標平台 (Android、iOS)，在「Authentication Strategy」下拉式選單中選取「API Key」選項。接著，在 API 金鑰欄位中插入 API 金鑰。

4. 請參閱 API 金鑰限制說明文件，確保 API 金鑰安全無虞。

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