@chipmobilesdk/rn-ads 0.5.0 → 0.6.0

package/src/react/AdsProvider.tsx

@@ -1,57 +1,56 @@
-/**
- * Instance context (US1).
- *
- * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
- * it without every screen threading it through props.
- *
- * The provider does not create the instance. The app does, and passes it in —
- * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
- * throw during render is a far worse place to discover that than a throw at
- * startup where the app can decide what to do about it.
- */
-
-import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
-import { AppState, type AppStateStatus } from 'react-native';
-
-import type { AdsInstance } from '../core/adsInstance';
-
-const AdsContext = createContext<AdsInstance | null>(null);
-
-export interface AdsProviderProps {
-	readonly instance: AdsInstance;
-	/**
-	 * Whether the provider forwards foreground/background transitions to the
-	 * instance. On by default: FR-034's "never show while inactive" and
-	 * "re-evaluate a stale ad on return" both depend on the instance being told.
-	 * Turn it off only when the app already drives `setAppActive` itself.
-	 */
-	readonly trackAppState?: boolean;
-	readonly children: ReactNode;
-}
-
-export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
-	useEffect(() => {
-		if (!trackAppState) {
-			return;
-		}
-		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
-			instance.setAppActive(status === 'active');
-		});
-		return () => {
-			subscription.remove();
-		};
-	}, [instance, trackAppState]);
-
-	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
-}
-
-/**
- * Returns the instance, or null outside a provider.
- *
- * Null rather than a throw on purpose: a screen that renders a banner should
- * degrade to rendering nothing when ads are not wired up, not take the screen
- * down with it (NFR-005).
- */
-export function useAds(): AdsInstance | null {
-	return useContext(AdsContext);
-}
+/**
+ * Instance context (US1).
+ *
+ * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
+ * it without every screen threading it through props.
+ *
+ * The provider does not create the instance. The app does, and passes it in —
+ * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
+ * throw during render is a far worse place to discover that than a throw at
+ * startup where the app can decide what to do about it.
+ */
+
+import { appLifecycle } from '@chipmobilesdk/rn-core';
+import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
+
+import type { AdsInstance } from '../core/adsInstance';
+
+const AdsContext = createContext<AdsInstance | null>(null);
+
+export interface AdsProviderProps {
+	readonly instance: AdsInstance;
+	/**
+	 * Whether the provider forwards foreground/background transitions to the
+	 * instance. On by default: FR-034's "never show while inactive" and
+	 * "re-evaluate a stale ad on return" both depend on the instance being told.
+	 * Turn it off only when the app already drives `setAppActive` itself. The
+	 * transitions come from rn-core's shared `appLifecycle()`; `inactive` counts as
+	 * not active.
+	 */
+	readonly trackAppState?: boolean;
+	readonly children: ReactNode;
+}
+
+export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
+	useEffect(() => {
+		if (!trackAppState) {
+			return;
+		}
+		return appLifecycle().subscribe(state => {
+			instance.setAppActive(state === 'active');
+		});
+	}, [instance, trackAppState]);
+
+	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
+}
+
+/**
+ * Returns the instance, or null outside a provider.
+ *
+ * Null rather than a throw on purpose: a screen that renders a banner should
+ * degrade to rendering nothing when ads are not wired up, not take the screen
+ * down with it (NFR-005).
+ */
+export function useAds(): AdsInstance | null {
+	return useContext(AdsContext);
+}

package/src/react/hooks.ts

