@amplytools/react-native-amply-sdk 0.14.0 → 0.15.0

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

@@ -94,12 +94,16 @@ namespace JS {
 - (void)getRecentEvents:(double)limit
                 resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject;
+- (void)getLastCampaignTouch:(double)withinMs
+                     resolve:(RCTPromiseResolveBlock)resolve
+                      reject:(RCTPromiseRejectBlock)reject;
 - (void)getDataSetSnapshot:(NSDictionary *)type
                    resolve:(RCTPromiseResolveBlock)resolve
                     reject:(RCTPromiseRejectBlock)reject;
 - (void)registerDeepLinkListener;
 - (void)setUserId:(NSString * _Nullable)userId;
 - (void)setAppLanguage:(NSString * _Nullable)tag;
+- (NSNumber *)handleUrl:(NSString *)url;
 - (void)setLogLevel:(NSString *)level;
 - (NSString *)getLogLevel;
 - (void)setCustomProperties:(NSDictionary *)properties;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplytools/react-native-amply-sdk",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "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__/appLanguage.test.ts

@@ -294,3 +294,5 @@ describe('setAppLanguage while initialize is in flight', () => {
     expect(native.setAppLanguage.mock.calls).toEqual([['fr']]);
   });
 });
+
+export {};

package/src/__tests__/handleUrl.test.ts

