@amplytools/react-native-amply-sdk 0.3.0 → 0.4.1

package/ios/Sources/AmplyReactNative/AmplyModule.mm

@@ -44,14 +44,29 @@ static NSString* AmplyLogLevelToString(AmplyLogLevel level) {
     return @"none";
 }
 
-@interface Amply : NativeAmplyModuleSpecBase <NativeAmplyModuleSpec, ASDKDeepLinkListener, ASDKSystemEventsListener, ASDKLogListener>
+// Maps a JS-reported result string to the KMP CampaignResult enum. Strict semantics:
+// anything other than a deliberate user "Dismissed" or explicit "Completed" fails open
+// to Unavailable (proceed) — never strand the continuation on a malformed value.
+static ASDKCampaignResult* AmplyCampaignResultFromString(NSString *result) {
+    if ([result isEqualToString:@"Completed"]) return ASDKCampaignResult.completed;
+    if ([result isEqualToString:@"Dismissed"]) return ASDKCampaignResult.dismissed;
+    if ([result isEqualToString:@"Unavailable"]) return ASDKCampaignResult.unavailable;
+    RCTLogWarn(@"[AmplyReactNative] Unknown campaign result '%@'; treating as Unavailable (fail-open)", result);
+    return ASDKCampaignResult.unavailable;
+}
+
+@interface Amply : NativeAmplyModuleSpecBase <NativeAmplyModuleSpec, ASDKDeepLinkListener, ASDKCampaignPresenter, ASDKSystemEventsListener, ASDKLogListener>
 @property (nonatomic, strong) ASDKAmply *amplyInstance;
 @property (nonatomic, assign) BOOL deepLinkListenerRegistered;
+@property (nonatomic, assign) BOOL campaignPresenterRegistered;
 @property (nonatomic, assign) BOOL systemEventsListenerRegistered;
 @property (nonatomic, assign) BOOL lifecycleObserversRegistered;
 @property (nonatomic, assign) BOOL logListenerRegistered;
 @property (nonatomic, assign) AmplyLogLevel currentLogLevel;
 @property (nonatomic, strong) NSMutableArray<void (^)(ASDKAmply *)> *pendingPropertyOps;
+// Maps a bridge-minted mediationId -> the KMP CampaignResolution token awaiting an
+// outcome from JS. Guarded by @synchronized(self.pendingCompletions).
+@property (nonatomic, strong) NSMutableDictionary<NSString *, id<ASDKCampaignResolution>> *pendingCompletions;
 @end
 
 @implementation Amply
@@ -209,6 +224,132 @@ RCT_EXPORT_MODULE()
   }
 }
 