@@ -1,75 +1,70 @@
-/**
- * React bindings (US1, FR-027).
- *
- * Each hook subscribes to exactly what it reads. `usePlacementState` subscribes
- * to one placement rather than to the whole event stream, which is what keeps a
- * banner from re-rendering because an unrelated interstitial was clicked —
- * PERF-002's bounded re-render assertion depends on it.
- *
- * None of these hand back an ad object. A consumer queries and subscribes to
- * state; it never holds provider-owned memory (FR-027).
- */
-
-import { useEffect, useState } from 'react';
-
-import type { InitStatus, PlacementState } from '../config/types';
-import type { AdEventListener } from '../diagnostics/events';
-import { useAds } from './AdsProvider';
-
-/** Live state for one placement. `unavailable` outside a provider. */
-export function usePlacementState(placementKey: string): PlacementState {
-	const ads = useAds();
-	const [state, setState] = useState<PlacementState>(() =>
-		ads ? ads.getPlacementState(placementKey) : 'unavailable',
-	);
-
-	useEffect(() => {
-		if (!ads) {
-			setState('unavailable');
-			return;
-		}
-		// Re-read on subscribe: the state may have moved between the initial
-		// render and this effect, and dropping that transition would leave the
-		// UI showing a state the instance has already left.
-		setState(ads.getPlacementState(placementKey));
-		return ads.subscribePlacement(placementKey, setState);
-	}, [ads, placementKey]);
-
-	return state;
-}
-
-/** Live initialization status. `unavailable` outside a provider. */
-export function useAdsStatus(): InitStatus {
-	const ads = useAds();
-	const [status, setStatus] = useState<InitStatus>(() => (ads ? ads.getStatus() : 'unavailable'));
-
-	useEffect(() => {
-		if (!ads) {
-			setStatus('unavailable');
-			return;
-		}
-		setStatus(ads.getStatus());
-		return ads.subscribeStatus(setStatus);
-	}, [ads]);
-
-	return status;
-}
-
-/**
- * Forwards every event to a listener without causing a render.
- *
- * Deliberately does not accumulate events into state: a package that kept an
- * event log would be persisting exactly the kind of history it promises not to
- * (FR-021), and re-rendering on every impression would defeat PERF-002. A screen
- * that wants a visible log keeps its own.
- */
-export function useAdsEvents(listener: AdEventListener): void {
-	const ads = useAds();
-
-	useEffect(() => {
-		if (!ads) {
-			return;
-		}
-		return ads.subscribeEvents(listener);
-	}, [ads, listener]);
-}
+/**
+ * React bindings (US1, FR-027).
+ *
+ * Each hook subscribes to exactly what it reads. `usePlacementState` subscribes
+ * to one placement rather than to the whole event stream, which is what keeps a
+ * banner from re-rendering because an unrelated interstitial was clicked —
+ * PERF-002's bounded re-render assertion depends on it.
+ *
+ * None of these hand back an ad object. A consumer queries and subscribes to
+ * state; it never holds provider-owned memory (FR-027).
+ */
+
+import { useExternalStore, useLatestCallback } from '@chipmobilesdk/rn-core/react';
+import { useCallback, useEffect } from 'react';
+
+import type { InitStatus, PlacementState } from '../config/types';
+import type { AdEventListener } from '../diagnostics/events';
+import { useAds } from './AdsProvider';
+
+/** Live state for one placement. `unavailable` outside a provider. */
+export function usePlacementState(placementKey: string): PlacementState {
+	const ads = useAds();
+	const subscribe = useCallback(
+		(listener: () => void) =>
+			ads ? ads.subscribePlacement(placementKey, listener) : NO_SUBSCRIPTION,
+		[ads, placementKey],
+	);
+	const getSnapshot = useCallback(
+		(): PlacementState => (ads ? ads.getPlacementState(placementKey) : 'unavailable'),
+		[ads, placementKey],
+	);
+	// useSyncExternalStore: tear-free, and no transition lost between render and
+	// subscription, which the useState copy had to re-read to avoid.
+	return useExternalStore(subscribe, getSnapshot);
+}
+
+/** Live initialization status. `unavailable` outside a provider. */
+export function useAdsStatus(): InitStatus {
+	const ads = useAds();
+	const subscribe = useCallback(
+		(listener: () => void) => (ads ? ads.subscribeStatus(listener) : NO_SUBSCRIPTION),
+		[ads],
+	);
+	const getSnapshot = useCallback((): InitStatus => (ads ? ads.getStatus() : 'unavailable'), [ads]);
+	return useExternalStore(subscribe, getSnapshot);
+}
+
+const NO_SUBSCRIPTION = (): void => undefined;
+
+/**
+ * Forwards every event to a listener without causing a render.
+ *
+ * Deliberately does not accumulate events into state: a package that kept an
+ * event log would be persisting exactly the kind of history it promises not to
+ * (FR-021), and re-rendering on every impression would defeat PERF-002. A screen
+ * that wants a visible log keeps its own.
+ */
+export function useAdsEvents(listener: AdEventListener): void {
+	const ads = useAds();
+	// An inline listener is a new function every render; subscribing through the
+	// latest one keeps a single subscription per instance (PERF-13).
+	const latest = useLatestCallback(listener);
+
+	useEffect(() => {
+		if (!ads) {
+			return;
+		}
+		return ads.subscribeEvents(latest);
+	}, [ads, latest]);
+}

package/src/testing/conformance.ts