@@ -0,0 +1,155 @@
+/**
+ * `handleUrl` hands an incoming link to the native SDK and reports whether the SDK recognised it.
+ * It is synchronous, and it never throws: an older native build without the method answers false.
+ */
+type SdkModule = typeof import('../index');
+
+function loadWith(native: Record<string, unknown>): SdkModule {
+  // Absent isInitialized means "SDK up" for the plain pass-through tests below.
+  const withState = {isInitialized: () => true, ...native};
+  let Amply!: SdkModule;
+  jest.isolateModules(() => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require('../nativeModule').__setNativeModule(withState as never);
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    Amply = require('../index');
+  });
+  return Amply;
+}
+
+const DEBUG_URL = 'myapp://amply-debug/campaign?t=abc';
+
+describe('handleUrl', () => {
+  it('passes the DEBUG_URL to the native module and returns its answer', () => {
+    const handleUrl = jest.fn(() => true);
+    const Amply = loadWith({handleUrl});
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(true);
+    expect(handleUrl).toHaveBeenCalledWith(DEBUG_URL);
+  });
+
+  it('returns false when the native module does not recognise the DEBUG_URL', () => {
+    const Amply = loadWith({handleUrl: jest.fn(() => false)});
+
+    expect(Amply.handleUrl('myapp://settings')).toBe(false);
+  });
+
+  it('returns false without throwing when the native module has no handleUrl', () => {
+    const Amply = loadWith({});
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(false);
+  });
+
+  it('returns false without throwing when the native call throws', () => {
+    const Amply = loadWith({
+      handleUrl: jest.fn(() => {
+        throw new Error('boom');
+      }),
+    });
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(false);
+  });
+
+  it('returns false for a non-string DEBUG_URL', () => {
+    const handleUrl = jest.fn(() => true);
+    const Amply = loadWith({handleUrl});
+
+    expect(Amply.handleUrl(null as never)).toBe(false);
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it('is on the default export', () => {
+    const Amply = loadWith({handleUrl: jest.fn(() => true)});
+
+    expect(Amply.default.handleUrl(DEBUG_URL)).toBe(true);
+  });
+});
+
+describe('handleUrl before initialize', () => {
+  function loadUninitialised(initialize?: () => Promise<void>) {
+    let up = false;
+    const handleUrl = jest.fn(() => true);
+    const native = {
+      handleUrl,
+      isInitialized: jest.fn(() => up),
+      initialize: jest.fn(
+        initialize ??
+          (async () => {
+            up = true;
+          }),
+      ),
+      addListener: jest.fn(),
+      removeListeners: jest.fn(),
+    };
+    return {Amply: loadWith(native), handleUrl};
+  }
+  const KEYS = {appId: 'id', apiKeyPublic: 'public', apiKeySecret: 'secret'};
+
+  it('parks a debug link, returns true and does not call native', () => {
+    const {Amply, handleUrl} = loadUninitialised();
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(true);
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it('replays the parked link to native once after initialize', async () => {
+    const {Amply, handleUrl} = loadUninitialised();
+    Amply.handleUrl(DEBUG_URL);
+
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).toHaveBeenCalledTimes(1);
+    expect(handleUrl).toHaveBeenCalledWith(DEBUG_URL);
+  });
+
+  it('replays only the newer of two parked links', async () => {
+    const {Amply, handleUrl} = loadUninitialised();
+    Amply.handleUrl('myapp://amply-debug/campaign?t=old');
+    Amply.handleUrl('myapp://amply-debug/campaign?t=new');
+
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).toHaveBeenCalledTimes(1);
+    expect(handleUrl).toHaveBeenCalledWith('myapp://amply-debug/campaign?t=new');
+  });
+
+  it('does not park a non-debug link', async () => {
+    const {Amply, handleUrl} = loadUninitialised();
+
+    expect(Amply.handleUrl('myapp://settings')).toBe(false);
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it('drops the parked link when initialize fails', async () => {
+    const {Amply, handleUrl} = loadUninitialised(async () => {
+      throw new Error('init failed');
+    });
+    Amply.handleUrl(DEBUG_URL);
+
+    await expect(Amply.initialize(KEYS)).rejects.toThrow('init failed');
+
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    '',
+    'not a url',
+    'myapp://amply-debug/campaign',
+    'myapp://amply-debug/campaign?t=',
+    'myapp://amply-debug/other?t=abc',
+    'myapp://other/campaign?t=abc',
+    'amply-debug/campaign?t=abc',
+    '://amply-debug/campaign?t=abc',
+  ])('returns false without throwing for %p', async url => {
+    const {Amply, handleUrl} = loadUninitialised();
+
+    expect(Amply.handleUrl(url)).toBe(false);
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+});
+
+export {};

package/src/__tests__/lastCampaignTouch.test.ts

@@ -0,0 +1,151 @@
+import * as Amply from '../index';
+import {__setNativeModule} from '../nativeModule';
+
+const mockNativeModule = {
+  isInitialized: jest.fn(() => true),
+  getLastCampaignTouch: jest.fn(),
+};
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+describe('getLastCampaignTouch', () => {
+  let warn: jest.SpyInstance;
+
+  beforeEach(() => {
+    __setNativeModule(mockNativeModule as never);
+    warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+    jest.clearAllMocks();
+    __setNativeModule(null);
+  });
+
+  it('passes withinMs through to the native module and returns the touch', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: 'shown',
+      atMs: 1_760_000_000_000,
+    });
+
+    const touch = await Amply.getLastCampaignTouch(ONE_HOUR_MS);
+
+    expect(mockNativeModule.getLastCampaignTouch).toHaveBeenCalledWith(ONE_HOUR_MS);
+    expect(touch).toEqual({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: 'shown',
+      atMs: 1_760_000_000_000,
+    });
+  });
+
+  it('is exposed on the default export too', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+
+    await expect(Amply.default.getLastCampaignTouch(0)).resolves.toBeNull();
+  });
+
+  it('resolves null when the native side has no touch', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+  });
+
+  it('resolves null when the native side resolves undefined', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(undefined);
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+  });
+
+  it.each([
+    ['shown', 'shown'],
+    ['engaged', 'engaged'],
+    ['SHOWN', 'shown'],
+    ['ENGAGED', 'engaged'],
+  ])('maps native kind %s to %s', async (nativeKind, expected) => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: nativeKind,
+      atMs: 1,
+    });
+
+    const touch = await Amply.getLastCampaignTouch(ONE_HOUR_MS);
+
+    expect(touch?.kind).toBe(expected);
+  });
+
+  it('resolves null and warns for a kind this bridge does not know', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: 'clicked',
+      atMs: 1,
+    });
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('getLastCampaignTouch'), expect.anything());
+  });
+
+  it.each([
+    ['a missing campaignId', {campaignName: 'x', kind: 'shown', atMs: 1}],
+    ['a non-numeric atMs', {campaignId: 'c', campaignName: 'x', kind: 'shown', atMs: '1'}],
+  ])('resolves null for a payload with %s', async (_label, payload) => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(payload);
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+  });
+
+  it('keeps an empty campaign name rather than dropping the touch', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: '',
+      kind: 'engaged',
+      atMs: 5,
+    });
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toEqual({
+      campaignId: 'cmp_1',
+      campaignName: '',
+      kind: 'engaged',
+      atMs: 5,
+    });
+  });
+
+  it('resolves null instead of rejecting when the native call fails', async () => {
+    mockNativeModule.getLastCampaignTouch.mockRejectedValueOnce(new Error('bridge gone'));
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it('accepts zero', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+
+    await Amply.getLastCampaignTouch(0);
+
+    expect(mockNativeModule.getLastCampaignTouch).toHaveBeenCalledWith(0);
+  });
+
+  it('leaves a large window to the native clamp', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+    const ninetyDaysMs = 90 * 24 * ONE_HOUR_MS;
+
+    await Amply.getLastCampaignTouch(ninetyDaysMs);
+
+    expect(mockNativeModule.getLastCampaignTouch).toHaveBeenCalledWith(ninetyDaysMs);
+  });
+
+  it.each([
+    ['negative', -1],
+    ['NaN', Number.NaN],
+    ['Infinity', Number.POSITIVE_INFINITY],
+    ['a string', '3600000'],
+    ['undefined', undefined],
+  ])('rejects with a RangeError for %s and never calls native', async (_label, value) => {
+    await expect(Amply.getLastCampaignTouch(value as never)).rejects.toBeInstanceOf(RangeError);
+    expect(mockNativeModule.getLastCampaignTouch).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/systemEventUtils.test.ts

@@ -42,6 +42,28 @@ describe('formatSystemEventLabel', () => {
       );
     });
 
+    it('names the campaign in CampaignShown when the SDK sends campaignName', () => {
+      const event = makeEvent('CampaignShown', {
+        campaignId: 'abc',
+        campaignName: 'Spring offer',
+        source: 'click',
+      });
+      expect(formatSystemEventLabel(event)).toBe(
+        'Campaign shown "Spring offer" (abc) via click',
+      );
+    });
+
+    it('ignores an empty campaignName in CampaignShown', () => {
+      const event = makeEvent('CampaignShown', {
+        campaignId: 'abc',
+        campaignName: '',
+        source: 'click',
+      });
+      expect(formatSystemEventLabel(event)).toBe(
+        'Campaign shown (abc) via click',
+      );
+    });
+
     it('formats EventTriggered with source event', () => {
       const event = makeEvent('EventTriggered', {sourceEvent: 'purchase'});
       expect(formatSystemEventLabel(event)).toBe('Event triggered (purchase)');

package/src/campaignTouch.ts

@@ -0,0 +1,74 @@
+import type {CampaignTouchPayload} from './nativeSpecs/NativeAmplyModule';
+
+/**
+ * - `'shown'`: the campaign was shown (`CampaignShown`).
+ * - `'engaged'`: the campaign resolved `Completed` (`CampaignResolved` with `result: 'Completed'`).
+ */
+export type CampaignTouchKind = 'shown' | 'engaged';
+
+/**
+ * The most recent moment a campaign reached the user, as answered by `getLastCampaignTouch`.
+ *
+ * Meant for your own analytics: attach `campaignId` / `campaignName` to a purchase (or any
+ * conversion) that happens shortly after a campaign, even when it did not start from the
+ * campaign's own link.
+ */
+export type CampaignTouch = {
+  /**
+   * The id the SDK reports in `CampaignShown`. Inside an experiment that is the arm's own id —
+   * the same value `{@campaign.id}` resolves to, so it is also the right value for an explicit
+   * `amply_campaign_id` mark.
+   */
+  campaignId: string;
+  /** The campaign's name when the touch was recorded. Empty if the event carried no name. */
+  campaignName: string;
+  /** One touch per campaign: the newer of a show and a completion wins. */
+  kind: CampaignTouchKind;
+  /** When it happened, epoch milliseconds in the SDK's server-corrected clock. */
+  atMs: number;
+};
+
+/** Thrown (as a rejection) by `getLastCampaignTouch` for a window that is not a usable number. */
+export function assertValidWithinMs(withinMs: unknown): asserts withinMs is number {
+  if (typeof withinMs !== 'number' || !Number.isFinite(withinMs) || withinMs < 0) {
+    throw new RangeError(
+      `[Amply] getLastCampaignTouch: withinMs must be a finite number >= 0, got ${String(withinMs)}`,
+    );
+  }
+}
+
+function toKind(raw: unknown): CampaignTouchKind | null {
+  if (typeof raw !== 'string') {
+    return null;
+  }
+  const lowered = raw.toLowerCase();
+  return lowered === 'shown' || lowered === 'engaged' ? lowered : null;
+}
+
+/**
+ * Narrows what the native bridge resolved to the public type. Anything it cannot read as a
+ * touch becomes null with a warning: the caller asked "was there a campaign", and a payload this
+ * bridge does not understand is not one it can vouch for.
+ */
+export function toCampaignTouch(payload: CampaignTouchPayload | null | undefined): CampaignTouch | null {
+  if (payload == null) {
+    return null;
+  }
+  const kind = toKind(payload.kind);
+  const isReadable =
+    kind !== null &&
+    typeof payload.campaignId === 'string' &&
+    payload.campaignId.length > 0 &&
+    typeof payload.atMs === 'number' &&
+    Number.isFinite(payload.atMs);
+  if (!isReadable) {
+    console.warn('[Amply] getLastCampaignTouch: ignoring an unreadable native payload', payload);
+    return null;
+  }
+  return {
+    campaignId: payload.campaignId,
+    campaignName: typeof payload.campaignName === 'string' ? payload.campaignName : '',
+    kind,
+    atMs: payload.atMs,
+  };
+}

package/src/index.ts

@@ -3,6 +3,9 @@ import {addSystemEventListenerRaw, addSystemEventListener as addSystemEventListe
 export {useAmplySystemEvents} from './hooks/useAmplySystemEvents';
 export {formatSystemEventLabel} from './systemEventUtils';
 export type {FormatOptions} from './systemEventUtils';
+import {assertValidWithinMs, toCampaignTouch} from './campaignTouch';
+import type {CampaignTouch} from './campaignTouch';
+export type {CampaignTouch, CampaignTouchKind} from './campaignTouch';
 import type {
   CampaignResult,
   GateDecision,
@@ -238,6 +241,9 @@ export async function initialize(config: AmplyInitializationConfig): Promise<voi
   try {
     await getNativeModule().initialize(withParkedAppLanguage(config, parked));
   } catch (error) {
+    // A debug link parked for a failed start has nothing to open; replaying it later would
+    // surprise a retry that the user did not scan for.
+    parkedDebugUrl = null;
     // Nothing reached the SDK, so the call still has to — unless a newer one replaced it.
     if (parkedAppLanguage == null && isLatestLanguageWrite(parked)) {
       parkedAppLanguage = parked;
@@ -251,6 +257,7 @@ export async function initialize(config: AmplyInitializationConfig): Promise<voi
     getNativeModule().setAppLanguage(null);
   }
   flushParkedAppLanguage();
+  flushParkedDebugUrl();
   // Anything the host registered before this point was parked rather than lost.
   replayPendingRegistrations();
 }
@@ -334,6 +341,92 @@ export function setAppLanguage(tag: string | null): void {
   parkedAppLanguage = {tag, seq: languageWriteSeq};
 }
 
+/** A debug link that arrived before the SDK was up. At most one: a newer link replaces it. */
+let parkedDebugUrl: string | null = null;
+
+const URL_SCHEME_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+const DEBUG_LINK_HOST = 'amply-debug';
+const DEBUG_LINK_PATH = '/campaign';
+const DEBUG_LINK_TOKEN_PARAM = 't';
+
+/**
+ * True for `<any scheme>://amply-debug/campaign?t=<non-empty>`. Parsed by hand, without decoding,
+ * so a malformed string is just "not a debug link" and can never throw.
+ */
+function isDebugLink(url: string): boolean {
+  const scheme = URL_SCHEME_PREFIX.exec(url);
+  if (scheme == null) {
+    return false;
+  }
+  const rest = url.slice(scheme[0].length).split('#')[0];
+  const queryStart = rest.indexOf('?');
+  if (queryStart < 0) {
+    return false;
+  }
+  const target = rest.slice(0, queryStart);
+  const slash = target.indexOf('/');
+  if (slash < 0 || target.slice(0, slash) !== DEBUG_LINK_HOST) {
+    return false;
+  }
+  if (target.slice(slash).replace(/\/+$/, '') !== DEBUG_LINK_PATH) {
+    return false;
+  }
+  return rest
+    .slice(queryStart + 1)
+    .split('&')
+    .some(pair => {
+      const eq = pair.indexOf('=');
+      return eq > 0 && pair.slice(0, eq) === DEBUG_LINK_TOKEN_PARAM && eq < pair.length - 1;
+    });
+}
+
+function flushParkedDebugUrl(): void {
+  const url = parkedDebugUrl;
+  parkedDebugUrl = null;
+  if (url == null) {
+    return;
+  }
+  try {
+    getNativeModule().handleUrl?.(url);
+  } catch (error) {
+    console.warn('[Amply] Failed to replay a debug link parked until initialize', error);
+  }
+}
+
+/**
+ * Hand an incoming URL to Amply. Call it for every link your app is opened with — cold start
+ * and while running — before your own routing; when it returns `true` Amply recognised the
+ * link as its own and took it over, so your app should not route it.
+ *
+ * Safe to call before {@link initialize}, which is how a cold-start link arrives: an Amply debug
+ * link is held (the newest one) and opened once initialization succeeds, and `true` is returned.
+ *
+ * Synchronous. Returns `false` for any other URL, for a non-string, and when the installed
+ * native SDK predates this method; it never throws.
+ * @param url The full incoming URL
+ */
+export function handleUrl(url: string): boolean {
+  if (typeof url !== 'string') {
+    return false;
+  }
+  try {
+    if (!isSdkUp()) {
+      if (!isDebugLink(url)) {
+        return false;
+      }
+      parkedDebugUrl = url;
+      return true;
+    }
+    const nativeModule = getNativeModule();
+    if (typeof nativeModule.handleUrl !== 'function') {
+      return false;
+    }
+    return nativeModule.handleUrl(url) === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Set the user ID for analytics. Pass null to clear.
  * @param userId The user ID to set, or null to clear
@@ -612,6 +705,35 @@ export async function getRecentEvents(limit: number): Promise<EventRecord[]> {
   return getNativeModule().getRecentEvents(limit);
 }
 
+/**
+ * The campaign the user was most recently touched by — shown, or completed — at most `withinMs`
+ * ago, or `null` if there was none.
+ *
+ * Use it to attribute a purchase (or any conversion) in your own analytics to the campaign that
+ * preceded it, including one made from somewhere other than the campaign's link:
+ *
+ * ```ts
+ * const touch = await Amply.getLastCampaignTouch(30 * 60 * 1000);
+ * analytics.track('Purchase', {sku, amply_campaign_id: touch?.campaignId});
+ * ```
+ *
+ * One touch per campaign, the newer of a show and a completion. `withinMs` is inclusive and
+ * capped at 30 days by the SDK. Resolves `null` before {@link initialize}, while the SDK's storage
+ * is off, and if the native call fails — it rejects only for a `withinMs` that is not a finite
+ * number >= 0, which is a bug at the call site.
+ */
+export async function getLastCampaignTouch(withinMs: number): Promise<CampaignTouch | null> {
+  assertValidWithinMs(withinMs);
+  try {
+    return toCampaignTouch(await getNativeModule().getLastCampaignTouch(withinMs));
+  } catch (error) {
+    // The SDK answers null for every state it can be in; a rejection here is the bridge itself
+    // failing, and an analytics lookup must never break the purchase flow that asked.
+    console.warn('[Amply] getLastCampaignTouch failed; resolving null', error);
+    return null;
+  }
+}
+
 export async function getDataSetSnapshot(type: DataSetType): Promise<DataSetSnapshot> {
   return getNativeModule().getDataSetSnapshot(type);
 }
@@ -733,6 +855,7 @@ export default {
   trackGated,
   registerGate,
   getRecentEvents,
+  getLastCampaignTouch,
   getDataSetSnapshot,
   addDeepLinkListener,
   addSystemEventListener,
@@ -740,6 +863,7 @@ export default {
   removeAllListeners,
   setUserId,
   setAppLanguage,
+  handleUrl,
   setLogLevel,
   getLogLevel,
   setCustomProperty,

package/src/nativeSpecs/NativeAmplyModule.ts

@@ -69,8 +69,24 @@ export type EventRecord = {
   properties: JsonMap;
 };
 
+/**
+ * A system event from the SDK. `CampaignShown` and `CampaignResolved` carry `campaignId` and,
+ * from SDK 0.15.0, `campaignName` in `properties`.
+ */
 export type SystemEventPayload = EventRecord;
 
+/**
+ * Wire shape of a campaign touch as the native bridges send it. `kind` is `'shown'` or
+ * `'engaged'`; the public `CampaignTouch` type narrows it. Kept a plain string here so the
+ * codegen contract does not change if the SDK ever adds a kind.
+ */
+export type CampaignTouchPayload = {
+  campaignId: string;
+  campaignName: string;
+  kind: string;
+  atMs: number;
+};
+
 export type TriggeredEventCountStrategy = 'global' | 'session';
 
 export type TriggeredEventParam = {
@@ -201,6 +217,12 @@ export interface Spec extends TurboModule {
    */
   unregisterGate(baseUrl: string): void;
   getRecentEvents(limit: number): Promise<EventRecord[]>;
+  /**
+   * The campaign the user was most recently touched by (shown, or completed) at most `withinMs`
+   * ago, or null. Never rejects for "not initialised" — that resolves null, as in the SDK.
+   * `withinMs` is clamped natively to [0, 30 days].
+   */
+  getLastCampaignTouch(withinMs: number): Promise<CampaignTouchPayload | null>;
   getDataSetSnapshot(type: DataSetType): Promise<DataSetSnapshot>;
   registerDeepLinkListener(): void;
   /**
@@ -214,6 +236,13 @@ export interface Spec extends TurboModule {
    * @param tag The language tag, or null to clear
    */
   setAppLanguage(tag: string | null): void;
+  /**
+   * Hand an incoming URL to the SDK. Returns true when the SDK recognised it as its own
+   * (a test-launch link) and took it over; false for any other URL, or when the SDK is not
+   * initialized.
+   * @param url The full incoming URL
+   */
+  handleUrl(url: string): boolean;
   /**
    * Set the log level at runtime.
    * @param level The log level to set

package/src/systemEventUtils.ts

@@ -27,8 +27,10 @@ export function formatSystemEventLabel(
   }
   if (event.name === 'CampaignShown') {
     const campaignId = event.properties.campaignId as string | undefined;
+    // Sent by SDK 0.15.0 and later (on CampaignShown and CampaignResolved alike).
+    const campaignName = event.properties.campaignName as string | undefined;
     const source = event.properties.source as string | undefined;
-    return `Campaign shown${campaignId ? ` (${campaignId})` : ''}${
+    return `Campaign shown${campaignName ? ` "${campaignName}"` : ''}${campaignId ? ` (${campaignId})` : ''}${
       source ? ` via ${source}` : ''
     }`;
   }