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.

Step 3: Sync Your Project

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

Integration

Generate the Config File

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.