Participant Configuration

src/extension/config.json is the central configuration file for your extension. It controls which modules are active, what text participants see, which sites to record, and where to send data. Changes to this file require a rebuild: run npm run build after editing.

What config.json controls

Which modules are enabled
Lists that control which sites are recorded, and in how much detail
The URL where the extension fetches updated configuration at runtime
Any module-specific settings (e.g., which search engines to mirror, which AI platforms to spider)

configuration_url

configuration_url tells the extension where to load its configuration from. Pointing it at a server is useful for deployed studies where you want to update settings (for example, adding sites to an allow list) without rebuilding and redistributing the extension.

"configuration_url": "https://yourdomain.com/config.json"

For a study with no server, use rex-config://config.json, which loads the configuration bundled with the extension (the demo does this):

"configuration_url": "rex-config://config.json"

For a server, use an https:// URL. <IDENTIFIER> in the URL is replaced with the participant’s ID, so each participant can get their own configuration:

"configuration_url": "https://yourdomain.com/config.json?identifier=<IDENTIFIER>"

Module config sections

Each module reads its own section of config.json. The section key uses underscores and must match what the module expects. At minimum, each module needs "enabled": true to activate. Example for rex-history:

"history": {
  "enabled": true,
  "allow_lists": ["news-sites"]
}

The module map lists which config section each module reads. Field-level documentation for each module is still being written.

List configuration

Lists are named sets of domain and URL patterns, stored by rex-lists. You define them in the lists section of the configuration and refer to them by name in each module’s section. rex-history uses four kinds:

allow_lists: visits that match are recorded in full. When allow lists are set, other visits are recorded as CATEGORY:NOT_ON_ALLOWLIST, with the URL, title, and domain removed.
filter_lists: visits that match have their URL replaced by the entry’s category, such as CATEGORY:email.
category_lists: visits that match are tagged with the entry’s category.
domain_only_lists: visits that match keep the domain but not the URL or title.

"history": {
  "enabled": true,
  "allow_lists": ["news-sites"],
  "domain_only_lists": ["social-media-sites"]
}

Each name ("news-sites" here) must match a list defined in the lists section. In every case the time of the visit is kept. See the rex-history README for the full behavior and the rex-lists README for the list format.

Annotated full example

Here is a realistic config.json for a study that collects browsing history and stores data locally. The _comment keys are non-functional annotations (JSON has no native comment syntax) that help you and future collaborators understand the config at a glance.

{
  "_comment": "Study config for an example study. Data stays on the participant's device.",
  "name": "Example Study",
  "configuration_url": "rex-config://config.json",

  "history": {
    "_comment": "Record news and reference sites in full; everything else as a timestamp only.",
    "enabled": true,
    "collection_interval_minutes": 60,
    "lookback_days": 30,
    "allow_lists": ["study-allow"]
  },

  "lists": {
    "study-allow": [
      { "pattern": "wikipedia.org", "pattern_type": "domain", "metadata": { "category": "reference" } },
      { "pattern": "example-news.org", "pattern_type": "domain", "metadata": { "category": "news" } }
    ]
  },

  "local_download": {
    "_comment": "Store data locally. Replace with passive_data_kit for a server.",
    "enabled": true
  }
}

When you are ready to move to a production server, swap local_download for passive_data_kit (and the rex-local-download module for rex-passive-data-kit) and set configuration_url to your server’s config endpoint. See Production Backend for that step.