A set of behaviors injected into the browser to perform certain operations on a page, such as scrolling, fetching additional URLs, or performing customized actions for social-media sites.
The behaviors are compiled into a single file, dist/behaviors.js
, which can be injected into any modern browser to load the behavior system.
No additional dependencies are required, and the behaviors file can be pasted directly into your browser.
The file can injected in a number of ways, using tools like puppeteer/playwright, a browser extension content script, or even a devtools Snippet, or even a regular
<script>
tag. Injecting the behaviors into the browser is outside the scope of this repo, but here are a few ways you can try the behaviors:
For an extensive walkthrough of creating your own behaviors, follow the Tutorial.
To test out the behaviors in your current browser, you can:
- Go to the dist/behaviors.js
- Copy the file (it is minified so will be on one line).
- Open a web page, such as one that has a custom behavior, like: https://twitter.com/webrecorder_io
- Open devtools console, and paste the script
- Enter
self.__bx_behaviors.run();
- You should see the Twitter page automatically scrolling and visiting tweets.
To integrate behaviors into an automated workflow, here is an short example using puppeteer.
// assumes browsertrix-behaviors is installed as a node module
const behaviors = fs.readFileSync("./node_modules/browsertrix-behaviors/dist/behaviors.js", "utf-8");
await page.evaluateOnNewDocument(behaviors + `
self.__bx_behaviors.init({
autofetch: true,
autoplay: true,
autoscroll: true,
siteSpecific: true,
});
`);
// call and await run on top frame and all child iframes
await Promise.allSettled(page.frames().map(frame => frame.evaluate("self.__bx_behaviors.run()")));
see Browsertrix Crawler for a complete working example of injection using puppeteer.
Once the behavior script has been injected, run: __bx_behaviors.init(opts)
to initialize which behaviors should be used. opts
includes several boolean options:
autofetch
- enable background autofetching of img srcsets, and stylesheets (when possible)autoplay
- attempt to automatically play and video/audio, or fetch the URLs for any video streams found on the page.autoscroll
- attempt to repeatedly scroll the page to the bottom as far as possible.timeout
- set a timeout (in ms) for all behaviors to finish.siteSpecific
- run a site-specific behavior if available.log
- a function or global string to receive log messages from behaviors
The autoplay
and autofetch
are background behaviors, and will run as soon as init(...)
is called, or as soon as the page is loaded.
Background behaviors do not change the page, but attempt to do additional fetching to ensure more resources are loaded.
Background behaviors can be used with user-directed browsing, and can also be loaded in any iframes on the page.
The autoscroll
and siteSpecific
enable 'active' behaviors, modify the page, and run until they are finished or timeout.
If both siteSpecific
and autoscroll
is specified, only one behavior is run. If a site-specific behavior exists, it takes precedence over auto-scroll, otherwise, auto-scroll is useed.
Currently, the available site-specific behaviors are available for:
Additional site-specific behaviors can be added to the site directory.
To run the active behavior, call: await __bx_behaviors.run()
after init.
Alternatively, calling await __bx_behaviors.run(opts)
will also call init(opts)
if init has not been called before.
The promised returned by run will wait for the active behavior to finish, for the timeout
time to be reached. It will also ensure any pending autoplay requests are started for the autoplay
behavior.
By default, behaviors will log debug messages to console.log
. To disable this logging, set log: false
in the init options.
This param can also be set to a custom init function by string. For example, to have behavior event messages be passed to self.my_log
, set log: "my_log"
in the options.
Additional logging options may be added soon.
Browsertrix Behaviors uses webpack to build. Run yarn run build
to build the latest dist/behaviors.js
.
Shared utility functions can be added to utils.js
while site-specific behavior can be added to lib/site
.