Integrating the SDK

Add the Cognitive3D SDK for Android to your app from Maven Central, then configure it with your API key and a scene. The SDK starts recording automatically when your app launches, with no initialization code.

Requirements

• Android Studio Narwhal (2025.1.1) or later.
• 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:

KotlinGroovy

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

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

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-sdk:+")
}

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

Warning

Dynamic versions (+) can pull in a release with different build requirements and break your build without warning. They also make builds non-reproducible. Pin an explicit version for production apps.

Note

Versions 1.0.0 to 1.0.2 of com.cognitive3d:android-sdk are early Android XR builds, not this SDK. Use version 1.3.0 or later. For Android XR apps, use com.cognitive3d:android-xr-sdk instead.

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 requires no runtime permissions. It merges INTERNET and ACCESS_NETWORK_STATE into your app manifest to send data and read the Wi-Fi signal.

If you enable audio recording, your app must also declare android.permission.RECORD_AUDIO in its own manifest. The SDK doesn't merge it.

Set up a scene

The SDK needs a scene ID in its configuration, even if your app has no 3D scene. If you don't have scene geometry, create a scene with the Empty Scene sample in the Upload Web App.

After you upload the scene, press Download Scene Settings to save its sceneId and versionNumber. You enter these values in cognitive3d.json in the next section.

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

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.