@agoodway/goodleads-web

Browser SDK for GoodLeads lead capture widgets. Provides the client-side runtime for quiz funnels, video calls, live chat, session recording, consent tracking, and ad platform attribution — all as vanilla TypeScript with zero framework dependencies.

Installation

npm install @agoodway/goodleads-web
# or
bun add @agoodway/goodleads-web

Entry Points

| Import | Description | |--------|-------------| | @agoodway/goodleads-web | Main SDK (quiz API, video, chat, tracking, consent) | | @agoodway/goodleads-web/recording | Session recording module (rrweb wrapper) |

Usage

Quiz Funnel API Integration

Connect a quiz engine to the GoodLeads Lead Collection API:

import { initQuizFunnel } from "@agoodway/goodleads-web";

initQuizFunnel({
  container: document.getElementById("quiz")!,
  accountSlug: "acme-roofing",
  apiBaseUrl: "https://api.goodleads.com",
  // Optional: pre-fetched questionnaire (skips network fetch)
  questionnaire: questionnaireData,
  // Optional: campaign targeting
  campaignSlug: "spring-2025",
  // Optional: session recording
  recordingSessionId: "rec_abc123",
});

Ad Platform Attribution

Automatically captures UTM parameters and ad platform click IDs from the URL:

import { collectTrackingMetadata, collectPlatformCookies } from "@agoodway/goodleads-web";

// Collects from URL params: utm_*, gclid, fbclid, ttclid, msclkid, etc.
const metadata = collectTrackingMetadata();
// { utm_source: "google", gclid: "abc123", ... }

// Collects platform cookies (_fbc, _fbp, etc.)
const cookies = collectPlatformCookies();

Supported platforms:

• Google Ads (gclid, gbraid, wbraid, ValueTrack params)
• Meta/Facebook (fbclid, campaign_id, adset_id, ad_id, placement)
• TikTok (ttclid)
• Microsoft Ads (msclkid)
• UTM parameters (source, medium, campaign, content, term)

Consent Proof

Build cryptographic consent proof for TCPA compliance:

import { buildConsentProof } from "@agoodway/goodleads-web";
import type { ConsentProofContext } from "@agoodway/goodleads-web";

const proof = buildConsentProof({
  consentText: "I agree to be contacted...",
  consentVersion: "v2.1",
  questionId: "tcpa_consent",
  ipAddress: "192.168.1.1",
  userAgent: navigator.userAgent,
  pageUrl: window.location.href,
});

Session Recording

Initialize session recording with rrweb:

import { initSessionRecording } from "@agoodway/goodleads-web/recording";

const recording = initSessionRecording({
  sessionId: "rec_abc123",
  eventsUrl: "https://api.goodaudit.com/api/v1/session-recordings/rec_abc123/events",
  sessionToken: "token-from-start-flow",
});

// Later: stop recording
recording.stop();

Video Calls

The SDK manages WebRTC video call state including consent, ringing, active call, and ended states:

import { LeadVideoManager } from "@agoodway/goodleads-web";

const video = new LeadVideoManager({
  container: document.getElementById("video-widget")!,
  socket: leadSocket,
  buyer: { name: "John's Roofing", phone: "555-0123" },
});

video.start(); // Shows consent modal → rings buyer → connects call

Live Chat

Real-time chat widget connected via Phoenix WebSocket:

import { LeadChatManager } from "@agoodway/goodleads-web";

const chat = new LeadChatManager({
  container: document.getElementById("chat-widget")!,
  socket: leadSocket,
  buyer: { name: "John's Roofing" },
});

Phoenix WebSocket Connection

Manages the real-time connection to the GoodLeads backend:

import { LeadSocket } from "@agoodway/goodleads-web";

const socket = new LeadSocket({
  url: "wss://api.goodleads.com/socket",
  leadId: "lead-uuid",
  leadToken: "bearer-token",
});

socket.connect();
socket.onPresence((payload) => {
  console.log("Buyer presence:", payload);
});

Dependencies

• @agoodway/goodleads-quiz-core — Quiz engine and question types
• phoenix — Phoenix WebSocket client for real-time features
• rrweb — Session recording (only in the /recording entry point)

Browser Support

Works in all modern browsers (ES2022+). No polyfills required.

License

MIT