Integrate with BeSample

This page describes how to configure a new Batch of slots for participants that will be recruited through the BeSample recruitment service. Meadows integrates with BeSample to enable participant recruitment for behavioral research studies. Start here for a more general introduction on recruitment.

Quick Start

1. Open your experiment version and go to the Participants tab
2. Click Create a new Batch.. and select the "BeSample" template from the dropdown
3. Paste the redirect URL from your BeSample study settings in the Exit URL field
4. Enter your BeSample Researcher Key under template settings
5. Under exit page, tick display exit link and automatically forward to exit link
6. Set the number of slots and click Create
7. Copy the Entry URL and paste it into BeSample as your study link

New to Meadows? See the Getting Started guide for a complete walkthrough.

How completion is reported

BeSample adds a few identifiers to your study link when it sends a participant to Meadows. When the participant finishes, Meadows sends them back to BeSample with two of these:

• battempt, which tells BeSample which attempt was completed, and
• completion_code, which proves that the participant reached the end of your experiment.

The completion code is different for every participant. Meadows calculates it from the one-time number BeSample sent (bnum) and your BeSample Researcher Key. That is why the batch needs your key.

Batch configuration

Entry URL

After you have configured and confirmed your batch, you'll enter this URL into BeSample as your study link. Unlike for some other platforms, the Entry URL for BeSample does not show the entry variables. BeSample adds these to the link itself when it sends a participant to Meadows. If the link already contained them, they would appear twice, and Meadows could not generate a completion code for the participant.

Entry variables

These are the so-called query parameters that BeSample adds to your study link. Meadows stores them with your participant's data.

bpid

The participant's BeSample ID. This is the same across all your BeSample studies, so it can help you link participants' identities across studies.

battempt

Required - Identifies this attempt by the participant. Meadows forwards it to BeSample when the participant finishes. Do not remove it.

bnum

Required - A one-time number that Meadows uses to calculate the completion code. Do not remove it.

Depending on how your BeSample study is set up, BeSample may also add tc (country), tg (gender) and ta (age). If your study uses these, add them as entry variables too. Meadows only lets participants in if their link carries exactly the entry variables configured on the batch; otherwise they will see "There is an issue with your link".

Exit URL

Here you should paste the redirect URL from your BeSample study settings, for example https://step.besample.app/study/redirect. Meadows adds battempt and completion_code to it for each participant, so you don't need to configure any exit variables.

Template settings

researcher key

Required - Your BeSample Researcher Key (sometimes called your Besample ID). You can find it in your BeSample account. Meadows uses it to calculate completion codes; it is never shown to participants.

Exit page

These are features of the final page on Meadows that the participant will see when they finish your experiment:

display exit link

This will show a large green button that links back to BeSample.

display completion code

This displays the participant's own completion code. If the redirect back to BeSample fails, the participant can enter this code on BeSample instead.

display meadows alias

This will display the Meadows nickname (of the form adjective-animal) on the final page, which may help in your troubleshooting communication with the participant.

automatically forward to exit link

If this is selected, after 4 seconds on the "thank you" page, the participant's browser will take them back to BeSample.

Testing your configuration

To try your batch without going through BeSample, add the entry variables to the Entry URL yourself, for example:

https://meadows-research.com/experiments/my-experiment/v/1/take-part/?bpid=test&battempt=test&bnum=1

If you have added more entry variables to your batch, such as tc, add these too. When you finish, the exit link should end in completion_code= followed by your Researcher Key (as bnum is 1). If you ticked display completion code, the final page shows the same code.

Before launching your study, also take part once yourself through BeSample, if your BeSample study allows a test run. Then check the metadata table of your Meadows batch: your test participant should have real values for bpid, battempt and bnum.

Troubleshooting

Participants see "There is an issue with your link"

The variables in the link don't match the entry variables of your batch. Compare them with the variables in the address bar when the experiment opened. Your BeSample study may send tc, tg or ta, which then need to be added to the batch. Opening the Entry URL directly, without any variables, also shows this message; see Testing your configuration.

Participants stay on the final page instead of returning to BeSample

display exit link or automatically forward to exit link was not ticked under exit page. These can't be changed after the batch is created, so create a new batch.

Participants return to BeSample but are not paid automatically

Run the test under Testing your configuration and look at the exit link. If completion_code has no value, bnum is missing from the entry variables of your batch. If the code doesn't equal your Researcher Key, the key was entered incorrectly; create a new batch with the correct key.

The completion code on the final page is empty

bnum is missing from the entry variables of your batch.

If none of these help, contact us.