Installation and integration

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

Requirements

• Android Studio Hedgehog (2023.1.1) or later
• Minimum SDK: 29
• Kotlin 1.9+ or Java 11+

Installation

Step 1: Add Maven Central Repository

In your project's settings.gradle.kts, ensure 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:

KotlinGroovy

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

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

To always use the latest version, you can use a dynamic version:

KotlinGroovy

    implementation("com.cognitive3d:android-sdk:+")

    implementation 'com.cognitive3d:android-sdk:+'

Warning

Dynamic versions (+) are convenient but can lead to non-reproducible builds and unexpected breaking changes. For production apps, we recommend pinning to a specific version.

AndroidX XR Version Compatibility

The Cognitive3D SDK depends on AndroidX XR libraries. You must use the SDK version that matches the AndroidX XR alpha version in your project.

AndroidX XR version	Available via
alpha09	Maven Central, GitHub Releases
alpha10	GitHub Releases

Make sure to download the AAR that matches the AndroidX XR alpha version used in your project.

Installing via AAR

As an alternative to Maven Central, or if you need a specific AndroidX XR alpha version, you can install the SDK using the AAR file from our GitHub Releases:

1. Download the .aar file matching your AndroidX XR version from the releases page
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-xrAlpha10-release.aar"))
}

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

Step 3: Sync Your Project

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

Integration

The Cognitive3D SDK requires a configuration file in your assets folder. We provide a Gradle task to generate a template automatically.

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_API_KEY_HERE",
                "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_HERE",
                    "version": "YOUR_SCENE_VERSION_HERE",
                    "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_API_KEY_HERE",
                "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_HERE",
                    "version": "YOUR_SCENE_VERSION_HERE",
                    "path": "${project.group}.MainActivity"
                    }
                ]
                }"""
            println("✅ Created template at: ${configFile.absolutePath}")
        } else {
            println("⚠️ cognitive3d.json already exists.")
        }
    }
}

2. Run the Task

• Open the Gradle tab in Android Studio (right sidebar)
• Navigate to Tasks → cognitive3d → generateCognitiveConfig
• Double-click to run

The config file appears in app/src/main/assets/cognitive3d.json.

3. Configure Your Settings

Open the generated cognitive3d.json and update these values:

Field	Description
api_key	Your Cognitive3D API key from 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

Import the Cognitive3D library in your activity or application class:

KotlinJava

    import com.cognitive3d.android.Cognitive3DManager

    import com.cognitive3d.android.Cognitive3DManager;

You're now ready to use the SDK throughout your application.

(Optional) Config Options Reference

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.