@@ -0,0 +1,112 @@
+/**
+ * What any `AdsEngine` must do (IOS-12, ADS-13).
+ *
+ * The same checks run against the fake engine and against the AdMob adapter over
+ * the provider mock (or the real provider, from a demo screen on a device), so a
+ * test that drives the fake proves something about the device path. The subject
+ * says how the provider delivers its callbacks; the checks only use the port.
+ */
+import {
+	ensure,
+	runChecks,
+	type Check,
+	type ConformanceReport,
+} from '@chipmobilesdk/rn-core/testing';
+
+import type { Reward } from '../config/types';
+import type { AdsEngine, EngineAdEvent, EngineAdHandle } from '../engine/port';
+
+export interface AdsEngineSubject {
+	readonly engine: AdsEngine;
+	/** The provider finishes loading the ad behind `handle`. */
+	deliverLoad(handle: EngineAdHandle): void;
+	/** The provider grants a reward for the ad behind `handle`. */
+	deliverReward(handle: EngineAdHandle, reward: Reward): void;
+	/** The user closes the ad behind `handle`. */
+	deliverDismiss(handle: EngineAdHandle): void;
+}
+
+export interface AdsEngineHarness {
+	create(): AdsEngineSubject;
+}
+
+/** Lets callbacks a provider delivers on a later microtask arrive. */
+async function settle(): Promise<void> {
+	for (let turn = 0; turn < 3; turn += 1) {
+		await Promise.resolve();
+	}
+}
+
+export const adsEngineChecks: readonly Check<AdsEngineHarness>[] = [
+	{
+		name: 'is available, and initializes with privacy applied',
+		async run(harness) {
+			const { engine } = harness.create();
+			ensure(engine.isAvailable(), 'reported unavailable');
+			await engine.initialize({ childDirected: true, maxAdContentRating: 'G' });
+		},
+	},
+	{
+		name: 'delivers loaded to a subscriber of an interstitial, and nothing after unsubscribing',
+		async run(harness) {
+			const subject = harness.create();
+			const handle = await subject.engine.createFullScreen('interstitial', 'conformance/1');
+			ensure(typeof handle.id === 'string' && handle.id !== '', 'handle has no id');
+			const seen: EngineAdEvent['type'][] = [];
+			const stop = subject.engine.subscribe(handle, event => seen.push(event.type));
+			subject.deliverLoad(handle);
+			await settle();
+			ensure(seen.join(',') === 'loaded', `subscriber saw ${seen.join(',') || 'nothing'}`);
+			stop();
+			stop();
+			subject.deliverDismiss(handle);
+			await settle();
+			ensure(seen.length === 1, `notified after unsubscribing: ${seen.join(',')}`);
+		},
+	},
+	{
+		name: 'delivers the reward and the dismissal of a rewarded ad',
+		async run(harness) {
+			const subject = harness.create();
+			const handle = await subject.engine.createFullScreen('rewarded', 'conformance/2', {
+				personalizedAds: false,
+			});
+			const seen: EngineAdEvent[] = [];
+			subject.engine.subscribe(handle, event => seen.push(event));
+			subject.deliverLoad(handle);
+			await settle();
+			subject.deliverReward(handle, { type: 'coins', amount: 5 });
+			subject.deliverDismiss(handle);
+			await settle();
+			const reward = seen.find(event => event.type === 'rewarded');
+			ensure(reward?.type === 'rewarded', `no reward among ${seen.map(e => e.type).join(',')}`);
+			ensure(
+				reward.reward.type === 'coins' && reward.reward.amount === 5,
+				`reward ${JSON.stringify(reward.reward)}`,
+			);
+			ensure(seen.at(-1)?.type === 'dismissed', `last event ${seen.at(-1)?.type}`);
+		},
+	},
+	{
+		name: 'gives every ad its own handle',
+		async run(harness) {
+			const { engine } = harness.create();
+			const first = await engine.createFullScreen('interstitial', 'conformance/1');
+			const second = await engine.createFullScreen('interstitial', 'conformance/1');
+			ensure(first.id !== second.id, 'two ads share a handle');
+		},
+	},
+	{
+		name: 'disposes safely twice',
+		async run(harness) {
+			const { engine } = harness.create();
+			const handle = await engine.createFullScreen('interstitial', 'conformance/1');
+			engine.dispose(handle);
+			engine.dispose(handle);
+		},
+	},
+];
+
+export function runAdsEngineConformance(harness: AdsEngineHarness): Promise<ConformanceReport> {
+	return runChecks(() => harness, adsEngineChecks);
+}