XR_ANDROID_google_cloud_auth

String Nama

XR_ANDROID_google_cloud_auth

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

788

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_future

Tanggal Terakhir Diubah

2025-12-18

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Ringkasan

Ekstensi ini memungkinkan penggunaan ekstensi berbasis Google Cloud dengan mengizinkan aplikasi memberikan kredensial autentikasi untuk Google Cloud API. Developer harus menggunakan Konsol Google Cloud ( https://console.cloud.google.com/ ) untuk membuat project Google Cloud bagi aplikasi. Ekstensi ini memerlukan ekstensi XR_EXT_future .

Selama pengembangan, aplikasi dapat men-debug masalah dengan penyiapan Google Cloud menggunakan ekstensi XR_EXT_debug_utils . Jika aplikasi memiliki Debug Messenger, dan terjadi error yang berpotensi dapat ditindaklanjuti di runtime saat mengirim permintaan ke Google Cloud atas nama aplikasi, runtime akan memanggil callback messenger dengan pesan error. Dalam hal ini, developer harus melihat pesan error dan semua dokumentasi yang tersedia, lalu memastikan bahwa aplikasi dan project Google Cloud disiapkan dengan benar untuk menggunakan Google Cloud API. Runtime harus menggunakan jenis pesan XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT , tingkat keparahan XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT , dan messageId “GoogleCloudError”.

Autentikasi

Struktur XrGoogleCloudAuthInfoBaseHeaderANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.

Struktur ini tidak digunakan secara langsung di API, tetapi diperluas oleh struktur lain yang dapat digunakan dengan xrSetGoogleCloudAuthAsyncANDROID untuk memberikan kredensial autentikasi.

Penggunaan yang Valid (Implisit)

Struktur XrGoogleCloudAuthInfoApiKeyANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • apiKey adalah pointer ke string yang merepresentasikan kunci API.

Jika struktur ini diteruskan ke xrSetGoogleCloudAuthAsyncANDROID , anggota apiKey harus berupa string ASCII tidak kosong tanpa spasi atau karakter kontrol, jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

apiKey harus memenuhi kondisi berikut:

  • Kunci API harus berupa Kunci API yang valid yang dibuat untuk project Google Cloud Anda.
  • Project Google Cloud Anda harus mengaktifkan Google Cloud API yang relevan (ditentukan oleh ekstensi yang bergantung).
  • Jika Kunci API memiliki batasan, batasan tersebut harus mengizinkan API Google Cloud yang relevan dan aplikasi Anda.

Jika tidak, panggilan ke xrSetGoogleCloudAuthAsyncANDROID akan berhasil, tetapi semua panggilan ke fungsi yang bergantung pada otorisasi cloud akan bertindak seperti yang didokumentasikan untuk kegagalan cloud dalam ekstensi yang menentukan fungsi tersebut. Jika fungsi dapat melaporkan kegagalan dan aplikasi mengaitkan XrGoogleCloudAuthErrorResultANDROID ke parameter output fungsi tersebut, runtime harus menetapkan XrGoogleCloudAuthErrorResultANDROID :: error ke XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID untuk menunjukkan error ini.

Operasi asinkron akan selesai dengan XR_SUCCESS setelah kunci API divalidasi untuk pemformatan dan disimpan oleh runtime.

Penggunaan yang Valid (Implisit)

Struktur XrGoogleCloudAuthInfoTokenANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • authToken adalah pointer ke string yang merepresentasikan token autentikasi.

Jika struktur ini diteruskan ke xrSetGoogleCloudAuthAsyncANDROID , anggota authToken harus berupa string ASCII tidak kosong tanpa spasi atau karakter kontrol, jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE . authToken harus memenuhi kondisi berikut:

  • Kredensial ini harus berupa kredensial yang valid dan belum habis masa berlakunya yang dibuat untuk project Google Cloud Anda.
  • Project Google Cloud Anda harus mengaktifkan Google Cloud API yang relevan (ditentukan oleh ekstensi yang bergantung).

  • Kredensial harus berupa salah satu dari:

    • Token akses OAuth2 dengan cakupan yang relevan, yang dihasilkan dengan login ke akun Google menggunakan aplikasi Anda, ATAU
    • Token JWT Bertanda Tangan dengan klaim yang relevan, yang dibuat oleh Akun Layanan dari project Google Cloud Anda.

Persyaratan dalam setiap kasus ditentukan oleh ekstensi yang bergantung. Jika tidak, panggilan ke xrSetGoogleCloudAuthAsyncANDROID akan berhasil, tetapi semua panggilan ke fungsi yang bergantung pada otorisasi cloud akan bertindak seperti yang didokumentasikan untuk kegagalan cloud dalam ekstensi yang menentukan fungsi tersebut. Jika fungsi dapat melaporkan kegagalan dan aplikasi mengaitkan XrGoogleCloudAuthErrorResultANDROID ke parameter output fungsi tersebut, runtime harus menetapkan XrGoogleCloudAuthErrorResultANDROID :: error ke XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID untuk menunjukkan error ini.

Aplikasi harus secara proaktif meneruskan token baru melalui xrSetGoogleCloudAuthAsyncANDROID sebelum masa berlaku token lama berakhir. Runtime harus menggunakan token terbaru yang diteruskan oleh aplikasi saat memulai permintaan jaringan baru.

Operasi asinkron akan selesai dengan XR_SUCCESS setelah token divalidasi untuk pemformatan dan disimpan oleh runtime.

Penggunaan yang Valid (Implisit)

Struktur XrGoogleCloudAuthInfoKeylessANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.

Saat struktur ini diteruskan ke xrSetGoogleCloudAuthAsyncANDROID, runtime dapat membuat kredensial secara dinamis (misalnya, di Android, runtime berkomunikasi dengan Layanan Google Play dari proses aplikasi). Jika Autentikasi Tanpa Kunci tidak disiapkan dengan benar, runtime dapat menampilkan XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID secara serentak.

Operasi asinkron akan melakukan permintaan jaringan yang diperlukan untuk mengambil kredensial. Hasil operasi ini akan ditampilkan di XrFutureCompletionEXT :: futureResult dari xrSetGoogleCloudAuthCompleteANDROID . Jika hasil mendatang adalah XR_SUCCESS , kredensial Keyless Auth berhasil diterapkan. Jika hasil mendatang adalah XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , aplikasi dapat mencoba lagi nanti.

Penggunaan yang Valid (Implisit)

Fungsi xrSetGoogleCloudAuthAsyncANDROID ditentukan sebagai:

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

Deskripsi Parameter

  • session adalah XrSession yang akan menggunakan kredensial.
  • authInfo adalah pointer ke struct yang menentukan metode dan parameter autentikasi, dengan kolom XrGoogleCloudAuthInfoBaseHeaderANDROID :: type yang menunjukkan struct tertentu.
  • future adalah pointer ke tuas XrFutureEXT tempat hasil masa depan yang dibuat ditampilkan, atau XR_NULL_HANDLE jika fungsi tidak menampilkan XR_SUCCESS .

Menetapkan kredensial yang digunakan untuk mengautentikasi dengan Google Cloud. Operasi ini bersifat asinkron. Panggil xrPollFutureEXT untuk memeriksa status siap pada future. Setelah masa mendatang dalam status siap, panggil xrSetGoogleCloudAuthCompleteANDROID untuk mengambil hasilnya.

Parameter authInfo harus berupa pointer ke struct yang anggota XrGoogleCloudAuthInfoBaseHeaderANDROID :: type-nya mengidentifikasi metode autentikasi yang akan digunakan, dan yang memperluas XrGoogleCloudAuthInfoBaseHeaderANDROID (misalnya, XrGoogleCloudAuthInfoApiKeyANDROID).

Persyaratan, perilaku, dan kondisi error (sinkron dan asinkron) khusus untuk setiap metode autentikasi dijelaskan dalam dokumentasi untuk struktur datanya masing-masing.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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

Fungsi xrSetGoogleCloudAuthCompleteANDROID ditentukan sebagai:

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

Deskripsi Parameter

  • session adalah XrSession yang digunakan untuk memulai operasi.
  • future adalah XrFutureEXT yang harus diselesaikan.
  • completion adalah pointer ke XrFutureCompletionEXT yang diisi oleh runtime.

Kode Pengembalian pada Masa Mendatang

Nilai XrFutureCompletionEXT :: futureResult:

Berhasil

  • XR_SUCCESS : Kredensial berhasil diterapkan.

Kegagalan

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Autentikasi Tanpa Kunci gagal. Aplikasi dapat mencoba lagi nanti. Aplikasi atau developer juga dapat memeriksa prasyarat tertentu agar berhasil (misalnya, di Android, perangkat harus memiliki penginstalan Layanan Google Play yang terbaru dan layanan ini harus berfungsi dengan baik).

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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

Error Autentikasi Google Cloud

Enumerasi XrGoogleCloudAuthErrorANDROID ditentukan sebagai:

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;

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Tidak ada error yang terjadi saat memanggil Google Cloud API.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Kuota terlampaui saat memanggil Google Cloud API.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Gagal menjangkau Google Cloud API, mungkin karena masalah konektivitas jaringan atau ketersediaan server.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Terjadi error autentikasi saat memanggil Google Cloud API.

Struktur XrGoogleCloudAuthErrorResultANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • error adalah XrGoogleCloudAuthErrorANDROID yang menjelaskan penyebab error operasi yang mengakses Google Cloud.

Jika operasi gagal karena Autentikasi Google Cloud, struct ini dapat dirangkai ke struct hasil operasional untuk memberikan informasi lebih lanjut tentang error.

Penggunaan yang Valid (Implisit)

Kode contoh

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.
  }
}

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Memperluas XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Memperluas 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

Masalah

  • Revisi 1, 18-12-2025 (Ben King)

    • Deskripsi ekstensi awal.