Viral coefficient optimization

ather than an open-ended growth hypothesis.

Core Solution

Optimizing viral coefficient requires building an event-driven attribution pipeline that tracks the complete referral journey, calculates k with cohort precision, and surfaces conversion bottlenecks for rapid iteration. The implementation spans token generation, attribution logic, event processing, and real-time metric calculation.

Step 1: Cryptographic Referral Token Generation

Referral links must be tamper-resistant, trackable, and revocable. Use UUIDv7 for temporal ordering and HMAC-SHA256 for signature verification.

import { createHmac, randomUUID } from 'crypto';

interface ReferralToken {
  id: string;
  issuerId: string;
  signature: string;
  expiresAt: number;
}

export function generateReferralToken(issuerId: string, secret: string): ReferralToken {
  const id = randomUUID();
  const payload = `${id}:${issuerId}`;
  const expiresAt = Date.now() + (30 * 24 * 60 * 60 * 1000); // 30 days
  const signature = createHmac('sha256', secret)
    .update(`${payload}:${expiresAt}`)
    .digest('hex');

  return { id, issuerId, signature, expiresAt };
}

export function verifyReferralToken(token: ReferralToken, secret: string): boolean {
  if (Date.now() > token.expiresAt) return false;
  const expected = createHmac('sha256', secret)
    .update(`${token.id}:${token.issuerId}:${token.expiresAt}`)
    .digest('hex');
  return expected === token.signature;
}

Step 2: Attribution Pipeline Architecture

Referral events must flow through an idempotent consumer that handles cross-device matching, attribution window validation, and conversion state transitions. The architecture uses an event bus (Kafka/PubSub), a stateful attribution service, and a metrics aggregator.

Architecture Decisions:

• Event Sourcing: All referral interactions are appended as immutable events. Enables replay, audit trails, and accurate cohort reconstruction.
• Idempotent Processing: Deduplication via event IDs prevents double-counting from retries or client-side duplicate dispatches.
• Rolling Attribution Windows: Configurable windows (default 7 days, extendable to 14) capture delayed conversions without inflating last-click bias.
• Probabilistic Device Matching: Fallback to hashed email/phone matching when deterministic cookies fail, with explicit opt-in for privacy compliance.

// Event schema
type ReferralEvent = 
  | { type: 'INVITE_SENT'; eventId: string; issuerId: string; recipientHash: string; timestamp: number }
  | { type: 'INVITE_RECEIVED'; eventId: string; token: string; deviceId: string; timestamp: number }
  | { type: 'SIGNUP_COMPLETED'; eventId: string; userId: string; token: string; timestamp: number }
  | { type: 'ACTIVATION_COMPLETED'; eventId: string; userId: string; action: string; timestamp: number };

// Idempotent event processor
export class AttributionProcessor {
  private processedIds = new Set<string>();

  async process(event: ReferralEvent): Promise<void> {
    if (this.processedIds.has(event.eventId)) return;
    this.processedIds.add(event.eventId);

    switch (event.type) {
      case 'INVITE_SENT':
        await this.trackInviteSent(event);
        break;
      case 'INVITE_RECEIVED':
        await this.trackInviteReceived(event);
        break;
      case 'SIGNUP_COMPLETED':
        await this.trackSignupCompleted(event);
        break;
      case 'ACTIVATION_COMPLETED':
        await this.trackActivationCompleted(event);
        break;
    }
  }

  private async trackInviteSent(event: Extract<ReferralEvent, { type: 'INVITE_SENT' }>) {
    // Store in Redis/TTL for window validation
    await redis.setex(`invite:${event.eventId}`, 604800, JSON.stringify(event));
  }

  private async trackSignupCompleted(event: Extract<ReferralEvent, { type: 'SIGNUP_COMPLETED' }>) {
    const inviteKey = `invite:*:${event.token}`;
    const invite = await redis.get(inviteKey);
    if (!invite) return; // Outside attribution window or invalid token

    const parsed = JSON.parse(invite) as Extract<ReferralEvent, { type: 'INVITE_SENT' }>;
    // Atomic increment for conversion tracking
    await redis.hincrby(`k_metrics:${parsed.issuerId}`, 'conversions', 1);
    await redis.hset(`user_attribution:${event.userId}`, { issuerId: parsed.issuerId, convertedAt: Date.now() });
  }
}

Step 3: Real-Time k Calculation Service

k must be calculated per cohort, not globally. Rolling 7-day and 30-day windows prevent skew from viral spikes or seasonal drops.

export class ViralCoefficientCalculator {
  async calculateK(issuerId: string, windowDays: number = 7): Promise<number> {
    const cutoff = Date.now() - (windowDays * 24 * 60 * 60 * 1000);
    const invites = await this.countInvites(issuerId, cutoff);
    const conversions = await this.countConversions(issuerId, cutoff);
    
    return invites > 0 ? conversions / invites : 0;
  }

  private async countInvites(issuerId: string, cutoff: number): Promise<number> {
    const keys = await redis.keys(`invite:*:${issuerId}`);
    let count = 0;
    for (const key of keys) {
      const data = await redis.get(key);
      if (data && JSON.parse(data).timestamp > cutoff) count++;
    }
    return count;
  }

  private async countConversions(issuerId: string, cutoff: number): Promise<number> {
    const raw = await redis.hget(`k_metrics:${issuerId}`, 'conversions');
    return raw ? parseInt(raw, 10) : 0;
  }
}

Step 4: Conversion Optimization Loop

Engineering teams must instrument the post-referral landing page, onboarding flow, and first-action completion. A/B test attribution-aware landing variants, track drop-off at each step, and route low-conversion cohorts to simplified onboarding. Use feature flags to isolate changes and measure c impact without contaminating i.

Pitfall Guide

1. Tracking Clicks Instead of Conversions Click-through rates inflate perceived viral performance but do not correlate with acquisition cost or retention. Always track SIGNUP_COMPLETED and ACTIVATION_COMPLETED as conversion boundaries. Clicks belong to top-of-funnel analytics, not k calculation.

2. Static Attribution Windows Hardcoded 24-hour windows discard 40–60% of valid referrals. Users switch devices, delay onboarding, or require social validation before signing up. Implement rolling windows with configurable durations and decay functions for older events.

3. Cross-Device Attribution Failure Mobile-to-desktop handoffs break cookie-based tracking. Use deterministic matching (verified email/phone) as primary, fallback to hashed device fingerprinting with explicit privacy disclosures, and never merge identities without user consent.

4. Referral Farming and Fraud Incentivized sharing attracts automated accounts, fake emails, and self-referral loops. Implement rate limiting per IP/device, require activation thresholds before rewarding issuers, and cross-validate recipient email domains against known disposable providers.

5. Optimizing i at the Expense of c Pushing users to send 10 invites when 3 convert at 5% yields k = 0.15. Reducing share friction to 5 invites with a 12% conversion rate yields k = 0.6. Engineering resources should target conversion bottlenecks first, then scale i.

6. Ignoring Post-Signup Retention Viral acquisition is worthless if referred users churn within 48 hours. Track D1/D7 retention for referred vs. organic cohorts. Adjust reward structures to trigger only after retention thresholds are met.

7. Non-Idempotent Event Processing Retries, network blips, and client-side duplicate dispatches cause double-counting. Always enforce event ID deduplication, use atomic increments for counters, and maintain idempotent database writes with unique constraints on (eventId, userId).

Production Bundle

Action Checklist

• Define referral event schema with explicit conversion boundaries
• Implement HMAC-signed referral tokens with expiration
• Deploy idempotent event processor with deduplication
• Configure rolling attribution windows (7/14 days)
• Instrument post-referral landing page and onboarding funnel
• Build real-time k calculator with cohort segmentation
• Implement fraud detection: rate limits, disposable email blocking, activation-gated rewards
• Set up A/B testing framework for conversion optimization

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Mobile-first app with cross-device onboarding	Probabilistic device matching + email verification fallback	Captures delayed conversions without violating platform restrictions	Low infrastructure overhead, moderate privacy compliance cost
B2B SaaS with long sales cycles	14-day rolling window + activation-gated rewards	Aligns attribution with enterprise evaluation timelines	Higher reward liability, lower CAC via accurate targeting
Consumer app with viral incentives	Fraud detection layer + D7 retention threshold	Prevents referral farming from inflating k	Initial engineering cost, 40–60% reduction in wasted rewards
Legacy app with cookie-only tracking	Migrate to event-sourced pipeline with UUIDv7 tokens	Eliminates attribution drift and enables cohort analysis	Medium migration cost, long-term CPA reduction

Configuration Template

viral_attribution:
  token:
    algorithm: "HMAC-SHA256"
    expiry_days: 30
    rotation_schedule: "0 0 1 * *"
  attribution:
    window_days: [7, 14]
    cross_device_fallback: true
    hash_algorithm: "SHA-256"
    privacy_consent_required: true
  fraud:
    rate_limit_per_ip: 50
    rate_limit_per_device: 100
    disposable_domains_file: "/config/disposable_domains.txt"
    reward_trigger: "activation_completed"
  metrics:
    calculation_interval_seconds: 300
    cohort_segments: ["new", "power", "churned"]
    alert_thresholds:
      k_below: 0.15
      c_drop_percent: 20

Quick Start Guide

1. Generate Tokens: Integrate generateReferralToken into your user dashboard. Store tokens in your database with issuerId, expiresAt, and signature.
2. Deploy Event Consumer: Run the AttributionProcessor as a background worker. Connect it to your event bus and configure Redis for stateful window tracking.
3. Instrument Frontend: Dispatch INVITE_SENT, INVITE_RECEIVED, SIGNUP_COMPLETED, and ACTIVATION_COMPLETED events with unique eventId values. Ensure idempotent retries.
4. Calculate k: Deploy ViralCoefficientCalculator to your metrics service. Query per-issuer k using rolling windows and expose via internal API or dashboard.
5. Validate & Iterate: Run a 7-day cohort test. Compare attribution accuracy before/after migration. Adjust windows, test landing variants, and gate rewards on activation. Monitor fraud alerts and adjust rate limits accordingly.