My App Open Ad Only Showed When the App Came Back From Background. The 'Returned to Foreground' Signal Fired Before the Ad Had Loaded

// app-open-gate.test.ts: run with `node --test app-open-gate.test.ts`
import { test } from "node:test";
import assert from "node:assert/strict";
import { AppOpenGate, COOLDOWN_MS, OPPORTUNITY_WINDOW_MS } from "./app-open-gate.ts";
 
function setup() {
  let t = 0;
  let shown = 0;
  const gate = new AppOpenGate(() => { shown += 1; }, () => t);
  return { gate, advance: (ms: number) => { t += ms; }, shown: () => shown };
}
 
// Reproduction of the old logic: decide only on the "returned to foreground" signal
class NaiveGate {
  loaded = false;
  shown = 0;
  onLoaded() { this.loaded = true; }
  onReturn() { if (this.loaded) { this.shown += 1; this.loaded = false; } }
}
 
test("old logic: the ad loads right after launch, but no return signal ever comes, so it never shows", () => {
  const naive = new NaiveGate();
  naive.onLoaded(); // loaded 1.2 s after launch; the return signal has never fired
  assert.equal(naive.shown, 0);
});
 
test("if loading finishes inside the launch window, it shows exactly once", () => {
  const { gate, advance, shown } = setup();
  advance(1_200);
  gate.onLoaded();
  gate.tick();
  assert.equal(shown(), 1);
});
 
test("if loading misses the window, it is skipped for this launch and never pops up later", () => {
  const { gate, advance, shown } = setup();
  advance(OPPORTUNITY_WINDOW_MS + 1);
  gate.onLoaded();
  advance(60_000);
  gate.tick();
  assert.equal(shown(), 0);
});
 
test("an ad that finishes loading mid-session does not show (there is no return to hang it on)", () => {
  const { gate, advance, shown } = setup();
  advance(OPPORTUNITY_WINDOW_MS + 1);
  gate.tick(); // the launch opportunity has expired
  advance(120_000);
  gate.onLoaded();
  assert.equal(shown(), 0);
});
 
test("returning from background shows a ready ad, but not inside the cooldown", () => {
  const { gate, advance, shown } = setup();
  advance(1_000);
  gate.onLoaded(); // first ad, at launch
  assert.equal(shown(), 1);
  gate.onClosed();
 
  advance(10_000);
  gate.onForeground(false);
  advance(5_000);
  gate.onLoaded(); // the ad reloaded after closing
  gate.onForeground(true); // a return inside the cooldown
  assert.equal(shown(), 1);
 
  advance(COOLDOWN_MS);
  gate.onForeground(false);
  gate.onForeground(true); // a return after the cooldown
  assert.equal(shown(), 2);
});
 
test("it also shows when loading finishes one second after the return", () => {
  const { gate, advance, shown } = setup();
  advance(OPPORTUNITY_WINDOW_MS + 1);
  gate.tick();
  advance(300_000);
  gate.onForeground(false);
  gate.onForeground(true);
  advance(1_000);
  gate.onLoaded();
  assert.equal(shown(), 1);
});
 
test("when launched in the background, it waits until the app comes to the front", () => {
  const { gate, advance, shown } = setup();
  gate.onForeground(false); // launched in the background
  gate.onLoaded();
  advance(30_000);
  gate.tick();
  assert.equal(shown(), 0);
  gate.onForeground(true);
  assert.equal(shown(), 1);
});

// startAppOpenAd.ts: a sketch of the wiring, assuming AppOpenAd from react-native-google-mobile-ads.
import { AppState } from "react-native";
import { AdEventType, AppOpenAd, TestIds } from "react-native-google-mobile-ads";
import { AppOpenGate } from "./app-open-gate";
 
// Always use the test unit while developing. Pass the production ID in through an environment variable.
const UNIT_ID = __DEV__
  ? TestIds.APP_OPEN
  : (process.env.EXPO_PUBLIC_APP_OPEN_UNIT_ID ?? "YOUR_APP_OPEN_UNIT_ID");
 
let ad = AppOpenAd.createForAdRequest(UNIT_ID);
let needsReload = false; // did the previous load fail?
const gate = new AppOpenGate(() => ad.show());
 
function load(): void {
  ad = AppOpenAd.createForAdRequest(UNIT_ID);
  ad.addAdEventListener(AdEventType.LOADED, () => gate.onLoaded());
  ad.addAdEventListener(AdEventType.CLOSED, () => {
    gate.onClosed();
    load(); // ads are single-use; prepare the next one as soon as this one closes
  });
  ad.addAdEventListener(AdEventType.ERROR, () => {
    gate.onClosed();
    needsReload = true; // don't retry on the spot; waiting for the next return avoids a retry loop on a bad connection
  });
  ad.load();
}
 
export function startAppOpenAd(): () => void {
  gate.onForeground(AppState.currentState === "active"); // if launched in the background, wait until it comes to the front
  load();
 
  const sub = AppState.addEventListener("change", (state) => {
    gate.onForeground(state === "active");
    if (state === "active" && needsReload) {
      needsReload = false;
      load();
    }
  });
  const timer = setInterval(() => gate.tick(), 1_000); // lets an untouched opportunity expire
 
  return () => {
    sub.remove();
    clearInterval(timer);
  };
}

// launch-trace.ts: log the launch order with elapsed time since launch
const t0 = performance.now();
 
export function trace(label: string): void {
  console.log(`[launch +${Math.round(performance.now() - t0)}ms] ${label}`);
}
 
// Where to call it:
//   trace("came to front")        <- right after you subscribe to AppState, with the current state
//   trace("ad load started")      <- just before ad.load()
//   trace("ad load finished")     <- inside the LOADED listener
//   trace("ad shown")             <- just before show() (add whether it was launch or return)