+/**
+ * Continuation form of track. The resolve block IS the continuation: it is resolved
+ * with @"complete" or @"cancel" exactly once. The KMP trackEvent continuation overload
+ * guarantees exactly-once main-thread delivery; __block + a resolved flag guards the
+ * (defensive) double-settle. Fails open to @"complete" on any synchronous failure or
+ * if the SDK is not initialized.
+ *
+ * The raw CampaignResult is never surfaced here — the SDK collapses it into the
+ * onComplete/onCancel decision before this bridge ever sees it.
+ */
+- (void)trackEventGated:(NSString *)event
+             properties:(NSDictionary *)properties
+                resolve:(RCTPromiseResolveBlock)resolve
+                 reject:(RCTPromiseRejectBlock)reject
+{
+  if (!event || event.length == 0) {
+    if (reject) {
+      reject(@"AMP_INVALID_EVENT", @"Event 'event' is required", nil);
+    }
+    return;
+  }
+
+  NSDictionary *props = [properties isKindOfClass:[NSDictionary class]] ? properties : @{};
+
+  __block BOOL settled = NO;
+  void (^settle)(NSString *) = ^(NSString *decision) {
+    if (settled) { return; }
+    settled = YES;
+    if (resolve) {
+      resolve(decision);
+    }
+  };
+
+  if (!self.amplyInstance) {
+    // Fail open: not initialized -> proceed immediately (KMP state-machine row 1).
+    RCTLogWarn(@"[AmplyReactNative] trackEventGated before init; proceeding (fail-open)");
+    settle(@"complete");
+    return;
+  }
+
+  @try {
+    [self.amplyInstance trackEventEventName:event
+                                 properties:props
+                                  onProceed:^{ settle(@"complete"); }
+                                   onCancel:^{ settle(@"cancel"); }];
+    RCTLogInfo(@"[AmplyReactNative] trackEventGated dispatched: %@", event);
+  } @catch (NSException *exception) {
+    RCTLogError(@"[AmplyReactNative] trackEventGated failed; proceeding (fail-open): %@", exception.reason);
+    settle(@"complete");
+  }
+}
+
+- (void)resolveCampaign:(NSString *)mediationId
+                 result:(NSString *)result
+{
+  id<ASDKCampaignResolution> completion = nil;
+  @synchronized (self) {
+    if (!self.pendingCompletions) { return; }
+    completion = self.pendingCompletions[mediationId];
+    if (completion) {
+      [self.pendingCompletions removeObjectForKey:mediationId];
+    }
+  }
+  if (!completion) {
+    // Late/duplicate/unknown reply — the SDK token is the source of truth and is
+    // already settled (or never existed). Ignore.
+    RCTLogInfo(@"[AmplyReactNative] resolveCampaign for unknown/settled mediationId=%@; ignored", mediationId);
+    return;
+  }
+  ASDKCampaignResult *mapped = AmplyCampaignResultFromString(result);
+  RCTLogInfo(@"[AmplyReactNative] resolveCampaign mediationId=%@ result=%@", mediationId, result);
+  [completion resolveResult:mapped];
+}
+
+- (void)registerCampaignPresenter
+{
+  if (!self.amplyInstance) {
+    RCTLogWarn(@"[AmplyReactNative] Cannot register campaign presenter - Amply not initialized");
+    return;
+  }
+  if (self.campaignPresenterRegistered) {
+    RCTLogInfo(@"[AmplyReactNative] Campaign presenter already registered");
+    return;
+  }
+  if (!self.pendingCompletions) {
+    self.pendingCompletions = [NSMutableDictionary new];
+  }
+  RCTLogInfo(@"[AmplyReactNative] Registering campaign presenter");
+  // Catch-all registration: JS is the single capability registry and routes by URL.
+  [self.amplyInstance registerCampaignPresenterPresenter:self];
+  self.campaignPresenterRegistered = YES;
+}
+
+#pragma mark - ASDKCampaignPresenter
+
+/**
+ * Called by the KMP SDK when a campaign dispatches a present (blocking) action.
+ * We mint a mediationId, park the completion token, and surface the dispatch to JS.
+ * JS later replies via resolveCampaign:result:.
+ */
+- (void)onCampaignPresentUrl:(NSString *)url
+                        info:(NSDictionary<NSString *, id> *)info
+                  completion:(id<ASDKCampaignResolution>)completion
+{
+  NSString *mediationId = [[NSUUID UUID] UUIDString];
+  @synchronized (self) {
+    if (!self.pendingCompletions) {
+      self.pendingCompletions = [NSMutableDictionary new];
+    }
+    self.pendingCompletions[mediationId] = completion;
+  }
+
+  RCTLogInfo(@"[AmplyReactNative] Dispatching campaign present mediationId=%@ url=%@", mediationId, url);
+
+  NSDictionary *payload = @{
+    @"url": url ?: @"",
+    @"info": info ?: @{},
+    @"mediationId": mediationId
+  };
+
+  // Emitter delivery is async; emit on the main queue to match the deeplink path.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [self emitOnCampaignPresent:payload];
+  });
+}
+
 - (void)getRecentEvents:(double)limit
                 resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject
