Workshop: Customizing Browsertrix with Behaviors

September 18, 10:00-11:30 EDT | 16:00-17:30 CEST

September 24, 19:00-20:00 EDT [follow-up Q&A: TBC]

Registration: This event is for IIPC Members. Registration links are available in the Members-only Archive. Contact staff[at]netpreserve.org if you don’t have access.

Developed by Webrecorder, Browsertrix is a powerful browser-based crawling tool that has been gaining popularity with organizations that need customized, high-fidelity web captures. A key feature is its use of behaviors, which are automated actions that can be run on each page during a crawl. Behaviors are “one more way Browsertrix makes it easy to capture the web exactly the way you want” (Tessa Walsh).

Browsertrix offers several types of behaviors:

• Built-in behaviors that come included with the crawler:
  • Background behaviors for common actions like scrolling, clicking on page elements, and auto-playing videos.
  • Site-specific behaviors for supported social media sites such as Instagram, Facebook, X/Twitter, and TikTok.  
• Fully user-defined custom behaviors that can be created for any page using the Chrome DevTools Recorder or written in JavaScript.

As the Browsertrix community grows, so does the knowledge base. Web archiving curators, in particular, have been using the tool and have accumulated valuable experience and solutions. This workshop aims to share that accumulated knowledge and help create a repository of use cases.

Goals

This workshop is designed to help you leverage the full potential of Browsertrix behaviors and to help you go beyond the basics. Our goals for the workshop are threefold:

• Built-in behaviors: we will dive into the best practices for using built-in behaviors, focusing on common challenges and practical workarounds.
• Custom behaviors: we will explore use cases for creating your own custom behaviors, show you how to document and implement them effectively.
• Reuse: we will share tips on how some site-specific behaviors can be run on other sites.

The session aims to address the following key areas:

Understanding and troubleshooting behaviors

• Principle of least effort: Learn how to use built-in behaviors like autoclick to their full effectiveness and when it may not be necessary to develop new custom behaviors.
• Limits and modification: Learn the limitations of new behaviors and how to modify them effectively.
• Error interpretation: Gain an understanding of how to interpret console error messages that occur during or after a crawl.
• Problem levels: Divide troubleshooting into different levels of difficulty, from easy to medium to hard.

Roles and workflow

• Behavior differentiation: Learn to differentiate between a behavior recorded by a curator and one developed by a developer.
• Workflow for curators: Establish a clear workflow that defines the types of behaviors curators can use or create on their own and when they should request developer assistance.

Best practices and brainstorming

• Repository/Awesome list: Brainstorm the best location for a repository of tried-and-tested behaviors for different types of content.
• Discoverability: Discuss the best methods for describing these behaviors to make them easily discoverable by other users.

This workshop builds on insights from past conference presentations and valuable examples shared by the community.

Prerequisites

To get the most out of this session, you should have:

• A basic understanding of Browsertrix (both cloud and local versions).
• Familiarity with the official Browsertrix documentation and the recent Webrecorder blog post on behaviors.
• Watched relevant past presentations on Browsertrix.

Target audience

The workshop is designed for anyone who uses Browsertrix. Much of the material covered will be for a non-technical audience. However, since we will also be covering how to debug and develop new behaviors, developers should find it valuable as well.

Having both curators and developers attend the event could foster a deeper understanding of how curators can create and use behaviors on their own, and when it is helpful to team up with developers.

Format

• This workshop will primarily be a “show-and-tell” session presented by the Webrecorder Team, building on the content from the Oslo workshop. It will cover in-built features, but the primary focus will be on custom behaviors.
• The session will include a presentation with examples from Webrecorder, as well as use cases submitted by other IIPC member organizations. There will be no hands-on component, but participants are encouraged to ask questions throughout the event. To get the most out of the workshop, attendees should have a basic familiarity with Browsertrix.
• Parts of the presentation will be recorded and shared with members. Depending on interest, we may schedule a shorter follow-up Q&A session for the following week.

References and resources

• https://www.youtube.com/watch?v=GHqgikgr8I4 [Introducing Browsertrix: General Overview]
• https://webrecorder.net/blog/2025-05-28-create-use-and-automate-actions-with-custom-behaviors-in-browsertrix
• https://crawler.docs.browsertrix.com/user-guide/behaviors
• https://github.com/webrecorder/custom-behaviors
• https://archiveweb.page/en/features/behaviors
• https://netpreserve.org/members-only-archive/scaling-browsertrix-crawls