Auto-Throttling AdMob When Crash Rates Spike: A Revenue-Protecting Brake Architecture with Rork, Firebase Remote Config, and Crashlytics

import FirebaseCrashlytics
import FirebaseAnalytics
 
@MainActor
final class StabilityReporter {
    static let shared = StabilityReporter()
    private let queue = DispatchQueue(label: "stability.reporter", qos: .utility)
 
    func reportSessionStart() {
        Analytics.logEvent("app_session_start", parameters: [
            "build": Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "0",
            "os": UIDevice.current.systemVersion,
            "device": ProcessInfo.processInfo.machineHardwareName,
            "ts": Date().timeIntervalSince1970
        ])
    }
 
    func reportSoftError(_ error: Error, severity: String = "warning") {
        // Pattern: log non-fatals to Crashlytics AND mirror an event
        // to Analytics so you can query by time window later.
        Crashlytics.crashlytics().record(error: error)
        Analytics.logEvent("soft_error", parameters: [
            "severity": severity,
            "domain": (error as NSError).domain,
            "code": (error as NSError).code,
            "ts": Date().timeIntervalSince1970
        ])
    }
 
    func reportAdEvent(unit: String, event: String, errorCode: Int? = nil) {
        // Keeping ad-related events on a separate Analytics channel
        // lets you isolate ad-SDK origin from app-origin crashes
        // when you are triaging an incident.
        var params: [String: Any] = [
            "unit": unit,
            "event": event,
            "ts": Date().timeIntervalSince1970
        ]
        if let code = errorCode { params["error_code"] = code }
        Analytics.logEvent("ad_event", parameters: params)
    }
}

import * as functions from "firebase-functions";
import { BigQuery } from "@google-cloud/bigquery";
import { getRemoteConfig } from "firebase-admin/remote-config";
 
interface WindowStats {
  windowSec: number;
  sessions: number;
  crashes: number;
  crashFreeRate: number;
}
 
const WINDOWS = [60, 600, 3600]; // 1 min / 10 min / 60 min
const bq = new BigQuery();
 
async function fetchWindow(seconds: number): Promise<WindowStats> {
  const [job] = await bq.createQueryJob({
    query: `
      SELECT
        COUNTIF(event_name = 'app_session_start') AS sessions,
        COUNTIF(event_name = 'app_exception') AS crashes
      FROM \`my-app.analytics_XXX.events_*\`
      WHERE _TABLE_SUFFIX BETWEEN
        FORMAT_DATE('%Y%m%d', CURRENT_DATE())
        AND FORMAT_DATE('%Y%m%d', CURRENT_DATE())
        AND event_timestamp >= UNIX_MICROS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @sec SECOND))
    `,
    params: { sec: seconds }
  });
  const [rows] = await job.getQueryResults();
  const sessions = Number(rows[0].sessions ?? 0);
  const crashes = Number(rows[0].crashes ?? 0);
  const rate = sessions > 0 ? (sessions - crashes) / sessions : 1.0;
  return { windowSec: seconds, sessions, crashes, crashFreeRate: rate };
}
 
function decideState(stats: WindowStats[]): "Normal" | "Caution" | "Throttle" | "Halt" {
  const w1 = stats.find(s => s.windowSec === 60)!;
  const w10 = stats.find(s => s.windowSec === 600)!;
  const w60 = stats.find(s => s.windowSec === 3600)!;
 
  // Halt: 20+ crashes in 1 minute, or 60-minute average dips below 96%
  if (w1.crashes >= 20 || w60.crashFreeRate < 0.96) return "Halt";
  // Throttle: 10-minute average drops under 99%
  if (w10.crashFreeRate < 0.99) return "Throttle";
  // Caution: 60-minute average drops under 99.7%
  if (w60.crashFreeRate < 0.997) return "Caution";
  return "Normal";
}
 
