Online Behavioural Research Methods: Programming with jsPsych
An open source textbook for psychology students learning programming and online research methods.
Primary Author: Nicholaus P. Brosowsky
Co-Authors: Liam Yeo, Jackie Spear
Introduction
This textbook is designed to teach you how to create online behavioural experiments using modern web technologies, with a particular focus on jsPsych, a JavaScript library specifically built for psychological research. Originally developed for my Research in Cognitive Psychology course at the University of Manitoba, this book provides a comprehensive introduction to programming online studies that can be used by anyone interested in conducting behavioural research on the web.
While the examples and labs throughout this book draw primarily from cognitive psychology research, reflecting my background as a cognitive psychologist, the principles and techniques you’ll learn are broadly applicable to any field conducting online behavioural studies.
Book Structure and Learning Path
The book is structured to take you from complete beginner to competent online experiment programmer through a carefully scaffolded progression. You’ll start by learning the fundamental web technologies that power all online experiments: HTML for structure, CSS for styling, and JavaScript for interactivity. These foundational skills are essential because jsPsych, like all web-based experiment platforms, builds upon these core technologies.
Once you have a solid grasp of the fundamentals, you’ll dive into jsPsych itself, learning how this specialized library can dramatically simplify the process of creating psychological experiments. You’ll discover how to present stimuli, collect responses, measure precise timing data, and manage the flow of your experiments through jsPsych’s intuitive plugin system and timeline structure.
As you progress through the units, you’ll tackle increasingly sophisticated experimental designs. You’ll learn to incorporate multimedia elements like images, audio, and video into your studies. You’ll master techniques for creating dynamic, responsive experiments that adapt based on participant responses. You’ll explore methods for properly saving and organizing your data, implementing randomization strategies, and even adding gamification elements to enhance participant engagement.
Each unit combines theoretical instruction with hands-on laboratory exercises that reinforce your learning through practical application. These labs guide you through creating experiments that investigate classic phenomena in cognitive psychology, from memory and attention to decision-making and face perception. By working through these exercises, you’ll not only learn programming techniques but also gain insights into experimental design principles that are important for conducting rigorous behavioural research.
Learning Outcomes
By the end of this book, you’ll have the skills to design, implement, and deploy sophisticated online behavioural experiments. More importantly, you’ll understand the underlying principles that will allow you to adapt these techniques to your own research questions and continue learning as web technologies evolve. Whether you’re planning to conduct your own research, collaborate with other investigators, or simply want to understand how online studies work, this book will provide you with a solid foundation in the art and science of web-based behavioural research.
Prerequisites
This textbook is designed to be accessible to complete beginners with no prior programming experience. The only requirements are a computer and a modern web browser (Chrome, Firefox, Safari, or Edge)
No Software Installation Required: Everything we’ll do happens in your web browser and all the files can be edited with any text editor. You won’t need to download or install any programming software, text editors, or development tools.
jsPsych V8: This textbook uses version 8 of jsPsych. When navigating to the documentation, please make sure you are using version 8: https://www.jspsych.org/v8/
Academic Background: While the examples focus on cognitive psychology, no specific psychology background is required. The book explains psychological concepts as they arise, making it suitable for students from any discipline interested in online behavioral research.
Time Commitment: This book is designed around a 13-week course structure, with each chapter and associated lab tutorial intended to be completed within one week. Most students should expect to spend 3-5 hours per week on reading, exercises, and lab work, though this may vary depending on your familiarity with the concepts and your learning pace.
Getting Setup
For this book, we’re going to adopt the quickest and simplest method to get you started. The majority of the book can be completed offline by first downloading the lab materials using this link.
You’ll need to unzip the folder and move it somewhere it can be stored on your computer (e.g., Documents).
The files inside this folder can be edited using any text editor. However, there are many text editors with built-in tools to make it easier to program by formatting the text in a way that highlights the important parts. Webstorm is one that I would recommend that is free to use available here: https://www.jetbrains.com/webstorm/download/.
Later in the book, we’ll discuss options in terms of hosting your experiment so anyone can access it through a website URL and saving data to a server.
A Note About This Textbook
This is the first edition of this textbook, developed specifically for hands-on learning in an evolving field. As with any first edition, you may (probably will..) encounter errors, unclear explanations, or technical issues. This is a work in progress!
If you encounter problems:
Technical issues with code examples: Check that you’ve followed all steps exactly as written, then try refreshing your browser or waiting a few minutes (GitHub Pages can take time to update)
Errors or unclear content: Please report these by visiting the textbook’s GitHub repository at https://github.com/icoglab/online-behavioural-research-methods and clicking on the “Issues” tab to log a new issue
Suggestions for improvement: We welcome feedback about content that could be explained more clearly or additional topics that would be helpful
Your feedback helps improve this resource for future students. Don’t hesitate to report even minor issues like typos or broken links. Contributing to the improvement of educational resources is part of learning to work collaboratively in the open-source community that powers much of modern web development.
Version Information: This textbook will be updated regularly based on student feedback and changes in web technologies. Check the repository for the most current version and any important updates or corrections.
Getting Started Mindset
Remember that every expert programmer started exactly where you are now. The files you’ll be editing are just text with special formatting rules. Your browser is remarkably forgiving, so if something doesn’t work perfectly the first time, you can always edit the text and try again.
Think of programming your experiment like writing instructions for a very literal assistant. You need to be specific and clear, but the basic building blocks are straightforward. By the end of this course, you’ll be amazed at what you can create with just text files and a web browser.