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

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,
@@ -232,11 +235,198 @@ export async function initialize(config: AmplyInitializationConfig): Promise<voi
   if (config.debug || config.logLevel) {
     ensureDebugLogListener();
   }
-  await getNativeModule().initialize(config);
+  // Taken now, synchronously: a call made after this point is later than the config and must
+  // stay parked so it is applied after it.
+  const parked = takeParkedAppLanguage();
+  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;
+    }
+    throw error;
+  }
+  // A parked clear cannot travel in the config, where null means "leave it alone". Replayed only
+  // if nothing newer came in while initialize was in flight: the native SDK reports itself up
+  // before this promise settles, and a call made in that window has already reached it.
+  if (parked?.tag === null && !hasText(config.appLanguage) && isLatestLanguageWrite(parked)) {
+    getNativeModule().setAppLanguage(null);
+  }
+  flushParkedAppLanguage();
+  flushParkedDebugUrl();
   // Anything the host registered before this point was parked rather than lost.
   replayPendingRegistrations();
 }
 
+/**
+ * A {@link setAppLanguage} call made before the SDK was up. Boxed so that a parked `null` — a
+ * request to return to automatic detection — is distinguishable from nothing parked.
+ *
+ * The native bridges buffer such calls too, but replay them AFTER building the SDK, which applies
+ * the config's `appLanguage` first. An earlier call would then overwrite a later config value,
+ * the opposite of "last write wins". Parking it here lets {@link initialize} put the two in the
+ * order they were made.
+ */
+let parkedAppLanguage: LanguageWrite | null = null;
+
+/**
+ * One {@link setAppLanguage} call. `seq` orders it against every other call, forwarded or held:
+ * a held value is applied only while it is still the latest write, so one taken before
+ * initialize cannot be replayed over a call the native SDK received while initialize was in
+ * flight.
+ */
+interface LanguageWrite {
+  readonly tag: string | null;
+  readonly seq: number;
+}
+
+/** Bumped by every {@link setAppLanguage} call, whether it is forwarded or held. */
+let languageWriteSeq = 0;
+
+function isLatestLanguageWrite(write: LanguageWrite | null): write is LanguageWrite {
+  return write != null && write.seq === languageWriteSeq;
+}
+
+function hasText(value: string | null | undefined): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function takeParkedAppLanguage(): LanguageWrite | null {
+  const parked = parkedAppLanguage;
+  parkedAppLanguage = null;
+  return parked;
+}
+
+/** The config's own appLanguage wins: initialize was called after the parked call. */
+function withParkedAppLanguage(
+  config: AmplyInitializationConfig,
+  parked: LanguageWrite | null,
+): AmplyInitializationConfig {
+  if (hasText(config.appLanguage) || parked == null || parked.tag === null) {
+    return config;
+  }
+  return {...config, appLanguage: parked.tag};
+}
+
+function flushParkedAppLanguage(): void {
+  const parked = takeParkedAppLanguage();
+  if (isLatestLanguageWrite(parked)) {
+    getNativeModule().setAppLanguage(parked.tag);
+  }
+}
+
+/**
+ * Tell Amply the language your app's UI is in, so sheets, stories and mini-apps show in the
+ * matching language and campaigns can target it. Use this when the app chooses its language
+ * itself (an in-app language picker, i18next, …) rather than following the device.
+ *
+ * Any common tag format works — `'pt_BR'`, `'pt-BR'`, `'zh-TW'`, `'fr'`, any case. A value that
+ * is not a language tag is ignored by the SDK with a warning log. The value is persisted across
+ * launches; pass `null` to return to automatic detection. The device language is never changed.
+ *
+ * Safe to call before {@link initialize}: the value is held and applied at initialization, and
+ * an `appLanguage` passed to a later `initialize` call wins over it.
+ * @param tag The language tag, or null to clear
+ */
+export function setAppLanguage(tag: string | null): void {
+  languageWriteSeq += 1;
+  if (isSdkUp()) {
+    getNativeModule().setAppLanguage(tag);
+    return;
+  }
+  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
@@ -515,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);
 }
@@ -636,12 +855,15 @@ export default {
   trackGated,
   registerGate,
   getRecentEvents,
+  getLastCampaignTouch,
   getDataSetSnapshot,
   addDeepLinkListener,
   addSystemEventListener,
   addSystemEventsListener,
   removeAllListeners,
   setUserId,
+  setAppLanguage,
+  handleUrl,
   setLogLevel,
   getLogLevel,
   setCustomProperty,

package/src/nativeSpecs/NativeAmplyModule.ts

@@ -46,6 +46,12 @@ export type AmplyInitializationConfig = {
    * Takes precedence over `debug` if both are specified.
    */
   logLevel?: LogLevel | null;
+  /**
+   * The language the app's UI is in, in any common format (`'pt_BR'`, `'zh-TW'`, `'fr'`).
+   * The same as calling `setAppLanguage` right after initialization, and persisted the same
+   * way. Omitted, null or blank leaves the current setting alone.
+   */
+  appLanguage?: string | null;
 };
 
 export type EventType = 'custom' | 'system';
@@ -63,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 = {
@@ -195,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;
   /**
@@ -202,6 +230,19 @@ export interface Spec extends TurboModule {
    * @param userId The user ID to set, or null to clear
    */
   setUserId(userId: string | null): void;
+  /**
+   * Set the language the app's UI is in. Any common tag format; null returns to automatic
+   * detection. Persisted by the SDK across launches.
+   * @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}` : ''
     }`;
   }