Database

Introduction

Our framework uses a MongoDB database with five collections that are created upon session start and during gameplay logging.

Collection Name	Description
devices	Stores user device variables and their current states per session and device
explanations	Stores generated explanations along with user ratings and interaction metadata
logs	Stores detailed logs of user interactions with the system during gameplay
sessions	Stores general session information including identifiers, timestamps, and user context
tasks	Stores user progress and performance on gameplay tasks

Devices

The 'devices' collection stores device states and properties for each user in the form of JSON objects. Each object corresponds to a particular device in the smart environment for a specific session.

Fields

• _id: Internal MongoDB Object ID.
• userSessionId: References the session this device belongs to (sessions.sessionId).
• deviceId: Unique ID of the device, matches the id field in game.json.
• deviceInteraction: Array of objects describing the current interaction state (see Interacting with Devices) of the device.

Each element in deviceInteraction includes:

• name: Name of the interaction variable (e.g., “Power”, “Temperature”)
• type: Interaction type (e.g., "Boolean_Action")
• value: Current value of the device parameter

Example

{
  "_id": {
    "$oid": "6890802b170e8ab76cd90c50"
  },
  "userSessionId": "a9297ea7-8f3a-4fcd-abd3-ae3bed267494",
  "deviceId": "deep_fryer",
  "deviceInteraction": [
    {
      "name": "Power",
      "type": "Boolean_Action",
      "value": false
    },
    {
      "name": "Temperature",
      "type": "Numerical_Action",
      "value": 0
    }
  ]
}

• userSessionId: User Session ID, references sessions.sessionId
• deviceId: Device ID, matches device id in game.json
• deviceInteraction: Array of JSON objects for each device interaction, containing the interaction name, type, and current value

Logs

The logs collection stores all user-generated actions and system events during gameplay. Each entry records a single event along with a timestamp, session reference, and context-specific metadata.

Fields

• _id: Internal MongoDB Object ID.
• type: Type of the logged event (see Log Types below).
• metadata: Event-specific metadata (e.g., task ID, rule ID, device ID).
• timestamp: Unix timestamp of when the event occurred.
• userSessionId: References the session in which the event occurred (sessions.sessionId).

Example

{
  "_id": {
    "$oid": "6890802e170e8ab76cd90c55"
  },
  "type": "TASK_BEGIN",
  "metadata": {
    "task_id": "deep_fryer"
  },
  "timestamp": 1754300462,
  "userSessionId": "a9297ea7-8f3a-4fcd-abd3-ae3bed267494"
}

• type: Log type, see Log Types section below
• metadata: Metadata for relevant log types, such as task ID
• timestamp: Unix timestamp of log creation
• userSessionId: User Session ID, references sessions.sessionId

Log Types

Each log entry’s type field corresponds to one of the following predefined event types, handled by the platform’s Logger class.

Log Type	Description	Metadata Fields
RULE_TRIGGER	Triggered when a smart home automation rule activates	rule_id, rule_action
TASK_BEGIN	User starts a new task	task_id
TASK_COMPLETED	User successfully completes a task	task_id
TASK_TIMEOUT	Task duration exceeded the allowed time limit	task_id
ABORT_TASK	Task was aborted manually or by the system	task_id, abort_reason
DEVICE_INTERACTION	User interacts with a device (e.g., toggling, adjusting value)	Device-specific metadata
WALL_SWITCH	User switches view to a different wall within the same room	room, wall
ENTER_DEVICE_CLOSEUP	User enters close-up view of a device	device
EXIT_DEVICE_CLOSEUP	User exits close-up view of a device	device
ROOM_SWITCH	User moves from one room to another	destination_room, destination_wall

RULE_TRIGGER

Logged when automated rules are triggered in the smart home environment.

Metadata:

• rule_id: ID of the triggered rule
• rule_action: Action performed by the rule

TASK_BEGIN

Logged when a user starts a new task.

Metadata:

• task_id: ID of the task being started

TASK_COMPLETED

Logged when a user successfully completes a task.

Metadata:

• task_id: ID of the completed task

TASK_TIMEOUT

Logged when a task exceeds its time limit.

Metadata:

• task_id: ID of the task that timed out

ABORT_TASK

Logged when a user or system aborts a task.

Metadata:

• task_id: ID of the aborted task
• abort_reason: Reason for task abortion

DEVICE_INTERACTION

Logged when a user interacts with smart home devices.

Metadata:

• Device-specific interaction data (varies by device type and interaction)

WALL_SWITCH

Logged when user switches between walls in a room.

Metadata:

• room: Name of the room
• wall: Wall identifier being switched to

ENTER_DEVICE_CLOSEUP

Logged when user enters device closeup/interaction mode.

Metadata:

• device: Device identifier being accessed

EXIT_DEVICE_CLOSEUP

Logged when user exits device closeup mode.

Metadata:

• device: Device identifier being exited

ROOM_SWITCH

