@amplytools/react-native-amply-sdk 0.4.0 → 0.5.0

package/src/__tests__/campaignResolved.test.ts

@@ -0,0 +1,276 @@
+import * as Amply from '../index';
+import {__setNativeModule} from '../nativeModule';
+
+type CampaignPresentEvent = {
+  url: string;
+  params: Record<string, unknown>;
+  info: Record<string, unknown>;
+  mediationId: string;
+};
+
+// Drains the microtask queue a few times so promise-chained presenter resolutions
+// (sync or async) settle before assertions run.
+async function flushMicrotasks(): Promise<void> {
+  for (let i = 0; i < 5; i++) {
+    await Promise.resolve();
+  }
+}
+
+const mockNativeModule = {
+  initialize: jest.fn(),
+  isInitialized: jest.fn(() => true),
+  track: jest.fn(),
+  trackGated: jest.fn(),
+  resolveCampaign: jest.fn(),
+  getRecentEvents: jest.fn(),
+  getDataSetSnapshot: jest.fn(),
+  registerDeepLinkListener: jest.fn(),
+  registerGate: jest.fn(),
+  addListener: jest.fn(),
+  removeListeners: jest.fn(),
+  onSystemEvent: jest.fn(),
+  onDeepLink: jest.fn(),
+  onCampaignPresent: jest.fn(),
+  setCustomProperties: jest.fn(),
+  getCustomProperty: jest.fn(),
+  removeCustomProperty: jest.fn(),
+  clearCustomProperties: jest.fn(),
+};
+
+describe('Amply gate API (trackGated + registerGate)', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+    Amply.removeAllListeners();
+    __setNativeModule(null);
+  });
+
+  beforeEach(() => {
+    __setNativeModule(mockNativeModule as never);
+  });
+
+  describe('trackEvent (fire-and-forget)', () => {
+    it('forwards to native track and never gates', async () => {
+      await Amply.trackEvent('SaveTapped', {foo: 'bar'});
+
+      expect(mockNativeModule.track).toHaveBeenCalledWith({
+        name: 'SaveTapped',
+        properties: {foo: 'bar'},
+      });
+      expect(mockNativeModule.trackGated).not.toHaveBeenCalled();
+    });
+
+    it('defaults missing properties to an empty object', async () => {
+      await Amply.trackEvent('Ping');
+
+      expect(mockNativeModule.track).toHaveBeenCalledWith({
+        name: 'Ping',
+        properties: {},
+      });
+    });
+  });
+
+  describe('trackGated', () => {
+    it('resolves proceed/completed when the gate is satisfied', async () => {
+      mockNativeModule.trackGated.mockResolvedValueOnce({
+        outcome: 'proceed',
+        reason: 'completed',
+      });
+
+      const decision = await Amply.trackGated('SaveTapped', {foo: 'bar'});
+
+      expect(mockNativeModule.trackGated).toHaveBeenCalledWith('SaveTapped', {
+        foo: 'bar',
+      });
+      expect(decision).toEqual({outcome: 'proceed', reason: 'completed'});
+    });
+
+    it('resolves proceed/failOpen when the native layer reports fail-open', async () => {
+      mockNativeModule.trackGated.mockResolvedValueOnce({
+        outcome: 'proceed',
+        reason: 'failOpen',
+      });
+
+      const decision = await Amply.trackGated('SaveTapped', {});
+
+      expect(decision).toEqual({outcome: 'proceed', reason: 'failOpen'});
+    });
+
+    it('resolves cancelled on a user dismiss under onAbort=cancel', async () => {
+      mockNativeModule.trackGated.mockResolvedValueOnce({outcome: 'cancelled'});
+
+      const decision = await Amply.trackGated('SaveTapped', undefined);
+
+      expect(mockNativeModule.trackGated).toHaveBeenCalledWith('SaveTapped', {});
+      expect(decision).toEqual({outcome: 'cancelled'});
+    });
+
+    it('never rejects — fails open to proceed/failOpen when native rejects', async () => {
+      mockNativeModule.trackGated.mockRejectedValueOnce(new Error('boom'));
+
+      const decision = await Amply.trackGated('SaveTapped', {});
+
+      expect(decision).toEqual({outcome: 'proceed', reason: 'failOpen'});
+    });
+
+    it('fails open on an unexpected/malformed native decision', async () => {
+      mockNativeModule.trackGated.mockResolvedValueOnce({outcome: 'wat'} as never);
+
+      const decision = await Amply.trackGated('SaveTapped', {});
+
+      expect(decision).toEqual({outcome: 'proceed', reason: 'failOpen'});
+    });
+
+    it('normalizes an unknown proceed reason to failOpen', async () => {
+      mockNativeModule.trackGated.mockResolvedValueOnce({
+        outcome: 'proceed',
+        reason: 'something-else',
+      } as never);
+
+      const decision = await Amply.trackGated('SaveTapped', {});
+
+      expect(decision).toEqual({outcome: 'proceed', reason: 'failOpen'});
+    });
+  });
+
+  describe('registerGate', () => {
+    it('registers once on the native module per baseUrl and subscribes to onCampaignPresent', async () => {
+      const remove = jest.fn();
+      mockNativeModule.onCampaignPresent.mockReturnValue({remove});
+
+      const presenter = jest.fn();
+      const unsubscribe = await Amply.registerGate('stillframe://ad', presenter);
+
+      expect(mockNativeModule.registerGate).toHaveBeenCalledTimes(1);
+      expect(mockNativeModule.registerGate).toHaveBeenCalledWith('stillframe://ad', 'cancel', 0);
+      expect(mockNativeModule.onCampaignPresent).toHaveBeenCalledTimes(1);
+
+      // Second registration of the same baseUrl re-subscribes but does NOT re-register.
+      await Amply.registerGate('stillframe://ad', jest.fn());
+      expect(mockNativeModule.registerGate).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      expect(remove).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes through onAbort and timeoutMs options', async () => {
+      mockNativeModule.onCampaignPresent.mockReturnValue({remove: jest.fn()});
+
+      await Amply.registerGate('stillframe://ad', jest.fn(), {
+        onAbort: 'proceed',
+        timeoutMs: 8000,
+      });
+
+      expect(mockNativeModule.registerGate).toHaveBeenCalledWith('stillframe://ad', 'proceed', 8000);
+    });
+
+    it('delivers params + info to the presenter and forwards completed', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation(
+        (listener: (e: CampaignPresentEvent) => void) => {
+          emit = listener;
+          return {remove: jest.fn()};
+        },
+      );
+
+      const presenter = jest.fn(
+        (_params, _info, resolution: Amply.GateResolution) => resolution.completed(),
+      );
+      await Amply.registerGate('stillframe://ad', presenter);
+
+      expect(emit).toBeDefined();
+      emit!({
+        url: 'stillframe://ad?adUnit=rewarded_main',
+        params: {adUnit: 'rewarded_main'},
+        info: {campaignId: 'c1'},
+        mediationId: 'm1',
+      });
+
+      await flushMicrotasks();
+
+      expect(presenter).toHaveBeenCalledWith(
+        {adUnit: 'rewarded_main'},
+        {campaignId: 'c1'},
+        expect.any(Object),
+      );
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m1', 'Completed');
+    });
+
+    it('forwards a dismissed resolution', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation(
+        (listener: (e: CampaignPresentEvent) => void) => {
+          emit = listener;
+          return {remove: jest.fn()};
+        },
+      );
+
+      await Amply.registerGate('stillframe://ad', (_p, _i, resolution) =>
+        resolution.dismissed(),
+      );
+
+      emit!({url: 'stillframe://ad', params: {}, info: {}, mediationId: 'm2'});
+      await flushMicrotasks();
+
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m2', 'Dismissed');
+    });
+
+    it('reports Unavailable (fail-open) when the presenter throws', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation(
+        (listener: (e: CampaignPresentEvent) => void) => {
+          emit = listener;
+          return {remove: jest.fn()};
+        },
+      );
+
+      await Amply.registerGate('stillframe://ad', () => {
+        throw new Error('presenter blew up');
+      });
+
+      emit!({url: 'stillframe://ad', params: {}, info: {}, mediationId: 'm3'});
+      await flushMicrotasks();
+
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m3', 'Unavailable');
+    });
+
+    it('resolves at most once even if the presenter reports twice', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation(
+        (listener: (e: CampaignPresentEvent) => void) => {
+          emit = listener;
+          return {remove: jest.fn()};
+        },
+      );
+
+      await Amply.registerGate('stillframe://ad', (_p, _i, resolution) => {
+        resolution.completed();
+        resolution.dismissed();
+      });
+
+      emit!({url: 'stillframe://ad', params: {}, info: {}, mediationId: 'm4'});
+      await flushMicrotasks();
+
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledTimes(1);
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m4', 'Completed');
+    });
+
+    it('ignores dispatches whose url does not match the registered baseUrl', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation(
+        (listener: (e: CampaignPresentEvent) => void) => {
+          emit = listener;
+          return {remove: jest.fn()};
+        },
+      );
+
+      const presenter = jest.fn();
+      await Amply.registerGate('stillframe://ad', presenter);
+
+      emit!({url: 'other://thing', params: {}, info: {}, mediationId: 'm5'});
+      await flushMicrotasks();
+
+      expect(presenter).not.toHaveBeenCalled();
+      expect(mockNativeModule.resolveCampaign).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/index.ts

@@ -4,18 +4,23 @@ export {useAmplySystemEvents} from './hooks/useAmplySystemEvents';
 export {formatSystemEventLabel} from './systemEventUtils';
 export type {FormatOptions} from './systemEventUtils';
 import type {
+  CampaignResult,
+  GateDecision,
   AmplyInitializationConfig,
   DataSetSnapshot,
   DataSetType,
   DeepLinkEvent,
   EventRecord,
   LogLevel,
+  CampaignPresentEvent,
   TrackEventPayload,
 } from './nativeSpecs/NativeAmplyModule';
 
 let deepLinkRegistered = false;
 let debugLogListenerRegistered = false;
+const registeredGates = new Set<string>();
 const deepLinkSubscriptions = new Set<() => void>();
+const campaignPresenterSubscriptions = new Set<() => void>();
 
 /**
  * Format a debug log entry for console output using new format.
@@ -132,6 +137,185 @@ export async function track(payload: TrackEventPayload): Promise<void> {
   await getNativeModule().track(payload);
 }
 
+/**
+ * Possible results a gate presenter can report. Re-exported from the
+ * native spec for app presenters.
+ */
+export type {CampaignResult, GateDecision};
+
+/**
+ * Outcome of a gate presenter's presentation, reported back via {@link GateResolution}.
+ */
+export type GatePresenterResult = CampaignResult;
+
+/**
+ * Resolution token handed to a {@link GatePresenter}. The presenter MUST report
+ * exactly one terminal result. Convenience helpers map to the underlying
+ * {@link CampaignResult}.
+ */
+export type GateResolution = {
+  /** The gate condition was satisfied (e.g. rewarded ad watched to completion). */
+  completed: () => void;
+  /** The user deliberately dismissed without satisfying the condition. */
+  dismissed: () => void;
+  /** Any non-user failure (no-fill, not-ready, failed-to-show). Fails open. */
+  unavailable: () => void;
+};
+
+/**
+ * A capability presenter for a gate (blocking) action, registered via
+ * {@link registerGate} and keyed by the gate's `baseUrl`. Receives the parsed query
+ * `params`, the enriched `info`, and a {@link GateResolution} token it must resolve
+ * exactly once. Throwing synchronously is treated as `unavailable` (fail-open).
+ */
+export type GatePresenter = (
+  params: Record<string, unknown>,
+  info: Record<string, unknown>,
+  resolution: GateResolution,
+) => void;
+
+/**
+ * Options for {@link registerGate}.
+ */
+export type RegisterGateOptions = {
+  /**
+   * Abort policy when the user dismisses the gate without satisfying it.
+   * - `'cancel'` → {@link trackGated} resolves `{ outcome: 'cancelled' }`.
+   * - `'proceed'` → {@link trackGated} resolves `{ outcome: 'proceed', reason: 'failOpen' }`.
+   * Defaults to `'cancel'`.
+   */
+  onAbort?: 'cancel' | 'proceed';
+  /**
+   * Max time (ms) the gate waits for a presenter result before failing open.
+   * Defaults to the SDK's gate default.
+   */
+  timeoutMs?: number;
+};
+
+/**
+ * Fire-and-forget analytics track. Records the event and lets any matching NORMAL
+ * campaign action dispatch as usual. A gate action matched here will NOT block —
+ * there is no caller to gate. Use {@link trackGated} to await a gate.
+ */
+export async function trackEvent(
+  event: string,
+  properties?: Record<string, unknown> | null,
+): Promise<void> {
+  await getNativeModule().track({name: event, properties: properties ?? {}});
+}
+
+/**
+ * Gated track. Records the event; if a gate action matches AND a presenter is
+ * registered for its `baseUrl`, the SDK dispatches the presentation and awaits its
+ * outcome before resolving:
+ * - `{ outcome: 'proceed', reason: 'completed' }` — the presenter satisfied the gate.
+ * - `{ outcome: 'proceed', reason: 'failOpen' }` — no gate matched, not initialized,
+ *   timeout, unavailable, infra failure, or dismiss under `onAbort=proceed`.
+ * - `{ outcome: 'cancelled' }` — user dismiss under an `onAbort=cancel` gate.
+ *
+ * This NEVER rejects: any infra failure resolves to `{ outcome: 'proceed', reason:
+ * 'failOpen' }` so the caller is never stranded.
+ */
+export async function trackGated(
+  event: string,
+  properties?: Record<string, unknown> | null,
+): Promise<GateDecision> {
+  const props = properties ?? {};
+  try {
+    const decision = (await getNativeModule().trackGated(event, props)) as Partial<GateDecision>;
+    if (decision && decision.outcome === 'cancelled') {
+      return {outcome: 'cancelled'};
+    }
+    if (decision && decision.outcome === 'proceed') {
+      const reason = decision.reason === 'completed' ? 'completed' : 'failOpen';
+      return {outcome: 'proceed', reason};
+    }
+    // Unexpected/malformed payload: fail open.
+    console.warn('[Amply] trackGated returned an unexpected decision; failing open', decision);
+    return {outcome: 'proceed', reason: 'failOpen'};
+  } catch (error) {
+    // Fail open: any bridge/SDK failure must proceed, never strand the caller.
+    console.warn('[Amply] trackGated failed; proceeding (fail-open)', error);
+    return {outcome: 'proceed', reason: 'failOpen'};
+  }
+}
+
+function trackCampaignPresenterSubscription(subscription?: {remove?: () => void}): () => void {
+  let removed = false;
+  const unsubscribe = () => {
+    if (removed) {
+      return;
+    }
+    removed = true;
+    subscription?.remove?.();
+    campaignPresenterSubscriptions.delete(unsubscribe);
+  };
+  campaignPresenterSubscriptions.add(unsubscribe);
+  return unsubscribe;
+}
+
+/**
+ * Register a gate presenter for a gate (blocking) action, keyed by its `baseUrl`.
+ * The presenter is invoked when a matching gate is dispatched; it receives the parsed
+ * query `params`, the enriched `info`, and a {@link GateResolution} it must resolve
+ * exactly once (`completed`/`dismissed`/`unavailable`). The SDK collapses multi-step
+ * ad lifecycles into the single result you report. A synchronous throw → `unavailable`
+ * (fail-open).
+ *
+ * @returns an unsubscribe function.
+ */
+export async function registerGate(
+  baseUrl: string,
+  presenter: GatePresenter,
+  opts?: RegisterGateOptions,
+): Promise<() => void> {
+  const onAbort = opts?.onAbort ?? 'cancel';
+  const timeoutMs = opts?.timeoutMs ?? 0;
+
+  if (!registeredGates.has(baseUrl)) {
+    getNativeModule().registerGate(baseUrl, onAbort, timeoutMs);
+    registeredGates.add(baseUrl);
+  }
+
+  const nativeModule = getNativeModule();
+  const subscription = nativeModule.onCampaignPresent((event: CampaignPresentEvent) => {
+    const {url, params, info, mediationId} = event;
+    // The native side routes by baseUrl, but guard here too in case multiple gates
+    // share the single onCampaignPresent channel.
+    if (baseUrl && url && !url.startsWith(baseUrl)) {
+      return;
+    }
+
+    let settled = false;
+    const report = (result: CampaignResult) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      nativeModule.resolveCampaign(mediationId, result);
+    };
+    const resolution: GateResolution = {
+      completed: () => report('Completed'),
+      dismissed: () => report('Dismissed'),
+      unavailable: () => report('Unavailable'),
+    };
+
+    try {
+      presenter(
+        (params ?? {}) as Record<string, unknown>,
+        info as Record<string, unknown>,
+        resolution,
+      );
+    } catch (error) {
+      // Presenter failure is an infra failure, never a user dismiss → Unavailable.
+      console.warn('[Amply] gate presenter threw; reporting Unavailable (fail-open)', error);
+      report('Unavailable');
+    }
+  });
+
+  return trackCampaignPresenterSubscription(subscription);
+}
+
 export async function getRecentEvents(limit: number): Promise<EventRecord[]> {
   return getNativeModule().getRecentEvents(limit);
 }
