feat: add SPARK recruitment service support for adolescent participants

SPARK is a Hartley Lab recruitment service that passes subject_ID,
participant_ID, age, and gender via URL params. Completion redirects to
spark.hartleylab.org. Includes dev mode card, thanks page redirect,
deploy Slack notification, and documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gureckis

.github/workflows/deploy.yml

@@ -263,5 +263,6 @@ jobs:
               "mturk_url": "https://${{ secrets.EXP_DEPLOY_HOST }}/e/${{ steps.dotenv_github.outputs.VITE_CODE_NAME }}/#/welcome/mturk/",
               "sona_url": "https://${{ secrets.EXP_DEPLOY_HOST }}/e/${{ steps.dotenv_github.outputs.VITE_CODE_NAME }}/#/welcome/sona/?survey_code=%SURVEY_CODE%",
               "sona_paid_url": "https://${{ secrets.EXP_DEPLOY_HOST }}/e/${{ steps.dotenv_github.outputs.VITE_CODE_NAME }}/#/welcome/sona_paid/?survey_code=%SURVEY_CODE%",
+              "spark_url": "https://${{ secrets.EXP_DEPLOY_HOST }}/e/${{ steps.dotenv_github.outputs.VITE_CODE_NAME }}/#/welcome/spark/?subject_ID=%SUBJECT_ID%&participant_ID=%PARTICIPANT_ID%&age=%AGE%&gender=%GENDER%",
               "citizen_url": "https://${{ secrets.EXP_DEPLOY_HOST }}/e/${{ steps.dotenv_github.outputs.VITE_CODE_NAME }}/#/welcome/citizen/"
             }

docs/coding/configuration.md

@@ -301,6 +301,10 @@ VITE_SONA_PAID_CREDIT_TOKEN      = ''
 - `VITE_SONA_PAID_CREDIT_TOKEN` is the SONA payment token for automatic payment
   granting
 
+Note: SPARK does not require any environment variables. The SPARK completion URL
+(`https://spark.hartleylab.org/completed`) is configured directly in
+`src/core/config.js` since it is not secret.
+
 #### Code Version Options (`.env.github.local`)
 
 The `.env.github.local` file contains information about the latest git commit

docs/labconfig.md

@@ -269,7 +269,7 @@ Next, select "Webhook" as the type of workflow you are creating.
 Click add variables and add the following variable names to your workflow
 `deploy_base`, `deploy_base_codename`, `github_username`,`github_hash`,
 `qr_code`, `prolific_url`, `cloudresearch_url`, `mturk_url`, `sona_url`,
-`sona_paid_url`, `citizen_url`. This
+`sona_paid_url`, `spark_url`, `citizen_url`. This
 screenshot shows only a subset being added:
 
 ![Slack config](/images/labconfig-slack3.png)
@@ -293,6 +293,7 @@ add the variables to the message):
 - MTurk URL: mturk_url
 - SONA (credit) URL: sona_url
 - SONA (paid) URL: sona_paid_url
+- SPARK URL: spark_url
 - Citizen URL: citizen_url
 
 QR Code: qr_code

docs/recruit/recruitment.md

@@ -338,6 +338,58 @@ In the developer tools sidebar, you can select "sona" or "sona_paid" from the
 you test the full flow including the thanks/credit page without needing an
 actual SONA participant.
 
