@npaw/forge-react-native 9.6.1

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (C) NPAW - All Rights Reserved
+
+This software is protected under international copyright law. All rights
+reserved and protected by the copyright holders. This software is confidential
+and only available to authorized individuals with the permission of the
+copyright holders. If you obtained this software and do not have permission,
+please contact the copyright holders and delete it.
+
+Use of this software requires an active NPAW commercial agreement. See
+https://npaw.com for licensing and support.

package/NPAWForgeReactNative.podspec

@@ -0,0 +1,44 @@
+# 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: CocoaPods spec for the @npaw/forge-react-native core TurboModule over the Forge Apple SDK.
+
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NPAWForgeReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://npaw.com"
+  s.license      = { :type => "Commercial", :text => "Copyright (C) NPAW - All Rights Reserved" }
+  s.authors      = { "Victor Soto" => "victor.soto@nicepeopleatwork.com" }
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :path => "." }
+
+  s.source_files  = "ios/**/*.{h,m,mm,swift}"
+  s.swift_version = "5.9"
+
+  # FORGE_APPLE_CONSUMPTION BEGIN (staged: hydrated self-contained variant)
+  s.vendored_frameworks = "ios/ForgeApple/ForgeKernelFFI.xcframework"
+  s.preserve_paths = "ios/ForgeApple/**"
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    "OTHER_SWIFT_FLAGS" => "$(inherited) -DFORGE_HAS_UNIFFI -DFORGE_RN_HYDRATED",
+  }
+  # FORGE_APPLE_CONSUMPTION END
+
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
+end

package/README.md

