@zoyth/simple-site-framework 1.0.0

package/docs/features/analytics/ab-testing.md

@@ -0,0 +1,171 @@
+# A/B Testing
+
+Run experiments to optimize conversions and user engagement.
+
+## Overview
+
+The framework provides a client-side A/B testing system that:
+
+- Assigns users to variants deterministically
+- Persists assignments across sessions
+- Integrates with analytics tracking
+- Supports weighted variant distribution
+
+## Quick Start
+
+```typescript
+'use client';
+import { getABTestVariant, trackABTestEvent } from '@zoyth/simple-site-framework/client';
+
+const variant = getABTestVariant({
+  testId: 'hero-cta',
+  variants: { A: { weight: 50 }, B: { weight: 50 } },
+});
+
+const ctaText = variant === 'A' ? 'Start Free Trial' : 'Get Started Free';
+
+<button onClick={() => trackABTestEvent('hero-cta', variant, 'click')}>
+  {ctaText}
+</button>
+```
+
+## Setting Up a Test
+
+### 1. Define the Test
+
+```typescript
+const test = {
+  testId: 'pricing-layout',
+  variants: {
+    control: { weight: 50 },
+    cards: { weight: 50 },
+  },
+};
+```
+
+### 2. Get Variant Assignment
+
+```typescript
+const variant = getABTestVariant(test);
+// Returns 'control' or 'cards'
+```
+
+### 3. Render Based on Variant
+
+```typescript
+{variant === 'control' ? (
+  <PricingTable layout="table" />
+) : (
+  <PricingTable layout="cards" />
+)}
+```
+
+### 4. Track Conversions
+
+```typescript
+function handlePurchase() {
+  trackABTestEvent('pricing-layout', variant, 'purchase');
+}
+```
+
+## Variant Assignment
+
+### How It Works
+
+1. User visits page with A/B test
+2. Framework generates or retrieves user ID
+3. User ID + test ID produces deterministic hash
+4. Hash maps to variant based on weights
+5. Assignment persists via cookie/localStorage
+
+### Weighted Distribution
+
+```typescript
+// Equal split
+variants: { A: { weight: 50 }, B: { weight: 50 } }
+
+// 80/20 split
+variants: { control: { weight: 80 }, experiment: { weight: 20 } }
+
+// Three-way split
+variants: { A: { weight: 33 }, B: { weight: 33 }, C: { weight: 34 } }
+```
+
+Weights don't need to sum to 100 - they're relative proportions.
+
+## Tracking Test Events
+
+### trackABTestEvent
+
+```typescript
+import { trackABTestEvent } from '@zoyth/simple-site-framework/client';
+
+// Track exposure (user saw the variant)
+trackABTestEvent('test-id', variant, 'exposure');
+
+// Track interaction
+trackABTestEvent('test-id', variant, 'click');
+
+// Track conversion
+trackABTestEvent('test-id', variant, 'conversion');
+```
+
+### Custom Event Data
+
+```typescript
+trackABTestEvent('test-id', variant, 'purchase', {
+  value: 49.99,
+  currency: 'USD',
+});
+```
+
+## Multi-Page Tests
+
+For tests spanning multiple pages, variant persists automatically:
+
+```typescript
+// Page 1: Assign variant
+const variant = getABTestVariant({
+  testId: 'onboarding-flow',
+  variants: { A: { weight: 50 }, B: { weight: 50 } },
+});
+
+// Page 2: Same variant returned
+const variant = getABTestVariant({
+  testId: 'onboarding-flow',
+  variants: { A: { weight: 50 }, B: { weight: 50 } },
+});
+// Same user always gets the same variant
+```
+
+## Analyzing Results
+
+### In Google Analytics 4
+
+1. Navigate to Explore > Free Form
+2. Add dimension: Custom Event Parameter > `ab_test_id`
+3. Add dimension: Custom Event Parameter > `ab_variant`
+4. Add metric: Event count, Conversions
+5. Compare variant performance
+
+### Statistical Significance
+
+- Run tests for at least 2 weeks
+- Aim for 1,000+ visitors per variant
+- Use a significance calculator before concluding
+- Don't stop tests early on promising results
+
+## Best Practices
+
+- Test one variable at a time
+- Define success metrics before starting
+- Run tests long enough for statistical significance
+- Document all active tests
+- Clean up completed tests
+- Don't nest A/B tests unless variants are independent
+
+## See Also
+
+- [Tracking Events](./tracking-events.md)
+- [Conversion Tracking](./conversion-tracking.md)
+- [A/B Testing Guide](../../guides/ab-testing.md)

package/docs/features/analytics/conversion-tracking.md

