@chipmobilesdk/rn-ads 0.1.0 → 0.2.0

package/src/core/adOriginatedReturn.ts

@@ -0,0 +1,134 @@
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * This is the reason app-open belongs in the package rather than in the app.
+ * Every other app-open rule — when to show one, how often, on which screens — is
+ * policy the app owns. This one is not policy; it is a fact only the package
+ * holds. When a user dismisses a full-screen ad, or comes back from a browser an
+ * ad opened, the app sees an ordinary return to the foreground and has no way to
+ * tell it apart from any other. Showing an app-open ad on that return means
+ * showing an ad immediately after an ad, which is both a poor experience and the
+ * kind of thing store review notices.
+ *
+ * The package knows, because it holds the full-screen lock and it sees the click
+ * events. So it refuses, with a reason distinct from `busy` and `not_ready` so
+ * the app can tell what happened.
+ *
+ * **Bounded on both sides, deliberately.** Arming has to be tied to something
+ * that actually happened, and it has to expire:
+ *
+ *   - Armed when the provider reports a full-screen ad opened, or on a click —
+ *     that second case is a browser the ad opened, which is the only signal the
+ *     provider gives for it. Arming is deliberately not tied to the app
+ *     reporting that it went to the background; see `noteFullScreenShown`.
+ *   - Disarmed without firing if the app was away longer than
+ *     `AD_RETURN_MAX_AWAY_MS`. Someone who left, did something else, and came
+ *     back an hour later is not returning from an ad, and treating them as if
+ *     they were would refuse a legitimate show.
+ *   - Refusals last `AD_RETURN_GRACE_MS` after the return, then stop. The window
+ *     only needs to cover the moment right after the return, where an app-open
+ *     show would otherwise fire. A window that outlived that moment would start
+ *     refusing shows that have nothing to do with the ad.
+ *
+ * Three limits are worth stating plainly, because they are limits rather than
+ * defects and the documentation must not imply otherwise:
+ *
+ *   1. It cannot survive process death. If the OS kills the app while an ad is
+ *      on screen, the return is a cold start and nothing links it to the ad.
+ *   2. It depends on the app reporting `setAppActive` faithfully — an obligation
+ *      0.1.0 already imposes for staleness re-evaluation, not a new one.
+ *   3. A browser opened by an ad without a preceding click event is undetectable.
+ *
+ * Pure state. No listener, no timer — it is driven entirely by transitions the
+ * package already observes, which is why `dispose()` has nothing extra to
+ * release for it.
+ */
+
+import { AD_CLICK_WINDOW_MS, AD_RETURN_GRACE_MS, AD_RETURN_MAX_AWAY_MS } from './timers';
+
+export interface AdOriginatedTracker {
+	/** A full-screen ad is on screen, per the provider's own `opened` callback. */
+	noteFullScreenShown(nowMs: number): void;
+	/** Record an ad click — the only signal that an ad opened a browser. */
+	noteClick(nowMs: number): void;
+	/** The app went to the background. Kept for the click case's timing. */
+	noteBackground(nowMs: number): void;
+	/** The app came back. Decides whether this return was ad-originated. */
+	noteForeground(nowMs: number): void;
+	/** Whether an app-open show should be refused right now. */
+	isRefusing(nowMs: number): boolean;
+	/** Drops all state. For dispose, and for tests asserting a clean slate. */
+	reset(): void;
+}
+
+export function createAdOriginatedTracker(): AdOriginatedTracker {
+	let lastClickAtMs: number | null = null;
+	let armedAtMs: number | null = null;
+	let refusalUntilMs: number | null = null;
+
+	return {
+		/**
+		 * Arming happens here — when the provider says an ad is on screen — and
+		 * deliberately **not** when the app reports going to the background.
+		 *
+		 * That was the first design and it does not survive a real device. React
+		 * Native delivers app-state changes over the bridge, and while the app is
+		 * backgrounded its JS thread is throttled, so the `background` event is
+		 * routinely processed only once the app is already returning. By then the
+		 * ad has been dismissed and the full-screen lock released, so sampling the
+		 * lock at that moment reports "no ad was showing" and the return is let
+		 * through — the exact case FR-128 exists to catch. Arming on a fact the
+		 * provider reports, rather than on the timeliness of an event, removes the
+		 * race entirely.
+		 */
+		noteFullScreenShown(nowMs) {
+			armedAtMs = nowMs;
+		},
+
+		noteClick(nowMs) {
+			lastClickAtMs = nowMs;
+			// A click is itself grounds to arm: the ad may be opening a browser,
+			// and if it is, no `opened` callback will follow.
+			armedAtMs = nowMs;
+		},
+
+		noteBackground(nowMs) {
+			// Only meaningful for the browser case, and only as a refinement: a
+			// background that closely follows a click is that browser opening.
+			if (lastClickAtMs !== null && nowMs - lastClickAtMs <= AD_CLICK_WINDOW_MS) {
+				armedAtMs = nowMs;
+			}
+		},
+
+		noteForeground(nowMs) {
+			if (armedAtMs === null) {
+				return;
+			}
+			const away = nowMs - armedAtMs;
+			armedAtMs = null;
+			lastClickAtMs = null;
+			if (away > AD_RETURN_MAX_AWAY_MS) {
+				// Too long to still be attributable to the ad. Not a refusal.
+				return;
+			}
+			refusalUntilMs = nowMs + AD_RETURN_GRACE_MS;
+		},
+
+		isRefusing(nowMs) {
+			if (refusalUntilMs === null) {
+				return false;
+			}
+			if (nowMs >= refusalUntilMs) {
+				refusalUntilMs = null;
+				return false;
+			}
+			return true;
+		},
+
+		reset() {
+			lastClickAtMs = null;
+			armedAtMs = null;
+			refusalUntilMs = null;
+		},
+	};
+}