vidscrip-forms

Vidscrip Forms

HIPAA-compliant healthcare intake and assessment forms for multiple practices.

This repo contains:

• Branded frontend forms (standalone HTML + JS)
• A unified Google Apps Script backend (unified-google-apps-script.js)
• Config-driven form definitions and event handlers (formConfigs/*.gs)

Architecture

High-level flow

1. A user opens a form and answers questions.
2. The frontend posts events or final payloads to the Google Apps Script web app endpoint.
3. Backend routes by formType and eventType.
4. Data is written to a branded Google Sheet tab.
5. Intercom events/tags are sent (when responseId exists).
6. Survey API receives completed/final payloads (when configured).

Backend model

• unified-google-apps-script.js: Router, shared helpers, Intercom, Survey API integration
• formConfigs/loadConfigs.gs: Config registry (getFormConfig)
• formConfigs/eventHandlers.gs: Generic event pipeline
• formConfigs/*.gs: Per-form definitions (sheetName, headers, row builder, supported events)
• formConfigs/tests.gs: Generic and event-flow test harness

Form modes

• Event-driven forms: send formType + eventType where eventType is one of:
  • viewed
  • progressive
  • completed
  • final
  • clickedCta
• Generic one-shot forms: send one payload with formType only (must have isGeneric: true in config)

Current forms

• Arkansas Urology SHIM quiz
  • Path: arkansas-urology/shim-quiz/index.html
  • Multi-step assessment with progressive saves
• OABSS bladder/bowel assessment
  • Path: oabss/index.html
  • Event-driven funnel with score/severity and triage metadata
• Desert Oasis heart health study
  • Path: desert-oasis/heart-health-study/index.html
  • Address and consent capture flow

Repository layout

• unified-google-apps-script.js - primary backend entrypoint (doPost)
• formConfigs/ - modular form configs + event handlers + tests
• arkansas-urology/ - Arkansas Urology form assets
• oabss/ - OABSS form
• desert-oasis/ - Desert Oasis forms/assets
• assets/ - shared static assets
• GOOGLE_SHEETS_SETUP.md - Apps Script deployment setup
• SECURITY_SETUP.md - token/property security practices
• GA4_TRACKING.md - analytics implementation notes

Setup

1) Google Apps Script

1. Create or open your Apps Script project bound to the destination spreadsheet.
2. Copy in unified-google-apps-script.js and all files from formConfigs/.
3. Deploy as a Web App (Execute as: Me, Who has access: Anyone or your required access policy).
4. Use the Web App URL as your frontend submit endpoint.

2) Script Properties (required)

Add in Apps Script Project Settings -> Script Properties:

• INTERCOM_API_TOKEN

Optional (for Survey API writes):

• SURVEY_API_KEY
• VIDSCRIP_BASE_URL

3) Frontend endpoint wiring

Set each form’s GOOGLE_APPS_SCRIPT_URL (or fetch target URL) to your deployed web app endpoint.

4) Local development

Run a static server from repo root:

python3 -m http.server 8080

Open forms:

• http://localhost:8080/arkansas-urology/shim-quiz/
• http://localhost:8080/oabss/
• http://localhost:8080/desert-oasis/heart-health-study/

In Codespaces, use the forwarded URL instead of localhost.

Testing

Apps Script tests

Use functions in formConfigs/tests.gs:

• testGenericForm('oabss')
• testAllGenericForms()
• testEventFlow('arkansas-urology-shim')
• testAllEventFlows()
• testOnNewRowAdded('Sheet Name')

Manual verification checklist

• Sheet tab is created (or updated) for the target form
• Existing rows are updated by responseId where expected
• Intercom events/tags fire for tracked contacts
• Survey API calls succeed when credentials are configured

Security notes

• Never commit API tokens or secrets.
• Keep secrets only in Apps Script Script Properties.
• Rotate exposed tokens immediately.

See SECURITY_SETUP.md for details.

Related docs

• GOOGLE_SHEETS_SETUP.md
• SECURITY_SETUP.md
• GA4_TRACKING.md
• GA4_CUSTOM_REPORTS.md
• CUSTOMER_DATA_SUMMARY.md
• PROGRESSIVE_SUBMISSION.md

Contributing

When adding a new form:

1. Add a config object in formConfigs/<newForm>.gs.
2. Register it in formConfigs/loadConfigs.gs.
3. Add tests in formConfigs/tests.gs.
4. Ensure frontend payload shape matches backend expectations.
5. Update this README and any form-specific setup docs.