@npaw/forge-react-native 9.7.1 → 9.7.3

package/plugin/mutations.js

@@ -0,0 +1,140 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Pure, idempotent host-project mutations applied by the Forge Expo config plugin; kept free of Expo imports so every one is unit-testable on its own.
+ */
+
+'use strict';
+
+const TAG_OPEN = '// @npaw/forge-react-native begin';
+const TAG_CLOSE = '// @npaw/forge-react-native end';
+
+const FORGE_MAVEN_URL = 'https://artifact.plugin.npaw.com/artifactory/plugins/android';
+const KOTLIN_METADATA_FLAG = '-Xskip-metadata-version-check';
+
+/**
+ * Replaces a previously inserted block, or inserts a new one after the line
+ * matching `anchor`.
+ *
+ * `expo prebuild` runs repeatedly and is expected to be idempotent, so every
+ * mutation is fenced by a tag pair: a second run rewrites the block between the
+ * fences instead of appending a duplicate. Without the fences a re-run would
+ * silently stack a second `maven { ... }` entry on every prebuild.
+ */
+function mergeBlock(contents, { name, block, anchor }) {
+  const open = `${TAG_OPEN} ${name}`;
+  const close = `${TAG_CLOSE} ${name}`;
+  const fenced = `${open}\n${block}\n${close}`;
+
+  const openIndex = contents.indexOf(open);
+  if (openIndex !== -1) {
+    const closeIndex = contents.indexOf(close, openIndex);
+    if (closeIndex === -1) {
+      throw new Error(`Forge config plugin: unterminated "${name}" block; remove it and re-run prebuild`);
+    }
+    return contents.slice(0, openIndex) + fenced + contents.slice(closeIndex + close.length);
+  }
+
+  const match = contents.match(anchor);
+  if (!match || match.index === undefined) return null;
+  const insertAt = match.index + match[0].length;
+  return `${contents.slice(0, insertAt)}\n${fenced}${contents.slice(insertAt)}`;
+}
+
+/**
+ * Adds the NPAW Artifactory repository to the project-level build.gradle.
+ *
+ * The packages declare this repository themselves, so it is only load-bearing
+ * when the host centralises resolution — but adding it is harmless when it is
+ * already reachable, and the failure it prevents (an unresolvable Forge AAR at
+ * the first build) is opaque enough to be worth pre-empting.
+ */
+function addForgeMavenRepository(contents) {
+  const block = [
+    'allprojects {',
+    '    repositories {',
+    `        maven { url '${FORGE_MAVEN_URL}' }`,
+    '    }',
+    '}',
+  ].join('\n');
+
+  if (contents.includes(FORGE_MAVEN_URL) && !contents.includes(TAG_OPEN)) {
+    // Someone added the repository by hand before adopting the plugin. Leave
+    // their edit alone rather than producing a second declaration.
+    return contents;
+  }
+
+  // Anchored after the buildscript block so the insert lands at top level,
+  // never inside `buildscript { repositories { ... } }` where it would only
+  // affect plugin resolution and not the app's dependencies.
+  const merged = mergeBlock(contents, {
+    name: 'maven',
+    block,
+    anchor: /^\}\s*$/m,
+  });
+  return merged === null ? `${contents.trimEnd()}\n\n${TAG_OPEN} maven\n${block}\n${TAG_CLOSE} maven\n` : merged;
+}
+
+/**
+ * Adds the Kotlin metadata compiler flag to the application module.
+ *
+ * The published Forge Android artifacts are built with a newer Kotlin than the
+ * React Native and Expo templates use — the template in this repo pins
+ * `kotlinVersion = "1.9.24"` — so an application module compiling its own
+ * Kotlin against Forge types needs this flag. Applications already on Kotlin
+ * 2.2 or newer do not, which is why callers can turn it off.
+ */
+function addKotlinMetadataFlag(contents) {
+  if (new RegExp(`freeCompilerArgs[^\\n]*${KOTLIN_METADATA_FLAG}`).test(contents)) {
+    return contents;
+  }
+
+  const block = [
+    '    kotlinOptions {',
+    `        freeCompilerArgs += ["${KOTLIN_METADATA_FLAG}"]`,
+    '    }',
+  ].join('\n');
+
+  const merged = mergeBlock(contents, {
+    name: 'kotlin',
+    block,
+    anchor: /^android\s*\{\s*$/m,
+  });
+  if (merged === null) {
+    throw new Error('Forge config plugin: no android { } block found in the app build.gradle');
+  }
+  return merged;
+}
+
+// Deliberately NOT automated here: turning bridgeless off.
+//
+// `react-native-video` v6 has no Fabric or bridgeless support, so applications
+// using the video adapter package must disable bridgeless — but the documented
+// mechanism is source-level, not a build setting: `load(bridgelessEnabled =
+// false)` in MainApplication and a `bridgelessEnabled` override returning NO in
+// AppDelegate. There is no gradle or Podfile property that does it.
+//
+// A mod writing some plausible-looking gradle property would be a silent no-op
+// that reads as success, which is worse than leaving the step manual. Rewriting
+// MainApplication and AppDelegate source is the alternative, and it breaks
+// across React Native versions in ways prebuild cannot verify. The client
+// documentation keeps this as a manual step until the v7 video adapter removes
+// the constraint entirely.
+
+module.exports = {
+  FORGE_MAVEN_URL,
+  KOTLIN_METADATA_FLAG,
+  TAG_OPEN,
+  TAG_CLOSE,
+  mergeBlock,
+  addForgeMavenRepository,
+  addKotlinMetadataFlag,
+};

package/src/NPAWForge.ts

@@ -14,7 +14,7 @@
 
 import NativeNPAWForge from './specs/NativeNPAWForge';
 import { ForgeVideo } from './ForgeVideo';
-import { subscribeInstanceEvents } from './events';
+import { subscribeInstanceEvents, subscribeInstanceLogs } from './events';
 import type {
   ForgeConfig,
   ForgeEventSubscription,
@@ -22,6 +22,7 @@ import type {
   ForgeOutcome,
   ForgeParams,
   ForgeRecordedEvent,
+  ForgeRenderedLog,
   ForgeVideoOptions,
 } from './types';
 
@@ -153,6 +154,16 @@ export class NPAWForge {
     return subscribeInstanceEvents(this.instanceId, callback);
   }
 
+  /**
+   * Live feed of the kernel's rendered decision log for this instance - the
+   * same lines `logLevel: 'trace'` writes to the platform console, without
+   * needing native tooling to read them. The kernel level gates what is
+   * rendered, so raise it (`setLogLevel('trace')`) before expecting detail.
+   */
+  onLog(callback: (log: ForgeRenderedLog) => void): ForgeEventSubscription {
+    return subscribeInstanceLogs(this.instanceId, callback);
+  }
+
   // ---- video ----
 
   /**

package/src/events.ts

@@ -14,9 +14,14 @@
 
 import { NativeEventEmitter, NativeModules } from 'react-native';
 import NativeNPAWForge from './specs/NativeNPAWForge';
-import type { ForgeEventSubscription, ForgeRecordedEvent } from './types';
+import type {
+  ForgeEventSubscription,
+  ForgeRecordedEvent,
+  ForgeRenderedLog,
+} from './types';
 
 export const FORGE_EVENT_CHANNEL = 'NPAWForgeEvent';
+export const FORGE_LOG_CHANNEL = 'NPAWForgeLog';
 
 const emitter = new NativeEventEmitter(
   // The spec module implements addListener/removeListeners; iOS needs the
@@ -38,3 +43,18 @@ export function subscribeInstanceEvents(
   );
   return { remove: () => subscription.remove() };
 }
+
+export function subscribeInstanceLogs(
+  instanceId: string,
+  callback: (log: ForgeRenderedLog) => void
+): ForgeEventSubscription {
+  const subscription = emitter.addListener(
+    FORGE_LOG_CHANNEL,
+    (log: ForgeRenderedLog) => {
+      if (log.instanceId === instanceId) {
+        callback(log);
+      }
+    }
+  );
+  return { remove: () => subscription.remove() };
+}

package/src/index.ts

@@ -15,22 +15,32 @@
 export { NPAWForge, DEFAULT_VIDEO_IDENTIFIER } from './NPAWForge';
 export { ForgeVideo } from './ForgeVideo';
 export { ForgeAdReporter } from './ForgeAdReporter';
-export { FORGE_EVENT_CHANNEL } from './events';
+export { FORGE_EVENT_CHANNEL, FORGE_LOG_CHANNEL } from './events';
 export {
   installErrorCapture,
   trackScreenView,
   createNavigationObserver,
 } from './capture';
 export type { ErrorCaptureOptions, ScreenViewOptions } from './capture';
+export { createSectionsCapture } from './sections';
+export type {
+  ForgeSectionContent,
+  ForgeSectionsCaptureHandle,
+  ForgeSectionsCaptureOptions,
+  ForgeViewabilityCallbackInfo,
+  ForgeViewToken,
+} from './sections';
 export type {
   ForgeConfig,
   ForgeEventSubscription,
+  ForgeLogLevelName,
   ForgeNetworkOutcome,
   ForgeNetworkRequestRecord,
   ForgeOutcome,
   ForgeOutcomeCode,
   ForgeParams,
   ForgeRecordedEvent,
+  ForgeRenderedLog,
   ForgeVideoOptions,
 } from './types';
 

package/src/sections.ts

@@ -0,0 +1,292 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: SECTIONS capture for React Native virtualized lists - turns FlatList/SectionList viewability callbacks into the same four raw section events Web and Roku emit, with matching thresholds and dedupe.
+ */
+
+import type { NPAWForge } from './NPAWForge';
+import type { ForgeParams } from './types';
+
+/**
+ * The shape React Native hands to `onViewableItemsChanged`.
+ *
+ * Declared structurally rather than imported from `react-native` so this module
+ * carries no dependency on the RN type surface and stays unit-testable without
+ * a renderer.
+ */
+export type ForgeViewToken = {
+  key?: string | null;
+  index?: number | null;
+  isViewable: boolean;
+  item?: unknown;
+};
+
+export type ForgeViewabilityCallbackInfo = {
+  viewableItems: ForgeViewToken[];
+  changed: ForgeViewToken[];
+};
+
+/** Facts the integrator supplies for a row. Everything is optional but `contentId`. */
+export type ForgeSectionContent = {
+  contentId?: string;
+  contentTitle?: string;
+  contentLink?: string;
+  /** Grid coordinates, when the list is not a simple single-axis rail. */
+  row?: number;
+  column?: number;
+};
+
+export type ForgeSectionsCaptureOptions = {
+  /** Logical section name — the rail's identity in reporting. */
+  section: string;
+  /** Zero-based order of this section within the screen. */
+  sectionOrder?: number;
+  /**
+   * Maps a list item to its reporting facts. Return `undefined` to skip an
+   * item entirely (placeholders, ad slots, loading skeletons).
+   */
+  resolveContent: (item: unknown, index: number) => ForgeSectionContent | undefined;
+  /**
+   * Percentage of a row that must be on screen to count as seen. Mirrors the
+   * Web threshold and RN's `itemVisiblePercentThreshold`. Default 50.
+   */
+  visibilityPercentThreshold?: number;
+  /**
+   * How long a row must stay visible before it is an impression. Mirrors RN's
+   * `minimumViewTime`. Default 1000 ms.
+   */
+  impressionMinVisibleMs?: number;
+  /** Minimum visible time that counts as dwell. Default 1000 ms. */
+  dwellMs?: number;
+  /** Upper bound on tracked rows, mirroring the Web cap. Default 200. */
+  maxTrackedItems?: number;
+  /**
+   * Local half of the capture gate. The kernel is the authority — it drops all
+   * four section kinds when the SECTIONS plan bit is off — but returning false
+   * here also spares the bridge the traffic. Default: always on.
+   */
+  enabled?: () => boolean;
+  /** Injectable clock, for tests. */
+  now?: () => number;
+};
+
+export type ForgeSectionsCaptureHandle = {
+  /** Pass straight to `FlatList.onViewableItemsChanged`. */
+  onViewableItemsChanged: (info: ForgeViewabilityCallbackInfo) => void;
+  /** Pass straight to `FlatList.viewabilityConfig`. */
+  viewabilityConfig: {
+    itemVisiblePercentThreshold: number;
+    minimumViewTime: number;
+  };
+  /** Call from a row's `onPress`. */
+  trackClick: (item: unknown, index: number) => void;
+  /**
+   * Clears dedupe state so the same rows can report again. Call on navigation,
+   * matching how the Web implementation resets per route.
+   */
+  reset: () => void;
+  /** Emits a closing `raw_section_hidden` if the section is visible, and stops. */
+  dispose: () => void;
+};
+
+// Kernel-mirrored defaults, identical to bindings/web/src/sections-capture.ts.
+const DEFAULT_VISIBILITY_THRESHOLD_PCT = 50;
+const DEFAULT_IMPRESSION_MIN_VISIBLE_MS = 1000;
+const DEFAULT_DWELL_MS = 1000;
+const DEFAULT_MAX_TRACKED_ITEMS = 200;
+
+type TrackedRow = {
+  key: string;
+  index: number;
+  content: ForgeSectionContent;
+  visibleSince: number;
+};
+
+function tokenKey(token: ForgeViewToken, index: number): string {
+  return token.key ?? `index:${index}`;
+}
+
+/**
+ * Creates a sections capture handle for one list.
+ *
+ * React Native's virtualized lists are JavaScript-owned: rows are recycled and
+ * unmounted as they scroll, so the native Android and Apple sections observers
+ * see nothing usable. The viewability callback is the only reliable signal, and
+ * it already carries the two knobs the Web implementation derives from
+ * IntersectionObserver — a visibility percentage and a minimum view time — so
+ * the semantics map across rather than being re-invented.
+ *
+ * ```tsx
+ * const sections = createSectionsCapture(forge, {
+ *   section: 'Continue watching',
+ *   resolveContent: (item) => ({ contentId: item.id, contentTitle: item.title }),
+ * });
+ *
+ * <FlatList
+ *   data={rows}
+ *   onViewableItemsChanged={sections.onViewableItemsChanged}
+ *   viewabilityConfig={sections.viewabilityConfig}
+ *   renderItem={({ item, index }) => (
+ *     <Row onPress={() => sections.trackClick(item, index)} />
+ *   )}
+ * />
+ * ```
+ *
+ * One handle per list. Call `dispose` when the screen unmounts so the section's
+ * `raw_section_hidden` pairs with the `raw_section_visible` it emitted.
+ */
+export function createSectionsCapture(
+  forge: NPAWForge,
+  options: ForgeSectionsCaptureOptions,
+): ForgeSectionsCaptureHandle {
+  const visibilityPercentThreshold =
+    options.visibilityPercentThreshold ?? DEFAULT_VISIBILITY_THRESHOLD_PCT;
+  const impressionMinVisibleMs =
+    options.impressionMinVisibleMs ?? DEFAULT_IMPRESSION_MIN_VISIBLE_MS;
+  const dwellMs = options.dwellMs ?? DEFAULT_DWELL_MS;
+  const maxTrackedItems = options.maxTrackedItems ?? DEFAULT_MAX_TRACKED_ITEMS;
+  const now = options.now ?? (() => Date.now());
+  const isEnabled = options.enabled ?? (() => true);
+
+  const tracked = new Map<string, TrackedRow>();
+  const impressionsSeen = new Set<string>();
+  const dwellSeen = new Set<string>();
+  let sectionVisible = false;
+  let disposed = false;
+
+  function emit(name: string, params: ForgeParams): void {
+    // Fire-and-forget: a rejected raw event must never surface inside a list
+    // render or a scroll handler.
+    void forge.trackRawEvent(name, params).catch(() => undefined);
+  }
+
+  function sectionParams(): ForgeParams {
+    const params: ForgeParams = { section: options.section };
+    if (options.sectionOrder !== undefined) params.sectionOrder = options.sectionOrder;
+    return params;
+  }
+
+  function dedupeKey(row: TrackedRow): string {
+    return row.content.contentId ?? `${options.section}#${row.key}`;
+  }
+
+  function contentParams(row: TrackedRow): ForgeParams {
+    const params: ForgeParams = { ...sectionParams(), position: row.index };
+    const { contentId, contentTitle, contentLink, row: gridRow, column } = row.content;
+    if (contentId !== undefined) params.contentId = contentId;
+    if (contentTitle !== undefined) params.contentTitle = contentTitle;
+    if (contentLink !== undefined) params.contentLink = contentLink;
+    if (gridRow !== undefined) params.row = gridRow;
+    if (column !== undefined) params.column = column;
+    return params;
+  }
+
+  function openSection(visibleCount: number): void {
+    if (sectionVisible) return;
+    sectionVisible = true;
+    emit('raw_section_visible', {
+      ...sectionParams(),
+      visibilityPct: visibilityPercentThreshold,
+      itemCount: visibleCount,
+    });
+  }
+
+  function closeSection(): void {
+    if (!sectionVisible) return;
+    sectionVisible = false;
+    emit('raw_section_hidden', sectionParams());
+  }
+
+  function rowBecameVisible(token: ForgeViewToken, fallbackIndex: number): void {
+    const index = token.index ?? fallbackIndex;
+    const key = tokenKey(token, index);
+    if (tracked.has(key)) return;
+    if (tracked.size >= maxTrackedItems) return;
+
+    const content = options.resolveContent(token.item, index);
+    if (!content) return;
+
+    tracked.set(key, { key, index, content, visibleSince: now() });
+  }
+
+  function rowBecameHidden(token: ForgeViewToken, fallbackIndex: number): void {
+    const index = token.index ?? fallbackIndex;
+    const key = tokenKey(token, index);
+    const row = tracked.get(key);
+    if (!row) return;
+    tracked.delete(key);
+
+    const elapsed = now() - row.visibleSince;
+    const key_ = dedupeKey(row);
+
+    // Impression first: a row that met the minimum view time was seen, whether
+    // or not it also earned a dwell.
+    if (elapsed >= impressionMinVisibleMs && !impressionsSeen.has(key_)) {
+      impressionsSeen.add(key_);
+      emit('raw_content_impression', {
+        ...contentParams(row),
+        visibilityPct: visibilityPercentThreshold,
+      });
+    }
+
+    if (elapsed >= dwellMs && !dwellSeen.has(key_)) {
+      dwellSeen.add(key_);
+      emit('raw_content_dwell', { ...contentParams(row), dwellMs: Math.round(elapsed) });
+    }
+  }
+
+  return {
+    viewabilityConfig: {
+      itemVisiblePercentThreshold: visibilityPercentThreshold,
+      minimumViewTime: impressionMinVisibleMs,
+    },
+
+    onViewableItemsChanged(info) {
+      if (disposed || !isEnabled()) return;
+
+      for (const [position, token] of (info.changed ?? []).entries()) {
+        if (token.isViewable) rowBecameVisible(token, position);
+        else rowBecameHidden(token, position);
+      }
+
+      const visible = (info.viewableItems ?? []).length;
+      if (visible > 0) openSection(visible);
+      else closeSection();
+    },
+
+    trackClick(item, index) {
+      if (disposed || !isEnabled()) return;
+      const content = options.resolveContent(item, index);
+      if (!content) return;
+      emit('raw_click', {
+        ...contentParams({ key: `index:${index}`, index, content, visibleSince: now() }),
+      });
+    },
+
+    reset() {
+      // Flush what is on screen before forgetting it, so a navigation away does
+      // not silently drop rows that had already earned an impression.
+      for (const row of [...tracked.values()]) {
+        rowBecameHidden({ key: row.key, index: row.index, isViewable: false }, row.index);
+      }
+      tracked.clear();
+      impressionsSeen.clear();
+      dwellSeen.clear();
+      closeSection();
+    },
+
+    dispose() {
+      if (disposed) return;
+      this.reset();
+      disposed = true;
+    },
+  };
+}

package/src/types.ts

@@ -33,6 +33,27 @@ export type ForgeOutcome = {
   details?: Record<string, string>;
 };
 
+/** Log levels the kernel renders lines at, as they travel on the wire. */
+export type ForgeLogLevelName =
+  | 'off'
+  | 'error'
+  | 'warning'
+  | 'info'
+  | 'debug'
+  | 'trace';
+
+/**
+ * One line of the kernel's rendered decision log - the same text
+ * `logLevel: 'trace'` writes to the platform console. Already rendered and
+ * redacted natively; `tag` is the kernel's own scope tag.
+ */
+export type ForgeRenderedLog = {
+  instanceId: string;
+  level: ForgeLogLevelName;
+  tag: string;
+  message: string;
+};
+
 /** One kernel-recorded event from the bounded native snapshot mirror. */
 export type ForgeRecordedEvent = {
   instanceId: string;
@@ -48,8 +69,8 @@ export type ForgeRecordedEvent = {
  * aliases are intentionally not exposed); unknown keys are warn-and-ignore
  * on the native side for forward compatibility.
  *
- * iOS note: deviceUuid and autoDeviceIdentityEnabled are Android-only today
- * (the Swift Builder lacks the setters); iOS logs and ignores them.
+ * Every key applies on both platforms, including `deviceUuid` and
+ * `autoDeviceIdentityEnabled`, which iOS ignored before Forge 9.7.2.
  */
 export type ForgeConfig = {
   appName?: string;