Installation and integration

This guide walks you through adding the Cognitive3D SDK to your Android XR (Jetpack XR) project.

Note

Building for Meta Quest with the Meta Spatial SDK? Use the Meta Spatial SDK installation guide instead. Each platform has its own Maven artifact.

Requirements

• Android Studio Narwhal (2025.1.1) or later.
• Compile SDK: 36 (required by the Jetpack XR 1.0.0-beta01 libraries).
• Minimum SDK: 29.
• Kotlin 1.9+ or Java 11+.

Installation

Step 1: Add the Maven Central repository

In your project's settings.gradle.kts, make sure Maven Central is included:

KotlinGroovy

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

// settings.gradle
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Step 2: Add the dependency

In your app's build file, add the Cognitive3D SDK for Android XR:

KotlinGroovy

// build.gradle.kts
dependencies {
    implementation("com.cognitive3d:android-xr-sdk:1.2.1")
}

// build.gradle
dependencies {
    implementation 'com.cognitive3d:android-xr-sdk:1.2.1'
}

The latest version is listed on Maven Central.

To always get the latest version, use a dynamic version (+) instead:

KotlinGroovy

// build.gradle.kts
dependencies {
    implementation("com.cognitive3d:android-xr-sdk:+")
}

// build.gradle
dependencies {
    implementation 'com.cognitive3d:android-xr-sdk:+'
}

Warning

Dynamic versions (+) can pull in a release with different build requirements, such as a newer Jetpack XR version or compile SDK, and break your build without warning. They also make builds non-reproducible. Pin an explicit version for production apps.

Jetpack XR version compatibility

The Cognitive3D SDK depends on the Jetpack XR (androidx.xr) libraries. Use the SDK version that matches the Jetpack XR version in your project:

Jetpack XR version	Cognitive3D SDK version	Maven artifact	Available via
1.0.0-beta01	1.2.0 and later	com.cognitive3d:android-xr-sdk	Maven Central, GitHub Releases
1.0.0-alpha10	1.1.0	Not on Maven Central	GitHub Releases (AAR only)
1.0.0-alpha09	1.0.2	com.cognitive3d:android-sdk (legacy)	Maven Central

Note

The com.cognitive3d:android-sdk artifact name was used for the Android XR SDK before version 1.1.0. From 1.1.0 onward, the Android XR SDK is published as com.cognitive3d:android-xr-sdk. If your build file still references android-sdk, switch to android-xr-sdk to get current releases.

Installing via AAR

As an alternative to Maven Central, you can install the SDK from an AAR file attached to a release on GitHub Releases:

1. Download cognitive3d-android-androidXr-release.aar from the release that matches your Jetpack XR version.
2. Place the .aar file in your app's libs/ directory.
3. Add the following to your app's build file:

KotlinGroovy

// build.gradle.kts
dependencies {
    implementation(files("libs/cognitive3d-android-androidXr-release.aar"))
}

// build.gradle
dependencies {
    implementation files('libs/cognitive3d-android-androidXr-release.aar')
}

An AAR file doesn't carry its dependencies. Add the matching Jetpack XR libraries (androidx.xr.runtime, androidx.xr.scenecore, androidx.xr.arcore, and androidx.xr.compose) to your app's build file yourself.

Step 3: Sync your project

Press Sync Now in the banner that appears, or go to File → Sync Project with Gradle Files.

Permissions

The SDK merges these permissions into your app manifest and requests them at runtime when your first activity resumes:

Permission	Required	Purpose
android.permission.HEAD_TRACKING	Yes	Head position and gaze
android.permission.HAND_TRACKING	Yes	Hand and controller tracking
android.permission.EYE_TRACKING_COARSE	No	Eye-tracked gaze
android.permission.EYE_TRACKING_FINE	No	Eye-tracked gaze

If the participant denies a required permission, the SDK doesn't record that session. If they deny eye tracking, the SDK falls back to head-based gaze.

Integration

The Cognitive3D SDK reads its settings from a cognitive3d.json file in your app's assets folder. A Gradle task generates a template for you.

1. Add the Gradle task

Add the following code to your app's build file:

KotlinGroovy