@@ -675,6 +816,20 @@ static ASDKDataSetType *AmplyDataSetTypeFromDictionary(NSDictionary *type, NSStr
 - (void)dealloc
 {
   [[NSNotificationCenter defaultCenter] removeObserver:self];
+
+  // Fail open any in-flight mediated actions so no continuation is left hanging.
+  NSArray<id<ASDKCampaignResolution>> *inFlight = nil;
+  @synchronized (self) {
+    inFlight = self.pendingCompletions.allValues;
+    [self.pendingCompletions removeAllObjects];
+  }
+  for (id<ASDKCampaignResolution> completion in inFlight) {
+    @try {
+      [completion resolveResult:ASDKCampaignResult.unavailable];
+    } @catch (NSException *exception) {
+      // Best-effort cleanup during teardown.
+    }
+  }
 }
 
 #pragma mark - ASDKSystemEventsListener

package/ios/Sources/AmplyReactNative/AmplyReactNative/AmplyReactNative-generated.mm

@@ -23,6 +23,10 @@
 {
   _eventEmitterCallback("onDeepLink", value);
 }
+- (void)emitOnCampaignPresent:(NSDictionary *)value
+{
+  _eventEmitterCallback("onCampaignPresent", value);
+}
 
 - (void)setEventEmitterCallback:(EventEmitterCallbackWrapper *)eventEmitterCallbackWrapper
 {
@@ -56,6 +60,18 @@ namespace facebook::react {
       return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, PromiseKind, "track", @selector(track:resolve:reject:), args, count);
     }
 
+    static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_trackEventGated(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+      return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, PromiseKind, "trackEventGated", @selector(trackEventGated:properties:resolve:reject:), args, count);
+    }
+
+    static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_resolveCampaign(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+      return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, VoidKind, "resolveCampaign", @selector(resolveCampaign:result:), args, count);
+    }
+
+    static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_registerCampaignPresenter(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+      return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, VoidKind, "registerCampaignPresenter", @selector(registerCampaignPresenter), args, count);
+    }
+
     static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_getRecentEvents(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
       return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, PromiseKind, "getRecentEvents", @selector(getRecentEvents:resolve:reject:), args, count);
     }
