Android XR for OpenXR | Android Developers

Android XR SDK 已推出開發人員預覽版 3，歡迎提供意見！歡迎試用，如有任何問題，請前往支援頁面與我們聯絡。

XR_ANDROID_google_cloud_auth

名稱字串

XR_ANDROID_google_cloud_auth

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

788

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_future

上次修改日期

2025-12-18

IP 狀態

未發現任何智慧財產權聲明。

著作人

John Ullman (Google)
Ben King (Google)
Nihav Jain (Google)
Jared Finder (Google)

總覽

這項擴充功能可讓應用程式提供 Google Cloud API 的驗證憑證，進而使用 Google Cloud 擴充功能。開發人員必須使用 Google Cloud 控制台 ( https://console.cloud.google.com/ ) 為應用程式建立 Google Cloud 專案。這項擴充功能需要擴充功能 XR_EXT_future。

在開發期間，應用程式可以使用擴充功能 XR_EXT_debug_utils 偵錯 Google Cloud 設定問題。如果應用程式有 Debug Messenger，且代表應用程式傳送要求給 Google Cloud 時，執行階段發生可能可執行的錯誤，執行階段會使用錯誤訊息叫用 Messenger 的回呼。在這種情況下，開發人員應參閱錯誤訊息和所有可用的文件，然後確保應用程式和 Google Cloud 專案已正確設定，可使用 Google Cloud API。執行階段必須使用訊息類型 XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT、嚴重程度 XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT 和 messageId「GoogleCloudError」。

驗證

XrGoogleCloudAuthInfoBaseHeaderANDROID 結構體的定義如下：

typedef struct XrGoogleCloudAuthInfoBaseHeaderANDROID {
    XrStructureType    type;
    const void*        next;
} XrGoogleCloudAuthInfoBaseHeaderANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。

這個結構不會直接用於 API，但其他結構會擴充這個結構，可與 xrSetGoogleCloudAuthAsyncANDROID 搭配使用，以提供驗證憑證。

有效用量 (隱含)

必須先啟用 XR_ANDROID_google_cloud_auth 擴充功能，才能使用 XrGoogleCloudAuthInfoBaseHeaderANDROID
type 必須是下列其中一個 XrStructureType 值：XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID、XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID、XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID
next must 為 NULL，或指向結構鏈中下一個結構的有效指標。另請參閱：XrGoogleCloudAuthErrorResultANDROID

XrGoogleCloudAuthInfoApiKeyANDROID 結構定義如下：

typedef struct XrGoogleCloudAuthInfoApiKeyANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        apiKey;
} XrGoogleCloudAuthInfoApiKeyANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。
apiKey 是代表 API 金鑰的字串指標。

將這個結構體傳遞至 xrSetGoogleCloudAuthAsyncANDROID 時，apiKey 成員必須為不含空格或控制字元的非空白 ASCII 字串，否則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

apiKey 必須進一步符合下列條件：

必須是為 Google Cloud 專案產生的有效 API 金鑰。
您的 Google Cloud 專案必須啟用相關的 Cloud API (由依附擴充功能指定)。
如果 API 金鑰設有限制，這些限制必須允許相關的 Google Cloud API 和您的應用程式。

否則，對 xrSetGoogleCloudAuthAsyncANDROID 的呼叫會成功，但對依附雲端授權的函式進行的所有呼叫，都會按照定義這些函式的擴充功能中，雲端失敗的相關說明運作。如果函式「可以」回報失敗，且應用程式將 XrGoogleCloudAuthErrorResultANDROID 鏈結至該函式的輸出參數，則執行階段「必須」將 XrGoogleCloudAuthErrorResultANDROID :: error 設為 XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID，表示發生這項錯誤。

執行階段驗證 API 金鑰格式並儲存後，非同步作業就會完成，並傳回 XR_SUCCESS。

有效用量 (隱含)

使用 XrGoogleCloudAuthInfoApiKeyANDROID 前，XR_ANDROID_google_cloud_auth 擴充功能必須啟用
 type 必須為 XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
apiKey 必須是空值結尾的 UTF-8 字串

XrGoogleCloudAuthInfoTokenANDROID 結構體的定義如下：

typedef struct XrGoogleCloudAuthInfoTokenANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        authToken;
} XrGoogleCloudAuthInfoTokenANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。
authToken 是代表驗證權杖的字串指標。

將這個結構體傳遞至 xrSetGoogleCloudAuthAsyncANDROID 時，authToken 成員必須是不含空格或控制字元的非空白 ASCII 字串，否則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。authToken 必須進一步符合下列條件：

必須是為 Google Cloud 專案產生的有效憑證，且未過期。
您的 Google Cloud 專案必須啟用相關的 Cloud API (由依附擴充功能指定)。
憑證必須是下列其中一項：
- 透過應用程式登入 Google 帳戶時產生的 OAuth2 存取權杖 (具有相關範圍)，或
- 由 Google Cloud 雲端專案的服務帳戶產生，並包含相關權杖附加資訊的已簽署 JWT 權杖。

