Skip to content

Getting Started with the Cognitive3DR Package

cognitive3dr is an R client for the Cognitive3D analytics API. It fetches your session data and returns tidy tibbles ready for analysis, handling authentication, pagination, property flattening, name resolution, and type coercion automatically.

Requirement(s)

  • R 4.1.0+: This package requires R version 4.1.0 or higher. To check your current version: R.version$version.string
  • Cognitive3D Account: You'll need an active Cognitive3D account to obtain your API key and project ID. You can sign up on the Cognitive3D website.

Installation

Install the development version directly from GitHub using devtools:

# install.packages("devtools")
devtools::install_github("CognitiveVR/cognitive3dr")

Authentication

Load the package and authenticate with your API key. You can pass the key directly or set the C3D_API_KEY environment variable to avoid storing credentials in your scripts.

library(cognitive3dr)

# Option 1: Pass the key directly (not recommended for shared scripts)
c3d_auth("YOUR_API_KEY_HERE")

# Option 2: Set an environment variable (recommended)
# Add this to your ~/.Renviron file:
#   C3D_API_KEY=YOUR_API_KEY_HERE
# or 
# usethis::edit_r_environ()
# Add the line: C3D_API_KEY=your_key_here

# Save and restart R
# Then authenticate like:
c3d_auth(Sys.getevn("C3D_API_KEY"))

Note

Your API key can be found in the Cognitive3D Dashboard under Organization Settings → Manage API Keys. Treat it like a password — do not commit it to source control.

Set Your Project

After authenticating, specify which project you want to query. Your project ID is visible in the Cognitive3D Dashboard URL when viewing a project (e.g., app.cognitive3d.com/project/4460/...).

c3d_project(4460)  # Replace with your project ID

This sets a session-level default so you don't need to pass project_id to every function call.

Quick Start

Once authenticated and your project is set, you can pull data in just a few lines:

library(cognitive3dr)

c3d_auth()         # reads C3D_API_KEY from environment
c3d_project(4460)  # set default project

# Fetch the last 100 sessions
sessions <- c3d_sessions(n = 100)

# Fetch custom events from the last 30 days
events <- c3d_events()

# Fetch objective completion data with step-level detail
results <- c3d_objective_results(include_steps = TRUE)

# Fetch ExitPoll survey response counts
polls <- c3d_exitpoll()

All functions return tibbles, making them compatible with dplyr, ggplot2, and other tidyverse tools.

Common Parameters

Most data-fetching functions share a consistent set of filter parameters:

Parameter Type Default Description
project_id Integer from c3d_project() Cognitive3D project ID
start_date Date / string 30 days ago Start of the date range ("YYYY-MM-DD")
end_date Date / string now End of the date range ("YYYY-MM-DD")
exclude_test Logical TRUE Filter out sessions tagged as test
exclude_idle Logical TRUE Filter out sessions tagged as junk or idle
min_duration Numeric none Minimum session duration to include in results, in seconds

Next Steps

  • Sessions — Fetch session-level data with c3d_sessions()
  • Events — Retrieve custom event records with c3d_events()
  • Objectives — Query objective and step completion with c3d_objective_results()
  • ExitPoll — Pull survey response counts with c3d_exitpoll()

intercom 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.