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 状态

没有已知的 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 设置方面的问题。如果应用有调试消息传递器，并且在运行时代表应用向 Google Cloud 发送请求时发生可能需要采取措施的错误，则运行时会使用错误消息调用消息传递器的回调。在这种情况下，开发者应查阅出错提示和所有可用文档，然后确保应用和 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 必须是以 null 结尾的 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 必须是以 null 结尾的 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。

异步操作将执行必要的网络请求来提取凭据。此操作的结果将通过 XrFutureCompletionEXT :: futureResult 从 xrSetGoogleCloudAuthCompleteANDROID 返回。如果 future 结果为 XR_SUCCESS，则表示无密钥身份验证凭据已成功应用。如果 future 结果为 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）。

每种身份验证方法的具体要求、行为和错误条件（同步和异步）在各自数据结构的文档中进行了说明。

有效用法（隐式）

必须先启用 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 的指针。

Future 返回代码

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)
- 初始扩展程序说明。