Integrating the SDK

Add the Cognitive3D SDK to your Meta Spatial SDK project from Maven Central, then configure it with your API key and scene. The SDK starts recording automatically when your app launches.

Requirements

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

KotlinGroovy

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

// build.gradle
dependencies {
    implementation 'com.cognitive3d:meta-spatial-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:meta-spatial-sdk:+")
}

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

Warning

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

com.cognitive3d:meta-spatial-sdk is the Cognitive3D artifact. It's separate from Meta's own com.meta.spatial:meta-spatial-sdk libraries, which your app already depends on.

Meta Spatial SDK version compatibility

Cognitive3D SDK 1.1.0 and later is built against Meta Spatial SDK 0.10.1. The SDK declares the Meta Spatial libraries it uses as runtime dependencies, so Gradle resolves them to the version your app declares when that version is newer.

Cognitive3D SDK version	Built against Meta Spatial SDK	Available via
1.2.0 and later	0.10.1	Maven Central, GitHub Releases
1.1.0	0.10.1	GitHub Releases (AAR only)

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-metaSpatial-release.aar from a release.
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-metaSpatial-release.aar"))
}

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

An AAR file doesn't carry its dependencies. Make sure your app already declares the Meta Spatial SDK libraries (meta-spatial-sdk, meta-spatial-sdk-toolkit, meta-spatial-sdk-vr, and meta-spatial-sdk-physics).

Step 3: Sync your project

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

Activity requirements

The SDK attaches to the Meta Spatial scene through your activity. Your main activity must extend AppSystemActivity, or another VrActivity subclass:

KotlinJava

import com.meta.spatial.toolkit.AppSystemActivity

class MainActivity : AppSystemActivity() {
    // ...
}

import com.meta.spatial.toolkit.AppSystemActivity;

public class MainActivity extends AppSystemActivity {
    // ...
}

If the activity isn't a VrActivity, the SDK logs Failed to initialize platform provider and doesn't record the session.

Permissions

The SDK merges com.oculus.permission.HAND_TRACKING into your app manifest and requests it at runtime when your first activity resumes.

Warning

Hand tracking permission is required. If the participant denies it, the SDK doesn't record that session.

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.