Campaign Tracking

// UTM parameters are captured automatically
// Example URL: https://example.com?utm_source=google&utm_medium=cpc&utm_campaign=brand

// pxlpeak captures and stores:
interface UTMParameters {
  utm_source: 'google';      // Traffic source
  utm_medium: 'cpc';         // Marketing medium
  utm_campaign: 'brand';     // Campaign name
  utm_content?: string;      // Ad variation
  utm_term?: string;         // Paid search keyword
}

// Access UTM data in events
pxlpeak.track('page_viewed', {
  page_path: '/landing',
  // UTM params automatically attached
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'brand'
});

// Recommended UTM naming conventions
interface UTMConventions {
  source: {
    description: 'Platform or publisher';
    examples: ['google', 'facebook', 'linkedin', 'newsletter', 'partner_acme'];
    format: 'lowercase, underscores for spaces';
  };

  medium: {
    description: 'Marketing channel type';
    standardValues: [
      'cpc',       // Paid search
      'cpm',       // Display advertising
      'email',     // Email marketing
      'social',    // Organic social
      'paid_social', // Paid social
      'referral',  // Partner referrals
      'affiliate', // Affiliate marketing
      'organic'    // Organic search (rarely used)
    ];
    format: 'lowercase, use standard values';
  };

  campaign: {
    description: 'Campaign identifier';
    format: 'lowercase_with_underscores';
    include: ['campaign_name', 'month_year', 'audience'];
    examples: ['brand_jan_2026', 'product_launch_enterprise'];
  };

  content: {
    description: 'Differentiates ad variations';
    examples: ['headline_a', 'video_ad', 'sidebar_banner'];
  };

  term: {
    description: 'Paid search keywords';
    examples: ['marketing_attribution', 'analytics_software'];
  };
}

// UTM builder function
function buildCampaignURL(
  baseURL: string,
  campaign: CampaignParams
): string {
  const params = new URLSearchParams();

  params.set('utm_source', campaign.source.toLowerCase());
  params.set('utm_medium', campaign.medium.toLowerCase());
  params.set('utm_campaign', campaign.campaign.toLowerCase().replace(/\s+/g, '_'));

  if (campaign.content) {
    params.set('utm_content', campaign.content.toLowerCase());
  }
  if (campaign.term) {
    params.set('utm_term', campaign.term.toLowerCase());
  }

  return `${baseURL}?${params.toString()}`;
}

// Define and manage campaigns in pxlpeak
interface Campaign {
  id: string;
  name: string;
  description: string;

  // Tracking configuration
  tracking: {
    utmSource: string;
    utmMedium: string;
    utmCampaign: string;
  };

  // Budget and goals
  budget?: {
    amount: number;
    currency: string;
    period: 'daily' | 'weekly' | 'monthly' | 'total';
  };

  goals?: {
    conversions?: number;
    revenue?: number;
    cpa?: number;
    roas?: number;
  };

  // Timeline
  startDate: string;
  endDate?: string;
  status: 'draft' | 'active' | 'paused' | 'completed';

  // Organization
  channel: string;
  tags: string[];
}

// Create a campaign
const campaign = await pxlpeak.campaigns.create({
  name: 'Q1 Brand Awareness',
  description: 'Brand awareness campaign targeting marketing managers',

  tracking: {
    utmSource: 'google',
    utmMedium: 'cpc',
    utmCampaign: 'brand_q1_2026'
  },

  budget: {
    amount: 10000,
    currency: 'USD',
    period: 'monthly'
  },

  goals: {
    conversions: 500,
    cpa: 20
  },

  startDate: '2026-01-01',
  endDate: '2026-03-31',
  status: 'active',
  channel: 'paid_search',
  tags: ['brand', 'awareness', 'q1']
});

// Organize campaigns into groups for better management
interface CampaignGroup {
  id: string;
  name: string;
  campaigns: string[];  // Campaign IDs
  aggregateMetrics: boolean;
}

// Create campaign group
const group = await pxlpeak.campaignGroups.create({
  name: 'Q1 2026 Initiatives',
  campaigns: ['camp_001', 'camp_002', 'camp_003'],
  aggregateMetrics: true
});

// Query group performance
const groupMetrics = await pxlpeak.analytics.query({
  dateRange: { start: '2026-01-01', end: '2026-03-31' },
  metrics: ['impressions', 'clicks', 'conversions', 'revenue', 'spend'],
  filters: [
    { field: 'campaign_group', operator: 'eq', value: group.id }
  ]
});

