Custom session properties

While custom events capture what happened, properties describe the context in which things happen. Properties are key-value pairs that persist throughout a session, providing metadata for all events and interactions.

Cognitive3D distinguishes between two types:

• Participant Properties describe the user, who they are, their role, their preferences
• Session Properties describe the environment, app configuration, workspace settings, device state

Think of properties as dimensions you can use to segment and filter your analytics data. For example, you might ask: "How does model loading time differ between hosts and guests?" or "Do users in full-space mode engage more than those in home-space mode?"

Use Participant Properties for:

• User identity (ID, display name)
• Account attributes (subscription tier, organization)
• Role or permissions (host, guest, viewer, editor)
• User preferences or settings
• Experience level or onboarding state

Use Session Properties for:

• App mode or configuration (full-space, home-space)
• Workspace or room identifiers
• Device or environment information
• Collaboration settings (max participants, permissions)

Participant Properties

Set participant properties early in the session, typically during authentication or app initialization:

KotlinJava

// Core identity
Cognitive3DManager.setParticipantId("user_12345")
Cognitive3DManager.setParticipantFullName("John Smith")

// Custom attributes
Cognitive3DManager.setParticipantProperty("role", "architect")
Cognitive3DManager.setParticipantProperty("organization", "Acme Design Co")
Cognitive3DManager.setParticipantProperty("subscription_tier", "professional")
Cognitive3DManager.setParticipantProperty("experience_level", "expert")

// Core identity
Cognitive3DManager.setParticipantId("user_12345");
Cognitive3DManager.setParticipantFullName("Parisa Srg");

Cognitive3DManager.setParticipantProperty("role", "architect");
Cognitive3DManager.setParticipantProperty("organization", "Acme Design Co");
Cognitive3DManager.setParticipantProperty("subscription_tier", "professional");
Cognitive3DManager.setParticipantProperty("experience_level", "expert");

The setParticipantId and setParticipantFullName methods are convenience functions for common identity fields. Use setParticipantProperty for any custom attributes.

Session Properties

Set session properties when the session context is established:

KotlinJava

// App configuration
Cognitive3DManager.setSessionProperty("app_mode", "full_space")

// Workspace context
Cognitive3DManager.setSessionProperty("workspace_id", "ws_abc123")
Cognitive3DManager.setSessionProperty("workspace_name", "Q4 Design Review")
Cognitive3DManager.setSessionProperty("room_code", "ABC-123")

// Collaboration settings
Cognitive3DManager.setSessionProperty("collaboration_enabled", true)
Cognitive3DManager.setSessionProperty("max_participants", 8)
Cognitive3DManager.setSessionProperty("voice_chat_enabled", true)

// App configuration
Cognitive3DManager.setSessionProperty("app_mode", "full_space");

// Workspace context
Cognitive3DManager.setSessionProperty("workspace_id", "ws_abc123");
Cognitive3DManager.setSessionProperty("workspace_name", "Q4 Design Review");
Cognitive3DManager.setSessionProperty("room_code", "ABC-123");

// Collaboration settings
Cognitive3DManager.setSessionProperty("collaboration_enabled", true);
Cognitive3DManager.setSessionProperty("max_participants", 8);
Cognitive3DManager.setSessionProperty("voice_chat_enabled", true);

Examples

Session properties and participant properties both record some data. When deciding which type to use, ask: "Does this describe the person, or the environment they're in?". Some examples:

Complete initialization on app launch

Setting up analytics context early ensures all subsequent events and interactions are properly attributed to the correct user and session. Initialize participant and session properties as soon as the user authenticates and the workspace loads:

KotlinJava

fun initializeAnalyticsContext(user: User, workspace: Workspace, config: AppConfig) {
    // Participant: Who is this user?
    Cognitive3DManager.setParticipantId(user.id)
    Cognitive3DManager.setParticipantFullName(user.displayName)
    Cognitive3DManager.setParticipantProperty("email_domain", user.email.substringAfter("@"))
    Cognitive3DManager.setParticipantProperty("role", user.workspaceRole.name)  // "host", "editor", "viewer"
    Cognitive3DManager.setParticipantProperty("is_host", (user.id == workspace.hostId).toString())
    Cognitive3DManager.setParticipantProperty("organization_id", user.organizationId)
    Cognitive3DManager.setParticipantProperty("account_age_days", user.accountAgeDays.toString())

    // Session: What's the environment?
    Cognitive3DManager.setSessionProperty("app_mode", config.spaceMode.name)
    Cognitive3DManager.setSessionProperty("workspace_id", workspace.id)
    Cognitive3DManager.setSessionProperty("workspace_name", workspace.displayName)
    Cognitive3DManager.setSessionProperty("project_id", workspace.projectId)
    Cognitive3DManager.setSessionProperty("expected_participant_count", workspace.invitedCount.toString())
    Cognitive3DManager.setSessionProperty("voice_chat_enabled", config.voiceChatEnabled.toString())
}

public void initializeAnalyticsContext(User user, Workspace workspace, AppConfig config) {
    // Participant: Who is this user?
    Cognitive3DManager.setParticipantId(user.getId());
    Cognitive3DManager.setParticipantFullName(user.getDisplayName());

    String emailDomain = user.getEmail().substring(user.getEmail().indexOf("@") + 1);
    Cognitive3DManager.setParticipantProperty("email_domain", emailDomain);
    Cognitive3DManager.setParticipantProperty("role", user.getWorkspaceRole().name());

    boolean isHost = user.getId().equals(workspace.getHostId());
    Cognitive3DManager.setParticipantProperty("is_host", String.valueOf(isHost));
    Cognitive3DManager.setParticipantProperty("organization_id", user.getOrganizationId());
    Cognitive3DManager.setParticipantProperty("account_age_days", String.valueOf(user.getAccountAgeDays()));

    // Session: What's the environment?
    Cognitive3DManager.setSessionProperty("app_mode", config.getSpaceMode().name());
    Cognitive3DManager.setSessionProperty("workspace_id", workspace.getId());
    Cognitive3DManager.setSessionProperty("workspace_name", workspace.getDisplayName());
    Cognitive3DManager.setSessionProperty("project_id", workspace.getProjectId());
    Cognitive3DManager.setSessionProperty("expected_participant_count", String.valueOf(workspace.getInvitedCount()));
    Cognitive3DManager.setSessionProperty("voice_chat_enabled", String.valueOf(config.isVoiceChatEnabled()));
}

Best Practices

When to set properties

• Set participant properties immediately after authentication
• Set session properties when the session context is fully established

Participant vs Session

• Ask: "Does this describe the person, or the environment they're in?"
• User's role → Participant (it's about who they are in this context)
• Workspace's max capacity → Session (it's about the environment configuration)
• User's subscription tier → Participant (account-level attribute)
• Whether voice chat is enabled → Session (workspace configuration)

Value formatting

• Keep values concise and categorical when possible (easier to filter and group)
• Avoid putting large text blocks or serialized objects in properties

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.