+## SPARK
+
+[SPARK](https://spark.hartleylab.org) is a recruitment service from the Hartley
+Lab designed for adolescent participants of various ages. Unlike SONA, SPARK
+does not require environment variables or credit tokens — completion is handled
+by redirecting participants back to the SPARK platform.
+
+::: tip
+SPARK is available to Hartley Lab members and collaborators. Contact the
+Hartley Lab for access.
+:::
+
+### URL parameters
+
+SPARK passes the following URL parameters when directing a participant to your
+study:
+
+- `subject_ID` (required) — the SPARK subject identifier
+- `participant_ID` — the participant identifier
+- `age` — the participant's age
+- `gender` — the participant's gender
+
+These parameters are stored in `api.private.recruitmentInfo` and can be
+accessed anywhere in your experiment code. For example, you can use
+`api.private.recruitmentInfo.age` and `api.private.recruitmentInfo.gender` in
+`src/user/components/InformedConsentText.vue` to display age-appropriate consent
+forms (e.g., showing a parental consent form for participants under 18).
+
+The study URL format is:
+
+```
+https://your-deploy-host/e/your-code-name/#/welcome/spark/?subject_ID=XXXX&participant_ID=XXXX&age=XX&gender=XXXX
+```
+
+### How completion works
+
+When a participant finishes the study, the thanks page provides a button that
+redirects them to:
+
+```
+https://spark.hartleylab.org/completed/${subject_ID}
+```
+
+This marks the participant's session as complete in the SPARK system.
+
+### Testing in developer mode
+
+In the developer tools sidebar, you can select "spark" from the **Service**
+dropdown to simulate SPARK recruitment during development. The SPARK card in the
+recruitment chooser will launch with test parameters so you can verify the full
+flow including the thanks/completion redirect.
+
 ## Crowd-sourcing
 
 In the future the lab might make a citizen science recruitment portal. To

src/builtins/thanks/ThanksView.vue

@@ -301,6 +301,41 @@ onMounted(() => {
         </TitleTwoCol>
       </div>
 
+      <!-- SPARK recruitment service completion -->
+      <div v-if="api.getRecruitmentService() == 'spark'">
+        <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 for your contribution to science!
+            </h1>
+            <p class="text-lg mb-8">
+              Please click the button below to return to SPARK and mark your participation as complete. We really
+              appreciate your time.
+            </p>
+          </template>
+          <template #left>
+            <div class="text-left text-muted-foreground">
+              <h3 class="text-lg font-bold mb-2">Study Complete</h3>
+              <p class="text-sm text-muted-foreground">
+                Click the button to return to SPARK and confirm your completion of 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.spark.completionUrl}/${api.private.recruitmentInfo.subject_ID}`"
+              >
+                Return to SPARK
+                <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">

src/core/config.js

@@ -103,6 +103,9 @@ export default {
     experimentId: import.meta.env.VITE_SONA_PAID_EXPERIMENT_ID,
     creditToken: import.meta.env.VITE_SONA_PAID_CREDIT_TOKEN,
   },
+  spark: {
+    completionUrl: 'https://spark.hartleylab.org/completed',
+  },
   firebaseConfig: {
     apiKey: import.meta.env.VITE_FIREBASE_APIKEY,
     authDomain: import.meta.env.VITE_FIREBASE_AUTHDOMAIN,

src/core/stores/smilestore.js

@@ -204,6 +204,8 @@ const initBrowserEphemeral = {
       '#/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',
+    spark:
+      '#/welcome/spark/?subject_ID=SPARK_TEST_001&participant_ID=SPARK_PID_001&age=14&gender=female',
     web: '#/welcome',
   },
 }

src/core/utils/utils.js

@@ -74,6 +74,14 @@ export function processQuery(query, service) {
     smilestore.setRecruitmentService(service, {
       survey_code: urlParams.survey_code,
     })
+  } else if (service === 'spark' && urlParams.subject_ID) {
+    log.log('Spark mode')
+    smilestore.setRecruitmentService(service, {
+      subject_ID: urlParams.subject_ID,
+      participant_ID: urlParams.participant_ID || '',
+      age: urlParams.age || '',
+      gender: urlParams.gender || '',
+    })
   } else if (
     service === 'citizensci' &&
     urlParams.CITIZEN_ID &&

src/dev/developer_mode/RecruitmentChooserView.vue

@@ -140,6 +140,25 @@ const api = useViewAPI()
         </CardContent>
       </Card>
 
+      <!-- SPARK Platform Card -->
+      <Card class="flex flex-col">
+        <CardHeader>
+          <CardTitle>SPARK</CardTitle>
+          <CardDescription
+            >SPARK is a recruitment service from the Hartley Lab for adolescent participants of various
+            ages.</CardDescription
+          >
+        </CardHeader>
+        <CardContent class="flex justify-end flex-1 items-end">
+          <Button asChild variant="default" size="xs" class="is-red" id="spark_tester">
+            <a :href="api.urls['spark']"
+              ><i-lucide-dices /> SPARK 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>