《移动游戏产品的架构·商业化与发行工程》7.2 归因窗口、去重与隐私限制

// file: src/biz/attribution-window.ts
// tier: L1
// verify: node --test test/biz/attribution-window.test.ts

export type TouchKind = "click" | "view";
export type ChannelId = "adnet-alpha" | "adnet-beta" | "adnet-gamma";
export type AttributionModel = "last-touch" | "first-touch";

export interface Touch {
  readonly touchId: string;
  readonly channel: ChannelId;
  readonly kind: TouchKind;
  readonly touchedAtMs: number;
}

export interface WindowPolicy {
  readonly clickWindowMs: number;
  readonly viewWindowMs: number;
  readonly model: AttributionModel;
}

export type WindowCode = "in-window" | "too-old" | "future";

export interface WindowCheck {
  readonly code: WindowCode;
  readonly ageMs: number;
  readonly windowMs: number;
}

export function checkTouch(touch: Touch, installAtMs: number, policy: WindowPolicy): WindowCheck {
  const windowMs = touch.kind === "click" ? policy.clickWindowMs : policy.viewWindowMs;
  const ageMs = installAtMs - touch.touchedAtMs;
  if (ageMs < 0) {
    return { code: "future", ageMs, windowMs };
  }
  if (ageMs > windowMs) {
    return { code: "too-old", ageMs, windowMs };
  }
  return { code: "in-window", ageMs, windowMs };
}

export interface RejectedTouch {
  readonly touchId: string;
  readonly code: WindowCode;
}

export interface Selection {
  readonly status: "attributed" | "unattributed";
  readonly touch: Touch | null;
  readonly eligibleCount: number;
  readonly rejected: readonly RejectedTouch[];
  readonly detail: string;
}

function isBetter(candidate: Touch, current: Touch, model: AttributionModel): boolean {
  if (candidate.touchedAtMs !== current.touchedAtMs) {
    return model === "last-touch"
      ? candidate.touchedAtMs > current.touchedAtMs
      : candidate.touchedAtMs < current.touchedAtMs;
  }
  if (candidate.kind !== current.kind) {
    return candidate.kind === "click";
  }
  return candidate.touchId < current.touchId;
}

export function selectTouch(
  touches: readonly Touch[],
  installAtMs: number,
  policy: WindowPolicy,
): Selection {
  const eligible: Touch[] = [];
  const rejected: RejectedTouch[] = [];
  for (const touch of touches) {
    const check = checkTouch(touch, installAtMs, policy);
    if (check.code === "in-window") {
      eligible.push(touch);
    } else {
      rejected.push({ touchId: touch.touchId, code: check.code });
    }
  }
  if (eligible.length === 0) {
    return {
      status: "unattributed",
      touch: null,
      eligibleCount: 0,
      rejected,
      detail: `${rejected.length} touch(es) outside the window`,
    };
  }
  let touch = eligible[0] as Touch;
  for (const candidate of eligible) {
    if (isBetter(candidate, touch, policy.model)) {
      touch = candidate;
    }
  }
  return {
    status: "attributed",
    touch: touch ?? null,
    eligibleCount: eligible.length,
    rejected,
    detail: `${policy.model} picked ${touch?.touchId ?? "-"} among ${eligible.length} eligible`,
  };
}

export type EventName = "install" | "activate" | "purchase";

export interface PostbackEvent {
  readonly eventId: string;
  readonly installId: string;
  readonly eventName: EventName;
  readonly valueCents: number;
  readonly receivedAtMs: number;
}

export type DedupeCode = "accepted" | "duplicate" | "conflict";

export interface DedupeResult {
  readonly code: DedupeCode;
  readonly events: readonly PostbackEvent[];
  readonly detail: string;
}

export function dedupePostback(
  seen: readonly PostbackEvent[],
  incoming: PostbackEvent,
): DedupeResult {
  const key = `${incoming.installId}:${incoming.eventId}`;
  const existing = seen.find(
    (event) => `${event.installId}:${event.eventId}` === key,
  );
  if (existing === undefined) {
    return { code: "accepted", events: [...seen, incoming], detail: `${key} accepted` };
  }
  if (existing.eventName === incoming.eventName && existing.valueCents === incoming.valueCents) {
    return { code: "duplicate", events: seen, detail: `${key} already recorded` };
  }
  return {
    code: "conflict",
    events: seen,
    detail: `${key} arrived with a different event name or value`,
  };
}

export type ConsentState = "granted" | "denied" | "unknown";
export type IdState = "available" | "limited" | "unavailable";
export type IdentifierMode = "device-id" | "fingerprint" | "aggregated" | "none";

export interface PrivacyPolicy {
  readonly requireConsent: boolean;
  readonly allowFingerprint: boolean;
  readonly allowAggregated: boolean;
}

export interface IdentifierDecision {
  readonly mode: IdentifierMode;
  readonly allowed: boolean;
  readonly reason: string;
}

export function resolveIdentifier(
  consent: ConsentState,
  ids: IdState,
  policy: PrivacyPolicy,
): IdentifierDecision {
  if (consent === "denied") {
    return { mode: "none", allowed: false, reason: "consent denied" };
  }
  if (policy.requireConsent && consent === "unknown") {
    return policy.allowAggregated
      ? { mode: "aggregated", allowed: true, reason: "consent unknown, aggregated only" }
      : { mode: "none", allowed: false, reason: "consent unknown and aggregation disabled" };
  }
  if (ids === "available") {
    return { mode: "device-id", allowed: true, reason: "device identifier available" };
  }
  if (ids === "limited") {
    if (policy.allowFingerprint) {
      return { mode: "fingerprint", allowed: true, reason: "identifier limited, fingerprint fallback" };
    }
    return policy.allowAggregated
      ? { mode: "aggregated", allowed: true, reason: "identifier limited, aggregated only" }
      : { mode: "none", allowed: false, reason: "identifier limited and fallbacks disabled" };
  }
  return policy.allowAggregated
    ? { mode: "aggregated", allowed: true, reason: "identifier unavailable, aggregated only" }
    : { mode: "none", allowed: false, reason: "identifier unavailable and aggregation disabled" };
}

export function formatSelection(selection: Selection): string {
  const touch = selection.touch;
  if (touch === null) {
    return `unattributed rejected=${selection.rejected.length}`;
  }
  return `${selection.status}:${touch.channel}:${touch.kind} eligible=${selection.eligibleCount}`;
}