Android XR for OpenXR | Android Developers

Android 開發人員高峰會再度登場，並專為 Android XR 規劃一系列議程。歡迎試用，並提供意見！

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

XR_ANDROID_google_cloud_auth

Name String

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「必須」為 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 專案必須啟用相關 Google Cloud API (由依附的擴充功能指定)。
如果 API 金鑰設有限制，則必須允許相關的 Google Cloud API 和您的應用程式。

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

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

有效用途 (隱含)

必須先啟用 XR_ANDROID_google_cloud_auth 擴充功能，才能使用 XrGoogleCloudAuthInfoApiKeyANDROID
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 專案必須啟用相關 Google 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「必須」是以空值結尾的 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 是指向 struct 的指標，用於指定驗證方式和參數，其 XrGoogleCloudAuthInfoBaseHeaderANDROID :: type 欄位會指出特定 struct。
future 是 XrFutureEXT 控制代碼的指標，建立的 Future 會傳回至該指標。如果函式未傳回 XR_SUCCESS，則為 XR_NULL_HANDLE。

設定用於向 Google Cloud 驗證身分的憑證。這項作業會以非同步方式執行。呼叫 xrPollFutureEXT，檢查 future 的就緒狀態。Future 進入就緒狀態後，請呼叫 xrSetGoogleCloudAuthCompleteANDROID 擷取結果。

authInfo 參數必須指向 struct，其 XrGoogleCloudAuthInfoBaseHeaderANDROID :: type 成員會識別要使用的驗證方式，並擴充 XrGoogleCloudAuthInfoBaseHeaderANDROID (例如 XrGoogleCloudAuthInfoApiKeyANDROID)。

每種驗證方式的具體要求、行為和錯誤條件 (同步和非同步)，請參閱各自資料結構的說明文件。

有效用途 (隱含)

必須先啟用 XR_ANDROID_google_cloud_auth 擴充功能，才能呼叫 xrSetGoogleCloudAuthAsyncANDROID
session「必須」是有效的 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 服務，且這些服務必須正常運作)。

有效用途 (隱含)

必須先啟用 XR_ANDROID_google_cloud_auth 擴充功能，才能呼叫 xrSetGoogleCloudAuthCompleteANDROID
session「必須」是有效的 XrSession 控制代碼
completion「必須」是指向 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)
- 初始擴充功能說明。