@agoodway/goodleads-astro
v0.1.0
Published
Astro integration for GoodLeads lead capture. Provides a drop-in `<QuizFunnel>` component and server-side route helpers for session recording — everything you need to add a lead capture quiz funnel to an Astro site.
Readme
@agoodway/goodleads-astro
Astro integration for GoodLeads lead capture. Provides a drop-in <QuizFunnel> component and server-side route helpers for session recording — everything you need to add a lead capture quiz funnel to an Astro site.
Installation
npm install @agoodway/goodleads-astro
# or
bun add @agoodway/goodleads-astroEntry Points
| Import | Description |
|--------|-------------|
| @agoodway/goodleads-astro | QuizFunnel Astro component |
| @agoodway/goodleads-astro/recording-routes | Server-side recording route builders |
Quick Start
1. Add the QuizFunnel Component
---
import QuizFunnel from "@agoodway/goodleads-astro";
---
<html>
<body>
<QuizFunnel
accountSlug="acme-roofing"
apiBaseUrl="https://api.goodleads.com"
/>
</body>
</html>That's it — the component includes all styles, scripts, and the quiz engine. It fetches the questionnaire from your GoodLeads account and renders the full multi-step funnel.
2. Component Props
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| accountSlug | string | Yes | Your GoodLeads account slug |
| apiBaseUrl | string | Yes | GoodLeads API base URL |
| questionnaireSlug | string | No | Specific questionnaire to load (defaults to account default) |
| questionnaire | object | No | Pre-fetched questionnaire data (skips network fetch) |
| campaignSlug | string | No | Campaign slug for attribution |
| clientIpAddress | string | No | Client IP for server-rendered pages |
| recordingSessionId | string | No | Enable session recording with this ID |
| dev | boolean | No | Enable dev mode (bypasses phone verification) |
3. Add Session Recording Routes (Optional)
If you want session recording, add two API routes:
src/pages/api/recordings/start.ts
import { createStartRecordingRoute } from "@agoodway/goodleads-astro/recording-routes";
export const prerender = false;
export const POST = createStartRecordingRoute({
goodAuditApiUrl: import.meta.env.GOODAUDIT_API_URL,
goodAuditApiKey: import.meta.env.GOODAUDIT_API_KEY,
goodleadsApiUrl: import.meta.env.GOODLEADS_API_URL,
recordingCookieSecret: import.meta.env.GOODLEADS_RECORDING_COOKIE_SECRET,
});src/pages/api/recordings/complete.ts
import { createCompleteRecordingRoute } from "@agoodway/goodleads-astro/recording-routes";
export const prerender = false;
export const POST = createCompleteRecordingRoute({
goodAuditApiUrl: import.meta.env.GOODAUDIT_API_URL,
goodAuditApiKey: import.meta.env.GOODAUDIT_API_KEY,
goodleadsApiUrl: import.meta.env.GOODLEADS_API_URL,
recordingCookieSecret: import.meta.env.GOODLEADS_RECORDING_COOKIE_SECRET,
});4. Dynamic Configuration
Route config can be a function that receives the Astro API context:
export const POST = createStartRecordingRoute((context) => ({
goodAuditApiUrl: context.locals.runtime.env.GOODAUDIT_API_URL,
goodAuditApiKey: context.locals.runtime.env.GOODAUDIT_API_KEY,
goodleadsApiUrl: context.locals.runtime.env.GOODLEADS_API_URL,
recordingCookieSecret: context.locals.runtime.env.RECORDING_COOKIE_SECRET,
}));This is useful for Cloudflare Workers, Vercel Edge, or other runtimes where env vars are accessed differently.
Environment Variables
| Variable | Description |
|----------|-------------|
| GOODAUDIT_API_URL | GoodAudit session recording API URL |
| GOODAUDIT_API_KEY | GoodAudit API key |
| GOODLEADS_API_URL | GoodLeads internal API URL (for lead session validation) |
| GOODLEADS_RECORDING_COOKIE_SECRET | Secret for signing completion cookies |
Recording Route Configuration
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| goodAuditApiUrl | string | Yes | GoodAudit API base URL |
| goodAuditApiKey | string | Yes | GoodAudit API key |
| goodleadsApiUrl | string | Yes | GoodLeads API base URL |
| recordingCookieSecret | string | Yes | HMAC secret for cookie signing |
| completionCookieName | string | No | Cookie name (default: gl_recording_complete) |
| completionRoutePath | string | No | Cookie path (default: /api/recordings/complete) |
| completionCookieTtlSeconds | number | No | Cookie TTL (default: 7200 / 2 hours) |
Styling
The component imports its own stylesheet wrapped in @layer goodleads. You can override styles using standard CSS specificity or by targeting the layer:
@layer goodleads {
.quiz-funnel {
--quiz-accent: #your-brand-color;
}
}See STYLING.md for the full list of class hooks, CSS variables, and override patterns.
How It Works
- The
<QuizFunnel>component renders a loading skeleton - On mount, it fetches the questionnaire from your GoodLeads account
- The quiz engine drives the user through conditional questions
- Answers are submitted to the Lead Collection API as the user progresses
- On completion, the lead is matched with a buyer and real-time features (video call, chat) activate
- If session recording is enabled, browser events are captured and uploaded to GoodAudit
Dependencies
@agoodway/goodleads-quiz-core— Quiz engine logic@agoodway/goodleads-server— Server-side recording flow handlers@agoodway/goodleads-web— Browser-side SDK (bundled into the component script)
Peer Dependencies
astro^5.x
License
MIT