@@ -116,6 +132,15 @@ namespace facebook::react {
         methodMap_["track"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_track};
         setMethodArgConversionSelector(@"track", 0, @"JS_NativeAmplyModule_TrackEventPayload:");
         
+        methodMap_["trackEventGated"] = MethodMetadata {2, __hostFunction_NativeAmplyModuleSpecJSI_trackEventGated};
+        
+        
+        methodMap_["resolveCampaign"] = MethodMetadata {2, __hostFunction_NativeAmplyModuleSpecJSI_resolveCampaign};
+        
+        
+        methodMap_["registerCampaignPresenter"] = MethodMetadata {0, __hostFunction_NativeAmplyModuleSpecJSI_registerCampaignPresenter};
+        
+        
         methodMap_["getRecentEvents"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_getRecentEvents};
         
         
@@ -153,6 +178,7 @@ namespace facebook::react {
         
         eventEmitterMap_["onSystemEvent"] = std::make_shared<AsyncEventEmitter<id>>();
         eventEmitterMap_["onDeepLink"] = std::make_shared<AsyncEventEmitter<id>>();
+        eventEmitterMap_["onCampaignPresent"] = std::make_shared<AsyncEventEmitter<id>>();
         setEventEmitterCallback([&](const std::string &name, id value) {
           static_cast<AsyncEventEmitter<id> &>(*eventEmitterMap_[name]).emit(value);
         });

package/ios/Sources/AmplyReactNative/AmplyReactNative/AmplyReactNative.h

@@ -78,6 +78,13 @@ namespace JS {
 - (void)track:(JS::NativeAmplyModule::TrackEventPayload &)payload
       resolve:(RCTPromiseResolveBlock)resolve
        reject:(RCTPromiseRejectBlock)reject;
+- (void)trackEventGated:(NSString *)event
+             properties:(NSDictionary *)properties
+                resolve:(RCTPromiseResolveBlock)resolve
+                 reject:(RCTPromiseRejectBlock)reject;
+- (void)resolveCampaign:(NSString *)mediationId
+                 result:(NSString *)result;
+- (void)registerCampaignPresenter;
 - (void)getRecentEvents:(double)limit
                 resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject;
@@ -107,6 +114,7 @@ facebook::react::EventEmitterCallback _eventEmitterCallback;
 
 - (void)emitOnSystemEvent:(NSDictionary *)value;
 - (void)emitOnDeepLink:(NSDictionary *)value;
+- (void)emitOnCampaignPresent:(NSDictionary *)value;
 @end
 
 namespace facebook::react {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplytools/react-native-amply-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "React Native SDK for Amply: Mobile SDK to orchestrate in-app experiences and campaigns remotely, without app releases",
   "license": "MIT",
   "repository": {

package/src/__tests__/campaignResolved.test.ts

@@ -0,0 +1,180 @@
+import * as Amply from '../index';
+import {__setNativeModule} from '../nativeModule';
+
+type CampaignPresentEvent = {url: string; 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(),
+  trackEventGated: jest.fn(),
+  resolveCampaign: jest.fn(),
+  getRecentEvents: jest.fn(),
+  getDataSetSnapshot: jest.fn(),
+  registerDeepLinkListener: jest.fn(),
+  registerCampaignPresenter: 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 CampaignResolved present/resolve/result API', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+    __setNativeModule(null);
+  });
+
+  beforeEach(() => {
+    __setNativeModule(mockNativeModule as never);
+  });
+
+  describe('trackEvent continuation overload', () => {
+    it('calls fire-and-forget track when no callbacks are supplied', async () => {
+      await Amply.trackEvent('SaveTapped', {foo: 'bar'});
+
+      expect(mockNativeModule.track).toHaveBeenCalledWith({
+        name: 'SaveTapped',
+        properties: {foo: 'bar'},
+      });
+      expect(mockNativeModule.trackEventGated).not.toHaveBeenCalled();
+    });
+
+    it('routes a "complete" resolution to onProceed', async () => {
+      mockNativeModule.trackEventGated.mockResolvedValueOnce('complete');
+
+      const onProceed = jest.fn();
+      const onCancel = jest.fn();
+
+      await Amply.trackEvent('SaveTapped', {foo: 'bar'}, {onProceed, onCancel});
+
+      expect(mockNativeModule.trackEventGated).toHaveBeenCalledWith('SaveTapped', {
+        foo: 'bar',
+      });
+      expect(onProceed).toHaveBeenCalledTimes(1);
+      expect(onCancel).not.toHaveBeenCalled();
+    });
+
+    it('routes a "cancel" resolution to onCancel', async () => {
+      mockNativeModule.trackEventGated.mockResolvedValueOnce('cancel');
+
+      const onProceed = jest.fn();
+      const onCancel = jest.fn();
+
+      await Amply.trackEvent('SaveTapped', undefined, {onProceed, onCancel});
+
+      expect(mockNativeModule.trackEventGated).toHaveBeenCalledWith('SaveTapped', {});
+      expect(onCancel).toHaveBeenCalledTimes(1);
+      expect(onProceed).not.toHaveBeenCalled();
+    });
+
+    it('fails open to onProceed when the native call rejects', async () => {
+      mockNativeModule.trackEventGated.mockRejectedValueOnce(new Error('boom'));
+
+      const onProceed = jest.fn();
+      const onCancel = jest.fn();
+
+      await Amply.trackEvent('SaveTapped', {}, {onProceed, onCancel});
+
+      expect(onProceed).toHaveBeenCalledTimes(1);
+      expect(onCancel).not.toHaveBeenCalled();
+    });
+
+    it('runs onProceed (not onCancel) for "cancel" when no onCancel is supplied', async () => {
+      mockNativeModule.trackEventGated.mockResolvedValueOnce('cancel');
+
+      const onProceed = jest.fn();
+
+      await Amply.trackEvent('SaveTapped', {}, {onProceed});
+
+      // The raw result is never exposed; a "cancel" with no onCancel hook is a no-op
+      // for the continuation. onProceed must not fire on a cancel.
+      expect(onProceed).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('registerCampaignPresenter', () => {
+    it('registers once on the native module and subscribes to onCampaignPresent', async () => {
+      const remove = jest.fn();
+      mockNativeModule.onCampaignPresent.mockReturnValue({remove});
+
+      const presenter = jest.fn(() => 'Completed' as const);
+      const unsubscribe = await Amply.registerCampaignPresenter(presenter);
+
+      expect(mockNativeModule.registerCampaignPresenter).toHaveBeenCalledTimes(1);
+      expect(mockNativeModule.onCampaignPresent).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      expect(remove).toHaveBeenCalledTimes(1);
+    });
+
+    it('forwards a synchronous result to resolveCampaign', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation((listener: (e: CampaignPresentEvent) => void) => {
+        emit = listener;
+        return {remove: jest.fn()};
+      });
+
+      const presenter = jest.fn(() => 'Dismissed' as const);
+      await Amply.registerCampaignPresenter(presenter);
+
+      expect(emit).toBeDefined();
+      emit!({url: 'stillframe://ad', info: {campaignId: 'c1'}, mediationId: 'm1'});
+
+      // allow the (possibly async) presenter resolution to flush
+      await flushMicrotasks();
+
+      expect(presenter).toHaveBeenCalledWith('stillframe://ad', {campaignId: 'c1'});
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m1', 'Dismissed');
+    });
+
+    it('forwards a promise-resolved result to resolveCampaign', async () => {
+      let emit: ((e: CampaignPresentEvent) => void) | undefined;
+      mockNativeModule.onCampaignPresent.mockImplementation((listener: (e: CampaignPresentEvent) => void) => {
+        emit = listener;
+        return {remove: jest.fn()};
+      });
+
+      const presenter = jest.fn(async () => 'Unavailable' as const);
+      await Amply.registerCampaignPresenter(presenter);
+
+      emit!({url: 'stillframe://ad', info: {}, mediationId: 'm2'});
+
+      await flushMicrotasks();
+
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m2', 'Unavailable');
+    });
+
+    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()};
+      });
+
+      const presenter = jest.fn(() => {
+        throw new Error('presenter blew up');
+      });
+      await Amply.registerCampaignPresenter(presenter);
+
+      emit!({url: 'stillframe://ad', info: {}, mediationId: 'm3'});
+
+      await flushMicrotasks();
+
+      expect(mockNativeModule.resolveCampaign).toHaveBeenCalledWith('m3', 'Unavailable');
+    });
+  });
+});

