Press CTRL+K to open search

Google Sheets

  • Published on Aug 26, 2026
  • 1 minute(s) read
  • G
 Prev Next

Feedback Provider: Google Sheets

Google Sheets is the current provider implementation for Feedback Manager.

This provider is one implementation of the shared FeedbackProvider interface. Additional providers can be introduced independently under providers/ and in code under provider/ without changing upstream submission flow.

Provider Files

File Responsibility
config.ts Env-backed provider configuration and sheet label map
provider.ts Config validation, JWT auth client creation, append write logic

Environment Variables

Provider selection:

  • FEEDBACK_PROVIDER=google-sheets

Provider-owned env vars:

Env var Required Default Purpose
FEEDBACK_SHEET_ID Yes None Target spreadsheet ID
GOOGLE_CLIENT_EMAIL Yes None Service account email
GOOGLE_PRIVATE_KEY Yes None Service account private key
FEEDBACK_SHEET_RANGE No Feedback!A:Z Append range

Notes:

  • GOOGLE_PRIVATE_KEY must keep escaped newlines and is normalized at runtime via sanitizePrivateKey.
  • Missing required provider env vars throw config.missing during provider initialization.

GCP Setup

  1. Create or choose a Google Cloud project.
  2. Enable Google Sheets API.
  3. Create a service account and generate a JSON key.
  4. Set service account values in environment:
    • GOOGLE_CLIENT_EMAIL
    • GOOGLE_PRIVATE_KEY
  5. Share target spreadsheet with the service account email with editor access.
  6. Set FEEDBACK_SHEET_ID and optional FEEDBACK_SHEET_RANGE.

Sheet Mapping

The provider appends rows in the following order:

Column key Label
timestamp Timestamp
user_id User ID (Internal)
site_name Site
site_id Site ID
module Module
category Category
feedback Feedback
email Email
email_contact_allowed Email Contact Allowed
url URL

Runtime Behavior

Write path:

  1. Validate provider config
  2. Build JWT auth client using Sheets scope
  3. Map FeedbackContext to row values
  4. Append row with valueInputOption RAW
  5. Return success response or error response

Success response:

  • success: true
  • message: Feedback submitted successfully

Failure response:

  • success: false
  • error: <error message or fallback>

Common Failure Modes

Symptom Likely cause What to check
config.missing on startup Missing env vars Required provider env vars
Failed to write feedback Invalid key format Private key value and newline escaping
Permission denied from Sheets API Service account has no sheet access Spreadsheet sharing settings
Spreadsheet not found Wrong sheet ID or range FEEDBACK_SHEET_ID and FEEDBACK_SHEET_RANGE

Isolation Rule for Future Providers

Each provider must keep configuration isolated to its own implementation:

  • Define provider env vars in provider-local config
  • Validate only provider-specific requirements in provider initialization
  • Keep provider docs in one dedicated file under providers/