@@ -0,0 +1,207 @@
+# Conversion Tracking
+
+Track goals and measure conversion rates.
+
+## Overview
+
+Conversion tracking measures when users complete desired actions:
+
+- Form submissions
+- CTA clicks
+- Sign-ups
+- Purchases
+- Downloads
+- Phone calls
+
+## Tracking Conversions
+
+### trackConversion
+
+```typescript
+'use client';
+import { trackConversion } from '@zoyth/simple-site-framework/client';
+
+function handleSignup() {
+  trackConversion('signup_complete', {
+    method: 'email',
+    source: 'hero_cta',
+  });
+}
+```
+
+### trackCTAClick
+
+Shorthand for CTA conversion tracking:
+
+```typescript
+import { trackCTAClick } from '@zoyth/simple-site-framework/client';
+
+<button onClick={() => trackCTAClick('get-started', 'pricing-page')}>
+  Get Started
+</button>
+```
+
+## Common Conversion Types
+
+### Form Submission
+
+```typescript
+function handleFormSubmit(formData) {
+  trackConversion('form_submit', {
+    form_name: 'contact',
+    form_location: 'contact_page',
+  });
+}
+```
+
+### Lead Generation
+
+```typescript
+trackConversion('lead_generated', {
+  lead_type: 'demo_request',
+  source: 'landing_page',
+});
+```
+
+### Purchase
+
+```typescript
+trackConversion('purchase', {
+  transaction_id: 'T12345',
+  value: 99.99,
+  currency: 'USD',
+  items: ['pro_plan'],
+});
+```
+
+### Download
+
+```typescript
+trackConversion('file_download', {
+  file_name: 'whitepaper.pdf',
+  file_type: 'pdf',
+});
+```
+
+### Phone Call
+
+```typescript
+<TrackedLink
+  href="tel:+15551234567"
+  eventName="phone_call"
+  eventData={{ location: 'header' }}
+>
+  Call Us
+</TrackedLink>
+```
+
+## Conversion Funnels
+
+Track multi-step conversion paths:
+
+```typescript
+// Step 1: View pricing
+trackEvent('funnel_step', {
+  funnel: 'signup',
+  step: 1,
+  step_name: 'view_pricing',
+});
+
+// Step 2: Select plan
+trackEvent('funnel_step', {
+  funnel: 'signup',
+  step: 2,
+  step_name: 'select_plan',
+  plan: 'pro',
+});
+
+// Step 3: Complete signup
+trackConversion('signup_complete', {
+  funnel: 'signup',
+  step: 3,
+  plan: 'pro',
+});
+```
+
+## GTM Conversion Setup
+
+### Google Ads Conversions
+
+1. In GTM, create Conversion Linker tag
+2. Create Google Ads Conversion Tracking tag
+3. Set trigger to fire on your conversion event
+4. Add conversion ID and label from Google Ads
+
+### GA4 Conversions
+
+1. In GA4, go to Configure > Events
+2. Find your conversion event
+3. Toggle "Mark as conversion"
+
+## Conversion Attribution
+
+### First Click
+
+Attribute to first touchpoint:
+
+```typescript
+trackConversion('signup', {
+  first_touch_source: sessionStorage.getItem('first_source'),
+  first_touch_medium: sessionStorage.getItem('first_medium'),
+});
+```
+
+### Last Click
+
+Attribute to most recent touchpoint:
+
+```typescript
+trackConversion('signup', {
+  utm_source: searchParams.get('utm_source'),
+  utm_medium: searchParams.get('utm_medium'),
+  utm_campaign: searchParams.get('utm_campaign'),
+});
+```
+
+## Conversion Components
+
+### MobileCTA
+
+Sticky mobile CTA with built-in conversion tracking:
+
+```typescript
+import { MobileCTA } from '@zoyth/simple-site-framework/components';
+
+<MobileCTA
+  text="Get Started"
+  href="/signup"
+  trackingId="mobile-cta-signup"
+/>
+```
+
+### ExitIntentModal
+
+Track exit-intent conversions:
+
+```typescript
+import { ExitIntentModal } from '@zoyth/simple-site-framework/components';
+
+<ExitIntentModal
+  onConversion={() => trackConversion('exit_intent_signup')}
+/>
+```
+
+## Best Practices
+
+- Define conversions before building pages
+- Track micro-conversions (newsletter signup) and macro-conversions (purchase)
+- Include attribution data with conversions
+- Test conversion tracking in staging before production
+- Monitor conversion rates over time for regressions
+
+## See Also
+
+- [Tracking Events](./tracking-events.md)
+- [A/B Testing](./ab-testing.md)
+- [MobileCTA Component](../../components/conversion/MobileCTA.md)
+- [ExitIntentModal Component](../../components/ExitIntentModal.md)

package/docs/features/analytics/custom-events.md