// Configure tracking for different channels
interface ChannelConfig {
  channel: string;
  platforms: string[];
  trackingMethod: 'utm' | 'click_id' | 'pixel' | 'api';
  attribution: {
    touchpointType: 'click' | 'impression' | 'both';
    lookbackWindow: number;  // days
  };
}

const channelConfigs: ChannelConfig[] = [
  {
    channel: 'paid_search',
    platforms: ['google_ads', 'microsoft_ads'],
    trackingMethod: 'click_id',
    attribution: {
      touchpointType: 'click',
      lookbackWindow: 30
    }
  },
  {
    channel: 'paid_social',
    platforms: ['meta_ads', 'linkedin_ads', 'twitter_ads'],
    trackingMethod: 'utm',
    attribution: {
      touchpointType: 'click',
      lookbackWindow: 7
    }
  },
  {
    channel: 'display',
    platforms: ['google_dv360', 'thetradedesk'],
    trackingMethod: 'pixel',
    attribution: {
      touchpointType: 'both',
      lookbackWindow: 30
    }
  },
  {
    channel: 'email',
    platforms: ['mailchimp', 'klaviyo', 'custom'],
    trackingMethod: 'utm',
    attribution: {
      touchpointType: 'click',
      lookbackWindow: 7
    }
  }
];

// Integrate with ad platforms for enhanced tracking
interface AdPlatformIntegration {
  google_ads: {
    gclid: 'Auto-captured click ID';
    importConversions: true;
    costData: true;
  };

  meta_ads: {
    fbclid: 'Auto-captured click ID';
    conversionAPI: true;
    costData: true;
  };

  linkedin_ads: {
    liclid: 'Auto-captured click ID';
    conversionTracking: true;
    costData: true;
  };
}

// Configure Google Ads integration
await pxlpeak.integrations.configure({
  platform: 'google_ads',
  credentials: {
    customerId: 'xxx-xxx-xxxx',
    developerToken: process.env.GOOGLE_ADS_DEV_TOKEN
  },
  settings: {
    importConversions: true,
    conversionActions: ['purchase', 'lead'],
    importCostData: true,
    syncFrequency: 'hourly'
  }
});

// Auto-capture click IDs
// pxlpeak automatically captures and stores:
// - gclid (Google Ads)
// - fbclid (Meta/Facebook)
// - msclkid (Microsoft Ads)
// - li_fat_id (LinkedIn)
// - ttclid (TikTok)

// Attribute conversions across campaign touchpoints
interface CampaignTouchpoint {
  campaign_id: string;
  campaign_name: string;
  source: string;
  medium: string;
  timestamp: string;
  interaction_type: 'click' | 'view';
}

// Query campaign attribution
const attributionReport = await pxlpeak.attribution.query({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  conversionEvent: 'purchase_completed',
  model: 'linear',
  groupBy: ['campaign_name', 'source', 'medium'],
  metrics: [
    'conversions',
    'revenue',
    'attributed_conversions',
    'attributed_revenue'
  ]
});

// Results
// {
//   results: [
//     {
//       campaign_name: 'brand_q1_2026',
//       source: 'google',
//       medium: 'cpc',
//       conversions: 150,
//       revenue: 14999.50,
//       attributed_conversions: 87.5,  // Multi-touch credit
//       attributed_revenue: 8749.72
//     },
//     ...
//   ]
// }

// Compare first-touch vs last-touch attribution by campaign
const touchAnalysis = await pxlpeak.attribution.compare({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  conversionEvent: 'purchase_completed',
  groupBy: 'campaign_name',
  models: ['first_touch', 'last_touch']
});

// Identify campaigns that introduce vs convert
// First-touch heavy: Good for awareness
// Last-touch heavy: Good for conversion

// Track campaign assist value
const assistedConversions = await pxlpeak.attribution.query({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  conversionEvent: 'purchase_completed',
  groupBy: 'campaign_name',
  metrics: [
    'direct_conversions',     // Last-touch conversions
    'assisted_conversions',   // Appeared in path but not last
    'total_touchpoints',      // Times appeared in any path
    'assist_ratio'            // Assisted / Direct ratio
  ]
});