Logged when user navigates between different rooms via doors.

Metadata:

• destination_room: Target room being navigated to
• destination_wall: Target wall within the destination room

Sessions

The 'sessions' collection stores general metadata about a user’s study session, including timing, client settings, custom parameters, and socket connections.

Fields

• _id: Internal MongoDB Object ID.
• sessionId: Unique identifier for the session.
• startTime: Timestamp marking when the session began.
• lastActivity: Timestamp of the most recent interaction in the session.
• userAgent: User’s browser and system information string.
• screenSize: Screen dimensions used by the participant.
  • width: Screen width in pixels
  • height: Screen height in pixels
• isCompleted: Boolean indicating whether the session was successfully completed.
• completionTime: Timestamp of session completion (if applicable).
• customData: User-specific metadata, passed through the URL as base64-encoded data when launching the study. Includes fields like:
  • Condition: Experimental condition assigned
  • Technical_Interest: Self-reported interest in technology
  • User_Name: Name or label of participant (if provided)
• explanation_cache: Cached explanation object, used only in on-demand explanation mode.
• socketId: Latest Socket.io connection ID for real-time communication.

Example

{
  "_id": {
    "$oid": "6890802b170e8ab76cd90c4c"
  },
  "sessionId": "a9297ea7-8f3a-4fcd-abd3-ae3bed267494",
  "startTime": {
    "$date": "2025-08-04T09:40:59.417Z"
  },
  "lastActivity": {
    "$date": "2025-08-04T09:40:59.417Z"
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
  "screenSize": {
    "width": 1280,
    "height": 665
  },
  "isCompleted": true,
  "completionTime": {
    "$date": "2025-08-04T09:44:09.273Z"
  },
  "customData": {
    "Condition": 2,
    "Technical_Interest": "interested",
    "User_Name": "John"
  },
  "explanation_cache": null,
  "socketId": "ODKC-GRRXqG6JI_CAAAD"
}

Tasks

The 'tasks' collection stores information about each user’s progress for individual tasks in a gameplay session. Similar to devices, there may be multiple entries per user session—one per task.

Fields

• _id: Internal MongoDB Object ID.
• userSessionId: References the session during which the task was executed (sessions.sessionId).
• taskId: Unique task identifier, matches id field in game.json.
• task_order: Order in which the task appears in the gameplay sequence (starting from 0).
• taskDescription: Human-readable task prompt shown to the user.
• isCompleted: true if the user completed the task successfully.
• isAborted: true if the task was aborted (e.g., by user or system).
• isTimedOut: true if the task exceeded its time limit.
• completionTime: Timestamp of successful completion (if any).
• abortedReason: Explanation for abortion (if any).
• startTime: Timestamp of when the task began.
• endTime: Timestamp of when the task ended (regardless of outcome).
• interactionTimes: Number of user interactions during the task.
• duration: Time taken to complete or exit the task, in seconds.

Example

{
  "_id": {
    "$oid": "6890802b170e8ab76cd90c4d"
  },
  "userSessionId": "a9297ea7-8f3a-4fcd-abd3-ae3bed267494",
  "taskId": "deep_fryer",
  "task_order": 0,
  "taskDescription": "Turn on the deep fryer",
  "isCompleted": false,
  "isAborted": false,
  "isTimedOut": true,
  "completionTime": null,
  "abortedReason": null,
  "startTime": {
    "$date": "2025-08-04T09:40:59.420Z"
  },
  "endTime": {
    "$date": "2025-08-04T09:43:00.414Z"
  },
  "interactionTimes": 5,
  "duration": 120.994
}

Explanations

The explanations collection stores all explanations presented to users during gameplay. Each entry includes the explanation content, timing, session context, task context, and user feedback (if provided).

Fields

• _id: Internal MongoDB Object ID.
• explanation_id: UUID uniquely identifying the explanation event.
• explanation: Text content of the explanation shown to the user.
• created_at: Timestamp of when the explanation was generated or displayed.
• userSessionId: References the session during which the explanation was triggered (sessions.sessionId).
• taskId: ID of the task associated with the explanation (if applicable).
• delay: Delay (in seconds) between triggering and showing the explanation, defined by the associated rule.
• rating: Object containing user feedback:
  • is_liked: Boolean indicating whether the user liked the explanation. This field is added only after the user interacts with the feedback UI. Example

{
  "_id": {
    "$oid": "68a441d567cee9ab1e3d0f8d"
  },
  "explanation_id": "13a674b5-b762-4650-8101-2fbe7e5d08cd",
  "explanation": "Since the cooker hood is not turned on, the deep fryer cannot be turned on.",
  "created_at": {
    "$date": "2025-08-19T09:20:21.854Z"
  },
  "userSessionId": "06711ce4-a2af-4e62-9026-17231df6a985",
  "taskId": "deep_fryer",
  "delay": 0,
  "rating": {
    "is_liked": true
  }
}