|Nicole Mirea ebbb44b0b7||2 months ago|
|functions||2 months ago|
|public||7 months ago|
|src||3 months ago|
|.gitignore||7 months ago|
|.tmuxinator.yml||7 months ago|
|Gemfile||7 months ago|
|Gemfile.lock||7 months ago|
|LICENSE||7 months ago|
|README.md||2 months ago|
|babel.config.js||7 months ago|
|database.rules.json||1 year ago|
|emulate.sh||7 months ago|
|firebase.json||7 months ago|
|package-lock.json||3 months ago|
|package.json||7 months ago|
|storage.rules||7 months ago|
|vue.config.js||7 months ago|
This directory contains code for running the speech experiments (and scheduling participants) on a Firebase instance. The speech experiments are written using the Vue.js framework on the front end, and Firebase on the backend.
Here are steps for how to get your study online, under a Firebase project that you have control over.
src/fb_init.js.sample. Remove '.sample' from the end of this file.
firebase initin this directory. Add the realtime database, hosting, storage, pubsub, and emulators as options. Link it to your just-created project. You'll want to set the hosting directory to
distinstead of the default
public, and select the "single-page site" option.
npm installinside this directory to update packages as needed.
Before spinning up your dev server or pushing to Firebase, you'll also need to set your configuration variables in
functions/.env. A sample configuration file
functions/.env.sample is provided.
functions/.env should contain:
For scheduling participants and sending out reminder emails, your Firebase project must have access to the Google Calendar and Gmail APIs. I recommend creating a separate Google account for this purpose (e.g.
firstname.lastname@example.org). This does not need to be the Google account that created the Firebase project, but if you created the Firebase app using your GSuite account, this account should also be a GSuite account within the same organization.
GOOGLE_USERNAMEis the email address for the study's Google account
GOOGLE_PASSWORDis the password for the study's Google account
Technically, it's not the project that has access to the APIs—it's a consent screen app associated with the project, which must be registered with Google. Here are steps for setting this up:
Note: you may need to wait a few minutes for the Client ID and Client Secret to propagate before continuing.
If your app is external, and in "testing mode", you will need to do go through these steps at least once a week while your study is online (preferably, more often).
It is sometimes preferable to use separate URLs for your screening survey and your experimental sessions / consent form. You can set both of these here. They will be used in emails to participants, and they should both redirect to the Firebase project (see this tutorial for how to redirect custom domain name to a Firebase project). If you're not sure what to put here, set both to the Google-assigned URL.
The project uses two Google calendars to manage booking equipment pick-up/drop-off appointments. Both calendars should be owned by the study's Google account, though you can provide other accounts access to these calendars if you choose to do so. The Calendar ID to paste into the config file can be found in Google Calendar Settings, under "Integrate calendar" for each calendar.
The calendars serve different roles in the booking process:
EXP_AVAILABILITY_CALENDAR: each event on this calendar will be split into timeslots for booking participants. Availability events should occur on Mondays (for pick-up appointments) and Fridays (for drop-off appointments). These events will be split into timeslots with length equal to
EXP_BOOKINGS_CALENDAR: events on this calendar are created by the Firebase app automatically, when participants book appointment slots. Each event represents an appointment, and the title contains information about the appointment (the participant's numeric ID, their email address, and the type of appointment [pick-up/drop-off]).
This variable sets the length of each appointment timeslot, in minutes. If you have an upper bound n on how many participants can be run in a given week—for example, due to limited equipment or limited funds—be careful not to open availability events that are longer than
EXP_APPT_MINS * n.
In order for participants to find the experimenter at appointments, it is important to give them instructions on where to go.
EXP_LOCATION_NAME: the name of the location where the experimenter will meet participants for equipment pick-up/drop-offs. This phrase will be used when booking appointments and in emails to participants, in place of the blank in these sentences:
EXP_LOCATION_URL: a link to a map of the location. A Google maps link works well for this purpose.
EXP_PARKING_INSTRUCTIONS: A paragraph that will appear immediately after the location URL in reminder and confirmation emails. You may choose to include information about parking locations and reimbursement for transportation expenses here.
Daily reminder emails (the COVID survey, a reminder to start the study) will be sent according to these parameters:
EXP_DAILY_EMAIL_TIME: the time of day to send the reminder email, in hours (0-24)
EXP_TIMEZONE: the timezone that this time should be calculated with respect to
Your experimenter dashboard (which will be available at
your-url-here.com/experimenter) will be password protected with the password you choose here.
The dev server requires both a local emulation of Firebase and a build of the Vue frontend.
To start a local emulation of Firebase:
To auto-compile the dev build of the Vue frontend (this may need to be run twice):
npm run watch
To do both at the same time with a single command, first install tmuxinator, then run:
npm run serve-firebase
This will create two tmux panes—one with your Firebase logs, and the other with the status of your Vue.js build.
Note that the emulator database is not persistent from session to session, so if you plan to use this mode to run a study offline, in a lab, you'll need to save the database to a separate JSON file between sessions! This method is not recommended, because of the high potential for data loss, but if you are dealing with especially sensitive information, it may be preferable.
To actually get your study online, first stop your Vue auto-builder (Ctrl+C in the Vue pane/window from the previous step) and run:
npm run deploy-all
This will build a production version of your site's frontend and upload your changes to Firebase.
While the experiment is online, participants will interact with the study like this:
Experimenter availability can be set using Google calendar, by creating events on the
EXP_AVAILABILITY_CALENDAR described above. Each event will be split into 15-minute appointment timeslots, and an equal number of timeslots should be available on Mondays and Fridays.
All scheduled appointments will appear on the
EXP_BOOKINGS_CALENDAR as soon as they are booked, as well as on the experimenter dashboard, located at
your-study-url.com/experimenter. The experimenter dashboard displays the participants' status in the "flow", their accrued earnings for completing sessions, and the results of their COVID screenings.
On the morning of each appointment, participants will receive an invitation to complete a COVID-19 screening form via email. The result of this will appear on the experimenter dashboard. If a participant fails the screening, the appointment will automatically be cancelled, and the experimenter email account will receive an email with the results of the participants' responses to the screening survey. Participants will be reminded to respond again if they have not responded an hour before their appointment.
At pick-up appointments, the experimenter has the opportunity to confirm pick-up and send the link to the first day's session, or to mark the participant as a no-show.
At drop-off appointments, the experimenter can confirm that equipment has been dropped off. This can help keep track of which participants have yet to return their equipment for following up.
When new spots open up, experimenters can email participants who tried to sign up for the study while the study was full using the "bulk operations" tab.
These experiments and the experimenter dashboard should work in the latest version of all browsers except Internet Explorer (which doesn't let you record audio without flash) or mobile phone browsers, because most (all?) smartphone operating systems don't let browsers record audio, for privacy reasons.