// Real-time campaign metrics
interface CampaignMetrics {
  impressions: number;
  clicks: number;
  ctr: number;              // Click-through rate
  conversions: number;
  conversionRate: number;
  revenue: number;
  cost: number;             // From ad platform integration
  cpc: number;              // Cost per click
  cpa: number;              // Cost per acquisition
  roas: number;             // Return on ad spend
  roiPercent: number;       // ROI percentage
}

// Query campaign performance
const performance = await pxlpeak.campaigns.getPerformance({
  campaignId: 'camp_xxx',
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  metrics: [
    'impressions', 'clicks', 'ctr',
    'conversions', 'conversion_rate',
    'revenue', 'cost', 'cpc', 'cpa', 'roas'
  ],
  granularity: 'day'
});

// Subscribe to real-time updates
pxlpeak.campaigns.subscribe('camp_xxx', {
  onConversion: (conversion) => {
    console.log('New conversion:', conversion);
  },
  onMetricUpdate: (metrics) => {
    console.log('Updated metrics:', metrics);
  }
});

// Compare against benchmarks
interface CampaignBenchmarks {
  industry: {
    ctr: number;
    conversionRate: number;
    cpc: number;
    cpa: number;
  };

  historical: {
    previousPeriod: CampaignMetrics;
    previousYear: CampaignMetrics;
  };

  goals: {
    targetCPA: number;
    targetROAS: number;
    targetConversions: number;
  };
}

// Get campaign with benchmarks
const campaignWithBenchmarks = await pxlpeak.campaigns.getWithBenchmarks({
  campaignId: 'camp_xxx',
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  comparePeriod: 'previous_month',
  includeIndustryBenchmarks: true
});

// {
//   metrics: { ctr: 3.2, conversionRate: 2.1, cpa: 18.50 },
//   benchmarks: {
//     industry: { ctr: 2.5, conversionRate: 1.8, cpa: 22.00 },
//     previousPeriod: { ctr: 2.9, conversionRate: 1.9, cpa: 21.00 }
//   },
//   performance: {
//     vsIndustry: '+28% CTR, +17% Conv Rate, -16% CPA',
//     vsPrevious: '+10% CTR, +11% Conv Rate, -12% CPA'
//   }
// }

// Test campaign variations
interface CampaignTest {
  id: string;
  name: string;
  campaigns: {
    control: string;  // Campaign ID
    variants: string[];
  };
  trafficAllocation: number[];  // Percentage for each
  primaryMetric: string;
  secondaryMetrics: string[];
  minimumSampleSize: number;
  statisticalSignificance: number;
  status: 'running' | 'completed' | 'stopped';
}

// Create campaign test
const test = await pxlpeak.campaignTests.create({
  name: 'Landing Page A/B Test',
  campaigns: {
    control: 'camp_001',  // Original landing page
    variants: ['camp_002']  // New landing page
  },
  trafficAllocation: [50, 50],
  primaryMetric: 'conversion_rate',
  secondaryMetrics: ['bounce_rate', 'time_on_page', 'revenue_per_visitor'],
  minimumSampleSize: 1000,
  statisticalSignificance: 0.95
});

// Get test results
const results = await pxlpeak.campaignTests.getResults(test.id);
// {
//   status: 'significant',
//   winner: 'camp_002',
//   confidence: 0.97,
//   metrics: {
//     control: { conversionRate: 2.1, sampleSize: 5234 },
//     variant: { conversionRate: 2.8, sampleSize: 5189 }
//   },
//   lift: { conversionRate: '+33%' },
//   recommendation: 'Implement variant - 97% confidence of improvement'
// }

// Optimize budget allocation across campaigns
const budgetOptimization = await pxlpeak.campaigns.optimizeBudget({
  campaignIds: ['camp_001', 'camp_002', 'camp_003'],
  totalBudget: 50000,
  optimizationGoal: 'roas',  // or 'conversions', 'cpa'
  constraints: {
    minSpendPerCampaign: 5000,
    maxSpendPerCampaign: 30000
  }
});

// {
//   recommendations: [
//     { campaignId: 'camp_001', currentBudget: 15000, recommendedBudget: 22000, expectedROAS: 4.2 },
//     { campaignId: 'camp_002', currentBudget: 20000, recommendedBudget: 18000, expectedROAS: 3.1 },
//     { campaignId: 'camp_003', currentBudget: 15000, recommendedBudget: 10000, expectedROAS: 2.8 }
//   ],
//   expectedTotalROAS: 3.5,
//   currentTotalROAS: 3.2,
//   improvement: '+9%'
// }

// Generate campaign reports
const report = await pxlpeak.reports.generate({
  type: 'campaign_performance',
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  groupBy: ['campaign_name', 'week'],
  metrics: [
    'impressions', 'clicks', 'ctr',
    'conversions', 'conversion_rate',
    'revenue', 'cost', 'roas'
  ],
  filters: [
    { field: 'channel', operator: 'eq', value: 'paid_search' }
  ],
  sort: [{ field: 'revenue', direction: 'desc' }],
  format: 'pdf'
});

// Schedule recurring reports
await pxlpeak.reports.schedule({
  name: 'Weekly Campaign Report',
  type: 'campaign_performance',
  schedule: 'weekly',
  dayOfWeek: 'monday',
  time: '09:00',
  recipients: ['marketing@example.com'],
  config: {
    dateRange: 'last_7_days',
    groupBy: ['campaign_name'],
    metrics: ['clicks', 'conversions', 'revenue', 'roas']
  }
});

// Build campaign dashboard
const dashboard = await pxlpeak.dashboards.create({
  name: 'Campaign Performance',
  widgets: [
    {
      type: 'kpi_card',
      title: 'Total Conversions',
      metric: 'conversions',
      comparison: 'previous_period'
    },
    {
      type: 'line_chart',
      title: 'Conversions Over Time',
      metrics: ['conversions'],
      groupBy: 'day',
      breakdown: 'campaign_name'
    },
    {
      type: 'bar_chart',
      title: 'Revenue by Campaign',
      metric: 'revenue',
      groupBy: 'campaign_name',
      sort: 'desc'
    },
    {
      type: 'table',
      title: 'Campaign Details',
      columns: ['campaign_name', 'clicks', 'conversions', 'revenue', 'roas'],
      sort: [{ field: 'revenue', direction: 'desc' }]
    }
  ],
  filters: [
    { field: 'date_range', type: 'date_picker', default: 'last_30_days' },
    { field: 'channel', type: 'dropdown', options: 'dynamic' }
  ]
});

// Build tracked URLs
interface CampaignURLBuilder {
  baseURL: string;
  campaign: string;
  source: string;
  medium: string;
  content?: string;
  term?: string;
  customParams?: Record<string, string>;
}

function buildCampaignURL(config: CampaignURLBuilder): string {
  const url = new URL(config.baseURL);

  url.searchParams.set('utm_campaign', config.campaign);
  url.searchParams.set('utm_source', config.source);
  url.searchParams.set('utm_medium', config.medium);

  if (config.content) {
    url.searchParams.set('utm_content', config.content);
  }

  if (config.term) {
    url.searchParams.set('utm_term', config.term);
  }

  if (config.customParams) {
    for (const [key, value] of Object.entries(config.customParams)) {
      url.searchParams.set(key, value);
    }
  }

  return url.toString();
}

// UI Component for URL building
// Available at: Dashboard → Campaigns → URL Builder

// Create short links for campaign tracking
const shortLink = await pxlpeak.links.create({
  destinationURL: 'https://example.com/landing-page',
  campaign: {
    source: 'linkedin',
    medium: 'social',
    campaign: 'product_launch_2026',
    content: 'post_1'
  },
  customSlug: 'product-launch',  // Optional
  tracking: {
    clickTracking: true,
    deviceTracking: true,
    locationTracking: true
  }
});

// Result: https://link.pxlpeak.io/product-launch
// Redirects to full URL with UTM parameters

## Campaign Naming Conventions

### Structure
[channel]_[campaign_type]_[target]_[date]

### Examples
- paid_search_brand_awareness_jan_2026
- email_nurture_enterprise_q1_2026
- social_product_launch_smb_mar_2026

### Guidelines
1. Use lowercase with underscores
2. Be descriptive but concise
3. Include date or quarter
4. Include target audience when relevant
5. Be consistent across all campaigns

## Campaign Launch Checklist

### Before Launch
- [ ] UTM parameters configured
- [ ] Landing page tracking verified
- [ ] Conversion tracking tested
- [ ] Goals and KPIs defined
- [ ] Budget allocated
- [ ] Attribution model selected

### At Launch
- [ ] Verify traffic appearing in pxlpeak
- [ ] Check UTM parameters captured correctly
- [ ] Monitor for tracking errors

### Ongoing
- [ ] Daily performance checks
- [ ] Weekly optimization reviews
- [ ] Monthly attribution analysis
- [ ] Quarterly strategy review