@@ -0,0 +1,51 @@
+# @npaw/forge-react-native
+
+NPAW Forge analytics for React Native: application sessions, user identity,
+video and ad analytics, capture, and network observation, powered by the shared
+Forge analytics core through the native Android and Apple SDKs.
+
+Use of this package requires an active NPAW commercial agreement. See
+[LICENSE](./LICENSE).
+
+## Install
+
+```sh
+npm install @npaw/forge-react-native
+```
+
+Requires React Native 0.75+ with the New Architecture enabled (TurboModules).
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+### Android
+
+No extra steps: the module resolves the published Forge Android coordinates.
+
+## Usage
+
+```js
+import { NPAWForge } from '@npaw/forge-react-native';
+
+const forge = await NPAWForge.create({
+  accountCode: '<account-code>',
+  appName: 'My App',
+  appReleaseVersion: '1.0.0',
+});
+
+await forge.startSession({ screen: 'Home' });
+```
+
+## Player adapters
+
+This package reports application sessions and manual video/ad events. For
+automatic playback reporting with `react-native-video`, add
+[`@npaw/forge-react-native-video`](https://www.npmjs.com/package/@npaw/forge-react-native-video).
+
+## Documentation
+
+Integration guides and the API reference are published at
+[npaw.com](https://npaw.com).

package/android/build.gradle

@@ -0,0 +1,77 @@
+// 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: Android library build for the @npaw/forge-react-native TurboModule wrapping the published Forge Android SDK. Pure-Java module so the Kotlin-2.3-built Forge AAR imposes no Kotlin floor on host apps.
+
+def isNewArchitectureEnabled() {
+    return project.hasProperty('newArchEnabled') && project.newArchEnabled == 'true'
+}
+
+apply plugin: 'com.android.library'
+if (isNewArchitectureEnabled()) {
+    apply plugin: 'com.facebook.react'
+}
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+// Committed default stays 0.0.0; release staging rewrites it and the dev loop
+// injects the locally published version via NpawForge_forgeCoreVersion or
+// FORGE_CORE_VERSION (see scripts/react-native/hydrate-natives.sh).
+def forgeCoreVersion = project.hasProperty('NpawForge_forgeCoreVersion')
+    ? project.property('NpawForge_forgeCoreVersion')
+    : (System.getenv('FORGE_CORE_VERSION') ?: '9.6.1')
+
+android {
+    namespace 'com.npaw.forge.reactnative'
+    compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 23)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    testOptions {
+        // android.util.Log in JVM unit tests (warn-and-ignore config paths).
+        unitTests.returnDefaultValues = true
+    }
+}
+
+repositories {
+    mavenCentral()
+    google()
+    def localMavenRepo = System.getenv('FORGE_LOCAL_MAVEN_REPO')
+    if (localMavenRepo != null && !localMavenRepo.isEmpty()) {
+        maven { url uri(localMavenRepo) }
+    }
+    maven { url 'https://artifact.plugin.npaw.com/artifactory/plugins/android' }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-native:+'
+    // compileOnly + runtimeOnly split: this module's javac compiles against
+    // the Forge classes (javac ignores Kotlin metadata), while nothing from
+    // the Kotlin-2.3-built Forge graph — including its kotlin-stdlib —
+    // reaches the host app's Kotlin COMPILE classpath. The full graph still
+    // flows to every runtime classpath, where newer stdlib is binary-safe.
+    compileOnly "com.npaw.forge:forge-android-core:${forgeCoreVersion}"
+    runtimeOnly "com.npaw.forge:forge-android-core:${forgeCoreVersion}"
+    compileOnly "com.npaw.forge:forge-android-network-capture:${forgeCoreVersion}"
+    runtimeOnly "com.npaw.forge:forge-android-network-capture:${forgeCoreVersion}"
+
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation "com.npaw.forge:forge-android-core:${forgeCoreVersion}"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  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: Manifest stub for the @npaw/forge-react-native Android library module.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/npaw/forge/reactnative/ForgeDtoMapper.java

@@ -0,0 +1,295 @@
+/**
+ * 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: DTO conversions between React Native bridge maps and the Forge Android facade types (configs, params, outcomes, recorded events, network records).
+ */
+
+package com.npaw.forge.reactnative;
+
+import androidx.annotation.Nullable;
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.ReadableMap;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+import com.npaw.forge.android.NPAWForge;
+import com.npaw.forge.android.core.ForgeOutcome;
+import com.npaw.forge.android.core.ForgeRecordedEvent;
+import com.npaw.forge.android.network.NetworkRequestOutcome;
+import com.npaw.forge.android.network.NetworkRequestRecord;
+import com.npaw.forge.android.network.NetworkRequestSource;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+public final class ForgeDtoMapper {
+
+  private ForgeDtoMapper() {}
+
+  // ---- inputs ----
+
+  public static Map<String, Object> toObjectMap(@Nullable ReadableMap map) {
+    if (map == null) {
+      return Collections.emptyMap();
+    }
+    return new HashMap<>(map.toHashMap());
+  }
+
+  /** Stringifies every value; the Forge params surfaces are string maps. */
+  public static HashMap<String, String> toStringMap(@Nullable ReadableMap map) {
+    HashMap<String, String> result = new HashMap<>();
+    if (map == null) {
+      return result;
+    }
+    for (Map.Entry<String, Object> entry : map.toHashMap().entrySet()) {
+      Object value = entry.getValue();
+      if (value == null) {
+        continue;
+      }
+      if (value instanceof Double) {
+        double d = (Double) value;
+        if (d == Math.rint(d) && !Double.isInfinite(d) && Math.abs(d) < 9.007199254740992E15) {
+          long asLong = (long) d;
+          result.put(entry.getKey(), String.valueOf(asLong));
+          continue;
+        }
+      }
+      if (value instanceof Boolean) {
+        result.put(entry.getKey(), ((Boolean) value) ? "true" : "false");
+        continue;
+      }
+      result.put(entry.getKey(), String.valueOf(value));
+    }
+    return result;
+  }
+
+  public static HashMap<String, Double> toDoubleMap(@Nullable ReadableMap map) {
+    HashMap<String, Double> result = new HashMap<>();
+    if (map == null) {
+      return result;
+    }
+    for (Map.Entry<String, Object> entry : map.toHashMap().entrySet()) {
+      Object value = entry.getValue();
+      if (value instanceof Number) {
+        result.put(entry.getKey(), ((Number) value).doubleValue());
+      }
+    }
+    return result;
+  }
+
+  @Nullable
+  public static String emptyToNull(@Nullable String value) {
+    return value == null || value.isEmpty() ? null : value;
+  }
+
+  public static void applyConfig(NPAWForge.Builder builder, @Nullable ReadableMap config) {
+    if (config == null) {
+      return;
+    }
+    for (Map.Entry<String, Object> entry : config.toHashMap().entrySet()) {
+      String key = entry.getKey();
+      Object value = entry.getValue();
+      if (value == null) {
+        continue;
+      }
+      switch (key) {
+        case "appName":
+          builder.setAppName(String.valueOf(value));
+          break;
+        case "appReleaseVersion":
+          builder.setAppReleaseVersion(String.valueOf(value));
+          break;
+        case "buildVariant":
+          builder.setBuildVariant(String.valueOf(value));
+          break;
+        case "lmaEndpoint":
+          builder.setLmaEndpoint(String.valueOf(value));
+          break;
+        case "analyticsUserAgent":
+          builder.setAnalyticsUserAgent(String.valueOf(value));
+          break;
+        case "logLevel":
+          builder.setLogLevel(value);
+          break;
+        case "startSessionOnInitialize":
+          builder.setStartSessionOnInitialize(asBoolean(value));
+          break;
+        case "processEventsBeforeSessionStart":
+          builder.setProcessEventsBeforeSessionStart(asBoolean(value));
+          break;
+        case "preSessionEventQueueLimitEvents":
+          builder.setPreSessionEventQueueLimitEvents((int) asLong(value));
+          break;
+        case "preSessionEventQueueMaxAgeMs":
+          builder.setPreSessionEventQueueMaxAgeMs(asLong(value));
+          break;
+        case "allowLocalHttpForTesting":
+          builder.setLocalPlaintextTransportForTesting(asBoolean(value));
+          break;
+        case "deviceUuid":
+          builder.setDeviceUuid(String.valueOf(value));
+          break;
+        case "autoDeviceIdentityEnabled":
+          builder.setAutoDeviceIdentityEnabled(asBoolean(value));
+          break;
+        default:
+          android.util.Log.w(
+              "NPAWForgeRN", "Unknown ForgeConfig key '" + key + "' ignored (forward compatibility)");
+          break;
+      }
+    }
+  }
+
+  public static NetworkRequestRecord toNetworkRequestRecord(ReadableMap record) {
+    Map<String, Object> map = record.toHashMap();
+    String targetUrl = stringOr(map, "targetUrl", "");
+    String method = stringOr(map, "method", "GET");
+    int responseStatusCode = (int) longOr(map, "responseStatusCode", 0L);
+    long durationMs = longOr(map, "durationMs", 0L);
+    NetworkRequestOutcome outcome = parseOutcome(stringOr(map, "outcome", "unknown"));
+    return new NetworkRequestRecord(
+        targetUrl,
+        method,
+        responseStatusCode,
+        durationMs,
+        outcome,
+        0L,
+        UUID.randomUUID().toString(),
+        NetworkRequestSource.Manual,
+        null,
+        null,
+        nullableString(map, "responseStatusText"),
+        nullableString(map, "errorMessage"),
+        nullableString(map, "traceparent"),
+        nullableLong(map, "dnsDurationMs"),
+        nullableLong(map, "connectDurationMs"),
+        nullableLong(map, "sslDurationMs"),
+        nullableLong(map, "requestDurationMs"),
+        nullableLong(map, "timeToFirstByteMs"),
+        nullableLong(map, "responseDownloadDurationMs"),
+        nullableLong(map, "redirectDurationMs"),
+        nullableInt(map, "redirectCount"),
+        nullableString(map, "protocol"),
+        nullableLong(map, "requestBytes"),
+        nullableLong(map, "responseBytes"),
+        Collections.emptyMap(),
+        Collections.emptyMap());
+  }
+
+  // ---- outputs ----
+
+  public static WritableMap outcomeToMap(ForgeOutcome outcome) {
+    WritableMap result = Arguments.createMap();
+    result.putString("code", outcome.getCode());
+    result.putBoolean("isAccepted", outcome.isAccepted());
+    if (outcome instanceof ForgeOutcome.FailedWithDiagnostic) {
+      ForgeOutcome.FailedWithDiagnostic failed = (ForgeOutcome.FailedWithDiagnostic) outcome;
+      result.putString("reason", failed.getReason());
+      WritableMap details = Arguments.createMap();
+      for (Map.Entry<String, String> entry : failed.getDetails().entrySet()) {
+        details.putString(entry.getKey(), entry.getValue());
+      }
+      result.putMap("details", details);
+    }
+    return result;
+  }
+
+  public static WritableMap recordedEventToMap(String instanceId, ForgeRecordedEvent event) {
+    WritableMap result = Arguments.createMap();
+    result.putString("instanceId", instanceId);
+    result.putString("eventName", event.getEventName());
+    result.putDouble("timestampMs", (double) event.getTimestampMs());
+    WritableMap payload = Arguments.createMap();
+    for (Map.Entry<String, String> entry : event.getPayload().entrySet()) {
+      payload.putString(entry.getKey(), entry.getValue());
+    }
+    result.putMap("payload", payload);
+    result.putBoolean("urgent", event.getUrgent());
+    if (event.getViewKey() != null) {
+      result.putString("viewKey", event.getViewKey());
+    }
+    return result;
+  }
+
+  public static WritableMap snapshotToMap(String instanceId, List<ForgeRecordedEvent> events) {
+    WritableArray items = Arguments.createArray();
+    for (ForgeRecordedEvent event : events) {
+      items.pushMap(recordedEventToMap(instanceId, event));
+    }
+    WritableMap result = Arguments.createMap();
+    result.putArray("items", items);
+    return result;
+  }
+
+  // ---- helpers ----
+
+  private static boolean asBoolean(Object value) {
+    if (value instanceof Boolean) {
+      return (Boolean) value;
+    }
+    return Boolean.parseBoolean(String.valueOf(value));
+  }
+
+  private static long asLong(Object value) {
+    if (value instanceof Number) {
+      return ((Number) value).longValue();
+    }
+    return Long.parseLong(String.valueOf(value));
+  }
+
+  private static String stringOr(Map<String, Object> map, String key, String fallback) {
+    Object value = map.get(key);
+    return value == null ? fallback : String.valueOf(value);
+  }
+
+  private static long longOr(Map<String, Object> map, String key, long fallback) {
+    Object value = map.get(key);
+    return value instanceof Number ? ((Number) value).longValue() : fallback;
+  }
+
+  @Nullable
+  private static String nullableString(Map<String, Object> map, String key) {
+    Object value = map.get(key);
+    return value == null ? null : String.valueOf(value);
+  }
+
+  @Nullable
+  private static Long nullableLong(Map<String, Object> map, String key) {
+    Object value = map.get(key);
+    return value instanceof Number ? ((Number) value).longValue() : null;
+  }
+
+  @Nullable
+  private static Integer nullableInt(Map<String, Object> map, String key) {
+    Object value = map.get(key);
+    return value instanceof Number ? ((Number) value).intValue() : null;
+  }
+
+  private static NetworkRequestOutcome parseOutcome(String wireName) {
+    switch (wireName) {
+      case "success":
+        return NetworkRequestOutcome.Success;
+      case "http_error":
+        return NetworkRequestOutcome.HttpError;
+      case "network_error":
+        return NetworkRequestOutcome.NetworkError;
+      case "cancelled":
+        return NetworkRequestOutcome.Cancelled;
+      case "timeout":
+        return NetworkRequestOutcome.Timeout;
+      case "blocked":
+        return NetworkRequestOutcome.Blocked;
+      default:
+        return NetworkRequestOutcome.Unknown;
+    }
+  }
+}

package/android/src/main/java/com/npaw/forge/reactnative/ForgeInstanceRegistry.java

@@ -0,0 +1,61 @@
+/**
+ * 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: Process-wide registry mapping React Native instance ids to live NPAWForge facades; the compile-time seam the video package uses to reach core instances. Written in Java so the module compiles under any host-app Kotlin version despite the Kotlin-2.3-built Forge AAR.
+ */
+
+package com.npaw.forge.reactnative;
+
+import com.npaw.forge.android.NPAWForge;
+import com.npaw.forge.android.video.VideoAdapter;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import androidx.annotation.Nullable;
+
+public final class ForgeInstanceRegistry {
+
+  private static final ConcurrentHashMap<String, NPAWForge> INSTANCES = new ConcurrentHashMap<>();
+
+  private ForgeInstanceRegistry() {}
+
+  public static void register(String instanceId, NPAWForge forge) {
+    INSTANCES.put(instanceId, forge);
+  }
+
+  @Nullable
+  public static NPAWForge remove(String instanceId) {
+    return INSTANCES.remove(instanceId);
+  }
+
+  @Nullable
+  public static NPAWForge resolve(String instanceId) {
+    return INSTANCES.get(instanceId);
+  }
+
+  @Nullable
+  public static VideoAdapter resolveVideoAdapter(String instanceId, @Nullable String identifier) {
+    NPAWForge forge = INSTANCES.get(instanceId);
+    return forge == null ? null : forge.getVideoAdapter(identifier);
+  }
+
+  public static Map<String, NPAWForge> snapshot() {
+    return new HashMap<>(INSTANCES);
+  }
+
+  public static List<NPAWForge> clear() {
+    List<NPAWForge> live = new ArrayList<>(INSTANCES.values());
+    INSTANCES.clear();
+    return live;
+  }
+}