package/src/index.ts

@@ -4,18 +4,22 @@ export {useAmplySystemEvents} from './hooks/useAmplySystemEvents';
 export {formatSystemEventLabel} from './systemEventUtils';
 export type {FormatOptions} from './systemEventUtils';
 import type {
+  CampaignResult,
   AmplyInitializationConfig,
   DataSetSnapshot,
   DataSetType,
   DeepLinkEvent,
   EventRecord,
   LogLevel,
+  CampaignPresentEvent,
   TrackEventPayload,
 } from './nativeSpecs/NativeAmplyModule';
 
 let deepLinkRegistered = false;
 let debugLogListenerRegistered = false;
+let campaignPresenterRegistered = false;
 const deepLinkSubscriptions = new Set<() => void>();
+const campaignPresenterSubscriptions = new Set<() => void>();
 
 /**
  * Format a debug log entry for console output using new format.
@@ -132,6 +136,147 @@ export async function track(payload: TrackEventPayload): Promise<void> {
   await getNativeModule().track(payload);
 }
 
+/**
+ * Continuation hooks for the gating form of {@link trackEvent}.
+ *
+ * `onProceed` is "what to do next" (run exactly once when the gate resolves in
+ * favor of proceeding). `onCancel` is an OPTIONAL local-UI cleanup hook, invoked
+ * only when a campaign's blocking action is user-dismissed under an `onAbort=cancel`
+ * policy. Never put business logic in `onCancel`.
+ *
+ * The raw campaign result is deliberately not exposed — app code must never branch
+ * on which action ran or how it resolved.
+ */
+export type TrackEventContinuation = {
+  onProceed: () => void;
+  onCancel?: () => void;
+};
+
+/**
+ * Possible results a campaign presenter can report. Re-exported from the
+ * native spec for app presenters.
+ */
+export type {CampaignResult};
+
+/**
+ * A capability presenter for a campaign present (blocking) action. Keyed by deeplink
+ * URL semantics, NOT by event — the app is a registry of capabilities. Returns (or
+ * resolves) the terminal {@link CampaignResult}. Throwing / rejecting is treated as
+ * `'Unavailable'` (fail-open).
+ */
+export type CampaignPresenter = (
+  url: string,
+  info: Record<string, unknown>,
+) => CampaignResult | Promise<CampaignResult>;
+
+/**
+ * Fire-and-forget analytics track. Records the event and lets any matching NORMAL
+ * campaign action dispatch as usual. A blocking action matched here will NOT fire —
+ * there is no continuation to gate.
+ */
+export function trackEvent(event: string, properties?: Record<string, unknown> | null): Promise<void>;
+/**
+ * Continuation (gating) form. Records the event; if a blocking campaign action
+ * matches AND a presenter is registered, the SDK dispatches it and awaits its result
+ * before resolving the continuation:
+ * - proceed (completed / unavailable / timeout / dismissed+proceed) → `onProceed`
+ * - user dismiss against an `onAbort=cancel` action → `onCancel`
+ *
+ * Fails open: any error path runs `onProceed`. Passing a continuation is the gating
+ * switch — the same event tracked elsewhere without one is a valid, non-gating call.
+ */
+export function trackEvent(
+  event: string,
+  properties: Record<string, unknown> | null | undefined,
+  continuation: TrackEventContinuation,
+): Promise<void>;
+export async function trackEvent(
+  event: string,
+  properties?: Record<string, unknown> | null,
+  continuation?: TrackEventContinuation,
+): Promise<void> {
+  const props = properties ?? {};
+
+  if (!continuation) {
+    await getNativeModule().track({name: event, properties: props});
+    return;
+  }
+
+  let decision: string;
+  try {
+    decision = await getNativeModule().trackEventGated(event, props);
+  } catch (error) {
+    // Fail open: any bridge/SDK failure must proceed, never strand the app.
+    console.warn('[Amply] trackEvent continuation failed; proceeding (fail-open)', error);
+    continuation.onProceed();
+    return;
+  }
+
+  if (decision === 'cancel') {
+    // A deliberate user-dismiss under an onAbort=cancel action. Only the local-UI
+    // cleanup hook runs; the continuation is suppressed.
+    continuation.onCancel?.();
+    return;
+  }
+
+  // 'complete' and any unexpected value fail open to onProceed.
+  continuation.onProceed();
+}
+
+async function ensureCampaignPresenterRegistration(): Promise<void> {
+  if (!campaignPresenterRegistered) {
+    getNativeModule().registerCampaignPresenter();
+    campaignPresenterRegistered = true;
+  }
+}
+
+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 capability presenter for campaign present (blocking) actions. The presenter
+ * is invoked when a blocking action is dispatched; it must report a terminal
+ * {@link CampaignResult} (returned or resolved). The SDK collapses multi-step ad
+ * lifecycles into the single result you report. Throwing/rejecting → `'Unavailable'`.
+ *
+ * @returns an unsubscribe function.
+ */
+export async function registerCampaignPresenter(
+  presenter: CampaignPresenter,
+): Promise<() => void> {
+  await ensureCampaignPresenterRegistration();
+
+  const nativeModule = getNativeModule();
+  const subscription = nativeModule.onCampaignPresent((event: CampaignPresentEvent) => {
+    const {url, info, mediationId} = event;
+    void Promise.resolve()
+      .then(() => presenter(url, info as Record<string, unknown>))
+      .then(
+        result => {
+          nativeModule.resolveCampaign(mediationId, result);
+        },
+        error => {
+          // Presenter failure is an infra failure, never a user dismiss → Unavailable.
+          console.warn('[Amply] campaign presenter failed; reporting Unavailable', error);
+          nativeModule.resolveCampaign(mediationId, 'Unavailable');
+        },
+      );
+  });
+
+  return trackCampaignPresenterSubscription(subscription);
+}
+
 export async function getRecentEvents(limit: number): Promise<EventRecord[]> {
   return getNativeModule().getRecentEvents(limit);
 }
@@ -211,6 +356,15 @@ export function removeAllListeners(): void {
     }
   });
   deepLinkSubscriptions.clear();
+
+  campaignPresenterSubscriptions.forEach(unsubscribe => {
+    try {
+      unsubscribe();
+    } catch (error) {
+      console.warn('[Amply] Failed to remove campaign presenter', error);
+    }
+  });
+  campaignPresenterSubscriptions.clear();
 }
 
 export type {
@@ -220,6 +374,7 @@ export type {
   DeepLinkEvent,
   EventRecord,
   LogLevel,
+  CampaignPresentEvent,
   TrackEventPayload,
 };
 
@@ -237,6 +392,8 @@ export default {
   initialize,
   isInitialized,
   track,
+  trackEvent,
+  registerCampaignPresenter,
   getRecentEvents,
   getDataSetSnapshot,
   addDeepLinkListener,