@@ -211,6 +395,16 @@ export function removeAllListeners(): void {
     }
   });
   deepLinkSubscriptions.clear();
+
+  campaignPresenterSubscriptions.forEach(unsubscribe => {
+    try {
+      unsubscribe();
+    } catch (error) {
+      console.warn('[Amply] Failed to remove gate presenter', error);
+    }
+  });
+  campaignPresenterSubscriptions.clear();
+  registeredGates.clear();
 }
 
 export type {
@@ -220,6 +414,7 @@ export type {
   DeepLinkEvent,
   EventRecord,
   LogLevel,
+  CampaignPresentEvent,
   TrackEventPayload,
 };
 
@@ -237,6 +432,9 @@ export default {
   initialize,
   isInitialized,
   track,
+  trackEvent,
+  trackGated,
+  registerGate,
   getRecentEvents,
   getDataSetSnapshot,
   addDeepLinkListener,

package/src/nativeSpecs/NativeAmplyModule.ts

@@ -84,10 +84,91 @@ export type DeepLinkEvent = {
   consumed: boolean;
 };
 
+/**
+ * Terminal result reported by a gate presenter back to the SDK.
+ *
+ * - 'Completed': the presenter satisfied the gate condition (e.g. rewarded ad
+ *   watched to completion). The gate proceeds with reason `completed`.
+ * - 'Dismissed': a USER-INITIATED dismiss without satisfying the condition. With an
+ *   `onAbort=cancel` gate this cancels; with `onAbort=proceed` it proceeds. Reserved
+ *   strictly for user intent — never infra failures.
+ * - 'Unavailable': any non-user failure (no-fill, failed-to-show, not-ready, missing
+ *   precondition). Always fails open and proceeds with reason `failOpen`.
+ *
+ * NOTE: this raw result is intentionally NOT surfaced to app gating code — the public
+ * `trackGated` surface only ever sees the collapsed {@link GateDecision}.
+ */
+export type CampaignResult = 'Completed' | 'Dismissed' | 'Unavailable';
+
+/**
+ * Bridge-level gate decision, mirroring the KMP `GateDecision`:
+ * - `{ outcome: 'proceed', reason: 'completed' | 'failOpen' }` — the gate cleared.
+ *   `completed` means the presenter satisfied the condition; `failOpen` means any
+ *   infra/timeout/not-ready/dismiss-under-proceed path resolved permissively.
+ * - `{ outcome: 'cancelled' }` — a deliberate user dismiss under an `onAbort=cancel`
+ *   gate. The caller should suppress its follow-up action.
+ *
+ * The raw {@link CampaignResult} is never surfaced here; it is collapsed natively.
+ */
+export type GateDecision =
+  | {outcome: 'proceed'; reason: 'completed' | 'failOpen'}
+  | {outcome: 'cancelled'};
+
+/**
+ * Payload delivered to JS when a gate dispatches its (blocking) presentation.
+ * The JS handler must eventually report a {@link CampaignResult} for `mediationId`
+ * via `resolveCampaign`.
+ */
+export type CampaignPresentEvent = {
+  url: string;
+  /**
+   * Parsed query parameters from the gate action URL — a flat string map decoded
+   * from the URL query string (e.g. `{ adUnit: 'rewarded_main', placement: 'home' }`).
+   */
+  params: JsonMap;
+  /**
+   * Enriched, decoupled action info:
+   * `{ url, campaignId, campaignName, triggeringEvent, triggeringProperties, content }`.
+   */
+  info: JsonMap;
+  mediationId: string;
+};
+
 export interface Spec extends TurboModule {
   initialize(config: AmplyInitializationConfig): Promise<void>;
   isInitialized(): boolean;
   track(payload: TrackEventPayload): Promise<void>;
+  /**
+   * Gated form of track: records the event, evaluates campaigns, and — if a gate
+   * action matches and a presenter is registered — dispatches the gate presentation
+   * and awaits its outcome. Resolves with the collapsed {@link GateDecision} as a
+   * plain map:
+   * - `{ outcome: 'proceed', reason: 'completed' }` — gate satisfied.
+   * - `{ outcome: 'proceed', reason: 'failOpen' }` — any permissive path (no gate,
+   *   not initialized, timeout, unavailable, dismiss under `onAbort=proceed`, infra
+   *   failure).
+   * - `{ outcome: 'cancelled' }` — user dismiss under an `onAbort=cancel` gate.
+   *
+   * The raw {@link CampaignResult} is never returned to JS; it is collapsed natively.
+   * This promise MUST NOT reject — every failure path resolves to a `proceed`/failOpen.
+   */
+  trackGated(event: string, properties: JsonMap): Promise<JsonMap>;
+  /**
+   * Report the terminal result of a gate presentation dispatched to JS via the
+   * `onCampaignPresent` event. Idempotent natively — late/duplicate calls are ignored.
+   * @param mediationId The id carried by the matching `onCampaignPresent` event.
+   * @param result One of {@link CampaignResult} ('Completed' | 'Dismissed' | 'Unavailable').
+   */
+  resolveCampaign(mediationId: string, result: string): void;
+  /**
+   * Register the JS side as the recipient of gate presentation dispatches for the
+   * given `baseUrl`. The native side wires the gate; JS receives each dispatch via
+   * the `onCampaignPresent` event and replies through `resolveCampaign`.
+   * @param baseUrl The gate action base URL this presenter handles.
+   * @param onAbort Abort policy: 'cancel' (user dismiss cancels) or 'proceed'.
+   * @param timeoutMs Max time the gate waits for a presenter result before failing open.
+   */
+  registerGate(baseUrl: string, onAbort: string, timeoutMs: number): void;
   getRecentEvents(limit: number): Promise<EventRecord[]>;
   getDataSetSnapshot(type: DataSetType): Promise<DataSetSnapshot>;
   registerDeepLinkListener(): void;
@@ -128,6 +209,7 @@ export interface Spec extends TurboModule {
   clearCustomProperties(): void;
   readonly onSystemEvent: EventEmitter<SystemEventPayload>;
   readonly onDeepLink: EventEmitter<DeepLinkEvent>;
+  readonly onCampaignPresent: EventEmitter<CampaignPresentEvent>;
   addListener(eventName: string): void;
   removeListeners(count: number): void;
 }