每個案例的需求是由依附擴充功能指定。否則，對 xrSetGoogleCloudAuthAsyncANDROID 的呼叫會成功，但對依附雲端授權的函式進行的所有呼叫，都會按照定義這些函式的擴充功能中，雲端失敗的相關說明運作。如果函式「可以」回報失敗，且應用程式將 XrGoogleCloudAuthErrorResultANDROID 鏈結至該函式的輸出參數，則執行階段「必須」將 XrGoogleCloudAuthErrorResultANDROID :: error 設為 XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID，表示發生這項錯誤。

應用程式必須在舊權杖到期前，透過 xrSetGoogleCloudAuthAsyncANDROID 主動傳遞新權杖。啟動新的網路要求時，執行階段必須使用應用程式傳遞的最新權杖。

執行階段驗證權杖格式並儲存後，非同步作業就會完成，並傳回 XR_SUCCESS。

有效用量 (隱含)

必須先啟用 XR_ANDROID_google_cloud_auth 擴充功能，才能使用 XrGoogleCloudAuthInfoTokenANDROID
 type 必須為 XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
authToken must 是以空值結尾的 UTF-8 字串

XrGoogleCloudAuthInfoKeylessANDROID 結構體的定義如下：

typedef struct XrGoogleCloudAuthInfoKeylessANDROID {
    XrStructureType    type;
    const void*        next;
} XrGoogleCloudAuthInfoKeylessANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。

將這個結構體傳遞至 xrSetGoogleCloudAuthAsyncANDROID 時，執行階段「可能」會動態產生憑證 (例如在 Android 上，執行階段會從應用程式程序與 Google Play 服務通訊)。如果無金鑰驗證設定不正確，執行階段可能會同步傳回 XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID。

非同步作業會執行必要的網路要求，以擷取憑證。這項作業的結果會透過 xrSetGoogleCloudAuthCompleteANDROID 中的 XrFutureCompletionEXT :: futureResult 傳回。如果未來結果為 XR_SUCCESS，表示已成功套用免金鑰驗證憑證。如果未來結果為 XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID，應用程式可能稍後會再試一次。

有效用量 (隱含)

XR_ANDROID_google_cloud_auth 擴充功能必須先啟用，才能使用 XrGoogleCloudAuthInfoKeylessANDROID
 type 必須為 XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

xrSetGoogleCloudAuthAsyncANDROID 函式定義如下：

XrResult xrSetGoogleCloudAuthAsyncANDROID(
    XrSession                                   session,
    const XrGoogleCloudAuthInfoBaseHeaderANDROID* authInfo,
    XrFutureEXT*                                future);

參數說明

session 是會使用憑證的 XrSession。
authInfo 是指向結構體的指標，用於指定驗證方法和參數，而 XrGoogleCloudAuthInfoBaseHeaderANDROID :: type 欄位則會指出特定結構體。
future 是 XrFutureEXT 控制代碼的指標，建立的 Future 會傳回至該指標，如果函式未傳回 XR_SUCCESS，則會傳回 XR_NULL_HANDLE。

設定用於向 Google Cloud 進行驗證的憑證。這項作業是非同步作業。呼叫 xrPollFutureEXT，檢查 Future 的就緒狀態。Future 處於就緒狀態後，請呼叫 xrSetGoogleCloudAuthCompleteANDROID 擷取結果。

authInfo 參數必須是指向結構體的指標，該結構體的 XrGoogleCloudAuthInfoBaseHeaderANDROID :: type 成員會識別要使用的驗證方法，並擴充 XrGoogleCloudAuthInfoBaseHeaderANDROID (例如 XrGoogleCloudAuthInfoApiKeyANDROID )。

如要瞭解各驗證方法的具體需求、行為和錯誤情況 (同步和非同步)，請參閱相關資料結構的說明文件。

有效用量 (隱含)

呼叫 xrSetGoogleCloudAuthAsyncANDROID 前，XR_ANDROID_google_cloud_auth 擴充功能必須啟用
session must 為有效的 XrSession 控制代碼
authInfo 必須是指向有效 XrGoogleCloudAuthInfoBaseHeaderANDROID 型結構體的指標。另請參閱：XrGoogleCloudAuthInfoApiKeyANDROID、XrGoogleCloudAuthInfoKeylessANDROID、XrGoogleCloudAuthInfoTokenANDROID
future 必須是指向 XrFutureEXT 值的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

xrSetGoogleCloudAuthCompleteANDROID 函式定義如下：

XrResult xrSetGoogleCloudAuthCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrFutureCompletionEXT*                      completion);

參數說明

session 是用來啟動作業的 XrSession。
future 是完成 XrFutureEXT 的必要步驟。
completion 是指向執行階段填入的 XrFutureCompletionEXT 的指標。

日後推出的回覆代碼

XrFutureCompletionEXT :: futureResult 值：

成功

XR_SUCCESS：已成功套用憑證。

失敗

XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID：無金鑰驗證失敗。應用程式可以稍後再試。應用程式或開發人員「可能」也會檢查某些成功的前提條件 (例如在 Android 上，裝置「必須」安裝最新版本的 Google Play 服務，且這些服務「必須」正常運作)。

有效用量 (隱含)

呼叫 xrSetGoogleCloudAuthCompleteANDROID 前，XR_ANDROID_google_cloud_auth 擴充功能必須啟用
session must 為有效的 XrSession 控制代碼
completion must 是 XrFutureCompletionEXT 結構的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_FUTURE_INVALID_EXT
XR_ERROR_FUTURE_PENDING_EXT
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

Google Cloud 驗證錯誤

XrGoogleCloudAuthErrorANDROID 列舉定義如下：

typedef enum XrGoogleCloudAuthErrorANDROID {
    XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID = 0,
    XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID = -1,
    XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID = -2,
    XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID = -3,
    XR_GOOGLE_CLOUD_AUTH_ERROR_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGoogleCloudAuthErrorANDROID;

列舉值如下：

列舉說明

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

呼叫 Google Cloud API 時未發生任何錯誤。

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

呼叫 Google Cloud API 時超出配額。

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

無法連線至 Google Cloud API，原因可能是網路連線問題或伺服器可用性。

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

呼叫 Google Cloud API 時發生授權錯誤。

XrGoogleCloudAuthErrorResultANDROID 結構體的定義如下：

typedef struct XrGoogleCloudAuthErrorResultANDROID {
    XrStructureType                  type;
    void*                            next;
    XrGoogleCloudAuthErrorANDROID    error;
} XrGoogleCloudAuthErrorResultANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。
error 是 XrGoogleCloudAuthErrorANDROID，詳細說明存取 Google Cloud 的作業發生錯誤的原因。

如果作業因 Google Cloud 驗證而失敗，這個結構體「可能」會鏈結至作業結果結構體，提供錯誤的詳細資訊。

有效用量 (隱含)

XR_ANDROID_google_cloud_auth 擴充功能必須先啟用，才能使用 XrGoogleCloudAuthErrorResultANDROID
 type 必須為 XR_TYPE_GOOGLE_CLOUD_AUTH_ERROR_RESULT_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
error 必須是有效的 XrGoogleCloudAuthErrorANDROID 值

範例程式碼

XrSession session; // previously initialized
XrInstance instance; // previously initialized
XrFutureEXT future = XR_NULL_HANDLE;

// The function pointers are previously initialized using
// xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // previously initialized
PFN_xrSetGoogleCloudAuthAsyncANDROID xrSetGoogleCloudAuthAsyncANDROID; // previously initialized
PFN_xrSetGoogleCloudAuthCompleteANDROID xrSetGoogleCloudAuthCompleteANDROID; // previously initialized

auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    xrPollFutureEXT(instance, &pollInfo, &pollResult);
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Set Google Cloud auth via API key.
XrGoogleCloudAuthInfoApiKeyANDROID authApiKey{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID};
authApiKey.apiKey = "MYAPIKEY";
XrResult result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authApiKey), &future);

// Or, set Google Cloud auth via auth token:
XrGoogleCloudAuthInfoTokenANDROID authToken{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID};
authToken.authToken = "MYAUTHTOKEN";
result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authToken), &future);

// Or, set Google Cloud auth via keyless auth:
XrGoogleCloudAuthInfoKeylessANDROID authKeyless{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID};
result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authKeyless),
    &future);

// Check the result of the auth setup.
if (result == XR_ERROR_VALIDATION_FAILURE) {
  // The credentials were invalid.
} else if (result == XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID) {
  // Keyless auth was not properly setup.
} else if (result == XR_SUCCESS) {
  waitUntilReady(future);
  XrFutureCompletionEXT completion{XR_TYPE_FUTURE_COMPLETION_EXT};
  xrSetGoogleCloudAuthCompleteANDROID(session, future, &completion);

  if (completion.futureResult == XR_SUCCESS) {
    // Credentials were successfully applied.
  } else if (completion.futureResult == XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID) {
    // An error occurred when setting keyless auth credentials. This error may be retried.
  }
}

新結構

XrGoogleCloudAuthInfoApiKeyANDROID
XrGoogleCloudAuthInfoBaseHeaderANDROID
XrGoogleCloudAuthInfoKeylessANDROID
XrGoogleCloudAuthInfoTokenANDROID
擴充 XrGoogleCloudAuthInfoBaseHeaderANDROID：
- XrGoogleCloudAuthErrorResultANDROID

新列舉

XrGoogleCloudAuthErrorANDROID

新增列舉常數

XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
XR_ANDROID_google_cloud_auth_SPEC_VERSION
擴充 XrResult：
- XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
- XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID
擴充 XrStructureType：
- XR_TYPE_GOOGLE_CLOUD_AUTH_ERROR_RESULT_ANDROID
- XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID
- XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID
- XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID

問題

修訂版本 1，2025 年 12 月 18 日 (Ben King)
- 擴充功能的初始說明。