// build.gradle.kts
tasks.register("generateCognitiveConfig") {
    group = "cognitive3d"
    description = "Generates a template cognitive3d.json file in assets"
    doLast {
        val assetsDir = File(projectDir, "src/main/assets")
        if (!assetsDir.exists()) assetsDir.mkdirs()

        val configFile = File(assetsDir, "cognitive3d.json")
        if (!configFile.exists()) {
            configFile.writeText("""
                {
                "api_key": "APIKEY:DATA YOUR_APPLICATION_API_KEY",
                "gateway_url": "https://data.cognitive3d.com",
                "enable_logging": false,
                "enable_gaze": true,
                "gaze_snapshot_count": 256,
                "event_snapshot_count": 256,
                "dynamic_snapshot_count": 512,
                "sensor_snapshot_count": 512,
                "fixation_snapshot_count": 256,
                "boundary_snapshot_count": 64,
                "automatic_send_timer": 10,
                "local_data_cache_size": 104857600,
                "scene_settings": [
                    {
                    "name": "Default Scene",
                    "id": "YOUR_SCENE_ID",
                    "version": "YOUR_SCENE_VERSION",
                    "path": "${project.group}.MainActivity"
                    }
                ]
                }
            """.trimIndent())
            println("✅ Created template at: ${configFile.absolutePath}")
        } else {
            println("⚠️ cognitive3d.json already exists.")
        }
    }
}

// build.gradle
tasks.register("generateCognitiveConfig") {
    group = "cognitive3d"
    description = "Generates a template cognitive3d.json file in assets"
    doLast {
        def assetsDir = new File(projectDir, "src/main/assets")
        if (!assetsDir.exists()) assetsDir.mkdirs()

        def configFile = new File(assetsDir, "cognitive3d.json")
        if (!configFile.exists()) {
            configFile.text = """{
                "api_key": "APIKEY:DATA YOUR_APPLICATION_API_KEY",
                "gateway_url": "https://data.cognitive3d.com",
                "enable_logging": false,
                "enable_gaze": true,
                "gaze_snapshot_count": 256,
                "event_snapshot_count": 256,
                "dynamic_snapshot_count": 512,
                "sensor_snapshot_count": 512,
                "fixation_snapshot_count": 256,
                "boundary_snapshot_count": 64,
                "automatic_send_timer": 10,
                "local_data_cache_size": 104857600,
                "scene_settings": [
                    {
                    "name": "Default Scene",
                    "id": "YOUR_SCENE_ID",
                    "version": "YOUR_SCENE_VERSION",
                    "path": "${project.group}.MainActivity"
                    }
                ]
                }"""
            println("✅ Created template at: ${configFile.absolutePath}")
        } else {
            println("⚠️ cognitive3d.json already exists.")
        }
    }
}

2. Run the task

1. Open the Gradle tab in Android Studio (right sidebar).
2. Navigate to Tasks → cognitive3d → generateCognitiveConfig.
3. Double-click the task to run it.

The task creates the config file at app/src/main/assets/cognitive3d.json.

3. Configure your settings

Open the generated cognitive3d.json and update these values:

Field	Description
api_key	Your application API key, found in the Project Keys dialog via Manage Developer Key on the dashboard
scene_settings.id	Your scene ID from the Cognitive3D dashboard
scene_settings.version	Your scene version number
scene_settings.path	Your main activity path

Initialize the SDK

The SDK starts a session automatically when your first activity resumes, so no initialization code is required. It also pauses, resumes, and ends the session with your activity lifecycle.

To call the SDK from your code, import Cognitive3DManager in your activity or application class:

KotlinJava

import com.cognitive3d.android.Cognitive3DManager

import com.cognitive3d.android.Cognitive3DManager;

Config options reference

These optional settings in cognitive3d.json control how the SDK records and sends data:

Option	Default	Description
enable_logging	false	Enable debug logging
enable_gaze	true	Track user gaze data
gaze_snapshot_count	256	Gaze datapoint count before auto-sending to the dashboard
event_snapshot_count	256	Event count before auto-sending to the dashboard
dynamic_snapshot_count	512	Dynamic snapshots count before auto-sending to the dashboard
sensor_snapshot_count	512	Sensor datapoint count before auto-sending to the dashboard
automatic_send_timer	10	Seconds between automatic data sends
local_data_cache_size	104857600	Local cache size in bytes (100MB)

Next steps

Once installed and configured, you're ready to start tracking:

• Custom session properties
• Custom events
• Custom sensors
• Dynamic objects

If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.