pulse-updates 1.3.5 → 1.3.7

package/src/init.ts

@@ -14,9 +14,10 @@
  *  - the urls, from the base url and the slug, which is what stops the two halves
  *    from ever addressing different apps;
  *  - platform and OS version, from React Native;
- *  - the device id, minted and persisted on first launch — an app that has a stable
- *    identifier of its own (the vendor id, an installation id) should pass it, and an
- *    app that has none should not have to invent one to be measurable.
+ *  - the config/experiment id, minted and persisted on first launch — an app that has
+ *    a stable identifier of its own may pass it. Event tracking keeps the original
+ *    context identity by default; privacy-sensitive campaign events can explicitly
+ *    opt into a separate random app-scoped analytics installation UUID.
  *
  * Deliberately not automatic: the app version. Nothing here can read the store build
  * reliably on both platforms, and a version guessed wrong aims a rollout at the wrong
@@ -92,6 +93,13 @@ export interface InitPulseOptions {
   eventPropertyAllowlist?: readonly string[];
   redactEventProperties?: readonly string[];
 
+  /**
+   * Event-envelope identity. Defaults to the backwards-compatible config context.
+   * Use `anonymous_installation` for events that carry their own experiment/variant
+   * dimensions and must never transmit the app's device or account identifier.
+   */
+  eventIdentityMode?: 'context' | 'anonymous_installation';
+
   /** Signed config uses the same Ed25519 public key as OTA updates. */
   signingPublicKey?: string;
   signingKeyId?: string;
@@ -156,7 +164,7 @@ export interface AsyncPulseStorage {
 let activeClient: PulseClient | null = null;
 let stopActiveRefresh: (() => void) | null = null;
 
-/** Wires config and events, and returns the context the two share. */
+/** Wires config and events with an explicit event-envelope identity policy. */
 export function initPulse(opts: InitPulseOptions): PulseClient {
   // Reconfiguration is synchronous. Calling the old async dispose without awaiting
   // it lets its eventual flush tear down the brand-new tracker — exactly the race a
@@ -216,6 +224,7 @@ export function initPulse(opts: InitPulseOptions): PulseClient {
   configureTracking({
     url: trackUrl,
     getContext,
+    identityMode: opts.eventIdentityMode,
     flushIntervalMs: opts.flushIntervalMs,
     storage: opts.storage,
     storageKey: `pulse.${slug}.events.v1`,
@@ -300,8 +309,9 @@ export function initPulse(opts: InitPulseOptions): PulseClient {
 }
 
 /**
- * AsyncStorage-friendly one-call setup. It preloads only Pulse's three app-scoped
- * records, then exposes the same synchronous hot-path API as initPulse.
+ * AsyncStorage-friendly one-call setup. It preloads only Pulse's app-scoped config,
+ * event, analytics-installation and exposure records, then exposes the same
+ * synchronous hot-path API as initPulse.
  */
 export async function initPulseAsync(
   opts: Omit<InitPulseOptions, 'storage'> & { storage: AsyncPulseStorage },
@@ -311,6 +321,7 @@ export async function initPulseAsync(
     `pulse.${slug}.device-id`,
     `pulse.${slug}.config.v1`,
     `pulse.${slug}.events.v1`,
+    `pulse.${slug}.events.v1.analytics-installation-id`,
     `pulse.${slug}.exposures.v1`,
     DEVICE_ID_KEY,
   ];

package/src/links.ts

@@ -98,12 +98,30 @@ export interface DeferredLinkOutcomeEvent {
   occurredAt: string;
 }
 
+export type AnonymousFirstOpenDeviceType =
+  | 'phone'
+  | 'tablet'
+  | 'tv'
+  | 'desktop'
+  | 'gaming_console'
+  | 'unknown';
+
 export interface AnonymousFirstOpenContext {
   appBundleId: string;
   locale: string;
   platform: 'ios';
   /** Native first-install timestamp. Matching is refused when recency cannot be proven. */
   installedAt: number;
+  /** Ephemeral release/runtime dimensions. Invalid values are omitted from the request. */
+  appVersion?: string;
+  osVersion?: string;
+  /** Hardware model code (for example iPhone17,2), never IDFV/IDFA/a unique device id. */
+  deviceModelCode?: string;
+  deviceType?: AnonymousFirstOpenDeviceType;
+  distribution?: string;
+  /** JavaScript Date#getTimezoneOffset semantics, bounded to real-world UTC offsets. */
+  timezoneOffsetMinutes?: number;
+  isEmulator?: boolean;
 }
 
 export type AnonymousFirstOpenResult =
@@ -247,6 +265,17 @@ const MAX_APPLIED_IDS = 32;
 const MAX_NOTIFIED_OUTCOMES = MAX_APPLIED_IDS * 3;
 const MAX_RESOLVER_OUTCOMES = MAX_NOTIFIED_OUTCOMES;
 const MAX_PERSISTED_BYTES = 131_072;
+const VERSION_SIGNAL = /^[A-Za-z0-9][A-Za-z0-9._+()-]*$/;
+const DEVICE_MODEL_CODE = /^[A-Za-z0-9][A-Za-z0-9._,+-]*$/;
+const DISTRIBUTION_SIGNAL = /^[a-z0-9][a-z0-9._-]*$/;
+const DEVICE_TYPES = new Set<AnonymousFirstOpenDeviceType>([
+  'phone',
+  'tablet',
+  'tv',
+  'desktop',
+  'gaming_console',
+  'unknown',
+]);
 
 interface QueuedResolverOutcome {
   /** Non-reversible local transition key; never sent over the network. */
@@ -258,6 +287,8 @@ interface QueuedResolverOutcome {
   occurredAt: string;
   matchBasis: DeferredLinkMatchBasis;
   confidence: number;
+  /** Correlates a later deterministic truth to an earlier anonymous first-open attempt. */
+  installAttemptId?: string;
   attempts: number;
   nextRetryAt: number;
 }
@@ -606,8 +637,18 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     const transitionKey = stableOutcomeKey(link.id, name);
     if (state.notifiedOutcomes.includes(transitionKey)) return;
 
-    const occurredAt = new Date(now()).toISOString();
+    const outcomeTimestamp = now();
+    const occurredAt = new Date(outcomeTimestamp).toISOString();
     const shouldReportToResolver = (options.reportResolverOutcomes ?? true) && isPublicToken(link.id);
+    const firstOpenAttemptIsRecent = state.firstOpen.attemptedAt > 0
+      && state.firstOpen.attemptedAt <= outcomeTimestamp
+      && outcomeTimestamp - state.firstOpen.attemptedAt <= recentInstallMaxAgeMs;
+    const correlatedInstallAttemptId = firstOpenAttemptIsRecent
+      && link.matchGuaranteed
+      && link.matchBasis !== 'unique_probabilistic'
+      && link.matchBasis !== 'unmatched'
+      ? state.firstOpen.installAttemptId
+      : null;
     const queued: QueuedResolverOutcome | null = shouldReportToResolver ? {
       transitionKey,
       token: link.id,
@@ -619,6 +660,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       occurredAt,
       matchBasis: link.matchBasis,
       confidence: link.confidence,
+      ...(correlatedInstallAttemptId ? { installAttemptId: correlatedInstallAttemptId } : {}),
       attempts: 0,
       nextRetryAt: 0,
     } : null;
@@ -963,6 +1005,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       locale: normalizeLocale(context.locale),
       firstOpen: true,
       installAttemptId,
+      ...normalizeAnonymousFirstOpenSignals(context),
     };
     try {
       const response = await withTimeout(
@@ -1243,6 +1286,57 @@ function normalizeLocale(locale: string): string {
   return locale.trim().replace(/_/g, '-');
 }
 
+function normalizeAnonymousFirstOpenSignals(
+  context: AnonymousFirstOpenContext,
+): Partial<Omit<AnonymousFirstOpenContext, 'appBundleId' | 'locale' | 'platform' | 'installedAt'>> {
+  const appVersion = normalizeSignalString(context.appVersion, VERSION_SIGNAL, 64);
+  const osVersion = normalizeSignalString(context.osVersion, VERSION_SIGNAL, 64);
+  const deviceModelCode = normalizeSignalString(context.deviceModelCode, DEVICE_MODEL_CODE, 80);
+  const distribution = normalizeDistributionSignal(context.distribution);
+  const normalizedDeviceType = typeof context.deviceType === 'string'
+    ? context.deviceType.trim().toLowerCase()
+    : '';
+  const deviceType = DEVICE_TYPES.has(normalizedDeviceType as AnonymousFirstOpenDeviceType)
+    ? normalizedDeviceType as AnonymousFirstOpenDeviceType
+    : undefined;
+  const timezoneOffsetMinutes = typeof context.timezoneOffsetMinutes === 'number'
+    && Number.isFinite(context.timezoneOffsetMinutes)
+    && Number.isInteger(context.timezoneOffsetMinutes)
+    && context.timezoneOffsetMinutes >= -840
+    && context.timezoneOffsetMinutes <= 840
+    ? context.timezoneOffsetMinutes
+    : undefined;
+  const isEmulator = typeof context.isEmulator === 'boolean' ? context.isEmulator : undefined;
+  return {
+    ...(appVersion ? { appVersion } : {}),
+    ...(osVersion ? { osVersion } : {}),
+    ...(deviceModelCode ? { deviceModelCode } : {}),
+    ...(deviceType ? { deviceType } : {}),
+    ...(distribution ? { distribution } : {}),
+    ...(timezoneOffsetMinutes !== undefined ? { timezoneOffsetMinutes } : {}),
+    ...(isEmulator !== undefined ? { isEmulator } : {}),
+  };
+}
+
+function normalizeDistributionSignal(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim().toLowerCase().replace(/[ -]+/g, '_');
+  const canonical = normalized === 'appstore' ? 'app_store' : normalized;
+  return normalizeSignalString(canonical, DISTRIBUTION_SIGNAL, 24);
+}
+
+function normalizeSignalString(
+  value: unknown,
+  grammar: RegExp,
+  maxLength: number,
+): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim();
+  return normalized.length > 0 && normalized.length <= maxLength && grammar.test(normalized)
+    ? normalized
+    : undefined;
+}
+
 function makeInstallAttemptId(custom?: () => string): string {
   try {
     const candidate = custom?.()
@@ -1322,6 +1416,7 @@ async function postResolverOutcome(
         occurredAt: outcome.occurredAt,
         matchBasis: outcome.matchBasis,
         confidence: outcome.confidence,
+        ...(outcome.installAttemptId ? { installAttemptId: outcome.installAttemptId } : {}),
       }),
     },
     timeoutMs,
@@ -1357,6 +1452,11 @@ function readResolverOutcomeQueue(raw: unknown): QueuedResolverOutcome[] {
       ? clampConfidence(value.confidence, 0)
       : null;
     if (confidence === null) continue;
+    const installAttemptId = matchBasis !== 'unique_probabilistic' && matchBasis !== 'unmatched'
+      && typeof value.installAttemptId === 'string'
+      && INSTALL_ATTEMPT_ID.test(value.installAttemptId)
+      ? value.installAttemptId.toLowerCase()
+      : undefined;
     seenTransitions.add(transitionKey);
     seenEvents.add(eventId);
     queue.unshift({
@@ -1367,6 +1467,7 @@ function readResolverOutcomeQueue(raw: unknown): QueuedResolverOutcome[] {
       occurredAt,
       matchBasis,
       confidence,
+      ...(installAttemptId ? { installAttemptId } : {}),
       attempts: safeInteger(value.attempts, 100_000),
       nextRetryAt: safeTimestamp(value.nextRetryAt),
     });

package/src/track.ts

@@ -31,9 +31,21 @@ export interface TrackOptions {
    */
   url: string;
 
-  /** The same context the config uses — identity travels with the batch, once. */
+  /**
+   * Request context shared with config. `context` identity mode reads deviceId/userId
+   * for backwards-compatible experiment metrics; `anonymous_installation` ignores
+   * them and reads only platform/appVersion.
+   */
   getContext?: () => ConfigContext;
 
+  /**
+   * `context` preserves the original experiment-event contract and sends the context
+   * deviceId/userId. `anonymous_installation` is an explicit privacy mode: it ignores
+   * both and sends only an SDK-minted app-scoped random UUID under the legacy wire
+   * field `deviceId`. Defaults to `context` for backwards compatibility.
+   */
+  identityMode?: 'context' | 'anonymous_installation';
+
   /** How often a non-empty queue is sent. Default 10s. */
   flushIntervalMs?: number;
 
@@ -95,9 +107,12 @@ const DEFAULT_MAX_QUEUE = 500;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_MAX_ATTEMPTS = 10;
 const DEFAULT_STORAGE_KEY = 'pulse.events.v1';
+const ANALYTICS_INSTALLATION_ID_SUFFIX = '.analytics-installation-id';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 let options: TrackOptions | null = null;
 let queue: QueuedEvent[] = [];
+let analyticsInstallationId = '';
 let timer: ReturnType<typeof setInterval> | null = null;
 let sending = false;
 let nextAttemptAt = 0;
@@ -116,6 +131,9 @@ export function configureTracking(opts: TrackOptions): void {
   disposeTracking();
   options = opts;
   queue = readQueue(opts);
+  analyticsInstallationId = opts.identityMode === 'anonymous_installation'
+    ? resolveAnalyticsInstallationId(opts)
+    : '';
   nextAttemptAt = 0;
   startTimer();
   lifecycleSubscription = opts.appState?.addEventListener('change', (state) => {
@@ -170,11 +188,12 @@ export async function flushEvents(): Promise<number> {
   const opts = options;
   const requestGeneration = trackingGeneration;
   const ctx = opts.getContext?.() ?? {};
+  const anonymousInstallation = opts.identityMode === 'anonymous_installation';
 
-  // Without a device id the server cannot put the event in an arm, and an empty id
-  // would pool every such install into one. Held rather than dropped: the id usually
-  // arrives a moment after boot.
-  if (!ctx.deviceId) return 0;
+  // The legacy/default mode intentionally preserves the original experiment-event
+  // contract. Anonymous campaign events opt into a separate identity explicitly.
+  if (!anonymousInstallation && !ctx.deviceId) return 0;
+  const requestDeviceId = anonymousInstallation ? analyticsInstallationId : ctx.deviceId;
 
   const batch = queue.slice(0, opts.maxBatch ?? DEFAULT_MAX_BATCH);
   queue = queue.slice(batch.length);
@@ -191,8 +210,10 @@ export async function flushEvents(): Promise<number> {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        deviceId: ctx.deviceId,
-        userId: ctx.userId,
+        deviceId: requestDeviceId,
+        // Anonymous mode deliberately omits the property rather than serializing an
+        // empty identifier. Context mode remains backwards compatible.
+        ...(anonymousInstallation ? {} : { userId: ctx.userId }),
         platform: ctx.platform,
         appVersion: ctx.appVersion,
         events: batch.map((e) => ({ id: e.id, event: e.event, time: e.time, props: e.props })),
@@ -257,6 +278,7 @@ export function stopTracking(): void {
   disposeTracking();
   options = null;
   queue = [];
+  analyticsInstallationId = '';
   sending = false;
   nextAttemptAt = 0;
 }
@@ -329,6 +351,31 @@ function storageKey(opts: TrackOptions): string {
   return opts.storageKey?.trim() || DEFAULT_STORAGE_KEY;
 }
 
+function analyticsInstallationIdStorageKey(opts: TrackOptions): string {
+  return `${storageKey(opts)}${ANALYTICS_INSTALLATION_ID_SUFFIX}`;
+}
+
+function resolveAnalyticsInstallationId(opts: TrackOptions): string {
+  if (opts.storage) {
+    try {
+      const stored = opts.storage.getString(analyticsInstallationIdStorageKey(opts))?.trim();
+      if (stored && UUID_PATTERN.test(stored)) return stored.toLowerCase();
+    } catch {
+      // A telemetry identifier can stay memory-only when storage is unavailable.
+    }
+  }
+
+  const generated = randomAnalyticsInstallationId();
+  if (opts.storage) {
+    try {
+      opts.storage.set(analyticsInstallationIdStorageKey(opts), generated);
+    } catch {
+      // A telemetry identifier can stay memory-only when storage is unavailable.
+    }
+  }
+  return generated;
+}
+
 function readQueue(opts: TrackOptions): QueuedEvent[] {
   if (!opts.storage) return [];
   try {
@@ -360,3 +407,19 @@ function randomEventId(): string {
   if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();
   return `evt-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
 }
+
+function randomAnalyticsInstallationId(): string {
+  const cryptoLike = globalThis.crypto as {
+    randomUUID?: () => string;
+    getRandomValues?: (values: Uint8Array) => Uint8Array;
+  } | undefined;
+  if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID().toLowerCase();
+
+  const bytes = new Uint8Array(16);
+  if (typeof cryptoLike?.getRandomValues === 'function') cryptoLike.getRandomValues(bytes);
+  else for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (value) => value.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}