Participant Onboarding

Once your extension is ready, participants need to install it and get it running. This page covers the two ways to distribute it and what participants experience.

Distribution options

Option A: Chrome Web Store (recommended for most studies)

Publish your extension as Unlisted and share the direct install link. Participants install with one click and no technical steps. See Chrome Web Store for publishing instructions.

Option B: Load unpacked (small studies, known participants)

Skip the Web Store entirely. Share the dist/extension/ folder with participants (e.g., as a zip via Box or Google Drive) and walk them through loading it manually. This works well when you know your participants personally and can guide them through setup: no developer account or review process required.

Steps to share with participants:

Build your extension: npm run build
Zip the dist/extension/ folder and share it securely
Participants unzip it, then open chrome://extensions, turn on Developer mode, click Load unpacked, and select the folder

Note: Chrome may show a warning that the extension is not from the Web Store. Participants can dismiss this.

What participants need

Chrome or Edge: REX extensions run in Chromium-based browsers. Firefox is not supported. If your participants might use Firefox as their primary browser, address this in your enrollment communications.
Chrome 130 or later. See Set a minimum Chrome version.
The install link or folder: depending on your distribution method above.

Install flow

Participant clicks the install link you provide.
Chrome opens the Web Store listing page for your extension.
Participant clicks Add to Chrome.
A permissions dialog appears listing what the extension will access.
Participant clicks Add extension to confirm.
The extension installs and the icon appears in the browser toolbar.

The whole process takes under a minute if the participant is ready to proceed.

The permissions dialog

Chrome shows participants a list of permissions the extension requires before they confirm installation. For a typical REX study extension, this includes access to browsing history, tabs, and page content.

Participants sometimes hesitate at this dialog. It helps to prepare them in advance. In your onboarding materials, explain what each permission is for in plain language:

Read your browsing history (Chrome may word this differently): this is how the extension records which sites you visit as part of the study
Read and change all your data on websites you visit: this covers content injection (if your study uses page manipulation) and reading page content; explain specifically what your study does and does not do with this

Be accurate. If your extension does not modify pages, say so. Participants who understand why permissions are needed are less likely to uninstall the extension mid-study.

First run

After installation, the extension will prompt the participant to enter their study ID.

Where participants get their ID: You assign participant IDs and share them before or at the point of enrollment. Common approaches are including the ID in the enrollment confirmation email, displaying it on a study landing page after they complete a screening survey, or embedding it in the install link as a URL parameter if your extension supports that.

Whatever method you use, make sure participants know their ID before they click the install link. The ID entry screen appears immediately and participants may not know where to look if they have not been prepared.

After entering their ID, the extension becomes active. If you included an acknowledgement screen, participants will see that before the main interface.

Verifying the extension is working

Participants can check by clicking the extension icon in the toolbar. If the extension is active and recording, the main interface will show a status indicator confirming it is running. If you used rex-local-download, they can also click the download button and confirm a JSON file downloads successfully.

It is worth asking participants to verify during your initial contact after enrollment, before any significant time has passed.

Troubleshooting

Extension not appearing in the toolbar

The extension may be installed but not pinned to the toolbar. Ask the participant to click the puzzle piece icon in the top-right of Chrome, find the extension in the list, and click the pin icon.

Extension appears but shows a disabled state

Go to chrome://extensions and check that the toggle next to the extension name is on. If it was automatically disabled, there may be an error indicator: a small warning icon. Ask the participant to share a screenshot so you can investigate.

Participant ID not accepted

IDs are case-sensitive. Ask the participant to re-enter the ID exactly as it was provided, checking for extra spaces, capital letters, or transcription errors. If you assigned IDs in a spreadsheet or email, double-check the original source.

Extension was uninstalled or disappeared

Chrome sometimes removes extensions during browser updates if the extension encounters repeated errors, or the participant may have removed it manually. Ask the participant to reinstall using the original link. If data loss is a concern, check your server (or ask the participant to download their data if you used rex-local-download) to see what was collected before the uninstall.