@@ -0,0 +1,219 @@
+# Custom Events
+
+Define and track application-specific events.
+
+## Overview
+
+Beyond built-in tracking helpers, you can define custom events tailored to your application's needs.
+
+## Creating Custom Events
+
+### Basic Custom Event
+
+```typescript
+'use client';
+import { trackEvent } from '@zoyth/simple-site-framework/client';
+
+trackEvent('feature_used', {
+  feature_name: 'dark_mode',
+  action: 'toggle_on',
+});
+```
+
+### Typed Custom Events
+
+Define types for consistency:
+
+```typescript
+type AppEvent =
+  | { name: 'feature_used'; data: { feature_name: string; action: string } }
+  | { name: 'content_viewed'; data: { content_id: string; content_type: string } }
+  | { name: 'search_performed'; data: { query: string; results_count: number } };
+
+function trackAppEvent(event: AppEvent) {
+  trackEvent(event.name, event.data);
+}
+
+// Usage
+trackAppEvent({
+  name: 'search_performed',
+  data: { query: 'pricing', results_count: 5 },
+});
+```
+
+## Event Naming Conventions
+
+### Recommended Format
+
+Use `object_action` pattern in snake_case:
+
+```typescript
+// ✅ Good
+'button_click'
+'form_submit'
+'video_play'
+'page_scroll'
+'menu_open'
+'search_complete'
+
+// ❌ Bad
+'clickButton'       // camelCase
+'FORM_SUBMIT'       // UPPER_CASE
+'user clicked btn'  // spaces
+'click'             // too vague
+```
+
+### Category Prefixes
+
+Group related events:
+
+```typescript
+// Navigation
+'nav_menu_open'
+'nav_link_click'
+'nav_search_used'
+
+// Content
+'content_viewed'
+'content_shared'
+'content_bookmarked'
+
+// Commerce
+'product_viewed'
+'cart_updated'
+'checkout_started'
+```
+
+## Event Properties
+
+### Standard Properties
+
+Include consistent context:
+
+```typescript
+trackEvent('button_click', {
+  // What
+  element_id: 'hero-cta',
+  element_text: 'Get Started',
+
+  // Where
+  page_path: '/pricing',
+  page_section: 'hero',
+
+  // Context
+  locale: 'en',
+  viewport: 'desktop',
+});
+```
+
+### Dynamic Properties
+
+Capture runtime context:
+
+```typescript
+function trackInteraction(elementId: string, action: string) {
+  trackEvent(`${elementId}_${action}`, {
+    timestamp: Date.now(),
+    page_path: window.location.pathname,
+    referrer: document.referrer,
+    screen_width: window.innerWidth,
+  });
+}
+```
+
+## Custom Event Patterns
+
+### Feature Usage Tracking
+
+```typescript
+function trackFeatureUsage(feature: string) {
+  trackEvent('feature_used', {
+    feature,
+    session_id: getSessionId(),
+    usage_count: incrementUsageCount(feature),
+  });
+}
+```
+
+### Error Tracking
+
+```typescript
+function trackError(error: Error, context: string) {
+  trackEvent('app_error', {
+    error_message: error.message,
+    error_type: error.name,
+    context,
+    page_path: window.location.pathname,
+  });
+}
+```
+
+### User Engagement
+
+```typescript
+function trackEngagement(type: string, duration?: number) {
+  trackEvent('user_engagement', {
+    engagement_type: type,
+    engagement_duration: duration,
+    page_path: window.location.pathname,
+  });
+}
+
+// Track time on page
+trackEngagement('time_on_page', 45);
+
+// Track interaction
+trackEngagement('comment_posted');
+```
+
+### Search Tracking
+
+```typescript
+function trackSearch(query: string, results: number) {
+  trackEvent('search', {
+    search_term: query,
+    results_count: results,
+    search_type: 'site_search',
+  });
+}
+
+function trackSearchClick(query: string, position: number) {
+  trackEvent('search_result_click', {
+    search_term: query,
+    click_position: position,
+  });
+}
+```
+
+## GTM Integration
+
+Custom events push to GTM dataLayer:
+
+```typescript
+// Framework automatically pushes to dataLayer
+trackEvent('custom_event', { key: 'value' });
+
+// Equivalent to:
+window.dataLayer.push({
+  event: 'custom_event',
+  key: 'value',
+});
+```
+
+In GTM, create triggers based on custom event names to fire tags.
+
+## Best Practices
+
+- Document your event taxonomy
+- Use consistent naming conventions across the team
+- Include enough context to make events actionable
+- Avoid tracking PII (emails, names, phone numbers)
+- Don't over-track - focus on events that inform decisions
+- Test events in GTM Preview mode before deploying
+- Review and prune unused events periodically
+
+## See Also
+
+- [Tracking Events](./tracking-events.md)
+- [Conversion Tracking](./conversion-tracking.md)
+- [Privacy](./privacy.md)