地理空間 API 和 Cloud Anchors 等 ARCore 功能會使用託管於 Google Cloud 的 ARCore API。使用這些功能時,您的應用程式會使用憑證存取 ARCore API 服務。
本快速入門導覽課程說明如何設定應用程式,使其能與託管於 Google Cloud 的 ARCore API 服務通訊。
建立新的 Google Cloud 專案或使用現有專案
如果已有專案,請選取該專案。
如果您目前沒有 Google Cloud 專案,請建立一個。
啟用 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 會使用應用程式的簽署金鑰指紋來識別應用程式。
如何取得偵錯簽署指紋
執行專案或偵錯時,Android SDK 工具會自動使用產生的偵錯憑證簽署應用程式。
請使用下列指令取得偵錯憑證指紋。keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore
keytool
公用程式會提示您輸入 KeyStore 密碼。偵錯 KeyStore 的預設密碼為 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
如何從 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。這組金鑰應用於簽署指紋。
- 在 Google Play 管理中心的「應用程式簽署」頁面,捲動至「應用程式簽署金鑰憑證」。
- 使用 SHA-1 憑證指紋。
建立 OAuth 2.0 用戶端 ID
針對上述步驟中的每個適用的簽署金鑰,在 Google Cloud 專案的憑證中建立 OAuth 2.0 用戶端 ID。
在 Google Cloud 中開啟「憑證」頁面。
按一下「建立憑證」,然後從選單中選取「OAuth 用戶端 ID」。
按照下列方式填寫必填欄位:
- 應用程式類型:選擇「Android」。
- Package name:使用 AndroidManifest.xml 中宣告的套件名稱。
- SHA-1 憑證指紋:使用在先前步驟中取得的指紋。
按下「建立」。
包含必要程式庫
- 在應用程式的依附元件中加入
com.google.android.gms:play-services-auth:16+
。 如果您要使用程式碼壓縮,請將程式碼新增至應用程式的
build.gradle
檔案:buildTypes { release { ... proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } }
請在應用程式的
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 服務帳戶和簽署金鑰,請按照下列步驟操作:
- 在 Google Cloud 中開啟「憑證」頁面。
憑證 - 依序按一下「建立憑證」>「服務帳戶」。
- 在「Service account details」(服務帳戶詳細資料) 下方輸入新帳戶的名稱,然後按一下「Create」(建立)。
- 在「服務帳戶權限」頁面,前往「請選擇角色」下拉式選單。依序選取「Service Accounts」(服務帳戶) >「Service Account Token Creator」(服務帳戶憑證建立者),然後按一下「Continue」(繼續)。
- 在「將這個服務帳戶的存取權授予使用者」頁面中,按一下「完成」。
- 在「Credentials」(憑證) 頁面上找到「Service Account」(服務帳戶) 部分,然後按一下您剛建立的帳戶名稱。
- 在「Service account details」(服務帳戶詳細資料) 頁面中,向下捲動至「Keys」(金鑰) 部分,然後選取「Add Key」(新增金鑰) >「Create new key」(建立新的金鑰)。
選取「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 工作階段中傳送權杖
- 確認 iOS 驗證策略已設為「AuthenticationToken」。在 Unity 中,依序前往「Edit」 >「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」。在「iOS Authentication Strategy」下拉式選單中,選取「Authentication Token」選項。
取得權杖後,請使用
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 金鑰
- 在 Google Cloud 中開啟「憑證」頁面。
憑證 - 按一下「建立憑證」,然後在選單中選取「API 金鑰」。
「建立的 API 金鑰」對話方塊會顯示新建金鑰的字串。 在 Unity 中,依序前往「Edit」 >「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」。針對每個目標平台 (Android、iOS),在「Authentication Strategy」下拉式選單中選取「API Key」選項。接著,在 API 金鑰欄位中插入 API 金鑰。
- 請參閱 API 金鑰限制說明文件,確保 API 金鑰安全無虞。
應用程式現已設為使用 API 金鑰。
後續步驟
設定授權後,請查看下列使用這個 API 的 ARCore 功能: