《移动游戏产品的架构·商业化与发行工程》8.2 广告作弊与点击农场

毛收入 = 展示量 / 1000 × eCPM
可结收入 = 毛收入 × 可结比例
追回金额 = 毛收入 - 可结收入

// file: src/biz/ad-fraud.ts
// tier: L1
// verify: node --test test/biz/ad-fraud.test.ts

export type TrafficVerdict = "valid" | "suspect" | "invalid";
export type AdPlacement = "rewarded" | "interstitial" | "banner";

export interface TrafficSample {
  readonly placement: AdPlacement;
  readonly impressions: number;
  readonly clicks: number;
  readonly conversions: number;
  readonly verifiedCompletions: number;
  readonly uniqueDevices: number;
  readonly p50TimeToClickMs: number;
  readonly eCpmCents: number;
}

export interface TrafficPolicy {
  readonly expectedCtr: number;
  readonly expectedCvr: number;
  readonly minTimeToClickMs: number;
  readonly maxImpressionsPerDevice: number;
  readonly maxVerificationGap: number;
  readonly suspectScore: number;
  readonly invalidScore: number;
}

export interface TrafficSignal {
  readonly code: string;
  readonly points: number;
  readonly detail: string;
}

export interface TrafficAssessment {
  readonly placement: AdPlacement;
  readonly ctr: number;
  readonly cvr: number;
  readonly impressionsPerDevice: number;
  readonly grossCents: number;
  readonly billableCents: number;
  readonly clawbackCents: number;
  readonly score: number;
  readonly verdict: TrafficVerdict;
  readonly signals: readonly TrafficSignal[];
}

export interface RevenueAtRisk {
  readonly invalidImpressions: number;
  readonly atRiskCents: number;
}

const SUSPECT_BILLABLE_RATIO = 0.5;

function assertNonNegative(name: string, value: number): void {
  if (!Number.isFinite(value) || value < 0) {
    throw new RangeError(`${name} must be a finite non-negative number, got ${value}`);
  }
}

function validate(sample: TrafficSample): void {
  assertNonNegative("impressions", sample.impressions);
  assertNonNegative("clicks", sample.clicks);
  assertNonNegative("conversions", sample.conversions);
  assertNonNegative("verifiedCompletions", sample.verifiedCompletions);
  assertNonNegative("uniqueDevices", sample.uniqueDevices);
  assertNonNegative("p50TimeToClickMs", sample.p50TimeToClickMs);
  assertNonNegative("eCpmCents", sample.eCpmCents);
  if (sample.clicks > sample.impressions) {
    throw new RangeError("clicks cannot exceed impressions");
  }
  if (sample.conversions > sample.clicks) {
    throw new RangeError("conversions cannot exceed clicks");
  }
  if (sample.verifiedCompletions > sample.clicks) {
    throw new RangeError("verified completions cannot exceed clicks");
  }
}

export function estimateRevenueAtRisk(
  impressions: number,
  eCpmCents: number,
  fraudShare: number,
): RevenueAtRisk {
  assertNonNegative("impressions", impressions);
  assertNonNegative("eCpmCents", eCpmCents);
  if (fraudShare < 0 || fraudShare > 1) {
    throw new RangeError(`fraudShare must be between 0 and 1, got ${fraudShare}`);
  }
  const invalidImpressions = Math.round(impressions * fraudShare);
  return {
    invalidImpressions,
    atRiskCents: Math.round((invalidImpressions / 1000) * eCpmCents),
  };
}

export function assessTraffic(sample: TrafficSample, policy: TrafficPolicy): TrafficAssessment {
  validate(sample);
  const ctr = sample.impressions === 0 ? 0 : sample.clicks / sample.impressions;
  const cvr = sample.clicks === 0 ? 0 : sample.conversions / sample.clicks;
  const impressionsPerDevice =
    sample.uniqueDevices === 0 ? 0 : sample.impressions / sample.uniqueDevices;
  const grossCents = (sample.impressions / 1000) * sample.eCpmCents;
  const signals: TrafficSignal[] = [];

  if (sample.clicks > 0 && ctr > policy.expectedCtr * 3) {
    signals.push({
      code: "ctr-spike",
      points: 25,
      detail: `CTR ${(ctr * 100).toFixed(2)}% is more than three times expected ${(policy.expectedCtr * 100).toFixed(2)}%`,
    });
  }
  if (sample.clicks >= 100 && cvr < policy.expectedCvr / 4) {
    signals.push({
      code: "conversion-collapse",
      points: 20,
      detail: `CVR ${(cvr * 100).toFixed(3)}% is far below expected ${(policy.expectedCvr * 100).toFixed(2)}%`,
    });
  }
  if (sample.clicks > 0 && sample.p50TimeToClickMs < policy.minTimeToClickMs) {
    signals.push({
      code: "instant-click",
      points: 20,
      detail: `median time to click ${sample.p50TimeToClickMs}ms is below ${policy.minTimeToClickMs}ms`,
    });
  }
  if (sample.uniqueDevices > 0 && impressionsPerDevice > policy.maxImpressionsPerDevice) {
    signals.push({
      code: "device-concentration",
      points: 20,
      detail: `${impressionsPerDevice.toFixed(1)} impressions per device exceeds ${policy.maxImpressionsPerDevice}`,
    });
  }
  if (sample.clicks > 0) {
    const gap = (sample.clicks - sample.verifiedCompletions) / sample.clicks;
    if (gap > policy.maxVerificationGap) {
      signals.push({
        code: "verification-gap",
        points: 30,
        detail: `${(gap * 100).toFixed(1)}% of clicks lack a server-side completion`,
      });
    }
  }

  const score = Math.min(100, signals.reduce((sum, signal) => sum + signal.points, 0));
  const verdict: TrafficVerdict =
    score >= policy.invalidScore ? "invalid" : score >= policy.suspectScore ? "suspect" : "valid";
  const payableRatio = verdict === "valid" ? 1 : verdict === "suspect" ? SUSPECT_BILLABLE_RATIO : 0;
  const billableCents = grossCents * payableRatio;
  return {
    placement: sample.placement,
    ctr,
    cvr,
    impressionsPerDevice,
    grossCents,
    billableCents,
    clawbackCents: grossCents - billableCents,
    score,
    verdict,
    signals,
  };
}

export function formatTrafficAssessment(assessment: TrafficAssessment): string {
  const codes = assessment.signals.map((signal) => signal.code).join(",") || "none";
  return `${assessment.placement} ${assessment.verdict} score=${assessment.score} gross=${Math.round(assessment.grossCents)} billable=${Math.round(assessment.billableCents)} signals=${codes}`;
}