feat: add SONA recruitment support with unpaid study config option

gureckis · claude · gureckis · commit 73275fce089b · 2026-02-26T19:30:24.000-05:00
Add SONA (credit) and SONA (paid) as recruitment services with auto-credit
granting via redirect URLs. Add `unpaidStudy` config option to switch
informed consent text between payment and course credit language. Include
dev tools toggle for unpaidStudy and document SONA setup in recruitment,
configuration, and lab config docs.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/coding/configuration.md b/docs/coding/configuration.md
@@ -71,6 +71,7 @@ api.setRuntimeConfig('windowsizerRequest', { width: 800, height: 600 })
 api.setRuntimeConfig('windowsizerAggressive', true)
 
 api.setRuntimeConfig('anonymousMode', false)
+api.setRuntimeConfig('unpaidStudy', true) // for SONA credit or other unpaid studies
 api.setRuntimeConfig('labURL', 'https://gureckislab.org')
 api.setRuntimeConfig('brandLogoFn', 'universitylogo.png')
 
@@ -228,6 +229,11 @@ means they are made available to the web application/experiment.
   deployed in anonymous mode. This mode is useful for submitting a link to the
   study with a paper submission. In this mode, all <SmileText/>-default
   references to the organization conducting the study are removed.
+- `unpaidStudy` is a runtime-only config option (set via
+  `api.setRuntimeConfig('unpaidStudy', true)` in `design.js`) that switches the
+  default informed consent text from payment language to course credit language.
+  Defaults to `false`. Useful for SONA credit studies or any unpaid recruitment
+  service. Can also be toggled in the developer tools sidebar.
 - `VITE_LAB_URL` is the URL of the lab website. This can be used to link to the
   lab website or university homepage so participants can learn more about the
   organization conducting the study.
@@ -267,12 +273,33 @@ VITE_FIREBASE_APPID              = appid
 
 # enter google analytics id
 VITE_GOOGLE_ANALYTICS            = xxxx
+
+# sona (credit)
+VITE_SONA_URL                    = ''
+VITE_SONA_EXPERIMENT_ID          = ''
+VITE_SONA_CREDIT_TOKEN           = ''
+
+# sona (paid)
+VITE_SONA_PAID_URL               = ''
+VITE_SONA_PAID_EXPERIMENT_ID     = ''
+VITE_SONA_PAID_CREDIT_TOKEN      = ''
 ```
 
 - There several `VITE_FIREBASE_` options for configuring Google's Firestore
   backend (see [data storage](/coding/datastorage) for more info).
 - `VITE_GOOGLE_ANALYTICS` is the Google Analytics ID for your experiment
   (optional)
+- `VITE_SONA_URL` is the base URL of your institution's SONA instance for
+  credit-based studies (see [SONA recruitment](/recruit/recruitment#sona) for
+  details)
+- `VITE_SONA_EXPERIMENT_ID` is the SONA experiment ID for credit-based studies
+- `VITE_SONA_CREDIT_TOKEN` is the SONA credit token for automatic credit
+  granting
+- `VITE_SONA_PAID_URL` is the base URL of your institution's SONA instance for
+  paid studies
+- `VITE_SONA_PAID_EXPERIMENT_ID` is the SONA experiment ID for paid studies
+- `VITE_SONA_PAID_CREDIT_TOKEN` is the SONA payment token for automatic payment
+  granting
 
 #### Code Version Options (`.env.github.local`)
 
diff --git a/docs/labconfig.md b/docs/labconfig.md
@@ -365,6 +365,15 @@ VITE_FIREBASE_APPID              = xxxx
 # enter google analytics id
 VITE_GOOGLE_ANALYTICS            = xxxx
 
+# sona (credit)
+VITE_SONA_URL                    = ''
+VITE_SONA_EXPERIMENT_ID          = ''
+VITE_SONA_CREDIT_TOKEN           = ''
+
+# sona (paid)
+VITE_SONA_PAID_URL               = ''
+VITE_SONA_PAID_EXPERIMENT_ID     = ''
+VITE_SONA_PAID_CREDIT_TOKEN      = ''
 ```
 
 You will want to replace the values for the entries that contain the word
