Інтеграція Google VR SDK у мобільний додаток

Інтеграція Google VR SDK у мобільні додатки

Google VR SDK (Cardboard SDK після ребрендингу 2021 року) — офіційна бібліотека для додавання Cardboard VR у мобільні додатки на iOS та Android. SDK бере на себе lens distortion, head tracking, stereo projection та QR-сканування профілю пристрою.

Поточний статус: Cardboard SDK проти deprecated Google VR SDK

Важливо: оригінальний Google VR SDK (gvr-android-sdk) оголошено deprecated з 2019 року. Актуальна версія — відкритий Google Cardboard SDK, активно підтримується. Якщо проєкт використовує старий com.google.vr.sdk — міграція рекомендована.

Новий Cardboard SDK підтримує:

• Unity через UPM пакет com.google.cardboard
• Нативний Android (C++ через JNI + Java wrapper)
• Нативний iOS (Objective-C/Swift)

Інтеграція в Unity

Найпоширеніший шлях. Через Package Manager додаємо com.google.cardboard з git URL:

https://github.com/googlevr/cardboard.git#upm

Після встановлення в сцену додаємо компонент CardboardCamera на Main Camera. SDK автоматично:

• Розбиває екран пополам для стереорендеринга
• Застосовує lens distortion correction
• Читає head tracking з IMU
• Обробляє trigger button

// Перший запуск: показуємо UI для сканування QR
void Start() {
    if (!CardboardQrCode.IsDeviceParamsSet()) {
        Cardboard.SDK.ScanDeviceParams();
    }
}

// Recenter за натисканням кнопки
void Update() {
    if (CardboardInput.GetButtonDown()) {
        Cardboard.SDK.Recenter();
    }
}

Нативна інтеграція Android (Java/Kotlin)

Для нативних додатків без Unity:

// build.gradle
implementation 'com.google.cardboard:sdk:1.21.0'

Ключові компоненти SDK:

// Ініціалізація в Activity
private CardboardHeadTracker headTracker;
private CardboardLensDistortion lensDistortion;
private CardboardDistortionRenderer distortionRenderer;

@Override
protected void onCreate(Bundle savedInstanceState) {
    CardboardSdk.initializeOnce(this, "your-app-name");
    headTracker = CardboardHeadTracker.create();
    // ...
}

// У render loop (вызывается з GLSurfaceView)
@Override
public void onDrawFrame(GL10 gl) {
    // Отримуємо матриці для кожного ока
    long monotonic_time_ns = System.nanoTime();
    float[] leftEyeViewMatrix  = new float[16];
    float[] rightEyeViewMatrix = new float[16];

    headTracker.getPose(monotonic_time_ns, leftEyeViewMatrix, rightEyeViewMatrix);

    // Рендеринг кожного ока...

    // Застосовуємо lens distortion через SDK
    distortionRenderer.renderEyeToDisplay(
        /* display */ 0, /* x */ 0, /* y */ 0,
        /* width */ displayWidth, /* height */ displayHeight,
        /* leftEyeParams */ leftEyeParams,
        /* rightEyeParams */ rightEyeParams
    );
}

Нативна інтеграція iOS (Swift)

// Podfile або SPM
pod 'GoogleCardboard', '~> 1.21'

// CardboardV1API — основний entry point
import CardboardSDK

class VRViewController: UIViewController {
    private var renderer: CardboardRenderer!

    override func viewDidLoad() {
        super.viewDidLoad()
        CardboardQrCode.getSavedDeviceParams { [weak self] params in
            if params == nil {
                CardboardQrCode.scanQrCodeAndSaveDeviceParams(from: self)
            }
            self?.initRenderer()
        }
    }
}

QR-сканування: обробка edge cases

QR-сканер відкривається при першому запуску або за явним запитом користувача. Потенційні проблеми:

• Користувач відмовився сканувати → SDK використовує дефолтні параметри Cardboard v1. Lens distortion буде некоректною для нестандартних корпусів.
• QR не читається (погане освітлення, пошкоджений код) → кнопка "ввести вручну" або "використовувати стандартний Cardboard".
• Після зміни корпуса → у налаштуваннях додатку кнопка "змінити гарнітуру", вызывает CardboardQrCode.scanQrCodeAndSaveDeviceParams().

Split-screen та fullscreen режим

Cardboard SDK очікує ландшафтну орієнтацію. На iOS це означає блокування UIInterfaceOrientationMask на .landscapeRight. На Android — android:screenOrientation="landscape" в manifest + обробка onConfigurationChanged щоб не пересоздавать activity.

Екранні вирізи (notch, Dynamic Island) у ландшафтному режимі можуть перекривати частину VR-картинки. Використовуйте WindowInsets.displayCutout (Android) та safeAreaInsets (iOS) для правильного позиціонування рендер-області.

Типові проблеми при інтеграції

IllegalStateException: Surface is not valid при старті на Android — GLSurfaceView не готовий на момент ініціалізації Cardboard. Вирішується ініціалізацією в surfaceCreated() callback, а не в onCreate().

SDK не компілюється з новим NDK — Cardboard SDK має нативну C++ частину, іноді потребує явного abiFilters "armeabi-v7a", "arm64-v8a" у gradle.

На iOS 17+ CMMotionManager потребує NSMotionUsageDescription у Info.plist — без нього краш при старті VR-режиму.

Робочий процес

Аудит існуючого проєкту: Unity або нативний, поточні залежності, цільові версії iOS/Android.

Інтеграція Cardboard SDK, налаштування QR-сканування.

Адаптація рендеринга: split-screen, lens distortion, stereo проекції.

Gaze interaction та Cardboard button.

Тестування на реальних пристроях різних виробників.

Оцінка часу

Базова інтеграція Cardboard SDK у Unity-проєкт — 2–3 дні. Нативна інтеграція з кастомним рендерером для iOS або Android — 3–5 днів.