export const adThrottleEvaluator = functions.pubsub
  .schedule("every 2 minutes")
  .onRun(async () => {
    const stats = await Promise.all(WINDOWS.map(fetchWindow));
    const next = decideState(stats);
 
    const rc = getRemoteConfig();
    const template = await rc.getTemplate();
    const current = (template.parameters.ad_throttle_state?.defaultValue as any)?.value ?? "Normal";
 
    // Hysteresis: only step one level at a time
    const order = ["Normal", "Caution", "Throttle", "Halt"];
    const curIdx = order.indexOf(current);
    const nextIdx = order.indexOf(next);
    const decided = order[Math.max(0, Math.min(order.length - 1,
      nextIdx > curIdx ? curIdx + 1 : nextIdx < curIdx ? curIdx - 1 : curIdx))];
 
    if (decided !== current) {
      template.parameters.ad_throttle_state = {
        defaultValue: { value: decided },
        description: `auto: stats=${JSON.stringify(stats)}`
      };
      await rc.publishTemplate(template);
      console.log(`State transition: ${current} -> ${decided}`);
    }
  });

import FirebaseRemoteConfig
 
final class AdThrottleStateProvider {
    static let shared = AdThrottleStateProvider()
    private let rc = RemoteConfig.remoteConfig()
 
    init() {
        let settings = RemoteConfigSettings()
        settings.minimumFetchInterval = 300 // 5 minutes
        settings.fetchTimeout = 8           // 8 seconds: longer hurts UX, shorter increases failure rate
        rc.configSettings = settings
        // Pattern: default new installs to Caution, not Normal
        rc.setDefaults(["ad_throttle_state": "Caution" as NSObject])
    }
 
    func currentState() -> ThrottleState {
        let raw = rc.configValue(forKey: "ad_throttle_state").stringValue ?? "Caution"
        return ThrottleState(rawValue: raw) ?? .caution
    }
 
    func refresh() async {
        do {
            _ = try await rc.fetchAndActivate()
        } catch {
            // On failure, hold the existing value; report as non-fatal info
            StabilityReporter.shared.reportSoftError(error, severity: "info")
        }
    }
}
 
enum ThrottleState: String {
    case normal = "Normal"
    case caution = "Caution"
    case throttle = "Throttle"
    case halt = "Halt"
}

import GoogleMobileAds
 
@MainActor
final class AdServingGate {
    static let shared = AdServingGate()
    private var localFailureCount = 0
    private var localFailureWindow: Date = Date()
 
    func shouldServeInterstitial() -> Bool {
        let state = effectiveState()
        switch state {
        case .normal: return true
        case .caution:
            // 50% reduction with deterministic per-user sampling
            return abs(userBucket()) % 2 == 0
        case .throttle, .halt:
            return false
        }
    }
 
    func shouldServeBanner() -> Bool {
        let state = effectiveState()
        return state != .halt
    }
 
    func shouldServeRewarded(isUserInitiated: Bool) -> Bool {
        let state = effectiveState()
        if state == .halt { return false }
        if state == .throttle { return isUserInitiated }
        return true
    }
 
    /// Combine the Remote Config state with the local failsafe
    private func effectiveState() -> ThrottleState {
        let remote = AdThrottleStateProvider.shared.currentState()
        // 3+ ad errors in the last 5 minutes -> downgrade to at least Caution
        let now = Date()
        if now.timeIntervalSince(localFailureWindow) > 300 {
            localFailureCount = 0
            localFailureWindow = now
        }
        let localGuard: ThrottleState = localFailureCount >= 3 ? .caution : .normal
        let order: [ThrottleState] = [.normal, .caution, .throttle, .halt]
        return order[max(order.firstIndex(of: remote)!, order.firstIndex(of: localGuard)!)]
    }
 
    func recordAdLoadFailure() {
        let now = Date()
        if now.timeIntervalSince(localFailureWindow) > 300 {
            localFailureCount = 0
            localFailureWindow = now
        }
        localFailureCount += 1
    }
 
    private func userBucket() -> Int {
        // Hash a stable user ID for deterministic sampling
        let uid = UserDefaults.standard.string(forKey: "stable_user_id") ?? ""
        return uid.hashValue
    }
}