diff --git a/docs/recruit/recruitment.md b/docs/recruit/recruitment.md
@@ -233,6 +233,111 @@ htt?ps://exps.gureckislab.org/e/note-useless-uncle#/welcome/mturk/assignmentId=1
 which loads slightly different content. You can customize aspects of this via
 the `recruitment/MTurkRecruitPage.vue` component.
 
+## SONA
+
+[SONA Systems](https://www.sona-systems.com) is a participant management
+platform commonly used at universities for recruiting research participants from
+subject pools. Participants typically receive course credit for their
+participation, though SONA also supports paid studies.
+
+<SmileText /> supports both **SONA (credit)** and **SONA (paid)** as recruitment
+services.
+
+### Configuration
+
+SONA requires several environment variables to be set in your `env/.env.local`
+file. You will need to obtain these values from your SONA administrator or from
+your SONA experiment settings page.
+
+```
+# sona (credit)
+VITE_SONA_URL                    = 'https://yourschool.sona-systems.com'
+VITE_SONA_EXPERIMENT_ID          = 'your_experiment_id'
+VITE_SONA_CREDIT_TOKEN           = 'your_credit_token'
+
+# sona (paid)
+VITE_SONA_PAID_URL               = 'https://yourschool.sona-systems.com'
+VITE_SONA_PAID_EXPERIMENT_ID     = 'your_experiment_id'
+VITE_SONA_PAID_CREDIT_TOKEN      = 'your_credit_token'
+```
+
+You only need to fill in the set that matches your study type (credit or paid).
+After updating these values, run `npm run upload_config` to sync them to GitHub
+for deployment.
+
+- `VITE_SONA_URL` / `VITE_SONA_PAID_URL` is the base URL of your institution's
+  SONA instance (e.g., `https://yourschool.sona-systems.com`)
+- `VITE_SONA_EXPERIMENT_ID` / `VITE_SONA_PAID_EXPERIMENT_ID` is the experiment
+  ID assigned by SONA when you create the study
+- `VITE_SONA_CREDIT_TOKEN` / `VITE_SONA_PAID_CREDIT_TOKEN` is the
+  authentication token SONA provides for automatic credit/payment granting via
+  web studies
+
+### Setting up your study URL in SONA
+
+When creating a web study in SONA, you need to provide the study URL. SONA will
+append a `survey_code` parameter that identifies each participant. Your study URL
+should follow this pattern:
+
+For credit-based studies:
+```
+https://exps.gureckislab.org/e/note-useless-uncle/#/welcome/sona/?survey_code=%SURVEY_CODE%
+```
+
+For paid studies:
+```
+https://exps.gureckislab.org/e/note-useless-uncle/#/welcome/sona_paid/?survey_code=%SURVEY_CODE%
+```
+
+Replace `note-useless-uncle` with your project's code name. The `%SURVEY_CODE%`
+placeholder is automatically replaced by SONA with the participant's unique
+survey code.
+
+### Informed consent for unpaid studies
+
+SONA credit-based studies are unpaid, so the default informed consent language
+about monetary payment is inappropriate. To show course-credit-appropriate
+consent language, set the `unpaidStudy` runtime config option in your
+`design.js`:
+
+```js
+api.setRuntimeConfig('unpaidStudy', true)
+```
+
+This changes the compensation bullet in the default `InformedConsentText.vue`
+from payment language to course credit language. See the
+[configuration docs](/coding/configuration) for more on runtime config. You can
+also toggle this setting in the developer tools sidebar using the "Unpaid"
+switch.
+
+::: tip
+The `unpaidStudy` option is not specific to SONA — it can be used for any
+recruitment service where participants are not paid (e.g., citizen science
+studies).
+:::
+
+### How completion works
+
+When a participant finishes the study, the thanks page automatically provides a
+button that redirects them back to SONA. This redirect URL includes the
+participant's survey code and your credit/payment token, so SONA can
+automatically grant credit or payment without any manual intervention.
+
+For credit studies, the redirect goes to:
+```
+{SONA_URL}/webstudy_credit.aspx?experiment_id={ID}&credit_token={TOKEN}&survey_code={CODE}
+```
+
+This means participants are credited immediately upon clicking the button — no
+completion codes to copy and paste.
+
+### Testing in developer mode
+
+In the developer tools sidebar, you can select "sona" or "sona_paid" from the
+**Service** dropdown to simulate SONA recruitment during development. This lets
+you test the full flow including the thanks/credit page without needing an
+actual SONA participant.
+
 ## Crowd-sourcing
 
 In the future the lab might make a citizen science recruitment portal. To
diff --git a/env/.env b/env/.env
@@ -32,4 +32,4 @@ VITE_MAX_WRITES                  = 1000
 VITE_MIN_WRITE_INTERVAL          = 2000
 
 # stepper limit
-VITE_MAX_STEPS                   = 5000
+VITE_MAX_STEPS                   = 5000
diff --git a/src/builtins/thanks/ThanksView.vue b/src/builtins/thanks/ThanksView.vue
@@ -231,6 +231,76 @@ onMounted(() => {
         </TitleTwoCol>
       </div>
 
+      <!-- SONA (credit) recruitment service completion -->
+      <div v-if="api.getRecruitmentService() == 'sona'">
+        <TitleTwoCol leftFirst leftWidth="w-1/3" :responsiveUI="api.config.responsiveUI">
+          <template #title>
+            <h1 class="text-3xl font-bold mb-4">
+              <i-fa6-solid-square-check class="inline mr-2" />&nbsp;Thanks, let's record your credit!
+            </h1>
+            <p class="text-lg mb-8">
+              Please click the button below to return to SONA and receive credit for completing this study. We really
+              appreciate your time.
+            </p>
+          </template>
+          <template #left>
+            <div class="text-left text-muted-foreground">
+              <h3 class="text-lg font-bold mb-2">Credit Process</h3>
+              <p class="text-sm text-muted-foreground">
+                Click the button to return to SONA and automatically receive credit for this study.
+              </p>
+            </div>
+          </template>
+          <template #right>
+            <div class="border border-border text-left bg-muted p-6 rounded-lg">
+              <Button
+                variant="default"
+                as="a"
+                :href="`${appconfig.sona.url}/webstudy_credit.aspx?experiment_id=${appconfig.sona.experimentId}&credit_token=${appconfig.sona.creditToken}&survey_code=${api.private.recruitmentInfo.survey_code}`"
+              >
+                Return to SONA for credit
+                <i-fa6-solid-arrow-right />
+              </Button>
+            </div>
+          </template>
+        </TitleTwoCol>
+      </div>
+
+      <!-- SONA (paid) recruitment service completion -->
+      <div v-if="api.getRecruitmentService() == 'sona_paid'">
+        <TitleTwoCol leftFirst leftWidth="w-1/3" :responsiveUI="api.config.responsiveUI">
+          <template #title>
+            <h1 class="text-3xl font-bold mb-4">
+              <i-fa6-solid-square-check class="inline mr-2" />&nbsp;Thanks, let's begin the payment process!
+            </h1>
+            <p class="text-lg mb-8">
+              Please click the button below to return to SONA and receive payment for completing this study. We really
+              appreciate your time.
+            </p>
+          </template>
+          <template #left>
+            <div class="text-left text-muted-foreground">
+              <h3 class="text-lg font-bold mb-2">Payment Process</h3>
+              <p class="text-sm text-muted-foreground">
+                Click the button to return to SONA and automatically receive payment for this study.
+              </p>
+            </div>
+          </template>
+          <template #right>
+            <div class="border border-border text-left bg-muted p-6 rounded-lg">
+              <Button
+                variant="default"
+                as="a"
+                :href="`${appconfig.sonaPaid.url}/webstudy_credit.aspx?experiment_id=${appconfig.sonaPaid.experimentId}&credit_token=${appconfig.sonaPaid.creditToken}&survey_code=${api.private.recruitmentInfo.survey_code}`"
+              >
+                Return to SONA for payment
+                <i-fa6-solid-arrow-right />
+              </Button>
+            </div>
+          </template>
+        </TitleTwoCol>
+      </div>
+
       <!-- Web recruitment service completion -->
       <div v-if="api.getRecruitmentService() == 'web'">
         <TitleTwoCol leftFirst leftWidth="w-1/3" :responsiveUI="api.config.responsiveUI">
diff --git a/src/core/config.js b/src/core/config.js
@@ -92,6 +92,17 @@ export default {
   windowsizerRequest: parseWidthHeight(import.meta.env.VITE_WINDOWSIZER_REQUEST),
   windowsizerAggressive: import.meta.env.VITE_WINDOWSIZER_AGGRESSIVE === 'true',
   anonymousMode: import.meta.env.VITE_ANONYMOUS_MODE === 'true',
+  unpaidStudy: false,
+  sona: {
+    url: import.meta.env.VITE_SONA_URL,
+    experimentId: import.meta.env.VITE_SONA_EXPERIMENT_ID,
+    creditToken: import.meta.env.VITE_SONA_CREDIT_TOKEN,
+  },
+  sonaPaid: {
+    url: import.meta.env.VITE_SONA_PAID_URL,
+    experimentId: import.meta.env.VITE_SONA_PAID_EXPERIMENT_ID,
+    creditToken: import.meta.env.VITE_SONA_PAID_CREDIT_TOKEN,
+  },
   firebaseConfig: {
     apiKey: import.meta.env.VITE_FIREBASE_APIKEY,
     authDomain: import.meta.env.VITE_FIREBASE_AUTHDOMAIN,
diff --git a/src/core/stores/smilestore.js b/src/core/stores/smilestore.js
@@ -202,6 +202,8 @@ const initBrowserEphemeral = {
       '#/mturk/?assignmentId=123RVWYBAZW00EXAMPLE456RVWYBAZW00EXAMPLE&hitId=123RVWYBAZW00EXAMPLE&turkSubmitTo=https://www.mturk.com/&workerId=AZ3456EXAMPLE',
     citizensci:
       '#/welcome/citizensci/?CITIZEN_ID=XXXXX&CITIZEN_STUDY_ID=123RVWYBAZW00EXAMPLE&CITIZEN_SESSION_ID=AZ3456EXAMPLE',
+    sona: '#/welcome/sona/?survey_code=SONA_TEST_12345',
+    sona_paid: '#/welcome/sona_paid/?survey_code=SONA_PAID_TEST_67890',
     web: '#/welcome',
   },
 }
diff --git a/src/core/utils/utils.js b/src/core/utils/utils.js
@@ -64,6 +64,16 @@ export function processQuery(query, service) {
         assignment_id: urlParams.assignmentId,
       })
     }
+  } else if (service === 'sona' && urlParams.survey_code) {
+    log.log('Sona mode')
+    smilestore.setRecruitmentService(service, {
+      survey_code: urlParams.survey_code,
+    })
+  } else if (service === 'sona_paid' && urlParams.survey_code) {
+    log.log('Sona paid mode')
+    smilestore.setRecruitmentService(service, {
+      survey_code: urlParams.survey_code,
+    })
   } else if (
     service === 'citizensci' &&
     urlParams.CITIZEN_ID &&
diff --git a/src/dev/developer_mode/RecruitmentChooserView.vue b/src/dev/developer_mode/RecruitmentChooserView.vue
@@ -103,6 +103,43 @@ const api = useViewAPI()
         </CardContent>
       </Card>
 
+      <!-- SONA Platform Card -->
+      <Card class="flex flex-col">
+        <CardHeader>
+          <CardTitle>SONA</CardTitle>
+          <CardDescription
+            >SONA is a platform for running experiments from the university "for credit" pool of
+            students.</CardDescription
+          >
+        </CardHeader>
+        <CardContent class="flex justify-end flex-1 items-end">
+          <Button asChild variant="default" size="xs" class="is-orange" id="sona_tester">
+            <a :href="api.urls['sona']"
+              ><i-lucide-dices /> SONA User
+              <ArrowRight class="inline-block ml-1 w-4 h-4" />
+            </a>
+          </Button>
+        </CardContent>
+      </Card>
+
+      <!-- SONA Paid Platform Card -->
+      <Card class="flex flex-col">
+        <CardHeader>
+          <CardTitle>SONA Paid</CardTitle>
+          <CardDescription
+            >SONA Paid is a platform for running paid experiments from the university pool.</CardDescription
+          >
+        </CardHeader>
+        <CardContent class="flex justify-end flex-1 items-end">
+          <Button asChild variant="default" size="xs" class="is-teal" id="sona_paid_tester">
+            <a :href="api.urls['sona_paid']"
+              ><i-lucide-dices /> SONA Paid User
+              <ArrowRight class="inline-block ml-1 w-4 h-4" />
+            </a>
+          </Button>
+        </CardContent>
+      </Card>
+
       <!-- Citizen Science Platform Card -->
       <Card class="flex flex-col">
         <CardHeader>
@@ -112,7 +149,7 @@ const api = useViewAPI()
           >
         </CardHeader>
         <CardContent class="flex justify-end flex-1 items-end">
-          <Button asChild variant="default" size="xs" class="is-green" id="citizen_tester">
+          <Button asChild variant="default" size="xs" class="is-purple" id="citizen_tester">
             <a :href="api.urls['citizensci']"
               ><i-lucide-dices /> Citizen Sci User
               <ArrowRight class="inline-block ml-1 w-4 h-4" />
@@ -128,7 +165,7 @@ const api = useViewAPI()
           <CardDescription>Anonymous web user is not referred by any recruitment service.</CardDescription>
         </CardHeader>
         <CardContent class="flex justify-end flex-1 items-end">
-          <Button asChild variant="default" size="xs" class="is-purple" id="web_tester">
+          <Button asChild variant="default" size="xs" class="is-green" id="web_tester">
             <a :href="api.urls['web']"
               ><i-lucide-dices /> Anon Web User
               <ArrowRight class="inline-block ml-1 w-4 h-4" />
@@ -172,6 +209,16 @@ const api = useViewAPI()
   color: #393939;
 }
 
+.is-teal {
+  background-color: rgb(102, 223, 214);
+  color: #393939;
+}
+
+.is-orange {
+  background-color: rgb(255, 179, 102);
+  color: #393939;
+}
+
 .is-purple {
   background-color: #ebaeff;
   color: #393939;
diff --git a/src/dev/developer_mode/sidebar/ConfigurationVariablesPanel.vue b/src/dev/developer_mode/sidebar/ConfigurationVariablesPanel.vue
diff --git a/src/user/components/InformedConsentText.vue b/src/user/components/InformedConsentText.vue
diff --git a/src/user/design.js b/src/user/design.js

Original file line number	Diff line number	Diff line change
`@@ -202,6 +202,8 @@ const initBrowserEphemeral = {`
`202`	`202`	`'#/mturk/?assignmentId=123RVWYBAZW00EXAMPLE456RVWYBAZW00EXAMPLE&hitId=123RVWYBAZW00EXAMPLE&turkSubmitTo=https://www.mturk.com/&workerId=AZ3456EXAMPLE',`
`203`	`203`	`citizensci:`
`204`	`204`	`'#/welcome/citizensci/?CITIZEN_ID=XXXXX&CITIZEN_STUDY_ID=123RVWYBAZW00EXAMPLE&CITIZEN_SESSION_ID=AZ3456EXAMPLE',`
	`205`	`+ sona: '#/welcome/sona/?survey_code=SONA_TEST_12345',`
	`206`	`+ sona_paid: '#/welcome/sona_paid/?survey_code=SONA_PAID_TEST_67890',`
`205`	`207`	`web: '#/welcome',`
`206`	`208`	`},`
`207`	`209`	`}`