XR_ANDROID_google_cloud_auth

String Nama

XR_ANDROID_google_cloud_auth

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

788

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_future

Tanggal Terakhir Diubah

2025-12-18

Status IP

Tidak ada klaim kekayaan intelektual 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 untuk aplikasi. Ekstensi ini memerlukan ekstensi XR_EXT_future .

Selama pengembangan, aplikasi dapat men-debug masalah terkait penyiapan Google Cloud menggunakan ekstensi XR_EXT_debug_utils . Jika aplikasi memiliki Debug Messenger, dan terjadi error yang berpotensi dapat ditindaklanjuti dalam runtime saat mengirim permintaan ke Google Cloud atas nama aplikasi, runtime akan memanggil callback messenger dengan pesan error. Dalam hal ini, developer harus membaca pesan error dan semua dokumentasi yang tersedia, lalu memastikan bahwa aplikasi dan project Google Cloud telah 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 didefinisikan 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 didefinisikan 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 mewakili kunci API.

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

apiKey harus memenuhi kondisi berikut:

  • Kunci API ini 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 Google Cloud API 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 merantai 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 didefinisikan 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 mewakili token autentikasi.

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

  • Kredensial ini harus 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 dihasilkan 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 merantai 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 didefinisikan 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 menghasilkan kredensial secara dinamis (misalnya, di Android, runtime berkomunikasi dengan Layanan Google Play dari proses aplikasi). Jika Keyless Auth tidak disiapkan dengan benar, runtime mungkin akan menampilkan XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID secara sinkron.

Operasi asinkron akan menjalankan 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 di masa mendatang adalah XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , aplikasi dapat mencoba lagi nanti.

Penggunaan yang Valid (Implisit)

Fungsi xrSetGoogleCloudAuthAsyncANDROID didefinisikan 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 handle XrFutureEXT tempat future yang dibuat ditampilkan, atau XR_NULL_HANDLE jika fungsi tidak menampilkan XR_SUCCESS .

Tetapkan kredensial yang digunakan untuk melakukan autentikasi dengan Google Cloud. Operasi ini bersifat asinkron. Panggil xrPollFutureEXT untuk memeriksa status siap di masa mendatang. Setelah future 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 tertentu (baik sinkron maupun asinkron) untuk setiap metode autentikasi dijelaskan dalam dokumentasi untuk masing-masing struct data.

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 didefinisikan 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 Status 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 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 Auth Google Cloud

Enumerasi XrGoogleCloudAuthErrorANDROID didefinisikan 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 terjadi error 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 didefinisikan 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 mungkin dihubungkan ke struct hasil operasional untuk memberikan informasi selengkapnya tentang error tersebut.

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.